@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/pixel2motion/SKILL.md

@@ -1,279 +0,0 @@
----
-name: pixel2motion
-description: "Turn a raster logo (PNG/JPG/WebP/screenshot) into a clean minimal SVG with edge smoothness as the primary hard gate and IoU optimized as high as reasonably possible without a fixed global threshold, then into a choreographed logo animation delivered as standalone JS-rendered HTML, applying Disney's 12 animation principles. Use when asked to animate a logo, build a logo reveal / splash screen / brand intro, convert a logo image into animated SVG or HTML, add motion to a vectorized mark, or create loading/idle/hover motion for a brand mark. v2: also handles self-crossing draw-on choreography (split-fill, exact easing subdivision, tip glint), closed variable-width ribbon fitting, and quantitative motion QA (easing probe, ink-delta continuity sweep). Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "nolangz/pixel2motion"
----
-
-# Pixel2Motion (v2)
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-**Pixel → Vector → Motion.** This skill fuses two disciplines:
-
-1. **Vectorization discipline** (from logo-vectorizer-minimal-smooth): fit the raster source with the *lowest-complexity* editable geometry that passes visual QA.
-2. **Motion discipline** (from Disney's 12 Principles of Animation): choreograph that geometry into brand-appropriate motion with evidence-based timing and easing.
-
-The fusion rests on one insight: **minimal smooth geometry IS animatable geometry**. A logo built from 3 semantic parts animates cleanly; a logo built from 400 pixel-stair traced points cannot be choreographed or accepted as a professional logo vector. Phase 2 therefore does not merely vectorize — it *structures for motion*. And the animation must always land exactly on the QA-verified static vector (the **Final Frame Contract**).
-
-## Deliverables
-
-- `logo.svg` — final static vector (motion-ready structure)
-- `logo_motion.html` — showcase-style standalone HTML with the main animation, atomic motion studies, replay/slow/speed controls, and QA hooks
-- `motion_spec.md` — personality words, principles applied, timeline table, easing tokens, atomic motions, tunable controls
-- `outputs/fit_iterations/*.png` + `overlay_progress_strip.png` — geometry QA evidence
-- `outputs/motion_frames/*.png` + `motion_strip.png` — motion QA evidence
-- `final_render.png`, `html_render.png` — static renders; path audit artifacts when smoothness was a concern
-
----
-
-## Phase 1 — PIXEL: Read the source, write the brief
-
-1. **Analyze the raster source.** Record image size, mode, alpha, foreground colors, background (transparent/solid). Identify the *semantic parts*: mark vs wordmark, individual letters, dots, swooshes, containers, negative space. Each part is a future actor in the animation.
-2. **Write the motion brief** before touching geometry:
-   - **Personality**: 3 brand motion words (e.g. "swift, precise, confident"). Derive from the logo's own visual language (geometric = engineered motion, organic = flowing motion, rounded = soft/bouncy) plus any user-stated brand context. See `references/motion-personality.md` to map words → timing scale, easing tokens, principle emphasis.
-   - **Usage context**: splash/intro (deliberate 1200–2000ms), header reveal (300–800ms), loading state (continuous loop), hover micro-interaction (150–300ms). Ask the user only if genuinely ambiguous; default to a splash-style reveal plus a static end state.
-   - **Choreography sketch**: which parts move, in what order, using which reveal pattern (see `references/reveal-patterns.md`).
-3. Record the brief in `motion_spec.md`. Every later parameter must trace back to it.
-
-## Phase 2 — VECTOR: Fit minimal geometry, structured for motion
-
-Follow the lowest-complexity-first workflow. **Do not maximize pixel-fit by default**; start with the simplest editable geometry that can explain the mark, escalating only when an overlay shows a structural mismatch.
-
-### Complexity Ladder
-
-Use the first level that matches the source well enough:
-
-1. **Primitives**: circles, ellipses, rects, lines, simple arcs, transforms.
-2. **Primitive composites**: boolean-like combinations of a few primitives or masks.
-3. **Few-curve analytic paths**: a small number of cubic segments for smooth ribbons, swooshes, C-marks, leaves, waves, shields. For closed and/or self-intersecting variable-width ribbons (∞ marks, scripts) use the centerline-scaffold recipe — `references/ribbon-fitting.md` + `scripts/fit_ribbon_centerline.py`; its report also emits each crossing's arc fractions, which Phase 3's split draw-on needs.
-4. **Smoothed outline paths**: more knots only where the source has real shape changes; preserve G1 tangent continuity, no noisy handle flips.
-5. **Trace-derived paths**: only for irregular silhouettes where simpler geometry fails (`scripts/raster_logo_trace.py` for measurement/starter masks). Trace output is a measurement aid, never automatically final art. Smooth or refit the trace before delivery.
-
-If a higher-complexity version improves only pixel antialiasing, keep the lower one. If a lower-complexity version has wrong endpoints, width profile, center, silhouette, negative space, or visibly stair-stepped edges, move up one level or refit with smooth curves. Prefer live SVG `<text>` for wordmarks unless exact letterforms are required. Decide the provisional complexity from the source itself and record the reason in `motion_spec.md`.
-
-### Smoothness Gate (hard requirement)
-
-IoU is not allowed to hide bad vector craft. **A smooth logo source must ship as smooth vector geometry.** The final SVG fails geometry acceptance if any intended smooth edge visibly stair-steps, chatters, has pixel-grid orthogonal runs, contains noisy trace knots, or looks like a bitmap mask at 200-400% zoom, even when IoU is numerically high.
-
-- Pixel-grid contours from threshold masks are acceptable only as starter measurements or for genuinely pixel-art logos. For ordinary logos, refit them into primitives, arcs, ellipses, or cubic paths before Phase 3.
-- A path made mostly of 1px horizontal/vertical line segments is a failed smoothness gate for curves, swooshes, ellipses, circles, letters, and rounded shapes.
-- Smooth parts must be represented by the lowest number of curve segments that preserves silhouette, width profile, extrema, and negative space. Do not chase antialiasing with hundreds of line segments.
-- When replacing a high-IoU jagged trace with a smoother curve slightly lowers IoU, prefer the smooth version if structural landmarks still match. The smooth result may pass with a lower IoU when the residuals are explainable, visually minor, and caused by deliberate smoothing, antialiasing, font substitution, or raster-source artifacts. Record the tradeoff in `motion_spec.md`.
-- Inspect a zoomed render (`final_render.png` or a dedicated zoom crop) before accepting. If the user would notice stair-stepping in a screenshot or browser zoom, the vector is not accepted.
-
-### Motion-Ready Structure (the fusion layer)
-
-The SVG is a cast of actors, not just a picture. While fitting geometry, enforce:
-
-- **One element (or `<g>`) per semantic part**, with stable ids: `#mark`, `#wordmark`, `#letter-a`, `#dot`, `#swoosh`. Animation targets ids/classes — never structural selectors like `path:nth-child(3)`.
-- **Split paths along animation seams.** If the choreography sketch animates the swoosh separately from the dot, they must be separate elements even if one compound path could render both.
-- **Transform origins**: parts that scale/rotate get `transform-box: fill-box; transform-origin: center` (or a deliberate origin) — set via CSS in Phase 3, but verify each part's bounding box makes that origin sensible now.
-- **Draw-on readiness**: any stroke that will be drawn on gets `pathLength="1"` so dash animation is `stroke-dasharray: 1; stroke-dashoffset: 1 → 0` regardless of true length. Confirm the path's start point and direction match the intended draw direction; reverse the path if not.
-- **Wordmark letters**: if letters will stagger, give each its own element/`<text>` span; a single `<text>` cannot cascade.
-- **No baked transforms that fight choreography**: keep part-local coordinates simple so animated transforms compose predictably.
-
-### Geometry QA (evidence required)
-
-- Write SVG with a correct `viewBox`; render to PNG; generate a cyan overlay over the source; save every overlay under `outputs/fit_iterations/NN_name_overlay.png`.
-- Inspect overlays with multimodal vision: centers, radii, endpoints, width profile, extrema, negative space, silhouette.
-- Compute and record IoU every iteration, but do **not** use a fixed global IoU threshold. Optimize IoU as high as reasonably possible after smoothness and structural correctness are protected. A slightly lower IoU can pass when the overlay is visually faithful and residuals are documented; a high-IoU fit still fails if it has structural mismatches, noisy handles, visible bumps, wrong negative space, pixel-stair edges, or path-audit failures.
-- Iterate one complexity level at a time; prefer moving/retuning a few knots before adding knots; add local complexity only where the overlay proves failure. If a path looks bumpy, reduce knots and re-fit macro curves — do not add points.
-- For complex smooth paths or any hand-fitted curve that feels uneven, run `scripts/svg_path_audit.py` (noisy handles, tangent jumps, tiny alternating segments, and stair-step trace runs are failures even at high IoU).
-- Save at least one smoothness evidence image when the source has curves: a zoomed crop, path audit artifact, or render that makes edge quality inspectable. Record the visual verdict in `motion_spec.md`.
-- Finish with `scripts/overlay_progress_strip.py` (source + current-run overlays + final render only).
-
-### Iteration budget: smooth accepted fit or best-of-10
-
-Fitting loops rabbit-hole easily. Default budget: **10 geometry iterations per run** (one iteration = one geometry change + render + overlay inspection). The loop stops when either one arrives first: **accepted fit** (smoothness, structural, and visual checks pass, with IoU pushed as high as practical) or **10 iterations attempted**.
-
-- Number every iteration's artifacts (`NN_name_overlay.png`) and record metrics per iteration (IoU, `src_only_px`, `render_only_px`, boundary RMS / local residuals, audit warnings, smoothness verdict, visual verdict). Persist the fitting scripts and parameters under `outputs/fit_work/` so any iteration can be resumed later — never leave them in throwaway temp paths.
-- Reaching accepted fit early ends the loop early; proceed to Phase 3 immediately.
-- When the 10-iteration budget is exhausted: stop refining and select the best candidate. Ranking for "best": (1) smoothness gate pass, (2) no structural mismatch, (3) IoU and pixel deltas, (4) boundary RMS / local residuals, (5) fewest audit kinks and tangent issues, (6) visual overlay verdict, (7) lowest editable complexity. A clean-but-slightly-loose fit generally beats a tighter fit with a visible tangent kink; an invisible kink may ride along only as a disclosed known issue.
-- If the shipped candidate has a lower IoU than another rejected candidate, report why it still passes or why it is only a preview (e.g. "IoU is lower because jagged threshold artifacts were smoothed; endpoints and silhouette landmarks match"). Geometry-only refinement does not require redoing the choreography — part ids and the centerline survive, so `motion.css` is reusable and only re-packaging (`animate_svg_showcase.py`) plus the Final Frame Contract re-check are needed.
-
-## Phase 3 — MOTION: Choreograph with the 12 principles
-
-Choreograph against `references/twelve-principles-for-logos.md`. Minimum bar: every animation consciously applies **Staging, Slow In/Slow Out, Timing, Follow Through, and Appeal**; the rest as personality demands.
-
-### Structure the timeline with the Golden Ratio
-
-```
-Anticipation : Action : Follow-through  =  20% : 50% : 30%
-```
-```
-For a 1500ms reveal: ~300ms anticipation, ~750ms main action, ~450ms settle. Stagger overlapping parts by 10–20% of the part's own duration; never let all parts start or stop on the same frame (the #1 mechanical-motion mistake). Heavier/larger parts move slower; the drag hierarchy (root → primary → secondary → tertiary detail) orders the cascade.
-```
-
-### Derive parameters, don't invent them
-
-Pick the duration band from usage context, easing tokens and exaggeration level from the personality mapping, and the reveal pattern from the part inventory. `references/reveal-patterns.md` has annotated, principle-tagged patterns: draw-on, staggered assembly, scale-pop with overshoot, mask wipe, morph-from-primitive, letter cascade, plus idle loops and hover states. Define CSS custom properties (`--p2m-duration`, `--p2m-ease-*`) once and use them everywhere — brand consistency lives in tokens. **Exception that overrides this rule: inside `@keyframes`, timing functions must be literal** (see Implementation) — a token referenced there is silently dropped and the motion degrades to linear without any error.
-
-### Implementation
-
-- Read `references/html-delivery-template.md` before building `logo_motion.html`.
-- Author the main animation as **CSS keyframes targeting the part ids** in `motion.css`, or as a bespoke JS act/phase timeline when the choreography needs measured pivots, live sequencing, or per-letter layout. If using JS, preserve the same QA hooks described below.
-- CSS keyframes must use `animation-fill-mode: both` or `forwards`; otherwise deterministic `?t=<ms>` frame capture and `?static=1` final-state checks are not reliable.
-- **Keyframe easing must be literal.** `animation-timing-function: var(--token)` inside `@keyframes` does not resolve in Chromium: the declaration is silently dropped and the segment falls back to the animation's base timing function — usually `linear`, the exact mechanical look the principles forbid. Worse, multi-piece choreography whose pieces were paced by subdivided easings degrades to per-piece constant speeds with **speed cliffs at every handoff** (a measured 4.3× velocity discontinuity read as a "stutter"). Keep tokens for `animation:` shorthands (durations/delays resolve fine) and documentation, but write literal `cubic-bezier(...)` in every keyframe, with a comment naming the token. This failure is invisible in casual playback and in evenly-spaced frame strips — verify with the easing probe (Motion QA step 3).
-- **Author all part animations on one shared clock** (one duration, phase offsets as intra-keyframe percentages) so `?t=<ms>` maps 1:1 to the choreography and probes/captures stay trivial to reason about.
-- Prefer a single-keyframes-per-element design; when one element needs independent property timelines (e.g. eased movement + linear fades), use comma-separated parallel animations on the same clock.
-- Build the default deliverable with `scripts/animate_svg_showcase.py` — it recreates the main SVG via JavaScript DOM calls, wraps motion CSS for reduced-motion safety, and adds a template shell with atomic motion studies, principles strip, replay button, slow-motion toggle, speed slider, `?t=<ms>`, `?static=1`, and `window.__p2mReady`.
-- `scripts/animate_svg_html.py` remains a minimal fallback for QA or debugging; it is not the preferred final user-facing HTML because it lacks the atomic motions and tuners.
-- The HTML must stay dependency-free and derived from the same geometry as `logo.svg`; atomic variants must reuse the same mark, not separate decorative redraws.
-- The default HTML motion stage displays the main logo at **0.7x of the SVG's intrinsic width** (`width * 0.7`, still capped by the viewport). This leaves breathing room around the animation and reduces clipping risk. QA screenshots may override the viewport/crop, but the user-facing template should keep the 0.7x presentation scale.
-- **Reduced motion is mandatory**: under `prefers-reduced-motion: reduce` the logo must appear immediately in its final static state.
-- Infinite loops (loading/idle) must be seamless: the 100% keyframe state must equal the 0% state; test mentally at 30 seconds — still pleasant?
-
-### Draw-on across self-intersections
-
-A wide masked draw stroke following a self-crossing centerline (∞ marks, script signatures, monograms) prematurely reveals the *other* branch wherever the paths cross — an "X" pops in before the pen draws it. When the centerline self-intersects, apply the **split-fill recipe** in `references/reveal-patterns.md` §1b: cut the fill into pieces between crossing passes (each with its own mask spine), use **butt caps** with dash pattern `1 1` (round caps make the visible tip lead the pen by half the stroke width — it stalls at every handoff, then the next piece pops in as a cap-radius disk), subdivide the global easing **exactly** (de Casteljau) so the combined pace equals the design, and bridge the paint-under-ink dead window at the later pass with a tip glint riding `offset-path`. The dash-math artifact table in the same reference prevents the t=0 cap-dot and tail-leak artifacts. Get the cut fractions from `scripts/fit_ribbon_centerline.py`'s report (it emits each exclusion's arc fractions). Prove the fix with frames around each crossing pass plus the continuity sweep (Motion QA step 4).
-
-### Showcase HTML requirements
-
-The final HTML must follow the provided template pattern:
-
-- **Main animation**: a primary hero stage in `#logo-root`, replayable by click/tap and by the Replay button.
-- **Atomic motions**: at least 3 small studies such as hover, pulse, arc/spin, press/squash, draw-on, or letter cascade. They should demonstrate isolated motion principles and target semantic parts when practical.
-- **Tuners**: replay button, slow-motion toggle, and speed slider. The speed slider must affect the live main animation, not only future replays.
-- **Principles strip**: compact pills for the principles used; when using a JS timeline, highlight active principles during the phase where they are visible.
-- **QA hooks**: keep `#logo-root`, `?t=<ms>`, `?static=1`, and `window.__p2mReady` compatible with `scripts/capture_motion_frames.py`.
-
-### Motion QA (evidence required)
-
-1. Capture frames at choreography-significant timestamps with `scripts/capture_motion_frames.py` (uses the `?t=` hook for deterministic seeking): at minimum t=0, end of anticipation, mid-action, peak overshoot, settle, and final — **plus every risk window**: each crossing pass, piece handoff, and occluder entry/exit gets its own bracketing frames (a strip of evenly-spaced beats hides handoff defects entirely).
-2. Inspect the strip with multimodal vision: Does anticipation read? Do parts cascade rather than move in lockstep? Does overshoot stay within personality bounds? Is anything clipped by the viewBox mid-flight (expand viewBox or rein in the motion — never let the logo clip)?
-3. **Probe the easing actually applied** with `scripts/probe_motion_continuity.py --probe`: read computed values (`stroke-dashoffset`, `offset-distance`, …) at 2–3 seeked timestamps and compare against the designed curve. Values matching the LINEAR window fraction at every timestamp mean a keyframe timing function was silently dropped (see the literal-easing rule). The t=0 frame must also be checked for dash artifacts (cap ink-dot, tail leak).
-4. **Continuity sweep across risk windows** with `--ink-sweep`: ink-pixel deltas every ~10ms across handoffs/crossings. A flatline followed by a jump is the stall+pop signature and fails the run. A single near-zero sample where the pen passes *under* already-painted ink is physical — bridge it perceptually (tip glint), don't leave it bare.
-5. **Final Frame Contract**: the captured final frame must match `final_render.png` (the QA-verified static vector) in geometry, color, scale, and position. Use `--compare-final` for a cross-pipeline pixel-diff number, then run the decisive **same-pipeline check**: capture `?static=1` and `?t=<end>` with the same tool, viewport, and DPR — these must match **exactly (0 diff)**. Cross-pipeline residue (different renderer/DPR/resampling) is noise to confirm visually, not chase numerically. An animation that lands somewhere else than the verified logo fails the run.
-6. For loops, capture one frame just before and just after the seam; they must be visually identical.
-7. Assemble `motion_strip.png` as the motion analog of the overlay progress strip.
-
----
-
-## Bundled Scripts
-
-# Phase 2 — measurement / starter trace (inspect & simplify its output; never final art by default)
-python3 scripts/raster_logo_trace.py source.png --out outputs
-
-# Phase 2 — render + cyan overlay + IoU metrics in one step (headless Chrome; set CHROME_BIN if needed)
-python3 scripts/render_overlay.py logo.svg source.png \
-  --out outputs/fit_iterations/02_refined_overlay.png \
-  --render-out outputs/final_render.png --report outputs/fit_metrics.json
-
-# Phase 2 — closed / self-intersecting variable-width ribbons (∞ marks, scripts):
-
-# centerline scaffold + auto-recenter + source edge snap; report includes each
-
-# exclusion's arc fractions (= split-cut parameters for Phase 3)
-python3 scripts/fit_ribbon_centerline.py source.png --seeds seeds.json --out-dir outputs/ribbon_fit
-
-# Phase 2 — Bezier smoothness audit before accepting complex paths
-python3 scripts/svg_path_audit.py logo.svg --out-svg bezier_segments.svg --report bezier_audit.json
-
-# Phase 2 — geometry QA strip
-python3 scripts/overlay_progress_strip.py --source source.png --dir outputs/fit_iterations \
-  --pattern "*overlay*.png" --final-image outputs/final_render.png --out outputs/overlay_progress_strip.png
-
-# Phase 3 — static HTML (intermediate check of JS DOM reconstruction)
-python3 scripts/svg_to_js_html.py logo.svg --out logo_static.html --title "Logo"
-
-# Phase 3 — animated showcase HTML deliverable
-python3 scripts/animate_svg_showcase.py logo.svg --css motion.css --out logo_motion.html \
-  --title "Logo Motion" --duration-hint 1500
-
-# Phase 3 — minimal fallback HTML (debug/QA only, not preferred final delivery)
-python3 scripts/animate_svg_html.py logo.svg --css motion.css --out logo_motion_minimal.html \
-  --title "Logo Motion" --duration-hint 1500
-
-# Phase 3 — deterministic frame capture + strip + final-frame diff (requires playwright)
-python3 scripts/capture_motion_frames.py logo_motion.html \
-  --times 0,300,700,1000,1250,1500 --out outputs/motion_frames \
-  --strip outputs/motion_strip.png --compare-final outputs/final_render.png
-
-# Phase 3 — easing probe: is the designed curve the one the browser runs? (requires playwright)
-python3 scripts/probe_motion_continuity.py logo_motion.html \
-  --times 500,700,900 --probe "#draw-stroke:stroke-dashoffset,#pen-glint:offset-distance"
-
-# Phase 3 — ink-delta continuity sweep across handoffs/crossings (requires playwright)
-python3 scripts/probe_motion_continuity.py logo_motion.html --ink-sweep 850:1010:10
-```
-Environment notes: Pillow/numpy via a venv when system Python is externally managed (`python3 -m venv .venv && .venv/bin/pip install pillow numpy`); geometry rendering uses headless Chrome (`CHROME_BIN` if needed), while motion frame capture requires Playwright or equivalent deterministic browser screenshot tooling.
-
-If Playwright is unavailable, use any real-browser screenshot tooling available in the environment with the same `?t=<ms>` URLs; wall-clock screenshots of a running animation are not acceptable evidence (non-deterministic).
-```
-
-## Acceptance Criteria
-
-Completion requires evidence, not claims:
-
-**Geometry (inherited):**
-- `logo.svg` exists, renders, and uses the lowest complexity that passes overlay QA and the smoothness gate; structural mismatches (center, scale, endpoints, width profile, spacing, negative space, silhouette) are absent; smooth marks pass visual zoom inspection and path audit when budgeted or when curves felt uneven.
-- Report final IoU and pixel deltas, but do not apply a fixed global IoU pass/fail value. IoU should be as high as practical after preserving smoothness and structural correctness. If a lower-IoU result passes, explain exactly why the residuals are acceptable.
-- Final geometry must not contain visible stair-stepped edges on intended smooth shapes. A jagged trace with excellent IoU is rejected unless the source is deliberately pixel art and this is explicitly documented.
-- `overlay_progress_strip.png` shows source → current-run iterations → final render.
-- **Budgeted delivery**: if the 10-iteration budget ran out, shipping the best-of-run geometry is acceptable when smoothness, structure, and visual QA pass and the residuals are disclosed. If residuals are not acceptable, label the output as a preview, keep the fit state resumable from `outputs/fit_work/`, and offer continued refinement. The Final Frame Contract applies to whatever geometry shipped.
-
-**Structure (fusion):**
-- Every choreographed part is an independently addressable element with a stable id; draw-on paths carry `pathLength="1"`; the part inventory in `motion_spec.md` matches the SVG structure.
-
-**Motion (new):**
-- `logo_motion.html` follows the showcase template: main animation in `#logo-root`, atomic motion studies, replay/slow/speed controls, principles strip, dependency-free execution, `prefers-reduced-motion`, `?t=` seeking, `?static=1`, and `window.__p2mReady`.
-- The speed control changes playback for the currently running main animation; Replay restarts deterministically; atomic motions are visibly interactive/moving and derived from `logo.svg`.
-- The choreography demonstrably applies the principles claimed in `motion_spec.md`; timeline follows the 20/50/30 shape (or documents why not); no two parts share identical start+end times unless intentional staging.
-- `motion_strip.png` exists and has been inspected with multimodal vision; nothing clips mid-flight.
-- **Easing verified applied** (probe at 2–3 timestamps; not linear-by-accident) and **no stall+pop signature** in the continuity sweep across handoffs/crossings.
-- **Final Frame Contract holds**: captured final frame ≡ verified static render (cross-pipeline diff reported + visual confirmation, same-pipeline `?static=1` vs `?t=<end>` exact). Loops are seam-checked.
-- IoU is a required reported diagnostic but not a fixed-threshold gate for the full motion deliverable: a technically smooth animation fails if it is off-personality, mechanical (lockstep parts, linear easing), or lands off the verified logo.
-
-## References
-
-- `references/twelve-principles-for-logos.md` — each Disney principle with logo-specific application and parameter ranges
-- `references/motion-personality.md` — brand personality → timing scale, easing tokens, exaggeration bounds, principle emphasis
-- `references/reveal-patterns.md` — choreography pattern library: reveals, idle loops, hover states, with timing tables and CSS skeletons; §1b split-fill draw-on for self-crossing marks + dash-math artifact table
-- `references/html-delivery-template.md` — required final HTML structure: main animation, atomic motions, tuners, principles strip, QA hooks
-- `references/ribbon-fitting.md` — closed/self-intersecting variable-width ribbon fitting (centerline scaffold + recenter + source edge snap) and wordmark font matching
-
-## v2 changelog
-
-Hardened from a production run (calligraphic ∞ + bead + serif wordmark) where the draw-on visibly stuttered at the second self-crossing. Three stacked causes were isolated and each produced a new rule or tool:
-
-1. `var()` timing functions inside `@keyframes` silently degrade to linear in Chromium → literal-easing rule + easing probe (`scripts/probe_motion_continuity.py --probe`). This was the dominant cause: per-piece linear pacing created a 4.3× speed cliff at the piece handoff.
-2. Round-cap draw masks make the visible tip lead the pen by half the stroke width → stall+pop at handoffs (measured 50ms flatline + cap-disk jump) → butt-cap dash recipe + dash-math artifact table + ink-delta continuity sweep (`--ink-sweep`).
-3. The later crossing pass paints *under* existing ink → a physically unavoidable ~10–25ms dead window → tip-glint secondary action (offset-path on the centerline, base opacity 0, exits under an occluder).
-
-Also new: split-fill recipe for self-crossing draw-ons with exact de Casteljau easing subdivision (reveal-patterns §1b), `scripts/fit_ribbon_centerline.py` + `references/ribbon-fitting.md` for closed variable-width ribbon geometry (its report emits the split-cut arc fractions Phase 3 needs), same-pipeline Final Frame Contract check (exact-0 expectation), and risk-window frame bracketing in Motion QA.
-
-## Source
-
-Rewritten for AICUT from [`nolangz/pixel2motion`](https://github.com/nolangz/pixel2motion)
-(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/pixel2motion/references/html-delivery-template.md

@@ -1,42 +0,0 @@
-# HTML Delivery Template
-
-Use this contract for the final `logo_motion.html`. The CueRecord sample is the model: one HTML file that presents the main logo animation, small atomic motion studies, and live playback controls.
-
-## Required Page Structure
-
-- Hero stage: a centered primary SVG animation in `#logo-root`; this is the element captured by QA tooling. User-facing motion templates should display the main logo at 0.7x of the SVG's intrinsic width, still capped by the viewport.
-- Atomic motions row: three or four small variants derived from the same `logo.svg`, such as hover, pulse, arc/spin, and press/squash. These are motion atoms, not unrelated decoration.
-- Controls: replay button, slow-motion toggle, and speed range slider. The speed slider must affect the live main animation, not only the next replay.
-- Principles strip: compact pills for the Disney principles used by the choreography; highlight active principles during the run when using a JS timeline.
-- Footer/help text may be minimal, but do not use explanatory marketing copy.
-
-## Main Animation
-
-- Prefer an act/phase timeline for logo reveals: staging hold, anticipation, action, overlap/follow-through, final settle.
-- Use explicit SVG transform pivots for complex marks. A helper like `T(px, py, {x, y, sx, sy, rot})` is safer than relying on CSS `transform-origin` when SVG bounding boxes are awkward.
-- Store the finished logo state in a `setFinalLogo()` function or equivalent. Reduced motion and `?static=1` must land there.
-- CSS keyframe animations must use `animation-fill-mode: both` or `forwards` so `?t=<ms>` and `?static=1` can expose real timeline states.
-- Keep `window.__p2mReady = true` only after the animation is rendered, seeked, or static-finalized.
-
-## Atomic Motions
-
-- Build atoms from the same semantic parts used by the main SVG (`#mark`, `#dot`, `#wordmark`, letters, accents).
-- Each atom should isolate one principle or interaction: hover appeal, ambient pulse, arc/spin, press squash, draw-on, or letter cascade.
-- Atomic variants must be interactive or visibly moving, but they must not distract from the hero animation.
-- If a generic script clone cannot safely preserve unique IDs, use a data-URI image fallback for atomic thumbnails and hand-author semantic atomic variants when the user expects production polish.
-
-## Tuners
-
-- Replay restarts the main animation deterministically.
-- Slow motion toggles to a readable default around 0.25x.
-- Speed slider default should be slow enough to inspect the principles, often around 0.4x to 0.6x for showcase delivery.
-- Playback-rate changes should apply to currently running animations.
-
-## QA Hooks
-
-- `?t=<ms>` pauses the main animation at an exact timestamp for frame capture.
-- `?static=1` shows the final static logo.
-- In QA/chromeless mode, hide controls and atomic variants if needed, but keep `#logo-root` available for screenshots.
-- `prefers-reduced-motion: reduce` must show the finished static logo immediately.
-- The `?t=` hook also powers quantitative QA: `scripts/probe_motion_continuity.py` reads computed styles at seeked timestamps (catches silently-dropped keyframe easings — see the literal-easing rule) and sweeps ink-pixel deltas across risk windows (catches handoff stalls/pops invisible in coarse frame strips).
-- The decisive Final Frame Contract check is SAME-pipeline: capture `?static=1` and `?t=<end>` with the same tool/viewport/DPR and require an exact 0 diff; cross-pipeline diffs against the Phase 2 render contain resampling noise and are confirmed visually.

package/skills/pixel2motion/references/motion-personality.md

@@ -1,109 +0,0 @@
-# Motion Personality: Brand → Parameters
-
-Translate brand identity into motion parameters systematically. Never pick easing or duration by taste — derive them here, record the derivation in `motion_spec.md`.
-
-## Step 1 — Locate the brand on two axes
-
-- **Energy**: low (calm, premium, institutional) ↔ high (sporty, startup, entertainment)
-- **Tone**: serious (finance, health, enterprise) ↔ playful (consumer, kids, social)
-
-Read the logo itself for evidence: sharp geometric forms → engineered/serious motion; organic curves → flowing motion; rounded shapes and bright colors → soft/playful motion. User-stated brand words override visual inference.
-
-## Step 2 — Axis → principle parameters
-
-| Principle | Low energy | High energy |
-|---|---|---|
-| Squash & Stretch | 0–10% | 20–40% |
-| Anticipation | 50–100ms | 150–300ms |
-| Part timing | 400–800ms | 100–250ms |
-| Exaggeration | 0–15% | 25–50% |
-| Follow-through | extended soft settle | quick bounce |
-
-| Principle | Serious | Playful |
-|---|---|---|
-| Arcs | direct, near-linear paths | curved, bouncy paths |
-| Secondary action | minimal (shadow, fade) | abundant (sparkle, ripple) |
-| Squash & Stretch | replace with plain scale | embrace |
-| Appeal style | clean, geometric | round, organic |
-
-## Step 3 — Personality presets
-
-Pick the closest preset, then adjust from the axes. Each preset gives the **token set** to define once as CSS custom properties.
-
-> **Token trap (Chromium)**: custom properties do NOT resolve in `animation-timing-function` declarations inside `@keyframes` — `animation-timing-function: var(--p2m-ease-enter)` is silently dropped and the segment runs with the animation's base timing function (usually `linear`), the exact mechanical motion these presets exist to prevent. Nothing errors and evenly-spaced frame strips look fine. Use the tokens in `animation:` shorthands (durations/delays resolve correctly) and as documentation, but write literal `cubic-bezier(...)` values inside keyframes with a comment naming the token. Verify with `scripts/probe_motion_continuity.py --probe`.
-
-### Playful / Joyful (consumer apps, kids, social)
-```css
---p2m-duration: 900ms;            /* reveal total; loops 1500-2000ms */
---p2m-ease-enter: cubic-bezier(0.34, 1.56, 0.64, 1);  /* overshoot */
---p2m-ease-settle: cubic-bezier(0.22, 1, 0.36, 1);
---p2m-squash: 0.18;               /* 18% deformation allowed */
---p2m-overshoot: 1.08;
-```
-Emphasize: squash & stretch, exaggeration, secondary action. Avoid: long anticipation (kills the fun).
-
-### Elegant / Premium (luxury, fashion, hospitality)
-```css
---p2m-duration: 1600ms;
---p2m-ease-enter: cubic-bezier(0.4, 0, 0.6, 1);       /* extended symmetric */
---p2m-ease-settle: cubic-bezier(0.16, 1, 0.3, 1);
---p2m-squash: 0;                  /* no deformation */
---p2m-overshoot: 1.02;            /* whisper of overshoot, or none */
-```
-Emphasize: timing (slow, unhurried), staging, arcs (long graceful paths), restraint as appeal. Fades and mask wipes over movement. Avoid: bounce, squash, fast cuts.
-
-### Trustworthy / Professional (fintech, enterprise, B2B, healthcare)
-```css
---p2m-duration: 700ms;
---p2m-ease-enter: cubic-bezier(0, 0, 0.2, 1);         /* confident ease-out */
---p2m-ease-settle: cubic-bezier(0.4, 0, 0.2, 1);
---p2m-squash: 0;
---p2m-overshoot: 1.0;             /* land exactly, no bounce */
-```
-Emphasize: slow in/out (smoothness = stability), consistent timing, solid drawing. Motion must be predictable: same easing family everywhere. Avoid: overshoot, randomness, secondary flourishes.
-
-### Energetic / Bold (sports, gaming, startups, media)
-```css
---p2m-duration: 600ms;
---p2m-ease-enter: cubic-bezier(0.16, 1, 0.3, 1);      /* explosive out */
---p2m-ease-settle: cubic-bezier(0.34, 1.56, 0.64, 1);
---p2m-squash: 0.25;
---p2m-overshoot: 1.12;
-```
-Emphasize: timing (fast), exaggeration, strong anticipation (coil before release), impact frames. Avoid: slow fades, symmetric easing.
-
-### Calm / Caring (wellness, meditation, education)
-```css
---p2m-duration: 1400ms;           /* loops: 3000-4000ms breathing */
---p2m-ease-enter: ease-in-out;
---p2m-ease-settle: cubic-bezier(0.4, 0, 0.6, 1);
---p2m-squash: 0.04;               /* breathing-level only */
---p2m-overshoot: 1.0;
-```
-Emphasize: slow in/out (symmetric oscillation), arcs, gentle staging. Opacity and blur over translation. Avoid: anything sudden; keep amplitudes small.
-
-### Friendly / Approachable (small business, community, services)
-```css
---p2m-duration: 850ms;
---p2m-ease-enter: cubic-bezier(0.25, 0.46, 0.45, 0.94);
---p2m-ease-settle: cubic-bezier(0.22, 1, 0.36, 1);
---p2m-squash: 0.08;
---p2m-overshoot: 1.04;
-```
-Middle of every axis: soft deformation, moderate timing, one gentle secondary action.
-
-## Step 4 — Sanity checks
-
-- Describe the finished animation in 3 words. Do they match the brand words from the brief?
-- Would a competitor's logo wearing this exact motion feel the same? If yes, push one principle further toward the personality.
-- The same token values must drive reveal, loop, and hover variants — one brand, one motion voice.
-- Show the animation without the product around it: still recognizably this brand?
-
-## Universal tokens (work for any personality)
-
-```css
---p2m-ease-out-universal: cubic-bezier(0.16, 1, 0.3, 1);
---p2m-ease-natural: cubic-bezier(0.4, 0, 0.2, 1);
---p2m-ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);   /* scale amplitude with duration */
---p2m-ease-narrative: cubic-bezier(0.34, 0, 0.14, 1);   /* deliberate sequences */
-```

package/skills/pixel2motion/references/reveal-patterns.md

@@ -1,163 +0,0 @@
-# Logo Choreography Pattern Library
-
-Reveal, loop, and hover patterns. Each entry: when to use, principles it leans on, timeline shape, and a CSS skeleton targeting motion-ready part ids. All durations assume the personality tokens from `motion-personality.md`; multiply, don't hardcode.
-
-The timeline shape notation `A:B:C` = anticipation : action : follow-through as % of total (golden ratio default 20:50:30).
-
----
-
-## Reveals
-
-### 1. Draw-On (stroke reveal)
-**For**: marks with a clear stroke skeleton — monograms, signatures, line icons, circular C-marks.
-**Principles**: straight-ahead feel on a pose-to-pose spine; slow in/out; staging (the pen leads the eye).
-**Requires**: `pathLength="1"` on each drawn path; path direction = draw direction.
-**Shape**: 10:70:20 (drawing IS the action; brief pre-beat; ink "dries" as fills fade in after).
-
-```css
-#mark path {
-  stroke-dasharray: 1;
-  stroke-dashoffset: 1;
-  animation: p2m-draw calc(var(--p2m-duration) * 0.7) var(--p2m-ease-natural) calc(var(--p2m-duration) * 0.1) forwards;
-}
-@keyframes p2m-draw { to { stroke-dashoffset: 0; } }
-/* fills fade in during the last 20% */
-#mark .fill { opacity: 0; animation: p2m-fade calc(var(--p2m-duration) * 0.25) ease-out calc(var(--p2m-duration) * 0.75) forwards; }
-@keyframes p2m-fade { to { opacity: 1; } }
-```
-Multiple strokes: stagger starts by 10–15% of one stroke's duration, ordered by natural writing order.
-
-#### Dash math — artifact table
-
-With `pathLength="1"` everything is normalized; `stroke-dasharray: <dash> <gap>`. Wrong combinations leak ink before the draw starts — check the t=0 frame explicitly:
-
-| caps | dasharray | start offset | result |
-|---|---|---|---|
-| round | `1` (gap=1, period 2) | `1` | **artifact**: the zero-length dash at the path start renders its round cap — an ink dot before the draw begins |
-| round | `1` | `1.05` (overshoot) | **artifact**: period-2 wraparound shows the path TAIL — [0.95, 1] is visible at t=0 |
-| round | `1 1.2` (gap > path) | `1.1` | correct for round caps: every dash interval stays off [0, 1] until the draw starts. Note the visible tip still LEADS the pen by half the stroke width (cap lookahead) — fine for single-stroke draws, disqualifying for multi-piece handoffs |
-| butt | `1 1` | `1` | correct and exact: a zero-length butt dash renders nothing, visible tip == pen position. Mandatory for split-fill handoffs (§1b) |
-
-If a mask stroke's seam/caps would rest at a visible location, hide them under an occluder (dot, knot, letter) chosen back in Phase 2.
-
-### 1b. Draw-On Across Self-Intersections (split-fill)
-**For**: ∞ marks, script signatures, monograms — any centerline that crosses itself.
-**Problem**: the reveal stroke is roughly the ribbon's max width; at a crossing it reveals the *other* branch's fill before the pen reaches it — an "X" pops in mid-draw.
-**Principles**: same as Draw-On, plus solid drawing (the partial mark must always look hand-drawn, never glitched).
-
-Recipe (all numbers field-verified):
-
-1. **Split the FILL into pieces** cut between crossing passes — cut ~40px of arc before the later pass; overlap the pieces ~4px with the same color (invisible, AA-proof). A piece that hasn't started is entirely absent from screen, so no stroke width can pre-reveal it.
-2. **One mask per piece**, each containing its own centerline sub-path spine with `pathLength="1"`. Get the cut parameters (each crossing's arc fractions) from `fit_ribbon_centerline.py`'s report.
-3. **Butt caps + `stroke-dasharray: 1 1`, offset `1 → 0`** on every mask spine (see the artifact table). Round caps stall the visible tip at each handoff (the half-stroke-width lookahead "re-arms"), then pop the next piece in as a cap-radius disk — measured as a 50ms ink flatline plus a disk-sized jump.
-4. **Extend the LATER piece's spine ~6px back before the cut**, so both pieces' tips traverse the overlap together and the handoff is spatially continuous.
-5. **Subdivide the global easing exactly** (de Casteljau). For draw easing E as a cubic Bézier in (time, progress) space — P0=(0,0), P1=(x1,y1), P2=(x2,y2), P3=(1,1):
-   - solve τ where progress y(τ) = the piece boundary's arc fraction (bisection on the monotonic y);
-   - de Casteljau-split E at τ; normalize each half into its own `cubic-bezier()` by translating to its start point and dividing control coordinates by the segment's (Δx, Δy) spans;
-   - subdivide at the cut fraction for the earlier piece's END, and at (cut − 6px)'s fraction for the later piece's START. Each piece animates over its own keyframe window with its own literal curve; the combined pen pace equals the original design exactly (verify: tip speed continuous across the handoff, e.g. 1.49 → 1.45 px/ms).
-6. **Bridge the paint-under-ink dead window.** The later pass crosses *under* already-painted fill: for ~10–25ms no pixel can change — physically unavoidable (the ink sweep shows one near-zero sample). Add a **tip glint**: a small soft radial-gradient light (r ≈ 0.3× max ribbon width) with base `opacity="0"` in the SVG, riding the FULL centerline via `offset-path: path(...)` + `offset-distance 0% → 100%` with the ORIGINAL un-subdivided easing — it then coincides with the pen tip exactly (probe: 0px divergence). Z-order it beneath the occluding dot/bead so it emerges from and returns under it; fade it in after the anticipation beat and out before the settle. Base opacity 0 keeps static/?static=1/reduced-motion/final states clean.
-
-QA for this pattern: frames bracketing EACH crossing pass (the early pass must show a single clean branch), the easing probe (tip and glint must agree), the ink-delta sweep across the handoff (no flatline-then-jump), and the Final Frame Contract.
-
-### 2. Staggered Assembly
-**For**: multi-part logos — mark + wordmark, geometric compositions, dots + swooshes.
-**Principles**: follow-through & overlapping action (the star), staging (reading order), arcs (parts arrive on curves).
-**Shape**: 20:50:30. Drag hierarchy: container/mark → letters → accents. Per-part stagger = 10–20% of part duration.
-
-```css
-#mark     { animation: p2m-arrive var(--p2m-duration-part) var(--p2m-ease-enter) 0ms both; }
-#letter-1 { animation: p2m-arrive var(--p2m-duration-part) var(--p2m-ease-enter) 60ms both; }
-#letter-2 { animation: p2m-arrive var(--p2m-duration-part) var(--p2m-ease-enter) 120ms both; }
-#dot      { animation: p2m-arrive-bounce var(--p2m-duration-part) var(--p2m-ease-settle) 220ms both; }
-@keyframes p2m-arrive {
-  from { opacity: 0; transform: translateY(12px) scale(0.95); }
-  60%  { opacity: 1; transform: translateY(-2px) scale(var(--p2m-overshoot)); }
-  to   { opacity: 1; transform: translateY(0) scale(1); }
-}
-```
-Cap the full cascade at ~700ms beyond the first arrival; with many letters shrink stagger, not letter duration. Parts need `transform-box: fill-box; transform-origin: center;`.
-
-### 3. Scale-Pop with Overshoot
-**For**: compact marks, app icons, badges; the default splash gesture.
-**Principles**: anticipation (pre-shrink), squash & stretch (personality-gated), exaggeration, follow-through (overshoot + settle).
-**Shape**: 20:50:30 literally — this is the textbook golden-ratio pattern.
-
-```css
-#logo {
-  transform-box: fill-box; transform-origin: center;
-  animation: p2m-pop var(--p2m-duration) var(--p2m-ease-narrative) both;
-}
-@keyframes p2m-pop {
-  0%   { opacity: 0; transform: scale(0.6); }
-  20%  { opacity: 0; transform: scale(0.55); }            /* anticipation: coil */
-  60%  { opacity: 1; transform: scale(var(--p2m-overshoot)); }
-  80%  { transform: scale(0.99); }                        /* counter-settle */
-  100% { transform: scale(1); }
-}
-```
-Deliberate splash variant: start `scale(0.6) translateY(50px)` with `filter: blur(10px)`, clear blur by 60%.
-
-### 4. Mask Wipe
-**For**: wordmarks, horizontal lockups, elegant/premium personalities (motion without deformation).
-**Principles**: staging (the wipe directs reading), timing, solid drawing (geometry never deforms).
-**Shape**: 15:60:25. Wipe direction = reading direction (LTR logos wipe left→right).
-
-```css
-#wordmark { clip-path: inset(0 100% 0 0); animation: p2m-wipe calc(var(--p2m-duration) * 0.6) var(--p2m-ease-enter) calc(var(--p2m-duration) * 0.15) forwards; }
-@keyframes p2m-wipe { to { clip-path: inset(0 0 0 0); } }
-```
-Premium touch: pair with a 2–4px translateX drift in the same direction, settling as the wipe completes.
-
-### 5. Morph-from-Primitive
-**For**: logos whose mark relates to a simple shape (a circle becoming the C, a square unfolding).
-**Principles**: anticipation (the primitive IS the anticipation), appeal, solid drawing.
-**Note**: keep it cheap — morph between *few-knot* paths with identical command structure (this is where Phase 2's minimal geometry pays off; a 400-point traced path cannot morph). Animate `d` via CSS `d: path()` (Chromium) or pre-computed keyframe paths; cross-fade fallback for engines without `d` support.
-**Shape**: 25:50:25 — hold the primitive a beat longer so viewers register the transformation.
-
-### 6. Letter Cascade (wordmark-first logos)
-**For**: type-driven brands.
-**Principles**: overlapping action, arcs (letters arrive on subtle curves), timing (per-letter weight).
-Per-letter duration 200–300ms, stagger 30–60ms, total ≤ 700ms. Letters rise `translateY(0.6em → 0)` + fade, with optional 1–2° rotation that zeroes on landing (keeps baselines honest — check solid drawing in mid-frames).
-
----
-
-## Idle / Loading Loops
-
-Seamlessness rule: the 100% keyframe must equal the 0% keyframe exactly. Verify with seam frames (capture just before and after the loop point).
-
-### Breathing
-`scale(1 ↔ 1.02)`, 3000–4000ms, ease-in-out, infinite. Calm/ambient. Amplitude ≤ 2% — the logo is present, not performing.
-
-### Pulse Accent
-One part (the dot, the accent) pulses `opacity 0.7 ↔ 1` or `scale 1 ↔ 1.06`, 1500–2000ms cycle. Staging: only ONE part may pulse.
-
-### Orbit / Spinner
-A satellite element rotates around the mark, 1200–2000ms, **linear** (the one legitimate use of linear — eased rotation pulses). Mark itself stays still or breathes counter-phase.
-
-### Draw-Cycle
-Draw-on forward (70%), hold (15%), fade strokes (15%), repeat. For loading states 2000–3000ms cycle. Decay rule: if loading completes mid-cycle, finish the current draw then settle to the static logo — never hard-cut.
-
-Loop hygiene: still pleasant after 30 seconds? If it would annoy on the tenth loop, halve the amplitude. Stop or decay attention-grabbing loops after 3–5 cycles when nothing is actually loading.
-
----
-
-## Hover / Micro-interactions
-
-Duration 150–300ms, ease-out only (no time for ease-in). Must read as *response*, not *performance*.
-
-- **Lift**: `translateY(-2px)` + shadow tighten, 200ms. Trust/professional.
-- **Wink**: the accent part (dot, leaf) does a single 8–12% squash-bounce, 250ms. Playful.
-- **Sheen**: a masked highlight sweeps the wordmark once, 300ms. Premium.
-- **Re-draw**: the mark's stroke redraws at 2× speed, 300ms. Technical/creative brands.
-
-Hover must return to the exact rest state (Final Frame Contract applies to interaction end-states too). Provide `:focus-visible` parity for keyboard users.
-
----
-
-## Composition rules
-
-1. One reveal + at most one idle loop + at most one hover behavior. More is noise.
-2. Reveal plays once per session/page-load context; never on every route change.
-3. All variants share the same personality tokens.
-4. Everything lives inside `@media (prefers-reduced-motion: no-preference)`; the reduced-motion experience is the finished static logo, immediately.
-5. Performance: animate only `transform`, `opacity`, `clip-path`, `stroke-dashoffset`, `filter` (sparingly). Never layout properties. One `will-change` per animated part at most, removed after the reveal.