hyperframes-registry

# 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. ## Quick reference ```bash hyperframes add data-chart # install a block hyperframes add grain-overlay # install a component hyperframes add captions # install every block tagged captions 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. The positional value is resolved as an exact item name first. If no item matches and the value is a tag, the command installs every block with that tag. Registry dependencies are installed before the requested item. `hyperframes add` works only 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 Use the CLI as the primary discovery surface: ```bash npx hyperframes catalog npx hyperframes catalog --type block npx hyperframes catalog --type component npx hyperframes catalog --type block --tag social npx hyperframes catalog --json npx hyperframes catalog --human-friendly ``` The normal table and `--json` modes only list matches; install a selected name with `hyperframes add <name>`. `--human-friendly` opens an interactive picker and installs the selected item immediately. In CI or agent workflows, prefer `--json` followed by an explicit `add`. If the CLI cannot reach the configured registry, inspect the raw manifest as a fallback: ```bash 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. ## Contributing a new block or component To author a NEW registry item (caption style, VFX block, transition, lower third, or a reusable component) and ship it as an upstream PR — not install an existing one — follow the full idea → scaffold → build → validate → preview → ship workflow in [contributing.md](./references/contributing.md). Copy-paste starter templates (caption / VFX / component / `registry-item.json`) are in [templates.md](./references/templates.md).