hyperframes-registry Checked

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, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

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.

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, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

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

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 (./references/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 (./references/wiring-blocks.md) for full details.

Wiring components