@impractical-ai/motion 0.1.5 → 0.1.7

package/assets/kits/looks.ts

@@ -0,0 +1,935 @@
+// ─── Looks — scene lighting, shading, ambient backdrops, and the hero shot ──
+//
+// Three families that share one structural idea: consistency comes from SCENE
+// STATE, not per-element decoration.
+//
+// LIGHT. `light.set({ angle })` declares THE scene light once; every sweep,
+// rim, and cast shadow derives its direction from it. Mismatched shadow
+// directions are the amateur tell — with a single source of truth they cannot
+// happen.
+//
+// BACKDROP. Named ambient systems (`gradient-drift`, `orbs`, `dot-grid`) with
+// an ENERGY BUDGET: presets are tuned so a backdrop alone stays alive but
+// sub-salient on the motion meter (~0.5–2% pixel change per interval — large
+// soft forms, slow velocity, capped contrast). `calm()`/`lift()` duck the
+// background under dense foreground beats, like audio ducking for pixels.
+// The backdrop mounts BEHIND the scene root, so the scene's own background
+// must be transparent (or partially so) where the backdrop should show.
+//
+// HERO. The signature product-shot move: `hero(target, { anchor:
+// 'bottom-right' })` pushes the camera toward one corner of a panel WHILE the
+// panel tilts a few degrees in perspective, a sheen sweeps across the surface
+// as the angle changes, and the shadow deepens — zoom, angle, and light
+// responding together in one round-trip call. `tilt` is the standalone
+// perspective pose. Perspective is applied to the TARGET only, never the
+// stage: promoting the whole scaled stage to a 3D layer blows Chromium's
+// texture budget (see camera.set).
+//
+// Deterministic throughout: drifting backdrops are infinite yoyo tweens (pure
+// functions of timeline position), nothing reads a clock, nothing random.
+
+import gsap from 'gsap'
+import { layoutRect, resolveTarget } from './kits'
+
+export type LooksDeps = {
+  tl: gsap.core.Timeline
+  stage: HTMLElement
+  config: { width: number; height: number }
+  /** Register work to run after the direction body completes (buildScene's
+   * pending queue). Backdrop drift is added HERE, sized to the finished
+   * timeline: an infinite repeat on the master timeline would explode
+   * tl.duration() to gsap's infinity sentinel and the export would never
+   * end. */
+  defer?: (work: Promise<unknown>) => void
+}
+
+// ─── light ────────────────────────────────────────────────────────────────
+
+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 }
+}
+
+// ─── backdrop ─────────────────────────────────────────────────────────────
+
+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' // dev-tool grid with a traveling soft glow pulse
+
+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
+}
+
+// ─── hero ─────────────────────────────────────────────────────────────────
+
+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 }
+}
+
+const EASE = 'ease-in-out-cubic'
+
+/** Light-direction unit vector: where shadows FALL (opposite the source). */
+export function lightVector(angleDeg: number): { x: number; y: number } {
+  const rad = ((angleDeg + 180) * Math.PI) / 180
+  return { x: Math.sin(rad), y: -Math.cos(rad) }
+}
+
+/** Default tilt for a hero anchor: the panel leans so the anchored corner
+ * comes toward the camera. */
+export function heroTiltFor(anchor: HeroAnchor): { pitch: number; yaw: number } {
+  if (typeof anchor === 'object') {
+    return { pitch: (anchor.y - 0.5) * 14, yaw: (0.5 - anchor.x) * 18 }
+  }
+  switch (anchor) {
+    case 'top-left': return { pitch: -7, yaw: 9 }
+    case 'top-right': return { pitch: -7, yaw: -9 }
+    case 'bottom-left': return { pitch: 7, yaw: 9 }
+    case 'bottom-right': return { pitch: 7, yaw: -9 }
+    default: return { pitch: 0, yaw: 0 }
+  }
+}
+
+export function anchorFraction(anchor: HeroAnchor): { x: number; y: number } {
+  if (typeof anchor === 'object') return anchor
+  switch (anchor) {
+    case 'top-left': return { x: 0.2, y: 0.22 }
+    case 'top-right': return { x: 0.8, y: 0.22 }
+    case 'bottom-left': return { x: 0.2, y: 0.78 }
+    case 'bottom-right': return { x: 0.8, y: 0.78 }
+    default: return { x: 0.5, y: 0.5 }
+  }
+}
+
+/** Alpha of a computed background-color ('rgba(…)', 'rgb(…)', 'transparent'). */
+function bgAlpha(color: string): number {
+  const match = color.match(/rgba?\(([^)]+)\)/)
+  if (!match) return color === 'transparent' ? 0 : 1
+  const parts = match[1].split(',')
+  return parts.length === 4 ? parseFloat(parts[3]) : 1
+}
+
+/** A "surface" is something light can land on: an element that paints its own
+ * background. Light only exists ON material — a sweep over a transparent
+ * container must distribute to its surfaces, never hover over the gaps. */
+function isSurface(el: HTMLElement): boolean {
+  const style = getComputedStyle(el)
+  return bgAlpha(style.backgroundColor) > 0.03 || style.backgroundImage !== 'none'
+}
+
+/** Top-most surfaces under `root` (children of a collected surface are lit by
+ * their parent's sweep). The root itself counts when it paints a background. */
+function collectSurfaces(root: HTMLElement): HTMLElement[] {
+  if (isSurface(root)) return [root]
+  const out: HTMLElement[] = []
+  const walk = (node: HTMLElement) => {
+    for (const child of Array.from(node.children) as HTMLElement[]) {
+      if (child instanceof HTMLElement) {
+        if (isSurface(child)) out.push(child)
+        else walk(child)
+      }
+    }
+  }
+  walk(root)
+  return out
+}
+
+const GRADES: Record<string, string> = {
+  'warm-product': 'saturate(1.06) contrast(1.04) sepia(0.07)',
+  'cool-saas': 'saturate(1.05) contrast(1.03) hue-rotate(-6deg)',
+  noir: 'grayscale(0.92) contrast(1.16) brightness(0.98)',
+}
+
+let backdropSeq = 0
+
+export function createLooksKit(deps: LooksDeps): LooksKit {
+  const { tl, stage, config } = deps
+  const lightState: LightState = { angle: 135, warmth: 0.35 }
+
+  const at = (position: gsap.Position | undefined): number =>
+    typeof position === 'number' ? position : tl.duration()
+
+  const rectFor = (target: string | Element, kind: string) => {
+    const el = resolveTarget(stage, target, kind)
+    return { el, rect: layoutRect(stage, el) }
+  }
+
+  const light: LightKit = {
+    set: (state) => {
+      Object.assign(lightState, state)
+    },
+
+    sweep: (target, opts = {}, position) => {
+      const { el, rect: rootRect } = rectFor(target, 'light.sweep')
+      const duration = opts.duration ?? 0.9
+      const intensity = opts.intensity ?? 0.28
+      const warmTint = lightState.warmth > 0.5 ? '255,246,230' : '255,255,255'
+      const start = at(position)
+
+      // A TRAVELING POINT LIGHT, not a gradient stripe. One light position
+      // moves through root space along the scene-light direction; every
+      // surface is lit by a radial pool centered at the light's projected
+      // position, falling off with distance. Intensity ramps in and out with
+      // a smooth envelope — no visibility toggles, so nothing pops.
+      const v = lightVector(lightState.angle)
+      const radius = opts.width
+        ? Math.max(rootRect.width, rootRect.height) * opts.width * 2.4
+        : Math.max(rootRect.width, rootRect.height) * 0.85
+      const cx0 = rootRect.width / 2
+      const cy0 = rootRect.height / 2
+      const halfSpan = Math.hypot(rootRect.width, rootRect.height) / 2 + radius * 0.4
+      const fromPt = { x: cx0 - v.x * halfSpan, y: cy0 - v.y * halfSpan }
+      const toPt = { x: cx0 + v.x * halfSpan, y: cy0 + v.y * halfSpan }
+      const envelope = (p: number) => {
+        const up = Math.min(1, p / 0.18)
+        const down = Math.min(1, (1 - p) / 0.18)
+        return up * up * (3 - 2 * up) * (down * down * (3 - 2 * down))
+      }
+
+      const surfaces = collectSurfaces(el)
+      type Lit = { holder: HTMLElement; pool: HTMLElement; offsetX: number; offsetY: number }
+      const lit: Lit[] = []
+
+      const surfaceTint = `radial-gradient(circle, rgba(${warmTint},${Math.min(1, intensity)}) 0%, ` +
+        `rgba(${warmTint},${Math.min(1, intensity) * 0.45}) 38%, transparent 68%)`
+      // Light reads on BRIGHT surfaces by contrast: while the light passes,
+      // ambient dips a touch everywhere the pool is not. Without this, a
+      // white pool on a white card is physically invisible.
+      const ambientDip = Math.min(0.35, intensity * 0.55)
+
+      if (surfaces.length) {
+        for (const surface of surfaces) {
+          const sRect = layoutRect(stage, surface)
+          if (getComputedStyle(surface).position === 'static') surface.style.position = 'relative'
+          const holder = document.createElement('div')
+          holder.setAttribute('data-light-sweep', '')
+          // Inside the surface (inherits any 3D transform), clipped by its
+          // corners; opacity is driven by the envelope every frame.
+          holder.style.cssText =
+            `position:absolute;inset:0;overflow:hidden;pointer-events:none;z-index:40;` +
+            `opacity:0;border-radius:inherit;background:rgba(26,28,46,${ambientDip.toFixed(3)});`
+          const pool = document.createElement('div')
+          pool.style.cssText =
+            `position:absolute;left:0;top:0;width:${radius * 2}px;height:${radius * 2}px;` +
+            `background:${surfaceTint};will-change:transform;`
+          holder.appendChild(pool)
+          surface.appendChild(holder)
+          lit.push({
+            holder,
+            pool,
+            offsetX: sRect.left - rootRect.left,
+            offsetY: sRect.top - rootRect.top,
+          })
+        }
+      } else {
+        // Bare text: the light pool lives in the GLYPHS via a
+        // background-clip:text clone — never a rectangle.
+        const textContent = (el.textContent ?? '').trim()
+        if (!textContent) return { duration: 0 }
+        const style = getComputedStyle(el)
+        if (style.position === 'static') el.style.position = 'relative'
+        const holder = document.createElement('div')
+        holder.setAttribute('data-light-sweep', '')
+        holder.style.cssText =
+          'position:absolute;inset:0;pointer-events:none;z-index:40;opacity:0;'
+        const clone = document.createElement('div')
+        clone.textContent = textContent
+        clone.style.cssText =
+          `font-family:${style.fontFamily};font-size:${style.fontSize};` +
+          `font-weight:${style.fontWeight};font-style:${style.fontStyle};` +
+          `line-height:${style.lineHeight};letter-spacing:${style.letterSpacing};` +
+          `white-space:${style.whiteSpace};color:transparent;` +
+          `background-image:radial-gradient(circle ${Math.round(radius)}px at 0px 0px, ` +
+          `rgba(${warmTint},${Math.min(1, intensity * 2.4)}) 0%, transparent 70%);` +
+          `background-repeat:no-repeat;-webkit-background-clip:text;background-clip:text;`
+        holder.appendChild(clone)
+        el.appendChild(holder)
+        const proxyText = { p: 0 }
+        tl.to(
+          proxyText,
+          {
+            p: 1,
+            duration,
+            ease: opts.ease ?? EASE,
+            onUpdate: () => {
+              const p = proxyText.p
+              const lx = fromPt.x + (toPt.x - fromPt.x) * p
+              const ly = fromPt.y + (toPt.y - fromPt.y) * p
+              clone.style.backgroundPosition = `${(lx - radius).toFixed(1)}px ${(ly - radius).toFixed(1)}px`
+              holder.style.opacity = envelope(p).toFixed(3)
+            },
+          },
+          start
+        )
+        return { duration }
+      }
+
+      const proxy = { p: 0 }
+      tl.to(
+        proxy,
+        {
+          p: 1,
+          duration,
+          ease: opts.ease ?? EASE,
+          onUpdate: () => {
+            const p = proxy.p
+            const lx = fromPt.x + (toPt.x - fromPt.x) * p
+            const ly = fromPt.y + (toPt.y - fromPt.y) * p
+            const alpha = envelope(p).toFixed(3)
+            for (const entry of lit) {
+              // Transform-only per frame: the pool re-centers on the light's
+              // position in this surface's local space.
+              const px = lx - entry.offsetX - radius
+              const py = ly - entry.offsetY - radius
+              entry.pool.style.transform = `translate(${px.toFixed(1)}px, ${py.toFixed(1)}px)`
+              entry.holder.style.opacity = alpha
+            }
+          },
+        },
+        start
+      )
+      return { duration }
+    },
+
+    rim: (target, opts = {}, position) => {
+      const { el } = rectFor(target, 'light.rim')
+      const intensity = opts.intensity ?? 0.5
+      const duration = opts.duration ?? 0.5
+      const color = opts.color ?? (lightState.warmth > 0.5 ? '#ffe9c9' : '#eaf2ff')
+      const v = lightVector(lightState.angle)
+      const rim = document.createElement('div')
+      rim.setAttribute('data-light-rim', '')
+      // Inside the target for the same reason as the sweep: the rim must
+      // tilt with the panel it lights.
+      rim.style.cssText =
+        `position:absolute;inset:0;pointer-events:none;z-index:39;opacity:0;` +
+        `border-radius:inherit;` +
+        // The lit edge faces the source: inset shadow offset TOWARD the light.
+        `box-shadow:inset ${(-v.x * 3).toFixed(1)}px ${(-v.y * 3).toFixed(1)}px 8px ${color};`
+      if (getComputedStyle(el).position === 'static') el.style.position = 'relative'
+      el.appendChild(rim)
+      tl.to(rim, { opacity: intensity, duration, ease: EASE }, at(position))
+      return { duration }
+    },
+  }
+
+  const shade: ShadeKit = {
+    cast: (target, opts = {}, position) => {
+      const { el, rect } = rectFor(target, 'shade.cast')
+      const distance = opts.distance ?? Math.max(10, rect.height * 0.06)
+      const softness = opts.softness ?? distance * 2.4
+      const opacity = opts.opacity ?? 0.22
+      const duration = opts.duration ?? 0.5
+      const v = lightVector(lightState.angle)
+      const shadow = document.createElement('div')
+      shadow.setAttribute('data-shade-cast', '')
+      shadow.style.cssText =
+        `position:absolute;left:${rect.left}px;top:${rect.top}px;width:${rect.width}px;` +
+        `height:${rect.height}px;pointer-events:none;z-index:0;opacity:0;` +
+        `border-radius:${getComputedStyle(el).borderRadius || '8px'};` +
+        `box-shadow:${(v.x * distance).toFixed(1)}px ${(v.y * distance).toFixed(1)}px ` +
+        `${softness.toFixed(1)}px rgba(10,10,16,${opacity});`
+      // Behind the scene root, so the shadow never paints over the element.
+      stage.insertBefore(shadow, stage.firstChild)
+      tl.to(shadow, { opacity: 1, duration, ease: EASE }, at(position))
+      return { duration }
+    },
+
+    vignette: (opts = {}, position) => {
+      const strength = opts.strength ?? 0.22
+      const duration = opts.duration ?? 0.8
+      const overlay = document.createElement('div')
+      overlay.setAttribute('data-shade-vignette', '')
+      overlay.style.cssText =
+        `position:absolute;inset:0;pointer-events:none;z-index:9840;opacity:0;` +
+        `background:radial-gradient(ellipse 78% 72% at 50% 46%, transparent 58%, ` +
+        `rgba(8,8,14,${strength}) 100%);`
+      stage.appendChild(overlay)
+      tl.to(overlay, { opacity: 1, duration, ease: EASE }, at(position))
+      return { duration }
+    },
+
+    grade: (preset, opts = {}, position) => {
+      const filter = GRADES[preset]
+      const duration = opts.duration ?? 0.8
+      const root = stage.firstElementChild as HTMLElement | null
+      if (!filter || !root) return { duration: 0 }
+      tl.to(root, { filter, duration, ease: EASE }, at(position))
+      return { duration }
+    },
+  }
+
+  const backdrop = (style: BackdropStyle, opts: BackdropOpts = {}): BackdropHandle => {
+    const energy = Math.max(0, Math.min(1, opts.energy ?? 0.3))
+    const palette = opts.palette ?? ['#5865F2', '#00B476', '#ffb020']
+    const { width: W, height: H } = config
+    const container = document.createElement('div')
+    container.setAttribute('data-backdrop', style)
+    container.style.cssText =
+      `position:absolute;inset:0;overflow:hidden;pointer-events:none;` +
+      (opts.base ? `background:${opts.base};` : '')
+    if (opts.fixed !== false && stage.parentElement) {
+      // Fixed backplate: mounted on the stage's PARENT (the transition kit's
+      // escape-the-camera precedent), behind the stage — camera transforms
+      // move the UI plane over an unmoving ground. Parent-mounted nodes are
+      // not auto-cleaned per rebuild, so clear any predecessor first.
+      const parent = stage.parentElement
+      for (const old of Array.from(parent.querySelectorAll(':scope > [data-backdrop]'))) {
+        old.remove()
+      }
+      parent.insertBefore(container, stage)
+    } else {
+      // Behind the scene root — the scene's background must let it show through.
+      stage.insertBefore(container, stage.firstChild)
+    }
+    // calm()/lift() duck the FORMS, never the base ground.
+    const forms = document.createElement('div')
+    forms.style.cssText = 'position:absolute;inset:0;'
+    container.appendChild(forms)
+
+    // Speed scales with energy; drift cycles are long so per-frame change
+    // stays inside the sub-salient budget.
+    const cycle = 14 - energy * 8
+
+    // Collect the drifting elements now; add their tweens AFTER the direction
+    // body finishes, so each drift can be sized to the real scene duration
+    // with FINITE repeats (never inflating tl.duration()).
+    const drifting: Array<{ el: HTMLElement; vars: Record<string, unknown>; cycle: number }> = []
+
+    if (style === 'paper') {
+      // The reference-film ground: a softly shaded, essentially STILL sheet —
+      // cloudy light from one corner, gentle density in the opposite one.
+      // No drifting forms; the confidence is in the stillness.
+      const tint = palette[0] ?? '#8ea3c0'
+      const sheet = document.createElement('div')
+      sheet.style.cssText =
+        `position:absolute;inset:0;` +
+        `background:` +
+        `radial-gradient(120% 95% at 18% 8%, rgba(255,255,255,0.85) 0%, transparent 58%),` +
+        `radial-gradient(95% 85% at 86% 92%, ${tint}44 0%, transparent 62%),` +
+        `radial-gradient(70% 55% at 72% 18%, rgba(255,255,255,0.5) 0%, transparent 60%),` +
+        `radial-gradient(80% 70% at 8% 88%, ${tint}2e 0%, transparent 65%);`
+      forms.appendChild(sheet)
+    } else if (style === 'aurora') {
+      // Stripe-style mesh ribbons: elongated PRE-SOFT gradient sheets on a
+      // diagonal, drifting very slowly. No filters — stacked radial stops.
+      const colors = [palette[0] ?? '#635bff', palette[1] ?? '#ff7ac8', palette[2] ?? '#ffb020']
+      for (let i = 0; i < 2; i += 1) {
+        const ribbon = document.createElement('div')
+        ribbon.style.cssText =
+          `position:absolute;left:${(W * (i ? 0.02 : -0.18)).toFixed(0)}px;` +
+          `top:${(H * (i ? 0.4 : 0.0)).toFixed(0)}px;` +
+          `width:${(W * 1.5).toFixed(0)}px;height:${(H * (0.68 - i * 0.16)).toFixed(0)}px;` +
+          `transform:rotate(${-24 + i * 12}deg);` +
+          `background:` +
+          `radial-gradient(50% 62% at 28% 50%, ${colors[i % 3]}59 0%, transparent 70%),` +
+          `radial-gradient(46% 56% at 55% 44%, ${colors[(i + 1) % 3]}47 0%, transparent 70%),` +
+          `radial-gradient(40% 52% at 79% 56%, ${colors[(i + 2) % 3]}3d 0%, transparent 72%);` +
+          `opacity:${(0.65 + energy * 0.3).toFixed(2)};`
+        forms.appendChild(ribbon)
+        drifting.push({
+          el: ribbon,
+          vars: {
+            x: (i ? -1 : 1) * (200 + energy * 120),
+            y: (i ? 1 : -1) * (110 + energy * 70),
+            rotation: `+=${i ? -6 : 6}`,
+            scale: 1.12,
+          },
+          cycle: 6.5 + i * 1.8,
+        })
+      }
+    } else if (style === 'threads') {
+      // Mintlify-style strands: two fans of fine gradient curves sweeping
+      // opposite corners. Deterministic geometry, whole plate drifts gently.
+      const gradId = `bd-threads-${(backdropSeq += 1)}`
+      const plate = document.createElement('div')
+      plate.style.cssText = 'position:absolute;left:-6%;top:-6%;width:112%;height:112%;'
+      const ns = 'http://www.w3.org/2000/svg'
+      const svg = document.createElementNS(ns, 'svg')
+      svg.setAttribute('viewBox', `0 0 ${W} ${H}`)
+      svg.setAttribute('preserveAspectRatio', 'none')
+      svg.setAttribute('width', '100%')
+      svg.setAttribute('height', '100%')
+      const defs = document.createElementNS(ns, 'defs')
+      const grad = document.createElementNS(ns, 'linearGradient')
+      grad.setAttribute('id', gradId)
+      grad.setAttribute('x1', '0')
+      grad.setAttribute('y1', '0')
+      grad.setAttribute('x2', '1')
+      grad.setAttribute('y2', '1')
+      const s1 = document.createElementNS(ns, 'stop')
+      s1.setAttribute('offset', '0%')
+      s1.setAttribute('stop-color', palette[0] ?? '#16a34a')
+      const s2 = document.createElementNS(ns, 'stop')
+      s2.setAttribute('offset', '100%')
+      s2.setAttribute('stop-color', palette[1] ?? palette[0] ?? '#a3e635')
+      grad.appendChild(s1)
+      grad.appendChild(s2)
+      defs.appendChild(grad)
+      svg.appendChild(defs)
+      const strands = 14
+      for (let b = 0; b < 2; b += 1) {
+        for (let k = 0; k < strands; k += 1) {
+          const p = document.createElementNS(ns, 'path')
+          const f = k / (strands - 1)
+          const d = b
+            ? `M ${-W * 0.08} ${H * (0.62 + f * 0.3)} C ${W * 0.22} ${H * (0.5 + f * 0.28)}, ${W * 0.38} ${H * (0.92 - f * 0.24)}, ${W * 0.62} ${H * (0.66 + f * 0.2)}`
+            : `M ${W * (0.4 + f * 0.05)} ${-H * 0.08} C ${W * (0.52 + f * 0.06)} ${H * (0.22 + f * 0.1)}, ${W * (0.78 - f * 0.05)} ${H * (0.18 + f * 0.16)}, ${W * 1.08} ${H * (0.42 + f * 0.26)}`
+          p.setAttribute('d', d)
+          p.setAttribute('fill', 'none')
+          p.setAttribute('stroke', `url(#${gradId})`)
+          p.setAttribute('stroke-width', '1.5')
+          p.setAttribute('opacity', (0.3 + 0.35 * Math.sin(Math.PI * f)).toFixed(2))
+          svg.appendChild(p)
+        }
+      }
+      plate.appendChild(svg)
+      forms.appendChild(plate)
+      drifting.push({ el: plate, vars: { x: 55 + energy * 40, y: 30 + energy * 20, rotation: 1.5 }, cycle: 9 })
+    } else if (style === 'dot-matrix') {
+      // AgentMail-style shimmering dot field: two dot layers with DIFFERENT
+      // spacings drifting opposite ways — the moiré between them reads as an
+      // organic density wave. Radial mask keeps the content area clear.
+      const fg = palette[0] ?? '#8f9bb3'
+      const mask =
+        'radial-gradient(85% 78% at 50% 46%, transparent 28%, black 74%)'
+      const mk = (spacing: number, alpha: string, dir: 1 | -1) => {
+        const p = document.createElement('div')
+        p.style.cssText =
+          `position:absolute;left:-12%;top:-12%;width:124%;height:124%;` +
+          `background-image:radial-gradient(circle, ${fg}${alpha} 2px, transparent 2px);` +
+          `background-size:${spacing}px ${spacing}px;` +
+          `-webkit-mask-image:${mask};mask-image:${mask};`
+        forms.appendChild(p)
+        drifting.push({
+          el: p,
+          vars: { x: dir * (spacing * 2.5 + energy * 40), y: -dir * (spacing * 1.4 + energy * 24) },
+          cycle: dir > 0 ? 7 : 8.5,
+        })
+      }
+      mk(22, '73', 1)
+      mk(22, '40', -1)
+    } else if (style === 'grid-glow') {
+      // Blueprint grid + one traveling pre-soft glow pulse.
+      const lineC = palette[0] ?? '#3b82f6'
+      const grid = document.createElement('div')
+      grid.style.cssText =
+        `position:absolute;left:-8%;top:-8%;width:116%;height:116%;` +
+        `background-image:` +
+        `repeating-linear-gradient(0deg, ${lineC}38 0 1px, transparent 1px 56px),` +
+        `repeating-linear-gradient(90deg, ${lineC}38 0 1px, transparent 1px 56px);`
+      forms.appendChild(grid)
+      const glow = document.createElement('div')
+      const gsize = Math.round(W * 0.42)
+      glow.style.cssText =
+        `position:absolute;left:${Math.round(W * 0.1)}px;top:${Math.round(H * 0.15)}px;` +
+        `width:${gsize}px;height:${gsize}px;border-radius:50%;` +
+        `background:radial-gradient(circle, ${palette[1] ?? lineC}59 0%, transparent 62%);`
+      forms.appendChild(glow)
+      // Grid stays STATIC — drifting 1px lines crawl/alias at video scale.
+      drifting.push({
+        el: glow,
+        vars: { x: W * 0.5 + energy * 120, y: H * 0.38 + energy * 60 },
+        cycle: 7,
+      })
+      const glow2 = document.createElement('div')
+      const g2 = Math.round(W * 0.3)
+      glow2.style.cssText =
+        `position:absolute;left:${Math.round(W * 0.62)}px;top:${Math.round(H * 0.55)}px;` +
+        `width:${g2}px;height:${g2}px;border-radius:50%;` +
+        `background:radial-gradient(circle, ${lineC}47 0%, transparent 62%);`
+      forms.appendChild(glow2)
+      drifting.push({ el: glow2, vars: { x: -W * 0.4, y: -H * 0.3 }, cycle: 8.6 })
+    } else if (style === 'gradient-drift' || style === 'orbs') {
+      const count = style === 'orbs' ? 4 : 2
+      const sizeBase = style === 'orbs' ? 0.34 : 0.62
+      for (let i = 0; i < count; i += 1) {
+        const orb = document.createElement('div')
+        const size = W * sizeBase * (1 - i * 0.12)
+        const x = W * (0.15 + (i * 0.27) % 0.7)
+        const y = H * (0.12 + ((i * 0.37 + 0.1) % 0.66))
+        // A pre-soft radial disc, NOT filter:blur — an animated element
+        // carrying a huge blur filter recomposites every frame and janks the
+        // live preview (and breaks the house 20px animated-blur ceiling).
+        orb.style.cssText =
+          `position:absolute;left:${x - size * 0.5}px;top:${y - size * 0.5}px;` +
+          `width:${size * 2}px;height:${size * 2}px;border-radius:50%;` +
+          `background:radial-gradient(circle, ${palette[i % palette.length]} 0%, transparent 62%);` +
+          `opacity:${(0.1 + energy * 0.14).toFixed(3)};`
+        forms.appendChild(orb)
+        drifting.push({
+          el: orb,
+          vars: {
+            x: (i % 2 ? -1 : 1) * (40 + energy * 120) * (1 + i * 0.3),
+            y: (i % 3 ? 1 : -1) * (30 + energy * 90),
+            scale: 1 + 0.05 + energy * 0.08,
+          },
+          cycle: cycle + i * 2.3,
+        })
+      }
+    } else {
+      // dot-grid: a pattern plate panning very slowly.
+      const plate = document.createElement('div')
+      plate.style.cssText =
+        `position:absolute;left:-10%;top:-10%;width:120%;height:120%;` +
+        `background-image:radial-gradient(circle, rgba(120,120,140,${(0.16 + energy * 0.12).toFixed(3)}) 1.6px, transparent 1.6px);` +
+        `background-size:44px 44px;`
+      forms.appendChild(plate)
+      drifting.push({
+        el: plate,
+        vars: { x: 44 + energy * 66, y: 22 + energy * 33 },
+        cycle: cycle * 1.6,
+      })
+    }
+
+    const addDrift = () => {
+      const span = tl.duration()
+      if (!(span > 0) || span > 1e6) return
+      for (const drift of drifting) {
+        // Finite yoyo repeats capped at the scene span, so the drift covers
+        // the whole film without extending it.
+        const repeats = Math.max(1, Math.floor(span / drift.cycle))
+        tl.to(
+          drift.el,
+          {
+            ...drift.vars,
+            // Fills [0, span] exactly: cycles stretch slightly rather than
+            // leaving a dead tail.
+            duration: span / repeats,
+            repeat: repeats - 1,
+            yoyo: true,
+            ease: 'sine.inOut',
+          },
+          0
+        )
+      }
+    }
+    if (deps.defer) deps.defer(Promise.resolve().then(addDrift))
+    else addDrift()
+
+    return {
+      el: container,
+      calm: (position) => {
+        tl.to(forms, { opacity: 0.35, duration: 0.6, ease: EASE }, at(position))
+      },
+      lift: (position) => {
+        tl.to(forms, { opacity: 1, duration: 0.8, ease: EASE }, at(position))
+      },
+    }
+  }
+
+  const tilt: LooksKit['tilt'] = (target, opts = {}, position) => {
+    const el = resolveTarget(stage, target, 'tilt')
+    const duration = opts.duration ?? 0.8
+    tl.to(
+      el,
+      {
+        rotationX: opts.pitch ?? 0,
+        rotationY: opts.yaw ?? 0,
+        transformPerspective: opts.perspective ?? 1400,
+        duration,
+        ease: opts.ease ?? EASE,
+      },
+      at(position)
+    )
+    return { duration }
+  }
+
+  const hero: LooksKit['hero'] = (target, opts = {}, position) => {
+    const { el, rect } = rectFor(target, 'hero')
+    const anchor = opts.anchor ?? 'bottom-right'
+    const frac = anchorFraction(anchor)
+    const tiltPose = heroTiltFor(anchor)
+    const pitch = opts.pitch ?? tiltPose.pitch
+    const yaw = opts.yaw ?? tiltPose.yaw
+    const zoom = opts.zoom ?? 1.35
+    const duration = opts.duration ?? 0.9
+    const hold = opts.hold ?? 1.2
+    const returnDuration = opts.returnDuration ?? 0.8
+    const settle = opts.settle !== false
+    const ease = opts.ease ?? 'promo-inout'
+    const start = at(position)
+    const { width: W, height: H } = config
+
+    // Camera push toward the anchored region of the target (same transform
+    // model as camera.framing: viewport = scene × scale + translate).
+    const scale = (W / rect.width) * zoom
+    const cx = rect.left + rect.width * frac.x
+    const cy = rect.top + rect.height * frac.y
+    const x = W / 2 - scale * cx
+    const y = H / 2 - scale * cy
+    tl.to(stage, { scale, x, y, duration, ease, force3D: false }, start)
+
+    // The panel leans its far corner away — perspective on the TARGET, never
+    // the stage (GPU texture budget). The tilt starts a beat into the push
+    // and develops on a LONGER ease-out, so the angle is seen arriving in
+    // close-up instead of completing while the panel is still small.
+    const tiltStart = start + duration * 0.25
+    const tiltDuration = duration * 1.5
+    tl.to(
+      el,
+      {
+        rotationX: pitch,
+        rotationY: yaw,
+        transformPerspective: 1400,
+        duration: tiltDuration,
+        ease: 'ease-out-quart',
+      },
+      tiltStart
+    )
+
+    // Light RESPONDS to the angle: the sheen runs on exactly the tilt's
+    // window and curve, so the glint crosses the glass as the glass turns.
+    if (opts.sheen !== false) {
+      light.sweep(
+        el,
+        { duration: tiltDuration, intensity: 0.18, ease: 'ease-out-quart' },
+        tiltStart
+      )
+    }
+    // The shadow is painted BY the element (boxShadow), so it tilts with the
+    // panel — a stage-level shadow plate would stay flat under an angled card.
+    const restShadow = getComputedStyle(el).boxShadow
+    const from = restShadow === 'none' ? '0px 0px 0px rgba(6,6,14,0)' : restShadow
+    const v = lightVector(lightState.angle)
+    const deep = `${(v.x * 26).toFixed(0)}px ${(Math.max(v.y, 0.3) * 34).toFixed(0)}px 70px rgba(6,6,14,0.5)`
+    if (opts.shadow !== false) {
+      tl.fromTo(el, { boxShadow: from }, { boxShadow: deep, duration, ease }, start)
+    }
+
+    if (!settle) return { duration: duration + hold }
+
+    const back = start + duration + hold
+    tl.to(stage, { scale: 1, x: 0, y: 0, duration: returnDuration, ease, force3D: false }, back)
+    tl.to(
+      el,
+      { rotationX: 0, rotationY: 0, duration: returnDuration, ease },
+      back
+    )
+    if (opts.shadow !== false) {
+      tl.to(el, { boxShadow: from, duration: returnDuration, ease }, back)
+    }
+    return { duration: duration + hold + returnDuration }
+  }
+
+  const track: LooksKit['track'] = (target, opts = {}, position) => {
+    const el = resolveTarget(stage, target, 'track')
+    const duration = opts.duration ?? 2
+    const height = opts.height ?? 0.5
+    const attach = Math.max(0.01, Math.min(1, opts.attach ?? 0.25))
+    const from = opts.from ?? { scale: 1, x: 0, y: 0 }
+    const releaseMode = opts.release ?? 'full'
+    // The release lives INSIDE the same per-frame computation, never as a
+    // separate start-capturing tween: the exporter renders with parallel
+    // workers, and a fresh worker seeking past this tween gets its callbacks
+    // suppressed as "jumped over" — a capturing release tween then starts
+    // from an unposed camera and snaps. With the release folded in, every
+    // frame is a pure function of the seeked time, and the tween ENDS at the
+    // camera baseline, so a suppressed final render lands on the same pose
+    // the stage already holds.
+    const releaseDur = releaseMode === 'full' ? 0.8 : 0
+    const total = duration + releaseDur
+    const start = at(position)
+    const { width: W, height: H } = config
+    const proxy = { p: 0 }
+    tl.to(
+      proxy,
+      {
+        p: 1,
+        duration: total,
+        ease: 'none',
+        onUpdate: () => {
+          // Scene coords from the LIVE rect: unmap the current camera
+          // transform and any outer studio scaling, then re-center. Reading
+          // then writing in one pass — no feedback loop, and deterministic
+          // because gsap renders this proxy after the movers (insertion
+          // order; track is authored after the motion it follows).
+          const stageScale = Number(gsap.getProperty(stage, 'scaleX')) || 1
+          const sr = stage.getBoundingClientRect()
+          const k = stage.offsetWidth ? sr.width / (stage.offsetWidth * stageScale) : 1
+          const r = el.getBoundingClientRect()
+          const sceneL = (r.left - sr.left) / (k * stageScale)
+          const sceneT = (r.top - sr.top) / (k * stageScale)
+          const sceneW = r.width / (k * stageScale)
+          const sceneH = r.height / (k * stageScale)
+          if (!(sceneW > 0) || !(sceneH > 0)) return
+          const scale = Math.min((H * height) / sceneH, (W * 0.9) / sceneW)
+          const cx = sceneL + sceneW / 2
+          const cy = sceneT + sceneH / 2
+          const tx = W / 2 - scale * cx
+          const ty = H / 2 - scale * cy
+          const tt = proxy.p * total
+          // Eased catch-up from the declared start pose — pure function of tt.
+          const t = Math.min(1, tt / Math.max(1e-6, attach * duration))
+          const a = 1 - Math.pow(1 - t, 3)
+          let bs = from.scale + (scale - from.scale) * a
+          let bx = from.x + (tx - from.x) * a
+          let by = from.y + (ty - from.y) * a
+          if (releaseDur > 0 && tt > duration) {
+            // Ease back to the full frame — the subject's rect at any
+            // release-phase time is its rest pose, so this too replays
+            // correctly from a cold seek.
+            const rp = Math.min(1, (tt - duration) / releaseDur)
+            const re = rp < 0.5 ? 4 * rp * rp * rp : 1 - Math.pow(-2 * rp + 2, 3) / 2
+            bs = bs + (1 - bs) * re
+            bx = bx * (1 - re)
+            by = by * (1 - re)
+          }
+          // Clamp to the stage like camera.framing does — a tracked subject
+          // near an edge must never drag the frame off the stage into black.
+          const sw2 = stage.offsetWidth * bs
+          const sh2 = stage.offsetHeight * bs
+          bx = sw2 >= W ? Math.min(0, Math.max(W - sw2, bx)) : (W - sw2) / 2
+          by = sh2 >= H ? Math.min(0, Math.max(H - sh2, by)) : (H - sh2) / 2
+          gsap.set(stage, { scale: bs, x: bx, y: by, force3D: false })
+        },
+      },
+      start
+    )
+    return { duration: total }
+  }
+
+  return { light, shade, backdrop, hero, tilt, track }
+}