mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00

Files

T

James Russo 4bde66f532 feat(skills): hyperframes-registry skill (#261 )

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

2026-04-14 16:27:24 -07:00

2.3 KiB

Raw Blame History

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

Run hyperframes add <component-name>
Open the installed file (e.g., compositions/components/grain-overlay.html)
Read the comment header for usage instructions
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

2.3 KiB Raw Blame History