@impractical-ai/motion 0.1.0

package/assets/engine.d.ts

@@ -0,0 +1,914 @@
+// Impractical Motion — public engine surface v1.0.
+//
+// A scene is two files:
+//   App.tsx       the stage markup (plain React + CSS; this is your product UI)
+//   direction.ts  the choreography — `export default (ctx: DirectionContext) => {...}`
+//
+// 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 —
+// they desynchronise the export. Use ctx.video() for footage.
+//
+// Generated by scripts/build-engine-dts.mjs — do not edit by hand.
+
+import type gsap from 'gsap'
+import type { SplitText } from 'gsap/SplitText'
+
+// ─── Transitions — cover and reveal the whole frame ──────────────────────
+
+export type TransitionStyle =
+  | 'wipe' // a solid slab sweeps across the frame
+  | 'pixels' // a grid of squares snaps in, sweeping directionally
+  | 'iris'
+
+export type TransitionDirection = 'left' | 'right' | 'up' | 'down'
+
+export type TransitionOpts = {
+  color?: string
+  /** 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. */
+  cell?: number
+  /** 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. */
+  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. */
+  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`. */
+  in: (
+    style: TransitionStyle,
+    opts?: TransitionOpts,
+    position?: gsap.Position
+  ) => TransitionResult
+}
+
+// ─── Text — named, deterministic text animations ─────────────────────────
+
+export type TextUnit = 'chars' | 'words' | 'lines'
+
+export type RevealEffect =
+  | 'rise' // masked characters rise in from below (the house classic)
+  | 'fall' // masked characters drop in from above
+  | 'blur' // words de-blur and fade in
+  | 'wave' // characters bob up with an overshoot, heavily overlapped
+  | 'flip' // characters flip up from flat (3D rotationX)
+  | 'pop' // characters scale in with a springy overshoot
+  | 'slide' // words slide in from the left
+  | 'typewriter' // characters appear one by one, no easing
+  | 'scramble' // characters cycle through glyphs, then lock in
+  | 'wipe' // the whole element is revealed by a moving clip edge
+  | 'bounce' // characters drop onto the baseline and bounce (CustomBounce)
+  | 'elastic' // characters stretch up from the baseline (elastic ease)
+  | 'arc' // characters swing in along a curved path (MotionPath)
+  | 'streak'
+
+export type ExitEffect =
+  | 'rise' // masked characters continue up and out
+  | 'fall' // masked characters drop down and out
+  | 'blur' // words blur away
+  | 'fade' // the whole element fades out
+  | 'pop' // characters shrink away
+  | 'scramble' // characters unlock into glyph noise, then vanish
+  | 'wipe' // a clip edge eats the element left to right
+  | 'scatter' // characters burst apart and fall under gravity (Physics2D)
+  | 'streak'
+
+export type EmphasisEffect =
+  | 'pulse' // scale up and settle back (a breath)
+  | 'wiggle' // playful rotation wiggle that settles (CustomWiggle)
+  | 'shake'
+
+export type StaggerFrom = 'start' | 'center' | 'end' | 'edges'
+
+export type TextEffectOpts = {
+  by?: TextUnit // which unit to animate (effects pick a sensible default)
+  duration?: number // per-unit duration, seconds
+  stagger?: number // seconds between units
+  ease?: string
+  from?: StaggerFrom // where the stagger radiates from (default 'start')
+}
+
+export type EmphasisOpts = {
+  duration?: number // full span of the gesture
+  strength?: number // pulse: target scale; wiggle: degrees; shake: px
+  ease?: string
+}
+
+export type UnderlineOpts = {
+  color?: string
+  thickness?: number // stroke width, px
+  duration?: number
+  ease?: string
+  offsetY?: number // gap between text baseline box and the line, px
+}
+
+export type TextResult = {
+  duration: number // full span including stagger — for sequencing
+  targets: Element[]
+}
+
+export type CountOpts = {
+  to: number
+  from?: number // defaults to whatever number the element already shows
+  duration?: number
+  ease?: string
+}
+
+export type TextKit = {
+  /** 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). */
+  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. */
+  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. */
+  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. */
+  underline: (
+    target: string | Element,
+    opts?: UnderlineOpts,
+    position?: gsap.Position
+  ) => TextResult
+}
+
+// ─── Logo — named, deterministic brand-mark animations ───────────────────
+
+export type LogoRevealEffect =
+  | 'pop' // scales in with a springy overshoot
+  | 'blur' // de-blurs and settles from slightly oversized
+  | 'rise' // rises in from below behind an overflow mask
+  | 'wipe' // a clip edge sweeps the logo in (direction opt)
+  | 'iris' // a circular clip opens from the center
+  | 'slit' // a letterbox slit opens from a horizontal line
+  | 'spin' // rotates in while scaling up
+  | 'flip' // 3D flip up from edge-on
+  | 'bounce' // drops in and bounces on the baseline (CustomBounce)
+  | 'glitch' // seeded slice-band glitch that settles clean
+  | 'draw' // SVG only: strokes trace the paths, fills crossfade in
+  | 'build'
+
+export type LogoExitEffect =
+  | 'pop' // shrinks away
+  | 'blur' // blurs out
+  | 'fade' // plain fade
+  | 'wipe' // a clip edge eats the logo (direction opt)
+  | 'iris' // the circular clip closes
+  | 'drop'
+
+export type LogoEmphasisEffect =
+  | 'pulse' // scale up and settle back (one breath)
+  | 'breathe' // slow repeated scale loop (finite — set repeats)
+  | 'wiggle'
+
+export type LogoDirection = 'left' | 'right' | 'up' | 'down'
+
+export type LogoEffectOpts = {
+  duration?: number
+  ease?: string
+  stagger?: number // draw/build: seconds between shapes
+  direction?: LogoDirection // wipe: which way the edge travels
+}
+
+export type LogoEmphasisOpts = {
+  duration?: number
+  strength?: number // pulse/breathe: target scale; wiggle: degrees
+  ease?: string
+  repeats?: number // breathe: number of breaths (default 3)
+}
+
+export type ShineOpts = {
+  color?: string // band color (default white)
+  width?: number // band width as a fraction of the logo box (default 0.18)
+  angle?: number // gradient angle, degrees (default 105)
+  duration?: number
+  ease?: string
+}
+
+export type LogoResult = {
+  duration: number // full span including stagger — for sequencing
+  targets: Element[]
+}
+
+export type LogoKit = {
+  /** 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). */
+  exit: (
+    target: string | Element,
+    effect: LogoExitEffect,
+    opts?: LogoEffectOpts,
+    position?: gsap.Position
+  ) => LogoResult
+  /** 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). */
+  shine: (
+    target: string | Element,
+    opts?: ShineOpts,
+    position?: gsap.Position
+  ) => LogoResult
+}
+
+// ─── Effects — CSS filters and SVG filter primitives ─────────────────────
+
+export type FilterTier = 'css' | 'svg'
+
+export type FilterEffect =
+  // ── css tier ────────────────────────────────────────────────────────────
+  /** Gaussian blur. Replaces the hand-rolled whip-pan "stage-blur spike". */
+  | 'blur'
+  /** A halo in the element's own colour, from stacked drop-shadows. */
+  | 'glow'
+  /** Colour lifts (>1) or drains (<1). */
+  | 'saturate'
+  /** Brightness pull-down — for backgrounding a layer under an overlay. */
+  | 'dim'
+  /** Hue rotation drift. */
+  | 'hue'
+  // ── svg tier ────────────────────────────────────────────────────────────
+  /** 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. */
+  | 'chroma'
+  /** Turbulence-driven displacement: heat haze, liquid warp, dissolve. */
+  | 'displace'
+  /** Fractal-noise film grain composited over the source. */
+  | 'grain'
+  /** Bright-pass blur screened back over the source — bloom. */
+  | 'bloom'
+  /** Posterize to N discrete levels per channel. */
+  | 'threshold'
+
+export type FilterOpts = {
+  /** Peak value of the effect's primary parameter. */
+  amount?: number
+  /** Secondary constant: turbulence frequency, bloom radius, grain scale. */
+  detail?: number
+  duration?: number
+  ease?: string
+  /** Direction in degrees for `smear` and `chroma`. 0 = horizontal. */
+  angle?: number
+  /** 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`. */
+  duration: number
+  targets: Element[]
+}
+
+export type FilterKit = {
+  /** 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. */
+  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. */
+  spike: (
+    target: string | Element | Element[],
+    effect: FilterEffect,
+    opts?: FilterOpts,
+    position?: gsap.Position
+  ) => FilterResult
+}
+
+// ─── Masks — soft edges, mattes, fills, and blend modes ──────────────────
+
+export type MaskShape =
+  /** Hard directional edge (clip-path inset) — same geometry as logo.wipe. */
+  | 'wipe'
+  /** SOFT directional edge. The capability clip-path structurally lacks. */
+  | 'feather'
+  /** Hard circle growing from a point. */
+  | 'iris'
+  /** Soft circle with a feathered falloff. */
+  | 'radial'
+  /** Letterbox opening from a horizontal centre line. */
+  | 'slit'
+  /** Two panels parting from the centre outward. */
+  | 'barn'
+  /** N bands opening together. */
+  | 'blinds'
+  /** Caller-supplied clip-path or mask-image value — the escape hatch. */
+  | 'shape'
+
+export type BlendMode =
+  | 'screen'
+  | 'multiply'
+  | 'overlay'
+  | 'difference'
+  | 'exclusion'
+  | 'color-dodge'
+  | 'soft-light'
+  | 'luminosity'
+  | 'plus-lighter'
+  | 'normal'
+
+export type MaskDirection = 'left' | 'right' | 'up' | 'down'
+
+export type MatteKind = 'luma' | 'alpha'
+
+export type MaskOpts = {
+  direction?: MaskDirection
+  /** Feather width as a fraction of the element's box. 0 = hard edge. */
+  softness?: number
+  /** Band count for `blinds`. */
+  bands?: number
+  /** Centre for `iris` / `radial`, as fractions of the box. */
+  at?: { x?: number; y?: number }
+  /** For `shape`: any clip-path value. */
+  shape?: string
+  duration?: number
+  ease?: string
+}
+
+export type MatteOpts = {
+  /** 'luma' uses the source's brightness, 'alpha' its transparency. */
+  kind?: MatteKind
+  /** 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)'. */
+  gradient?: string
+  /** Or an image URL. */
+  image?: string
+  /** 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. */
+  from?: number
+  duration?: number
+  ease?: string
+}
+
+export type MaskResult = {
+  duration: number
+  targets: Element[]
+}
+
+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: (
+    target: string | Element | Element[],
+    shape: MaskShape,
+    opts?: MaskOpts,
+    position?: gsap.Position
+  ) => MaskResult
+  /** 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. */
+  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: (
+    target: string | Element,
+    opts?: FillOpts,
+    position?: gsap.Position
+  ) => MaskResult
+  /** Composite a layer against its beat with a blend mode. */
+  blend: (
+    target: string | Element | Element[],
+    mode: BlendMode,
+    opts?: BlendOpts,
+    position?: gsap.Position
+  ) => MaskResult
+}
+
+// ─── Type axes — variable-font weight/width/slant animation ──────────────
+
+export type AxisName = 'wght' | 'wdth' | 'slnt' | 'opsz' | (string & {})
+
+export type AxisEffect =
+  /** Ramp the axis from its current value to `to` and hold. */
+  | 'ramp'
+  /** Ramp up and settle back — one breath. */
+  | 'pulse'
+  /** A per-character wave that travels through the line once. */
+  | 'wave'
+
+export type AxisOpts = {
+  /** Target axis value. Clamped to the face's declared range. */
+  to?: number
+  from?: number
+  duration?: number
+  ease?: string
+  /** wave: seconds between adjacent characters. */
+  stagger?: number
+}
+
+export type AxisResult = { duration: number; targets: Element[] }
+
+export type AxisKit = {
+  animate: (
+    target: string | Element | Element[],
+    axis: AxisName,
+    effect: AxisEffect,
+    opts?: AxisOpts,
+    position?: gsap.Position
+  ) => AxisResult
+}
+
+// ─── 3D — a Three.js layer under the deterministic timeline ──────────────
+
+export type ThreeLayerOpts = {
+  /** Camera vertical FOV in degrees. */
+  fov?: number
+  /** 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). */
+  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. */
+  depth?: 'back' | 'front'
+}
+
+export type ThreeLayer = {
+  /** The scene graph — add meshes, lights, groups. */
+  scene: THREE.Scene
+  camera: THREE.PerspectiveCamera
+  /** 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: (
+    duration: number,
+    update?: (t: number) => void,
+    opts?: { ease?: string },
+    position?: gsap.Position
+  ) => { duration: number }
+}
+
+export type ThreeKit = {
+  /** Create a 3D layer sized to the stage. Everything async about it (first
+   * compile, first paint) completes before window.__ready. */
+  layer: (opts?: ThreeLayerOpts) => ThreeLayer
+}
+
+// ─── 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. */
+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. */
+  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?: number
+    /** 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. */
+export type TrackAnalysis = {
+  analyzerVersion: number
+  rate: number // envelope grid Hz
+  duration: number // exact decoded track length, seconds
+  bpm: number
+  downbeatPhase: number
+  beats: number[]
+  downbeats: number[]
+  onsets: number[]
+  sections: Array<{ start: number; end: number; energy: number }>
+  energy: number[]
+  bands: { low: number[]; mid: number[]; high: number[] }
+}
+
+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. */
+  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. */
+  energy: (t: number) => number
+  band: (t: number, band: 'low' | 'mid' | 'high') => number
+  /** 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. */
+  drive: (
+    target: string | Element,
+    map: (energy: number) => Record<string, number | string>,
+    opts?: { band?: 'low' | 'mid' | 'high'; from?: number; duration?: number },
+    position?: gsap.Position
+  ) => { duration: number }
+}
+
+export type Output = {
+  width: number
+  height: number
+  fps: number
+  render?: RenderConfig
+}
+
+export type Rect = { left: number; top: number; width: number; height: number }
+
+export type FramingTarget = string | Element | Rect | FramingTarget[]
+
+export type Framing = { scale: number; x: number; y: number }
+
+export type FramingOpts = {
+  scale?: number // explicit zoom level; skips fitting
+  fitWidth?: number // target occupies this fraction of the frame width
+  fitHeight?: number // target occupies this fraction of the frame height
+  maxScale?: number
+  offsetX?: number // nudge the framed center, in scene px
+  offsetY?: number
+  clamp?: boolean // keep the viewport inside the stage (no black past edges)
+}
+
+export type TypeOpts = {
+  cps?: number // characters per second
+  caret?: boolean
+}
+
+export type TweenOverride = {
+  sig?: string
+  start?: number // timeline position, seconds
+  duration?: number
+  ease?: string
+  stagger?: number
+  vars?: Record<string, number | string> // end values (scale, x, autoAlpha, …)
+}
+
+export type TextStyleOverride = {
+  fontFamily?: string
+  fontSize?: number
+  fontWeight?: number
+  textAlign?: 'left' | 'center' | 'right'
+  color?: string
+  x?: number
+  y?: number
+  hidden?: boolean
+}
+
+export type ObjectPositionOverride = {
+  x?: number
+  y?: number
+  scaleX?: number
+  scaleY?: number
+  rotation?: number
+  hidden?: boolean
+}
+
+export type AddedTextLayer = {
+  text: string
+  x: number
+  y: number
+  width: number
+}
+
+export type SceneOverrides = {
+  tweens?: Record<string, TweenOverride>
+  cameraSets?: Record<string, Partial<Framing>> // camera.set calls, by order
+  text?: Record<string, string> // stable text-fragment id -> replacement copy
+  textStyles?: Record<string, TextStyleOverride>
+  addedText?: Record<string, AddedTextLayer>
+  objects?: Record<string, ObjectPositionOverride> // stable UI wrapper id -> scene-pixel offset
+}
+
+export type TweenKind =
+  | 'camera'
+  | 'element'
+  | 'group'
+  | 'typing'
+  | 'caret'
+  | 'hold'
+  // Kit proxy tweens (see src/stage/kits.ts KitProxy). Without their own
+  // kinds they fall through to 'hold', which labels them "Hold the frame",
+  // HIDES their ease selector (studio/main.tsx:2792) and files them under the
+  // "pause" filter chip — three real defects.
+  | 'filter'
+  | 'mask'
+  | 'axis'
+  | 'three'
+
+export type TweenInfo = {
+  id: number
+  sig: string
+  kind: TweenKind
+  label: string
+  start: number
+  duration: number // per-target duration (excludes stagger span)
+  total: number // full span including stagger
+  ease: string // '' = gsap default
+  stagger?: number
+  vars: Record<string, number | string>
+  overridden: boolean
+}
+
+export type CameraSetInfo = Framing & { id: number; overridden: boolean }
+
+export type SceneInspection = {
+  config: Output
+  duration: number
+  tweens: TweenInfo[]
+  cameraSets: CameraSetInfo[]
+  overrides: SceneOverrides
+}
+
+export type DirectionContext = {
+  gsap: typeof gsap
+  tl: gsap.core.Timeline // the master timeline (created paused)
+  stage: HTMLElement // scene wrapper the camera transforms
+  config: Output
+  q: <T extends HTMLElement>(selector: string) => T
+  qa: (selector: string) => HTMLElement[]
+  camera: {
+    framing: (target: FramingTarget, opts?: FramingOpts) => Framing
+    full: () => Framing
+    set: (framing: Framing) => void
+    move: (
+      framing: Framing,
+      vars?: gsap.TweenVars,
+      position?: gsap.Position
+    ) => void
+  }
+  /** Deterministic, seek-driven typing with a fake caret. */
+  typeInto: (
+    target: string | HTMLTextAreaElement | HTMLInputElement,
+    text: string,
+    opts?: TypeOpts,
+    position?: gsap.Position
+  ) => { duration: number; caret: HTMLElement | null }
+  /** 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). */
+  textRect: (target: string | Element) => Rect
+  /** gsap SplitText — animate .chars / .words / .lines. */
+  split: (
+    target: string | Element,
+    vars?: SplitText.Vars
+  ) => SplitText
+  /** 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. */
+  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. 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' }`. */
+  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. */
+  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. */
+  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. */
+  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. */
+  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. */
+  __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. */
+  fx: FilterKit
+  /** 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
+}
+
+export type Direction = (ctx: DirectionContext) => void | Promise<void>
+
+// ─── Named eases ──────────────────────────────────────────────────────
+
+// ─── The promo easing set ─────────────────────────────────────────────────
+// Named curves for the "product promo" motion language (the ginyboi /
+// Apple-promo feel): elements snap in fast and settle long, cameras glide,
+// exits accelerate. These are the exact cubic-beziers from the house
+// animation guidelines, registered once so directions, blocks, and the
+// Tweak panel can all reference them by name.
+//
+//   promo-out    ease-out-expo   (.19, 1, .22, 1)  — entrances, card pops
+//   promo-soft   ease-out-quint  (.23, 1, .32, 1)  — gentler entrances, settles
+//   promo-inout  in-out-quint    (.86, 0, .07, 1)  — camera pushes, recenters
+//   promo-in     ease-in-quart   (.895,.03,.685,.22) — exits, dives
+//
+// Rule of thumb from the reference promos: entrances ~0.4–0.6s on promo-out
+// (visually settled inside 0.15s), line staggers ~0.2s, holds carry a slow
+// linear scale drift (~4%/s, ease 'none'), pops that need bounce use
+// back.out(1.8–2), and background/color cuts are HARD (no crossfade).
+
+/** Registered ease names usable anywhere GSAP accepts an ease. */
+export type PromoEase = 'promo-out' | 'promo-soft' | 'promo-inout' | 'promo-in' | 'launch-out'