mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 23:03:09 +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
78 lines
2.3 KiB
Markdown
78 lines
2.3 KiB
Markdown
# 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)
|
|
|
|
```html
|
|
<!-- 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:
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
// 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
|