freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.3

package/dist/assets/design/skills/hyperframes/references/routes/embedded-captions.md

@@ -0,0 +1,11 @@
+# Route: embedded-captions
+
+- **Input:** Existing talking-head footage to caption. It is an actual media file, not a URL or creative brief.
+- **Output:** The same footage, untouched, with a caption layer and selected caption identity. The subject may occlude embedded captions. Any length.
+- **Triggers:** "add captions", "add subtitles", "captions behind the subject", "cinematic captions for my clip".
+
+## Interview
+
+- **Must-haves:** which clip (the input file).
+- **Deferred (announce):** the caption **identity** pick — its Step 0 probes the clip first, then shortlists 2–3 identities from the catalog and recommends one. Say that's coming.
+- **Run-shape:** neither — the footage is untouched; there is no storyboard to review.

package/dist/assets/design/skills/hyperframes/references/routes/faceless-explainer.md

@@ -0,0 +1,12 @@
+# Route: faceless-explainer
+
+- **Input:** A topic, article, notes, or arbitrary text being explained, with no product being marketed and no website to capture.
+- **Output:** A faceless explainer MP4 with invented typography, abstract graphics, diagrams, or data visualization. Sweet spot 30–90s; hard cap about 3 minutes.
+- **Triggers:** "faceless explainer about X", "explain how DNS works as a video", "turn this article into an explainer".
+
+## Interview
+
+- **Must-haves:** **angle** — concept / how-to / listicle / narrative, recommend the one the text's own shape suggests · **length** — inside the 30–90s sweet spot, scaled to how much the text actually teaches · **destination** — YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
+- **Conditional:** a pasted script adds **`VO_MODE`** — use it verbatim, or restructure per scene?
+- **Pitch round:** `message` + `angle` — five tellings of the same topic are five different videos.
+- **Run-shape:** both.

package/dist/assets/design/skills/hyperframes/references/routes/general-video.md

@@ -0,0 +1,12 @@
+# Route: general-video
+
+- **Input:** Any custom creation or edit not covered by a specialized route: a static title card, longer brand or sizzle reel, multi-scene montage, static loop/poster, NLE-like footage remix, or freeform composition. It also executes every `flow: companion` brief.
+- **Output:** A HyperFrames composition of any length or format through design → plan → static layout → animation → check → approval → render.
+- **Triggers:** "make a static title card", "longer brand reel", "multi-scene composition", "static loop", "custom video", or any unmatched video request.
+
+## Interview
+
+- **Open-ended requests only:** first derive a one-sentence `message`. Ask `audience` only when it is unclear and would change the story or terminology. Ask `destination` only when it would change aspect or composition. Ask for a priority only when the brief contains a real trade-off. Default to one best version; ask about variations only when the user requests options or comparison.
+- **Specific requests:** a complete ask such as "a static title card with our logo for a website hero" needs no discovery questions.
+- **Pitch round:** `message` — the unformed open-ended request is this round's home case.
+- **Run-shape:** both questions apply. `/general-video` is also the companion host, so `flow: companion` stays on this route with the full toolbox.

package/dist/assets/design/skills/hyperframes/references/routes/motion-graphics.md

@@ -0,0 +1,11 @@
+# Route: motion-graphics
+
+- **Input:** A short design-led unit, typically under 10s, with no narration, where motion is the message: kinetic type, stat/count-up, chart hit, logo sting, animated title, lower-third, map, tweet/headline/page highlight, or asset-fusion shot.
+- **Output:** A short MP4 or transparent alpha WebM/MOV overlay.
+- **Triggers:** "an 8s logo sting", "animate this stat", "kinetic-type intro", "animate this title", "transparent lower-third overlay".
+
+## Interview
+
+- Autonomous by design: at most **one** clarifying question, owned by its director step, in the flow. No must-haves here beyond confirming the input; route directly.
+- **Run-shape:** neither — the piece is seconds long; a storyboard and a companion session have nothing to add.
+- **Front-door capability offer:** skip it. The director's one-question limit is authoritative.

package/dist/assets/design/skills/hyperframes/references/routes/music-to-video.md

