Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

contribute-catalog

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.

boraoztunc · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add boraoztunc/skills --skill contribute-catalog

About this skill


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:

Item nameID prefixExample IDs
cap-hormozihzhz-cg-0, hz-cw-3
cap-typewritertwtw-cg-0, tw-ch-0-5
vfx-chromevcvc-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:

{
  "$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. U
Read the complete source ↗