@impractical-ai/motion 0.1.5 → 0.1.7

package/assets/engine.d.ts

@@ -1,4 +1,4 @@
-// Impractical Motion — public engine surface v1.0.
+// 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)
@@ -506,10 +506,113 @@ export type ThreeLayerOpts = {
   depth?: 'back' | 'front'
 }
 
+export type ThreeCameraAngle =
+  | 'front'
+  | 'three-quarter-left'
+  | 'three-quarter-right'
+  | 'high'
+
+export type ThreeCameraPose = {
+  position: { x: number; y: number; z: number }
+  target: { x: number; y: number; z: number }
+  roll?: number
+  near?: number
+  far?: number
+}
+
+export type ThreeFrameOpts = {
+  /** Projected fraction of frame height occupied by the subject. Default 0.7. */
+  height?: number
+  /** `contain` also enforces maxWidth; `height` may crop horizontally. */
+  mode?: 'contain' | 'height'
+  maxWidth?: number
+  angle?: ThreeCameraAngle
+  /** 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. */
+  ease?: string
+}
+
+export type ThreeOrbitOpts = ThreeFrameOpts &
+  ThreeMoveOpts & {
+    /** Horizontal orbit delta in degrees. */
+    azimuth?: number
+    /** Vertical orbit delta in degrees. */
+    elevation?: number
+  }
+
+export type ThreeLightingPreset =
+  | 'ui-flat'
+  | 'product-soft'
+  | 'dramatic-rim'
+  | 'studio-neutral'
+
+export type ThreeLightingOpts = {
+  /** Camera-relative stays flattering through a move; world-locked reveals form. */
+  mode?: 'camera-relative' | 'world-locked'
+  intensity?: number
+  exposure?: number
+  rimColor?: THREE.ColorRepresentation
+}
+
+export type ThreeLightRig = {
+  ambient: THREE.AmbientLight
+  key: THREE.DirectionalLight
+  fill: THREE.DirectionalLight
+  rim: THREE.DirectionalLight
+  update: () => void
+}
+
+export type ThreeCameraRig = {
+  /** 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. */
+  set: (pose: ThreeCameraPose) => void
+  /** 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. */
+  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: (
+    subject: THREE.Object3D,
+    opts?: ThreeOrbitOpts,
+    position?: gsap.Position
+  ) => { duration: number; pose: ThreeCameraPose }
+  /** Current planned pose, including moves not yet reached by the playhead. */
+  pose: () => ThreeCameraPose
+}
+
+export type ThreeLightingRig = {
+  apply: (
+    subject: THREE.Object3D,
+    preset?: ThreeLightingPreset,
+    opts?: ThreeLightingOpts
+  ) => ThreeLightRig
+}
+
 export type ThreeLayer = {
   /** The scene graph — add meshes, lights, groups. */
   scene: THREE.Scene
   camera: THREE.PerspectiveCamera
+  /** Subject-first XYZ camera control: exact projected framing, dolly, and orbit. */
+  rig: ThreeCameraRig
+  /** Deterministic key/fill/rim presets bound to a 3D subject. */
+  lighting: ThreeLightingRig
   /** The canvas element, for tweening opacity/filters like any element. */
   canvas: HTMLCanvasElement
   /** Drive the layer over [position, position+duration]. `update` runs every
@@ -530,6 +633,463 @@ export type ThreeKit = {
   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. */
+export type CursorIconName =
+  | 'arrow'
+  | 'pointer'
+  | 'ibeam'
+  | 'grab'
+  | 'grabbing'
+  | 'crosshair'
+  | 'collab'
+
+export type CursorIcon = CursorIconName | { svg: string; hotspot: { x: number; y: number } }
+
+export type CursorActorOpts = {
+  /** Icon set. Default 'arrow'; named collaborators usually want 'collab'. */
+  icon?: CursorIcon
+  /** Tint for the collab arrow and label chip. */
+  color?: string
+  /** 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. */
+  size?: number
+  /** '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. */
+  morph?: boolean
+}
+
+export type CursorMoveOpts = {
+  /** Travel time in seconds. Default 0.8. */
+  duration?: number
+  /** 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. */
+  anchor?: { x?: number; y?: number }
+  /** 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. */
+  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. */
+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. */
+  press?: number | 'auto'
+  /** 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. */
+  lift?: boolean
+  then?: CursorThen
+}
+
+export type CursorExitOpts = {
+  duration?: number
+  ease?: string
+  /** 'edge' (default) or 'fade'. */
+  via?: 'edge' | 'fade'
+}
+
+export type CursorActor = {
+  /** 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. */
+  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 }`. */
+  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. */
+  exit: (opts?: CursorExitOpts, position?: gsap.Position) => { duration: number }
+  /** 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. */
+  actor: (name: string, opts?: CursorActorOpts) => CursorActor
+}
+
+export type PressOpts = {
+  /** Squash scale; 'auto' (default) derives from element size. */
+  amount?: number | 'auto'
+  /** Each way. Default 0.09. */
+  duration?: number
+  ease?: string
+}
+
+export type ScrollOpts = {
+  duration?: number
+  ease?: string
+  /** 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. */
+  text?: string
+  /** Set an input's value. */
+  value?: string
+  /** Swap an image/video source. */
+  src?: string
+  /** Set attributes verbatim. */
+  attrs?: Record<string, string>
+  /** 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. */
+  flash?: boolean
+}
+
+export type ActionsKit = {
+  cursor: CursorKit
+  /** 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. */
+  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. */
+  ui: {
+    set: (
+      target: string | Element,
+      change: UiChange,
+      position?: gsap.Position
+    ) => { duration: number }
+  }
+}
+
+// ─── Highlight — annotations that derive from their target ───────────────
+
+export type HighlightRelease = 'fade' | 'undraw' | 'hold'
+
+export type HighlightOpts = {
+  /** Stroke/fill color. Each primitive has its own sensible default. */
+  color?: string
+  /** Draw-on time in seconds. */
+  duration?: number
+  /** 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. */
+  persist?: number | 'hold'
+  /** 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. */
+  padding?: number
+  /** 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'. */
+  fit?: 'text' | 'box'
+}
+
+export type SpotlightOpts = {
+  /** 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. */
+  blur?: number
+  /** 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. */
+  padding?: number
+  duration?: number
+  ease?: string
+  persist?: number | 'hold'
+}
+
+export type HighlightKit = {
+  /** 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. */
+  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. */
+  marker: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
+  /** 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. */
+  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. */
+  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). */
+  angle: number
+  /** 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. */
+  set: (state: Partial<LightState>) => void
+  /** 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. */
+  rim: (
+    target: string | Element,
+    opts?: { color?: string; intensity?: number; duration?: number },
+    position?: gsap.Position
+  ) => { duration: number }
+}
+
+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. */
+  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). */
+  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. */
+  grade: (
+    preset: 'warm-product' | 'cool-saas' | 'noir',
+    opts?: { duration?: number },
+    position?: gsap.Position
+  ) => { duration: number }
+}
+
+export type BackdropStyle =
+  | 'gradient-drift'
+  | 'orbs'
+  | 'dot-grid'
+  | 'paper'
+  // Designed grounds mined from web heroes (references/cards/web-hero-grounds.md):
+  | 'aurora' // Stripe — mesh gradient ribbons on a diagonal, drifting slowly
+  | 'threads' // Mintlify — fanned fine line strands sweeping the corners
+  | 'dot-matrix' // AgentMail — shimmering dot field, radial falloff off content
+  | '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. */
+  energy?: number
+  /** 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?: 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?: boolean
+}
+
+export type BackdropHandle = {
+  el: HTMLElement
+  /** Duck the backdrop under a dense foreground beat. */
+  calm: (position?: gsap.Position) => void
+  /** Bring it back up during a hold. */
+  lift: (position?: gsap.Position) => void
+}
+
+export type HeroAnchor =
+  | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center'
+  | { x: number; y: number }
+
+export type HeroOpts = {
+  /** 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. */
+  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. */
+  pitch?: number
+  yaw?: number
+  /** Push-in time. Default 0.9. */
+  duration?: number
+  /** Seconds held at the angle before returning. Default 1.2. */
+  hold?: number
+  /** 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?: boolean
+  /** Shadow deepens as the panel lifts. Default true. */
+  shadow?: boolean
+  ease?: string
+}
+
+export type LooksKit = {
+  light: LightKit
+  shade: ShadeKit
+  /** 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. */
+  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. */
+  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. */
+  track: (
+    target: string | Element,
+    opts?: {
+      /** Tracking window in seconds. Default 2. */
+      duration?: number
+      /** 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. */
+      attach?: number
+      /** 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'. */
+      release?: 'hold' | 'full'
+    },
+    position?: gsap.Position
+  ) => { duration: number }
+}
+
+// ─── Sentence — a sentence as a stateful object ──────────────────────────
+
+export type SentenceHandle = {
+  el: HTMLElement
+  append: (text: string, opts?: { stagger?: number; duration?: number; recenter?: boolean; stress?: boolean }, position?: Position) => { duration: number }
+  swap: (slot: string, alternatives: string[], opts?: { interval?: number; stress?: boolean; align?: 'anchor' | 'recenter' }, position?: Position) => { duration: number }
+  stress: (word: string, opts?: { color?: string; duration?: number }, position?: Position) => { duration: number }
+  morphWord: (from: string, to: string, opts?: { duration?: number }, position?: Position) => { duration: number }
+  chip: (word: string, media: HTMLElement, opts?: { height?: number; radius?: number }, position?: Position) => HTMLElement
+}
+
+// ─── Morph — any element becomes any other element ───────────────────────
+
+export type MorphOpts = {
+  /** 'apple' = expo-out flight (~90% of the change in the first ~15% of the
+   * time, long soft landing). 'spring' = the reference bounce: expo-out
+   * flight, then a LIGHT damped sine rides 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. */
+  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). */
+  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). */
+  ease?: string
+  /** 0..1 — center of the A→B crossfade along the flight. */
+  handoff?: number
+  /** Width of the crossfade as a fraction of the flight (default 0.3 —
+   * tight; each side shows only near its natural shape). */
+  crossfade?: number
+  /** Arc lift in px (0 disables). Default: auto from travel distance. */
+  arc?: number
+  /** Part choreography (default 'stagger'): the target's direct children
+   * arrive individually inside the landing box; the source's children are
+   * absorbed as it leaves. `false` = containers only. */
+  parts?: 'stagger' | 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. */
+  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. */
+  settle?: boolean | { scale?: number; duration?: number; ease?: string }
+  zIndex?: number
+}
+
 // ─── Engine — the direction context you write against ────────────────────
 
 /** Render directives a scene (or a kit, during the direction) hands to the
@@ -598,18 +1158,45 @@ export type AudioKit = {
 }
 
 export type Output = {
+  /** Delivery raster dimensions. They do not change scene layout. */
   width: number
   height: number
   fps: number
   render?: RenderConfig
 }
 
+/** Resolved renderer contract. `width`/`height` are always logical scene
+ * coordinates; only the exporter consumes `delivery` as raster dimensions. */
+export type StageConfig = Output & {
+  composition: { width: number; height: number }
+  delivery: { width: number; height: number }
+}
+
 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 CameraFocusOpts = {
+  /** 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. */
+  mode?: 'contain' | 'height'
+  /** Width cap used by `contain`. Default 0.9. */
+  maxWidth?: number
+  /** 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. */
+  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. */
+  ease?: string
+}
+
 export type FramingOpts = {
   scale?: number // explicit zoom level; skips fitting
   fitWidth?: number // target occupies this fraction of the frame width
@@ -623,6 +1210,13 @@ 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). */
+  head?: boolean | { width?: number; height?: number }
 }
 
 export type TweenOverride = {
@@ -642,6 +1236,9 @@ 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. */
+  width?: number
   hidden?: boolean
 }
 
@@ -652,6 +1249,14 @@ 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. */
+  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. */
+  src?: string
 }
 
 export type AddedTextLayer = {
@@ -668,6 +1273,11 @@ 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. */
+  layerOrder?: Record<string, number>
 }
 
 export type TweenKind =
@@ -698,12 +1308,16 @@ export type TweenInfo = {
   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. */
+  targetObjectId?: string
+  targetTextId?: string
 }
 
 export type CameraSetInfo = Framing & { id: number; overridden: boolean }
 
 export type SceneInspection = {
-  config: Output
+  config: StageConfig
   duration: number
   tweens: TweenInfo[]
   cameraSets: CameraSetInfo[]
@@ -720,26 +1334,60 @@ export type DirectionContext = {
   gsap: typeof gsap
   tl: gsap.core.Timeline // the master timeline (created paused)
   stage: HTMLElement // scene wrapper the camera transforms
-  config: Output
+  config: StageConfig
   q: <T extends HTMLElement>(selector: string) => T
   qa: (selector: string) => HTMLElement[]
   camera: {
     framing: (target: FramingTarget, opts?: FramingOpts) => Framing
+    focus: (
+      target: FramingTarget,
+      opts?: CameraFocusOpts,
+      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: (
+      target: FramingTarget,
+      opts?: {
+        fill?: number
+        anchor?:
+          | 'left' | 'right' | 'top' | 'bottom'
+          | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+          | 'center'
+          | { x: number; y: number }
+      }
+    ) => 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 two sanctioned exceptions: a slow ambient drift
+     * (`duration: 2–5, ease: 'none'`) and an instant reframe behind a
+     * covering element (`duration: 0.01`). 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. */
     move: (
       framing: Framing,
       vars?: gsap.TweenVars,
       position?: gsap.Position
     ) => void
   }
-  /** Deterministic, seek-driven typing with a fake caret. */
+  /** 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 }
+  ) => { duration: number; caret: HTMLElement | null; head: HTMLElement | null }
   /** Rect the finished text will occupy in `target` (for framing the close-up). */
   measureTypedLine: (
     target: string | HTMLTextAreaElement | HTMLInputElement,
@@ -868,6 +1516,138 @@ export type DirectionContext = {
    * `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`. */
+  cursor: CursorKit
+  /** 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). */
+  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. */
+  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. */
+  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. */
+  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). */
+  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. */
+  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. */
+  hero: LooksKit['hero']
+  /** 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' })`. */
+  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. */
+  sentence: SentenceKit['sentence']
+  /** Universal shape morph: any element becomes any other element, a rect, or
+   * `'frame'`. FLIP box + interpolated rounded-rect clip-path silhouette +
+   * content-clone crossfade (`handoff` sets where). Author the TARGET hidden
+   * (`autoAlpha: 0`); the morph reveals it at arrival. `fromPath`/`toPath`
+   * accept real SVG paths for logo endcards. Export-worker safe. */
+  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). */
+  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. */
+  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. */
+  assemble: EnsembleKit['assemble']
+  /** 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. */
+  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). */
+  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. */
+  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: 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. */
+  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. */
+  slam: ImpactKit['slam']
   /** Masks, mattes, and blend composition — the things `clip-path` cannot do.
    *
    * `mask.reveal(el, shape, opts?, position?)` and `mask.hide(...)` animate
@@ -897,6 +1677,14 @@ export type DirectionContext = {
 
 export type Direction = (ctx: DirectionContext) => void | Promise<void>
 
+export type BuiltScene = {
+  timeline: gsap.core.Timeline
+  runtime: DeterministicStageRuntime
+  scene: SceneInspection
+  config: StageConfig
+  previewOverrides: (overrides: SceneOverrides) => boolean
+}
+
 // ─── Named eases ──────────────────────────────────────────────────────
 
 // ─── The promo easing set ─────────────────────────────────────────────────