# Hyperframes Registry

> Install, discover, and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

Source: https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes-registry
Repository: https://github.com/heygen-com/hyperframes
Author: heygen-com
License: Apache-2.0
Updated: hace 4 días
Context cost: 118 tok installed, 1.6k tok once triggered, 19.6k tok with every bundled file
Bundle: 12 files, 77 KB
Permissions requested: none declared

## Install

```bash
npx -y skills add heygen-com/hyperframes --skill hyperframes-registry --agent claude-code
```

## What it does

- Instala blocks y components del registry HyperFrames vía `hyperframes add <name>`
- Busca en el catálogo por intención con `hyperframes catalog --query` o navegación por tipo/tag
- Genera el snippet HTML para conectar un block instalado con `data-composition-id`, `data-start` y `data-track-index`
- Guía la fusión de HTML/CSS/JS de un component instalado dentro de la composición host
- Documenta el flujo idea → scaffold → validar → PR para contribuir un nuevo block o component al registry

## Use it when

- Al ejecutar `hyperframes add` o `hyperframes catalog`
- Al instalar un item exacto o todos los blocks que coincidan con un tag
- Al conectar un item instalado dentro de `index.html`
- Al trabajar con `hyperframes.json` o autorar un nuevo block/component para subirlo upstream

## Don't bother when

- Para instalar examples, usar `hyperframes init <dir> --example <name>` en su lugar

## What triggers it

- "Instala el block data-chart en mi proyecto"
- "Busca en el catálogo algo que revele un titular línea por línea"
- "Conecta el component grain-overlay en mi composición"
- "Quiero crear un nuevo block de captions para contribuirlo al registry"

## Before you install

- Requiere el CLI `hyperframes` y, para búsqueda por significado (`--on-device`), una descarga única de modelo.
- Needs on PATH: curl, npx

## Files

- SKILL.md — 6 KB
- examples/add-block.md — 1 KB
- examples/add-component.md — 1 KB
- references/component-quality-bar.md — 16 KB
- references/contributing.md — 6 KB
- references/demo-html-pattern.md — 2 KB
- references/discovery.md — 18 KB
- references/install-locations.md — 1 KB
- references/placeholder-material.md — 9 KB
- references/templates.md — 11 KB
- references/wiring-blocks.md — 3 KB
- references/wiring-components.md — 2 KB

## SKILL.md

Reproduced verbatim from heygen-com/hyperframes under Apache-2.0. This section is the upstream document and is in English.

# 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. **Search by intent before browsing:** the registry holds more items than you can scan by eye, so listing them and matching on names or tags is the slow path, and it fails whenever the author's wording differs from yours.

```bash
# Rank the whole catalog against what the beat should do
npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add caption-clip-wipe
```

Search is local and sends nothing. By default it ranks on vocabulary shared with the item's name, title and description, so it only finds items that reuse your words; `--on-device` ranks by meaning instead, after a one-time model download. With `--json` the envelope names which tier answered, so check that rather than assuming a ranking happened.

Installability is applied after ranking, not before it: a name the vectors carry but this registry cannot serve is dropped from the results and counted in `dropped`, so a non-zero `dropped` means the two are different generations. See `/hyperframes-cli` for the offline tier, the consent gates, and how to refresh a stale index.

To browse or filter instead of search:

```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).

---

Skills Agentes — https://skillsagentes.com/skills/heygen-com/hyperframes/hyperframes-registry