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

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.

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. Copy-paste starter templates (caption / VFX / component / registry-item.json) are in templates.md.

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

Contributing a Block or Component to the Registry

Guide the user from idea to merged PR for a new registry block or component.

Workflow

1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship

Step 1: Clarify

Ask what they're building. The registry has two item types:

• Block (registry/blocks/, type hyperframes:block) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
• Component (registry/components/, type hyperframes:component) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.

Then ask:

• One-sentence description of the effect
• Visual reference (URL, screenshot, or description)
• Who uses this and when?

Step 2: Scaffold

Create the registry structure:

For blocks:

registry/blocks/{block-name}/
  {block-name}.html
  registry-item.json

For components:

registry/components/{component-name}/
  {component-name}.html
  registry-item.json

Naming convention:

Use a 2-3 letter prefix. ALL element IDs must use this prefix to avoid collisions in sub-compositions.

registry-item.json — use the canonical templates in templates.md (block and component variants, both with all required fields).

Step 3: Build

Apply the correct template based on type. See templates.md for copy-paste starters.

Caption blocks

Non-negotiable caption rules:

• Font: 96px minimum for proportional fonts. 64-72px acceptable for monospace (wider characters need less size).
• Readability: -webkit-text-stroke: 2-3px OR multi-layer text-shadow
• Overflow: call window.__hyperframes.fitTextFontSize() on every group
• Karaoke: highlight active word via tl.to(wordEl, { color/scale }, WORDS[wi].start)
• Hard kill: tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) on EVERY group
• Never use `tl.from(el, { opacity: 0 })` at the same position as `tl.set(el, { opacity: 1 })` — the from clobbers the set. Use tl.to instead.

Per-character animation (typewriter, scramble):

• Wrap each character in <span> with ID {prefix}-ch-{group}-{char}
• Stagger via tl.set at computed intervals from word timestamps
• Cursors/decorative elements: use tl.set at intervals — NOT CSS animation (not seekable)

Positioning variants:

• Centered: display: flex; align-items: center; justify-content: center;
• Lower-third: position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;
• Left-aligned: position: absolute; bottom: 100px; left: 120px; text-align: left;

VFX blocks (Three.js)

• Use three@0.147.0 from CDN (global script)
• tl.eventCallback("onUpdate", renderScene); renderScene(); — NO requestAnimationFrame
• State proxy pattern: GSAP animates plain JS object, render function reads it
• Seeded PRNG (mulberry32) for randomness

All types

• data-composition-id MUST match window.__timelines["id"]
• All element IDs prefixed with block abbreviation
• gsap.timeline({ paused: true }) — always paused
• No Math.random(), no Date.now()

Step 4: Validate

hyperframes lint                    # 0 errors required
hyperframes validate --no-contrast  # 0 console errors required

Step 5: Preview

# Render preview video
hyperframes render -o preview.mp4

# Snapshot for visual QA
hyperframes snapshot --at "1.0,3.0,5.0,7.0"

# Publish to hyperframes.dev for review
npx hyperframes publish

Catalog preview image — The catalog card uses a PNG at docs/images/catalog/{kind}/{name}.png (where {kind} is blocks or components). Generate it from a snapshot, then:

• HeyGen internal contributors: run scripts/upload-docs-images.sh (requires AWS profile engineering-767398024897)
• External contributors: attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.

Step 6: Ship

All steps are required. Missing any one produces a broken catalog entry.

{kind} is blocks or components depending on what you built in Step 1.

# 1. Create branch
git checkout -b feat/registry-{name}

