@prestyj/cli 5.27.0 → 5.28.1

package/assets/motion/references/motion-language.md

@@ -0,0 +1,128 @@
+# Motion language
+
+Use this for every video you design. The user's brand kit, references or a
+chosen library look override any default below. These are principles, not a
+house look. Choose the concept, palette and type fresh for every video; never
+copy an earlier video's.
+
+## The bar
+
+Make a showcase piece, as if the best motion designers will judge it frame by
+frame. Ambition means deliberate craft, not length or effect count. Every
+colour, word, cut and ease needs a reason. Cut generic defaults: plain fades,
+slowly drifting gradients, text that slides up and sits there. Judge it as the
+kind of video it is: an explainer by how clearly it teaches, a tribute by how
+it honours its subject, a launch by how it makes people want the product.
+
+## Plan first
+
+Before writing code, decide these and record them in the `Concept` and
+`Language` lines of `frame.md`. A few lines is enough; nobody approves them.
+
+- **Concept**: the idea the video demonstrates, in one sentence. Show it; don't
+  just state it.
+- **Motif**: one shape or element that recurs and links every scene.
+- **Register**: the tone (calm, playful, urgent, tender, precise…) and what it
+  means for size, speed, easing and colour. Take it from the brief, the brand
+  and the viewing context.
+- **Palette**: each colour's role.
+- **Type**: each family's role.
+- **Beat**: tempo, arc and frame rate.
+
+## Principles
+
+**Register.** Map the tone to motion before choosing anything else. Quiet,
+steady motion carries information and reading; expressive motion is saved for
+the moments that matter, because it only reads as special against calm. These
+pairings are illustrative, not presets: calm is long, soft moves and few of
+them; playful is springy overshoot, squash and stretch; luxurious is slow and
+precise with generous space; urgent is fast moves and hard cuts; tender is
+warm, slow and held; technical is precise and snapping.
+
+**Continuity.** Each scene hands something to the next: a shape, a word, a
+colour field or a camera move. Prefer match cuts and shape handoffs to
+cross-fades. The `type-as-spatial-handoff` study in [README.md](README.md) shows
+type becoming the next scene.
+
+**Palette.** A few colours, each with a role, derived from the brand, subject or
+references. How many, how saturated and how often the frame changes colour
+follow the register: full-frame colour blocks that change on most cuts suit a
+loud, kinetic piece; a calm, tender or documentary piece holds a steadier field
+and lets one accent carry attention. Gradients and glows are seasoning, not the
+base. Keep text readable.
+
+**No harmful flashing.** Anything flashing over more than about 3% of the frame
+counts. Keep light/dark swaps, and swaps to and from saturated red, to at most
+six in any one second (three flashes): faster flashing can trigger seizures,
+and `motion_check` fails it. A swap on every beat at 120 BPM is fine; a white
+flash frame on every half-beat is not.
+
+**Type.** Choose faces for the register and the reading job. Size follows the
+viewing context and how much there is to read: a kinetic poster can set one to
+three huge words per shot; an explainer, documentary or lyric video sets whole
+lines at a comfortable reading size. Size type against the frame's shorter side
+(in vertical video, the width inside the safe margins) and check that the
+longest word fits. Animate weight and width axes as motion, not only position
+and opacity. Use one display family, at most one contrasting voice, such as an
+italic serif, and small uppercase tracked mono for labels and UI where the
+subject calls for it. Bundled axes (see `fonts.mjs list` and its specimen):
+weight and width in Mona Sans, Hubot Sans, Anybody, Archivo, Bricolage
+Grotesque and Martian Mono; italics in Fraunces and Newsreader. Brand fonts win.
+
+**Motion.** Smooth by default, bounce by choice. Entrances settle on the
+critically damped spring or `power3.out` / `expo.out`; exits `power3.in`; moves
+`power3.inOut` or `expo.inOut`. Overshoot (`back.out`, `elastic.out` or an
+underdamped spring) is a register chosen for playful or physical work, never
+the default; see [easing](runtime/gsap-easing-and-stagger.md). Durations follow
+the register: roughly 0.15–0.5 s for snappy, energetic or technical motion, and
+0.6–1.5 s or longer for calm, luxurious or tender work. Staggers run 0.012–0.06 s
+for type and longer for larger elements. Use real animation principles where
+they help: anticipation before big moves, squash and stretch on impact, arcs
+instead of straight paths, overlapping action, follow-through and smears on fast
+moves. Lead with one movement at a time, with smaller overlapping motion under
+it. Every move starts, travels and lands on purpose; nothing drifts without a
+reason.
+
+**Pace.** Keep time on a grid: the track's beats (`hf beats`) when there is
+music, otherwise a tempo chosen for the register. Cut by how much there is to
+take in, not by the grid alone: a simple image can last one beat; a line to
+read or an idea to grasp holds for several. Meaningful text stays still and
+readable for at least the longer of 0.8 s and one second per 15 characters,
+longer for the key line; repeated or decorative words can go faster. Vary the
+density (build, release, rest) so the video is neither always fast nor always
+slow. Shape the whole to its form, with a beginning, development, peak and
+resolution even in five seconds. Illustratively: a launch builds to its
+product, an explainer steps through its idea, a lyric video follows the song's
+sections, a tribute lets each moment breathe. End on a composed frame held long
+enough to read, and declare that hold in the hold plan before checking.
+
+**3D, when the subject earns it.** One hero object whose material, light and
+camera come from the concept and register, not a stock tech look; add
+supporting elements only when they mean something. Resolve 3D back to flat 2D to
+hand off to the next scene. Use the bundled Three.js (`three.mjs`); no 3D by
+default.
+
+**Chrome, when it suits.** A small persistent mono layer (labels, timecode,
+chapter name, a progress bar with markers) makes a tech subject feel like a pro
+tool. Leave it out elsewhere.
+
+**Frame rate.** 30 fps suits most work. Use 60 fps when fast, dense motion or
+scrolling UI must read smoothly; it doubles render time. Renders carry no
+motion blur, so fast moves stutter at 24 fps: keep 24 fps for slow, filmic or
+handmade work.
+
+**Truth.** Show only real product UI, numbers and claims from the user's
+sources.
+
+## Building blocks
+
+Library looks (`library.mjs list looks`) are complete palette, type and rhythm
+systems; when one fits the concept, it replaces the palette and type choices
+above. Library pieces are optional building blocks.
+
+## Check against the plan
+
+When `motion_check` returns frames, compare them with the plan in `frame.md` as
+well as the technical results. A lost motif, an off-palette colour, a generic
+transition or unreadable type is a concrete defect: fix it and check the new
+render.

