@prestyj/cli 5.27.0 → 5.28.1

package/assets/motion/references/runtime/gsap-transforms-and-perf.md

@@ -0,0 +1,129 @@
+# Transforms and Performance
+
+## Transform Aliases
+
+Prefer GSAP's transform aliases over raw `transform` strings:
+
+| GSAP property               | Equivalent            |
+| --------------------------- | --------------------- |
+| `x`, `y`, `z`               | `translateX/Y/Z` (px) |
+| `xPercent`, `yPercent`      | `translateX/Y` in `%` |
+| `scale`, `scaleX`, `scaleY` | `scale`               |
+| `rotation`                  | `rotate` (deg)        |
+| `rotationX`, `rotationY`    | 3D rotate             |
+| `skewX`, `skewY`            | `skew`                |
+| `transformOrigin`           | `transform-origin`    |
+
+Aliases let GSAP track and interpolate each axis independently, which prevents accidental overwrites between separate tweens on the same element.
+
+## autoAlpha
+
+Prefer `autoAlpha` over `opacity` for show/hide:
+
+```javascript
+gsap.to(".panel", { autoAlpha: 0, duration: 0.4 });
+```
+
+`autoAlpha: 0` sets both `opacity: 0` and `visibility: hidden`, which removes the element from hit-testing and accessibility tree at zero alpha — closer to "gone" than plain `opacity: 0`. The registered seekable timeline still interpolates only opacity; visibility changes at the hidden endpoint. Use `autoAlpha` only on non-clip elements or wrappers inside a clip; HyperFrames owns `.clip` visibility. Never duration-tween raw `visibility` or `display`.
+
+## clearProps
+
+Removes inline styles set by GSAP when the tween completes:
+
+```javascript
+gsap.to(".item", { x: 100, rotation: 45, clearProps: "all" });
+gsap.to(".item", { x: 100, rotation: 45, clearProps: "rotation,x" });
+```
+
+Useful at the end of an animation segment to hand the element back to CSS.
+
+## CSS Variables
+
+```javascript
+gsap.to(".chart", { "--hue": 180, duration: 1 });
+```
+
+Animate any custom property. Works for color, length, number — anything CSS will interpolate.
+
+## Relative and Directional Values
+
+- Relative: `"+=20"`, `"-=10"`, `"*=2"`.
+- Directional rotation: `"360_cw"`, `"-170_short"`, `"90_ccw"` — controls which way the angle takes when going between two values.
+
+## SVG Specifics
+
+- `svgOrigin` sets transform origin in the SVG's global coordinate space (not the element's local box). **Do not** combine `svgOrigin` with `transformOrigin` on the same element — pick one.
+- Animate SVG transform attributes via the same alias names (`x`, `y`, `rotation`) — GSAP handles the SVG-specific quirks.
+- **Resolve SVG geometry before building center-based transforms.** `createElementNS` is supported, but a detached, hidden, or zero-size element may not expose usable geometry when GSAP resolves a percentage `transformOrigin`. Attach and size the SVG before constructing the timeline, use an explicit `svgOrigin` when you know the canvas coordinates, or draw animated geometry around local `(0,0)` inside a positioning `<g>` for a center pivot that does not depend on a measured bounding box.
+
+## Performance Rules
+
+### Animate transforms, not layout properties
+
+Animate `x`, `y`, `scale`, `rotation`, `opacity`. Never animate `left`, `right`, `top`, `bottom`, `width`, `height`, `margin*`, the text-reflow props `letterSpacing` / `wordSpacing` / `fontSize` — and never `roundProps`.
+
+This is a **render-correctness** rule in HyperFrames, not just a GPU-performance nicety. The renderer seeks frame-by-frame and screenshots each frame, and the browser compositor snaps layout properties to whole device pixels. On a fast tween the per-frame step is several pixels, so the snap is invisible; on a slow tween or a long ease-out tail the value moves less than a pixel per frame — it holds the same pixel for several frames, then jumps a whole one. The result is motion that looks smooth when fast but visibly stutters when slow. Transforms interpolate sub-pixel and stay smooth at any speed. `roundProps` forces the same integer snap onto a transform — don't use it.
+
+"Layout property" is broader than position: anything that triggers **reflow** snaps the same way. `letterSpacing` / `fontSize` are the common trap — a slow "settle" that crawls one of them by a fraction of a pixel per frame dwells on a handful of discrete glyph layouts (visible micro-stutter). The faithful smooth fix depends on which property — **do not reach for `scale` reflexively**:
+
+- **`fontSize`** → animate `scale`. Scaling text up/down is the same visual and stays sub-pixel smooth (no reflow).
+- **`letterSpacing` / `wordSpacing`** → uniform `scale` is **not** the same effect (it resizes the glyphs; it does not change the gaps between them). To animate spacing smoothly, split the text into per-character (or per-word) elements and animate each one's `x` — the glyph spread is a transform, sub-pixel smooth and visually identical to a letter-spacing tween. GSAP's `SplitText` does the split. If the spacing change is a minor flourish, hold the final value statically instead.
+
+Unlike positional props, reflow props snap during browser **layout** — upstream of the canvas raster — so they stutter even in html-in-canvas, and the exception below does **not** apply to them.
+
+#### Fixing a flagged animation — preserve the intent
+
+The lint rule tells you a property will stutter; it does **not** tell you the fix, and a fix that merely passes lint can silently change the look. Swapping a `letterSpacing` tighten for a uniform `scale` lints clean but animates a _different thing_ (it resizes the glyphs instead of closing the gaps). Two rules:
+
+1. **Reproduce the same visual** — same start/end state, same trajectory, only sub-pixel-smooth. Use the faithful equivalent (per-glyph `x` for spacing, `scale` for `fontSize`, `x`/`y` for position), not whichever transform is the least code.
+2. **Verify against the original, not against the linter.** Render the original and the fixed version and compare the motion at its key moments — the fix should differ only by the removed stutter, not by _where things end up_. Lint-clean-and-smooth is not the bar; faithful-and-smooth is.
+
+If the faithful fix is non-trivial (a per-glyph split, a measured offset), build it or surface the tradeoff — never downgrade to a cheaper, different effect just to satisfy the linter.
+
+**Convert a position animation to a transform** by leaving the element at its resting `left`/`top` in CSS and animating the _offset_ with `x`/`y`:
+
+```javascript
+// CSS: #card { left: 1340px; top: 540px }   ← resting position stays in CSS
+tl.to("#card", { left: 1340, top: 540, duration: 1 }); // ✗ stutters
+tl.fromTo("#card", { x: 640, y: 0 }, { x: 0, y: 0, duration: 1 }); // ✓ x/y = delta from CSS rest (640 = startLeft − 1340)
+```
+
+For a parent-relative `left: "100%"` sweep, use `xPercent: 100` only when the element is the full width of its container; otherwise convert to pixels (`x: containerWidth`).
+
+**The one exception:** elements drawn through the html-in-canvas API — those under a `<canvas layoutsubtree>` ancestor, e.g. the `liquid-glass-*` blocks. The canvas rasterizes from sub-pixel `getComputedStyle`, so layout props don't snap there and those elements keep `left`/`top`. Everything the browser lays out (plain DOM) follows the rule.
+
+The `gsap_non_transform_motion` lint rule is the backstop, not the teacher — reach for transforms from the start instead of animating layout props and waiting for lint to reject them.
+
+### will-change (sparingly)
+
+```css
+.title {
+  will-change: transform;
+}
+```
+
+Only on elements that _actually_ animate. Applied everywhere it becomes useless and burns memory.
+
+### gsap.quickTo for frequent updates (preview-only)
+
+For high-frequency updates driven by **events** — pointer move, scroll, audio scrub — `quickTo` reuses the same tween instead of creating a new one each frame:
+
+```javascript
+const xTo = gsap.quickTo("#cursor", "x", { duration: 0.4, ease: "power3" });
+const yTo = gsap.quickTo("#cursor", "y", { duration: 0.4, ease: "power3" });
+
+container.addEventListener("mousemove", (e) => {
+  xTo(e.pageX);
+  yTo(e.pageY);
+});
+```
+
+> **Render mode has no input events.** The renderer seeks frame-by-frame; `mousemove`, `scroll`, etc. never fire. `quickTo`'s main use case applies in **live preview** in the browser only. For audio-reactive motion in renders, pre-extract audio data and drive the timeline declaratively (see `../rules/gsap-effects.md`).
+
+### Stagger beats N tweens
+
+One tween with `stagger` beats N tweens with manual delays for both readability and runtime cost.
+
+### Cleanup
+
+In live preview, pause or `kill()` off-screen animations. Render mode is unaffected (the renderer drives time directly).

