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.

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):

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

Worked Example: Adding a Block

Scenario

User has an existing HyperFrames project and wants to add an animated chart alongside their video content.

Steps

1. Install the block

hyperframes add data-chart

2. Wire into index.html

<div id="stage" data-composition-id="main" data-width="1920" data-height="1080" data-duration="30">
  <video
    id="speaker"
    src="speaker.mp4"
    data-start="0"
    data-duration="30"
    data-track-index="0"
    style="position: absolute; width: 60%; height: 100%; left: 0; top: 0; object-fit: cover;"
  ></video>

  <!-- Data chart appears at 5s in the right 40% of the screen -->
  <div
    data-composition-id="data-chart"
    data-composition-src="compositions/data-chart.html"
    data-start="5"
    data-duration="15"
    data-track-index="1"
    data-width="1920"
    data-height="1080"
    style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"
  ></div>
</div>

3. Lint and preview

hyperframes lint
hyperframes preview

4. Customize (optional)

Edit compositions/data-chart.html — data arrays are at the top of the script, colors are in the CSS rules scoped under [data-composition-id="data-chart"].

Worked Example: Adding a Component

Scenario

User wants to add a shimmer light sweep effect to their title text.

Steps

1. Install the component

hyperframes add shimmer-sweep

2. Read the snippet

Open compositions/components/shimmer-sweep.html and read the comment header.

3. Wire into your composition

HTML — wrap target elements:

<div class="shimmer-sweep-target" style="--shimmer-color: rgba(255, 255, 255, 0.5)">
  <h1 class="title">AI-Powered Video</h1>
</div>

CSS — paste the .shimmer-sweep-target and .shimmer-mask rules from the snippet.

JS — paste the auto-injection script (before timeline code):

document.querySelectorAll(".shimmer-sweep-target").forEach((el) => {
  if (!el.querySelector(".shimmer-mask")) {
    const mask = document.createElement("div");
    mask.className = "shimmer-mask";
    el.appendChild(mask);
  }
});

Timeline — add the sweep:

tl.fromTo(
  ".shimmer-sweep-target",
  {
    "--shimmer-pos": "-20%",
  },
  {
    "--shimmer-pos": "120%",
    duration: 1.2,
    ease: "power2.inOut",
    stagger: 0.15,
  },
  1.5,
);

4. Lint and preview

hyperframes lint
hyperframes preview

5. Customize

• --shimmer-color: highlight color per element
• --shimmer-width: light band width (default 20%)
• --shimmer-angle: sweep direction (default 120deg)
• Timeline duration, ease, stagger: control speed and feel

The demo.html Convention

Why components ship demo.html

Every component in the registry ships a companion demo.html file alongside its snippet. The demo serves two purposes:

1. Preview fixture — the CI preview pipeline renders the demo to generate thumbnail images and preview videos for the catalog docs page.

2. Usage example — the demo shows the component effect applied to representative content, serving as a working reference.

Demo structure

A demo is a complete, standalone HTML composition:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=1920, height=1080" />
    <title>Component Name — Demo</title>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <style>
      /* reset + canvas size */
    </style>
  </head>
  <body>
    <div data-composition-id="<name>-demo" data-width="1920" data-height="1080" data-duration="N">
      <!-- Demo content showing the effect -->
      <!-- Component snippet inlined here -->
    </div>
    <script>
      // GSAP timeline demonstrating the effect
      window.__timelines = window.__timelines || {};
      window.__timelines["<name>-demo"] = tl;
    </script>
  </body>
</html>

Key conventions:

• data-composition-id is <component-name>-demo to avoid collisions
• The demo is self-contained — all CSS and JS from the snippet is inlined
• The GSAP timeline is registered on window.__timelines
• Duration should be long enough to showcase the effect (typically 5-8 seconds)

Blocks don't need demo.html

Blocks are already standalone compositions that can be rendered directly. Only components need the demo wrapper.

Demos are not installed

The demo.html is NOT installed by hyperframes add — it exists only in the registry for preview generation and as a reference.

Registry Discovery

Reading the registry manifest

The top-level registry.json lists all available items:

curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

Each entry has name and type (hyperframes:example, hyperframes:block, or hyperframes:component).

Reading an item's manifest

Each item has a registry-item.json with full metadata:

<base>/<type-dir>/<name>/registry-item.json

