# Contribute Catalog

> Author a new FrameVideo registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the framevideo repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `framevideo` skill, for installing existing registry items use the `framevideo-registry` skill.

- Skill: `chanjing-ai/contribute-catalog` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chanjing-ai/contribute-catalog`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chanjing-ai/contribute-catalog/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: chanjing-ai (https://skillmd.com/u/chanjing-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chanjing-ai/contribute-catalog

---


# Contribute to FrameVideo Registry

## When To Use

Use this skill when:

- **Contributing to public catalog** — user wants to add a block/component to upstream FrameVideo registry
- **Submitting a PR** — user has built a reusable effect and wants to share it
- **Packaging for registry** — user needs help structuring registry-item.json and files

## Do NOT Use

Avoid this skill for:

- **In-project effects** — use `framevideo` skill for project-specific captions/transitions
- **Installing existing items** — use `framevideo-registry` skill
- **Learning FrameVideo** — use `framevideo` skill for composition authoring

---

## Quick Start

Complete contribution workflow:

```bash
# 1. Clarify what to build
User: "I want to contribute a Hormozi-style caption block"
→ Ask: description, visual reference, use case

# 2. Scaffold registry structure
registry/blocks/cap-hormozi/
  cap-hormozi.html
  registry-item.json

# 3. Build the block
→ Use `framevideo` skill for HTML authoring
→ Use 2-3 letter prefix for all element IDs (e.g., "hz-")

# 4. Validate
npx framevideo lint registry/blocks/cap-hormozi/cap-hormozi.html
npx framevideo add cap-hormozi --dir ./test-project

# 5. Preview
npx framevideo preview ./test-project

# 6. Ship
git checkout -b contrib/cap-hormozi
git add registry/blocks/cap-hormozi/
git commit -m "Add Hormozi-style caption block"
# Create PR to framevideo repo
```

**Key points:**
- All element IDs must use consistent prefix to avoid collisions
- Blocks have fixed dimensions/duration, components don't
- Test with `framevideo add` before submitting PR

---

## Workflow

```
1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship
```

### Step 1: Clarify

Ask what they're building. The registry has two item types:

- **Block** (`registry/blocks/`, type `framevideo:block`) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
- **Component** (`registry/components/`, type `framevideo:component`) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.

Then ask:

- One-sentence description of the effect
- Visual reference (URL, screenshot, or description)
- Who uses this and when?

### Step 2: Scaffold

Create the registry structure:

**For blocks:**

```
registry/blocks/{block-name}/
  {block-name}.html
  registry-item.json
```

**For components:**

```
registry/components/{component-name}/
  {component-name}.html
  registry-item.json