@@ -0,0 +1,12 @@
+# Route: music-to-video
+
+- **Input:** A music track, a video whose audio becomes the track, or a track generated from a mood brief — with no narration or website capture. User images or videos are optional, so a complete video needs zero supplied assets.
+- **Output:** A beat-synced MP4 driven by a deterministic beat/energy map (`audiomap.json`). It may become a lyric video, slideshow, visualizer, or kinetic promo without changing pipelines.
+- **Triggers:** "make a video for this song", "beat-synced video", "lyric video", "music visualizer", "kinetic promo to this beat".
+
+## Interview
+
+- **Must-haves:** the **music source** — a track file, a video to pull audio from, or generate one from a mood description · **destination → aspect**.
+- **Deferred (announce):** brand (font + palette) and the genre feel are chosen at its Step 3 by design — they emerge from the track's analysis, not from a question up front.
+- **Pitch round:** `message` — the visual concept riding the beat grid (lyric treatment, montage story, kinetic type); brand and genre feel still land at Step 3.
+- **Run-shape:** both.

package/dist/assets/design/skills/hyperframes/references/routes/pr-to-video.md

@@ -0,0 +1,28 @@
+# Route: pr-to-video
+
+- **Input:** A GitHub PR URL, `owner/repo#N`, or "this PR", read through `gh`; it is not a website capture request.
+- **Output:** A changelog, feature reveal, fix explainer, or refactor walkthrough with diff, before/after, file-tree, and impact scenes. Hard cap about 3 minutes; duration follows change size.
+- **Triggers:** "make a video about this PR", "turn PR #1187 into a changelog video", "release-notes video from this pull request".
+
+## Interview
+
+- **Must-haves:** the **PR reference** (URL, `owner/repo#N`, or "this PR") · **angle** — changelog / feature-reveal / fix-explainer / refactor-walkthrough, recommend the one the PR itself suggests · **audience** — developers (default) · mixed technical · non-technical stakeholders · **length** — from the size table below · **destination** — 16:9 is the default for a code explainer.
+- **Length comes from the PR's change size**, not a fixed guess — peek once, read-only (the workflow's Step 1 still does the full deterministic fetch):
+
+  ```bash
+  gh pr view <PR_REF> --json title,additions,deletions,changedFiles
+  ```
+
+  Pick the tier from `additions + deletions` (nudged up by `changedFiles`) and lead with it (hard cap ~3 min):
+
+  | PR change size                    | Recommended length |
+  | --------------------------------- | ------------------ |
+  | trivial (≲ 50 lines changed)      | ~20–40s            |
+  | focused (~50–200 lines)           | ~40–70s            |
+  | substantial (~200–600 lines)      | ~70–110s           |
+  | large (≳ 600 lines, or 25+ files) | ~110–180s          |
+
+  State the basis in one phrase ("~40s — small change, +44/−13 across 12 files"). The tier is a **ceiling** on how much story the diff can support, never a floor to fill: a one-headline story recommends inside 30–90s regardless of tier (the tier's range may still appear as a non-recommended fuller-walkthrough option).
+
+- **Pitch round:** `angle` and the opening hook — the diff fixes the facts, not the telling.
+- **Run-shape:** both.

package/dist/assets/design/skills/hyperframes/references/routes/product-launch-video.md

@@ -0,0 +1,13 @@
+# Route: product-launch-video
+
+- **Input:** A website URL; a script or brief that names a site; or a product-launch script with no derivable site or an explicit "do not scrape" instruction. Capture website assets and brand tokens unless the brief selects no-capture mode. Ask whether supplied script copy is verbatim voice-over or may be restructured.
+- **Output:** A product promo, launch video, site tour, or showcase MP4. Sweet spot 30–90s; hard cap about 3 minutes. A show-it-as-is brief features captured screens rather than inventing a separate route.
+- **Triggers:** "launch video for X", "promo for our site", "turn this script into a 60s promo", "text-only launch video", "turn this website into a video", "site tour from this URL".
+
+## Interview
+
+- **First, sell or show?** One question when the request doesn't say: market the product (a promo), or show the site as-is (a tour / showcase)? A show-it answer is **intent, not a different pipeline**: write it into `BRIEF.md` (`## Intent` / `## Customizations` — "feature the site's own captured screens as the video's assets") and the workflow's normal steps carry it — the captured screens become the featured `asset_candidates`.
+- **Must-haves:** **angle** — story shapes from the site's / brief's own positioning, recommend one with its basis · **length** — 30–90s sweet spot, scaled to the material · **destination** — YouTube / embed → 16:9 · X / LinkedIn / Instagram feed → 1:1 · Shorts / TikTok → 9:16.
+- **Conditional:** a show-it-as-is ask adds **what to show** — the whole site, or specific pages/sections (into `BRIEF.md`'s body); a pasted script/brief adds **`VO_MODE`** (verbatim or restructured?); a script that only names a site adds **capture?** — crawl it for brand + assets (default), or text-only / "don't scrape" (no-capture mode, a preset supplies the design system).
+- **Pitch round:** `message` + `angle`, after sell-or-show is settled — the pitches inherit that intent.
+- **Run-shape:** both.

package/dist/assets/design/skills/hyperframes/references/routes/remotion-to-hyperframes.md

@@ -0,0 +1,9 @@
+# Route: remotion-to-hyperframes
+
+- **Input:** Existing Remotion React source, only when the user explicitly asks to port, convert, or migrate it. A passing Remotion mention is not a trigger.
+- **Output:** A HyperFrames HTML composition translated from the source and compared with the Remotion render through the migration evaluation harness.
+- **Triggers:** "port my Remotion project", "convert this Remotion composition", "migrate from Remotion".
+
+## Interview
+
+- Not served by the intent layer — a migration with no brief. Route directly.

package/dist/assets/design/skills/hyperframes/references/routes/slideshow.md

@@ -0,0 +1,11 @@
+# Route: slideshow
+
+- **Input:** A brief, outline, or existing page to author as a presentation, pitch deck, or interactive deck. If "slides", "deck", or "convert this page" is ambiguous, confirm that the user wants a HyperFrames slideshow before authoring.
+- **Output:** A runnable HyperFrames composition plus the JSON island used by `SlideshowController`: discrete slides, fragment reveals, branching, hotspots, presenter mode, and speaker notes. The deliverable is a navigable deck, not an MP4.
+- **Triggers:** "make a pitch deck", "interactive presentation", "convert this page into slides", "slideshow with presenter mode".
+
+## Interview
+
+- The one question is the routing confirmation itself — "do you want this as a HyperFrames slideshow?" — asked during triage (it survives every mode: wrong routing is a quality problem). The deck contract owns everything after.
+- **Run-shape:** neither — the deliverable is a navigable deck, not a rendered video.
+- **Front-door capability offer:** skip it. After route confirmation, the deck workflow owns all remaining choices.

package/dist/assets/design/skills/hyperframes/references/routes/talking-head-recut.md

@@ -0,0 +1,11 @@
+# Route: talking-head-recut
+
+- **Input:** Existing talking-head, interview, or podcast footage to package. The underlying clip plays unchanged.
+- **Output:** The same footage with transcript-synced graphic-overlay cards: kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, or picture-in-picture. Any length.
+- **Triggers:** "package this video", "add graphic overlays to my talk", "add lower-thirds or data callouts to this interview".
+
+## Interview
+
+- **Must-haves:** which clip (the input file).
+- **Deferred (announce):** its render-strategy questions — aspect ratio, layout, style group, card count — stay at its Step 7, where the recommendations come from the probed footage and transcript. Say they're coming.
+- **Run-shape:** neither.

package/dist/assets/design/skills/hyperframes/references/script-format.md

@@ -0,0 +1,52 @@
+# `SCRIPT.md` — locked narration (optional)
+
+The **locked narration** for a project: the final spoken lines + voice + delivery. It is an _optional_ plan-layer file — a video with no narration (bgm-only, silent overlay) has none. The storyboard's per-frame `voiceover` is the lighter, editable _guide_; `SCRIPT.md` is the _commit_. (Storyboard format → `references/storyboard-format.md`.)
+
+This file defines the SCRIPT.md **shape** only. Synthesizing the spoken lines into audio is a capability owned by `media-use` → `../../media-use/audio/references/tts.md`.
+
+Free-form markdown — there is no strict parser; the TTS step extracts the indented spoken lines.
+
+## Shape
+
+A header block, then one section per spoken line.
+
+| Part                            | Holds                                                                                                                                   |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Header                          | `**Voice:**` (provider + voice), `**Voice settings:**` (e.g. stability / similarity / style), `**Voice direction:**` (overall delivery) |
+| `## Line N — <label> (Frame N)` | one spoken line, tied to its storyboard frame                                                                                           |
+| `**Time:**`                     | the frame's rough window — a _guide_, not authoritative (real timing comes from TTS word timestamps)                                    |
+| `**Delivery:**`                 | per-line delivery note                                                                                                                  |
+| indented block                  | the **spoken text** — the only part fed to TTS                                                                                          |
+
+## Example
+
+```markdown
+# SCRIPT — acme-launch
+
+**Voice:** Rachel (ElevenLabs)
+**Voice settings:** stability 0.35 · similarity 0.75 · style 0.20
+**Voice direction:** Confident, warm, a little playful.
+
+---
+
+## Line 1 — Hook (Frame 1)
+
+**Time:** 0.0 – 3.0s
+**Delivery:** Land the promise on the beat.
+
+    Ship a launch video in an afternoon.
+
+## Line 2 — The problem (Frame 2)
+
+**Time:** 3.0 – 7.0s
+**Delivery:** Wry, a touch tired.
+
+    The old way? Prompt, wait twenty minutes, get something that misses.
+```
+
+## To TTS
+
+Feed each line's spoken text to the provider documented in
+`media-use/audio/references/tts.md`. The `hyperframes tts` command is
+Kokoro-only; use its `--voice` flag, or use the bundled HeyGen helper when word
+timestamps are required. Real per-word timing replaces the `**Time:**` guides.

package/dist/assets/design/skills/hyperframes/references/skill-lifecycle.md

@@ -0,0 +1,30 @@
+# Skill installation and freshness
+
+Read this reference when installing or updating skills, diagnosing unexpected workflow behavior, or running HyperFrames setup in CI.
+
+HyperFrames installs the core set eagerly and workflow skills lazily.
+
+- **Core set:** `/hyperframes`, the `hyperframes-*` domain skills, and `/media-use`.
+- **Workflow skills:** installed when routing selects them through `this pack is bundled offline and is not updated at runtime <workflow-name>`.
+
+## What `init` does
+
+Create the project directory and its composition file directly; this pack needs no scaffolding step.
+
+The `--skip-skills` CLI flag is temporarily ignored. CI and tests may opt out with `HYPERFRAMES_SKIP_SKILLS=1`.
+
+## Diagnose and update
+
+```bash
+this pack is bundled offline and is not updated at runtime
+this pack is bundled offline and is not updated at runtime <workflow-name>
+```
+
+- `skills check` exits non-zero when an installed skill is stale or the core set is incomplete. Workflows available on demand but not installed are not failures.
+- Bare `skills update` refreshes the core set and everything already installed, prunes unpublished skills, and does not expand the workflow set.
+- Named `skills update <name...>` also installs those named workflows or domain skills.
+- Bare `skills` installs the full published set explicitly.
+
+If the HyperFrames CLI is unavailable, use `npx skills add heygen-com/hyperframes --skill <workflow-name>` for one workflow or `npx skills add heygen-com/hyperframes --all` for the full published set.
+
+The CLI may print a one-line stale-skill reminder during `render`, `lint`, or `check`. Treat a failed update as a visible tool failure; do not continue from a remembered workflow contract.

package/dist/assets/design/skills/hyperframes/references/storyboard-format.md

@@ -0,0 +1,99 @@
+# Storyboard format — `STORYBOARD.md` + parsed manifest
+
+Defines the storyboard's **base data format** only: the `STORYBOARD.md` file shape and the `StoryboardManifest` it parses into. How a workflow _generates_ a storyboard lives in that workflow; the optional narration/TTS file (`SCRIPT.md`) is a separate concern owned by the TTS step, not here.
+
+A storyboard is the **plan layer** for a video — an ordered set of **frames** (key moments) in one markdown file. Parser: `@hyperframes/core/storyboard` → `StoryboardManifest`.
+
+## Frontmatter (global direction)
+
+YAML block at the top. Unknown keys are kept under `globals.extra`.
+
+| Key        | Meaning                                                           | Example                                   |
+| ---------- | ----------------------------------------------------------------- | ----------------------------------------- |
+| `format`   | Canvas size                                                       | `1920x1080`                               |
+| `duration` | The brief's rough length expectation (advisory, not a hard limit) | `22s`                                     |
+| `message`  | One-line thesis                                                   | `Ship a launch video in an afternoon`     |
+| `arc`      | Narrative arc                                                     | `Hook → Problem → Solution → Proof → CTA` |
+| `audience` | Who it's for                                                      | `indie devs on X`                         |
+| `mode`     | Interaction mode (see `brief-contract.md`; default collaborative) | `autonomous`                              |
+
+Set `duration` from the brief's `length` when the storyboard is first written. It is an expectation, not a gate: assembly reports where the cut actually lands against it and flags a large gap — judge whether the drift serves the piece, and update the value when the intended length genuinely changes.
+
+## Per-frame sections
+
+One `## Frame N — Title` heading per frame (`Frame` / `Beat` / `Scene` accepted at H2/H3). Metadata as `- key: value` bullets; everything below them until the next heading is the free-form **narrative**.
+
+| Key             | Meaning                                                                                                       |
+| --------------- | ------------------------------------------------------------------------------------------------------------- |
+| `status`        | `outline` → `built` → `animated` (defaults `outline`)                                                         |
+| `src`           | project-relative path to the frame's HTML sub-composition (the tile poster renders from it)                   |
+| `duration`      | e.g. `4s`                                                                                                     |
+| `transition_in` | `crossfade` / `cut` / `wipe` … (alias `transition`)                                                           |
+| `scene`         | one-line contact-sheet caption (aliases `description` / `summary` / `caption`)                                |
+| `voiceover`     | the frame's narration _guide_ (aliases `vo` / `voice_over` / `narration`)                                     |
+| `poster`        | seconds to seek for the tile poster (past the intro animation)                                                |
+| _any other key_ | kept verbatim under the frame's `extra` — a workflow carries its own per-frame data (effects, assets, …) here |
+
+## Parsed manifest
+
+The parser is **lenient**: it never throws and records anything surprising as a `warning`.
+
+```
+StoryboardManifest {
+  globals: { format?, message?, arc?, audience?, extra: {…} }
+  frames: Array<{
+    index, number?, title?,
+    status,                       // "outline" | "built" | "animated"
+    src?, duration? / durationSeconds?, transitionIn?,
+    scene?, voiceover?, poster?,
+    narrative,                    // markdown below the metadata
+    extra: {…}                    // unknown keys, preserved
+  }>
+  warnings: Array<{ message, line?, frameIndex? }>
+}
+```
+
+## `SCRIPT.md` (out of scope here)
+
+Optional, free-form, **not parsed into the manifest** — the locked-narration file that drives TTS. Its format is defined in `references/script-format.md`, and it is absent for videos with no narration/TTS. The per-frame `voiceover` above is the storyboard's own narration guide.
+
+## Example
+
+```markdown
+---
+format: 1920x1080
+message: "Ship a launch video in an afternoon"
+arc: Hook → Problem → Solution → Proof → CTA
+audience: indie devs on X
+---
+
+## Frame 1 — Hook
+
+- scene: Big type punches in on the beat
+- duration: 3s
+- poster: 2s
+- transition_in: cut
+- status: animated
+- voiceover: "Ship a launch video in an afternoon."
+- src: compositions/frames/01-hook.html
+
+Open cold on the promise. This is the thesis — everything after pays it off.
+
+## Frame 2 — The problem
+
+- scene: A 20-minute timer spins on a stack of rejected takes
+- duration: 4s
+- transition_in: crossfade
+- status: built
+- voiceover: "The old way? Prompt, wait twenty minutes, get something that misses."
+- src: compositions/frames/02-problem.html
+
+The old way: prompt, wait, get something that misses. Establish the pain we remove.
+```
+
+## Notes
+
+- A frame with `status: outline` and no built `src` renders as an outline placeholder.
+- `built` is the middle rung: the frame's HTML exists and its **layout is confirmed** (a wireframe sketch or better) — motion not yet added. Nothing is drawn yet beyond the approved layout.
+- The process that walks these statuses — plan, sketch, build, each pass reviewed in chat and in `storyboard.html` — is `review-loop.md`.
+- Multi-line `voiceover` values collapse to one line on save.

package/dist/assets/design/skills/hyperframes/references/subagent-dispatch.md

@@ -0,0 +1,35 @@
+# Subagent dispatch — harness adapter
+
+The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-video` / `motion-graphics` / `general-video`) describe subagent dispatch in harness-neutral verbs. This file maps those verbs to the primitives of whatever agent harness you are running on. Read it once per run, before the first dispatch; everything else in the workflows (dispatch packets, file artifacts, exit-code gates, Resume tables) is harness-independent and needs no translation.
+
+## The contract (identical on every harness)
+
+- **DISPATCH(role_file, dispatch_context)** — start one child agent whose prompt is the **full contents of the named role file** (a builder-assembled payload like `.hyperframes/frame-packets/_role.md`, or a workflow's `sub-agents/<role>.md`) followed by the `## Dispatch context` block from the workflow, copied **verbatim** (never digested or paraphrased). Every harness below accepts arbitrary task text, so this works everywhere; never rely on the child seeing your conversation, memory, or skills — the prompt and the files on disk are its entire world.
+- **Parallel fan-out** — when a step says "start N workers in parallel", the workers are mutually independent (no ordering, no shared state beyond the filesystem). Run as many concurrently as your harness allows.
+- **WAIT** — a step's completion criterion is always **the expected artifact existing on disk** (e.g. `compositions/<scene-id>.html`), never the harness's completion notification (some harnesses deliver results best-effort). After waiting, verify the artifacts; a missing artifact means that child failed — re-dispatch it once with the same prompt before surfacing an error.
+
+## Concurrency cap → batching rule (cap never changes scope)
+
+A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, one scene per dispatch, with the available slots chewing through the full list.
+
+- When the harness queues excess children internally, submit **all N at once** and let the queue drain.
+- Harness hard-caps active children (e.g. OpenClaw `maxChildrenPerAgent`) → dispatch in **waves of the cap size**: start `cap` workers, wait for their artifacts, start the next wave, until all N scenes exist. Example: 9 scenes on a cap-3 harness = 3 waves of 3 — never drop scenes, never merge scenes into one worker to fit the cap.
+
+## Harness mapping
+
+Use the current harness's native delegation and waiting tools when they are available. The workflow contract stays the same:
+
+- **DISPATCH** sends the complete role file and dispatch context to one worker.
+- **Parallel fan-out** starts independent workers concurrently up to the harness limit.
+- **WAIT** verifies the expected artifacts on disk, not only a completion notification.
+- **Re-dispatch** starts a fresh worker with the same context plus the gate failure.
+
+When native delegation is unavailable, use the existing fallback ladder: launch headless CLI workers that share the project filesystem, then fall back to inline serial execution.
+
+On Codex, native delegation requires the user's explicit permission. Fold a one-line request into the workflow's first existing user pause before dispatch; a standing grant in `AGENTS.md` or the kickoff prompt also counts. Without it, use the fallback ladder rather than silently skipping work.
+
+## Vocabulary mapping
+
+- A request to work "in the background" means dispatch concurrently when the harness supports it.
+- Load a named skill through the harness's skill mechanism, or read `<skills-root>/<skill>/SKILL.md` directly.
+- Map generic read, write, edit, and shell verbs to the current harness's equivalent tools.

package/dist/assets/design/skills/hyperframes/references/workflow-catalog.md

@@ -0,0 +1,10 @@
+# Workflow catalog (moved)
+
+Each workflow's input/output/trigger contract now lives in its own route file — one
+small read per candidate instead of a whole catalog:
+
+`references/routes/<workflow>.md` — e.g. `routes/product-launch-video.md`,
+`routes/general-video.md`, `routes/remotion-to-hyperframes.md`.
+
+The same file carries that route's interview entry (must-haves, conditionals, deferred
+asks, run-shape), so confirming a route is exactly one read.

package/dist/assets/design/skills/hyperframes-animation/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: hyperframes-animation
+description: "All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic."
+---
+
+# HyperFrames Animation
+
+All motion knowledge in one skill: **rules** (atomic recipes), **blueprints** (multi-phase scene templates), **transitions** (scene-to-scene), **techniques** (broader motion-design patterns), and **adapters** (per-runtime APIs).
+
+For the composition contract (data attributes, sub-compositions, determinism) see `hyperframes-core`.
+
+## Default: compose atomic rules
+
+Pick 2-4 rules from `rules-index.md`, glue them together with a single paused GSAP timeline, done. This is faster and produces less code than starting from a blueprint.
+
+## Load a blueprint when
+
+- The scene matches an existing pre-designed multi-phase template (brand-reveal, social-proof, etc.) and reusing its phase pipeline saves real authoring time
+- You want runnable ground-truth code for a complex 4-5 phase choreography
+
+Blueprints live in `blueprints-index.md`. Each entry points to `blueprints/<id>.md` (recipe). Do not read it speculatively; load it when you've already decided you need scene-level orchestration.
+
+## Routing
+
+| Want to…                                                                       | Read                                                |
+| ------------------------------------------------------------------------------ | --------------------------------------------------- |
+| Pick an atomic motion pattern by trigger / tag                                 | `rules-index.md`                                    |
+| Read one rule's full HTML / CSS / GSAP recipe                                  | `rules/<name>.md`                                   |
+| Pick a multi-phase scene template                                              | `blueprints-index.md`                               |
+| Read one blueprint's full recipe                                               | `blueprints/<id>.md`                                |
+| Author a scene transition (CSS-driven, between two clips)                      | `transitions/overview.md`, `transitions/catalog.md` |
+| Look up a broader motion-design technique                                      | `techniques.md`                                     |
+| Motion blur — shutter smear on an element, and when not to use it              | `references/motion-blur.md`                         |
+| Analyze an existing composition's animation map                                | `scripts/animation-map.mjs`                         |
+| GSAP API — timeline / tweens / position parameters                             | `adapters/gsap.md`                                  |
+| GSAP — drop-in effect recipes                                                  | `rules/gsap-effects.md`                             |
+| GSAP — transforms / perf                                                       | `adapters/gsap-transforms-and-perf.md`              |
+| GSAP — eases / stagger                                                         | `adapters/gsap-easing-and-stagger.md`               |
+| GSAP — timeline / labels                                                       | `adapters/gsap-timeline-and-labels.md`              |
+| Lottie / dotLottie (After Effects exports, `window.__hfLottie`)                | `adapters/lottie.md`                                |
+| Character animation (walk cycle, mascot, jointed puppet, gestures)             | `adapters/lottie.md` → Characters                   |
+| Three.js / WebGL (3D scenes, `AnimationMixer`, `hf-seek`)                      | `adapters/three.md`                                 |
+| Anime.js (`window.__hfAnime`)                                                  | `adapters/animejs.md`                               |
+| CSS keyframes (`animation-delay` / `play-state` / `fill-mode`)                 | `adapters/css-animations.md`                        |
+| Web Animations API (`element.animate()`, `currentTime` seek)                   | `adapters/waapi.md`                                 |
+| TypeGPU / WebGPU (`navigator.gpu`, WGSL, compute pipelines)                    | `adapters/typegpu.md`                               |
+| HTML-as-texture + WebGL/GLSL post-fx (capture live DOM via `drawElementImage`) | `adapters/html-in-canvas-patterns.md`               |
+| Named text-animation effects (24 IDs via external `animate-text` skill)        | `adapters/animate-text.md`                          |
+
+## Picking a runtime
+
+- **GSAP** is the default for 95% of motion work — covers timeline orchestration, transforms, easing, stagger. All atomic rules in this skill are GSAP-based.
+- **Lottie** when an asset has its own pre-baked timeline (typically After Effects exports), including characters that walk, gesture or react.
+- **Three.js** for 3D scenes, camera motion, shader-driven visuals.
+- **Anime.js** for lightweight tweening when GSAP is overkill.
+- **CSS** for simple repeated motifs, decoration, shimmer — no JavaScript animation cost.
+- **WAAPI** for native browser keyframes without a GSAP dependency.
+- **TypeGPU / WebGPU** for GPU-rendered canvases (particles, liquid glass, custom shaders).
+
+Multiple runtimes can coexist in one composition. Each registers its instances on the runtime-specific global so HyperFrames can seek all of them in one pass.
+
+## Critical Constraints
+
+**Prerequisite: `hyperframes-core` → Non-Negotiable Rules** (single paused timeline, `data-duration` governs length, no `Math.random` / `Date.now` / `performance.now`, no `repeat: -1`, no page-load `gsap.set` on later-scene clips, no `display` or raw `visibility` tweens, and no timeline construction inside `async` / `setTimeout` / `Promise`). GSAP `autoAlpha` and zero-duration visibility sets at explicit timeline boundaries remain allowed by core. Use those exceptions only on non-clip elements or wrappers inside a clip; the framework owns `.clip` lifecycle. Don't restate the full contract here.
+
+Animation-craft additions on top of core's contract:
+
+- **Pre-calculated layout constants** — never derive positions from `getBoundingClientRect()` at tween time. Tween-time DOM measurements desync because the renderer samples in parallel; compute coordinates once at composition setup and reuse.
+- **Spatial motion uses GSAP transform aliases only** (`x`, `y`, `scale`, `rotation`). Core's allowlist also permits `opacity` / `color` / `backgroundColor` / `borderRadius` for non-spatial property tweens — but never `width` / `height` / `top` / `left` for layout changes.
+
+## Scripts
+
+```bash
+node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
+  --out <composition-dir>/.hyperframes/anim-map
+```
+
+Reads every GSAP timeline registered on `window.__timelines`, enumerates tweens, samples bboxes, computes flags, outputs `animation-map.json`. Use it to audit choreography (dead zones, stagger consistency, lifecycle warnings) after authoring.
+
+`animation-map.mjs` resolves helper packages from the current project first, then can bootstrap the bundled HyperFrames package version. Set `HYPERFRAMES_SKILL_PKG_VERSION=<version>` only when running the skill outside the bundled CLI/skill install and you need to pin that bootstrap version explicitly.
+
+## See Also
+
+- `hyperframes-core` — composition structure, data attributes, sub-compositions, deterministic render contract
+- `hyperframes-creative` — palettes, typography, narration, beat planning (non-animation creative direction)
+- `hyperframes-cli` — `freecodego_design_lint / check / snapshot / preview / render`

package/dist/assets/design/skills/hyperframes-animation/adapters/animate-text.md

@@ -0,0 +1,64 @@
+# Text Effects — Reference
+
+For deterministic text-animation specs (e.g., `typewriter` at exact `240ms / 46ms stagger / steps(1, end) easing`), this skill defers to the separate **`animate-text`** skill maintained by Pixel Point at [github.com/pixel-point/animate-text](https://github.com/pixel-point/animate-text). It provides a catalog of 24 named text effects with portable contracts and per-library implementation recipes (GSAP, Anime.js, WAAPI).
+
+**We do NOT ship the catalog inside this repo.** Pixel Point's `animate-text` is the source of truth; vendoring its files here would violate the upstream's licensing (no explicit license declared upstream as of this writing). Loading the skill separately keeps the legal picture clean while giving you the same catalog.
+
+## How to use it
+
+When a beat needs a deterministic text animation, load the upstream skill alongside this one:
+
+```bash
+# In your project root, install the upstream skill into .agents/skills/
+npx skills add pixel-point/animate-text
+```
+
+Or in a skill-aware agent runtime, the skill is invoked by name:
+
+```
+/animate-text
+```
+
+Once installed, the specs live at:
+
+```
+.agents/skills/animate-text/assets/effects/<id>.json   # per-library implementation recipe
+.agents/skills/animate-text/assets/specs/<id>.json     # portable motion contract
+```
+
+Sub-agents reading those files get exact GSAP timings, easing strings, DOM split rules, and stagger algorithms — no creative invention needed.
+
+## When you don't need the upstream skill
+
+If a beat's text animation is simple enough to describe in prose ("headline fades up word-by-word, 80ms stagger"), implement it inline using the GSAP knowledge already in these skills (`hyperframes-creative` → `references/motion-principles.md` and `references/beat-direction.md`; `hyperframes-animation` → `techniques.md`, entry #4 "Per-Word Kinetic Typography"). The upstream catalog is most valuable when:
+
+- You want a specific NAMED effect across multiple beats (so they feel like one design system, not one-offs)
+- You're choosing between several similar effects (typewriter vs per-character-rise vs bottom-up-letters) and want to see all 24 in one place
+- You need layout-aware effects (`kinetic-center-build`, `short-slide-right`, `short-slide-down`) where parameters alone aren't enough — those ship with custom layout algorithms
+
+## Effect names — vocabulary (do NOT use this as the implementation source)
+
+For convenience while writing storyboards: the upstream skill provides 24 effects. Their IDs are listed here so you can name them in `STORYBOARD.md` even before loading the upstream skill. **The implementation specs are in the upstream skill, not here.**
+
+- **Per-character (7):** soft-blur-in, per-character-rise, typewriter, bottom-up-letters, top-down-letters, stagger-from-center, stagger-from-edges
+- **Per-word (8):** per-word-crossfade, spring-scale-in, shared-axis-y, blur-out-up, kinetic-center-build, short-slide-right, short-slide-down, depth-parallax-words
+- **Per-line (2):** mask-reveal-up, line-by-line-slide
+- **Whole element (7):** micro-scale-fade, shimmer-sweep, fade-through, shared-axis-z, scale-down-fade, focus-blur-resolve, shared-axis-x
+
+For descriptions, durations, easing curves, and the per-library recipes: load `/animate-text` and read its own catalog page.
+
+## In the storyboard
+
+Every text element in every beat can name an effect by ID, e.g.:
+
+```markdown
+**Text Animations:**
+
+- Main headline: `kinetic-center-build`
+- Eyebrow label: `soft-blur-in`
+- Body copy 3 lines: `mask-reveal-up`
+```
+
+Sub-agents implementing the beat will load `/animate-text` if it's not already loaded, then read the spec for each named effect from the upstream skill's files.
+
+If the upstream skill isn't available (offline build, network restrictions, agent runtime that doesn't support skill loading), sub-agents fall back to implementing the effect from the description alone — using GSAP knowledge plus the effect ID as a description of intent (e.g., "typewriter" = per-character stepped reveal with no interpolation).