Where <type-dir> is examples, blocks, or components.

Item manifest fields

Available items

Blocks

Components

Install Locations

Default paths

How path remapping works

The target field in each item's registry-item.json specifies a default install path. The add command remaps the prefix based on hyperframes.json#paths:

• Block targets starting with compositions/ get remapped to <paths.blocks>/
• Component targets starting with compositions/components/ get remapped to <paths.components>/

hyperframes.json

Created automatically by hyperframes init. If it doesn't exist when you run add, the CLI creates it with defaults:

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

Custom layouts

To install blocks into a scenes/ directory instead of compositions/:

{
  "paths": {
    "blocks": "scenes"
  }
}

Then hyperframes add data-chart writes to scenes/data-chart.html instead of compositions/data-chart.html. The snippet output reflects the remapped path.

Wiring Blocks

Blocks are standalone compositions with their own data-composition-id, dimensions, duration, and GSAP timeline. Include them in a host composition using data-composition-src on a <div>.

Basic wiring

After hyperframes add data-chart, wire it into your index.html:

<div id="stage" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
  <video id="a-roll" src="video.mp4" data-start="0" data-duration="20" data-track-index="0"></video>

  <!-- Block: appears at 2s, plays for 15s, on layer 1 -->
  <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>
</div>

Required attributes

Timeline coordination

The block's internal GSAP timeline runs independently from the host timeline. The HyperFrames runtime loads the sub-composition, finds its window.__timelines registration, and seeks the block in sync with the host, offset by data-start. You do NOT need to reference the block's timeline in your host's GSAP code.

Positioning blocks

To position a block in a specific area of the screen, add CSS:

<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"
  style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"
></div>

Multiple blocks

Include multiple blocks sequentially or overlapping:

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="0"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>
<div
  data-composition-id="flowchart"
  data-composition-src="compositions/flowchart.html"
  data-start="15"
  data-duration="12"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>
<div
  data-composition-id="logo-outro"
  data-composition-src="compositions/logo-outro.html"
  data-start="27"
  data-duration="6"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

Wiring Components

Components are effect snippets — HTML, CSS, and optionally JS that you merge directly into an existing composition. Unlike blocks, components have no standalone timeline; they participate in the host composition's timeline.

General process

1. Run hyperframes add <component-name> 2. Open the installed file (e.g., compositions/components/grain-overlay.html) 3. Read the comment header for usage instructions 4. Copy the parts into your host composition:

• HTML elements — inside your <div data-composition-id="...">
• CSS styles — into your composition's <style> block
• JS setup — into your composition's <script>, before your timeline code
• Timeline calls — into your GSAP timeline (if the component exposes them)

Example: grain-overlay (CSS-only, no timeline integration)

<!-- Paste the overlay div into your composition -->
<div
  id="grain-overlay"
  style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; z-index: 100;"
>
  <div class="grain-texture"></div>
</div>

Then paste the CSS keyframes and .grain-texture rule into your styles. No GSAP timeline calls needed — the grain animates via CSS @keyframes.

Example: shimmer-sweep (needs timeline integration)

Wrap target elements, paste CSS and JS, then drive the sweep from your timeline:

tl.fromTo(
  ".shimmer-sweep-target",
  {
    "--shimmer-pos": "-20%",
  },
  {
    "--shimmer-pos": "120%",
    duration: 1.2,
    ease: "power2.inOut",
    stagger: 0.15,
  },
  2.0,
);

Example: grid-pixelate-wipe (scene transition)

Paste the overlay HTML and CSS, then drive .grid-cell scale in your timeline:

// Cover screen
tl.to(
  ".grid-cell",
  { scale: 1, duration: 0.6, stagger: { amount: 0.6, from: "center" }, ease: "power2.inOut" },
  5.0,
);
// Swap scenes
tl.set("#scene-a", { opacity: 0 }, 5.6);
tl.set("#scene-b", { opacity: 1 }, 5.6);
// Reveal
tl.to(
  ".grid-cell",
  { scale: 0, duration: 0.6, stagger: { amount: 0.6, from: "edges" }, ease: "power2.inOut" },
  5.6,
);

Key principles

• Components inherit the host composition's dimensions and duration
• Place component HTML at the appropriate z-index relative to your content
• Read the comment header in each snippet for customizable values
• Run hyperframes lint after wiring to catch structural issues