> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/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](https://github.com/heygen-com/hyperframes/blob/main/packages/core/schemas/registry-item.json). 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:

```bash theme={null}
npx hyperframes lint
npx hyperframes check
```

Then test the installation from another project:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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.