> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-canary-calibration-notes.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. 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 theme={null}
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 theme={null}
{
  "$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.

## 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 theme={null}
bun run lint:registry-items my-block
```

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

```bash theme={null}
npx hyperframes init scratch && cd scratch
npx hyperframes add my-block
npx hyperframes check
```

Generate the Catalog page and preview assets:

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