@impractical-ai/motion 0.1.11 → 0.1.13

package/assets/engine.d.ts

@@ -1,9 +1,191 @@
 // Impractical Motion — public engine surface v1.1.
 //
 // A scene is two files:
-//   App.tsx       the stage markup (plain React + CSS; this is your product UI)
+//   App.tsx       the stage markup (plain React + CSS) — the SET, not a
+//                 replica of the product: what the shots need on screen
 //   direction.ts  the choreography — `export default (ctx: DirectionContext) => {...}`
 //
+// COMPOSE THE SHOTS BEFORE YOU BUILD THE SET. Reconstruct the product first
+// and you get a slideshow of panels. List the shots first — the set is what
+// they need, and their components ARE the build list for App.tsx. Per shot:
+// the CLAIM it proves, WHAT IS ON SCREEN, the FRAMING —
+//   in-situ     a crop of the product, when where-it-lives is the point
+//   composed    elements arranged for this shot alone, at a scale where the
+//               change reads as total; need not exist in the product. A
+//               picker beside a miniature of what it recolours beats either
+//               one filmed in place.
+//   full-frame  a claim card; type owns the frame
+// A dense product at 1920x1080 puts body text near 11px, so a wide shot of
+// one establishes nothing. Frame the smallest thing that carries the meaning;
+// widen only when it means something. If the film claims coherence, ONE shot
+// shows the product whole.
+//
+// THE KIT LIBRARY. The types below are the ENGINE — the floor, not the
+// craft. Most of the house craft is in the kit library, which is NOT in this
+// file: call install_kits to write it into your draft, then import from
+// './kit/<name>'. Every kit below is already written and tuned against
+// reference footage; hand-rolling one is how a scene ends up looking it.
+//
+// HOW A FILM IS WRITTEN. The neutral film sequencer owns ordering; World
+// Camera owns only named-object framing, depth, and camera gestures.
+//   const film = createFilmSequencer({ tl })
+//   const world = createWorldCamera({ tl, stage, camera, register: 'promo' })
+//   const copy = createTextPlans(text)
+//   const result = film.do(manner.realize('[data-obj="RESULT_ROWS"]'))
+//   film.do(world.camera.whipTo('RESULT_ROWS').landWith(result))
+//   film.do(copy.exit('[data-claim]', 'rise'))
+//   film.cut(editorial.cut(layers, next), world.camera.cutTo('NEXT'))
+// Camera verbs: cutTo / moveTo / zoomTo / whipTo / departTo / angleTo /
+// focusOn. The id is data-obj. Every verb centers that object's authored
+// bounding box and maximizes it inside deterministic padding. Optional
+// framing words are tight / normal / loose — breathing room, not zoom.
+// film.do advances to settle, film.together shares a start, and
+// film.at(handle.impact) attaches a consequence to its cause. film.cut
+// waits for every outgoing plan END; coveredCut(handle, marker, reason, ...)
+// is the explicit exception for an intentionally carried seam. Content
+// manner and editorial cuts stay separate from World Camera. The raw camera
+// in DirectionContext below
+// (framing/full/crop/set/move) is the ESCAPE HATCH — measured or skeleton
+// work that needs an exact pose at an exact time — not the default path.
+//
+//   kit/kits — Side-effect import: the draft-side working-views engine (Studio
+//     reveal verbs on the currently deployed engine). Every kit imports this
+//     module,
+//   kit/reveal — DRAFT-SIDE working-views engine — GENERATED from
+//     src/stage/reveal.ts. Do not hand-edit.
+//   kit/actions — Actions — cursor, click, drag, scroll, and UI state
+//     primitives [exports: createActionsKit, createActionPlans]
+//   kit/ensemble — Ensemble choreography — words that move MANY elements as one
+//     system. [exports: createEnsembleKit]
+//   kit/looks — Looks — scene lighting, shading, ambient backdrops, and the
+//     hero shot [exports: createLooksKit]
+//   kit/sentence — The live-sentence kit: a sentence is a stateful object, not
+//     a static block. [exports: createSentenceKit]
+//   kit/morphkit — Universal shape morph — the shared-element architecture (how
+//     Framer Motion's layoutId / iOS matchedGeometryEffect / Flutter Hero do
+//     it): [exports: createMorphKit]
+//   kit/morphtree — GENERATED from src/stage/morph-tree.ts by
+//     build:morph-runtime. Do not edit. [exports: createMorphTreeKit]
+//   kit/highlight — Highlight — annotation primitives for pre-existing
+//     components [exports: createHighlightKit]
+//   kit/impact — Impact moves — the "slam": type or a card that hits the frame
+//     hard, or tips away out of it. [exports: createImpactKit]
+//   kit/streamkit — Streaming states — the choreographed WAITING that AI
+//     products live in. [exports: createStreamKit]
+//   kit/editorial — Editorial — cuts, jumps, and the camera-solved match cut
+//     [exports: createEditorialKit, createEditorialPlans]
+//   kit/depthmath — Depth math — pure, DOM-free, tested in isolation
+//   kit/depthkit — Depth — the stage as a physical world: layers, tilt, glass,
+//     light [exports: createDepthKit]
+//   kit/anchor — Anchor — never guess where another element is [exports:
+//     createAnchorKit]
+//   kit/atelier — Atelier — the house motion studies, callable from a film
+//     [exports: createAtelierKit]
+//   kit/cursor-geometry — Cursor geometry — project authored anchors into the
+//     cursor's actual plane.
+//   kit/film — Film — semantic sequencing without timestamp arithmetic
+//     [exports: createFilmSequencer]
+//   kit/manner — Manner kit — component-property motion (v2, the coverage
+//     bundle) [exports: createMannerKit, createMannerPlans]
+//   kit/morph-surface — Continuous vector surfaces with recursive content
+//     matching, scheduled by Film. [exports: createMorphSurfacePlans]
+//   kit/profile — Motion profile — loader, types, and the timing vocabulary
+//   kit/text — Text plans — full-span text timing for safe film boundaries
+//     [exports: createTextPlans]
+//   kit/world — World Camera — named subjects, spatial continuity, depth, and
+//     targeting [exports: createWorldCamera, createWorldKit]
+//
+// ─── MARKUP: what an element declares about itself ───────────────────────
+//
+// App.tsx is not inert scenery. The kits read ATTRIBUTES off the elements
+// you write, so these are decisions made WHILE writing the markup: an
+// element declares its identity, how it arrives, and how closely it can be
+// looked at. The direction then only says WHEN. An attribute you never
+// write is motion you never get, and it fails QUIET — manner.realize()
+// over elements with no data-manner animates nothing.
+//
+// IDENTITY — what the camera, the profile, and the kits can name
+//   data-obj="rows" — this element IS an object and keeps that identity for
+//     the whole film. Camera poses name objects, never coordinates. Ids must
+//     be unique.
+//   data-part — a part of its object — what assemble() rises in sequence.
+//     Unmarked, its direct children are the parts.
+//   data-el — a member of a manner cascade — what 'cascade' births one at a
+//     time. Unmarked, the root's direct children are the members.
+//   data-product-ui — this element is the product shell. Legacy world.beat
+//     fits and camera angles use it as a coherent plane; camera-only target
+//     framing always measures the specifically named object.
+//   data-detail="fine" — legacy world.beat declaration that content survives
+//     a deep closeup. Camera-only target framing has no magnification cap or
+//     waiver. The only legal value is 'fine'.
+//
+// HOW IT ARRIVES — a property of the ELEMENT, not of the cue
+//   data-manner="<word>" — the element declares its own entrance; the
+//     direction only says WHEN, with manner.realize(sel, at). A
+//     space-separated list is legal and the direction names which fires.
+//     Without this attribute manner.realize() silently does nothing. The
+//     words:
+//     cascade — children write on, metronome births + settle
+//     accent-pop — accent pop onto an already-born element (never past rest
+//       size)
+//     pop — the item pop — the overshoot entrance
+//     slide-home — slides home whole on the measured entry deceleration…
+//     complete — appears COMPLETE in one frame — no fade
+//     breath — the surface takes one small breath
+//     grow — grows downward clipped to reveal its rows
+//     zoom-out — the SURFACE zooms itself out over a static world — a
+//       subject-carried device…
+//     snap — a hard ui-state change in ONE frame — never a fade. TWO FORMS,
+//       discriminated…
+//     spark — a small burst off the element's corner
+//     doodle — a rigid motif flies a measured arc (data-arc names it)
+//     reveal — an outcome row snaps on whole and settles up
+//     slide — peers slide one pitch to make room
+//     swap — covered-cut content arrives low and settles while the chrome holds
+//       still
+//     reorg — reorganized content slides up settling
+//   data-speed="quick" — 'snap' | 'quick' | 'slow'. On 'cascade' it picks the
+//     birth cadence class; elsewhere it scales the profile duration.
+//     Stepped-table manners take no speed (an error, not a no-op) and a bare
+//     number is always an error.
+//   data-anchor="50% 50%" — transform-origin for the scale-borne manners.
+//   data-late — on a cascade member: excluded from the cascade — the kit
+//     hides it and its own later cue reveals it.
+//   data-display-birth="flex" — members are display:none until born, then
+//     take this display — for members whose arrival displaces layout.
+//   data-visible-from="next-frame" — births render no earlier than one frame
+//     after the cascade starts: the mid-birth cut mask. The only value —
+//     times belong to the direction.
+//   data-snap-<property>="value" — for 'snap' on an element that STAYS on
+//     screen: the properties it lands on, set in one frame, e.g.
+//     data-snap-background="#5a5a5a". An element that IS the state visual
+//     snaps on whole and needs none.
+//   data-arc="<name>" — which measured arc a 'doodle' flies.
+//   data-from="left" — 'left' | 'right' | 'above' | 'below' — the side a
+//     'slide' comes from (default 'left').
+//   data-focus — on a descendant: what a 'zoom-out' opens magnified on before
+//     pulling back.
+//
+// STAGE ROLES
+//   data-backdrop — you own what the backdrop IS — any markup, animated on
+//     the timeline; World Camera owns that it COVERS and automatically keeps
+//     one authored backdrop outside camera-space.
+//   data-frame-overlay — screen-fixed material above the camera world, such
+//     as continuous grain, vignette, scanlines, or letterbox bars. World
+//     Camera hoists it out of camera-space and keeps it viewport-sized.
+//   data-morph="name" — pairs a sub-component with the same name on the other
+//     side of a morph. Untagged children auto-pair by text.
+//   data-block — the blend-isolation host: filters and blend modes composite
+//     against this ancestor instead of leaking under the stage.
+//
+// ATELIER AND SCENE LIFECYCLE
+//   data-scene="id" — Register with world.scene(id); travel between
+//     registered scenes retires the scene being left. Re-enter it explicitly
+//     before revisiting.
+//   data-cadence — Optional manner/cadence grouping marker.
+//   data-atelier="id" — Wrap the skeleton returned by atelier_study; preserve
+//     its nested selector contract.
+//
 // The timeline is created PAUSED and rendered by seeking frame by frame, so
 // every animation must be a function of timeline position alone. Never use
 // Date.now(), Math.random(), setTimeout, CSS animations, or autoplaying video —
@@ -25,24 +207,24 @@ export type TransitionDirection = 'left' | 'right' | 'up' | 'down'
 
 export type TransitionOpts = {
   color?: string
-  /** Travel direction of the sweep (wipe/pixels). Default 'left'. */
+/** Travel direction of the sweep (wipe/pixels). Default 'left'. */
   direction?: TransitionDirection
   duration?: number
   ease?: string
-  /** Pixel cell size in px (pixels style). Default: frame height / 9. */
+/** Pixel cell size in px (pixels style). Default: frame height / 9. */
   cell?: number
-  /** Iris center as fractions of the frame, e.g. `{ x: 0.7, y: 0.4 }`. */
+/** Iris center as fractions of the frame, e.g. `{ x: 0.7, y: 0.4 }`. */
   at?: { x?: number; y?: number }
 }
 
 export type TransitionResult = {
   duration: number
-  /** The overlay's root element — e.g. to hide it manually mid-timeline. */
+/** The overlay's root element — e.g. to hide it manually mid-timeline. */
   root: HTMLElement
 }
 
 /** What the camera dives through. Every mode computes its own geometry —
- * never hand-tune margins or wrap glyphs in spans to fake these. */
+* never hand-tune margins or wrap glyphs in spans to fake these. */
 export type ThroughVia =
   | 'surface' // the element's face: its rect covers the frame (default)
   | 'glyph' // one character's COUNTER (the enclosed hole) covers the frame