# 2. Format HTML
npx oxfmt registry/{kind}/{name}/*.html

# 3. Update registry/registry.json — add entry to the "items" array:
#    { "name": "{name}", "type": "hyperframes:block" }  (or "hyperframes:component")

# 4. Generate catalog docs page
npx tsx scripts/generate-catalog-pages.ts

# 5. Publish to hyperframes.dev so reviewers can preview
npx hyperframes publish

# 6. Stage everything
git add registry/{kind}/{name}/ registry/registry.json docs/catalog/

# 7. Commit
git commit -m "feat(registry): add {name} — {one sentence}"

# 8. Push and open PR with hyperframes.dev link
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"

If you don't have a GitHub account: you need one to open a PR. Sign up at https://github.com/signup, then run gh auth login.

Quality Gate

• [ ] hyperframes lint → 0 errors
• [ ] hyperframes validate → 0 console errors
• [ ] npx oxfmt --check passes
• [ ] registry/registry.json updated with new entry
• [ ] scripts/generate-catalog-pages.ts run (docs page generated)
• [ ] npx hyperframes publish run (claim your project URL)
• [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
• [ ] All IDs unique and prefixed

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

For an always-current list run npx hyperframes catalog --type block. The tables below group the 97 blocks by category. Block name ≠ shader name: shader-transition blocks (e.g. domain-warp-dissolve) wrap a HyperShader runtime whose internal name omits the -dissolve/-warp suffix — see the showcase HTML installed alongside the block for the canonical name.

Shader transitions (14)

Single-shader blocks; each installs one HyperShader runtime + a showcase composition. Use ≤2 per video.

Transition galleries (13)

Showcase compositions grouping multiple CSS / GSAP transition styles by family. Use as reference for picking a CSS scene transition; not meant to embed as-is.

Liquid Glass (7)

WebGPU + html-in-canvas frosted-glass surfaces. Require Brave / Chrome canary with WebGPU enabled — set PRODUCER_HEADLESS_SHELL_PATH to point at the browser; engine auto-passes --enable-unsafe-webgpu. See /hyperframes-animation → adapters/typegpu.md.

VFX (6)

HTML-in-canvas + WebGL composition blocks. See /hyperframes-animation → adapters/three.md and adapters/html-in-canvas-patterns.md for the underlying APIs.

Showcases (6)

Story-driven showcase compositions — narrated YouTube-style inserts. Most include bundled SFX.

Maps + data viz (8)

D3 + GSAP animated geographies and charts.

Social overlays (7)

Platform-recognizable UI overlays. Stamp on top of a beat or use as a beat closer.

Branding + 3D UI (2)

Code snippets (24)

A code/terminal window that types a code or shell session per-character. Theme = visual chrome only; structure, wiring, and install are identical across all 24 — pick one by name, wire it like any block (data-composition-id + data-start + data-track-index, see wiring-blocks.md). Two chrome families:

VS Code workbench (12) — full editor chrome (activity bar, sidebar, tabs, integrated terminal, status bar). Theme variants: code-snippet-dark-2026, code-snippet-dark-modern, code-snippet-dark-plus, code-snippet-light-2026, code-snippet-light-modern, code-snippet-light-plus, code-snippet-high-contrast, code-snippet-high-contrast-light, code-snippet-monokai, code-snippet-solarized-light, code-snippet-visual-studio-dark, code-snippet-visual-studio-light.

Apple Terminal (12) — macOS Terminal.app window typing a shell session. Profile = window colors:

Code Animations (9)

The richer, motion-first counterpart to the static code-snippet-* window themes above: each is a self-contained 1920×1080 block (~5–8s) with a paused, deterministic GSAP timeline that _animates_ code — typing, diffing, morphing, spotlighting, or GPU hero reveals — rather than typing a fixed snippet inside editor/terminal chrome. Reuse-first: npx hyperframes add <name>, then customize the baked code/diff content in place; hand-author only when no block covers the motion you need.

DOM / text reveal (6):

GPU / WebGL hero reveals (3): heavier, for a title-card / hero code moment.

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.

Contribute Templates

Copy-paste starter templates for each component type. These embed the proven patterns that pass lint and validate.

Caption Template

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link
      href="https://fonts.googleapis.com/css2?family=Montserrat:wght@800;900&display=swap"
      rel="stylesheet"
    />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <style>
      *,
      *::before,
      *::after {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      body {
        background: #111;
        overflow: hidden;
      }
      #root-BLOCKNAME {
        position: relative;
        width: 1920px;
        height: 1080px;
        overflow: hidden;
        background: #111;
      }
      .cap-container {
        position: absolute;
        top: 0;
        left: 0;
        width: 100%;
        height: 100%;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      .cg {
        position: absolute;
        display: flex;
        align-items: center;
        justify-content: center;
        gap: 32px;
        max-width: 1700px;
        overflow: visible;
        opacity: 0;
        visibility: hidden;
      }
      .cw {
        font-family: "Montserrat", sans-serif;
        font-weight: 900;
        font-size: 128px;
        color: #ffffff;
        text-transform: uppercase;
        line-height: 1;
        display: inline-block;
        -webkit-text-stroke: 3px rgba(0, 0, 0, 0.8);
        paint-order: stroke fill;
        text-shadow: 0 4px 12px rgba(0, 0, 0, 0.5);
      }
    </style>
  </head>
  <body>
    <div
      id="root-BLOCKNAME"
      data-composition-id="BLOCKNAME"
      data-start="0"
      data-duration="9"
      data-width="1920"
      data-height="1080"
    >
      <div class="cap-container" id="cc-BLOCKNAME"></div>
      <div
        id="drv-BLOCKNAME"
        class="clip"
        data-start="0"
        data-duration="9"
        data-track-index="0"
        style="position:absolute;width:1px;height:1px;opacity:0;pointer-events:none"
      ></div>
    </div>
    <script>
      (function () {
        window.__timelines = window.__timelines || {};

        // REPLACE with actual transcript data
        var WORDS = [
          { text: "Welcome", start: 0.3, end: 0.65 },
          { text: "to", start: 0.65, end: 0.8 },
          { text: "the", start: 0.8, end: 0.95 },
          { text: "future", start: 0.95, end: 1.4 },
          // ... add all words
        ];

        var GROUPS = [
          { start: 0.3, end: 1.3, wordStart: 0, wordEnd: 3, text: "Welcome to the future" },
          // ... add all groups
        ];

        var container = document.getElementById("cc-BLOCKNAME");

        GROUPS.forEach(function (g, gi) {
          var groupEl = document.createElement("div");
          groupEl.id = "PREFIX-cg-" + gi;
          groupEl.className = "cg";

          for (var wi = g.wordStart; wi <= g.wordEnd; wi++) {
            var wordEl = document.createElement("span");
            wordEl.id = "PREFIX-cw-" + wi;
            wordEl.className = "cw";
            wordEl.textContent = WORDS[wi].text;
            groupEl.appendChild(wordEl);
          }

          // Pretext overflow prevention
          if (window.__hyperframes && window.__hyperframes.fitTextFontSize) {
            var _fit = window.__hyperframes.fitTextFontSize(g.text.toUpperCase(), {
              fontFamily: "Montserrat",
              fontWeight: 900,
              maxWidth: 1550,
              baseFontSize: 128,
              minFontSize: 48,
            });
            if (_fit.fontSize < 128) {
              for (var _fi = 0; _fi < groupEl.children.length; _fi++) {
                groupEl.children[_fi].style.fontSize = _fit.fontSize + "px";
              }
            }
          }
          container.appendChild(groupEl);
        });

        var tl = gsap.timeline({ paused: true });

        GROUPS.forEach(function (g, gi) {
          var groupEl = document.getElementById("PREFIX-cg-" + gi);

          // SHOW — set opacity to 1 (never use tl.from with opacity:0 here)
          tl.set(groupEl, { opacity: 1, visibility: "visible" }, g.start);

          // ENTRANCE — customize this per style
          tl.from(groupEl, { scale: 1.3, duration: 0.15, ease: "back.out(2)" }, g.start);

          // KARAOKE — highlight each word
          for (var wi = g.wordStart; wi <= g.wordEnd; wi++) {
            var wordEl = document.getElementById("PREFIX-cw-" + wi);
            tl.to(wordEl, { color: "#FFD700", scale: 1.1, duration: 0.06 }, WORDS[wi].start);
            tl.to(wordEl, { color: "#FFFFFF", scale: 1, duration: 0.08 }, WORDS[wi].end);
          }

          // EXIT
          tl.to(groupEl, { opacity: 0, scale: 0.9, duration: 0.1 }, g.end - 0.1);

          // HARD KILL (mandatory)
          tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end);
        });

        window.__timelines["BLOCKNAME"] = tl;
      })();
    </script>
  </body>
</html>

Replace checklist:

• BLOCKNAME → your block name (e.g., cap-swoosh)
• PREFIX → short unique prefix for IDs (e.g., sw)
• Font family, weight, size → your style's typography
• Entrance animation → your style's entrance
• Karaoke highlight → your style's active word treatment
• Colors → your style's palette

---

VFX Template

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/three@0.147.0/build/three.min.js"></script>
    <style>
      *,
      *::before,
      *::after {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      body {
        background: #030308;
        overflow: hidden;
      }
      #root-BLOCKNAME {
        position: relative;
        width: 1920px;
        height: 1080px;
        overflow: hidden;
        background: #030308;
      }
      #canvas-BLOCKNAME {
        position: absolute;
        top: 0;
        left: 0;
        width: 1920px;
        height: 1080px;
      }
    </style>
  </head>
  <body>
    <div
      id="root-BLOCKNAME"
      data-composition-id="BLOCKNAME"
      data-start="0"
      data-duration="10"
      data-width="1920"
      data-height="1080"
    >
      <canvas id="canvas-BLOCKNAME" width="1920" height="1080"></canvas>
      <div
        id="drv-BLOCKNAME"
        class="clip"
        data-start="0"
        data-duration="10"
        data-track-index="0"
        style="position:absolute;width:1px;height:1px;opacity:0;pointer-events:none"
      ></div>
    </div>
    <script>
      (function () {
        window.__timelines = window.__timelines || {};

        // Seeded PRNG — NEVER use Math.random()
        function mulberry32(a) {
          return function () {
            a |= 0;
            a = (a + 0x6d2b79f5) | 0;
            var t = Math.imul(a ^ (a >>> 15), 1 | a);
            t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
          };
        }
        var rng = mulberry32(42);

        var W = 1920,
          H = 1080;
        var canvas = document.getElementById("canvas-BLOCKNAME");
        var renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true });
        renderer.setSize(W, H);
        renderer.setPixelRatio(1);
        renderer.toneMapping = THREE.ACESFilmicToneMapping;
        renderer.toneMappingExposure = 1.1;

        var scene = new THREE.Scene();
        scene.background = new THREE.Color(0x030308);
        var camera = new THREE.PerspectiveCamera(50, W / H, 0.1, 100);
        camera.position.set(0, 0, 8);

        // YOUR SCENE SETUP HERE
        // - lights
        // - geometry
        // - materials

        // State proxy — GSAP animates this, render reads it
        var st = {
          rotY: 0,
          camZ: 8,
          // add your animated properties
        };

        var tl = gsap.timeline({ paused: true });

        // YOUR TWEENS HERE
        tl.to(st, { rotY: Math.PI * 2, duration: 10, ease: "none" }, 0);

        window.__timelines["BLOCKNAME"] = tl;

        function renderScene() {
          // Apply state to Three.js objects
          camera.position.z = st.camZ;
          // mesh.rotation.y = st.rotY;

          renderer.render(scene, camera);
        }

        // Render via onUpdate — NO requestAnimationFrame
        tl.eventCallback("onUpdate", renderScene);
        renderScene();
      })();
    </script>
  </body>
</html>

Replace checklist:

• BLOCKNAME → your block name (e.g., vfx-chrome-blob)
• Scene setup → your geometry, lights, materials
• State proxy → your animated properties
• Tweens → your animation timeline
• renderScene → apply state to your Three.js objects

---

registry-item.json Templates

For blocks:

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "BLOCKNAME",
  "type": "hyperframes:block",
  "title": "Human-Readable Title",
  "description": "One sentence: what it does and who uses it",
  "dimensions": { "width": 1920, "height": 1080 },
  "duration": 10,
  "tags": ["category", "subcategory"],
  "files": [
    {
      "path": "BLOCKNAME.html",
      "target": "compositions/BLOCKNAME.html",
      "type": "hyperframes:composition"
    }
  ]
}

For components (no dimensions or duration):

{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "COMPONENTNAME",
  "type": "hyperframes:component",
  "title": "Human-Readable Title",
  "description": "One sentence: what it does",
  "tags": ["category"],
  "files": [
    {
      "path": "COMPONENTNAME.html",
      "target": "compositions/components/COMPONENTNAME.html",
      "type": "hyperframes:snippet"
    }
  ]
}

Tags by category:

• Captions: captions, viral, professional, karaoke, minimal
• VFX: three-js, particles, shader, gpu
• Transitions: transition, shader, wipe, dissolve
• Blocks: lower-third, social, title-card, data-viz
• Components: effect, overlay, text-treatment

---

Component Template

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <style>
      *,
      *::before,
      *::after {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }
      body {
        background: transparent;
        overflow: hidden;
      }
      .COMPNAME-wrap {
        position: absolute;
        inset: 0;
        overflow: hidden;
        pointer-events: none;
      }
    </style>
  </head>
  <body>
    <div class="COMPNAME-wrap">
      <!-- Your reusable effect/overlay here -->
    </div>
    <script>
      (function () {
        // Component snippet — no data-composition-id, no __timelines.
        // The parent composition controls timing.
        // Keep all class names and IDs prefixed with COMPNAME.
      })();
    </script>
  </body>
</html>

Replace checklist:

• COMPNAME → your component name (e.g., shimmer-sweep)
• Background should be transparent so it overlays cleanly
• No data-composition-id or window.__timelines — the parent owns timing

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

Add additional <div data-composition-src="..."> siblings with non-overlapping or overlapping data-start values — each block's timeline is independent and seeked in sync by the runtime.

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)

See examples/add-component.md for the full shimmer-sweep walkthrough (HTML wrapping, CSS, JS setup, and timeline call).

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