Contribute to the Catalog

Add a reusable block or component to the HyperFrames registry.

The Catalog is generated from the registry in the HyperFrames repository. Add a block for a complete composition or a component for a reusable snippet.

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

Build the item

1. Fork and clone heygen-com/hyperframes.
2. Copy a nearby item of the same type as a starting point.
3. Rename the directory and update registry-item.json.
4. Add the item to registry/registry.json.

The manifest follows the registry item schema. Blocks declare dimensions and duration; components must not.

For a component, demo.html must be a complete composition that shows the effect and can be rendered by the Catalog preview pipeline.

Validate it

Run the same gates used for normal compositions:

npx hyperframes lint
npx hyperframes check

Then test the installation from another project:

npx hyperframes add your-item --dir /tmp/hyperframes-catalog-test

Check the installed file, copied include snippet, and standalone playback. Registry items must be deterministic: no real-time clocks, unseeded randomness, or render-time network dependencies.

Generate the Catalog page

npx tsx scripts/generate-catalog-pages.ts

The script regenerates the Catalog MDX, its index, and navigation from the registry manifests. Do not hand-edit a generated Catalog page.

To create the preview assets for one item:

npx tsx scripts/generate-catalog-previews.ts --only your-item

Open the pull request

Include:

• the registry files and regenerated Catalog output;
• a short description of where the item is useful;
• a preview image or video so reviewers can judge it without checking out the branch.

The item should be readable, seek correctly at any frame, work when installed outside its source directory, and add something meaningfully reusable. A one-off demo belongs in Examples rather than the Catalog.