@@ -50,99 +232,99 @@ export type ThroughVia =
   | 'anchor'
 
 export type ThroughOpts = {
-  /** Dive mode. Default 'surface'. 'glyph' needs `char` (or `charIndex`),
-   * 'word' needs `word`; both address plain text — no wrapper spans.
-   * 'anchor' dives toward the element and, at the cut, match-frames the
-   * element matching the SAME selector in the post-swap world (its twin),
-   * so the subject persists while everything around it changes. */
+/** Dive mode. Default 'surface'. 'glyph' needs `char` (or `charIndex`),
+* 'word' needs `word`; both address plain text — no wrapper spans.
+* 'anchor' dives toward the element and, at the cut, match-frames the
+* element matching the SAME selector in the post-swap world (its twin),
+* so the subject persists while everything around it changes. */
   via?: ThroughVia
-  /** glyph mode: the character to dive through — first occurrence in the
-   * target's text. The dive passes through its enclosed counter (o, e, a,
-   * 0…); characters without a hole throw with a diagnostic. */
+/** glyph mode: the character to dive through — first occurrence in the
+* target's text. The dive passes through its enclosed counter (o, e, a,
+* 0…); characters without a hole throw with a diagnostic. */
   char?: string
-  /** glyph mode: 0-based index into the target's text, instead of `char`. */
+/** glyph mode: 0-based index into the target's text, instead of `char`. */
   charIndex?: number
-  /** word mode: the word to dive through — first occurrence. */
+/** word mode: the word to dive through — first occurrence. */
   word?: string
-  /** Takeover color. Defaults: surface/anchor — the target's effective
-   * background (first non-transparent backgroundColor walking up from the
-   * target); glyph/word — the surface BEHIND the text (the walk starts at
-   * the text element's parent), i.e. what actually shows through the
-   * counters. */
+/** Takeover color. Defaults: surface/anchor — the target's effective
+* background (first non-transparent backgroundColor walking up from the
+* target); glyph/word — the surface BEHIND the text (the walk starts at
+* the text element's parent), i.e. what actually shows through the
+* counters. */
   color?: string
-  /** Dive duration in seconds. Default 0.5. */
+/** Dive duration in seconds. Default 0.5. */
   duration?: number
-  /** Dive ease. Default 'power3.in' (accelerates into the surface). */
+/** Dive ease. Default 'power3.in' (accelerates into the surface). */
   ease?: string
-  /** Cover overshoot: 1.0 = the dive geometry (element rect, glyph counter,
-   * or word rect per `via`) exactly covers the frame at the cut. Default
-   * 1.15, so a few px of drift can never expose an edge. Override only for
-   * taste — every mode measures its own geometry, so no mode NEEDS a
-   * hand-tuned margin. */
+/** Cover overshoot: 1.0 = the dive geometry (element rect, glyph counter,
+* or word rect per `via`) exactly covers the frame at the cut. Default
+* 1.15, so a few px of drift can never expose an edge. Override only for
+* taste — every mode measures its own geometry, so no mode NEEDS a
+* hand-tuned margin. */
   margin?: number
-  /** The world swap, applied as seek-safe `tl.set`s at the exact cut moment
-   * while the frame is fully covered: `hide` gets autoAlpha 0, `show` gets
-   * autoAlpha 1. For anything richer, place your own `tl.set`s at the
-   * returned `cutAt` time. */
+/** The world swap, applied as seek-safe `tl.set`s at the exact cut moment
+* while the frame is fully covered: `hide` gets autoAlpha 0, `show` gets
+* autoAlpha 1. For anything richer, place your own `tl.set`s at the
+* returned `cutAt` time. */
   swap?: { hide?: gsap.TweenTarget; show?: gsap.TweenTarget }
-  /** Element in the post-swap world to ARRIVE from: at the cut the camera
-   * snaps to this element's own cover framing (measured after the swap), so
-   * releasing the overlay reveals it filling the frame, and the pull-out
-   * starts inside the new world — the match-frame landing. Omit to pull out
-   * from the dive's own framing. */
+/** Element in the post-swap world to ARRIVE from: at the cut the camera
+* snaps to this element's own cover framing (measured after the swap), so
+* releasing the overlay reveals it filling the frame, and the pull-out
+* starts inside the new world — the match-frame landing. Omit to pull out
+* from the dive's own framing. */
   land?: string | Element
-  /** Framing the pull-out settles on. Default the full frame
-   * `{ scale: 1, x: 0, y: 0 }`. */
+/** Framing the pull-out settles on. Default the full frame
+* `{ scale: 1, x: 0, y: 0 }`. */
   settle?: { scale: number; x: number; y: number }
-  /** Pull-out duration. Default 1.0. */
+/** Pull-out duration. Default 1.0. */
   outDuration?: number
-  /** Pull-out ease. Default 'expo.out'. */
+/** Pull-out ease. Default 'expo.out'. */
   outEase?: string
 }
 
 export type ThroughResult = {
-  /** Full span: dive + pull-out. */
+/** Full span: dive + pull-out. */
   duration: number
-  /** Absolute timeline time of the cut — the frame is guaranteed fully
-   * covered here; schedule extra world-swap `tl.set`s at this time. */
+/** Absolute timeline time of the cut — the frame is guaranteed fully
+* covered here; schedule extra world-swap `tl.set`s at this time. */
   cutAt: number
-  /** The takeover overlay's root element. */
+/** The takeover overlay's root element. */
   root: HTMLElement
 }
 
 export type TransitionKit = {
-  /** Cover the frame — put this at the end of a clip. Appends to the
-   * timeline's end when no position is given. */
+/** Cover the frame — put this at the end of a clip. Appends to the
+* timeline's end when no position is given. */
   out: (
     style: TransitionStyle,
     opts?: TransitionOpts,
     position?: gsap.Position
   ) => TransitionResult
-  /** Start covered and reveal the scene — put this at a clip's start
-   * (position 0). Continues the same travel direction as its `out`. */
+/** Start covered and reveal the scene — put this at a clip's start
+* (position 0). Continues the same travel direction as its `out`. */
   in: (
     style: TransitionStyle,
     opts?: TransitionOpts,
     position?: gsap.Position
   ) => TransitionResult
-  /** The go-through: dive the camera INTO something until its color takes
-   * over the whole frame, cut worlds under the cover, then pull out into the
-   * new world. NEVER hand-roll this (a magic-scale zoom + a hand-timed
-   * `tl.set` swap + a re-aim) — through() computes the exact cover scale for
-   * its dive geometry, measures it in its state AT THE DIVE'S START TIME
-   * (entrances, moves, and tilts since build are all accounted for), and
-   * snaps a full-frame overlay in the right color at the cut so the
-   * takeover is guaranteed to the pixel. Four dive modes via `opts.via`:
-   * 'surface' (default — the element's face), 'glyph' (through one
-   * character's enclosed counter: `{ via: 'glyph', char: 'o' }` on plain
-   * text, no wrapper span — the hole is measured from the actual glyph
-   * outline, so the margin is computed, never tuned), 'word' (`{ via:
-   * 'word', word: 'world' }` — the word's rect), and 'anchor' (match-cut:
-   * dive toward the element, swap the world at the cut, and land on the
-   * element matching the same selector in the new world, so the subject
-   * persists while everything around it changes). Deterministic: every
-   * value is resolved once at build; the swap is `tl.set`s, never
-   * callbacks. Appends at the timeline's end when no position is given. */
+/** The go-through: dive the camera INTO something until its color takes
+* over the whole frame, cut worlds under the cover, then pull out into the
+* new world. NEVER hand-roll this (a magic-scale zoom + a hand-timed
+* `tl.set` swap + a re-aim) — through() computes the exact cover scale for
+* its dive geometry, measures it in its state AT THE DIVE'S START TIME
+* (entrances, moves, and tilts since build are all accounted for), and
+* snaps a full-frame overlay in the right color at the cut so the
+* takeover is guaranteed to the pixel. Four dive modes via `opts.via`:
+* 'surface' (default — the element's face), 'glyph' (through one
+* character's enclosed counter: `{ via: 'glyph', char: 'o' }` on plain
+* text, no wrapper span — the hole is measured from the actual glyph
+* outline, so the margin is computed, never tuned), 'word' (`{ via:
+* 'word', word: 'world' }` — the word's rect), and 'anchor' (match-cut:
+* dive toward the element, swap the world at the cut, and land on the
+* element matching the same selector in the new world, so the subject
+* persists while everything around it changes). Deterministic: every
+* value is resolved once at build; the swap is `tl.set`s, never
+* callbacks. Appends at the timeline's end when no position is given. */
   through: (
     target: string | Element,
     opts?: ThroughOpts,
@@ -223,39 +405,39 @@ export type CountOpts = {
 }
 
 export type TextKit = {
-  /** Animate text in. Returns the total span so you can sequence after it. */
+/** Animate text in. Returns the total span so you can sequence after it. */
   reveal: (
     target: string | Element,
     effect: RevealEffect,
     opts?: TextEffectOpts,
     position?: gsap.Position
   ) => TextResult
-  /** Animate text out (mirror of reveal). */
+/** Animate text out (mirror of reveal). */
   exit: (
     target: string | Element,
     effect: ExitEffect,
     opts?: TextEffectOpts,
     position?: gsap.Position
   ) => TextResult
-  /** Deterministic number count-up on an element's text (for stat pills and
-   * badges — pairs with a camera push-in). Snaps to integers on the
-   * timeline; width is locked so the layout doesn't breathe. */
+/** Deterministic number count-up on an element's text (for stat pills and
+* badges — pairs with a camera push-in). Snaps to integers on the
+* timeline; width is locked so the layout doesn't breathe. */
   count: (
     target: string | Element,
     opts: CountOpts,
     position?: gsap.Position
   ) => TextResult
-  /** A settle-back gesture on a whole element (no split): pulse, wiggle,
-   * shake. Great on CTAs and accent words after they appear. */
+/** A settle-back gesture on a whole element (no split): pulse, wiggle,
+* shake. Great on CTAs and accent words after they appear. */
   emphasize: (
     target: string | Element,
     effect: EmphasisEffect,
     opts?: EmphasisOpts,
     position?: gsap.Position
   ) => TextResult
-  /** Draw a hand-sketched underline stroke beneath an element. The stroke
-   * spans the element's box — target a tight element (an inline-block span
-   * around the exact words), not a full-width heading. */
+/** Draw a hand-sketched underline stroke beneath an element. The stroke
+* spans the element's box — target a tight element (an inline-block span
+* around the exact words), not a full-width heading. */
   underline: (
     target: string | Element,
     opts?: UnderlineOpts,
@@ -322,29 +504,29 @@ export type LogoResult = {
 }
 
 export type LogoKit = {
-  /** Animate a logo in. Returns the total span so you can sequence after it. */
+/** Animate a logo in. Returns the total span so you can sequence after it. */
   reveal: (
     target: string | Element,
     effect: LogoRevealEffect,
     opts?: LogoEffectOpts,
     position?: gsap.Position
   ) => LogoResult
-  /** Animate a logo out (mirror of reveal). */
+/** Animate a logo out (mirror of reveal). */
   exit: (
     target: string | Element,
     effect: LogoExitEffect,
     opts?: LogoEffectOpts,
     position?: gsap.Position
   ) => LogoResult
-  /** A settle-back gesture on the whole mark: pulse, breathe, wiggle. */
+/** A settle-back gesture on the whole mark: pulse, breathe, wiggle. */
   emphasize: (
     target: string | Element,
     effect: LogoEmphasisEffect,
     opts?: LogoEmphasisOpts,
     position?: gsap.Position
   ) => LogoResult
-  /** A glint sweep across the mark. Follows the logo's silhouette (the
-   * sheen is masked by the SVG shapes or the image alpha). */
+/** A glint sweep across the mark. Follows the logo's silhouette (the
+* sheen is masked by the SVG shapes or the image alpha). */
   shine: (
     target: string | Element,
     opts?: ShineOpts,
@@ -358,69 +540,69 @@ export type FilterTier = 'css' | 'svg'
 
 export type FilterEffect =
   // ── css tier ────────────────────────────────────────────────────────────
-  /** Gaussian blur. Replaces the hand-rolled whip-pan "stage-blur spike". */
+/** Gaussian blur. Replaces the hand-rolled whip-pan "stage-blur spike". */
   | 'blur'
-  /** A halo in the element's own colour, from stacked drop-shadows. */
+/** A halo in the element's own colour, from stacked drop-shadows. */
   | 'glow'
-  /** Colour lifts (>1) or drains (<1). */
+/** Colour lifts (>1) or drains (<1). */
   | 'saturate'
-  /** Brightness pull-down — for backgrounding a layer under an overlay. */
+/** Brightness pull-down — for backgrounding a layer under an overlay. */
   | 'dim'
-  /** Hue rotation drift. */
+/** Hue rotation drift. */
   | 'hue'
   // ── svg tier ────────────────────────────────────────────────────────────
-  /** DIRECTIONAL blur along `angle`. CSS filter cannot do this at all. */
+/** DIRECTIONAL blur along `angle`. CSS filter cannot do this at all. */
   | 'smear'
-  /** Chromatic aberration: red and blue channels offset in opposite
-   * directions. The glitch/impact look, without an asset. */
+/** Chromatic aberration: red and blue channels offset in opposite
+* directions. The glitch/impact look, without an asset. */
   | 'chroma'
-  /** Turbulence-driven displacement: heat haze, liquid warp, dissolve. */
+/** Turbulence-driven displacement: heat haze, liquid warp, dissolve. */
   | 'displace'
-  /** Fractal-noise film grain composited over the source. */
+/** Fractal-noise film grain composited over the source. */
   | 'grain'
-  /** Bright-pass blur screened back over the source — bloom. */
+/** Bright-pass blur screened back over the source — bloom. */
   | 'bloom'
-  /** Posterize to N discrete levels per channel. */
+/** Posterize to N discrete levels per channel. */
   | 'threshold'
 
 export type FilterOpts = {
-  /** Peak value of the effect's primary parameter. */
+/** Peak value of the effect's primary parameter. */
   amount?: number
-  /** Secondary constant: turbulence frequency, bloom radius, grain scale. */
+/** Secondary constant: turbulence frequency, bloom radius, grain scale. */
   detail?: number
   duration?: number
   ease?: string
-  /** Direction in degrees for `smear` and `chroma`. 0 = horizontal. */
+/** Direction in degrees for `smear` and `chroma`. 0 = horizontal. */
   angle?: number
-  /** Tint for `glow` and `bloom`. Defaults to the element's computed colour. */
+/** Tint for `glow` and `bloom`. Defaults to the element's computed colour. */
   color?: string
 }
 
 export type FilterResult = {
-  /** Full span in seconds, including the return leg of a `spike`. */
+/** Full span in seconds, including the return leg of a `spike`. */
   duration: number
   targets: Element[]
 }
 
 export type FilterKit = {
-  /** Ramp an effect ON and leave it there — a state change. */
+/** Ramp an effect ON and leave it there — a state change. */
   apply: (
     target: string | Element | Element[],
     effect: FilterEffect,
     opts?: FilterOpts,
     position?: gsap.Position
   ) => FilterResult
-  /** Ramp it back to nothing. */
+/** Ramp it back to nothing. */
   clear: (
     target: string | Element | Element[],
     effect: FilterEffect,
     opts?: FilterOpts,
     position?: gsap.Position
   ) => FilterResult
-  /** In and out in ONE gesture: the whip-pan blur, the impact bloom, the
-   * glitch chroma pop. One tween, so the Tweak panel shows ONE row with one
-   * slider, one duration and one ease — instead of the two rows the
-   * hand-rolled pattern produces, which the user has to keep in sync. */
+/** In and out in ONE gesture: the whip-pan blur, the impact bloom, the
+* glitch chroma pop. One tween, so the Tweak panel shows ONE row with one
+* slider, one duration and one ease — instead of the two rows the
+* hand-rolled pattern produces, which the user has to keep in sync. */
   spike: (
     target: string | Element | Element[],
     effect: FilterEffect,
@@ -432,21 +614,21 @@ export type FilterKit = {
 // ─── Masks — soft edges, mattes, fills, and blend modes ──────────────────
 
 export type MaskShape =
-  /** Hard directional edge (clip-path inset) — same geometry as logo.wipe. */
+/** Hard directional edge (clip-path inset) — same geometry as logo.wipe. */
   | 'wipe'
-  /** SOFT directional edge. The capability clip-path structurally lacks. */
+/** SOFT directional edge. The capability clip-path structurally lacks. */
   | 'feather'
-  /** Hard circle growing from a point. */
+/** Hard circle growing from a point. */
   | 'iris'
-  /** Soft circle with a feathered falloff. */
+/** Soft circle with a feathered falloff. */
   | 'radial'
-  /** Letterbox opening from a horizontal centre line. */
+/** Letterbox opening from a horizontal centre line. */
   | 'slit'
-  /** Two panels parting from the centre outward. */
+/** Two panels parting from the centre outward. */
   | 'barn'
-  /** N bands opening together. */
+/** N bands opening together. */
   | 'blinds'
-  /** Caller-supplied clip-path or mask-image value — the escape hatch. */
+/** Caller-supplied clip-path or mask-image value — the escape hatch. */
   | 'shape'
 
 export type BlendMode =
@@ -467,40 +649,40 @@ export type MatteKind = 'luma' | 'alpha'
 
 export type MaskOpts = {
   direction?: MaskDirection
-  /** Feather width as a fraction of the element's box. 0 = hard edge. */
+/** Feather width as a fraction of the element's box. 0 = hard edge. */
   softness?: number
-  /** Band count for `blinds`. */
+/** Band count for `blinds`. */
   bands?: number
-  /** Centre for `iris` / `radial`, as fractions of the box. */
+/** Centre for `iris` / `radial`, as fractions of the box. */
   at?: { x?: number; y?: number }
-  /** For `shape`: any clip-path value. */
+/** For `shape`: any clip-path value. */
   shape?: string
   duration?: number
   ease?: string
 }
 
 export type MatteOpts = {
-  /** 'luma' uses the source's brightness, 'alpha' its transparency. */
+/** 'luma' uses the source's brightness, 'alpha' its transparency. */
   kind?: MatteKind
-  /** Sweep the matte across the target rather than holding it still. */
+/** Sweep the matte across the target rather than holding it still. */
   sweep?: boolean
   duration?: number
   ease?: string
 }
 
 export type FillOpts = {
-  /** A CSS gradient, e.g. 'linear-gradient(90deg,#ED1D24,#00B8FF)'. */
+/** A CSS gradient, e.g. 'linear-gradient(90deg,#ED1D24,#00B8FF)'. */
   gradient?: string
-  /** Or an image URL. */
+/** Or an image URL. */
   image?: string
-  /** How far the fill drifts across the glyphs, in percent. */
+/** How far the fill drifts across the glyphs, in percent. */
   drift?: number
   duration?: number
   ease?: string
 }
 
 export type BlendOpts = {
-  /** Opacity the layer fades up from. Default 0. */
+/** Opacity the layer fades up from. Default 0. */
   from?: number
   duration?: number
   ease?: string
@@ -512,35 +694,35 @@ export type MaskResult = {
 }
 
 export type MaskKit = {
-  /** Reveal ANY element through a moving mask — the general verb that
-   * `text.reveal('wipe')` and `logo.reveal('iris')` are special cases of. */
+/** Reveal ANY element through a moving mask — the general verb that
+* `text.reveal('wipe')` and `logo.reveal('iris')` are special cases of. */
   reveal: (
     target: string | Element | Element[],
     shape: MaskShape,
     opts?: MaskOpts,
     position?: gsap.Position
   ) => MaskResult
-  /** The mirror: mask the element back out. */
+/** The mirror: mask the element back out. */
   hide: (
     target: string | Element | Element[],
     shape: MaskShape,
     opts?: MaskOpts,
     position?: gsap.Position
   ) => MaskResult
-  /** Track matte: `source`'s silhouette becomes `target`'s visibility. */
+/** Track matte: `source`'s silhouette becomes `target`'s visibility. */
   matte: (
     target: string | Element,
     source: string | Element,
     opts?: MatteOpts,
     position?: gsap.Position
   ) => MaskResult
-  /** Fill an element's GLYPHS with a live layer and drift it. */
+/** Fill an element's GLYPHS with a live layer and drift it. */
   fill: (
     target: string | Element,
     opts?: FillOpts,
     position?: gsap.Position
   ) => MaskResult
-  /** Composite a layer against its beat with a blend mode. */
+/** Composite a layer against its beat with a blend mode. */
   blend: (
     target: string | Element | Element[],
     mode: BlendMode,
@@ -554,20 +736,20 @@ export type MaskKit = {
 export type AxisName = 'wght' | 'wdth' | 'slnt' | 'opsz' | (string & {})
 
 export type AxisEffect =
-  /** Ramp the axis from its current value to `to` and hold. */
+/** Ramp the axis from its current value to `to` and hold. */
   | 'ramp'
-  /** Ramp up and settle back — one breath. */
+/** Ramp up and settle back — one breath. */
   | 'pulse'
-  /** A per-character wave that travels through the line once. */
+/** A per-character wave that travels through the line once. */
   | 'wave'
 
 export type AxisOpts = {
-  /** Target axis value. Clamped to the face's declared range. */
+/** Target axis value. Clamped to the face's declared range. */
   to?: number
   from?: number
   duration?: number
   ease?: string
-  /** wave: seconds between adjacent characters. */
+/** wave: seconds between adjacent characters. */
   stagger?: number
 }
 
@@ -586,15 +768,15 @@ export type AxisKit = {
 // ─── 3D — a Three.js layer under the deterministic timeline ──────────────
 
 export type ThreeLayerOpts = {
-  /** Camera vertical FOV in degrees. */
+/** Camera vertical FOV in degrees. */
   fov?: number
-  /** Initial camera position. Default { x: 0, y: 0, z: 6 }. */
+/** Initial camera position. Default { x: 0, y: 0, z: 6 }. */
   camera?: { x?: number; y?: number; z?: number }
-  /** Layer opacity 0..1 (the canvas is a normal stage element). */
+/** Layer opacity 0..1 (the canvas is a normal stage element). */
   opacity?: number
-  /** Stacking: 'front' (default) composites the transparent layer above
-   * the DOM; 'back' slots it behind — note an opaque App background will
-   * hide a 'back' layer entirely. */
+/** Stacking: 'front' (default) composites the transparent layer above
+* the DOM; 'back' slots it behind — note an opaque App background will
+* hide a 'back' layer entirely. */
   depth?: 'back' | 'front'
 }
 
@@ -613,29 +795,29 @@ export type ThreeCameraPose = {
 }
 
 export type ThreeFrameOpts = {
-  /** Projected fraction of frame height occupied by the subject. Default 0.7. */
+/** Projected fraction of frame height occupied by the subject. Default 0.7. */
   height?: number
-  /** `contain` also enforces maxWidth; `height` may crop horizontally. */
+/** `contain` also enforces maxWidth; `height` may crop horizontally. */
   mode?: 'contain' | 'height'
   maxWidth?: number
   angle?: ThreeCameraAngle
-  /** Subject-to-camera direction. Overrides angle. */
+/** Subject-to-camera direction. Overrides angle. */
   direction?: { x: number; y: number; z: number }
   roll?: number
 }
 
 export type ThreeMoveOpts = {
   duration?: number
-  /** Camera travel ease. Defaults to the house dolly (`expo.inOut`), same as
-   * the 2D camera; pass one only when the user asks for a different feel. */
+/** Camera travel ease. Defaults to the house dolly (`expo.inOut`), same as
+* the 2D camera; pass one only when the user asks for a different feel. */
   ease?: string
 }
 
 export type ThreeOrbitOpts = ThreeFrameOpts &
   ThreeMoveOpts & {
-    /** Horizontal orbit delta in degrees. */
+/** Horizontal orbit delta in degrees. */
     azimuth?: number
-    /** Vertical orbit delta in degrees. */
+/** Vertical orbit delta in degrees. */
     elevation?: number
   }
 
@@ -646,7 +828,7 @@ export type ThreeLightingPreset =
   | 'studio-neutral'
 
 export type ThreeLightingOpts = {
-  /** Camera-relative stays flattering through a move; world-locked reveals form. */
+/** Camera-relative stays flattering through a move; world-locked reveals form. */
   mode?: 'camera-relative' | 'world-locked'
   intensity?: number
   exposure?: number
@@ -662,30 +844,30 @@ export type ThreeLightRig = {
 }
 
 export type ThreeCameraRig = {
-  /** Solve a pose whose projected subject bounds meet the framing constraint. */
+/** Solve a pose whose projected subject bounds meet the framing constraint. */
   frame: (subject: THREE.Object3D, opts?: ThreeFrameOpts) => ThreeCameraPose
-  /** Immediate deterministic camera cut to a resolved pose. */
+/** Immediate deterministic camera cut to a resolved pose. */
   set: (pose: ThreeCameraPose) => void
-  /** Tween XYZ, target, roll, and clipping planes while keeping the target locked. */
+/** Tween XYZ, target, roll, and clipping planes while keeping the target locked. */
   moveTo: (
     pose: ThreeCameraPose,
     opts?: ThreeMoveOpts,
     position?: gsap.Position
   ) => { duration: number }
-  /** Solve and dolly to a subject. */
+/** Solve and dolly to a subject. */
   focus: (
     subject: THREE.Object3D,
     frame?: ThreeFrameOpts,
     move?: ThreeMoveOpts,
     position?: gsap.Position
   ) => { duration: number; pose: ThreeCameraPose }
-  /** Orbit in camera-local spherical coordinates and re-solve framing. */
+/** Orbit in camera-local spherical coordinates and re-solve framing. */
   orbit: (
     subject: THREE.Object3D,
     opts?: ThreeOrbitOpts,
     position?: gsap.Position
   ) => { duration: number; pose: ThreeCameraPose }
-  /** Current planned pose, including moves not yet reached by the playhead. */
+/** Current planned pose, including moves not yet reached by the playhead. */
   pose: () => ThreeCameraPose
 }
 
@@ -698,19 +880,19 @@ export type ThreeLightingRig = {
 }
 
 export type ThreeLayer = {
-  /** The scene graph — add meshes, lights, groups. */
+/** The scene graph — add meshes, lights, groups. */
   scene: THREE.Scene
   camera: THREE.PerspectiveCamera
-  /** Subject-first XYZ camera control: exact projected framing, dolly, and orbit. */
+/** Subject-first XYZ camera control: exact projected framing, dolly, and orbit. */
   rig: ThreeCameraRig
-  /** Deterministic key/fill/rim presets bound to a 3D subject. */
+/** Deterministic key/fill/rim presets bound to a 3D subject. */
   lighting: ThreeLightingRig
-  /** The canvas element, for tweening opacity/filters like any element. */
+/** The canvas element, for tweening opacity/filters like any element. */
   canvas: HTMLCanvasElement
-  /** Drive the layer over [position, position+duration]. `update` runs every
-   * frame with eased progress 0..1 BEFORE the render — set uniforms, camera
-   * and material state from `t` alone (no clocks, no accumulation). Call
-   * once per active span; overlapping drives render redundantly. */
+/** Drive the layer over [position, position+duration]. `update` runs every
+* frame with eased progress 0..1 BEFORE the render — set uniforms, camera
+* and material state from `t` alone (no clocks, no accumulation). Call
+* once per active span; overlapping drives render redundantly. */
   drive: (
     duration: number,
     update?: (t: number) => void,
@@ -720,17 +902,17 @@ export type ThreeLayer = {
 }
 
 export type ThreeKit = {
-  /** Create a 3D layer sized to the stage. Everything async about it (first
-   * compile, first paint) completes before window.__ready. */
+/** Create a 3D layer sized to the stage. Everything async about it (first
+* compile, first paint) completes before window.__ready. */
   layer: (opts?: ThreeLayerOpts) => ThreeLayer
 }
 
 // ─── Actions — stateful cursor actors, press, scroll, drag ───────────────
 
 /** Built-in cursor icons. `collab` is the Figma-style colored arrow + name
- * chip for multi-user scenes. Custom art passes `{ svg, hotspot }` — the
- * hotspot (0..1 of the icon box, where the tip sits) is part of the contract,
- * so brand cursors cannot reopen the misaligned-click bug. */
+* chip for multi-user scenes. Custom art passes `{ svg, hotspot }` — the
+* hotspot (0..1 of the icon box, where the tip sits) is part of the contract,
+* so brand cursors cannot reopen the misaligned-click bug. */
 export type CursorIconName =
   | 'arrow'
   | 'pointer'
@@ -743,57 +925,57 @@ export type CursorIconName =
 export type CursorIcon = CursorIconName | { svg: string; hotspot: { x: number; y: number } }
 
 export type CursorActorOpts = {
-  /** Icon set. Default 'arrow'; named collaborators usually want 'collab'. */
+/** Icon set. Default 'arrow'; named collaborators usually want 'collab'. */
   icon?: CursorIcon
-  /** Tint for the collab arrow and label chip. */
+/** Tint for the collab arrow and label chip. */
   color?: string
-  /** Figma-style name tag riding the cursor. */
+/** Figma-style name tag riding the cursor. */
   label?: string
-  /** Icon box size in scene px. Default 56 (at 1080p) — marketing videos
-   * oversize the cursor so the action reads at a glance. */
+/** Icon box size in scene px. Default 56 (at 1080p) — marketing videos
+* oversize the cursor so the action reads at a glance. */
   size?: number
-  /** 'still' (default) or 'human' — sub-pixel drift while parked between
-   * actions, so a resting cursor never reads as a freeze-frame. */
+/** 'still' (default) or 'human' — sub-pixel drift while parked between
+* actions, so a resting cursor never reads as a freeze-frame. */
   idle?: 'still' | 'human'
-  /** Auto-morph arrow → pointer over the last stretch of a click travel.
-   * Default true. */
+/** Auto-morph arrow → pointer over the last stretch of a click travel.
+* Default true. */
   morph?: boolean
 }
 
 export type CursorMoveOpts = {
-  /** Travel time in seconds. Default 0.8. */
+/** Travel time in seconds. Default 0.8. */
   duration?: number
-  /** Default 'ease-in-out-cubic' — every action eases in-out. */
+/** Default 'ease-in-out-cubic' — every action eases in-out. */
   ease?: string
-  /** Where on the target to land, as fractions of its box. Default
-   * `{ x: 0.5, y: 0.52 }` — the corpus's observed natural click point. */
+/** Target-box fractions, reprojected each frame after camera/target transforms.
+* Default `{ x: 0.5, y: 0.52 }`. */
   anchor?: { x?: number; y?: number }
-  /** Extra scene-px nudge after the anchor. */
+/** Extra scene-px nudge after the anchor. */
   offset?: { x?: number; y?: number }
-  /** First-action entrance: 'edge' (default — slides in from the nearest
-   * frame edge) or 'fade' (materializes just short of the target, for tight
-   * close-ups where the edge is far away). Ignored while already visible. */
+/** First-action entrance: 'edge' (default — slides in from the nearest
+* frame edge) or 'fade' (materializes just short of the target, for tight
+* close-ups where the edge is far away). Ignored while already visible. */
   enter?: 'edge' | 'fade'
 }
 
 /** What the cursor does after the action — the continuity contract.
- * 'stay' (default) parks it where it is so the NEXT action continues from
- * there; 'exit' leaves via the nearest edge; 'park' steps aside just below
- * the target (clears it for typing or a reveal); a selector travels to that
- * element and parks there. */
+* 'stay' (default) parks it where it is so the NEXT action continues from
+* there; 'exit' leaves via the nearest edge; 'park' steps aside just below
+* the target (clears it for typing or a reveal); a selector travels to that
+* element and parks there. */
 export type CursorThen = 'stay' | 'exit' | 'park' | string
 
 export type CursorClickOpts = CursorMoveOpts & {
-  /** Target squash scale. 'auto' (default) derives from the element's size —
-   * big surfaces squash less. A number (e.g. 0.9) is used verbatim. */
+/** Target squash scale. 'auto' (default) derives from the element's size —
+* big surfaces squash less. A number (e.g. 0.9) is used verbatim. */
   press?: number | 'auto'
-  /** Squash time each way. Default 0.09. */
+/** Squash time each way. Default 0.09. */
   pressDuration?: number
   then?: CursorThen
 }
 
 export type CursorDragOpts = CursorMoveOpts & {
-  /** Subtle scale lift on the payload while it is held. Default true. */
+/** Subtle scale lift on the payload while it is held. Default true. */
   lift?: boolean
   then?: CursorThen
 }
@@ -801,50 +983,49 @@ export type CursorDragOpts = CursorMoveOpts & {
 export type CursorExitOpts = {
   duration?: number
   ease?: string
-  /** 'edge' (default) or 'fade'. */
+/** 'edge' (default) or 'fade'. */
   via?: 'edge' | 'fade'
 }
 
 export type CursorActor = {
-  /** Move to an element (or continue there from the last position). */
+/** Move to an element (or continue there from the last position). */
   to: (
     target: string | Element,
     opts?: CursorMoveOpts,
     position?: gsap.Position
   ) => { duration: number }
-  /** Travel + press: squashes the cursor AND the target, ordered so the
-   * click visibly precedes any result the direction schedules after it. */
+/** Travel + press: squashes the cursor AND the target, ordered so the
+* click visibly precedes any result the direction schedules after it. */
   click: (
     target: string | Element,
     opts?: CursorClickOpts,
     position?: gsap.Position
   ) => { duration: number }
-  /** Grab a payload and carry it: cursor and payload move as ONE tween pair
-   * with identical timing, so they cannot desync. `to` is an element/selector
-   * (payload centers on it) or a scene-px delta `{ x, y }`. */
+/** Track the transformed payload each frame. `to`: same-plane element/selector
+* (centers the payload) or scene-px delta `{ x, y }`. */
   drag: (
     payload: string | Element,
     to: string | Element | { x: number; y: number },
     opts?: CursorDragOpts,
     position?: gsap.Position
   ) => { duration: number }
-  /** Leave the frame. The next action re-enters fresh. */
+/** Leave the frame. The next action re-enters fresh. */
   exit: (opts?: CursorExitOpts, position?: gsap.Position) => { duration: number }
-  /** Update the collab name chip on the timeline. */
+/** Update the collab name chip on the timeline. */
   label: (text: string, position?: gsap.Position) => void
 }
 
 export type CursorKit = CursorActor & {
-  /** Declare a named cursor — an independent actor with its own icon, color,
-   * label chip, and continuity state. Two actors animate concurrently just by
-   * overlapping their positions. */
+/** Declare a named cursor — an independent actor with its own icon, color,
+* label chip, and continuity state. Two actors animate concurrently just by
+* overlapping their positions. */
   actor: (name: string, opts?: CursorActorOpts) => CursorActor
 }
 
 export type PressOpts = {
-  /** Squash scale; 'auto' (default) derives from element size. */
+/** Squash scale; 'auto' (default) derives from element size. */
   amount?: number | 'auto'
-  /** Each way. Default 0.09. */
+/** Each way. Default 0.09. */
   duration?: number
   ease?: string
 }
@@ -852,46 +1033,46 @@ export type PressOpts = {
 export type ScrollOpts = {
   duration?: number
   ease?: string
-  /** Where the target settles in the container: 0 top, 0.5 center (default),
-   * 1 bottom. */
+/** Where the target settles in the container: 0 top, 0.5 center (default),
+* 1 bottom. */
   align?: number
 }
 
 export type UiChange = {
-  /** Replace the element's text content. */
+/** Replace the element's text content. */
   text?: string
-  /** Set an input's value. */
+/** Set an input's value. */
   value?: string
-  /** Swap an image/video source. */
+/** Swap an image/video source. */
   src?: string
-  /** Set attributes verbatim. */
+/** Set attributes verbatim. */
   attrs?: Record<string, string>
-  /** Add/remove classes (resolved against the authored class list). */
+/** Add/remove classes (resolved against the authored class list). */
   classes?: { add?: string[]; remove?: string[] }
-  /** Brief brightness pulse after the change, so the state change reads as an
-   * event rather than a glitch. */
+/** Brief brightness pulse after the change, so the state change reads as an
+* event rather than a glitch. */
   flash?: boolean
 }
 
 export type ActionsKit = {
   cursor: CursorKit
-  /** Squash without a cursor — keyboard sends, programmatic actions. */
+/** Squash without a cursor — keyboard sends, programmatic actions. */
   press: (
     target: string | Element,
     opts?: PressOpts,
     position?: gsap.Position
   ) => { duration: number }
-  /** Animated scroll of a container until `to` (element, selector, or an
-   * absolute scrollTop) is in view. `duration: 0` sets it instantly for
-   * initial state. */
+/** Animated scroll of a container until `to` (element, selector, or an
+* absolute scrollTop) is in view. `duration: 0` sets it instantly for
+* initial state. */
   scroll: (
     container: string | Element,
     to: string | Element | number,
     opts?: ScrollOpts,
     position?: gsap.Position
   ) => { duration: number }
-  /** Declarative hard UI state change on the timeline (seek-reversible).
-   * Instant by design — a cut is hard; `flash` adds the one animated accent. */
+/** Declarative hard UI state change on the timeline (seek-reversible).
+* Instant by design — a cut is hard; `flash` adds the one animated accent. */
   ui: {
     set: (
       target: string | Element,
@@ -906,37 +1087,37 @@ export type ActionsKit = {
 export type HighlightRelease = 'fade' | 'undraw' | 'hold'
 
 export type HighlightOpts = {
-  /** Stroke/fill color. Each primitive has its own sensible default. */
+/** Stroke/fill color. Each primitive has its own sensible default. */
   color?: string
-  /** Draw-on time in seconds. */
+/** Draw-on time in seconds. */
   duration?: number
-  /** Default 'ease-in-out-cubic'. */
+/** Default 'ease-in-out-cubic'. */
   ease?: string
-  /** Seconds the highlight holds after drawing, or 'hold' to stay to the end.
-   * Default 'hold' — releasing is a deliberate choice. */
+/** Seconds the highlight holds after drawing, or 'hold' to stay to the end.
+* Default 'hold' — releasing is a deliberate choice. */
   persist?: number | 'hold'
-  /** How it leaves when persist is a number: 'fade' (default) or 'undraw'. */
+/** How it leaves when persist is a number: 'fade' (default) or 'undraw'. */
   release?: Exclude<HighlightRelease, 'hold'>
-  /** Extra space around the target in scene px. Default derives from size. */
+/** Extra space around the target in scene px. Default derives from size. */
   padding?: number
-  /** Stroke thickness in px. */
+/** Stroke thickness in px. */
   thickness?: number
-  /** What to fit: 'text' hugs the glyphs (a block element's box spans its
-   * full column — a marker on "99.99%" must not swallow the empty half of
-   * the card); 'box' takes the element box. Marker, circle, and underline
-   * default to 'text'; ring, glow, and spotlight default to 'box'. */
+/** What to fit: 'text' hugs the glyphs (a block element's box spans its
+* full column — a marker on "99.99%" must not swallow the empty half of
+* the card); 'box' takes the element box. Marker, circle, and underline
+* default to 'text'; ring, glow, and spotlight default to 'box'. */
   fit?: 'text' | 'box'
 }
 
 export type SpotlightOpts = {
-  /** How dark the rest of the frame goes (0..1). Default 0.55. */
+/** How dark the rest of the frame goes (0..1). Default 0.55. */
   dim?: number
-  /** Defocus everything OUTSIDE the cutout by this many px (the target stays
-   * sharp). 0 (default) dims only. Engine ceiling: 20. */
+/** Defocus everything OUTSIDE the cutout by this many px (the target stays
+* sharp). 0 (default) dims only. Engine ceiling: 20. */
   blur?: number
-  /** Gaussian softness of the cutout edge in px. Default 26. */
+/** Gaussian softness of the cutout edge in px. Default 26. */
   feather?: number
-  /** Breathing room between the element's edge and the cutout, px. Default 16. */
+/** Breathing room between the element's edge and the cutout, px. Default 16. */
   padding?: number
   duration?: number
   ease?: string
@@ -944,51 +1125,51 @@ export type SpotlightOpts = {
 }
 
 export type HighlightKit = {
-  /** Rounded ring draws itself around the element, following its corner
-   * radius. The workhorse product-tour annotation. */
+/** Rounded ring draws itself around the element, following its corner
+* radius. The workhorse product-tour annotation. */
   ring: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
-  /** Hand-drawn ellipse loop with overshoot — red-pen annotation energy. */
+/** Hand-drawn ellipse loop with overshoot — red-pen annotation energy. */
   circle: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
-  /** Highlighter-pen swipe behind the glyphs: a skewed band wipes across in
-   * multiply blend, sized from the line height. */
+/** Highlighter-pen swipe behind the glyphs: a skewed band wipes across in
+* multiply blend, sized from the line height. */
   marker: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
-  /** Underline draw. Styles: 'straight' | 'marker' | 'sketch'. */
+/** Underline draw. Styles: 'straight' | 'marker' | 'sketch'. */
   underline: (
     target: string | Element,
     style?: 'straight' | 'marker' | 'sketch',
     opts?: HighlightOpts,
     position?: gsap.Position
   ) => { duration: number }
-  /** One soft glow pulse as a beat lands — light, not opacity. */
+/** One soft glow pulse as a beat lands — light, not opacity. */
   glow: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
-  /** Inverse move: everything EXCEPT the target dims behind a feathered
-   * cutout. The strongest "look here" in the vocabulary. */
+/** Inverse move: everything EXCEPT the target dims behind a feathered
+* cutout. The strongest "look here" in the vocabulary. */
   spotlight: (target: string | Element, opts?: SpotlightOpts, position?: gsap.Position) => { duration: number }
 }
 
 // ─── Looks — scene light, shading, backdrops, hero shot, track ───────────
 
 export type LightState = {
-  /** Direction the light COMES FROM, degrees clockwise from 12 o'clock.
-   * 135 = upper-left key (the portrait default). */
+/** Direction the light COMES FROM, degrees clockwise from 12 o'clock.
+* 135 = upper-left key (the portrait default). */
   angle: number
-  /** 0 cool … 1 warm. Tints sweeps and rims. */
+/** 0 cool … 1 warm. Tints sweeps and rims. */
   warmth: number
 }
 
 export type LightKit = {
-  /** Declare the scene light. Call once, early; sweeps, rims, and cast
-   * shadows derive their direction from it. */
+/** Declare the scene light. Call once, early; sweeps, rims, and cast
+* shadows derive their direction from it. */
   set: (state: Partial<LightState>) => void
-  /** A glint sweeps across the element, angled with the scene light — the
-   * `logo.shine` move generalized to any surface. */
+/** A glint sweeps across the element, angled with the scene light — the
+* `logo.shine` move generalized to any surface. */
   sweep: (
     target: string | Element,
     opts?: { duration?: number; intensity?: number; width?: number; ease?: string },
     position?: gsap.Position
   ) => { duration: number }
-  /** Edge light on the side facing the scene light — the premium product-
-   * shot rim. Fades in and holds. */
+/** Edge light on the side facing the scene light — the premium product-
+* shot rim. Fades in and holds. */
   rim: (
     target: string | Element,
     opts?: { color?: string; intensity?: number; duration?: number },
@@ -997,22 +1178,22 @@ export type LightKit = {
 }
 
 export type ShadeKit = {
-  /** Soft shadow under the element, offset along the scene light. Replaces
-   * hand-tuned boxShadow strings and always agrees with every other shadow. */
+/** Soft shadow under the element, offset along the scene light. Replaces
+* hand-tuned boxShadow strings and always agrees with every other shadow. */
   cast: (
     target: string | Element,
     opts?: { distance?: number; softness?: number; opacity?: number; duration?: number },
     position?: gsap.Position
   ) => { duration: number }
-  /** Frame vignette, faded in once and held (like the grain plate — never
-   * cut, so it doesn't blink at hard cuts). */
+/** Frame vignette, faded in once and held (like the grain plate — never
+* cut, so it doesn't blink at hard cuts). */
   vignette: (
     opts?: { strength?: number; duration?: number },
     position?: gsap.Position
   ) => { duration: number }
-  /** Named color grade on the scene content. 'warm-product' | 'cool-saas' |
-   * 'noir'. Applied to the scene root, so overlays (cursors, highlights)
-   * stay ungraded and legible. */
+/** Named color grade on the scene content. 'warm-product' | 'cool-saas' |
+* 'noir'. Applied to the scene root, so overlays (cursors, highlights)
+* stay ungraded and legible. */
   grade: (
     preset: 'warm-product' | 'cool-saas' | 'noir',
     opts?: { duration?: number },
@@ -1032,28 +1213,28 @@ export type BackdropStyle =
   | 'grid-glow'
 
 export type BackdropOpts = {
-  /** 0..1 — scales amplitude, speed, and opacity together. The default 0.3
-   * keeps the preset inside the sub-salient budget. */
+/** 0..1 — scales amplitude, speed, and opacity together. The default 0.3
+* keeps the preset inside the sub-salient budget. */
   energy?: number
-  /** Colors for the soft forms. Keep them near the scene's background
-   * luminance — the preset caps opacity, but hue contrast is yours. */
+/** Colors for the soft forms. Keep them near the scene's background
+* luminance — the preset caps opacity, but hue contrast is yours. */
   palette?: string[]
-  /** Base fill the backdrop paints under its forms. The backdrop mounts
-   * BEHIND the scene root, so a root that goes transparent needs the
-   * backdrop to own the ground color. */
+/** Base fill the backdrop paints under its forms. The backdrop mounts
+* BEHIND the scene root, so a root that goes transparent needs the
+* backdrop to own the ground color. */
   base?: string
-  /** FIXED BACKPLATE (default true): mount outside the camera-carrying
-   * stage, so zooms and pans move the UI plane while the ground stays put —
-   * the studio-cyclorama behavior of reference launch films. Set false to
-   * make the backdrop part of the world the camera moves through. */
+/** FIXED BACKPLATE (default true): mount outside the camera-carrying
+* stage, so zooms and pans move the UI plane while the ground stays put —
+* the studio-cyclorama behavior of reference launch films. Set false to
+* make the backdrop part of the world the camera moves through. */
   fixed?: boolean
 }
 
 export type BackdropHandle = {
   el: HTMLElement
-  /** Duck the backdrop under a dense foreground beat. */
+/** Duck the backdrop under a dense foreground beat. */
   calm: (position?: gsap.Position) => void
-  /** Bring it back up during a hold. */
+/** Bring it back up during a hold. */
   lift: (position?: gsap.Position) => void
 }
 
@@ -1062,26 +1243,26 @@ export type HeroAnchor =
   | { x: number; y: number }
 
 export type HeroOpts = {
-  /** Which region of the target the camera pushes toward. Default
-   * 'bottom-right' — the submit-button corner. */
+/** Which region of the target the camera pushes toward. Default
+* 'bottom-right' — the submit-button corner. */
   anchor?: HeroAnchor
-  /** How far in: scale ≈ (frame width / target width) × zoom. Default 1.35 —
-   * the target overflows the frame, close-up territory. */
+/** How far in: scale ≈ (frame width / target width) × zoom. Default 1.35 —
+* the target overflows the frame, close-up territory. */
   zoom?: number
-  /** Perspective tilt in degrees. Defaults derive from the anchor (the panel
-   * leans its far corner away): e.g. bottom-right → pitch 7, yaw -9. */
+/** Perspective tilt in degrees. Defaults derive from the anchor (the panel
+* leans its far corner away): e.g. bottom-right → pitch 7, yaw -9. */
   pitch?: number
   yaw?: number
-  /** Push-in time. Default 0.9. */
+/** Push-in time. Default 0.9. */
   duration?: number
-  /** Seconds held at the angle before returning. Default 1.2. */
+/** Seconds held at the angle before returning. Default 1.2. */
   hold?: number
-  /** Return time. Default 0.8; `settle: false` stays in the pose. */
+/** Return time. Default 0.8; `settle: false` stays in the pose. */
   returnDuration?: number
   settle?: boolean
-  /** Sheen sweep across the surface during the push. Default true. */
+/** Sheen sweep across the surface during the push. Default true. */
   sheen?: boolean
-  /** Shadow deepens as the panel lifts. Default true. */
+/** Shadow deepens as the panel lifts. Default true. */
   shadow?: boolean
   ease?: string
 }
@@ -1089,39 +1270,39 @@ export type HeroOpts = {
 export type LooksKit = {
   light: LightKit
   shade: ShadeKit
-  /** Mount an ambient animated backdrop behind the scene root. */
+/** Mount an ambient animated backdrop behind the scene root. */
   backdrop: (style: BackdropStyle, opts?: BackdropOpts) => BackdropHandle
-  /** The angle-zoom product shot: camera pushes toward one corner of the
-   * target while it tilts in perspective, sheen and shadow responding.
-   * A full round trip by default. */
+/** The angle-zoom product shot: camera pushes toward one corner of the
+* target while it tilts in perspective, sheen and shadow responding.
+* A full round trip by default. */
   hero: (target: string | Element, opts?: HeroOpts, position?: gsap.Position) => { duration: number }
-  /** Standalone perspective pose: tilt an element (not the stage) and hold.
-   * Tilt back with pitch/yaw 0. */
+/** Standalone perspective pose: tilt an element (not the stage) and hold.
+* Tilt back with pitch/yaw 0. */
   tilt: (
     target: string | Element,
     opts?: { pitch?: number; yaw?: number; duration?: number; ease?: string; perspective?: number },
     position?: gsap.Position
   ) => { duration: number }
-  /** Camera FOLLOWS an element while it moves: per-frame the tracked
-   * element's live position re-centers the camera at a locked occupancy.
-   * Seek-deterministic — each frame is a pure function of timeline position
-   * (the catch-up from `from` is an eased blend, not stateful smoothing).
-   * AUTHOR IT AFTER the motion it follows, so it renders after the movers. */
+/** Camera FOLLOWS an element while it moves: per-frame the tracked
+* element's live position re-centers the camera at a locked occupancy.
+* Seek-deterministic — each frame is a pure function of timeline position
+* (the catch-up from `from` is an eased blend, not stateful smoothing).
+* AUTHOR IT AFTER the motion it follows, so it renders after the movers. */
   track: (
     target: string | Element,
     opts?: {
-      /** Tracking window in seconds. Default 2. */
+/** Tracking window in seconds. Default 2. */
       duration?: number
-      /** Target occupancy as fraction of frame height. Default 0.5. */
+/** Target occupancy as fraction of frame height. Default 0.5. */
       height?: number
-      /** Fraction of the window spent easing from `from` onto the target.
-       * Default 0.25. */
+/** Fraction of the window spent easing from `from` onto the target.
+* Default 0.25. */
       attach?: number
-      /** Camera pose the track blends FROM (what the camera shows when the
-       * window opens). Default full frame. */
+/** Camera pose the track blends FROM (what the camera shows when the
+* window opens). Default full frame. */
       from?: { scale: number; x: number; y: number }
-      /** After the window: 'hold' keeps the last framing (a later camera call
-       * takes over); 'full' returns to the full frame. Default 'full'. */
+/** After the window: 'hold' keeps the last framing (a later camera call
+* takes over); 'full' returns to the full frame. Default 'full'. */
       release?: 'hold' | 'full'
     },
     position?: gsap.Position
@@ -1142,85 +1323,129 @@ export type SentenceHandle = {
 // ─── Morph — any element becomes any other element ───────────────────────
 
 export type MorphOpts = {
-  /** 'apple' = a firm in-out flight that keeps the deformation READABLE —
-   * the shape change is the subject, so it may not be over in three frames.
-   * 'spring' = the same flight with the reference bounce: a LIGHT damped
-   * sine riding the same path, calibrated from the dnyxstudios AE expression
-   * (amp .04·v, freq 1.8Hz, decay e^-3t, eased envelope). One motion, no
-   * delayed settle, ~one visible overshoot.
-   *
-   * Both are `ease-in-out-*` by design. A morph is travel WITHIN the frame,
-   * and the house table reserves `ease-out-*` for entrances; a front-loaded
-   * curve finishes the transformation before the viewer can look at it. */
+/** 'apple' = a firm in-out flight that keeps the deformation READABLE —
+* the shape change is the subject, so it may not be over in three frames.
+* 'spring' = the same flight with the reference bounce: a LIGHT damped
+* sine riding the same path, calibrated from the dnyxstudios AE expression
+* (amp .04·v, freq 1.8Hz, decay e^-3t, eased envelope). One motion, no
+* delayed settle, ~one visible overshoot.
+*
+* Both are `ease-in-out-*` by design. A morph is travel WITHIN the frame,
+* and the house table reserves `ease-out-*` for entrances; a front-loaded
+* curve finishes the transformation before the viewer can look at it. */
   feel?: 'apple' | 'spring'
-  /** Tune the 'spring' bounce. `amp` = first overshoot as a fraction of the
-   * travel (default 0.025 — light), `freq` Hz (default 1.8), `decay` per
-   * second (default 3), `flight` = fraction of `duration` spent on the main
-   * move before the bounce tail (default 0.55). */
+/** Tune the 'spring' bounce. `amp` = first overshoot as a fraction of the
+* travel (default 0.025 — light), `freq` Hz (default 1.8), `decay` per
+* second (default 3), `flight` = fraction of `duration` spent on the main
+* move before the bounce tail (default 0.55). */
   bounce?: { amp?: number; freq?: number; decay?: number; flight?: number }
   duration?: number
-  /** Flight curve — ANY GSAP ease works: house names, 'elastic.out(1, 0.4)',
-   * 'back.out(1.8)'… Overshoots extrapolate past the target (kept renderable). */
+/** Flight curve — ANY GSAP ease works: house names, 'elastic.out(1, 0.4)',
+* 'back.out(1.8)'… Overshoots extrapolate past the target (kept renderable). */
   ease?: string
-  /** 0..1 in EASED space — where along the SHAPE CHANGE the surface swaps
-   * from A to B. Not a fade midpoint: at this instant both sides hold the
-   * same box and the same chrome, so the swap is a match-frame cut. 0.5
-   * means "when the shape is halfway between the two," which is what the
-   * viewer actually perceives. */
+/** 0..1 in EASED space — where along the SHAPE CHANGE the surface swaps
+* from A to B. Not a fade midpoint: at this instant both sides hold the
+* same box and the same chrome, so the swap is a match-frame cut. 0.5
+* means "when the shape is halfway between the two," which is what the
+* viewer actually perceives. */
   handoff?: number
-  /** Fraction of the flight over which unmatched content departs and
-   * arrives (default 0.42). Content displaces along the travel vector and
-   * must be clear of the seam — that emptiness is what makes the cut
-   * invisible, so widening this past ~0.5 will start to show the swap. */
+/** Fraction of the flight over which unmatched content departs and
+* arrives (default 0.42). Content displaces along the travel vector and
+* must be clear of the seam — that emptiness is what makes the cut
+* invisible, so widening this past ~0.5 will start to show the swap. */
   content?: number
-  /** Arc lift in px (0 disables). Default: auto from travel distance. */
+/** Arc lift in px (0 disables). Default: auto from travel distance. */
   arc?: number
-  /** Content choreography (default 'displace'): unmatched children leave and
-   * arrive by moving ALONG the travel vector — replacement reads as motion,
-   * and both sides are clear of the seam before the surfaces swap.
-   * `false` = containers only; children hold still and stay counter-scaled,
-   * which is right when the two sides share a background image or the
-   * content is meant to look continuous. */
+/** Content choreography (default 'displace'): unmatched children leave and
+* arrive by moving ALONG the travel vector — replacement reads as motion,
+* and both sides are clear of the seam before the surfaces swap.
+* `false` = containers only; children hold still and stay counter-scaled,
+* which is right when the two sides share a background image or the
+* content is meant to look continuous. */
   parts?: 'displace' | false
-  /** Sub-component matching (default 'auto'): elements tagged
-   * `data-morph="name"` on BOTH sides (any depth) morph INTO each other —
-   * each pair rides its own interpolated box inside the flight, so the
-   * source's sub-component visibly becomes the target's. Untagged direct
-   * children are greedily auto-paired by text overlap. `false` disables. */
+/** Sub-component matching (default 'auto'): elements tagged
+* `data-morph="name"` on BOTH sides (any depth) morph INTO each other —
+* each pair rides its own interpolated box inside the flight, so the
+* source's sub-component visibly becomes the target's. Untagged direct
+* children are greedily auto-paired by text overlap. `false` disables. */
   match?: 'auto' | false
-  /** Landing overshoot on top of a non-spring flight. `true`/default object
-   * for the soft house settle, `{ scale, duration, ease }` to tune (elastic
-   * landings live here), `false` for none. 'spring' feel ignores this — its
-   * ring is already in the flight. */
+/** Landing overshoot on top of a non-spring flight. `true`/default object
+* for the soft house settle, `{ scale, duration, ease }` to tune (elastic
+* landings live here), `false` for none. 'spring' feel ignores this — its
+* ring is already in the flight. */
   settle?: boolean | { scale?: number; duration?: number; ease?: string }
   zIndex?: number
 }
 
+// ─── Morph surfaces — continuous vector material and DOM continuity ──────
+
+export type MorphSurfaceLayer = {
+  from: string; to: string; color?: string; endColor?: string
+  stroke?: number; opacity?: number; endOpacity?: number
+}
+
+export type MorphSurfaceOpts = MorphTreeOpts & {
+  layers: MorphSurfaceLayer[]
+/** Coordinates of the authored vector surface; roots provide its CSS size. */
+  viewBox?: string
+/** Keep decoration inside the changing outer shape; null disables clipping. */
+  clipToLayer?: number | null
+}
+
+export type MorphSurfaceResult = MorphTreeResult & { surfaceLayers: number }
+
+// ─── Morph tree — recursive continuity ───────────────────────────────────
+
+export type MorphTreeOpts = {
+  duration?: number
+  ease?: string
+/** How deep to recurse before children ride their parent rigidly. */
+  maxDepth?: number
+/** Perceptual budget: how many nodes may move independently. Past ~6 the
+* eye stops reading structure and starts seeing a swarm. */
+  maxMoving?: number
+/** Minimum affinity to call two elements the same thing. Lower = more
+* matches and more motion; higher = more collapse-and-emerge. */
+  floor?: number
+/** Fraction of the flight each depth level waits before it resolves.
+* Parents commit first; children follow. 0 disables the cascade. */
+  lead?: number
+/** Gather N sources into one target when the counts are lopsided. */
+  cluster?: boolean
+  arc?: number
+}
+
+export type MorphTreeResult = {
+  duration: number
+  moving: number
+  debug: string
+}
+
 // ─── Engine — the direction context you write against ────────────────────
 
 /** Render directives a scene (or a kit, during the direction) hands to the
- * exporter. The channel already exists end to end: `export const output` in
- * direction.ts → loadScene → buildScene → window.__config → the exporter's
- * probe — and because __config is assigned AFTER the direction runs, a kit
- * can set these from inside a direction call. Everything optional; absent
- * means today's behaviour exactly. */
+* exporter. The channel already exists end to end: `export const output` in
+* direction.ts → loadScene → buildScene → window.__config → the exporter's
+* probe — and because __config is assigned AFTER the direction runs, a kit
+* can set these from inside a direction call. Everything optional; absent
+* means today's behaviour exactly. */
 export type RenderConfig = {
-  /** Temporal motion blur (Phase 6). `off` (default) renders one sample per
-   * frame. Tiers fix samples-per-frame; `runs` limits blur to intervals so a
-   * 30s clip with 6s of camera moves does not pay the multiplier throughout. */
+/** Temporal motion blur (Phase 6). `off` (default) renders one sample per
+* frame. Tiers fix samples-per-frame; `runs` limits blur to intervals so a
+* 30s clip with 6s of camera moves does not pay the multiplier throughout. */
   blur?: {
     tier?: 'off' | 'light' | 'full'
-    /** Shutter angle in degrees, 0–360. Default 180. Costs nothing — it only
-     * changes WHICH times get sampled, never how many. */
+/** Shutter angle in degrees, 0–360. Default 180. Costs nothing — it only
+* changes WHICH times get sampled, never how many. */
     shutter?: number
-    /** Blur only these intervals, in seconds. Absent = the whole timeline. */
+/** Blur only these intervals, in seconds. Absent = the whole timeline. */
     runs?: Array<{ from: number; to: number }>
   }
 }
 
 /** Committed output of scripts/analyze-music.mjs — one JSON per track in
- * music/analysis/. A static file, identical in every export shard, which is
- * what makes audio-reactive motion compatible with seek-anywhere rendering. */
+* music/analysis/. A static file, identical in every export shard, which is
+* what makes audio-reactive motion compatible with seek-anywhere rendering. */
 export type TrackAnalysis = {
   analyzerVersion: number
   rate: number // envelope grid Hz
@@ -1236,25 +1461,25 @@ export type TrackAnalysis = {
 }
 
 export type AudioKit = {
-  /** True when a real analysis file was loaded. When false every envelope
-   * reads 0 and the beat grid is synthetic — directions never throw. */
+/** True when a real analysis file was loaded. When false every envelope
+* reads 0 and the beat grid is synthetic — directions never throw. */
   live: boolean
   bpm: number
   beats: number[]
   downbeats: number[]
   onsets: number[]
   sections: Array<{ start: number; end: number; energy: number }>
-  /** Overall loudness at timeline time t, 0..1. Pure lookup — the exporter
-   * loops the track under a longer video, so t wraps at the track length. */
+/** Overall loudness at timeline time t, 0..1. Pure lookup — the exporter
+* loops the track under a longer video, so t wraps at the track length. */
   energy: (t: number) => number
   band: (t: number, band: 'low' | 'mid' | 'high') => number
-  /** Timeline time of beat n (downbeat-phase corrected). */
+/** Timeline time of beat n (downbeat-phase corrected). */
   beat: (n: number) => number
-  /** Map the energy envelope onto element properties: one proxy tween whose
-   * onUpdate reads energy(t) — a pure function of playhead, so it renders
-   * identically from any seek. `map` receives 0..1 and returns gsap vars to
-   * set, e.g. (e) => ({ scale: 1 + e * 0.06 }). NO smoothing at read time:
-   * an IIR filter over successive frames is the shard-seam bug. */
+/** Map the energy envelope onto element properties: one proxy tween whose
+* onUpdate reads energy(t) — a pure function of playhead, so it renders
+* identically from any seek. `map` receives 0..1 and returns gsap vars to
+* set, e.g. (e) => ({ scale: 1 + e * 0.06 }). NO smoothing at read time:
+* an IIR filter over successive frames is the shard-seam bug. */
   drive: (
     target: string | Element,
     map: (energy: number) => Record<string, number | string>,
@@ -1264,7 +1489,7 @@ export type AudioKit = {
 }
 
 export type Output = {
-  /** Delivery raster dimensions. They do not change scene layout. */
+/** Delivery raster dimensions. They do not change scene layout. */
   width: number
   height: number
   fps: number
@@ -1272,7 +1497,7 @@ export type Output = {
 }
 
 /** Resolved renderer contract. `width`/`height` are always logical scene
- * coordinates; only the exporter consumes `delivery` as raster dimensions. */
+* coordinates; only the exporter consumes `delivery` as raster dimensions. */
 export type StageConfig = Output & {
   composition: { width: number; height: number }
   delivery: { width: number; height: number }
@@ -1285,21 +1510,21 @@ export type FramingTarget = string | Element | Rect | FramingTarget[]
 export type Framing = { scale: number; x: number; y: number }
 
 export type CameraFocusOpts = {
-  /** Fraction of the composition height occupied by the subject. Default 0.7. */
+/** Fraction of the composition height occupied by the subject. Default 0.7. */
   height?: number
-  /** `contain` also caps width; `height` guarantees height and may crop horizontally. */
+/** `contain` also caps width; `height` guarantees height and may crop horizontally. */
   mode?: 'contain' | 'height'
-  /** Width cap used by `contain`. Default 0.9. */
+/** Width cap used by `contain`. Default 0.9. */
   maxWidth?: number
-  /** Optional safety ceiling. When hit, exact occupancy cannot be guaranteed. */
+/** Optional safety ceiling. When hit, exact occupancy cannot be guaranteed. */
   maxScale?: number
   offsetX?: number
   offsetY?: number
   clamp?: boolean
-  /** Camera travel time. Default 0.8 seconds. */
+/** Camera travel time. Default 0.8 seconds. */
   duration?: number
-  /** Camera travel ease. Defaults to the house dolly (`expo.inOut`); pass one
-   * only when the user explicitly asks for a different camera feel. */
+/** Camera travel ease. Defaults to the house dolly (`expo.inOut`); pass one
+* only when the user explicitly asks for a different camera feel. */
   ease?: string
 }
 
@@ -1316,12 +1541,12 @@ export type FramingOpts = {
 export type TypeOpts = {
   cps?: number // characters per second
   caret?: boolean
-  /** Opt-in invisible tracking head that glides smoothly along the typed
-   * text — constant speed within each visual line, a quick eased drop at
-   * every wrap. Hand it to `track()` or a camera framing; the caret itself
-   * steps per character and wraps, so never track the caret directly.
-   * `width` is the head's scene-px width (default 300); `height` is a
-   * multiple of the line height (default 2.9). */
+/** Opt-in invisible tracking head that glides smoothly along the typed
+* text — constant speed within each visual line, a quick eased drop at
+* every wrap. Hand it to `track()` or a camera framing; the caret itself
+* steps per character and wraps, so never track the caret directly.
+* `width` is the head's scene-px width (default 300); `height` is a
+* multiple of the line height (default 2.9). */
   head?: boolean | { width?: number; height?: number }
 }
 
@@ -1342,8 +1567,8 @@ export type TextStyleOverride = {
   color?: string
   x?: number
   y?: number
-  /** Wrapping width in scene px — the side bars reflow text instead of
-   * scale-squeezing it. Applied as inline-block + width. */
+/** Wrapping width in scene px — the side bars reflow text instead of
+* scale-squeezing it. Applied as inline-block + width. */
   width?: number
   hidden?: boolean
 }
@@ -1355,13 +1580,13 @@ export type ObjectPositionOverride = {
   scaleY?: number
   rotation?: number
   hidden?: boolean
-  /** Plain CSS declarations the studio applies to the object's element —
-   * border-radius, background-color, box-shadow and friends. Applied at
-   * stage prepare, so they ride the structural rebuild route. */
+/** Plain CSS declarations the studio applies to the object's element —
+* border-radius, background-color, box-shadow and friends. Applied at
+* stage prepare, so they ride the structural rebuild route. */
   styles?: Record<string, string>
-  /** Replacement source for the image or video the object carries (the
-   * element itself or its first img/video descendant), usually a data URI so
-   * renders never depend on the network. */
+/** Replacement source for the image or video the object carries (the
+* element itself or its first img/video descendant), usually a data URI so
+* renders never depend on the network. */
   src?: string
 }
 
@@ -1379,10 +1604,10 @@ export type SceneOverrides = {
   textStyles?: Record<string, TextStyleOverride>
   addedText?: Record<string, AddedTextLayer>
   objects?: Record<string, ObjectPositionOverride> // stable UI wrapper id -> scene-pixel offset
-  /** Explicit paint order for editable siblings. Keys include the editable
-   * kind (`object:…` / `text:…`) so independently generated ids cannot
-   * collide. Values are normalized by the studio whenever an item moves in
-   * the stack. */
+/** Explicit paint order for editable siblings. Keys include the editable
+* kind (`object:…` / `text:…`) so independently generated ids cannot
+* collide. Values are normalized by the studio whenever an item moves in
+* the stack. */
   layerOrder?: Record<string, number>
 }
 
@@ -1402,6 +1627,54 @@ export type TweenKind =
   | 'axis'
   | 'three'
 
+export type EaseFingerprint = [number, number, number, number]
+
+export type EaseResolutionInfo = {
+  requested: string
+  resolvedId: string
+  status: 'default' | 'resolved' | 'custom' | 'unresolved'
+  resolvedFingerprint: EaseFingerprint
+}
+
+export type MotionOperationInfo = {
+  operationId: string
+  primitive: string
+  target?: string
+  targetCount?: number
+  requestedOptionKeys: string[]
+  acceptedOptionKeys: string[]
+  droppedOptionKeys: string[]
+  ease?: EaseResolutionInfo
+  effective?: {
+    transition?: {
+      style: string
+      direction: string
+      color: string
+      duration: number
+      at: { x: number; y: number }
+    }
+    blur?: {
+      from: number
+      to: number
+      tier: string
+      samples: number
+      shutter: number
+    }
+  }
+}
+
+export type ExecutionDiagnostic = {
+  code: 'unresolved-ease' | 'unknown-option-key' | 'dead-selector'
+  operationId: string
+  primitive: string
+  message: string
+}
+
+export type ExecutionIntegrityInspection = {
+  operations: MotionOperationInfo[]
+  diagnostics: ExecutionDiagnostic[]
+}
+
 export type TweenInfo = {
   id: number
   sig: string
@@ -1411,11 +1684,17 @@ export type TweenInfo = {
   duration: number // per-target duration (excludes stagger span)
   total: number // full span including stagger
   ease: string // '' = gsap default
+  target: string
+  targetCount: number
+  easeRequested: string
+  easeResolvedId: string
+  easeResolutionStatus: 'default' | 'resolved' | 'custom' | 'unresolved'
+  easeFingerprint: EaseFingerprint
   stagger?: number
   vars: Record<string, number | string>
   overridden: boolean
-  /** The editable layer this tween animates, when its first Element target
-   * sits inside one — lets the studio show a layer's choreography. */
+/** The editable layer this tween animates, when its first Element target
+* sits inside one — lets the studio show a layer's choreography. */
   targetObjectId?: string
   targetTextId?: string
 }
@@ -1428,14 +1707,50 @@ export type SceneInspection = {
   tweens: TweenInfo[]
   cameraSets: CameraSetInfo[]
   overrides: SceneOverrides
-  /**
-   * Non-fatal build complaints — a step whose element is gone, a text effect
-   * with nothing left to split. The scene still plays; these say what silently
-   * does nothing so a stale selector can't rot unnoticed.
-   */
+/**
+* Non-fatal build complaints — a step whose element is gone, a text effect
+* with nothing left to split. The scene still plays; these say what silently
+* does nothing so a stale selector can't rot unnoticed.
+*/
   warnings: string[]
-}
-
+/** Observational diagnostics; never rejects or changes authored motion. */
+  execution: ExecutionIntegrityInspection
+}
+
+/**
+* The context a direction is written against.
+*
+* HOW A FILM IS WRITTEN. `createFilmSequencer` (kit/film) owns semantic
+* ordering. `createWorldCamera` (kit/world) owns named-object framing, depth,
+* and camera gestures—never content animation or editorial rhythm:
+*
+*   const film = createFilmSequencer({ tl })
+*   const world = createWorldCamera({ tl, stage, camera, register: 'promo' })
+*   const copy = createTextPlans(text)
+*   const result = film.do(manner.realize('[data-obj="RESULT_ROWS"]'))
+*   film.do(world.camera.whipTo('RESULT_ROWS').landWith(result))
+*   film.do(copy.exit('[data-claim]', 'rise'))
+*   film.cut(editorial.cut(layers, next), world.camera.cutTo('NEXT'))
+*
+* Camera verbs are `cutTo` / `moveTo` / `zoomTo` / `whipTo` / `departTo` /
+* `angleTo` / `focusOn`. Every verb centres the named data-obj bounding box
+* and maximizes it inside a padded frame. The optional framing words are
+* only `'tight'` | `'normal'` | `'loose'`; they change breathing room, never
+* select or cap magnification. `film.do` advances to settle,
+* `film.together` shares a start, and
+* `film.at(handle.impact)` attaches a consequence to its cause. Any existing
+* kit call or bespoke GSAP gesture can be lifted with `film.plan()`. Primary
+* actions sequence from SETTLE; `film.cut()` uses the stricter END horizon, so
+* a scene can never hide an unfinished stagger or exit. Only
+* `film.coveredCut(handle, marker, reason, ...)` may cross that horizon, and it
+* makes the carrying motion explicit.
+*
+* The raw camera below (`framing` / `full` / `crop` / `set` / `move`) is the
+* ESCAPE HATCH, not the default: measured or skeleton work that needs an exact
+* pose at an exact time, and anything the kit has no vocabulary for. Reach for
+* it deliberately; a film that reaches for it by habit is composing shot by
+* shot with no subject, no containment and no continuity.
+*/
 export type DirectionContext = {
   gsap: typeof gsap
   tl: gsap.core.Timeline // the master timeline (created paused)
@@ -1443,6 +1758,11 @@ export type DirectionContext = {
   config: StageConfig
   q: <T extends HTMLElement>(selector: string) => T
   qa: (selector: string) => HTMLElement[]
+/** The RAW camera: an exact pose at an exact time. Prefer World Camera's
+* named verbs for shots (see the note on `DirectionContext` above) — they
+* maximize and centre the named subject with deterministic padding, which
+* none of the calls here do for you. Use these for measured/skeleton work,
+* and inside kits. */
   camera: {
     framing: (target: FramingTarget, opts?: FramingOpts) => Framing
     focus: (
@@ -1451,13 +1771,18 @@ export type DirectionContext = {
       position?: gsap.Position
     ) => Framing
     full: () => Framing
-    /** CROP framing: the reference resting shot — the target deliberately
-     * OVERFLOWS the frame (`fill` × cover, default 1.4) and one side hugs a
-     * frame edge (`anchor`: 'left' | 'right' | 'top' | 'bottom' | corners |
-     * {x,y} fraction), the rest bleeding off. Returns a Framing: compose
-     * with camera.set for the CUT-TO-CROP edit (wide→detail is a cut) or
-     * camera.move for a motivated push. A full-frame centered app is an
-     * establishing shot, used once — proof shots default to crop. */
+/** CROP framing, the raw-camera close shot: the target deliberately
+* OVERFLOWS the frame (`fill` × cover, default 1.4) and one side hugs a
+* frame edge (`anchor`: 'left' | 'right' | 'top' | 'bottom' | corners |
+* {x,y} fraction), the rest bleeding off. Returns a Framing you compose
+* with camera.set (the cut) or camera.move (the motivated push).
+*
+* IN A WORLD-KIT FILM YOU DO NOT CALL THIS. The declared equivalents are
+* `fit: 'closeup'` (cropping IS the shot — it goes past the edge-safety
+* wall on a subject that declares `data-detail="fine"`) and `fit: 'wide'`
+* for the whole-product establishing shot, and the kit centres the named
+* subject instead of anchoring it to a frame edge by hand. Use `crop`
+* when you are hand-composing a pose the kit has no vocabulary for. */
     crop: (
       target: FramingTarget,
       opts?: {
@@ -1470,338 +1795,346 @@ export type DirectionContext = {
       }
     ) => Framing
     set: (framing: Framing) => void
-    /** The house dolly. DEFAULTS: `duration: 0.8`, `ease: 'expo.inOut'` —
-     * a long dwell at both ends and a confident glide through the middle.
-     * These defaults ARE the recommended camera physics: do NOT pass ease
-     * or duration here unless the user explicitly asks for a different
-     * camera feel. The one sanctioned exception: an instant reframe behind
-     * a covering element (`duration: 0.01`). A slow linear drift
-     * (`duration: 2–5, ease: 'none'`) is NOT one — sub-pixel motion on the
-     * whole stage re-rasterizes every glyph each frame and renders as
-     * micro-flicker; the motion lab flags it as DRIFT and export blocks.
-     * Hold the camera still instead. Anything between 0.05–0.4s is
-     * neither a move nor a cut — avoid it. `ease-in-out-cubic` is for
-     * ELEMENT travel, never the camera. */
+/** The house dolly. DEFAULTS: `duration: 0.8`, `ease: 'expo.inOut'` —
+* a long dwell at both ends and a confident glide through the middle.
+* These defaults ARE the recommended camera physics: do NOT pass ease
+* or duration here unless the user explicitly asks for a different
+* camera feel. The one sanctioned exception: an instant reframe behind
+* a covering element (`duration: 0.01`). A slow linear drift
+* (`duration: 2–5, ease: 'none'`) is NOT one — sub-pixel motion on the
+* whole stage re-rasterizes every glyph each frame and renders as
+* micro-flicker; the motion lab flags it as DRIFT and export blocks.
+* Hold the camera still instead. Anything between 0.05–0.4s is
+* neither a move nor a cut — avoid it. `ease-in-out-cubic` is for
+* ELEMENT travel, never the camera.
+*
+* A world-kit beat supplies all of this from its declared register, and
+* `camera: { cut: true }` is how a beat asks for the snap instead of the
+* glide — so a film built on the kit never writes a camera duration or
+* ease at all. */
     move: (
       framing: Framing,
       vars?: gsap.TweenVars,
       position?: gsap.Position
     ) => void
   }
-  /** Deterministic, seek-driven typing with a fake caret. The caret follows
-   * real layout (mirror-probed), so it wraps with the text in a textarea.
-   * `head` (opt-in) is a smooth glide marker for camera tracking. */
+/** Deterministic, seek-driven typing with a fake caret. The caret follows
+* real layout (mirror-probed), so it wraps with the text in a textarea.
+* `head` (opt-in) is a smooth glide marker for camera tracking. */
   typeInto: (
     target: string | HTMLTextAreaElement | HTMLInputElement,
     text: string,
     opts?: TypeOpts,
     position?: gsap.Position
   ) => { duration: number; caret: HTMLElement | null; head: HTMLElement | null }
-  /** Rect the finished text will occupy in `target` (for framing the close-up). */
+/** Rect the finished text will occupy in `target` (for framing the close-up). */
   measureTypedLine: (
     target: string | HTMLTextAreaElement | HTMLInputElement,
     text: string
   ) => Rect
-  /** Rect of an element's rendered text content (a block element's box
-   * spans its full column — this measures just the text). */
+/** Rect of an element's rendered text content (a block element's box
+* spans its full column — this measures just the text). */
   textRect: (target: string | Element) => Rect
-  /** gsap SplitText — animate .chars / .words / .lines. */
+/** gsap SplitText — animate .chars / .words / .lines. */
   split: (
     target: string | Element,
     vars?: SplitText.Vars
   ) => SplitText
-  /** Empty tween that extends the timeline (a beat / settle). */
+/** Empty tween that extends the timeline (a beat / settle). */
   hold: (duration: number, position?: gsap.Position) => void
-  /** Timeline-driven MP4/WebM playback: scrubs the element's currentTime,
-   * so scrubbing and export frames are exact (a free-running <video> would
-   * shimmer — never autoplay one). `from` = source offset in seconds;
-   * `duration` defaults to the rest of the source. Returns `{ duration }`.
-   * The element is muted and paused; exports wait for each frame's decode. */
+/** Timeline-driven MP4/WebM playback: scrubs the element's currentTime,
+* so scrubbing and export frames are exact (a free-running <video> would
+* shimmer — never autoplay one). `from` = source offset in seconds;
+* `duration` defaults to the rest of the source. Returns `{ duration }`.
+* The element is muted and paused; exports wait for each frame's decode. */
   video: (
     target: string | HTMLVideoElement,
     opts?: { from?: number; duration?: number; playbackRate?: number },
     position?: gsap.Position
   ) => { duration: number }
-  /** Named text animations (built on SplitText, all deterministic).
-   * `text.reveal(el, effect)` in: rise, fall, blur, wave, flip, pop, slide,
-   * typewriter, scramble, wipe, bounce, elastic, arc, streak. `text.exit(el,
-   * effect)` out: rise, fall, blur, fade, pop, scramble, wipe, scatter,
-   * streak. `text.count(el, { to, from?, duration? })` counts a number up on
-   * the timeline (stat pills). `text.emphasize(el, 'pulse'|'wiggle'|'shake')`
-   * is a settle-back gesture for CTAs/accent words. `text.underline(el)`
-   * draws a sketched stroke under a tight element.
-   *
-   * `transition.out(style)` / `transition.in(style)` cover/reveal the whole
-   * FRAME with a color (overlay outside the camera): styles 'wipe',
-   * 'pixels', 'iris', opts `{ color?, direction?: 'left'|'right'|'up'|
-   * 'down', duration?, cell?, at? }`. `out` with no position appends at the
-   * clip's end — the standard way to end a clip for a cut; `in` at position
-   * 0 starts the clip covered and reveals it.
-   * `transition.through(target, { via?, char?, word?, swap?, land?, color?,
-   * duration?, outDuration? }, position?)` is the GO-THROUGH: dive INTO
-   * something until its color takes over the frame, world-swap under the
-   * cover, pull out into the new world. `via` picks the dive geometry:
-   * 'surface' (default, the element's face), 'glyph' (`{ via: 'glyph',
-   * char: 'o' }` — through the character's enclosed counter, measured from
-   * the real glyph outline on plain text: no wrapper spans, no hand-tuned
-   * margins), 'word' (`{ via: 'word', word: 'world' }` — the word's rect),
-   * 'anchor' (match-cut: the subject persists across the cut — the same
-   * selector's twin in the new world is the landing — while everything
-   * around it changes). Never hand-roll a dive (a magic-scale camera.move +
-   * a hand-timed swap): through() computes the exact cover scale, measures
-   * at the dive's own start time, and guarantees full coverage at the cut.
-   * All return `{ duration }` (full span including
-   * stagger) for sequencing, and accept `(target, effect, opts?, position?)`
-   * with opts `{ by?: 'chars'|'words'|'lines', duration?, stagger?, ease?,
-   * from?: 'start'|'center'|'end'|'edges' }`. */
+/** Named text animations (built on SplitText, all deterministic).
+* `text.reveal(el, effect)` in: rise, fall, blur, wave, flip, pop, slide,
+* typewriter, scramble, wipe, bounce, elastic, arc, streak. `text.exit(el,
+* effect)` out: rise, fall, blur, fade, pop, scramble, wipe, scatter,
+* streak. `text.count(el, { to, from?, duration? })` counts a number up on
+* the timeline (stat pills). `text.emphasize(el, 'pulse'|'wiggle'|'shake')`
+* is a settle-back gesture for CTAs/accent words. `text.underline(el)`
+* draws a sketched stroke under a tight element.
+*
+* `transition.out(style)` / `transition.in(style)` cover/reveal the whole
+* FRAME with a color (overlay outside the camera): styles 'wipe',
+* 'pixels', 'iris', opts `{ color?, direction?: 'left'|'right'|'up'|
+* 'down', duration?, cell?, at? }`. `out` with no position appends at the
+* clip's end — the standard way to end a clip for a cut; `in` at position
+* 0 starts the clip covered and reveals it.
+* `transition.through(target, { via?, char?, word?, swap?, land?, color?,
+* duration?, outDuration? }, position?)` is the GO-THROUGH: dive INTO
+* something until its color takes over the frame, world-swap under the
+* cover, pull out into the new world. `via` picks the dive geometry:
+* 'surface' (default, the element's face), 'glyph' (`{ via: 'glyph',
+* char: 'o' }` — through the character's enclosed counter, measured from
+* the real glyph outline on plain text: no wrapper spans, no hand-tuned
+* margins), 'word' (`{ via: 'word', word: 'world' }` — the word's rect),
+* 'anchor' (match-cut: the subject persists across the cut — the same
+* selector's twin in the new world is the landing — while everything
+* around it changes). Never hand-roll a dive (a magic-scale camera.move +
+* a hand-timed swap): through() computes the exact cover scale, measures
+* at the dive's own start time, and guarantees full coverage at the cut.
+* All return `{ duration }` (full span including
+* stagger) for sequencing, and accept `(target, effect, opts?, position?)`
+* with opts `{ by?: 'chars'|'words'|'lines', duration?, stagger?, ease?,
+* from?: 'start'|'center'|'end'|'edges' }`. */
   text: TextKit
-  /** Named logo/brand-mark animations (all deterministic). Target the
-   * element wrapping the mark — an inline `<svg>`, an `<img>`, or a div
-   * around one. `logo.reveal(el, effect)` in: pop, blur, rise, wipe, iris,
-   * slit, spin, flip, bounce, glitch, draw, build. `draw` (strokes trace the
-   * SVG paths, fills crossfade in — works even on fills-only logos) and
-   * `build` (shapes assemble one by one) need INLINE SVG with path/shape
-   * elements; on an `<img>` or path-less SVG they fall back to `wipe` with a
-   * console warning. `logo.exit(el, effect)` out: pop, blur, fade, wipe,
-   * iris, drop. `logo.emphasize(el, 'pulse'|'breathe'|'wiggle')` is a
-   * settle-back gesture (breathe takes `repeats`, finite). `logo.shine(el)`
-   * sweeps a glint across the mark, masked by the logo's own silhouette.
-   * All return `{ duration }` (full span including stagger) and accept
-   * `(target, effect, opts?, position?)` with opts `{ duration?, ease?,
-   * stagger?, direction?: 'left'|'right'|'up'|'down' }`. */
+/** Named logo/brand-mark animations (all deterministic). Target the
+* element wrapping the mark — an inline `<svg>`, an `<img>`, or a div
+* around one. `logo.reveal(el, effect)` in: pop, blur, rise, wipe, iris,
+* slit, spin, flip, bounce, glitch, draw, build. `draw` (strokes trace the
+* SVG paths, fills crossfade in — works even on fills-only logos) and
+* `build` (shapes assemble one by one) need INLINE SVG with path/shape
+* elements; on an `<img>` or path-less SVG they fall back to `wipe` with a
+* console warning. `logo.exit(el, effect)` out: pop, blur, fade, wipe,
+* iris, drop. `logo.emphasize(el, 'pulse'|'breathe'|'wiggle')` is a
+* settle-back gesture (breathe takes `repeats`, finite). `logo.shine(el)`
+* sweeps a glint across the mark, masked by the logo's own silhouette.
+* All return `{ duration }` (full span including stagger) and accept
+* `(target, effect, opts?, position?)` with opts `{ duration?, ease?,
+* stagger?, direction?: 'left'|'right'|'up'|'down' }`. */
   logo: LogoKit
   transition: TransitionKit
-  /** Real 3D — a Three.js layer under the same paused timeline. Use for
-   * depth After Effects fakes and CSS perspective cannot reach: real
-   * cameras, lights, materials. `const L = three.layer({ camera: {z: 6} })`
-   * gives `{ scene, camera, canvas, drive }` — add meshes and lights to
-   * `L.scene` (import * as THREE from 'three'), animate positions/rotations
-   * with ordinary `tl.to(mesh.position, {...})` tweens, then
-   * `L.drive(duration, (t) => {...}, opts?, position?)` renders the layer
-   * over that span (set uniforms/camera from `t` ALONE — no clocks, no
-   * setAnimationLoop, no accumulation; the frame must be a pure function of
-   * timeline position). The canvas is a normal stage element: tween its
-   * opacity, put fx/mask on it, cut it with tl.set. */
+/** Real 3D — a Three.js layer under the same paused timeline. Use for
+* depth After Effects fakes and CSS perspective cannot reach: real
+* cameras, lights, materials. `const L = three.layer({ camera: {z: 6} })`
+* gives `{ scene, camera, canvas, drive }` — add meshes and lights to
+* `L.scene` (import * as THREE from 'three'), animate positions/rotations
+* with ordinary `tl.to(mesh.position, {...})` tweens, then
+* `L.drive(duration, (t) => {...}, opts?, position?)` renders the layer
+* over that span (set uniforms/camera from `t` ALONE — no clocks, no
+* setAnimationLoop, no accumulation; the frame must be a pure function of
+* timeline position). The canvas is a normal stage element: tween its
+* opacity, put fx/mask on it, cut it with tl.set. */
   three: ThreeKit
-  /** Variable-font axis animation — type whose WEIGHT is the thing that
-   * moves. After Effects cannot do this at all. `axis.animate(el, axis,
-   * effect, opts?, position?)`: axes `wght` (weight), `wdth` (width), `slnt`
-   * (slant), `opsz` (optical size), or any custom axis name; effects `ramp`
-   * (go and hold), `pulse` (one breath), `wave` (travels through the
-   * characters). Opts `{ from?, to?, duration?, ease?, stagger? }`. On a
-   * non-variable font it degrades honestly (wght -> weight staircase, wdth ->
-   * scaleX, slnt -> skewX) with a console warning, never a throw. Geist (the
-   * house family) IS variable — weight 100-900. */
+/** Variable-font axis animation — type whose WEIGHT is the thing that
+* moves. After Effects cannot do this at all. `axis.animate(el, axis,
+* effect, opts?, position?)`: axes `wght` (weight), `wdth` (width), `slnt`
+* (slant), `opsz` (optical size), or any custom axis name; effects `ramp`
+* (go and hold), `pulse` (one breath), `wave` (travels through the
+* characters). Opts `{ from?, to?, duration?, ease?, stagger? }`. On a
+* non-variable font it degrades honestly (wght -> weight staircase, wdth ->
+* scaleX, slnt -> skewX) with a console warning, never a throw. Geist (the
+* house family) IS variable — weight 100-900. */
   axis: AxisKit
-  /** The soundtrack's offline analysis (music/analysis/<track>.json).
-   * `audio.beat(n)` / `audio.downbeats` place cuts on the REAL grid — the
-   * downbeat phase is measured, not assumed to start at 0. `audio.onsets`
-   * are the strongest hits; land impact beats on them. `audio.drive(el, map)`
-   * makes a property breathe with the track. When no analysis exists,
-   * `audio.live` is false and every envelope reads 0 — never throws. */
+/** The soundtrack's offline analysis (music/analysis/<track>.json).
+* `audio.beat(n)` / `audio.downbeats` place cuts on the REAL grid — the
+* downbeat phase is measured, not assumed to start at 0. `audio.onsets`
+* are the strongest hits; land impact beats on them. `audio.drive(el, map)`
+* makes a property breathe with the track. When no analysis exists,
+* `audio.live` is false and every envelope reads 0 — never throws. */
   audio: AudioKit
-  /** Ask the exporter for TRUE temporal motion blur over an interval —
-   * sub-frame supersampling at render time, the thing a real-time tool
-   * cannot do. Put it on fast camera moves and whip cuts; the preview does
-   * not show it (it renders one sample per frame), the MP4 does.
-   * `ctx.blur(from, to)` marks [from, to] seconds. Opts: `shutter` degrees
-   * (0-360, default 180 — wider smears more), `tier` 'light' (4 samples) or
-   * 'full' (8, final renders). Costs render time roughly x samples over the
-   * marked intervals only, so mark moves, not holds. */
+/** Ask the exporter for TRUE temporal motion blur over an interval —
+* sub-frame supersampling at render time, the thing a real-time tool
+* cannot do. Put it on fast camera moves and whip cuts; the preview does
+* not show it (it renders one sample per frame), the MP4 does.
+* `ctx.blur(from, to)` marks [from, to] seconds. Opts: `shutter` degrees
+* (0-360, default 180 — wider smears more), `tier` 'light' (4 samples) or
+* 'full' (8, final renders). Costs render time roughly x samples over the
+* marked intervals only, so mark moves, not holds. */
   blur: (
     from: number,
     to: number,
     opts?: { shutter?: number; tier?: 'light' | 'full' }
   ) => void
-  /** Register async prep (texture decode, analysis fetch) started inside the
-   * direction. buildScene awaits every registered promise before setting
-   * window.__ready, so the exporter never screenshots a half-loaded scene.
-   * For kit authors — a direction rarely needs it directly. */
+/** Register async prep (texture decode, analysis fetch) started inside the
+* direction. buildScene awaits every registered promise before setting
+* window.__ready, so the exporter never screenshots a half-loaded scene.
+* For kit authors — a direction rarely needs it directly. */
   __await: (work: Promise<unknown>) => void
-  /** Visual effects — CSS filters and SVG filter primitives, all
-   * deterministic. Three verbs, all `(target, effect, opts?, position?)`:
-   * `fx.apply` ramps an effect on and leaves it, `fx.clear` ramps it off,
-   * and `fx.spike` does both in ONE gesture (one Tweak row, not two).
-   *
-   * Effects: `blur` (gaussian), `glow` (halo in the element's own colour),
-   * `saturate`, `dim` (brightness), `hue` (rotation), `smear` (DIRECTIONAL
-   * blur along `angle` — CSS blur cannot do this), `chroma` (chromatic
-   * aberration, the glitch look), `displace` (turbulence warp: heat haze,
-   * liquid dissolve), `grain` (film grain), `bloom` (bright-pass glow),
-   * `threshold` (posterize to N levels).
-   *
-   * Opts `{ amount?, detail?, duration?, ease?, angle?, color? }` — `amount`
-   * is the effect's peak, `detail` its secondary constant (turbulence
-   * frequency, bloom radius), `angle` in degrees for smear/chroma.
-   *
-   * The whip-pan cut is `fx.spike(stage, 'blur', {}, 'whip1')` alongside a
-   * fast `camera.move` — do NOT hand-write a pair of
-   * `tl.to(stage, { filter: 'blur(12px)' })` tweens, which produces two
-   * unsynced rows in the Tweak panel. */
+/** Visual effects — CSS filters and SVG filter primitives, all
+* deterministic. Three verbs, all `(target, effect, opts?, position?)`:
+* `fx.apply` ramps an effect on and leaves it, `fx.clear` ramps it off,
+* and `fx.spike` does both in ONE gesture (one Tweak row, not two).
+*
+* Effects: `blur` (gaussian), `glow` (halo in the element's own colour),
+* `saturate`, `dim` (brightness), `hue` (rotation), `smear` (DIRECTIONAL
+* blur along `angle` — CSS blur cannot do this), `chroma` (chromatic
+* aberration, the glitch look), `displace` (turbulence warp: heat haze,
+* liquid dissolve), `grain` (film grain), `bloom` (bright-pass glow),
+* `threshold` (posterize to N levels).
+*
+* Opts `{ amount?, detail?, duration?, ease?, angle?, color? }` — `amount`
+* is the effect's peak, `detail` its secondary constant (turbulence
+* frequency, bloom radius), `angle` in degrees for smear/chroma.
+*
+* The whip-pan cut is `fx.spike(stage, 'blur', {}, 'whip1')` alongside a
+* fast `camera.move` — do NOT hand-write a pair of
+* `tl.to(stage, { filter: 'blur(12px)' })` tweens, which produces two
+* unsynced rows in the Tweak panel. */
   fx: FilterKit
-  /** Interaction actions — the cursor is a STATEFUL ACTOR, not a per-call
-   * sprite. The engine tracks where every cursor is and whether it is on
-   * screen: continuation from the last resting position is the default, and
-   * entry/exit are explicit moments. First action enters from the nearest
-   * frame edge (`enter: 'fade'` materializes near the target instead); the
-   * next action continues from wherever the last one parked; `cursor.exit()`
-   * leaves via the nearest edge. `cursor.click(el)` travels, auto-morphs
-   * arrow→pointer on approach, and squashes cursor AND target (squash derived
-   * from target size). `cursor.drag(payload, to)` carries the payload locked
-   * to the cursor in one tween pair. `then: 'stay'|'exit'|'park'|selector`
-   * says where the cursor goes after an action. `cursor.actor(name, { icon,
-   * color, label })` declares independent named cursors (multi-user scenes —
-   * 'collab' icon carries a Figma-style name chip); two actors animate
-   * concurrently just by overlapping positions. Icons carry REGISTERED
-   * hotspots, so click math cannot drift. Every action defaults to
-   * `ease-in-out-cubic` and takes `duration`. */
+/** Interaction actions — the cursor is a STATEFUL ACTOR, not a per-call
+* sprite. The engine tracks where every cursor is and whether it is on
+* screen: continuation from the last resting position is the default, and
+* entry/exit are explicit moments. First action enters from the nearest
+* frame edge (`enter: 'fade'` materializes near the target instead); the
+* next action continues from wherever the last one parked; `cursor.exit()`
+* leaves via the nearest edge. `cursor.click(el)` travels, auto-morphs
+* arrow→pointer on approach, and squashes cursor AND target (squash derived
+* from target size). `cursor.drag(payload, to)` carries the payload locked
+* to the cursor in one tween pair. `then: 'stay'|'exit'|'park'|selector`
+* says where the cursor goes after an action. `cursor.actor(name, { icon,
+* color, label })` declares independent named cursors (multi-user scenes —
+* 'collab' icon carries a Figma-style name chip); two actors animate
+* concurrently just by overlapping positions. Icons carry REGISTERED
+* hotspots, so click math cannot drift. Every action defaults to
+* `ease-in-out-cubic` and takes `duration`. */
   cursor: CursorKit
-  /** Squash without a cursor — keyboard sends, programmatic actions. Amount
-   * defaults from the element's size (big surfaces squash less). */
+/** Squash without a cursor — keyboard sends, programmatic actions. Amount
+* defaults from the element's size (big surfaces squash less). */
   press: ActionsKit['press']
-  /** Animated scroll of a container until a target is in view (`duration: 0`
-   * sets it instantly for initial state). */
+/** Animated scroll of a container until a target is in view (`duration: 0`
+* sets it instantly for initial state). */
   scroll: ActionsKit['scroll']
-  /** Declarative hard UI state change on the timeline, seek-reversible:
-   * `ui.set(el, { text?, value?, src?, attrs?, classes?, flash? })`. Instant
-   * by design — a cut is hard; `flash` adds the one animated accent. */
+/** Declarative hard UI state change on the timeline, seek-reversible:
+* `ui.set(el, { text?, value?, src?, attrs?, classes?, flash? })`. Instant
+* by design — a cut is hard; `flash` adds the one animated accent. */
   ui: ActionsKit['ui']
-  /** Annotation primitives for pre-existing components — the "look here"
-   * vocabulary. `highlight.ring(el)` draws a rounded ring around the element
-   * (follows its corner radius); `circle` is the hand-drawn red-pen loop with
-   * overshoot; `marker` is a highlighter swipe behind the glyphs (multiply
-   * blend, sized from line height); `underline(el, 'sketch'|'straight'|
-   * 'marker')`; `glow` is one soft halo pulse; `spotlight(el)` dims
-   * everything EXCEPT the target behind a feathered cutout — the strongest
-   * "look here" available. All geometry derives from the target; every
-   * highlight takes `persist: 'hold' | seconds` and `release: 'fade' |
-   * 'undraw'`, so nothing loiters. Pairs with the cursor kit: cursor.click +
-   * highlight.ring is the product-tour grammar. */
+/** Annotation primitives for pre-existing components — the "look here"
+* vocabulary. `highlight.ring(el)` draws a rounded ring around the element
+* (follows its corner radius); `circle` is the hand-drawn red-pen loop with
+* overshoot; `marker` is a highlighter swipe behind the glyphs (multiply
+* blend, sized from line height); `underline(el, 'sketch'|'straight'|
+* 'marker')`; `glow` is one soft halo pulse; `spotlight(el)` dims
+* everything EXCEPT the target behind a feathered cutout — the strongest
+* "look here" available. All geometry derives from the target; every
+* highlight takes `persist: 'hold' | seconds` and `release: 'fade' |
+* 'undraw'`, so nothing loiters. Pairs with the cursor kit: cursor.click +
+* highlight.ring is the product-tour grammar. */
   highlight: HighlightKit
-  /** Scene lighting. `light.set({ angle, warmth })` declares THE light once —
-   * sweeps, rims, and cast shadows all derive their direction from it, so
-   * shadows can never disagree. `light.sweep(el)` runs a glint across any
-   * surface; `light.rim(el)` is the premium edge light. */
+/** Scene lighting. `light.set({ angle, warmth })` declares THE light once —
+* sweeps, rims, and cast shadows all derive their direction from it, so
+* shadows can never disagree. `light.sweep(el)` runs a glint across any
+* surface; `light.rim(el)` is the premium edge light. */
   light: LooksKit['light']
-  /** Shading and grade. `shade.cast(el)` — soft shadow offset along the
-   * declared scene light; `shade.vignette()` — one held frame vignette;
-   * `shade.grade('warm-product'|'cool-saas'|'noir')` — named color grade on
-   * the scene content (overlays stay ungraded and legible). */
+/** Shading and grade. `shade.cast(el)` — soft shadow offset along the
+* declared scene light; `shade.vignette()` — one held frame vignette;
+* `shade.grade('warm-product'|'cool-saas'|'noir')` — named color grade on
+* the scene content (overlays stay ungraded and legible). */
   shade: LooksKit['shade']
-  /** Ambient animated backdrop mounted BEHIND the scene root (the scene's
-   * own background must let it show through). Styles: 'gradient-drift',
-   * 'orbs', 'dot-grid'. Presets are tuned to stay alive but sub-salient
-   * (~0.5–2% pixel change per interval); `energy` scales within the budget.
-   * The returned handle's `calm()`/`lift()` duck the backdrop under dense
-   * foreground beats — audio ducking for pixels. */
+/** Ambient animated backdrop mounted BEHIND the scene root (the scene's
+* own background must let it show through). Styles: 'gradient-drift',
+* 'orbs', 'dot-grid'. Presets are tuned to stay alive but sub-salient
+* (~0.5–2% pixel change per interval); `energy` scales within the budget.
+* The returned handle's `calm()`/`lift()` duck the backdrop under dense
+* foreground beats — audio ducking for pixels. */
   backdrop: LooksKit['backdrop']
-  /** The angle-zoom product shot: the camera pushes toward one corner of the
-   * target (`anchor: 'bottom-right'` = the submit-button corner) WHILE the
-   * panel tilts a few degrees in perspective, a sheen sweeps the surface as
-   * the angle changes, and the shadow deepens. Full round trip by default
-   * (in → hold → settle); `settle: false` stays in the pose. Perspective is
-   * applied to the target only, never the stage. */
+/** The angle-zoom product shot: the camera pushes toward one corner of the
+* target (`anchor: 'bottom-right'` = the submit-button corner) WHILE the
+* panel tilts a few degrees in perspective, a sheen sweeps the surface as
+* the angle changes, and the shadow deepens. Full round trip by default
+* (in → hold → settle); `settle: false` stays in the pose. Perspective is
+* applied to the target only, never the stage. */
   hero: LooksKit['hero']
-  /** Standalone perspective pose for an element: `tilt(el, { pitch, yaw })`,
-   * tilt back to 0 to flatten. */
+/** Standalone perspective pose for an element: `tilt(el, { pitch, yaw })`,
+* tilt back to 0 to flatten. */
   tilt: LooksKit['tilt']
-  /** Camera FOLLOWS a moving element — per-frame re-centering at a locked
-   * occupancy, seek-deterministic (the catch-up is an eased blend from a
-   * declared start pose, not stateful smoothing). AUTHOR IT AFTER the motion
-   * it follows. `track(el, { duration, height, release: 'full'|'hold' })`. */
+/** Camera FOLLOWS a moving element — per-frame re-centering at a locked
+* occupancy, seek-deterministic (the catch-up is an eased blend from a
+* declared start pose, not stateful smoothing). AUTHOR IT AFTER the motion
+* it follows. `track(el, { duration, height, release: 'full'|'hold' })`. */
   track: LooksKit['track']
-  /** A sentence as a stateful object. `sentence(el)` takes over the element's
-   * text (word spans) and returns a handle: `.append(words)` — words land
-   * into the held line; `.swap(slot, [...])` — one word cycles in place;
-   * `.stress(word)` — the one-accent-color semantic emphasis; `.morphWord`
-   * ("it!" → "it?"); `.chip(word, media)` — a word slot holds a media chip.
-   * New words are mounted hidden at build (layout stays stable); `recenter`
-   * eases the container instead of live reflow. */
+/** A sentence as a stateful object. `sentence(el)` takes over the element's
+* text (word spans) and returns a handle: `.append(words)` — words land
+* into the held line; `.swap(slot, [...])` — one word cycles in place;
+* `.stress(word)` — the one-accent-color semantic emphasis; `.morphWord`
+* ("it!" → "it?"); `.chip(word, media)` — a word slot holds a media chip.
+* New words are mounted hidden at build (layout stays stable); `recenter`
+* eases the container instead of live reflow. */
   sentence: SentenceKit['sentence']
-  /** Universal shape morph: any element becomes any other element, a rect, or
-   * `'frame'`. Both real elements ride ONE interpolated box (position, size,
-   * corner radius, arc lift) while the source's chrome is driven onto the
-   * target's — at `handoff` the two are the same picture, so the surfaces
-   * HARD-CUT and never crossfade. Matched sub-components (`data-morph="name"`
-   * on both sides) travel; unmatched content displaces along the travel
-   * vector; children are counter-scaled so nothing stretches.
-   *
-   * Author the TARGET hidden (`autoAlpha: 0`); the morph reveals it at
-   * arrival. Every visual state is a pure function of eased progress, so it
-   * is export-worker safe. For MANY-to-many structure — recursing into
-   * sub-components, N→1 gathers, 1→N splits — install `kit/morphtree`. */
+/** Universal shape morph: any element becomes any other element, a rect, or
+* `'frame'`. Both real elements ride ONE interpolated box (position, size,
+* corner radius, arc lift) while the source's chrome is driven onto the
+* target's — at `handoff` the two are the same picture, so the surfaces
+* HARD-CUT and never crossfade. Matched sub-components (`data-morph="name"`
+* on both sides) travel; unmatched content displaces along the travel
+* vector; children are counter-scaled so nothing stretches.
+*
+* Author the TARGET hidden (`autoAlpha: 0`); the morph reveals it at
+* arrival. Every visual state is a pure function of eased progress, so it
+* is export-worker safe. For recursive structure, N→1 gathers and 1→N splits use `morphTree()`. */
   morph: MorphKit['morph']
-  /** The chip⇄full-bleed round trip: grows the element to cover the frame,
-   * holds, returns home (`back: false` to stay). Scale IS the transition —
-   * the object persists (Apple News+ grammar). */
+/** Continuous vector material + recursive DOM continuity, on the master timeline. */
+  morphSurface: (from:string|Element,to:string|Element,opts:MorphSurfaceOpts,position?:gsap.Position)=>MorphSurfaceResult
+/** Recursive correspondence, clustering and seek-safe semantic handoff. */
+  morphTree: (from: string | Element, to: string | Element | HTMLElement[], opts?: MorphTreeOpts, position?: gsap.Position) => MorphTreeResult
+/** The chip⇄full-bleed round trip: grows the element to cover the frame,
+* holds, returns home (`back: false` to stay). Scale IS the transition —
+* the object persists (Apple News+ grammar). */
   expand: MorphKit['expand']
-  /** Elements arrive from BEHIND THE CAMERA onto the layout: each starts
-   * oversized and offset radially (the whole UI plane blown up past the
-   * lens), soft and translucent, then flies into its exact layout slot,
-   * staggered. `dropIn('[data-panel] > *', { from: 3.2, stagger: 0.1 })`.
-   * The container should already be visible; its CHILDREN drop in. */
+/** Elements arrive from BEHIND THE CAMERA onto the layout: each starts
+* oversized and offset radially (the whole UI plane blown up past the
+* lens), soft and translucent, then flies into its exact layout slot,
+* staggered. `dropIn('[data-panel] > *', { from: 3.2, stagger: 0.1 })`.
+* The container should already be visible; its CHILDREN drop in. */
   dropIn: EnsembleKit['dropIn']
-  /** Elements fly in from scattered planar directions ('edges' | 'center' |
-   * 'above') and settle into their exact layout slots — the tile-wall /
-   * place-on-canvas grammar. Ends at exact identity. */
+/** Elements fly in from scattered planar directions ('edges' | 'center' |
+* 'above') and settle into their exact layout slots — the tile-wall /
+* place-on-canvas grammar. Ends at exact identity. */
   assemble: EnsembleKit['assemble']
-  /** Inverse of assemble: elements explode radially out of their layout and
-   * fade. Layout is left clean (hidden, transforms reset). */
+/** Inverse of assemble: elements explode radially out of their layout and
+* fade. Layout is left clean (hidden, transforms reset). */
   scatter: EnsembleKit['scatter']
-  /** SHOWPIECE — elements fly ballistically through the frame: tossed 'up'
-   * and falling back out, raining 'down', or 'burst'. Items EXIT. Use on a
-   * story payoff (something launched/generated/released), at most 1–2
-   * showpieces per film — on an ambient beat this is noise. */
+/** SHOWPIECE — elements fly ballistically through the frame: tossed 'up'
+* and falling back out, raining 'down', or 'burst'. Items EXIT. Use on a
+* story payoff (something launched/generated/released), at most 1–2
+* showpieces per film — on an ambient beat this is noise. */
   fountain: EnsembleKit['fountain']
-  /** SHOWPIECE — generated celebration burst (no authored elements):
-   * particles with deterministic ballistics, spin, flutter, fade.
-   * `confetti({ at: '[data-submit]' })`. ONE per film, ONLY on a genuine
-   * payoff beat (shipped / delivered / won). */
+/** SHOWPIECE — generated celebration burst (no authored elements):
+* particles with deterministic ballistics, spin, flutter, fade.
+* `confetti({ at: '[data-submit]' })`. ONE per film, ONLY on a genuine
+* payoff beat (shipped / delivered / won). */
   confetti: EnsembleKit['confetti']
-  /** Gallery belt: the container's row of items scrolls continuously through
-   * a clipped viewport (children duplicated once; the wrap is seamless).
-   * A showcase beat — logos, covers, results — never ambient filler. */
+/** Gallery belt: the container's row of items scrolls continuously through
+* a clipped viewport (children duplicated once; the wrap is seamless).
+* A showcase beat — logos, covers, results — never ambient filler. */
   river: EnsembleKit['river']
-  /** Bento reflow: tiles in one grid continuously trade space — spans change
-   * and every tile FLIPs to its measured new slot, the grid staying full
-   * while cells resize around each other. Ends on the authored layout. */
+/** Bento reflow: tiles in one grid continuously trade space — spans change
+* and every tile FLIPs to its measured new slot, the grid staying full
+* while cells resize around each other. Ends on the authored layout. */
   bento: EnsembleKit['bento']
-  /** Choreographed waiting — the beat AI products actually live in.
-   * `stream.answer(el, text)` arrives word by word (machine writing, no
-   * caret); `stream.skeleton(el)` shimmers placeholders then resolves into
-   * the real content; `stream.status(el, ['Analyzing', 'Searching 3 sources'])`
-   * names the work. All seek-deterministic. */
+/** Choreographed waiting — the beat AI products actually live in.
+* `stream.answer(el, text)` arrives word by word (machine writing, no
+* caret); `stream.skeleton(el)` shimmers placeholders then resolves into
+* the real content; `stream.status(el, ['Analyzing', 'Searching 3 sources'])`
+* names the work. All seek-deterministic. */
   stream: StreamKit
-  /** The impact move. `slam(el)` lands type/cards hard from a perspective
-   * turn; `slam(el, { direction: 'away' })` tips them back out of frame.
-   * DISTORTION BELONGS TO MOTION: 'in' ends at exact identity, 'away' ends
-   * invisible — an element must never come to rest sheared. Pair with
-   * `blur()` across the fast window so the speed reads as smear, not a pop. */
+/** The impact move. `slam(el)` lands type/cards hard from a perspective
+* turn; `slam(el, { direction: 'away' })` tips them back out of frame.
+* DISTORTION BELONGS TO MOTION: 'in' ends at exact identity, 'away' ends
+* invisible — an element must never come to rest sheared. Pair with
+* `blur()` across the fast window so the speed reads as smear, not a pop. */
   slam: ImpactKit['slam']
-  /** Masks, mattes, and blend composition — the things `clip-path` cannot do.
-   *
-   * `mask.reveal(el, shape, opts?, position?)` and `mask.hide(...)` animate
-   * any element through a moving mask. Shapes: `wipe` (hard directional
-   * edge), `feather` (SOFT directional edge — clip-path cannot do this),
-   * `iris` (hard circle), `radial` (soft circle), `slit` (letterbox opening),
-   * `barn` (panels part from centre), `blinds` (N bands), `shape` (your own
-   * clip-path via `opts.shape`). Opts `{ direction?: 'left'|'right'|'up'|
-   * 'down', softness?: 0-1, bands?, at?: {x,y}, duration?, ease? }`.
-   * Prefer `feather` over `wipe` for anything soft or premium — a hard edge
-   * on a full-frame reveal reads as cheap.
-   *
-   * `mask.matte(target, source, opts?, position?)` makes `source`'s
-   * silhouette the target's visibility — v1 snapshots the source ONCE, so
-   * animating the source will not move the matte; use `{ sweep: true }` to
-   * travel it across the target instead.
-   *
-   * `mask.fill(el, { gradient? | image?, drift? })` fills an element's GLYPHS
-   * with a live layer and drifts it (background-clip: text).
-   *
-   * `mask.blend(el, mode, opts?, position?)` composites a layer against its
-   * beat. Modes: screen, multiply, overlay, difference, exclusion,
-   * color-dodge, soft-light, luminosity, plus-lighter, normal. `screen` for
-   * light on dark, `multiply` for ink on cream, `luminosity` for duotone. */
+/** Masks, mattes, and blend composition — the things `clip-path` cannot do.
+*
+* `mask.reveal(el, shape, opts?, position?)` and `mask.hide(...)` animate
+* any element through a moving mask. Shapes: `wipe` (hard directional
+* edge), `feather` (SOFT directional edge — clip-path cannot do this),
+* `iris` (hard circle), `radial` (soft circle), `slit` (letterbox opening),
+* `barn` (panels part from centre), `blinds` (N bands), `shape` (your own
+* clip-path via `opts.shape`). Opts `{ direction?: 'left'|'right'|'up'|
+* 'down', softness?: 0-1, bands?, at?: {x,y}, duration?, ease? }`.
+* Prefer `feather` over `wipe` for anything soft or premium — a hard edge
+* on a full-frame reveal reads as cheap.
+*
+* `mask.matte(target, source, opts?, position?)` makes `source`'s
+* silhouette the target's visibility — v1 snapshots the source ONCE, so
+* animating the source will not move the matte; use `{ sweep: true }` to
+* travel it across the target instead.
+*
+* `mask.fill(el, { gradient? | image?, drift? })` fills an element's GLYPHS
+* with a live layer and drifts it (background-clip: text).
+*
+* `mask.blend(el, mode, opts?, position?)` composites a layer against its
+* beat. Modes: screen, multiply, overlay, difference, exclusion,
+* color-dodge, soft-light, luminosity, plus-lighter, normal. `screen` for
+* light on dark, `multiply` for ink on cream, `luminosity` for duotone. */
   mask: MaskKit
 }