package/assets/motion/references/runtime/data-attributes.md

@@ -0,0 +1,78 @@
+# Data Attributes Reference
+
+Every HyperFrames composition uses `data-*` attributes to declare timing and structure to the framework. This is the full attribute table — pair with `tracks-and-clips.md` for the rules behind `data-track-index`.
+
+## Composition Root
+
+Every renderable composition needs one root element:
+
+| Attribute                    | Required      | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-composition-id`        | Yes           | Unique ID. Must match the animation registry key on `window.__timelines`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `data-width` / `data-height` | Yes           | Pixel frame size. Common values: `1920x1080`, `1080x1920`, `1080x1080`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `data-duration`              | Conditional\* | Render duration in seconds (total length / frame count), not the GSAP timeline length. **Read once at compile time, like `data-width` / `data-height`**: a static root `data-duration` is locked before scripts run, so a script (`root.setAttribute("data-duration", ...)`) or a `--variables`-driven value cannot change the render length. To vary length per render, author the root `data-duration` directly. (A clip's `data-duration` is different: re-read from the live DOM, so scripts/variables can drive it.) Only when the root omits `data-duration` does the renderer derive total length from the live DOM / timeline after scripts run. |
+| `data-fps`                   | No            | Optional frame rate hint. CLI render flags can override output fps.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `data-composition-variables` | No            | JSON array of variable declarations (on `<html>`). See `variables-and-media.md`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+\*`data-duration` is optional whenever the runtime can auto-infer duration: a registered GSAP timeline, a finite CSS animation, a finite WAAPI `element.animate()`, a registered Lottie animation, or timed clips (the root then ends at its latest clip end, and lint only warns `root_composition_duration_derived`). It is **required** for Three.js (no auto-inference), for infinite/unbounded CSS or WAAPI animations, and for any composition with no GSAP timeline, no animation signal and no timed clip with a length. `hf lint` enforces this (`root_composition_missing_duration_source`). See the adjacent `gsap.md` for the supported GSAP registry contract; preserve an explicit recipe duration rather than relying on inference when the source fixes it.
+
+The root should be `position: relative`, have explicit pixel dimensions, and hide overflow unless intentionally composing outside the frame.
+
+## Clip Attributes
+
+**`data-start` is what makes an element a clip.** The runtime collects `[data-start]` and drives visibility off that attribute, so any element carrying it is timed.
+
+`class="clip"` is a **convention, not a requirement**: the runtime never reads it. Keep writing it: drop it and the full-frame box collapses unless you supply that layout yourself, Studio uses it as an edit hint, and `lint` warns (`timed_element_missing_clip_class`) when a timed element lacks it. Omit it on `<video>` and `<audio>`.
+
+**Nesting is allowed.** A timed element inside a wrapper is still timed, and a timed ancestor clamps its descendants: a child cannot be visible while its timed ancestor is hidden. Direct children of the root get automatic layout (see "Root-level clips get automatic layout" below); nested ones do not, so give them their own positioning.
+
+| Attribute          | Required                                     | Meaning                                                                                                                                                                                                                                                                                            |
+| ------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`               | Yes on `<video>`/`<audio>`, else recommended | `lint` errors with `media_missing_id` on media without one, and an id-less `<audio>` is never mixed, so the render is **silent**. Elsewhere it is a warning (`studio_missing_editable_id`): Studio needs a stable edit target, and timeline targets reference it.                                  |
+| `data-start`       | Yes                                          | Start time in seconds, or a supported clip-time reference. This attribute is what marks the element as timed.                                                                                                                                                                                      |
+| `data-duration`    | Required for `div` and sub-compositions      | Duration in seconds. An `img` with `data-start` defaults to 3 s; video/audio default to the source length (less the playback offset, over the rate) once known; an authored value trims. Without any resolvable duration the element has no end and stays visible for the rest of the composition. |
+| `data-track-index` | No                                           | Studio timeline lane, display only. The render never reads it, and clips on one track may overlap in time. Absent, the parser defaults it and Studio lays out one lane per clip. Two `<audio>` elements on the same index that overlap in time raise a `lint` warning.                             |
+| `data-media-start` | No                                           | Offset into the media source, in seconds.                                                                                                                                                                                                                                                          |
+| `data-volume`      | No                                           | Static audio gain, default `1` (0 dB). `0` is silence and values above `1` boost, up to `3.98` (+12 dB) — Studio's fader writes this. For fades and ducking, use the `data-automation` volume lane (see `creator-editing-recipes.md`).                                                             |
+| `data-has-audio`   | No (`<video>` only)                          | `"true"` to declare the video carries an audio track when auto-detection would miss it.                                                                                                                                                                                                            |
+
+**The visibility window is half-open: `[start, start + duration)`.** A clip shows while `start ≤ t < start + duration` and is hidden at exactly `t = start + duration`. Land an animation's resolved end state slightly **before** `data-duration`, not on it, or its last frame is never rendered. Two clips can therefore be authored back to back (`b.start === a.start + a.duration`) with no overlapping frame.
+
+**Root-level clips get automatic layout.** For direct children of the composition root that carry `data-start`, the runtime forces `position: absolute` and anchors them at `top: 0; left: 0`, sizing them to 100% when they have no computed size, so scenes stack in the same viewport layer. Elements **without** `data-start` are skipped entirely: an untimed full-bleed background needs its own `position: absolute; inset: 0`, or it collapses to zero height.
+
+## Sub-Composition Host Attributes
+
+When a clip is a sub-composition host (loads another composition file):
+
+| Attribute                    | Required    | Meaning                                                                                                                                                     |
+| ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-composition-id`        | Recommended | The composition ID of the loaded file. Matching it is the convention; a host that names a different id, or none at all, is supported but resolves silently. |
+| `data-composition-src`       | Yes         | Path to the sub-composition HTML file.                                                                                                                      |
+| `data-width` / `data-height` | No          | Render dimensions for the instance. The compiler backfills them from the loaded file's root when absent.                                                    |
+| `data-variable-values`       | No          | Per-instance variable overrides as JSON. See `variables-and-media.md`.                                                                                      |
+| `data-var-src`               | No          | Binds the element's `src` to a declared variable id (media/image substitution, authored src = fallback).                                                    |
+| `data-var-text`              | No          | Binds the element's own text to a scalar variable id; children are preserved.                                                                               |
+
+See `sub-compositions.md` for the full wiring pattern.
+
+## Authoring Hints
+
+- `id="root"` — template convention used by scaffolds and the transition catalog so CSS can target the composition root with `#root` instead of `[data-composition-id="main"]`. Not required by the runtime, but consistent with the rest of the ecosystem.
+- `class="clip"`: layout and tooling convention on visible timed elements (`<div>`, `<img>`, …), not a runtime requirement. See Clip Attributes above.
+- `data-root="true"`: names the composition root explicitly. Without it the runtime picks the outermost `[data-composition-id]` element, which is right for almost every file; set it when compositions nest and you need to be unambiguous.
+- `data-layout-allow-overflow` — tells `hyperframes check` that overflow on this element (or its descendants) is intentional. Notes:
+  - The `check` layout audit measures `getBoundingClientRect` at sampled timestamps, not rendered pixels. `overflow: hidden` clips the visual but does **not** suppress a layout finding. This attribute is the escape hatch; CSS overflow is not.
+  - Can be set on the composition **root** as well as on any child. When the cited offender is `div.<comp>-root inside div.<comp>-root` (the root reports its own children's union as overflowing), the fix goes on the root, not on individual text descendants — shrinking font sizes will not converge.
+  - In a multi-scene `group_wN.html` (continue runs), every scene-local element stays in the DOM during the other scenes' time windows; the layout-box union almost always overflows the canvas during morph seams. Mark the root and every scene-local primary/supporting element with this attribute **at construction**, not after `check` flags it.
+  - **Blast radius — it silences more than the overflow audit.** The attribute is inherited down the subtree (the perception probe walks ancestors), so it also suppresses the rendered-perception checks `text-clipping`, `content-cramped-container`, and `foreground-over-panel` for every descendant. Putting it on a persistent panel that also hosts real foreground content disables collision checks on that content for the panel's whole lifetime. Prefer the narrowest opt-out: scope it to the smallest decorative wrapper, or use per-element `data-layout-bleed="true"` for one intentional primary-text crop. The two canvas/edge checks `primary-offscreen` and `foreground-over-panel` deliberately run **even under** allow-overflow, so it cannot hide a wordmark sliced by the frame or text bleeding onto a panel edge.
+- `data-layout-ignore` — exclude this element from layout audits entirely.
+- `data-layout-allow-caption-zone` — opt out of `--caption-zone` / `caption_zone_collision` for intentional lower-third copy (applies to the element and every descendant via `closest`; does **not** suppress overflow, overlap, occlusion, or other layout audits — pair those attrs if needed).
+
+## Legacy / Removed Attributes
+
+These names appear in older projects and examples. Use the current names when authoring or editing:
+
+| Legacy name  | Use instead        |
+| ------------ | ------------------ |
+| `data-layer` | `data-track-index` |
+| `data-end`   | `data-duration`    |

package/assets/motion/references/runtime/determinism-rules.md

@@ -0,0 +1,53 @@
+# Determinism, Animation Runtime, and Layout
+
+HyperFrames seeks compositions frame-by-frame. Every frame must be reproducible from its time value alone — same input time → same pixels. Three contracts enforce this: the **animation runtime contract**, the **determinism rules**, and the **layout contract**.
+
+## Animation Runtime Contract
+
+GSAP is the primary runtime. The core requirement is generic: animation state must be seekable from HyperFrames time.
+
+For GSAP:
+
+- Use `gsap.timeline({ paused: true })`.
+- Register it on `window.__timelines["<composition-id>"]`, keyed by the composition root's `data-composition-id`. You do **not** need to write `window.__timelines = window.__timelines || {}` first: the runtime creates the registry before your inline scripts evaluate.
+- **Building inside an async callback is supported.** `document.fonts.ready(...)` and friends are the documented setup path. What you must not do is **register the key before the build finishes**. An empty timeline registered early is treated as ready and nested empty, so the animation renders blank (`lint`: `gsap_timeline_registered_before_async_build`, error). Assign `window.__timelines[id] = tl` at the **end** of the callback, after the tweens are added, and optionally call `window.__hfForceTimelineRebind()` right after.
+- If the key does not match the root's `data-composition-id`, the runtime still binds it **when it is the only registered timeline**. With two or more registered, a mismatched key leaves the render frozen at t=0.
+- **Do not** call `tl.play()` for render-critical motion.
+- **Do not** create empty tweens only to set duration; use `data-duration` on the clip instead.
+
+Use the adjacent `gsap.md`, `gsap-timeline-and-labels.md` and `gsap-easing-and-stagger.md` for GSAP mechanics. These technical references do not choose the design; the video's plan in `frame.md` does.
+
+## Determinism Rules
+
+Rendered frames must be reproducible from the requested time. Do **not** use any of the following for visual state:
+
+- `Date.now()`, `performance.now()`, or any render-time clock.
+- Unseeded `Math.random()`. Use a seeded PRNG if random-looking placement is needed.
+- Render-time network fetches for required assets. Inline or pre-bundle them.
+- Hover, scroll, pointer, or focus state. The renderer has no input events.
+- Infinite loops such as `repeat: -1`. Compute a finite count: `repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)` — **`floor`, not `ceil`** (`ceil` overshoots `data-duration` and trips the `gsap_repeat_ceil_overshoot` lint; `max(0, …)` avoids a negative repeat = infinite).
+
+Also avoid:
+
+- Tweening `display`, raw `visibility`, or `autoAlpha` **on a clip element**: HyperFrames timing owns a clip's visibility, and `lint` rejects it (`gsap_animates_clip_element`). Fade with `opacity`, or tween a child wrapper. Do not tween `class="clip"`.
+- There is no fixed allowlist of animatable properties. `lint` enforces a **denylist**, so `filter`, `clipPath`, `strokeDashoffset`, `width`, `height` and similar are all legitimate targets. Prefer transforms and opacity where you have the choice, for performance rather than correctness. See the adjacent `gsap.md` for runtime details.
+- Animating the same property on the same element from multiple timelines at the same time — GSAP's overwrite behavior is order-dependent and can flip between renders.
+
+## Layout Contract
+
+Build the visible end-state in static HTML and CSS first, then animate from/to that state.
+
+- The composition root has fixed pixel frame dimensions.
+- **The root composition's total duration (render length / frame count) is fixed at compile time**, read once from the static root `data-duration` before scripts run, like `data-width` / `data-height`. A script or `--variables` value that rewrites the root `data-duration` afterward is ignored. To vary render length per output, author the root `data-duration` directly. (A _clip's_ own `data-duration` is re-read from the live DOM, so scripts/variables can still drive clip lengths. Only when the root omits `data-duration` does the renderer probe the live DOM / timeline for total length.)
+- Scene containers should fill the scene with `width: 100%; height: 100%; box-sizing: border-box`.
+- Use padding, flex, grid, and `max-width` for layout. Avoid positioning main content with hardcoded `top`/`left` offsets when a layout container can do it.
+- Absolute layers are appropriate for deliberately placed design elements; keep one positioning model per scene.
+- Prefer transforms and opacity for animation.
+- Keep text inside its intended container. Wrap, resize or use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })` deliberately; never let text clip silently.
+- For text measurement without DOM reflow, use `window.__hyperframes.pretext`. Measure off a canvas instead of writing into the page and reading it back, so nothing reflows: `pretext.prepare(text, font)` then `pretext.layout(prepared, maxWidth, lineHeight)` → `{ lineCount, height }`. `prepare` does the font measurement; everything downstream of a prepared string is arithmetic and cheap enough to run per frame. `fitTextFontSize` is built on it.
+  - `layout` gives you height, not width. To size a container to its text (shrinkwrap), use `pretext.prepareWithSegments(text, font)` and then `pretext.measureNaturalWidth(prepared)` for the single-line width, or `pretext.measureLineStats(prepared, maxWidth)` for `{ lineCount, maxLineWidth }`.
+  - `font` is a CSS font shorthand string, e.g. `"700 90px Inter"`.
+  - `clearCache` and `setLocale` are deliberately not exposed: they mutate state shared across compositions, which would make a render depend on what ran before it.
+- **Do not** use `<br>` in body text. Forced breaks ignore the actual rendered font width and produce an extra break when the line already wraps naturally, causing overlap. Let text wrap via `max-width`. Exception: short display titles where each word is deliberately on its own line.
+- **Transformed elements must be block-level + sized.** `transform`/`scaleX`/`scaleY` is a no-op on an inline `<span>`, and scaling an auto-width (0px) element shows nothing → invisible bars/fills. Give them `display: block`/`inline-block`/flex-item **and** a real `width`/`height` (e.g. `width: 100%` inside a sized parent). _(Silent — automated gates may miss it.)_
+- **Absolutely-positioned decoratives that pulse or overshoot** (`yoyo` scale, `back.out`) need clearance at their **peak** size and must not straddle an `overflow: hidden` edge — else they overlap a neighbor or get clipped. Position for the largest frame, not the resting one. _(silent.)_

package/assets/motion/references/runtime/doctor-browser.md

@@ -0,0 +1,57 @@
+# doctor, browser
+
+Environment diagnosis and bundled-Chrome management. Run these first when a render or preview fails.
+
+## doctor
+
+```bash
+hf doctor
+hf doctor --json     # CI / agent output (always exit 0; gate on payload `ok`)
+```
+
+Runs independent checks and reports each as ok/warn/fail:
+
+- **Version** — installed CLI vs latest on npm (hints upgrade when stale)
+- **Node.js** — ≥ 22 required
+- **CPU**, **Memory**, **Disk** — host resources
+- **Environment** — env vars that affect the renderer
+- **FFmpeg** / **FFprobe** — found, version, codecs
+- **Chrome** — bundled or system, version, path
+- **Docker** / **Docker running** — required only for `render --docker`
+- **/dev/shm** — inside containers only
+
+Run `doctor` first when:
+
+- `render` fails with a Chrome or FFmpeg error.
+- `preview` opens but the composition fails to load.
+- A fresh machine has never run HyperFrames.
+
+Common issues:
+
+- **Missing FFmpeg** — report the setup blocker and ask before installing software; use an existing compatible binary when available.
+- **Missing bundled Chrome** — run `hf browser ensure`.
+- **Low memory** — close other Chromes, reduce `--workers`, or use `--quality draft`.
+- **Chrome exits instantly inside an agent sandbox (macOS)** — seatbelt-style sandboxes
+  (e.g. codex `workspace-write`) block Chromium's Mach port bootstrap
+  (`MachPortRendezvous`; openai/codex#21292), so every Chrome — bundled, system, or
+  headless shell — dies at startup. This is a host-level block, not a HyperFrames or
+  Chrome install problem: compile checks and audio still pass, only rendering is
+  unavailable. State the blocker and deliver the checked composition; render outside the
+  sandbox only through an authorized route. Do not weaken the sandbox or upload files to cloud rendering without explicit permission. **Do not build a
+  substitute rasterizer** (magick/PIL/SVG frame pipelines) — on a blocked-browser host
+  the deliverable IS the checked composition plus this blocker note, and rendering is
+  handed to `--docker`, cloud, or the user. Write your final summary the moment the
+  blocker is identified, BEFORE any optional fallback work: a later session failure must
+  not erase the report of work already done.
+
+## browser
+
+```bash
+hf browser ensure    # find or download the pinned Chrome
+hf browser path      # print the browser executable path (for scripting)
+hf browser clear     # remove the cached Chrome download
+```
+
+Manage the Chrome build HyperFrames uses for rendering. The pinned version exists because pixel output drifts across Chrome versions — using the bundled build keeps rendered output reproducible across machines.
+
+Use `path` to embed the binary in scripts: `$(hf browser path)`.

package/assets/motion/references/runtime/gsap-easing-and-stagger.md

@@ -0,0 +1,199 @@
+# Easing, Stagger, and Function-Based Values
+
+## Easing
+
+Built-in eases: `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`, `none`.
+
+Each has `.in`, `.out`, `.inOut` variants.
+
+| Ease                                       | Use for                                                                                                 |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `power1.out`, `power2.out`                 | Gentle motion for secondary elements (a caption fade, a small shift). NOT the entrance default.         |
+| `power3.out` (house default), `power4.out` | The standard long-tail settle. Entrances, title cards, hero reveals.                                    |
+| `sine.inOut`                               | Long, slow, calm motion. Crossfades, ambient drift.                                                     |
+| `back.out(1.7)`                            | Overshoot then settle. A chosen register (playful, physical), never a default.                          |
+| `elastic.out(1, 0.3)`                      | Springy bounce. Same register rule; prefer a baked spring (see Spring Eases below).                     |
+| `expo.inOut`                               | Snappy, dramatic. Quick transitions between hero scenes.                                                |
+| `none` (linear)                            | Camera moves with timed counterpoint, mechanical motion.                                                |
+
+Pick `.out` for entrances, `.in` for exits, `.inOut` for symmetric moves and continuous motion.
+
+**Smooth by default, bounce by choice** — the same rule as the Motion section of [`motion-language.md`](../motion-language.md): entrances default to `power3.out` or the baked critically-damped spring (see Spring Eases below); overshoot eases (`back` / `elastic` / `bounce`, or an underdamped spring) are a register the brief chooses for playful or physical work, never the house style.
+
+## Easing Vocabulary (character & mood)
+
+Easings are tone of voice: a video that only whispers is boring; one that varies between whisper, normal, and punch is engaging. A composition should draw on ~3 easing characters across its beats — but vary **within the smooth families by energy** (`sine` / `power1` calm → `power3` standard → `power4` / `expo` punch); don't reach for overshoot to add variety. Overshoot is a _register_ (explicitly playful), not a spice. One ease everywhere reads flat; bounce everywhere reads cheap — the second failure is worse.
+
+The full palette by character (each family has `.in`, `.out`, `.inOut` variants):
+
+| Family               | Character                                                                    | Typical use                                                                                                                                  |
+| -------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `power1`–`power4`    | Gentle (1) to aggressive (4) acceleration curves                             | General purpose. **power3 is the house workhorse**; power2 for gentle secondary motion, power4 for dramatic snaps                            |
+| `back(N)`            | Overshoot then settle. N controls how far past the target (1=subtle, 4=wild) | Chosen register only (playful, physical), never a default. Keep N ≤ 2; prefer a baked spring at ζ 0.6–0.7 (physical settle, see Spring Eases) |
+| `elastic(amp, freq)` | Spring bounce. amp=magnitude, freq=oscillation speed                         | Same register rule; the baked spring (below) is the physical version                                                                         |
+| `bounce`             | Ball-drop bouncing                                                           | Physical-comedy register only (something literally dropping)                                                                                 |
+| `expo`               | Extreme acceleration curve (much steeper than power4)                        | Premium/luxury reveals, dramatic entrances                                                                                                   |
+| `sine`               | Smooth, organic, no hard edges                                               | Ambient float, breathing, Ken Burns, anything that loops. `.inOut` for yoyo motion                                                           |
+| `circ`               | Circular acceleration (starts very fast, ends very gentle or vice versa)     | Camera moves, scene transitions, orbital motion                                                                                              |
+| `steps(N)`           | Discrete N-step jumps, no interpolation                                      | Typing effects, cursor blink, counter ticks, retro/digital aesthetics                                                                        |
+
+**Mood mapping:** Match easing character to the beat's emotional content. Smooth/organic easings (`sine`, `power1`) feel contemplative and drifting. Aggressive deceleration (`power4.out`, `expo.out`) feels snappy and confident. Spring overshoot (`back.out`) feels bouncy and physical — but bouncy is a register, not an emphasis tool; reach for it only when the brief's register is playful or physical. The register recorded in `frame.md` should guide which character fits — not a formula.
+
+## Defaults
+
+```javascript
+const tl = gsap.timeline({
+  paused: true,
+  defaults: { duration: 0.6, ease: "power3.out" }, // the house settle — smooth beats bouncy
+});
+```
+
+Or globally:
+
+```javascript
+gsap.defaults({ duration: 0.6, ease: "power3.out" });
+```
+
+Setting defaults at timeline scope is preferred — it documents the motion language of that composition in one place.
+
+## Spring Eases (baked physics, seek-safe)
+
+The "iOS feel" is a **damped spring's velocity curve**, not a bounce: a fast launch into a long asymptotic settle. Well-made system animations are critically damped or close to it — they barely overshoot, or don't at all. `power3.out` / `expo.out` approximate that curve; when you want the exact one — or a _physical_ overshoot for a playful register — bake the spring's closed-form solution into a function ease.
+
+Why not a real-time spring library: an interactive spring is a stateful integrator (velocity accumulates frame to frame), which cannot be seeked deterministically — you'd have to simulate frames 0…N−1 to render frame N. The closed form below is a **pure function of progress** — no state, nothing to desync, seek-safe by construction. This is also why interaction-lib spring solvers are banned in compositions.
+
+```javascript
+// springEase — a damped spring's exact position curve as a GSAP ease.
+// response         ≈ seconds one oscillation would take (0.3–0.6 for entrances)
+// dampingFraction  1.0       = critically damped — smooth settle, NO overshoot (house default)
+//                  0.80–0.85 ≈ the iOS system register — ~1–1.5% overshoot, felt not seen
+//                  0.60–0.70 = playful register — ~5–10% overshoot (by choice; replaces back.out)
+function springEase({ response = 0.5, dampingFraction = 1 } = {}) {
+  const w = (2 * Math.PI) / response; // undamped natural frequency
+  const z = dampingFraction;
+  let pos; // x(t): 0 → 1, starting at rest (v0 = 0)
+  if (z < 1) {
+    const wd = w * Math.sqrt(1 - z * z);
+    pos = (t) => 1 - Math.exp(-z * w * t) * (Math.cos(wd * t) + ((z * w) / wd) * Math.sin(wd * t));
+  } else if (z > 1) {
+    const wo = w * Math.sqrt(z * z - 1);
+    pos = (t) =>
+      1 - Math.exp(-z * w * t) * (Math.cosh(wo * t) + ((z * w) / wo) * Math.sinh(wo * t));
+  } else {
+    pos = (t) => 1 - Math.exp(-w * t) * (1 + w * t);
+  }
+  // Settle time: last moment the curve sits outside ±0.1% of target.
+  // Fixed-step scan, runs once at setup — deterministic (no Math.random / Date.now).
+  const EPS = 0.001;
+  const rate = z <= 1 ? z * w : (z - Math.sqrt(z * z - 1)) * w; // slowest decay mode
+  const SCAN = 12 / rate;
+  const N = 4800;
+  let T = SCAN;
+  for (let i = N; i >= 0; i--) {
+    const t = (i / N) * SCAN;
+    if (Math.abs(1 - pos(t)) > EPS) {
+      T = ((i + 1) / N) * SCAN;
+      break;
+    }
+  }
+  const xT = pos(T);
+  return {
+    duration: T, // use as the tween's duration — the settle time IS the physics
+    ease: (p) => pos(p * T) + p * (1 - xT), // normalized so ease(1) === 1 exactly
+  };
+}
+```
+
+Usage — take **both** the ease and the duration from the helper (the settle time is part of the physics; overriding the duration just re-times the same curve, so tune speed via `response` instead):
+
+```javascript
+const settle = springEase({ response: 0.4 }); // critically damped → duration ≈ 0.59s
+tl.fromTo(
+  "#hero",
+  { scale: 0, opacity: 0 },
+  { scale: 1, opacity: 1, duration: settle.duration, ease: settle.ease },
+  0.2,
+);
+```
+
+| dampingFraction   | overshoot       | register                                                                                                                                           |
+| ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1.0 (default)** | none (monotone) | The house settle — the exact curve `power3.out` approximates. Product / enterprise / serious tone.                                                 |
+| 0.80–0.85         | ~1–1.5%         | "Alive, not bouncy" — the iOS system default register. The overshoot is felt, not seen.                                                            |
+| 0.60–0.70         | ~5–10%          | Playful register, by choice (same rule as `back.out`, which this replaces — a spring's second-order settle reads physical where `back` reads cartoon). |
+| < 0.55            | > 12%           | Don't. Cartoon-wobble territory.                                                                                                                   |
+
+| response  | duration (ζ=1) | feel                                                         |
+| --------- | -------------- | ------------------------------------------------------------ |
+| 0.25–0.35 | 0.37–0.51s     | tight snap — chips, small UI                                 |
+| 0.35–0.50 | 0.51–0.74s     | standard entrance                                            |
+| 0.50–0.70 | 0.74–1.03s     | weighted hero landing — when the shot opens on it, start it early so the subject is seen within about half a second |
+
+Craft notes:
+
+- **ζ=1 vs `power3.out`**: the true spring front-loads harder (~67% vs ~58% travelled at quarter-time) and settles on a longer asymptotic tail; max shape difference ~11%. That long tail is the "premium" read — use it when the settle IS the shot (a wordmark landing, a final lockup).
+- **At ζ<1, overshooting curves go on transforms only** — never on `opacity` (it would push past 1) or color. Split opacity onto its own `power2.out` tween at the same timeline position.
+- **Default unchanged**: ζ below ~0.8 is a register the brief chooses, never a default. The default of this section is ζ=1 — real spring physics is not a license for bounce.
+
+## Stagger
+
+```javascript
+gsap.fromTo(".item", { y: 24, opacity: 0 }, { y: 0, opacity: 1, duration: 0.5, stagger: 0.08 });
+```
+
+Object form:
+
+```javascript
+gsap.fromTo(
+  ".item",
+  { y: 24, opacity: 0 },
+  {
+    y: 0,
+    opacity: 1,
+    stagger: {
+      each: 0.08, // delay between each
+      from: "center", // "start" | "end" | "center" | "edges" | "random" | index
+      amount: 0.6, // total stagger time (overrides each if both set)
+      grid: "auto", // for 2D stagger
+      axis: "x" | "y",
+    },
+  },
+);
+```
+
+Prefer `stagger` over N separate tweens with manual delays — it stays correct when the target count or order changes. Use `fromTo()` rather than `from()` so the start state is explicit (see `gsap-timeline-and-labels.md` → sub-composition entrances).
+
+## Function-Based Values
+
+Any var can be a function `(index, target, targets) => value`:
+
+```javascript
+gsap.to(".item", {
+  x: (i, target, targets) => i * 50,
+  rotation: (i) => (i % 2 === 0 ? 5 : -5),
+  stagger: 0.1,
+});
+```
+
+Use this for per-element values that depend on index, attributes, or measured size. Cheaper and more idiomatic than building tweens in a loop.
+
+## gsap.matchMedia (preview only)
+
+`matchMedia` runs setup only when a media query matches and auto-reverts when it stops matching. It is useful for **preview** in the browser at different viewport sizes, and for `prefers-reduced-motion`. It is **not** a substitute for rendering at the composition's actual `data-width`/`data-height` — HyperFrames renders at a fixed viewport.
+
+```javascript
+let mm = gsap.matchMedia();
+mm.add(
+  {
+    isDesktop: "(min-width: 800px)",
+    reduceMotion: "(prefers-reduced-motion: reduce)",
+  },
+  (context) => {
+    const { isDesktop, reduceMotion } = context.conditions;
+    gsap.to(".box", {
+      rotation: isDesktop ? 360 : 180,
+      duration: reduceMotion ? 0 : 2,
+    });
+  },
+);
+```

package/assets/motion/references/runtime/gsap-timeline-and-labels.md

@@ -0,0 +1,96 @@
+# Timelines and Labels
+
+HyperFrames is a seek-driven runtime. Build one paused timeline per composition, attach it to `window.__timelines["<composition-id>"]`, and let HyperFrames seek it. Never call `.play()` for render-critical motion.
+
+## Creating a Timeline
+
+```javascript
+const tl = gsap.timeline({
+  paused: true,
+  defaults: { duration: 0.5, ease: "power3.out" },
+});
+
+tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
+```
+
+Timeline options:
+
+- **paused: true** — required in HyperFrames. The framework drives the playhead.
+- **repeat**, **yoyo** — apply to the whole timeline. `repeat: -1` is forbidden; use finite counts.
+- **defaults** — vars merged into every child tween. Use this instead of repeating `ease` and `duration` on every line.
+
+## Position Parameter
+
+The third argument to `.to()`/`.from()`/`.fromTo()` controls placement on the timeline:
+
+| Form           | Meaning                              |
+| -------------- | ------------------------------------ |
+| `0`, `1.5`     | Absolute time in seconds             |
+| `"+=0.5"`      | 0.5s after the end of the timeline   |
+| `"-=0.2"`      | 0.2s before the end of the timeline  |
+| `"intro"`      | At the `intro` label                 |
+| `"intro+=0.3"` | 0.3s after the `intro` label         |
+| `"<"`          | Same start as the previous tween     |
+| `">"`          | Right after the previous tween ends  |
+| `"<0.2"`       | 0.2s after the previous tween starts |
+| `">-0.1"`      | 0.1s before the previous tween ends  |
+
+```javascript
+tl.to(".a", { x: 100 }, 0);
+tl.to(".b", { y: 50 }, "<"); // same start as .a
+tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s after .b starts
+```
+
+Prefer the position parameter over `delay:` — it composes naturally and survives refactors that re-order tweens.
+
+## Labels
+
+```javascript
+tl.addLabel("intro", 0);
+tl.to(".a", { x: 100 }, "intro");
+
+tl.addLabel("outro", "+=0.5");
+tl.to(".a", { opacity: 0 }, "outro");
+```
+
+Labels make a long timeline readable and let multiple tweens converge on the same beat without re-typing absolute times.
+
+## Nesting Timelines
+
+```javascript
+const master = gsap.timeline({ paused: true });
+
+const child = gsap.timeline();
+child.to(".a", { x: 100 }).to(".b", { y: 50 });
+
+master.add(child, 0);
+```
+
+In HyperFrames, **do not** nest sub-composition timelines into the host. Sub-compositions loaded via `data-composition-src` are seeked independently by HyperFrames from their own `data-start`. Nesting is only for grouping pieces of the _same_ composition's timeline.
+
+## Inside Sub-Compositions: prefer `fromTo` over `from`
+
+For entrance tweens inside a sub-composition, prefer `gsap.fromTo()` over `gsap.from()`:
+
+```javascript
+// Sub-composition entrance — survives re-seek cleanly
+tl.fromTo(".title", { y: 60, opacity: 0 }, { y: 0, opacity: 1, duration: 0.6 }, 0.2);
+```
+
+Why: HyperFrames re-seeks the sub-composition every time its host clip becomes visible. `gsap.from()` snapshots the starting state at **registration time** (page load); when the playhead jumps back past `data-start`, that snapshot can desync from the actual CSS state and the element renders in the wrong position. `gsap.fromTo()` declares both endpoints explicitly, so the seek-back always produces the same start state.
+
+In top-level (standalone) compositions either form works — there's no re-seek-through-mount cycle.
+
+## Playback Control (debug / preview only)
+
+```javascript
+tl.play();
+tl.pause();
+tl.reverse();
+tl.restart();
+tl.time(2);
+tl.progress(0.5);
+tl.kill();
+```
+
+These are useful when previewing in the browser. In rendered output HyperFrames calls `seek()` internally — your timeline must produce identical state for the same time value every time it is seeked.