hyperframes 0.8.184 → 0.8.185

package/dist/skills/hyperframes/references/captions.md

@@ -0,0 +1,46 @@
+# Captions
+
+## Words and timings
+
+- `npx hyperframes transcribe <file> --json` and a HeyGen voiceover (`/media-use`) give every word's start and end. Work from those as `[{ "id": "w0", "text": "Hello", "start": 0.0, "end": 0.5 }, …]`.
+- Local transcription defaults to `small.en`, which **translates** non-English speech into English. Pass the model: `npx hyperframes transcribe <file> --model small.en` for English, `--model small --language <code>` otherwise, `--model medium.en` for speech over music. It writes `assets/transcript.json` (its JSON names the path) and overwrites it on the next run; `--to srt` or `--to vtt` writes a sidecar.
+- For Chinese, Japanese and other unspaced scripts, local transcription returns a whole sentence as one "word", sometimes in the other script (Traditional for Simplified speech). Split each segment's text into short phrases and spread its time across them by character count; check the characters against what is said.
+- Whisper invents "Thank you." over silence and repeats lines over a silent tail: drop words that start inside a final silence (`silencedetect=noise=-35dB:d=0.6`; real speech sits around −16 to −26 dB).
+- Never put two words in one timed entry, and match transcript words to caption words by position, not text, or a repeated word takes the wrong time.
+- Read the transcript before using it. More than 20% `♪` or `�` tokens, or nonsense words, means it failed: retry with a larger model, or take lyrics from the person. Drop non-word tokens before building groups.
+
+## Structure
+
+- One sub-composition host with `data-track-kind="captions"` holds every caption group, so Studio shows them on one captions track.
+- Ready-made styles: `npx hyperframes catalog --tag caption-style --json`. An installed one is source you can restyle.
+
+## Groups
+
+- 2–3 words for high energy, 3–5 conversational, 4–6 calm. Break at a sentence end, a pause of 150 ms or more, or the word limit.
+- One group visible at a time. A group opens at or before its first word's start and closes at or after its last word's end. A caption at exactly 0 s looks pre-existing: start 0.1–0.3 s in.
+- Every group ends with a hard kill after its exit, or a stale group can stay on screen:
+
+```js
+tl.to(group, { opacity: 0, duration: 0.12, ease: "power2.in" }, end - 0.12);
+tl.set(group, { opacity: 0, visibility: "hidden" }, end);
+```
+
+`tl.set` is an instant flip, so setting `visibility` on the group is fine; never tween it on a `.clip`.
+
+## Fit and place
+
+- Size each group to fit: `window.__hyperframes.fitTextFontSize(text, { fontFamily, fontWeight, maxWidth })` returns `{ fontSize }`. Defaults: `maxWidth` 1600 landscape, 900 portrait; base 78, minimum 42, step 2. When a word scales up for emphasis, divide `maxWidth` by that scale.
+- A full-width absolute container, centred with text alignment. Never `left: 50%; transform: translateX(-50%)`, which clips at the frame edges.
+- `overflow: visible`, not `hidden`, which cuts off scaled words and glows.
+- Landscape: 80–120 px from the bottom. Portrait: about 600–700 px from the bottom. Never over the speaker's face; inside the 80% title-safe box.
+- Position each group absolutely. In a flex column a group hidden with `visibility: hidden` still takes space, so the next one lands lower. In a stack that accumulates, groups in one block share one exit time, or the stack reflows.
+- Fade the group or its words, not both: the opacities multiply and read as a pop. A gradient or `background-clip: text` fill goes on the inner text span, not the transformed container.
+- Over footage, choose the blend by the brightness (0–255) behind the text: under 60 `screen`, 60–180 `overlay`, over 180 `normal` with opaque colour. Plain subtitles above brightness 60 get a scrim sized to the text (30–40%), never a full-width bar.
+- Footage may already carry burned-in subtitles only mid-clip: scan a 1 fps contact sheet before placing captions.
+
+## Text behind the speaker
+
+- Stack the video, then the captions, then a cutout of the person from `npx hyperframes remove-background` (`/media-use`), ordered by `z-index`. Shake or punch in the video and the cutout together in one wrapper.
+- `check` treats a `<video>` as opaque across its whole box, so a WebM cutout fails every caption behind it with `text_occluded`: put `data-layout-allow-occlusion` on the cutout and judge from `snapshot`.
+- A big word behind the head reads best 30–55% covered: under about 15% it floats, over about 65% it is eaten. Re-lay out when a content word is 80% covered, or two adjacent words 50% each. Measure the rendered word boxes against the matte over each caption's own time window (heads move: one clip went from y=224 to y=96 in 8 s); estimates from character widths were wrong both ways.
+- The matte model drops mic arms, lets large rigs near the body leak in, and flickers on held objects. Its first run downloads 168 MB, and it runs at about 2 fps at 1080p on CPU.

package/dist/skills/hyperframes/references/film.md

