mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-04 07:19:52 +00:00
James Russo
4bde66f532
## What
New skill `hyperframes-registry` that teaches AI coding agents how to install and wire registry blocks and components into HyperFrames compositions.
### Skill structure
```
skills/hyperframes-registry/
SKILL.md — triggers, overview, quick reference
references/
install-locations.md — default paths, hyperframes.json config
wiring-blocks.md — iframe inclusion, data attributes, positioning
wiring-components.md — snippet merging (HTML, CSS, JS, timeline)
discovery.md — manifest reading, item fields, available items table
demo-html-pattern.md — why components ship demo.html, structure conventions
examples/
add-block.md — worked example: data-chart block install + wiring
add-component.md — worked example: shimmer-sweep component install + wiring
```
## Why
Phase B of the catalog plan (PR 10). Without this skill, agents using `hyperframes add` have to guess how to wire installed items into compositions. The skill encodes the iframe/snippet patterns so agents get it right on the first attempt.
## How
- SKILL.md frontmatter triggers on: `hyperframes add`, "block", "component", `hyperframes.json`
- References cover every step: discovery, install, wiring blocks (iframe), wiring components (snippet merge), and the demo.html convention
- Two worked examples walk through complete install-to-preview workflows
- Updated CLAUDE.md skills table + trigger rules, README.md skills table, docs/packages/cli.mdx
## Test plan
- [x] `scripts/lint-skills.ts` passes (checked 4 skill files, no issues)
- [x] `oxfmt --check` passes on all markdown files
- [x] SKILL.md frontmatter has valid `name` and `description`
- [x] All reference links in SKILL.md resolve to existing files
- [x] CLAUDE.md, README.md, and docs CLI page updated with new skill
92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
# 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`:
|
|
|
|
```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
|
|
|
|
| Attribute | Description |
|
|
| ---------------------- | -------------------------------------------------------------------- |
|
|
| `data-composition-src` | Path to the block HTML file (relative to index.html) |
|
|
| `data-composition-id` | Unique ID matching the block's internal composition ID |
|
|
| `data-start` | When the block appears in the host timeline (seconds) |
|
|
| `data-duration` | How long the block plays (seconds, at most the block's own duration) |
|
|
| `data-track-index` | Layer ordering — higher numbers render in front |
|
|
| `data-width` | Block canvas width (match the block's dimensions) |
|
|
| `data-height` | Block canvas height (match the block's dimensions) |
|
|
|
|
## 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:
|
|
|
|
```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"
|
|
style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"
|
|
></div>
|
|
```
|
|
|
|
## Multiple blocks
|
|
|
|
Include multiple blocks sequentially or overlapping:
|
|
|
|
```html
|
|
<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>
|
|
```
|