contribute-catalog

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

Contribute to HyperFrames Registry

Guide the user from idea to merged PR for a new registry block or component.

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 hyperframes:block) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
• Component (registry/components/, type hyperframes: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:

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

registry-item.json for blocks:

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{block-name}",
  "type": "hyperframes: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": "hyperframes:composition"
    }
  ]
}

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

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

Step 3: Build

Apply the correct template based on type. See 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.__hyperframes.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

hyperframes lint                    # 0 errors required
hyperframes validate --no-contrast  # 0 console errors required

Step 5: Preview

# Render preview video
hyperframes render -o preview.mp4

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

# Publish to hyperframes.dev for review
npx hyperframes 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:

• HeyGen 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.

# 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": "hyperframes:block" }  (or "hyperframes:component")

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

# 5. Publish to hyperframes.dev so reviewers can preview
npx hyperframes 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 hyperframes.dev link
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.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

• hyperframes lint → 0 errors
• hyperframes 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 hyperframes publish run (claim your project URL)
• Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
• All IDs unique and prefixed