@@ -0,0 +1,47 @@
+# Films from a source: measured facts
+
+What is specific to HyperFrames, or was measured on shipped films, when one video is made from a website, a script, a pull request, a music track, a real place or a short motion brief. The story comes first, from `story.md`; the shape of each kind of film is in `types/`. Motion craft is in `motion.md`, look in `look.md`, sound in `sound.md`, captions in `captions.md`.
+
+## Script and pacing
+
+- TTS reads about 2.2 words a second. Keep a scene to about 19 words (9 s); at most two scenes may reach 26 words (12 s). 30–90 s is about 155 words or fewer; a whole film about 400 at most.
+- A voiceover longer than its visuals makes the visuals pad with idle drift. Trim the script; never stretch the motion.
+- Everything on screen in the first quarter of a scene, then frozen, reads as a slideshow. Reveal each piece when the voiceover names it, across the back half of the scene; write the voiceover as separate phrases so it has cue points.
+- Up to about six short scenes, build them yourself in one context (about 9 min for five, against about 21 min split across sub-agents). Beyond that, give each worker two or three scenes and start them all at once; a second wave nearly doubles the time.
+
+## From a website
+
+- `npx hyperframes capture <url> --json` writes `screenshots/full-page.png`: a 1x plate of the whole page, taken after the scroll pass with sticky and fixed elements made static, pixel-exact for a 1920-wide viewport travelling down it. It is skipped above 16384 px tall (use `scroll-*.png`); pushing in past 1:1 needs its own 2x capture of that region.
+- To show the site as it is, use its screenshots. Rebuilding the page in HTML drifts from the real layout; rebuild only the part that moves, or overlay captured assets at measured positions.
+- `--capture-budget` (default 120000 ms) bounds work after navigation; `--timeout` bounds navigation only. Videos are not downloaded: `capture --video <dir> --list`, then `--index N`. `asset-descriptions.md` has vision captions only when `OPENROUTER_API_KEY`, `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set.
+- "very little text content" with an empty asset catalog means the capture is unusable even when it says `ok: true`. A `logo-*.svg` name is a guess from page structure, not proof.
+- Brand tokens: link blue `#0000EE` and status reds and greens are never the accent; the accent is the colour that recurs across the most roles. Icon fonts (Font Awesome, icomoon, webflow-icons) are never the display or body face; a captured monospace goes to the mono role. Use only weights the brand font ships, or 600/700 render as fake bold. Every preset has a light ground: for a dark brand, swap ground and ink.
+- Capture keeps each `@font-face` rule, `unicode-range` subsets included, in `extracted/page.html`; copying the font files alone loses which characters each covers. Name copied fonts by family, weight and style, or an upright and an italic "Regular" collide.
+
+## From a pull request
+
+- `gh pr view --json files` stops at about 100 files: page `gh api repos/{owner}/{repo}/pulls/N/files`.
+- The PR author only opened it: credit commit authors, by commit count (`commits[].authors[]`); skip bots, lockfiles and `dist/`. Reviewers come as logins; names via `gh api users/<login> --jq .name`. TTS reads `@handles` aloud, so speak names.
+- Never invent a version. Use the first non-draft release published at or after the merge; else the default branch's `package.json` version as "unreleased"; else only the PR URL.
+- Length from size (additions + deletions), as a ceiling: ≲50 lines 20–40 s, 50–200 40–70 s, 200–600 70–110 s, ≳600 lines or 25+ files 110–180 s.
+- Show 2–4 hunks of 4–12 lines; counts like +N/−M go on a stat card, not into the voiceover.
+- The `code-*` registry blocks (`npx hyperframes catalog --query code --json`) are 1920×1080 scenes driven by `window.__TOKENS` (Shiki tokens, `github-dark`; `fontStyle` bit 1 italic, bit 2 bold) and `window.__BLOCK` (`{id, effect, seq, line?, duration}`). `code-diff` and `code-morph` need at least two states; `code-highlight` counts lines from 0 and `code-scroll` from 1; `code-typing` types at a fixed speed, so check characters × speed against the scene's duration. They reserve no caption band: inset the panel when captions are on.
+
+## On music
+
+- Library music, HeyGen's included, comes as 15–30 s loops: loop the bed to the film with a 0.4 s fade-in and a 1.5 s fade-out. A track whose opening is a quiet build drains a short film: start from a stronger later section.
+- Trust beat times only on rhythmic stretches; on calm music the tracker invents a metronome, often at double tempo (`npx hyperframes beats` reports `bpmConfidence`). Cut there on phrase and energy changes; `npx hyperframes audio --only sections,onsets,moments --json` finds them.
+- A move that must land on a hit starts 40–190 ms early; a reaction starts 0–45 ms after. The hit itself is a 0 ms `tl.set`: easing a hit kills it. Scenes tile the track with no gaps.
+- A word meant to be read holds at least one beat. Any single treatment goes stale after about 6 s: lengthen a section with a hold or a new treatment, never by slowing tweens. On rhythmic sections give footage one clip per strong beat; on calm ones one slow push from 1.0 to 1.08.
+
+## Maps and real places
+
+- A real place (a city, a building, a route, a zoom from the globe to a street) is shown on real imagery. Vector outlines from Natural Earth or GeoJSON read as a diagram and lose the place; keep them for borders and labels drawn on top.
+- Live tiles change between renders, so bake the camera move to video with `scripts/bake-basemap.mjs` (MapLibre over Esri satellite or Carto tiles; writes an all-intra MP4 and `<NAME>-coords.json`). From space down to a street: `PROJECTION=globe FROM="lng,lat" CENTER="lng,lat" ZSTART=1.85 ZEND=16` (Earth in a starfield turns from FROM to CENTER, then dives); `--help` lists the rest. It needs network for the tiles and takes well under a second a frame, so bake once, keep the MP4, and run one bake at a time. Draw borders, pins and labels as a live SVG from those coordinates, animating them only while the camera holds.
+- Credit the imagery on screen ("Esri, Maxar, Earthstar Geographics" or "© CARTO, © OpenStreetMap") in small type on a soft dark backing, so it holds contrast over bright tiles; mark it `data-layout-ignore` so the type floor in `check` skips it.
+
+## Short motion pieces
+
+- Kinetic type takes 3–7 English words or 4–12 Chinese characters per scene. A count-up runs 1.2–1.6 s, then holds, landing on a downbeat or a hard stop.
+- A highlighter that wraps across lines: tween a custom property on a `background-size` band with `box-decoration-break: clone`. `getTotalLength()` can return 0 before layout; give line draw-ons a fallback.
+- A point in an image guessed directly misses by 16–24% of the frame. `scripts/locate.mjs` narrows it with a numbered 9×9 grid, then 6×6 on the crop, then a check render (about 2% error).

package/dist/skills/hyperframes/references/format.md