package/assets/motion/references/runtime/gsap.md

@@ -0,0 +1,105 @@
+---
+name: hyperframes-gsap-adapter
+description: GSAP animation API reference for HyperFrames. Use when writing seekable GSAP timelines in HyperFrames compositions, including gsap.to(), from(), fromTo(), set(), timeline position parameters, labels, easing, stagger, finite repeats, and transform performance.
+---
+
+# HyperFrames GSAP
+
+GSAP usage scoped to HyperFrames' seek-driven render model. This technical reference does not choose choreography. See `minimal-composition.md` and `determinism-rules.md` for the composition contract.
+
+## HyperFrames Contract
+
+HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline synchronously, register it on `window.__timelines` with the exact `data-composition-id`, and let HyperFrames seek it.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script>
+  window.__timelines = window.__timelines || {};
+  const tl = gsap.timeline({ paused: true });
+
+  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
+  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);
+
+  window.__timelines["main"] = tl; // key must equal data-composition-id on the composition root
+</script>
+```
+
+- The registry key must match the composition root's `data-composition-id`.
+- Bracket and dot syntax both register: `window.__timelines["main"] = tl` and `window.__timelines.main = tl` are equivalent (the linter recognizes both). Bracket form is required when the id isn't a valid identifier (e.g. contains `-`).
+- Do not call `tl.play()` for render-critical motion.
+- Building inside an async callback such as `document.fonts.ready` is supported and common. What breaks is **registering the key before the build finishes**: an empty timeline registered early is treated as ready and nested empty, so it renders blank (`lint`: `gsap_timeline_registered_before_async_build`, error). Assign `window.__timelines[id] = tl` at the end of the callback. Do not drive render-critical motion from timers or event handlers.
+- Keep loops finite. HyperFrames renders finite video durations.
+- **Render duration comes from `data-duration` on the composition root, not from GSAP timeline length.** Do not pad the timeline with empty tweens like `tl.set({}, {}, 283)` to "extend" it. (Some external docs show this trick; in HyperFrames it conflicts with the seek-driven duration model — set `data-duration` instead.)
+
+## Core Tween Methods
+
+- **gsap.to(targets, vars)** — animate from current state to `vars`. Most common.
+- **gsap.from(targets, vars)** — animate from `vars` to current state (entrances).
+- **gsap.fromTo(targets, fromVars, toVars)** — explicit start and end.
+- **gsap.set(targets, vars)** — apply immediately (duration 0).
+
+Always use **camelCase** property names (e.g. `backgroundColor`, `rotationX`).
+
+## Common vars (cheatsheet)
+
+- **duration** — seconds (default 0.5).
+- **delay** — seconds before start.
+- **ease** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`. See `./gsap-easing-and-stagger.md`.
+- **stagger** — number or object. See `./gsap-easing-and-stagger.md`.
+- **repeat** — finite number; never `-1` in HyperFrames. Compute repeats from the visible duration.
+- **yoyo** — alternates direction with repeat.
+- **overwrite** — `false` (default), `true`, or `"auto"`.
+- **immediateRender** — default `true` for from()/fromTo(). Set `false` on later tweens targeting the same property+element.
+- **onComplete**, **onStart**, **onUpdate** — callbacks.
+
+For transforms, autoAlpha, clearProps, and SVG specifics see `./gsap-transforms-and-perf.md`.
+
+## Animated properties
+
+Prefer these efficient targets when they achieve the intended motion:
+
+- **Compositor-cheap**: `opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`, `transformOrigin`
+- **Visual fills**: `color`, `backgroundColor`, `borderColor`, `borderRadius`
+- **CSS variables**: `"--hue": 180` etc.
+- **Media `volume`** (on `<audio>` / `<video>`): do not tween it for fades or ducking; use the `data-automation` volume lane (see `data-attributes.md`). A lane wins over a tween on the same element.
+- **DOM text `innerText`** (for numeric counters): tween it directly, e.g. `tl.to(el, { innerText: 100, snap: { innerText: 1 } })` — `snap` keeps it integer; the GSAP inspector recognizes it as a counter. Use a deterministic proxy value with `onUpdate` for locale formatting or suffix logic when the design needs it.
+
+**Avoid** (use the transform alias instead):
+
+- `width` / `height` / `top` / `left` / `right` / `bottom` / `margin*` / `padding*` — trigger layout reflows. Use `scaleX/Y` (with `transformOrigin`) or `x` / `y`.
+
+**Forbidden** (breaks the renderer or the clip lifecycle):
+
+- `display`, raw `visibility` **on a clip element**: never duration-tween these. HyperFrames owns a clip's visibility and `lint` rejects it. Use `autoAlpha` (opacity plus endpoint visibility) or a zero-duration timeline set at an explicit boundary. Animating a clip element's other visual properties is fine and the shipped catalog does it throughout; what is forbidden is taking over its visibility.
+- Anything driven by `Math.random()`, `Date.now()`, `performance.now()`, or event handlers — animation state must be deterministic from time alone.
+
+> **Note**: the list above is a **denylist**, not an allowlist. Properties outside it, including `width`, `height`, `filter`, `clipPath` and `strokeDashoffset`, are legitimate targets; prefer transforms and opacity where you have the choice, for performance rather than correctness. See `determinism-rules.md` for the full deterministic-render contract.
+
+## References
+
+- `./gsap-timeline-and-labels.md` — timeline creation, position parameter (`+=`, `<`, `>`), labels, nesting, sub-comp `fromTo` preference, playback control.
+- `./gsap-easing-and-stagger.md` — easing families, stagger objects, function-based values, `gsap.matchMedia()`, `gsap.defaults()`.
+- `./gsap-transforms-and-perf.md` — transform aliases, autoAlpha, `quickTo`, `will-change`, performance rules.
+- The video's plan defines effects and motion; these API examples are not additional creative instructions.
+
+## Best Practices
+
+- Use camelCase property names; prefer transform aliases and autoAlpha.
+- Prefer timelines over chained tweens with delays; use the position parameter.
+- Add labels with `addLabel()` for readable sequencing.
+- Pass defaults into the timeline constructor.
+- Store the tween/timeline return value when controlling playback.
+
+## Do Not
+
+- Animate layout properties (`width`/`height`/`top`/`left`) when transforms suffice.
+- Use both `svgOrigin` and `transformOrigin` on the same SVG element.
+- Chain animations with `delay` when a timeline can sequence them.
+- Create tweens before the DOM exists.
+- Use infinite `repeat: -1` in HyperFrames compositions — use finite repeat counts computed from the visible duration.
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/gsap.ts`.
+- GSAP documentation: https://gsap.com/docs/v3/
+- GSAP timeline pause and seek behavior: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/

package/assets/motion/references/runtime/inputs-and-assets.md

@@ -0,0 +1,62 @@
+# GG runtime inputs and assets
+
+This is implementation support, not a creative workflow. The video's plan in
+`frame.md` sets the design. Bind approved text, fonts, colours, logos and media
+without adding a second look-selection process.
+
+`hf` in these references is shorthand for the exact bundled launcher command
+in the system prompt; expand it, never run bare `hf` or `npx hyperframes`.
+`<node>` and `<motion bin>` also come from that prompt. No self-updates,
+package installs, cloud rendering or publishing without explicit permission.
+
+## Local inputs
+
+- Keep original captures/uploads in `sources/`; use local `assets/` for the
+  files consumed by the composition. Never overwrite originals or finished renders.
+- A reusable kit lives at `brand-kits/<slug>/Motion.md` in the Motion workspace.
+  Keep it read-only for ordinary video work. Record the selected kit and permitted
+  bindings in `frame.md`; preserve legacy briefs rather than duplicating plans.
+- Record fit, crop and in-point choices in `frame.md`. A longer title or a
+  different aspect ratio calls for a deliberate layout adjustment, not a silent
+  crop.
+- Root output duration is a static composition contract. If an input changes
+  the duration, update the authored root explicitly; a runtime variable cannot
+  silently change the compiled video length.
+
+## Existing helpers (only when needed)
+
+```sh
+<node> "<motion bin>/fonts.mjs" list
+<node> "<motion bin>/fonts.mjs" add <project> <Family>...
+<node> "<motion bin>/pdf-extract.mjs" <file.pdf> <output-dir>
+<node> "<motion bin>/three.mjs" add <project>
+<node> "<motion bin>/library.mjs" list
+<node> "<motion bin>/reveal.mjs" <delivered-file>
+```
+
+Inspect helper help for less common operations; do not guess options. Fonts,
+Three.js and library assets remain available offline, but their existence does
+not require using them. Respect actual licenses and required brand typography.
+
+`fonts.mjs add` returns `head`: a `<style>` block of `@font-face` rules with
+paths from the project folder. Paste it into the composition `<head>`.
+`hf check` only recognises fonts declared in the page, so linking
+`assets/fonts/fonts.css` instead renders fine but is reported as missing fonts.
+
+GSAP loads from the pinned CDN script in
+[minimal-composition](minimal-composition.md). There is no local copy in the
+bundle; do not search for one or copy one from another project.
+
+Shared music and SFX are at `../../assets/music/` and `../../assets/sfx/` relative
+to this document. Upstream metadata can retain historical `skills/brag/` paths;
+resolve its filenames under these shared asset roots, not the removed skill.
+Those provenance notes are not instructions to invoke an old workflow.
+Preserve credits, cue maps and SFX analysis. Copy only used
+assets into the video project. The plan or user determines whether
+sound belongs in the video; do not automatically add music or hits.
+
+Use `motion_check` once on the current render as specified by `video-qa`; it
+runs the media helpers and returns images for this agent to inspect. Do not
+repeat its checks as a separate checklist. Request permission before
+installing missing FFmpeg/browser software; a detector setup failure does not
+justify skipping validation. Never upload user files to resolve a local blocker.

package/assets/motion/references/runtime/lint-validate-inspect.md

@@ -0,0 +1,131 @@
+# lint, check, snapshot
+
+Motion's `motion_check` tool already runs `check`, including lint, runtime, layout and contrast, and returns rendered images. Do not run the commands below as additional delivery gates. Use them only for targeted debugging of a concrete failure. `snapshot` captures still frames and zoomed crops; `validate`, `inspect` and `layout` are deprecated because `check` covers them.
+
+## Discipline (motion-heavy work)
+
+For a concrete problem during authoring or editing:
+
+- Use `lint` for a static-code failure or `check --snapshots` for runtime/layout evidence, not both by default.
+- Look at the returned images before changing the animation: a diagnostic must not become an alternative art direction.
+- Treat layout errors as defects unless a snapshot proves the layering is intentional, in which case mark it with `data-layout-allow-overflow` / `data-layout-allow-overlap` / `data-layout-allow-occlusion` / `data-layout-allow-caption-zone` (caption band only).
+- Existing meaningful motion assertions may remain, but GG does not require a new `*.motion.json` sidecar for every video. Use rendered-pixel checks and the `video-qa` evidence process for liveness, especially for canvas/WebGL. No detector or screenshot proves playback was watched.
+
+## lint
+
+```bash
+hf lint                  # current directory
+hf lint ./my-project     # specific project
+hf lint --verbose        # info-level findings
+hf lint --json           # machine-readable
+```
+
+Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`). Catches missing `data-composition-id`, overlapping tracks on the same `data-track-index`, unregistered timelines, and GSAP/CSS transform conflicts.
+
+`<video>`/`<audio>` work at any nesting depth, including inside a `compositions/*.html` sub-composition or a wrapper `<div>`: the runtime discovers media with a flat DOM query and seeks/decodes it wherever it lives (`packages/core/src/runtime/{media,startResolver}.ts`). After a render, `snapshot` each scene that has a video and confirm the panel actually shows footage (a blank/black panel where a clip should play is a real bug, not a placeholder).
+
+## check
+
+```bash
+hf check                    # current directory: the full browser gate
+hf check ./my-project       # specific project
+hf check --json             # agent-readable envelope {ok, lint, runtime, layout, motion, contrast, hdr, snapshots}
+hf check --snapshots        # also write overview frames (annotated) + per-finding crops
+hf check --samples 15       # denser timeline sweep (default 9)
+hf check --at 1.5,4,7.25    # explicit hero-frame timestamps
+hf check --at-transitions   # also sample every tween start/end boundary
+hf check --tolerance 4      # allowed overflow px before reporting (default 2)
+hf check --timeout 30000    # initial render-ready + navigation minimum in ms (defaults: 3000 / 10000)
+hf check --no-contrast      # skip the WCAG audit while iterating
+hf check --strict           # exit non-zero on warnings too (default: only errors)
+```
+
+One command, one Chrome boot. `check` runs the linter first and skips the browser entirely when lint reports errors. Then it loads the bundled composition once, wires runtime listeners before navigation, and sweeps one seek grid running every audit per sample:
+
+- **Runtime**: JavaScript console errors, unhandled exceptions, failed network requests (media-file `ERR_ABORTED` filtered out), HTTP 4xx/5xx.
+- **Layout**: text extending outside its container or the canvas, text clipped by its own box, held text overlaps and occlusion (with an approximate covered fraction), children escaping clipping containers.
+- **Motion**: `*.motion.json` sidecar assertions against the same seeked timeline (see below).
+- **Contrast**: WCAG AA on visible text, sampled at 5 grid points. Failures are **errors** and each finding carries the sampled fg/bg colors, measured vs required ratio, and a suggested compliant color in the same palette direction, so most contrast fixes need no screenshot at all.
+
+Every finding carries a selector, the element's `data-*` identity, the composition source file, a bbox, and the sample time: jump straight from the JSON to the HTML you must edit and re-run.
+
+**Severity is persistence-aware.** A dynamic issue observed at a single grid sample (an entrance/exit transient) demotes to info and never gates. Issues held across samples gate the exit code, a held `content_overlap` is an error, and a held, partially-visible `canvas_overflow` breaching ≥5% of the canvas promotes to warning. Coordinate-frame findings (`escaped_container`, `panel_out_of_canvas`, `connector_detached`) flag geometry computed in one frame but rendered in another — an element far outside its offset parent, a painted panel stuck across the canvas edge, a connector line detached from every node. Text drawn into a `<canvas>` has no DOM box, so `canvas_overflow` cannot see it; `canvas_content_at_edge` warns when a canvas's pixels show sharp content (drawn text, hard shapes) along the frame edge — mark intentional full-bleed art (particles, photos) with `data-layout-allow-overflow`. If a 3s+ composition shows zero geometry change across every sample, `check` fails with `sweep_static`: a frozen timeline makes every green verdict unreliable, so it refuses to pass. The fingerprint includes per-element opacity, so opacity-only reveals (code typing, staggered fades) count as motion — but only while they're still in flight at the sampled times. The classic trap is a reveal that completes early and then holds a static frame for the rest of the duration: every sample lands on the settled state and the run fails. For a source-backed recipe, preserve that early reveal and reading hold. Diagnose with samples at its actual action times and the rendered-pixel result. Do not spread the reveal, add a blinking element or introduce drift to appease a heuristic. Report an unresolved detector conflict honestly rather than changing locked choreography or claiming a pass.
+
+**Escape hatches** (mark intent in the HTML, then re-run):
+
+- `data-layout-allow-overflow` — overflow is intentional (entrance/exit travel).
+- `data-layout-allow-overlap` — deliberate text layering (e.g. a demo cursor label over a heading). Applies only to the marked text block; it is not inherited. Mark the specific layering participant, never a scene/root wrapper, so unrelated descendant collisions remain auditable.
+- `data-layout-allow-occlusion` — an element is meant to cover text.
+- `data-layout-allow-caption-zone` — intentional lower-third / caption-band copy under `--caption-zone`. Applies to the marked element and every descendant (`closest`); silences only `caption_zone_collision` (not overflow/overlap/occlusion). Prefer the narrowest wrapper that owns the intentional band copy.
+- `data-layout-ignore` — decorative element that should never be audited.
+
+**Opt-in pipeline gates** (used by orchestrators; off by default):
+
+```bash
+hf check --caption-zone "x0=0;y0=.82;x1=1;y1=1;severity=error;seek=.25,1"
+hf check --frame-check     # media (img/svg/video/canvas) out-of-frame detection
+```
+
+`--caption-zone` takes fractional band geometry (`x0/y0/x1/y1` required, 0-1 fractions of the composition's own canvas, portrait included) with optional `severity` and comma-separated `seek` fractions; it flags a text element's DOM box (`getBoundingClientRect`) that overlaps the band. Waive intentional lower-third copy with `data-layout-allow-caption-zone` on the element or its nearest wrapper (see Escape hatches). `--frame-check` reports media elements breaching the canvas beyond `max(120px, 6% of the min canvas dimension)`.
+
+**Fixing contrast errors** — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold). The finding's `suggestedColor` already picks the nearest compliant color in the right direction (brighten on dark backgrounds, darken on light); apply an allowed correction, or resolve a conflict with locked source/brand colours before changing them. Recheck the changed output through `motion_check`; do not duplicate the full diagnostic checklist.
+
+## Motion verification (`*.motion.json` sidecar)
+
+`check` verifies **motion intent** against the same seeked timeline the renderer uses — the closest automated proxy for "render the MP4 and watch it". It catches render-vs-preview bugs layout sampling can't: an entrance reveal the seek lands past, a broken stagger order, an element drifting off-frame mid-tween, a frozen shot.
+
+Drop a `*.motion.json` sidecar next to the composition (matching the html basename when several compositions share a dir). `check` discovers it automatically — no flag, no authoring-framework changes. With no sidecar, `check` behaves exactly as before.
+
+```json
+{
+  "duration": 6,
+  "assertions": [
+    { "kind": "appearsBy", "selector": "#headline", "bySec": 0.5 },
+    { "kind": "before", "a": "#headline", "b": "#cta" },
+    { "kind": "staysInFrame", "selector": ".card" },
+    { "kind": "keepsMoving", "withinSelector": ".scene" }
+  ]
+}
+```
+
+| Assertion                      | Fails (code) when                                                           |
+| ------------------------------ | --------------------------------------------------------------------------- |
+| `appearsBy(selector, bySec)`   | not visible (opacity ≥ 0.5) by `bySec` — `motion_appears_late`              |
+| `before(a, b)`                 | `a` does not first appear strictly before `b` — `motion_out_of_order`       |
+| `staysInFrame(selector)`       | once visible, its box leaves the canvas — `motion_off_frame`                |
+| `keepsMoving(withinSelector?)` | a fully-static window exceeds `maxStaticSec` (default 2s) — `motion_frozen` |
+
+`duration`, `withinSelector`, and `maxStaticSec` are optional. Findings are **errors by default** and appear in the same human and `--json` output as layout findings. A selector that matches nothing is reported as `motion_selector_missing` rather than silently passing — a typo'd selector fails loudly. Use this in the feedback loop instead of eyeballing the render: assert what the motion is supposed to do, and let `check` tell you when the seek diverges from intent.
+
+## snapshot
+
+```bash
+hf snapshot                       # 5 key frames as PNG
+hf snapshot ./my-project          # specific project
+hf snapshot --frames 10           # evenly-spaced N frames
+```
+
+Captures still PNGs from the composition for visual diffing, thumbnails, or attaching to a PR. Faster than rendering a video when you only need a few hero frames. Output lands in the project's snapshots directory. Not deprecated: it remains the standalone capture utility, while `check --snapshots` covers the gate's needs (overview frames annotated with labeled finding boxes, plus `finding-NN-<code>.png` crops for every error finding with a bbox).
+
+### Zooming into a reported finding
+
+`hyperframes check --snapshots` already writes a `finding-NN-<code>.png` crop for every error finding that carries a bbox, but the same zoom is available standalone once you know what to look at:
+
+```bash
+hf check --snapshots               # reports a finding, e.g. content_overlap on "#cta"
+hf snapshot --zoom "#cta"           # crop the element to verify the defect, at 3x density
+hf snapshot --zoom "100,50,400,300" --zoom-scale 2   # or an exact pixel region
+# fix the composition HTML, then re-check:
+hf check
+```
+
+`--zoom` takes a CSS selector or an exact `x,y,w,h` pixel region and always produces a real high-density crop (a raised `deviceScaleFactor`, never CSS zoom or a viewport resize), so the composition's layout — and its render determinism — is untouched. A selector matching nothing is a loud error, not a silent full-frame fallback, and a frame where the target has no visible box (collapsed or animated off-canvas) is skipped with a note instead of written as a sliver.
+
+## Deprecated: validate, inspect, layout
+
+All three keep working, print a deprecation notice on stderr, and mark `_meta.deprecated: true` in `--json`. Their functionality lives in `check`:
+
+- `validate` (runtime errors + contrast) → `check` (contrast failures are now gating errors with fix payloads, not warnings).
+- `inspect` / `layout` (layout sweep + motion sidecar) → `check` (same flags: `--samples`, `--at`, `--at-transitions`, `--tolerance`, `--strict`).
+
+Migrate scripts by replacing the sequence with the single `check` invocation; scaffolded projects' `npm run check` already points there.