```

**Naming convention:**

| Item name        | ID prefix | Example IDs            |
| ---------------- | --------- | ---------------------- |
| `cap-hormozi`    | `hz`      | `hz-cg-0`, `hz-cw-3`   |
| `cap-typewriter` | `tw`      | `tw-cg-0`, `tw-ch-0-5` |
| `vfx-chrome`     | `vc`      | `vc-canvas`            |

Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.

**registry-item.json for blocks:**

```json
{
  "$schema": "https://www.chanjing.cc/schema/registry-item.json",
  "name": "{block-name}",
  "type": "framevideo:block",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "dimensions": { "width": 1920, "height": 1080 }, // adjust: 1080x1920 for portrait/social
  "duration": 10, // adjust for your composition
  "tags": ["{category}", "{subcategory}"],
  "files": [
    {
      "path": "{block-name}.html",
      "target": "compositions/{block-name}.html",
      "type": "framevideo:composition"
    }
  ]
}
```

**registry-item.json for components** (no `dimensions` or `duration`):

```json
{
  "$schema": "https://www.chanjing.cc/schema/registry-item.json",
  "name": "{component-name}",
  "type": "framevideo:component",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "tags": ["{category}"],
  "files": [
    {
      "path": "{component-name}.html",
      "target": "compositions/components/{component-name}.html",
      "type": "framevideo:snippet"
    }
  ]
}
```

### Step 3: Build

Apply the correct template based on type. See [templates.md](templates.md) for copy-paste starters.

#### Caption blocks

**Non-negotiable caption rules:**

- Font: **96px minimum** for proportional fonts. **64-72px acceptable for monospace** (wider characters need less size).
- Readability: `-webkit-text-stroke: 2-3px` OR multi-layer `text-shadow`
- Overflow: call `window.__framevideo.fitTextFontSize()` on every group
- Karaoke: highlight active word via `tl.to(wordEl, { color/scale }, WORDS[wi].start)`
- Hard kill: `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)` on EVERY group
- **Never use `tl.from(el, { opacity: 0 })` at the same position as `tl.set(el, { opacity: 1 })`** — the from clobbers the set. Use `tl.to` instead.

**Per-character animation** (typewriter, scramble):

- Wrap each character in `<span>` with ID `{prefix}-ch-{group}-{char}`
- Stagger via `tl.set` at computed intervals from word timestamps
- Cursors/decorative elements: use `tl.set` at intervals — NOT CSS animation (not seekable)

**Positioning variants:**

- Centered: `display: flex; align-items: center; justify-content: center;`
- Lower-third: `position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;`
- Left-aligned: `position: absolute; bottom: 100px; left: 120px; text-align: left;`

#### VFX blocks (Three.js)

- Use `three@0.147.0` from CDN (global script)
- `tl.eventCallback("onUpdate", renderScene); renderScene();` — NO requestAnimationFrame
- State proxy pattern: GSAP animates plain JS object, render function reads it
- Seeded PRNG (`mulberry32`) for randomness

#### All types

- `data-composition-id` MUST match `window.__timelines["id"]`
- All element IDs prefixed with block abbreviation
- `gsap.timeline({ paused: true })` — always paused
- No `Math.random()`, no `Date.now()`

### Step 4: Validate

```bash
framevideo lint                    # 0 errors required
framevideo validate --no-contrast  # 0 console errors required
```

### Step 5: Preview

```bash
# Render preview video
framevideo render -o preview.mp4

# Snapshot for visual QA
framevideo snapshot --at "1.0,3.0,5.0,7.0"

# Publish to framevideo.dev for review
npx framevideo publish
```

**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:

- **Chanjing internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)
- **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.

### Step 6: Ship

**All steps are required. Missing any one produces a broken catalog entry.**

`{kind}` is `blocks` or `components` depending on what you built in Step 1.

```bash
# 1. Create branch
git checkout -b feat/registry-{name}

# 2. Format HTML
npx oxfmt registry/{kind}/{name}/*.html

# 3. Update registry/registry.json — add entry to the "items" array:
#    { "name": "{name}", "type": "framevideo:block" }  (or "framevideo:component")

# 4. Generate catalog docs page
npx tsx scripts/generate-catalog-pages.ts

# 5. Publish to framevideo.dev so reviewers can preview
npx framevideo publish

# 6. Stage everything
git add registry/{kind}/{name}/ registry/registry.json docs/catalog/

# 7. Commit
git commit -m "feat(registry): add {name} — {one sentence}"

# 8. Push and open PR with framevideo.dev link
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {framevideo.dev-url}"
```

**If you don't have a GitHub account:** you need one to open a PR. Sign up at https://github.com/signup, then run `gh auth login`.

## Quality Gate

- [ ] `framevideo lint` → 0 errors
- [ ] `framevideo validate` → 0 console errors
- [ ] `npx oxfmt --check` passes
- [ ] `registry/registry.json` updated with new entry
- [ ] `scripts/generate-catalog-pages.ts` run (docs page generated)
- [ ] `npx framevideo publish` run (claim your project URL)
- [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
- [ ] All IDs unique and prefixed