Add HyperFrames skills

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011h6NB8JQtfPc6eRCefEzBB
2026-10-14 21:51:46 +00:00
1 parent 6bd8165e6d
commit 1b2c8439f0
@@ -0,0 +1,45 @@
+# Motion-Graphics Builder
+
+Turn `shot-plan.json` into one renderable HyperFrames composition (`compositions/index.html`). Everything stays in the HF ecosystem — HTML is the source of truth; a single **paused** GSAP timeline carries all motion; the engine seeks it. Category-specific build rules live in `categories/<id>/module.md`; this file is the shared contract.
+
+## Reuse-first (the default)
+
+Default = **compose existing catalog capabilities, not hand-author**:
+
+- **Search first, for every named effect** — `npx hyperframes catalog --query "<the move, in plain English>" --json`, including an effect the user names after the plan is written. It needs nothing installed and no project. Author by hand only after a search came back with nothing that does the job, and report that miss with `npx hyperframes feedback --search-miss`.
+- `npx hyperframes add <block>` (registry) → customize in place. Most blocks bake content/data into their own script (only a few expose CSS-var params), so reuse = **add + edit**.
+- `hyperframes-animation` rules / blueprints / transitions for motion; runtime adapters (GSAP default).
+
+Hand-author only (a) gaps no block/rule covers, (b) the `asset-fusion` affordance binding. The Director named the block(s) + customizations in `shot-plan.json` (`content.block` + `content.customize`); see `catalog-map.md`.
+
+## The HF contract (non-negotiable)
+
+- Root `#stage` carries `data-composition-id`, `data-start="0"`, `data-duration=<s>`, `data-fps`, `data-width`, `data-height`.
+- Exactly ONE `gsap.timeline({ paused:true })`; register `window.__timelines["<id>"] = tl;`; end with `tl.seek(0)`. **Never `tl.play()`** for render-critical motion. No timers / async / event-driven timeline build. Finite repeats only.
+- **Timed clips** need `class="clip"` + a stable `id`. Timeline-driven groups inside one full-duration clip don't each need timing attrs.
+- **Fonts**: prefer local `@font-face` (.woff2) for deterministic / offline render; CDN Google Fonts do render (compiler caches + injects `@font-face`) but warn + need network.
+- **Deterministic only** — no `Date.now()` / `Math.random()` / network.
+
+## Layout before animation
+
+Build the **hero-frame end-state** in CSS first (flex + padding; never absolute offsets on content containers; the root must be sized). Use `fromTo()` for elements inside `.clip` and for any delayed entrance; `from()` is safe only for non-clip elements active from `t=0`. Exits belong to transitions or the final scene. Full rules: `references/builder-contract.md`.
+
+## IR → composition
+
+- `content.block` → `hyperframes add` it (or inline) + apply `content.customize`.
+- per-category `content` (text scenes / chart data / fusion positions / news-tweet content) → realize per `categories/<id>/module.md`.
+- resolved `asset_needs` → reference **frozen project-local paths** (never a remote URL or a prompt).
+- `palette[-1]` / bg + `font` from the envelope.
+- `export: alpha-overlay` → transparent bg; render `--format webm` (or `mov`).
+
+## Critical correctness (GSAP / seek)
+
+Opacity-gate delayed elements (set hidden until their entrance). Clamp at tween bounds (no overshoot past a held value). Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`). One motif per scene. Run `hyperframes check` for overflow / collisions.
+
+## Motion quality
+
+Before writing the timeline, read and follow the shared [motion principles](../../hyperframes-creative/references/motion-principles.md). For `charts` and `stat`, also read [data in motion](../../hyperframes-creative/references/data-in-motion.md) before laying out or animating the data.
+
+## Hand off for verification
+
+Self-check the authored file, then return it to the orchestrator. Step 5 runs `hyperframes lint`, `hyperframes check`, and proof snapshots on the assembled project. Do not render. When redispatched with a finding, fix the offending element and never change a fixed `data-duration` during repair. Remotion-source migrations use `/remotion-to-hyperframes` and its SSIM harness instead.
@@ -0,0 +1,54 @@
+# Motion-Graphics Director
+
+Turn a request into a `shot-plan.json` for a short (~3–30s) **design-led motion graphic**. You run in **two parts** around the asset-sourcing step: **Part 1 (plan)** before sourcing, **Part 2 (design)** after. You do NOT write composition code — that's the Builder. Schema: `references/shot-plan-ir.md`.
+
+## Part 1 — Plan (before sourcing)
+
+Emit a DRAFT `shot-plan.json`.
+
+0. **Decide first: does this need a search?** No → a **form category** (user supplies content). Yes → emit a search plan; the specific **search-driven category** (`webpage` / `news` / `tweet` / `asset-fusion`) is confirmed by what the search returns (Step 2 → finalized in Part 2).
+
+1. **Classify** — form categories by intent below; search-driven categories are picked post-search:
+
+   | Category       | Pick when…                                                                                                                                                                         |
+   | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `kinetic-type` | a punchy line / quote / title; text is the hero                                                                                                                                    |
+   | `stat`         | a single hero number / count-up                                                                                                                                                    |
+   | `charts`       | bar / line / pie / race / % from data                                                                                                                                              |
+   | `logo-reveal`  | a logo sting / brand lockup (user supplies the logo)                                                                                                                               |
+   | `lower-thirds` | name/title bars, callouts, social overlays                                                                                                                                         |
+   | `maps`         | a geographic shot — highlight regions, connect places, zoom to a location. Sub-fork: **vector** (D3, stylized) vs **basemap** (baked MapLibre — real satellite/dark/zoom-to-place) |
+   | `webpage`      | highlight / animate a real captured web page or UI _(search-driven)_                                                                                                               |
+   | `news`         | a news article → article-highlight: blur → zoom into keyword _(search-driven)_                                                                                                     |
+   | `tweet`        | a tweet → animated card _(search-driven)_                                                                                                                                          |
+   | `asset-fusion` | a real photo/asset's geometry _becomes_ the chart _(search-driven)_                                                                                                                |
+
+   If genuinely ambiguous between two, ask exactly one question. Then load `categories/<id>/module.md` for that category's specifics.
+
+2. **Asset strategy → `asset_needs[]`.** Each item: `{ role, kind: image|icon|logo|svg|news|web|tweet, query|source, treatment }`.
+   - asset-free (`kinetic-type`, most `stat`/`charts`) → `asset_needs: []`.
+   - `maps` → **vector** lane: `asset_needs: []` (D3/TopoJSON, runs live in HF). **basemap** lane (satellite/dark/zoom-to-place): `asset_needs: [{ type: "map-bake", … }]` (baked in Source — see `categories/maps/module.md`).
+   - `webpage` / `news` / `tweet` → search the real source (page / article / tweet) + a supporting image. **Two-pole queries only**: atomic (1–3 words, composable: portraits, logos, objects) OR specific (5–15 words: a news event, a tweet). Never the middle. A failed specific query is dropped, not broadened.
+   - `asset-fusion` → search or generate one hero asset.
+   - `logo-reveal` → user-supplied logo (`source`).
+
+3. **Envelope**: `duration_s` (3–30), `fps` (30), `canvas` (default 1080×1920; 16:9 / 1:1 per platform), `style`, `palette` (hex list, or `"derive-from-asset"`), `font` (from the HF embed list), `beats`, `export` (`mp4` | `alpha-overlay`).
+
+4. **Shot brief**: one paragraph — what the viewer experiences + the single dominant motion idea.
+
+## Part 2 — Design (after sourcing)
+
+Given the draft + resolved `assets/index.md` (if Step 2 ran) + `catalog-map.md`, design the shot **around the assets**:
+
+- **Run `npx hyperframes catalog --query "<the move, in plain English>" --json` for every look or effect the brief names**, before naming any block. It ranks the whole hosted registry and needs nothing installed. `catalog-map.md` is a partial snapshot; the search is the source of truth.
+- Pick the **catalog block(s)** from those results + the `hyperframes-animation` rules / blueprints (see `catalog-map.md` for how each category customizes).
+- Layout (hero-frame), motion (per `references/motion-vocabulary.md`), beats, pacing, exits.
+- `asset-fusion`: read the asset's **geometric affordance** → `element_positions` (center / extent / safe-zones / avoid-zones) + **eyedropper palette** from the asset.
+- Finalize `shot-plan.json`: `content.block` + `content.customize` + the per-category `content`.
+
+## Heuristics (design-led short motion)
+
+- **Motion IS the message**; no narration arc. Hook lands fast (~first 0.5s). **One dominant motif.** Pattern-interrupt if the piece runs >~2.5s (change exactly one thing). Effect intensity matches the energy. Legibility: a key element stays readable ≥~0.3s. Beats may be anticipated ~0.1s for perceived sync.
+- **Reuse-first**: name a catalog block; ask for hand-authored motion only for gaps + the `asset-fusion` affordance.
+
+Then hand `shot-plan.json` to the Builder.
@@ -0,0 +1,17 @@
+# Finalize / repair subagent
+
+Perform snapshot QA and one in-place repair pass. Dispatch only when Step 5 `lint`, `check`, or snapshot review reports a defect. The orchestrator owns final approval and render; this agent never renders.
+
+## Dispatch context
+
+`SKILL_DIR` / `PROJECT_DIR` / proof snapshot times / `lint` and `check` output tails, when present.
+
+## Flow
+
+1. **Snapshots** — run `npx hyperframes snapshot --at <proof-times>` and inspect overflow, off-canvas content, text collisions, empty frames, wrong content, and unreadable motion.
+2. **One in-place repair pass** — edit `compositions/index.html` for the visible issues. Never change a fixed `data-duration`; timing is set upstream.
+3. **Recheck** — rerun `npx hyperframes lint`, `npx hyperframes check`, and the affected snapshots. Return the result to the orchestrator without rendering.
+
+## STOP / escalate
+
+Only when the shot is **fundamentally wrong** (whole content off, needs recomposition) — return to Step 3/4 (re-design + re-build), don't force it with edits. Small fixes never escalate.