Contributing to the Catalog

Your agent already knows how to build video components. It writes HTML. HyperFrames renders it. The registry is the collection of everything that’s been built — 52 blocks and counting. This guide shows you how to add to it.

Quick version — Fork the repo. Write one HTML file with a paused GSAP timeline. Add registry-item.json. Run hyperframes lint + validate. Publish with npx hyperframes publish. Open a PR.

Why Contribute?

Every block in the registry exists because someone needed it and built it. When you add a block, every HyperFrames user gets it with one command:

npx hyperframes add instagram-follow

The registry grows, HyperFrames gets more useful, and your work ships to everyone.

Two Paths

Ideas (No Code)

You spot visual trends before anyone. That’s the most valuable contribution.

Screen-record a caption style from TikTok/YouTube that doesn’t exist yet
Sketch a lower-third in Figma with fonts, colors, and timing
Install a component, preview it, report what feels off

Open an issue on GitHub with a visual reference. Tag it component-request.

The bar for ideas is low. We’d rather have 100 and build the best 10.

Build It

Every block is a single HTML file. No build step, no framework. If you use Claude Code with HyperFrames skills:

“I want to contribute a new transition that looks like [description]”

The /hyperframes-registry skill scaffolds the structure, validates, renders a preview, publishes to hyperframes.dev, and prepares the PR.

What Goes in the Registry

Blocks (registry/blocks/) — full standalone compositions. Fixed dimensions, fixed duration. Caption styles, VFX effects, title cards, transitions. Components (registry/components/) — reusable snippets. No fixed size. CSS effects, text treatments, overlays that adapt to any composition.

Structure

registry/blocks/my-block/
  my-block.html           ← the composition
  registry-item.json      ← metadata

registry-item.json

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "my-block",
  "type": "hyperframes:block",
  "title": "My Block",
  "description": "What this block does in one sentence",
  "tags": ["category", "subcategory"],
  "dimensions": { "width": 1920, "height": 1080 },
  "duration": 5,
  "files": [
    {
      "path": "my-block.html",
      "target": "compositions/my-block.html",
      "type": "hyperframes:composition"
    }
  ]
}

The Rules

Five things that must be true for every registry item:

Deterministic

No Math.random(), no Date.now(). Use seeded PRNG only.

Paused timeline

gsap.timeline({ paused: true }). The player controls playback.

window.__timelines["id"] must match data-composition-id.

No requestAnimationFrame

Use tl.eventCallback("onUpdate", render) for Three.js/WebGL scenes.

Hard kills on captions

tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) — no lingering text.

Break any of these and renders won’t be reproducible. The renderer captures every frame by seeking the timeline — if your animation depends on real time or random state, it breaks.

Quality Bar

Not everything belongs in the registry. The bar is production quality.

Type	Minimum standard
Captions	96px+ font, text-stroke/shadow, overflow prevention
VFX	Solves a problem that takes 4+ hours from scratch
Transitions	Smoother than CSS — if opacity 0→1 works, it’s not a transition
Blocks	Would a professional use this in a client project?

Common rejection reasons

“Looks like a demo” — a spinning cube is not a component
“Text unreadable” — font too small, no contrast treatment
“Non-deterministic” — Math.random() or Date.now()
“Timeline not found” — ID mismatch between HTML and JS
“Breaks as sub-composition” — element IDs collide (prefix everything)

Workflow

Fork and create

Fork heygen-com/hyperframes and create your block directory:

mkdir -p registry/blocks/your-block

Write your block

Create the HTML composition and registry-item.json. Use the templates above.

Validate

hyperframes lint
hyperframes check
npx oxfmt your-block.html

Update registry

# Add to registry index
# Update registry/registry.json
npx tsx scripts/generate-catalog-pages.ts

Render preview

hyperframes render -o preview.mp4

Publish and PR

npx hyperframes publish

Open a PR with your hyperframes.dev preview link.

External contributors: attach the preview MP4 to your PR. A maintainer handles the catalog image. HeyGen internal: run scripts/upload-docs-images.sh to push catalog PNGs.

What’s Needed Right Now

These are gaps in the registry. If you’re looking for something to build, start here.

Category	Gap	Difficulty
Captions	Karaoke with clip-path sweep (CapCut style)	Medium
Captions	RTL language layouts (Arabic, Hebrew)	Medium
Lower thirds	10 variations for podcasts/interviews	Easy
Lower thirds	News ticker / scrolling text bar	Easy
Maps	Animated route maps, region highlights, location pins	Medium
VFX	Product turntable with HDRI	Hard
VFX	Particle system with physics (collisions, gravity)	Hard
Transitions	Morphing shape transitions	Hard
Data viz	Sankey / flow diagrams	Medium

​Why Contribute?

​Two Paths

​Ideas (No Code)

​Build It

​What Goes in the Registry

​Structure

​registry-item.json

​The Rules

​Quality Bar

​Common rejection reasons

​Workflow

​What’s Needed Right Now

Why Contribute?

Two Paths

Ideas (No Code)

Build It

What Goes in the Registry

Structure

registry-item.json

The Rules

Quality Bar

Common rejection reasons

Workflow

What’s Needed Right Now