heygen-com__hyperframes/docs/contributing/catalog.mdx

---
title: Contribute to the Catalog
description: Add a reusable block or component to the HyperFrames registry.
---

The Catalog is generated from the registry in the HyperFrames repository. You
can contribute a visual idea or build an item that anyone can install.

## Choose how to contribute

### Suggest an idea

Open a [GitHub issue](https://github.com/heygen-com/hyperframes/issues) with a
visual reference and explain where the effect would be useful. A screen
recording, Figma sketch, or example from another tool is enough to start.

### Build an item

Ask your agent to use the `/hyperframes-registry` skill, or follow the same
workflow below.

## Choose the item type

| Type | Use it for | Required files |
| --- | --- | --- |
| Block | A standalone composition with fixed dimensions and duration | `registry-item.json` and the composition HTML |
| Component | A snippet installed into another composition | `registry-item.json`, the snippet HTML, and a standalone `demo.html` |

Each item has its own directory under `registry/blocks/` or
`registry/components/`. Prefix every element ID with a short abbreviation of
the item name so it cannot collide when installed as a sub-composition.

```text
registry/blocks/my-block/
  my-block.html
  registry-item.json

registry/components/my-effect/
  my-effect.html
  demo.html
  registry-item.json
```

The Catalog preview generator skips a component without `demo.html`.

## Define the manifest

`registry-item.json` follows the
[registry item schema](https://github.com/heygen-com/hyperframes/blob/main/packages/core/schemas/registry-item.json).
Blocks declare `dimensions` and `duration`; components must not.

```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,
  "params": [
    {
      "key": "--accent",
      "label": "Accent",
      "type": "color",
      "default": "#ff4d4d"
    }
  ],
  "files": [
    {
      "path": "my-block.html",
      "target": "compositions/my-block.html",
      "type": "hyperframes:composition"
    }
  ]
}
```

Use `params` for the values someone should be able to change in Studio without
editing HTML. Supported controls are `color`, `text`, `number`, and `select`.

Other useful optional fields include `author`, `authorUrl`, `relatedSkill`,
`registryDependencies`, `license`, `sourcePrompt`, `minCliVersion`, and
`deprecated`. The TypeScript registry types and existing manifests are the
current authority. The published JSON schema validates the shared manifest
fields but does not yet describe the block-only `params` field.

### Binary assets

The registry is served straight out of the repository, so every byte an item
ships stays in the history forever. Compositions are text and cost nothing;
images, video, audio and fonts do not.

Commit those assets in your pull request as usual. Before merging, a maintainer
runs `bun run host:registry-assets <item-name>`, which uploads them to the CDN,
adds a `url` to each `files[]` entry and removes the bytes from the tree:

```json
{
  "path": "assets/carousel-images/one.jpg",
  "url": "https://static.heygen.ai/hyperframes-oss/registry-assets/deadbeefdeadbeef.jpg",
  "target": "assets/carousel-images/one.jpg",
  "type": "hyperframes:asset"
}
```

`path` does not change. It is still where the file lands relative to the item,
so your composition HTML, the Catalog preview renderer and `hyperframes add`
all behave exactly as they did — only the source of the bytes moves. Keys are
content-addressed, so an image shared by several items uploads once and a
changed image gets a new URL rather than a stale cached one.

### Installer metadata

Use `registryDependencies` to name registry items that must be installed first.
The installer resolves dependencies transitively and rejects missing items or
cycles. Reference exact item names and keep the dependency graph small.

Set `minCliVersion` to the first CLI version that supports the item. All resolved
items, including dependencies, must pass the compatibility check before any item
files are installed. An incompatible CLI reports the required version and an
upgrade command.

Set `deprecated` to a short migration message when an item has a replacement.
The installer warns and keeps the item available for existing projects.

```json
{
  "minCliVersion": "0.6.96",
  "registryDependencies": ["grain-overlay"],
  "deprecated": "Use my-block-v2 instead."
}
```

## Build for reuse

Every registry item must:

- use a paused GSAP timeline registered on `window.__timelines`;
- match `data-composition-id` to the registered timeline ID;
- use prefixed element IDs;
- avoid `Date.now()`, unseeded `Math.random()`, and real-time animation loops;
- seek correctly at any frame;
- work after installation outside its source directory.

A one-off example belongs in [Examples](/examples), not the Catalog.

## Validate and preview

Lint the item the way a user receives it — mounted into a real project. A bare
`npx hyperframes lint` cannot validate a registry directory, because the CLI
looks for `index.html` and items ship as `<name>.html` or `demo.html`:

```bash
bun run lint:registry-items my-block
```

To exercise the full gate, install the item into a scratch project and run there:

```bash
npx hyperframes init scratch && cd scratch
npx hyperframes add my-block
npx hyperframes check
```

Generate the Catalog page and preview assets:

```bash
npx tsx scripts/generate-catalog-pages.ts
npx tsx scripts/generate-catalog-previews.ts --only my-block
```

These generators read the item directly from the working tree. The `add`
command cannot install an unpublished local item by name: it resolves items
from the registry URL in `hyperframes.json`. Test `npx hyperframes add my-block`
from a clean project after the item is present in that registry manifest.

Do not hand-edit the generated item page. Fix its registry manifest or the
generator and regenerate it.

Watch the preview at full speed. Passing `check` proves the composition is
valid; it does not prove that the motion is readable or useful.

| Review question | What good looks like |
| --- | --- |
| Is there one visual hero? | The eye knows where to look in the first second |
| Can the important text be read once? | Information lands, then holds before the cut |
| Does motion accelerate and settle? | It does not drift at constant speed like a slide |
| Can someone restyle it? | Brand-facing values are exposed as parameters |
| Is it meaningfully reusable? | It solves a repeated production problem |

## Open the pull request

Include:

- the item directory;
- the matching entry in `registry/registry.json`;
- regenerated Catalog output;
- a `hyperframes.dev` preview from `npx hyperframes publish`;
- when to use it, its useful duration range, and any known pitfalls.

External contributors should attach the preview MP4. A maintainer will publish
the final Catalog media. HeyGen contributors can use
`scripts/upload-docs-images.sh` after preview review.