Hyperframes Registry

---
name: hyperframes-registry
description: Install and wire registry blocks and components into HyperFrames compositions. Use when running `hyperframes add`, installing a block or component, wiring an installed item into index.html / a host composition, editing hyperframes.json paths, or discovering what the registry offers. Triggers (EN): "hyperframes add", "install a block", "install a component", "wire this block", "wire the component", "hyperframes.json paths", "registry block", "browse the registry". Triggers (FR): "ajoute un bloc hyperframes", "installe un composant", "câble le bloc dans index.html", "fusionne le snippet du composant", "où s'installe le bloc", "explore le registry hyperframes". NOT for authoring new compositions from scratch, hyperframes init/examples, or CLI internals (see hyperframes-cli).
---

# HyperFrames Registry

The registry provides reusable blocks and components installable via `hyperframes add <name>`.

- **Blocks** — standalone sub-compositions (own dimensions, duration, timeline). Included via `data-composition-src` in a host composition.
- **Components** — effect snippets (no own dimensions). Pasted directly into a host composition's HTML.

## Single-voice craft (do NOT parallelize)

Installing and wiring a registry item is one coherent, sequential procedure — run the command, read what it wrote, merge it into the host composition. Do NOT fan out to parallel sub-agents or split the install vs. the wiring across workers: the wiring must match the exact files and IDs that THIS install just produced. One agent, one pass, in order.

Two craft rules that prevent the most common breakage:

- **Match the real IDs, never invent them.** `data-composition-id` MUST equal the block's internal composition ID — read it from the installed file, do not guess it from the block name. The snippet the CLI prints is a starting point with placeholders; treat its attribute *values* as TODO, not as truth.
- **Cite the file you wrote.** Every wiring step references the actual installed path (e.g. `compositions/data-chart.html`) and the actual attribute read out of it — no hallucinated paths, IDs, durations, or dimensions. If a value isn't in the install output or the file, read the file before writing it.

## When to use this skill

- User mentions `hyperframes add`, "block", "component", or `hyperframes.json`
- Output from `hyperframes add` appears in the session (file paths, clipboard snippet)
- You need to wire an installed item into an existing composition
- You want to discover what's available in the registry

## Quick reference

```bash
hyperframes add data-chart              # install a block
hyperframes add grain-overlay           # install a component
hyperframes add shimmer-sweep --dir .   # target a specific project
hyperframes add data-chart --json       # machine-readable output
hyperframes add data-chart --no-clipboard  # skip clipboard (CI/headless)
```

After install, the CLI prints which files were written and a snippet to paste into your host composition. The snippet is a starting point — you'll need to add `data-composition-id` (must match the block's internal composition ID), `data-start`, and `data-track-index` attributes when wiring blocks.

Note: `hyperframes add` only works for blocks and components. For examples, use `hyperframes init <dir> --example <name>` instead.

## Install locations

Blocks install to `compositions/<name>.html` by default.
Components install to `compositions/components/<name>.html` by default.

These paths are configurable in `hyperframes.json`:

```json
{
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}
```

See [install-locations.md](./references/install-locations.md) for full details.

## Wiring blocks

Blocks are standalone compositions — include them via `data-composition-src` in your host `index.html`:

```html
<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>
```

Key attributes:

- `data-composition-src` — path to the block HTML file
- `data-composition-id` — must match the block's internal ID
- `data-start` — when the block appears in the host timeline (seconds)
- `data-duration` — how long the block plays
- `data-width` / `data-height` — block canvas dimensions
- `data-track-index` — layer ordering (higher = in front)

See [wiring-blocks.md](./references/wiring-blocks.md) for full details.

## Wiring components

Components are snippets — paste their HTML into your composition's markup, their CSS into your style block, and their JS into your script (if any):

1. Read the installed file (e.g., `compositions/components/grain-overlay.html`)
2. Copy the HTML elements into your composition's `<div data-composition-id="...">`
3. Copy the `<style>` block into your composition's styles
4. Copy any `<script>` content into your composition's script (before your timeline code)
5. If the component exposes GSAP timeline integration (see the comment block in the snippet), add those calls to your timeline

See [wiring-components.md](./references/wiring-components.md) for full details.

## Discovery

Browse available items:

```bash
# Read the registry manifest
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
```

Each item's `registry-item.json` contains: name, type, title, description, tags, dimensions (blocks only), duration (blocks only), and file list.

See [discovery.md](./references/discovery.md) for details on filtering by type and tags.

## Output contract

When this skill finishes wiring an item, the result is:

- The installed file(s) at their resolved paths (block → `compositions/<name>.html`, component → `compositions/components/<name>.html`, or the `hyperframes.json`-configured paths).
- The host composition edited so the item is referenced: a `data-composition-src` `<div>` with real `data-composition-id` / `data-start` / `data-duration` / `data-track-index` / `data-width` / `data-height` for a block, OR the HTML + `<style>` + `<script>` (+ optional GSAP timeline calls) merged in for a component.
- A one-line summary stating exactly which file was installed, which host file was edited, and the `data-composition-id` (blocks) used — cited from the install output / file, never invented.

## Verify

Before calling the wiring done:

1. **File exists** — confirm the installed path the CLI reported actually exists (`ls compositions/<name>.html`). If absent, the install failed; re-run `hyperframes add <name>`.
2. **ID matches** — for a block, grep the installed file for its internal composition ID and confirm the host `data-composition-id` is identical. A mismatch = the block renders blank.
3. **It renders** — open / preview the host composition (per the project's normal preview path) and confirm the block or component actually appears at the intended `data-start`. Runtime is the only proof the wiring is correct — a green edit with a blank frame is not done.