hyperframes/docs/contributing/catalog.mdx

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

<Info>
**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.
</Info>

## 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:

```bash
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](https://github.com/heygen-com/hyperframes/issues) with a visual reference. Tag it `component-request`.

<Tip>The bar for ideas is low. We'd rather have 100 and build the best 10.</Tip>

### 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](https://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

```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:

<Steps>
  <Step title="Deterministic">
    No `Math.random()`, no `Date.now()`. Use seeded PRNG only.
  </Step>
  <Step title="Paused timeline">
    `gsap.timeline({ paused: true })`. The player controls playback.
  </Step>
  <Step title="Register timeline">
    `window.__timelines["id"]` must match `data-composition-id`.
  </Step>
  <Step title="No requestAnimationFrame">
    Use `tl.eventCallback("onUpdate", render)` for Three.js/WebGL scenes.
  </Step>
  <Step title="Hard kills on captions">
    `tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)` — no lingering text.
  </Step>
</Steps>

<Warning>
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.
</Warning>

## 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

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

**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 |