@@ -0,0 +1,157 @@
+# Composition format
+
+The detail behind the contract in `SKILL.md`. Full references: `npx hyperframes docs compositions`, `docs data-attributes`, `docs troubleshooting`.
+
+## Shape of a project
+
+```html
+<!-- index.html: a normal document; declares variables, mounts scenes -->
+<html
+  data-composition-variables='[{"id":"headline","type":"string","label":"Headline","default":"…"}]'
+>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="12"
+      data-width="1920"
+      data-height="1080"
+    >
+      <div
+        id="intro"
+        data-composition-id="intro"
+        data-composition-src="compositions/intro.html"
+        data-start="0"
+        data-duration="4"
+        data-track-index="1"
+        data-width="1920"
+        data-height="1080"
+      ></div>
+    </div>
+    <script>
+      window.__timelines["main"] = gsap.timeline({ paused: true });
+    </script>
+  </body>
+</html>
+```
+
+```html
+<!-- compositions/intro.html: everything inside <template> -->
+<template>
+  <style>
+    #root {
+      position: absolute;
+      inset: 0;
+    }
+  </style>
+  <div id="root" data-composition-id="intro" data-width="1920" data-height="1080">
+    <h1 id="headline" class="clip" data-start="0.4" data-duration="3" data-var-text="headline">
+      …
+    </h1>
+  </div>
+  <script>
+    const tl = gsap.timeline({ paused: true });
+    tl.fromTo(
+      "#headline",
+      { opacity: 0, filter: "blur(8px)" },
+      { opacity: 1, filter: "blur(0px)", duration: 0.18, ease: "power4.out" },
+      0.4,
+    );
+    window.__timelines["intro"] = tl;
+  </script>
+</template>
+```
+
+- Give the host, the scene root and the timeline key the same id. A host id that differs from its scene's makes each render wait 45 s per scene, then show static frames. Styles and scripts outside `<template>` are dropped.
+- Size the scene root with `inset: 0`, never hard-coded pixels; the canvas is `data-width` × `data-height`.
+- Keep ids unique across the assembled page (prefix them: `#intro-title`). A scene's timeline can't reach elements outside its file.
+- Use `fromTo`, not `from`, inside a scene: the host re-seeks the scene each time it shows, and `from` records its start state once, so it drifts on seek-back.
+- Never `add()` a scene's timeline to the root's; the runtime drives each scene itself, and nesting seeks it twice.
+
+## Attributes you'll use most
+
+| Attribute                                      | Meaning                                                                                             |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `data-start`, `data-duration`                  | Seconds, local to the file that declares the element                                                |
+| `data-track-index`                             | Studio lane only; paint order is CSS `z-index`                                                      |
+| `data-track-kind`                              | `graphics` or `captions` on scene hosts (video and audio come from the tag)                         |
+| `data-composition-src`, `data-variable-values` | Mount a scene file; per-mount variable values (a JSON object)                                       |
+| `data-media-start`                             | Offset into the source media (a trim)                                                               |
+| `data-playback-rate`                           | Constant speed, 0.1–10                                                                              |
+| `data-has-audio="true"`                        | A `<video>` keeps its own sound; a timed `<video>` with neither this nor `muted` fails lint         |
+| `data-volume`, `data-fade-in`, `data-fade-out` | Gain (1 = 0 dB, up to 3.98 = +12 dB) and edge fades; envelopes use `data-automation` (`/media-use`) |
+| `data-link`, `data-sync-origin`                | A video and audio edited as one (see Linked clips)                                                  |
+| `data-hidden`                                  | Hidden in preview and render; reversible                                                            |
+| `data-no-timeline`                             | On the root of a still composition: no timeline to wait for                                         |
+
+## Variables
+
+- Declare an array of `{id, type, label, default}`: the video's own on `index.html`'s `<html>`, a scene or block file's on that file's `<html>` (or root element), where they stay inside each mount. Types: `string` (`placeholder`, `maxLength`), `number` (`min`, `max`, `step`, `unit`), `color`, `boolean`, `enum` (`options: [{value, label}]`).
+- Bind without script: `data-var-text="id"`, `data-var-src="id"` (keep a real fallback `src` on media with audio), `var(--id)` in CSS; for logic, `window.__hyperframes.getVariables()` once at init.
+- Values are an object keyed by id. A host's `data-variable-values` sets one mount; Studio's Variables panel and batch renders set only the root's variables, so to vary a block, change its host's values. Variables can't change the root's `data-duration`.
+
+## Fonts
+
+- Bundled, so they resolve by name: Inter, Montserrat, Outfit, Nunito, Oswald, League Gothic, Archivo Black, Space Mono, IBM Plex Mono, JetBrains Mono, EB Garamond, Playfair Display, Source Code Pro, Noto Sans JP, Roboto, Open Sans, Lato, Poppins. Common system fonts (Helvetica, Arial, Times, Menlo and the like) are swapped for the nearest of these.
+- Any other family needs `@font-face` in the file that uses it, or lint fails `font_family_without_font_face`: `src: url('assets/fonts/x.woff2')` for a file in the project (a capture's own fonts, or one you download there), or `local('Exact Name')` for a font installed on this machine.
+
+## Timing and the timeline
+
+- A clip shows over `[start, start + duration)`: an end state landing exactly on its end is never rendered.
+- Only a composition's root timeline is paused; timelines nested inside it are not. Never `tl.play()`.
+- A scene's clock starts at 0 at its host's `data-start`; media `data-start` is local to its composition. `<video>` / `<audio>` without `data-duration` play their full length; an `<img>` without one lasts 3 s.
+- A host's `data-duration` is the scene's slot: a shorter scene timeline holds its last frame, and a slot shorter than the video goes blank when it ends.
+- Root children with `data-start` are laid out full-frame by the runtime; an untimed full-bleed background needs `position: absolute; inset: 0` or it collapses to nothing.
+- A fill on the composition root is dropped when the video has shader transitions or HDR media; put it on a full-bleed child.
+- `data-start="intro + 0.5"` starts after `intro` ends (spaces required). A typo, a missing id or a cycle silently resolves to 0, so snapshot what you time this way.
+- A clip nested inside another timed element counts its `data-start` from the composition, not from that element, and shows only while that element shows. `timeline` lists it under its parent and warns `never visible` when the windows miss (`lint`: `nested_clip_never_visible`).
+- `npx hyperframes timeline --json` lists every clip by kind with `absStart`, `absEnd`, `file`, `src`, `playbackRate`, `nested`, `host` and `durationSource`: read it instead of opening every file. It reads one level of nesting (a deeper scene shows `children=unread`); `laneError` means a `data-automation` or `data-fx-chain` that doesn't parse.
+
+## Adding media
+
+Write what a Studio drop writes, so the clip behaves like one the person dropped:
+
+- `id`, `class="clip"`, `data-start` (the playhead or the requested time, never a silent 0) and `data-track-index`. Video with sound: `playsinline data-has-audio="true"`; silent footage: `muted playsinline`. Audio: `data-volume="1"`.
+- Images and video fill the frame: `position: absolute; left: 0; top: 0`, width and height equal to the canvas, `object-fit: contain`.
+- `z-index` is the number of top-level clips already in that file plus one.
+- Raise the root's `data-duration` to cover the new clip's end, or it never plays.
+
+## Linked clips
+
+Studio's Detach audio writes a muted `<video>` and an `<audio>` of the same file sharing `data-link` and `data-sync-origin`; Studio moves, trims, splits and deletes them as one.
+
+- Prefer one `<video data-has-audio="true">`; link only when the sound needs its own track, volume or effects.
+- Every member keeps the same `data-start`, `data-duration`, `data-media-start` and `data-playback-rate`; retime them all together.
+- Unlink by removing `data-link` from every member. Leave `data-sync-origin` alone while they are still one source.
+
+## Layout audit opt-outs
+
+`check` measures boxes at sampled times; `overflow: hidden` does not silence a finding. Use the narrowest opt-out:
+
+| Attribute                        | Silences                                                                                                                 |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `data-layout-allow-overflow`     | Overflow on the element and every descendant, including text-clipping checks: keep it on the smallest decorative wrapper |
+| `data-layout-bleed="true"`       | One intentional crop of primary text                                                                                     |
+| `data-layout-allow-overlap`      | Deliberate text layering, on that block only (not inherited)                                                             |
+| `data-layout-allow-occlusion`    | An element meant to cover text                                                                                           |
+| `data-layout-allow-caption-zone` | Intentional copy in the caption band                                                                                     |
+| `data-layout-ignore`             | A decorative element never audited                                                                                       |
+
+## Lint errors you'll meet first
+
+| Rule                                                   | Fix                                                                                                    |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `video_missing_muted`                                  | A timed `<video>` gets `data-has-audio="true"` or `muted`                                              |
+| `gsap_css_transform_conflict`                          | Set the start inside the tween (`gsap.fromTo`) instead of a CSS `transform`                            |
+| `gsap_animates_clip_element`                           | Animate a child of the `.clip`, or its `opacity`                                                       |
+| `video_nested_in_timed_element`                        | Time the `<video>` or its wrapper, not both                                                            |
+| `media_missing_id`, `media_crossorigin_breaks_preview` | Give every `<audio>` an `id`; drop `crossorigin`                                                       |
+| `gsap_timeline_registered_before_async_build`          | Register the timeline at the end of the async callback                                                 |
+| `standalone_composition_wrapped_in_template`           | Only scene files use `<template>`                                                                      |
+| `subcomposition_root_styled_by_class`                  | Style a scene's root as `#root`                                                                        |
+| `subcomposition_blanks_before_host`                    | Make the scene's slot span the time it should show                                                     |
+| `clip_ends_past_root_duration`                         | Raise the root's `data-duration`                                                                       |
+| `linked_clips_out_of_sync`, `linked_clip_orphan`       | Retime every linked member together; unlink from all of them                                           |
+| `sweep_static`                                         | A 3 s+ video with no visible change: spread the motion, or mark a still composition `data-no-timeline` |
+| `missing_data_no_timeline`                             | A root or host with no timeline: add `data-no-timeline`, or every render waits 45 s                    |

package/dist/skills/hyperframes/references/look.md

@@ -0,0 +1,69 @@
+# The look
+
+Left alone, the same brief comes out with the same look run after run, and banning that look only moves it to the next default. Outside input breaks it, in this order: the project's design spec, a real brand, a reference image or film the person gave you, the subject's own world. Settle it before the first scene, as numbers in the LOOK line (below).
+
+## The project's design spec
+
+Read the first of `frame.md`, `design.md`, `DESIGN.md` at the project root that exists; ignore the rest.
+
+- **Frontmatter is normative**: `colors`, `typography`, `spacing`, `components`. Quote hex values, families and weights exactly; never round or invent them.
+- **The prose is intent**: what the look is for, Do's and Don'ts. Follow it for judgment, not values.
+- **Brand, not layout**: hex, fonts, weight relationships and Do's and Don'ts are strict; type sizes, spacing, border weight and decoration are yours to scale for video. A 1px border or a 6% shadow from a web page vanishes on screen.
+
+## From a brand
+
+- A website: `npx hyperframes capture <url> --json` writes screenshots, the copy (`extracted/visible-text.txt`), images, logos, `extracted/tokens.json` (colours, fonts) and `extracted/design-styles.json` under its output folder. Look at the screenshots before choosing anything. A capture that exits non-zero, prints `ok: false` or writes `BLOCKED.md` failed: take no brand data from its partial files.
+- Figma: `npx hyperframes figma tokens <fileKey>` (`/figma`).
+- Images the person attached: take palette and type from what you see.
+
+Use the brand's own fonts when the capture shipped their files or they are bundled (`format.md`); otherwise download the family's `.woff2` into `assets/fonts/` with an `@font-face`, or pick the closest bundled family and say so.
+
+## From a reference
+
+A reference film or image gives its grammar, never its content: shot lengths, how titles enter and leave, the transitions, the palette roles, the type's scale and weight. Snapshot it next to yours (`snapshot --at <t,…> --against ref.mp4`) and write the grammar down, marking what you measured apart from what you guessed.
+
+## Presets
+
+The presets are slide-deck looks: use one when the person names it, or for a deck (`/slideshow`), never as the fallback for a film without a brand. Each folder in `../assets/frame-presets/` holds a `FRAME.md` spec, a `caption-skin.html` and a `frame-showcase.html` contact sheet. To use one, copy its `FRAME.md` to the project root as `frame.md`, then read it as above; its fonts that aren't bundled need `@font-face` files. The two HTML files are reference code: read them for treatments, never mount them.
+
+| Preset              | Look                                                                                           |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| `biennale-yellow`   | Museum catalogue: parchment, deep indigo ink, solar-yellow blooms, Instrument Serif, hairlines |
+| `blockframe`        | Loud neobrutalist: 4px black borders, hard shadows, candy pastels, Inter 900 caps              |
+| `blue-professional` | Consulting restraint: cream canvas, one cobalt accent, Space Grotesk + Inter, tinted cards     |
+| `bold-poster`       | Vintage editorial poster: Shrikhand tilted display, Baskerville, tomato red, double borders    |
+| `broadside`         | Protest poster: ink-black and fire-orange planes, giant lowercase Barlow 900, mono chrome      |
+| `capsule`           | Friendly editorial: every container a pill, cream, nine candy accents, Bodoni Moda             |
+| `cartesian`         | Quiet catalogue: warm-stone palette, Playfair + Inter, taupe hairline grid, compass rings      |
+| `cobalt-grid`       | Two-colour risograph: cream paper, cobalt ink, graph-paper grid, Newsreader serif              |
+| `code-editorial`    | Developer brand book: warm paper, scarce terracotta, EB Garamond, navy code surface            |
+| `coral`             | Bold magazine: coral, ink and cream planes at hard edges, Bebas Neue, giant numerals           |
+| `creative-mode`     | Sparse neobrutalist: cream, 4px ink borders, Archivo Black caps, rationed accents              |
+| `daisy-days`        | Picture book: charcoal outlines, sunny pastels, Fredoka One, hand-drawn ornaments              |
+| `editorial-forest`  | Literary: green, pink and cream, Source Serif display, mono chrome, flat paper                 |
+
+## The LOOK line
+
+With no design spec, the look is the LOOK line of `SPEC.md` (`spec.md`), taken from the brand, the reference or the subject itself: its era, its materials, where it would be shown. Every part is a number (hex, px, %, a named face and weight), the ground and the hero come from a medium rather than from effects, and the BANNED line keeps it off the defaults. Inter, Space Grotesk, Instrument Serif, Geist and JetBrains Mono are where generated design lands; use them when the brand does, not by default. Copy the palette and the faces into the root variables below.
+
+## Video facts
+
+- Full-screen linear gradients on dark grounds band under H.264; use a radial gradient, a solid fill or a solid plus a local glow.
+- An accent at 5% opacity disappears in compression: 15–25% for atmosphere, full saturation for the focal element.
+
+## Make it re-brandable
+
+Declare palette and fonts as variables on the root `<html>` and use them everywhere, so the person can re-brand from Studio's Variables panel:
+
+```html
+<html
+  data-composition-variables='[
+  {"id":"color-ground","type":"color","label":"Background","default":"<ground from the plan>"},
+  {"id":"color-ink","type":"color","label":"Text","default":"<ink from the plan>"},
+  {"id":"color-accent","type":"color","label":"Accent","default":"<accent from the plan>"},
+  {"id":"font-display","type":"string","label":"Display font","default":"<display face from the plan>"}
+]'
+></html>
+```
+
+Reference them as `var(--color-accent)`; point a registry item's colour and font variables at the same values.

package/dist/skills/hyperframes/references/motion.md

@@ -0,0 +1,94 @@
+# Motion
+
+## Motion craft
+
+Measured frame by frame from the official HyperFrames launch films. These are defaults: a reference the person gave, or a Moment that does otherwise on purpose, wins for its own beat.
+
+- **Moves**: a fast move takes 0.3–0.6 s and carries motion blur on its own ease, peaking at its fastest frame: 6–12 px on text-sized elements, 15–20 px full-frame, horizontal-only on a horizontal move. One move is one tween.
+- **Arrive slow, leave clean**: long-tailed ease-outs on arrivals; landing takes longer than leaving. An exit is one smooth motion, never slide, stop, then leave. Entrances that are too snappy read as glitches; slowing the whole video by about a second often fixes it.
+- **Ease by role**: an arrival lands on a long tail (`expo.out`, `power4.out`), a camera move or a colour flood eases both ways (`power2.inOut`), a zoom through or an exit accelerates (`power3.in`). The same `power2.out` at 0.5 s on everything is the flat default that makes a film feel generated. Linear only for rotation, progress and constant speed that is the point.
+- **Springs** are named by damping ratio: 1.0 never bounces, 0.7-0.85 reads premium, 0.4-0.6 playful, under 0.3 a cartoon. Position and size may bounce; opacity and colour never do. GSAP's `elastic.out(1, 0.5)` and `back.out(1.4)` are the nearest built-ins; a closed-form spring of `t` keeps any frame renderable on its own.
+- **Exits** are 40-50% shorter than their entrances. **Overlap**: the next element starts when the previous is 30-50% done; fully sequential looks robotic, all at once looks cheap. **Stagger**: letters a frame apart, words 60-120 ms, list items 40-80 ms.
+- **Beat grid**: frames per beat = fps × 60 / BPM; compute each beat from its index and round it, never add a rounded beat repeatedly (at 128 BPM and 30 fps that drifts 2 frames in 32 beats). Cut on the beat, change the layout on the bar.
+- **Cuts**: cut at the fastest frame of a move, with matching direction and speed on both sides. A click into a new screen is a match cut on the click's rebound; the new screen comes in slightly large and settles.
+- **Titles**: a landed title is dead still; the motion moves to the next element, the camera or the world behind. Vary the entrance within a film, never a fade and slide-up for each:
+  - per word: `blur(6px)` → 0 and opacity 0 → 1 in 0.13 s, 0.067 s apart, no translate;
+  - per word from light grey to ink, 0.07–0.1 s apart, no position change;
+  - the whole line blurring in, 8 px → 0 in 0.13–0.2 s;
+  - per letter for a name, 0.1 s apart, opacity 0.3 → 1 with a slight blur;
+  - behind the subject: the title between the plate and a matte of the person;
+  - one word of the sentence rolling through options like a slot machine, about 0.1 s a roll.
+- **Holds**: a line the viewer must read holds about 0.5 s plus 0.3 s a word, the film's last line at least 2 s; a one- or two-word chapter line may hold 0.4 s. Then exit with a blur-out and fade of 0.13–0.25 s, word by word, or with the scene's move.
+- **Title size**: 4–9% of the frame height, one or two lines; quiet lines at 2.5–4% against hero words that fill 60–90% of the width. One highlighted word in the accent colour, which carries meaning.
+- **Rhythm**: contrast speeds. Montages cut every 0.13–0.8 s; a demo holds one framing for 7–10 s while the UI acts; shots average 1.8–3 s with motion inside them. Hold 0.3–0.75 s before the payoff, which plays at normal speed.
+- **Continuous motion that works**: the product's UI working, footage playing, a character acting, a 3D world turning, a slow orbit of a background stage (3–5° a second).
+- **Defaults that look generated**: breathing, floating or pulsing loops standing in for motion on titles and UI; titles that keep sliding or scaling after they land; a slow creeping scale on a title or a slow push late in a scene; bounce on UI; click rings; every scene entering the same way; every element fading and sliding up. A character's idle and overshoot are acting, not these (`types/character.md`).
+
+## Transitions with a cause
+
+Use 3–5 kinds in a film, each caused by something on screen. Hard cuts belong inside a scene (punch-ins); at most a third of the seams between beats are hard cuts, and worlds never crossfade into each other. Measured on the official films:
+
+| Transition               | How it is built                                                                                                                                                                     |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Zoom through a button    | the camera tracks to the button with blur (0.6 s), then the button scales from ~8% to ~250% of the frame in 0.35 s, strong ease-in; its fill becomes the next frame                 |
+| Object becomes the world | a pill or card grows past the frame in 0.65 s, ease-in-out, its radius shrinking; what was around it blurs ~15 px and fades in 0.3 s; the new content fades in while it still grows |
+| Morph                    | one container widens into the next (icon card → prompt box, ~110 → ~880 px in 0.2 s `power3.out`) with a horizontal blur 12 → 0                                                     |
+| Carry across             | the result shrinks 1 → 0.6 with blur peaking at 6 px mid-move and lands inside the next app as it builds around it                                                                  |
+| Colour flood             | the hero object stays while the whole ground changes colour in ~0.4 s `power2.inOut`                                                                                                |
+| Whip                     | a horizontal or vertical smear of 0.13–0.3 s; the arriving element lands blurred and sharpens in ~0.13 s                                                                            |
+| Iris from the click      | `clip-path: circle()` opens from the clicked point onto the next world in 0.15 s                                                                                                    |
+| Dip cut                  | the outgoing frame darkens ~40% for 3 frames before a hard cut, so the cut reads as meant                                                                                           |
+| Blur swap on one stage   | out: opacity → 0 with ~8 px blur in 0.13–0.2 s; in: blur → 0 in 0.13 s; the ground never cuts                                                                                       |
+
+Registry versions: `npx hyperframes catalog --tag transition --json`.
+
+| The person says        | Change                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------ |
+| "too fast"             | Slow every zoom and pan to 0.7× of its speed, nothing else                     |
+| "speed this up"        | Speed the content and shorten the beat by the same amount; later beats move up |
+| "the titles move"      | Land them, then hold them dead still until they leave                          |
+| "it feels like slides" | Enter the next scene through an object on screen; cut a move mid-flight        |
+
+## The right mechanism
+
+| Request                                 | Mechanism                                                                                                                  |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Punch-in, zoom, pan, Ken Burns, reframe | Tween `scale` and `x`/`y` on a wrapper inside the clip, never on the timed media element; chain the states on one timeline |
+| Crop or mask reveal                     | Tween `clip-path` or a mask on an inner wrapper; source time is untouched                                                  |
+| Constant speed change                   | `data-playback-rate` on the media, 0.1–10 (picture and pitch-preserved sound)                                              |
+| Speed ramp                              | A `rate` lane in `data-automation` on the media (`t` in clip seconds, `v` 0.1–10); it overrides the constant rate          |
+| Hold or freeze                          | Hold a final frame or a finished scene; a freeze mid-source needs a still exported first and placed as its own clip        |
+
+Ready-made moves: `npx hyperframes catalog --tag camera --json`, or `catalog --query "<the move>" --tag motion-primitive --json`.
+
+## Seeing motion
+
+The whole-film pass (beat sheet, cuts, phone width, the craft warnings) is `review.md`. For one move:
+
+- `npx hyperframes keyframes --json [--selector '#id'] [--runtime all]` lists keyframes and motion paths (GSAP, CSS, anime.js): property, time, value, ease.
+- `npx hyperframes keyframes --shot motion.png --selector '#id'` draws the real element's samples over time with its path (9 samples; `--samples N`). `--layout strip` for motion in place, `--from`/`--to` for one stretch, `--angle iso|top|side|'yaw,pitch'` for 3D, `--ghost` for a `<canvas>`.
+- `npx hyperframes snapshot --range 2,4 --frames 8` samples one stretch; `--composition <id>` samples one scene; `--at <t,…>` exact instants; `--zoom '#id'` a sharp crop; `--angle iso` depth and overlap.
+- Against a reference video: `snapshot --at <t,…> --against ref.mp4` writes a side-by-side sheet.
+- Assert intent instead of eyeballing it: a `<name>.motion.json` next to the composition makes `check` verify it on the seeked timeline, as errors (`motion_appears_late`, `motion_out_of_order`, `motion_off_frame`, `motion_frozen`):
+
+```json
+{
+  "assertions": [
+    { "kind": "appearsBy", "selector": "#headline", "bySec": 0.5 },
+    { "kind": "before", "a": "#headline", "b": "#cta" },
+    { "kind": "staysInFrame", "selector": ".card" },
+    { "kind": "keepsMoving", "withinSelector": ".scene" }
+  ]
+}
+```
+
+## Common faults
+
+| Symptom                          | Usual cause                                                                                                                                    |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Blank or frozen scene            | Timeline registered before an async build finished, `visibility` tweened on a `.clip`, or a host id that differs from its scene's timeline key |
+| Stutter or drift between renders | Layout measured in `onUpdate`, `requestAnimationFrame` or clock time; two timelines on one property                                            |
+| Jump at a cut                    | Outgoing and incoming states differ at the seam: snapshot just before and after it                                                             |
+| Ease looks off at a handoff      | Speeds don't match across the seam: mirror the ease (`power3.in` out, `power3.out` in)                                                         |
+
+Studio's keyframe diamonds and motion-path handles rewrite the GSAP script in the composition file, so the person may have changed motion since you wrote it.

package/dist/skills/hyperframes/references/overlays.md

@@ -0,0 +1,39 @@
+# Cards over talking-head footage
+
+Designed cards, lower thirds and split layouts over a person speaking. Placement numbers are for 1920×1080 and 1080×1920; scale others.
+
+## Where the video sits
+
+| Layout                       | Landscape (x, y, w×h) | Portrait (x, y, w×h) |
+| ---------------------------- | --------------------- | -------------------- |
+| Split, video beside the card | 960, 0, 960×1080      | 0, 960, 1080×960     |
+| Stack, video above           | 14, 14, 1892×548      | 0, 0, 1080×844       |
+| Overlay                      | full frame            | full frame           |
+
+Picture-in-picture, 28 px from the edges (bottom-right: y = H − h − 28):
+
+| Canvas    | Source | Rectangle         |
+| --------- | ------ | ----------------- |
+| Landscape | 16:9   | 1432, 28, 460×258 |
+| Landscape | 9:16   | 1644, 28, 248×440 |
+| Portrait  | 16:9   | 690, 28, 360×203  |
+| Portrait  | 9:16   | 738, 28, 312×555  |
+
+- Card zones: a lower third is the bottom 30%; a side panel the right 42% (landscape) or bottom 40% (portrait). Glass card slots: 48, 460, 660×540 landscape; 24, 1280, 1032×564 portrait.
+- Portrait type is landscape × 1.3 (titles × 1.35, stats × 1.4); padding drops from 40–64 px to 24–36 px.
+- Size a rectangle to its source's aspect: `object-fit: cover` crops a portrait source in a landscape box.
+
+## Timing
+
+- Cards fade in over 0.4 s (`power2.out`) and out over 0.35 s (`power2.in`). Re-frame the video (0.5–0.7 s) only in a gap between cards; move it with transforms on a wrapper, not `left`/`top`/`width`/`height`.
+- A static card goes dead after about 8 s; past about 15 s it needs a staged reveal. As a starting density: one card per 6–8 s under a minute, 8–12 s up to 3 min, 12–20 s up to 10 min.
+- A transcript's last word can end past the media: clamp card ends and the root `data-duration` to the file's ffprobe length, or the render ends in black.
+
+## Pitfalls
+
+- Lower-third, overlay and picture-in-picture scenes need a transparent root, or they hide the speaker.
+- Glass over bright footage goes white on white: put a dark scrim behind it (about `rgba(0,0,0,.55)` fading out from the top, `.72` at the bottom) and a dark glass base such as `rgba(15,16,22,.78)` with `backdrop-filter: blur(22px)`.
+- More than 3 timed elements on one track warns `timeline_track_too_dense`: give each chapter its own sub-composition.
+- Footage with keyframes more than about 1 s apart freezes on seek: re-encode with `-g <fps>`.
+
+Text behind the speaker (a caption between the footage and a cutout of the person): `captions.md`.

package/dist/skills/hyperframes/references/plugin-installation.md

@@ -7,10 +7,10 @@ That directory is `<PLUGIN_ROOT>`. If none exists, this is a standalone skill;
 follow the normal installation and freshness instructions.
 
 For a plugin installation, these rules replace the standalone update commands
-in every workflow and reference:
+in every skill and reference:
 
 - Do not run `hyperframes skills update`, `skills check`, or `npx skills add`.
-  The agent's plugin manager owns installation and updates. Read the workflow at
+  The agent's plugin manager owns installation and updates. Read the skill at
   `<PLUGIN_ROOT>/skills/<name>/SKILL.md`; report a missing bundled skill instead
   of downloading a different release. Resolve all skill references inside this
   bundle, even if a standalone copy is also installed. Claude exposes the router
@@ -35,7 +35,7 @@ in every workflow and reference:
   version alone does not freeze those inputs.
 - Treat the plugin directory as read-only. Put outputs and temporary work in the
   project or a temporary directory. Pass this plugin root and launcher convention
-  to any delegated workflow so it does not fall back to global skills.
+  to any delegated agent so it does not fall back to global skills.
 
 To get newer skills, use the client's plugin update flow and reload the session.
 Do not silently update an installed plugin during a video task.

package/dist/skills/hyperframes/references/review.md

@@ -0,0 +1,51 @@
+# Review
+
+You wrote the timeline, so you know what happens; the viewer sees it once, at full speed, often on a phone. Review is how you see the film as they will: as a harsh motion director, not a proud author. `check` catches what is broken; this pass catches what is weak. Run it after `check` passes, on every new film and on any edit that changes timing or layout, before you reply or render.
+
+## 1. Measure, then look
+
+1. `npx hyperframes check --json`. Besides errors it warns on craft it can measure: a line on screen too briefly to read (`line_unread`), more than 3 s with nothing changing (`dead_stretch`), text under 2.6% of the frame's short side (`text_below_floor`), an empty first frame (`first_frame_empty`, the thumbnail on social players), a film over 15 s with no sound (`film_silent`). A warning is a question, not a rule: fix it, or keep it on purpose and say why in the note (a deliberate hold carries `data-hold`).
+2. `npx hyperframes snapshot --review` writes three sheets: each scene just after it starts and at its middle, plus each `data-beat`, a strip across every cut (−0.2 s to +0.2 s), and the beat frames at phone width (360 px). Open all three.
+3. Motion between the beats: `snapshot --range START,END --frames 8` around the hero move and the payoff; `keyframes --shot` for a path that must arc or land.
+4. The rendered file: `npx hyperframes audio <video> --json` shows whether sound is there, where it hits and how loud it is. You cannot hear it; say so.
+
+Trust the numbers over your eye where they disagree: a clipped label or a 0.6 s line looks fine on a contact sheet.
+
+## 2. What to look for
+
+First, describe each beat frame in one sentence as a stranger would, naming every object; an object you would have to explain ("those bars are mirrors") is a P0. Then read the beat frames in order: do they tell a story a stranger follows, each one causing the next? Compare each with its shot in `SPEC.md`; what does not match is a note. Then name every default the frames show (`spec.md` "BANNED by default", or one not on the list yet), add each to the BANNED line, and fix them before anything else.
+
+Then go through the sheets once per question:
+
+| Question                      | What it catches                                                                                                                                    |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Does it read as what it is?   | A shape that reads as another object, a material that reads as plastic, a product screen that reads as a mockup, a face or mascot that reads wrong |
+| Does the subject separate?    | Subject and ground too close in value, two focal points in one frame, the eye with nowhere to go                                                   |
+| Framing and contact           | Crops, text at the edge or under platform UI, collisions at a seam, things floating that should touch                                              |
+| Timing as a first-time viewer | A read shorter than its words (`story.md` §6), something that pops on with no move, a jump at a cut, everything moving at once on one curve        |
+| Tells                         | Which items of `story.md` §8 and `motion.md` "Defaults that look generated" are on screen                                                          |
+| The pictures alone            | With the words covered, do the beat frames still tell the storyline?                                                                               |
+| The phone sheet               | Can every line meant to be read be read at 360 px?                                                                                                 |
+
+## 3. Notes and fixes
+
+Write each problem as one line: `t=4.2s · where · problem → exact change · what stays`. Rank them:
+
+- **P0** breaks the read or the contract: unreadable, wrong, broken, a tell in the hero shot.
+- **P1** weakens the film: a dead stretch, a soft payoff, a seam that jumps.
+- **P2** polish.
+
+Fix every P0 and the P1s worth their time: text first, then timing, then detail. Then snapshot only what you changed, once. A second pass only when a P0 is still open. Never score the film out of 10: a score finds nothing to fix. When a fix does not hold, snapshot the frames on either side of the problem, list every difference, and change only the line that causes it. A film that feels busy: remove a third of the motion and keep the moves that lead the eye.
+
+A fresh pair of eyes, when your host can start a sub-agent: give it only `STORYBOARD.md` and the three sheets, ask for P0 and P1 lines in the format above, and keep editing to yourself. Commit or copy the project before you fix, so a fix that makes things worse can be rolled back.
+
+## 4. The delivery note
+
+Write `REVIEW.md` at the project root and put its short form in your reply:
+
+- the creative calls you made, and the storylines you did not build;
+- what you measured and what you only looked at; what nobody checked (the sound was measured, not heard);
+- the weakest shot, and what you would change with more time;
+- warnings you kept on purpose, and why.
+
+The next turn reads it before changing anything.

package/dist/skills/hyperframes/references/runtimes.md

@@ -0,0 +1,43 @@
+# Animation runtimes
+
+HyperFrames seeks each frame on its own, so motion must be a function of time, never of the previous frame. Full GSAP reference: `npx hyperframes docs gsap`.
+
+## GSAP facts that bite
+
+- Register the timeline last. Building inside `document.fonts.ready.then(…)` or another async callback is fine if you register at the end of it; registering first renders blank (`gsap_timeline_registered_before_async_build`).
+- Place tweens at absolute seconds (`tl.to(el, {…}, 2.4)`). Set start states in the tween (`fromTo`), not in CSS.
+- Measure layout once before building tweens, never inside `onUpdate`.
+- Finite repeats only: `repeat: Math.max(0, Math.floor(duration / cycle) - 1)`.
+- Seed randomness with a small PRNG (mulberry32).
+- A scene's timeline can't reach elements outside its file, and two timelines must not animate the same property of one element.
+- Transforms on a `<span>` need `display: inline-block` or `block`.
+- Text that must fit a width: `window.__hyperframes.fitTextFontSize(text, { fontFamily, fontWeight, maxWidth })` returns `{ fontSize }`; `window.__hyperframes.pretext` measures text without a reflow.
+
+## Other runtimes
+
+| Runtime                      | Use for                           | How HyperFrames drives it                                                                        |
+| ---------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ |
+| CSS `@keyframes`             | Simple loops and decoration       | Found automatically; finite iterations, `animation-fill-mode: both`, `data-start` on the element |
+| WAAPI                        | Native keyframes                  | `element.animate(…, { fill: "both" })` then `pause()`; times are document time, so use `delay`   |
+| Lottie / dotLottie           | After Effects exports, characters | `autoplay: false`, always set `loop`, push the instance to `window.__hfLottie`                   |
+| anime.js v4                  | Existing anime code               | `autoplay: false`, push to `window.__hfAnime`, `anime.createSeededRandom`                        |
+| Three.js, WebGPU, p5, canvas | 3D and generative                 | Draw from `e.detail.time` in an `hf-seek` listener; set `data-duration` on the root              |
+
+Charts and map overlays: drive them from a GSAP tween's `onUpdate`, not the library's own transitions. A real place is shown on baked imagery, not drawn (`film.md` "Maps and real places"). Heavy setup (big meshes, shader compiles) registers a `window.__hf.buildReady["<key>"]` promise.
+
+## The seek protocol
+
+```html
+<script>
+  function renderAt(t) {
+    /* draw the frame for t seconds from state derived from t alone */
+  }
+  window.addEventListener("hf-seek", (e) => {
+    renderAt(e.detail.time);
+    // async work (GPU submit, image decode): e.detail.waitUntil(promise), called synchronously
+  });
+  renderAt(0);
+</script>
+```
+
+No `requestAnimationFrame` loop or timer as the clock.