package/assets/motion/references/runtime/minimal-composition.md

@@ -0,0 +1,75 @@
+# Minimal Composition
+
+The smallest renderable HyperFrames composition — a standalone (top-level) root with one clip and one tween:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1920, height=1080" />
+    <title>Minimal HyperFrames Composition</title>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      body {
+        margin: 0;
+        background: #0b0f14;
+        color: white;
+        font-family: Inter, system-ui, sans-serif;
+      }
+      #root {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+      }
+      .clip {
+        position: absolute;
+        inset: 0;
+        display: grid;
+        place-items: center;
+      }
+      h1 {
+        margin: 0;
+        font-size: 96px;
+      }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-width="1920"
+      data-height="1080"
+      data-duration="5"
+    >
+      <section id="title-card" class="clip" data-start="0" data-duration="5">
+        <h1 id="title">Hello HyperFrames</h1>
+      </section>
+    </div>
+    <script>
+      const tl = gsap.timeline({ paused: true });
+      tl.from("#title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0.2);
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+What the runtime actually requires:
+
+- Root `<div>` with `data-composition-id`, `data-width`, `data-height`. Root `data-start="0"` is written above by convention and every shipped block has it, but the runtime stamps it when absent, so it is not required.
+- A duration source: root `data-duration` (as above), or a GSAP timeline, or media, or an adapter that can infer one.
+- Timed elements carry `data-start` plus a duration. That attribute alone is what makes an element a clip: `class="clip"` is a layout and tooling convention, and `data-track-index` is a Studio display lane. Neither is required, and a composition with no clips at all renders fine.
+- A GSAP timeline created paused and registered on `window.__timelines["<composition-id>"]`.
+
+Everything else in the skeleton is ordinary HTML and CSS: the `#root` box, `.clip` positioning, and fonts are yours to choose.
+
+This pattern is **standalone** (top-level `index.html`) — no `<template>` wrapper around the root. For sub-compositions (files loaded by `data-composition-src`), see `sub-compositions.md`.
+
+## Vertical (9:16)
+
+For phone-first video, set the viewport meta to `width=1080, height=1920`, give the root `data-width="1080"` and `data-height="1920"`, and render with the matching size (`--resolution portrait`). Everything else stays the same.
+
+Size type against the frame's width, not its height: a 96 px headline that suits a 1920 px-wide frame takes over half the width of a 1080 px one, so check that the longest word fits. When the video will play in a feed (Reels, TikTok, Shorts), keep text, logos and key subjects out of the areas the app covers. Meta asks for the top 14%, the bottom 35% and 6% on each side to stay clear (about 270 px, 670 px and 65 px at 1080×1920); TikTok covers a similar band at the bottom and a column of buttons on the right.