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.

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

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:

{

  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",

  "paths": {

    "blocks": "compositions",

    "components": "compositions/components",

    "assets": "assets"

  }

}

See install-locations.md for full details.

Wiring blocks

Blocks are standalone compositions — include them via data-composition-src in your host index.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 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):

• Read the installed file (e.g., compositions/components/grain-overlay.html)

• Copy the HTML elements into your composition's <div data-composition-id="...">

• Copy the <style> block into your composition's styles

• Copy any <script> content into your composition's script (before your timeline code)

• If the component exposes GSAP timeline integration (see the comment block in the snippet), add those calls to your timeline

See wiring-components.md for full details.

Discovery

Browse available items:

# 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 for details on filtering by type and tags.