Skip to content

catalog.mdx

Latest commit

 

History

History
209 lines (164 loc) · 6.96 KB

catalog.mdx

File metadata and controls

209 lines (164 loc) · 6.96 KB
Raw
title Contributing to the Catalog
description How to add blocks and components to the HyperFrames registry.

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 /contribute-catalog 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"
    }
  ]
}

Optional installer metadata

Most registry items only need the fields above. Add these optional fields when the installer needs extra context:

{
  "minCliVersion": "0.6.96",
  "registryDependencies": ["grain-overlay"],
  "deprecated": "Use `my-block-v2` instead."
}
  • minCliVersion — use this when the item depends on a HyperFrames CLI/runtime feature added in a recent release. The installer uses it to stop incompatible installs before writing files and guide users to upgrade.
  • registryDependencies — list other registry item names that must be installed first. Dependencies are resolved transitively; keep the graph small, reference exact item names, and avoid cycles.
  • deprecated — show a warning during install while keeping the item available for existing projects. Include a short migration note when there is a better replacement.

The Rules

Five things that must be true for every registry item:

No `Math.random()`, no `Date.now()`. Use seeded PRNG only. `gsap.timeline({ paused: true })`. The player controls playback. `window.__timelines["id"]` must match `data-composition-id`. Use `tl.eventCallback("onUpdate", render)` for Three.js/WebGL scenes. `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

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

Workflow

Fork [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) and create your block directory: ```bash mkdir -p registry/blocks/your-block ``` Create the HTML composition and `registry-item.json`. Use the templates above. ```bash hyperframes lint hyperframes validate npx oxfmt your-block.html ``` ```bash # Add to registry index # Update registry/registry.json npx tsx scripts/generate-catalog-pages.ts ``` ```bash hyperframes render -o preview.mp4 ``` ```bash npx hyperframes publish ``` Open a PR with your [hyperframes.dev](https://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