@impractical-ai/motion 0.1.7 → 0.1.9

package/assets/kits/reveal.ts

@@ -1,1364 +0,0 @@
-// DRAFT-SIDE working-views engine — GENERATED from src/stage/reveal.ts. Do not hand-edit.
-// Regenerate with: node .build-draft-reveal.mjs
-//
-// Ships inside the draft so the Studio's reveal verbs work on the currently
-// deployed engine. Stands down automatically once the engine deploy lands.
-// Working views — the canvas shows what the agent is doing to it.
-//
-// Two gestures, both driven from the Studio over the bridge:
-//
-//   reveal(root)   a scene (or one component subtree) resolves parent→child
-//                  after a write lands. Elements are grouped by DOM depth;
-//                  siblings at a depth fire together, children wait for their
-//                  parent, and each one wipes in top-down behind a blue ring.
-//
-//   working(sel)   an element is ringed BEFORE anything is written, because
-//                  the agent declared it is working there. This is the only
-//                  thing that covers the silence while the model composes.
-//
-// WHY THIS IS SAFE IN AN EXPORT BUNDLE. The stage bundle is also the export
-// artifact, so nothing here may reach a rendered frame. It can't: every entry
-// point below runs only in response to a postMessage, export workers cold-seek
-// and never post, and the module mutates nothing at import time. An un-messaged
-// stage is byte-identical to one without this file.
-//
-// WHY IT DOESN'T FIGHT THE TIMELINE. Elements are hidden with `opacity` and
-// `clip-path` only — neither participates in layout, so the scene's geometry is
-// final before anything animates (rings can be measured in one pass) and any
-// GSAP tween that lands mid-reveal still computes against true rects. Every
-// animation is a Web Animations object we own and can cancel; we never write to
-// the timeline, and we always hand the inline styles back when we're done.
-
-/** Tuned 2026-08-20 and signed off. The ring does NOT converge — offset and
- *  lead are 0, so it stamps in place on the element's real box in sync with
- *  the content wiping in. A converging ring was tried and rejected: it makes
- *  the ring the subject instead of the thing arriving. */
-export type RevealOptions = {
-  /** ms between one depth and the next */
-  depthStagger?: number
-  /** ms between siblings inside a depth */
-  siblingStagger?: number
-  /** ms for a single element to resolve */
-  duration?: number
-  /** px the ring starts outside the box; 0 = stamp in place */
-  ringOffset?: number
-  /** ms the ring starts before its element */
-  ringLead?: number
-  /** draw the ring at all */
-  ring?: boolean
-  /** 'wipe' reveals top-down; 'fade' rises and de-blurs */
-  resolve?: 'wipe' | 'fade'
-  /** How the arrivals are ordered within one moment.
-   *   bfs    — all siblings at a depth together, depth by depth (the tuned one)
-   *   dfs    — one branch completed before the next starts (= document order,
-   *            since document order IS pre-order)
-   *   sweep  — a wave down the frame: delay follows the element's top edge, so
-   *            anything sharing a top edge fires together
-   *   size   — biggest first, so containers land before their details
-   *   leaves — deepest first: details assemble, then the frame around them
-   */
-  order?: 'bfs' | 'dfs' | 'sweep' | 'size' | 'leaves'
-  /** ms per 100px of travel for `sweep`; per element for the sequential modes */
-  stagger?: number
-  /** How far below the root to cascade. A rebuild triggered by a deletion only
-   *  needs to redo the slot that changed — going all the way down redraws an
-   *  entire card because one line was removed. Undefined = the whole subtree. */
-  maxDepth?: number
-  /** These are already clipped by the caller (see hideUntilRevealed). Animate
-   *  them open without re-hiding, and leave OPACITY ALONE — the timeline owns
-   *  opacity via autoAlpha, so holding it at 1 with a forwards fill would stop
-   *  the scene ever hiding the element again. clip-path is ours alone. */
-  preHidden?: boolean
-}
-
-const DEFAULTS: Required<RevealOptions> = {
-  depthStagger: 300,
-  siblingStagger: 120,
-  duration: 500,
-  ringOffset: 0,
-  ringLead: 0,
-  ring: true,
-  resolve: 'wipe',
-  order: 'dfs',
-  stagger: 90,
-  maxDepth: Infinity,
-  preHidden: false,
-}
-
-// HIDING: WHEN IT IS SAFE, AND WHEN IT IS NOT.
-//
-// An earlier version clipped arrivals out of sight DURING PLAYBACK, a few
-// hundred ms before the timeline would bring them in. That was unstable: the
-// film was running, so every hidden node depended on a perfectly-timed
-// hand-back, and any path that missed one left a component invisible for the
-// rest of the run.
-//
-// The montage is a different situation and hiding IS safe there. It never
-// plays — it seeks between frozen frames — so suppression is not racing
-// anything. Everything that will ever appear is hidden ONCE, up front, and
-// each element is released at its own creation moment and stays released. An
-// element's only possible appearance is its cascade, by construction rather
-// than by timing.
-//
-// Two rules keep it honest: we suppress with clip-path, which the engine never
-// writes, so we are never fighting GSAP for a property; and we never touch
-// opacity on a scene that has a timeline, because autoAlpha owns it.
-
-const EASE = 'cubic-bezier(0.16, 1, 0.3, 1)'
-const RING_COLOR = '#2f6bff'
-const LAYER_ID = 'stage-working-layer'
-
-/** The inline values an element carried BEFORE we touched it. The scene sets
- *  these itself — GSAP writes opacity/visibility inline for autoAlpha, and a
- *  chapter waiting its turn is legitimately opacity:0 — so restoring means
- *  putting the old string back, never removeProperty(). Blindly clearing is
- *  the same bug as clearProps eating an element's authored styles. */
-type Prop = 'opacity' | 'clipPath' | 'filter' | 'transform'
-const CSS_NAME: Record<Prop, string> = {
-  opacity: 'opacity', clipPath: 'clip-path', filter: 'filter', transform: 'transform',
-}
-/** ONLY the properties we actually wrote, and their values at the moment we
- *  wrote them. Snapshotting everything and putting it all back re-applies stale
- *  values: an element captured at t=0 carries GSAP's opacity:0 from before its
- *  entrance, so "restoring" it after its cascade makes it vanish. */
-type Prior = Partial<Record<Prop, string>>
-
-/** Every animation and node this module owns, so a second call — or an
- *  uninstall — can take all of it back with no residue. */
-let live: Animation[] = []
-let ringAnims: Animation[] = []
-let touched = new Map<HTMLElement, Prior>()
-let layer: HTMLElement | null = null
-
-const capture = (el: HTMLElement, props: Prop[]): Prior => {
-  const p: Prior = {}
-  for (const k of props) p[k] = el.style[k]
-  return p
-}
-
-/** Merge a capture in without clobbering an earlier one for the same property —
- *  the FIRST value we saw is the one the scene authored. */
-const remember = (el: HTMLElement, props: Prop[]): void => {
-  const existing = touched.get(el) ?? {}
-  for (const k of props) if (!(k in existing)) existing[k] = el.style[k]
-  touched.set(el, existing)
-}
-
-const restore = (el: HTMLElement, p: Prior | undefined): void => {
-  if (!p) return
-  for (const k of Object.keys(p) as Prop[]) {
-    const v = p[k]
-    if (v) el.style.setProperty(CSS_NAME[k], v)
-    else el.style.removeProperty(CSS_NAME[k])
-  }
-}
-
-/**
- * Is this element itself drawn right now?
- *
- * Deliberately does NOT walk the ancestors. A stricter ancestor-aware version
- * was tried: it dates children more accurately, but a container mid-fade at a
- * sampled instant drops its whole subtree, and entire components — a dashboard,
- * a panel — stopped earning a creation moment at all. Being generous here costs
- * a few early moments; being strict costs whole components.
- */
-const onScreen = (el: HTMLElement): boolean => {
-  const s = getComputedStyle(el)
-  if (s.display === 'none' || s.visibility === 'hidden' || Number(s.opacity) === 0) return false
-  const b = el.getBoundingClientRect()
-  return b.width >= 2 && b.height >= 2
-}
-
-const reduced = () =>
-  typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches
-
-function ringLayer(): HTMLElement {
-  if (layer && layer.isConnected) return layer
-  const el = document.createElement('div')
-  el.id = LAYER_ID
-  // The rings live inside the stage document, so they share its coordinate
-  // space — a camera transform on the stage carries them for free. Drawn as
-  // an overlay in the parent they would need the camera math re-derived.
-  el.style.cssText = 'position:fixed;inset:0;pointer-events:none;z-index:2147483000;'
-  document.body.appendChild(el)
-  layer = el
-  return el
-}
-
-/** Put every element back exactly as authored. Called before each new reveal
- *  and by uninstall, so an interrupted reveal can never strand a hidden node. */
-export function clearWorking(): void {
-  for (const a of live) {
-    try {
-      a.cancel()
-    } catch {
-      /* already finished */
-    }
-  }
-  live = []
-  clearRings()
-  stopWatching()
-  for (const [el, prior] of touched) restore(el, prior)
-  touched = new Map()
-  layer?.replaceChildren()
-}
-
-/** Drop the rings without touching any element state. */
-export function clearRings(): void {
-  for (const a of ringAnims) {
-    try {
-      a.cancel()
-    } catch {
-      /* already finished */
-    }
-  }
-  ringAnims = []
-  layer?.replaceChildren()
-}
-
-/** Depth = how many participating ancestors an element has. Computed from the
- *  DOM rather than authored, so any scene works with no annotation beyond the
- *  data-* hooks its direction already needs as selectors. */
-function depthOf(el: Element, participates: (n: Element) => boolean): number {
-  let d = 0
-  let p = el.parentElement
-  while (p) {
-    if (participates(p)) d += 1
-    p = p.parentElement
-  }
-  return d
-}
-
-function drawRing(el: HTMLElement, at: number, o: Required<RevealOptions>): void {
-  const b = el.getBoundingClientRect()
-  if (b.width < 2 || b.height < 2) return
-  const r = document.createElement('div')
-  r.style.cssText =
-    `position:absolute;left:${b.left}px;top:${b.top}px;` +
-    `width:${b.width}px;height:${b.height}px;` +
-    `border-radius:${getComputedStyle(el).borderRadius};` +
-    `outline:1.5px solid ${RING_COLOR};outline-offset:0;opacity:0;`
-  ringLayer().appendChild(r)
-  ringAnims.push(
-    r.animate(
-      [
-        { outlineOffset: `${o.ringOffset}px`, opacity: 0 },
-        { outlineOffset: `${o.ringOffset * 0.35}px`, opacity: 1, offset: 0.35 },
-        { outlineOffset: '0px', opacity: 1, offset: 0.62 },
-        { outlineOffset: '0px', opacity: 0 },
-      ],
-      { duration: o.duration + o.ringLead + 240, delay: at, easing: EASE, fill: 'both' }
-    )
-  )
-}
-
-/**
- * Resolve a subtree parent→child. Pass the whole stage after a first build, or
- * one component's root after an incremental write — same gesture, smaller tree,
- * which is what keeps a re-reveal from costing three seconds on every save.
- *
- * Returns the total run time in ms so the caller can sequence against it.
- */
-export function reveal(root: Element | null, options: RevealOptions = {}): number {
-  if (!root || reduced()) return 0
-  const participates = (n: Element) => n.hasAttribute?.('data-reveal') || hasHook(n)
-  // Depth is computed against every participating ancestor, but only the
-  // currently-visible elements are animated — so a scene whose later chapters
-  // are parked at autoAlpha:0 reveals what's on screen and leaves the rest.
-  const o = { ...DEFAULTS, ...options }
-  const within = (el: Element): boolean => {
-    if (!Number.isFinite(o.maxDepth)) return true
-    let d = 0
-    for (let n = el.parentElement; n && n !== root; n = n.parentElement) if (participates(n)) d += 1
-    return d <= o.maxDepth
-  }
-  const all = [...root.querySelectorAll<HTMLElement>('*')].filter(participates).filter(within)
-  // the root itself takes part, so a rebuilt slot reads as one box changing
-  if (root instanceof HTMLElement && participates(root)) all.unshift(root)
-  return revealElements(all.filter(onScreen), options)
-}
-
-/**
- * Cascade an explicit set of elements. This is the shared core: `reveal()`
- * collects a subtree and hands it here, and the montage hands it exactly the
- * elements that arrived at one creation moment.
- */
-export function revealElements(list: HTMLElement[], options: RevealOptions = {}): number {
-  const o = { ...DEFAULTS, ...options }
-  // Pre-hidden elements are already registered in `touched`; a full clear would
-  // restore every one of them and flash the whole scene into view. The rings
-  // from the previous stop still have to go, or they pile up.
-  if (o.preHidden) clearRings()
-  else clearWorking()
-  const els = list.filter(onScreen).filter((el) => !isScenery(el))
-
-  // Hand back anything we are NOT going to animate. A caller may have hidden
-  // these ahead of time (see preHide), and an element that is hidden but never
-  // revealed stays invisible for the rest of the run.
-  const revealing = new Set(els)
-  for (const el of list) {
-    if (!revealing.has(el) && touched.has(el)) {
-      restore(el, touched.get(el))
-      touched.delete(el)
-    }
-  }
-  if (!els.length || reduced()) return 0
-  const participates = (n: Element) => n.hasAttribute?.('data-reveal') || hasHook(n)
-
-  // When each element fires. Measured before anything is hidden — hiding uses
-  // only non-layout properties, so these rects stay true for the whole run.
-  const delay = new Map<HTMLElement, number>()
-  const seq = (list: HTMLElement[]) => list.forEach((el, i) => delay.set(el, i * o.stagger))
-
-  if (o.order === 'dfs') {
-    // querySelectorAll returns document order, which IS pre-order DFS
-    seq(els)
-  } else if (o.order === 'leaves') {
-    seq([...els].sort((a, b) => depthOf(b, participates) - depthOf(a, participates)))
-  } else if (o.order === 'size') {
-    const area = (el: HTMLElement) => {
-      const b = el.getBoundingClientRect()
-      return b.width * b.height
-    }
-    seq([...els].sort((a, b) => area(b) - area(a)))
-  } else if (o.order === 'sweep') {
-    const tops = els.map((el) => el.getBoundingClientRect().top)
-    const min = Math.min(...tops)
-    els.forEach((el, i) => delay.set(el, ((tops[i] - min) / 100) * o.stagger))
-  } else {
-    const waves: HTMLElement[][] = []
-    for (const el of els) {
-      const d = depthOf(el, participates)
-      ;(waves[d] ||= []).push(el)
-    }
-    waves.forEach((wave, d) => {
-      if (!wave) return
-      wave.forEach((el, i) => delay.set(el, d * o.depthStagger + i * o.siblingStagger))
-    })
-  }
-
-  const hidden = o.resolve === 'wipe' ? 'inset(0 0 100% 0)' : ''
-  if (!o.preHidden) {
-    for (const el of els) {
-      remember(el, hidden ? ['opacity', 'clipPath'] : ['opacity'])
-      el.style.opacity = '0'
-      if (hidden) el.style.clipPath = hidden
-    }
-  }
-
-  let total = 0
-  {
-    for (const el of els) {
-      const at = delay.get(el) ?? 0
-      if (o.ring) drawRing(el, at, o)
-
-      // When the timeline owns opacity we animate clip-path alone — otherwise
-      // GSAP overwrites our keyframes on its very next render.
-      const from: Keyframe =
-        o.resolve === 'wipe'
-          ? { clipPath: 'inset(0 0 100% 0)', filter: 'blur(3px)' }
-          : { filter: 'blur(4px)', transform: 'translateY(8px)' }
-      const to: Keyframe =
-        o.resolve === 'wipe'
-          ? { clipPath: 'inset(0 0 0% 0)', filter: 'blur(0px)' }
-          : { filter: 'blur(0px)', transform: 'translateY(0)' }
-      if (!o.preHidden) {
-        from.opacity = 0
-        to.opacity = 1
-      }
-
-      const a = el.animate([from, to], {
-        duration: o.duration,
-        delay: at + o.ringLead,
-        easing: EASE,
-        fill: 'both',
-      })
-      live.push(a)
-      // Hand the inline styles back the moment this element is settled, so a
-      // scene that keeps animating isn't left fighting our opacity.
-      a.finished
-        .then(() => {
-          // Hand the inline styles back so the scene isn't left fighting ours.
-          // For a pre-hidden element this is also its RELEASE: the original
-          // clip (usually none) goes back and it stays visible from here.
-          restore(el, touched.get(el))
-          touched.delete(el)
-        })
-        .catch(() => {
-          /* cancelled by the next reveal, which restores in clearWorking */
-        })
-      total = Math.max(total, at + o.ringLead + o.duration)
-    }
-  }
-  return total
-}
-
-/** Any element the direction could target is a candidate — that is exactly the
- *  set carrying a data-* hook, so scenes need no extra markup. */
-function hasHook(n: Element): boolean {
-  const el = n as HTMLElement
-  if (!el.dataset) return false
-  for (const k in el.dataset) if (k !== 'reveal') return true
-  return false
-}
-
-/**
- * Ring elements the agent has declared it is working on, and hold the ring
- * until it says otherwise. Nothing is hidden — the elements stay exactly as
- * they are; this only draws over them.
- */
-export function setWorking(selectors: string[]): void {
-  clearWorking()
-  if (reduced() || !selectors?.length) return
-  for (const sel of selectors) {
-    let nodes: NodeListOf<HTMLElement>
-    try {
-      nodes = document.querySelectorAll<HTMLElement>(sel)
-    } catch {
-      continue // a malformed selector must never break the stage
-    }
-    for (const el of nodes) {
-      const b = el.getBoundingClientRect()
-      if (b.width < 2 || b.height < 2) continue
-      const r = document.createElement('div')
-      r.style.cssText =
-        `position:absolute;left:${b.left}px;top:${b.top}px;` +
-        `width:${b.width}px;height:${b.height}px;` +
-        `border-radius:${getComputedStyle(el).borderRadius};` +
-        `outline:1.5px solid ${RING_COLOR};outline-offset:0;`
-      ringLayer().appendChild(r)
-      // A slow breath, not a blink — this can sit on screen for a minute while
-      // the model composes, and a blink would be unbearable at that length.
-      live.push(
-        r.animate([{ opacity: 0.35 }, { opacity: 1 }, { opacity: 0.35 }], {
-          duration: 1800,
-          iterations: Infinity,
-          easing: 'ease-in-out',
-        })
-      )
-    }
-  }
-}
-
-/* ── watching the film build itself ──────────────────────────────────────── */
-
-let watching = 0
-
-/**
- * Ring each element at the moment it FIRST APPEARS as the timeline runs.
- *
- * This is the reveal for a scene that already has a direction: the film's own
- * choreography is the schedule, so nothing here re-animates anything — an
- * element's entrance is already authored, and wiping it a second time would
- * double the motion. We only mark it.
- *
- * `selectors` narrows it to the elements a write just touched, which is what
- * turns "watch the film" into "watch MY change land".
- */
-export function watchAppearances(opts: { selectors?: string[]; hold?: number } = {}): void {
-  stopWatching()
-  if (reduced()) return
-
-  const pool: HTMLElement[] = []
-  if (opts.selectors?.length) {
-    for (const sel of opts.selectors) {
-      try {
-        pool.push(...document.querySelectorAll<HTMLElement>(sel))
-      } catch {
-        /* a malformed selector must never break the stage */
-      }
-    }
-  } else {
-    pool.push(...collect())
-  }
-  if (!pool.length) return
-
-  // getComputedStyle across a large scene every frame is real work, and we only
-  // need to catch a transition, not measure it — so sample, don't poll.
-  const stride = pool.length > 400 ? 6 : 3
-  const hold = opts.hold ?? 900
-  const seen = new WeakSet<HTMLElement>()
-  let frame = 0
-
-  const tick = () => {
-    if (!watching) return
-    if (frame++ % stride === 0) {
-      for (const el of pool) {
-        const now = onScreen(el)
-        if (now && !seen.has(el)) {
-          seen.add(el)
-          stamp(el, hold)
-        } else if (!now && seen.has(el)) {
-          seen.delete(el) // left the frame; ring it again if it comes back
-        }
-      }
-    }
-    watching = requestAnimationFrame(tick)
-  }
-  watching = requestAnimationFrame(tick)
-}
-
-export function stopWatching(): void {
-  if (watching) cancelAnimationFrame(watching)
-  watching = 0
-}
-
-/** A single ring, stamped in place and gone. */
-function stamp(el: HTMLElement, hold: number): void {
-  const b = el.getBoundingClientRect()
-  if (b.width < 2 || b.height < 2) return
-  const r = document.createElement('div')
-  r.style.cssText =
-    `position:absolute;left:${b.left}px;top:${b.top}px;` +
-    `width:${b.width}px;height:${b.height}px;` +
-    `border-radius:${getComputedStyle(el).borderRadius};` +
-    `outline:1.5px solid ${RING_COLOR};outline-offset:0;opacity:0;`
-  ringLayer().appendChild(r)
-  const a = r.animate(
-    [{ opacity: 0 }, { opacity: 1, offset: 0.18 }, { opacity: 1, offset: 0.6 }, { opacity: 0 }],
-    { duration: hold, easing: EASE, fill: 'both' }
-  )
-  ringAnims.push(a)
-  a.finished.then(() => r.remove()).catch(() => r.remove())
-}
-
-/* ── the creation montage ────────────────────────────────────────────────── */
-
-type StageWindow = Window & {
-  __renderAt?: (t: number) => void
-  __duration?: number
-}
-
-let montageToken = 0
-let montagePaused = false
-
-/** Hold the montage where it is. The loop parks between stops, so the frame you
- *  are looking at stays exactly as it is — nothing is animating behind it. */
-export function setMontagePaused(on: boolean): void {
-  montagePaused = on
-}
-export function isMontagePaused(): boolean {
-  return montagePaused
-}
-const waitWhilePaused = async (token: number): Promise<boolean> => {
-  while (montagePaused && token === montageToken) await sleep(80)
-  return token === montageToken
-}
-
-/**
- * When does each element FIRST come on screen?
- *
- * Answered by seeking, not by watching playback — the whole engine is a pure
- * function of timeline position, so stepping the playhead and reading the DOM
- * gives an exact answer with no clock involved. Elements drop out of the pool
- * as they're found, so the sweep gets cheaper the further it goes.
- */
-/**
- * Layout has to be SETTLED before scanning. onScreen requires a box of at least
- * 2px, so text whose webfont hasn't landed measures as nothing and never earns
- * a creation moment — which is why a first run could miss whole components and
- * a second run, with everything settled, found them.
- */
-export async function settleLayout(): Promise<void> {
-  try {
-    await (document.fonts?.ready ?? Promise.resolve())
-  } catch {
-    /* no font API */
-  }
-  await raf()
-  await raf()
-}
-
-export function scanAppearances(selectors?: string[], step = 1 / 12): Map<HTMLElement, number> {
-  const w = window as StageWindow
-  const found = new Map<HTMLElement, number>()
-  const dur = Number(w.__duration) || 0
-  if (!dur || !w.__renderAt) return found
-
-  const pool = new Set<HTMLElement>(collect(selectors))
-  const back = Number((window as unknown as { __timeline?: { time(): number } }).__timeline?.time() ?? 0)
-
-  for (let t = 0; t <= dur && pool.size; t += step) {
-    w.__renderAt(t)
-    for (const el of [...pool]) {
-      if (onScreen(el)) {
-        found.set(el, t)
-        pool.delete(el)
-      }
-    }
-  }
-  w.__renderAt(back) // leave the playhead where we found it
-  return found
-}
-
-/**
- * Step through the film stopping ONLY at the moments something is created, and
- * ring what arrived. Deliberately choppy: this is a montage of creation, not
- * playback, and every element gets its moment instead of whichever ones a
- * sampling loop happened to catch.
- *
- * Each stop lands `settle` seconds after the appearance so the element has
- * finished its entrance — a ring measured mid-entrance sits on a box the
- * element has already moved away from, which is what made watch mode look
- * out of register.
- */
-export async function montage(
-  opts: {
-    selectors?: string[]
-    /** minimum time to sit on each creation moment */
-    hold?: number
-    /** seconds past the appearance to park, so the entrance has finished */
-    settle?: number
-    maxStops?: number
-    step?: number
-    /** which algorithm finds the moments */
-    algo?: MomentAlgo
-    /** play the film between moments instead of cutting to the next one.
-     *  Safe under accumulation: an unreleased element stays clipped, so the
-     *  film cannot show one early and there is nothing to rewind. */
-    playBetween?: boolean
-    /** how the arrivals resolve — the cascade, with its tuned defaults */
-    reveal?: RevealOptions
-    /** EXPERIMENTAL, off by default. Suppress everything and release each
-     *  element at its own moment, so the cascade is its only appearance.
-     *  It reads well when it works, but it means owning visibility for
-     *  elements the scene owns, and real scenes break it in a dozen ways:
-     *  full-bleed grounds become curtains, children of transparent parents get
-     *  mis-dated, elements that leave and return get stranded. Ring-only has
-     *  none of that surface. */
-    accumulate?: boolean
-    /** Minimum seconds between creation moments. This matters far more under
-     *  accumulation than it looks: house style staggers lines ~0.2s apart, so
-     *  nearly every element earns its own appearance time, and one-at-a-time
-     *  release leaves the canvas empty for minutes. Folding a beat's worth of
-     *  arrivals into one moment is what makes the scene visibly fill. */
-    minGap?: number
-  } = {}
-): Promise<void> {
-  const w = window as StageWindow
-  if (!w.__renderAt || reduced()) return
-  stopWatching()
-  clearWorking()
-
-  const token = ++montageToken
-  await settleLayout()
-  if (token !== montageToken) return
-  const hold = opts.hold ?? 850
-  const settle = opts.settle ?? 0.45
-  const maxStops = opts.maxStops ?? 999
-
-  const stops = findMoments(opts.algo ?? 'changes', opts.selectors, opts.step)
-  if (!stops.length) return
-  const pool = collect(opts.selectors)
-
-  // Nothing may be seen before its own moment. Hide EVERYTHING that will ever
-  // appear, once, up front — then release each element at its creation moment
-  // and leave it released. The scene accumulates in front of the viewer, and
-  // an element's only possible appearance is its cascade.
-  //
-  // Safe here in a way it never was during playback: we are seeking between
-  // frozen frames, so suppression is not racing an entrance.
-  if (opts.accumulate !== false) hideUntilRevealed(pool)
-
-  let at = 0
-  for (const stop of stops) {
-    if (!(await waitWhilePaused(token))) return
-    if (token !== montageToken) return
-
-    const target = stop.at + settle
-    if (opts.playBetween && target > at) {
-      // Roll the film to the next moment at real speed. Unreleased elements are
-      // still clipped, so nothing arrives ahead of its own cascade.
-      let prevMs = performance.now()
-      while (at < target) {
-        if (!(await waitWhilePaused(token))) return
-        await raf()
-        if (token !== montageToken) return
-        const nowMs = performance.now()
-        at = Math.min(target, at + Math.min(0.05, (nowMs - prevMs) / 1000))
-        prevMs = nowMs
-        w.__renderAt(at)
-      }
-    }
-    at = target
-    // Park just past the LAST arrival so every element is settled — a ring
-    // measured mid-entrance sits on a box the element has already left.
-    w.__renderAt(target)
-    await raf()
-    if (token !== montageToken) return
-
-    // No awaited frame between the seek and the reveal: one task, so the
-    // browser never paints the un-clipped state in between.
-    const run = revealElements(stop.els, {
-      ...opts.reveal,
-      preHidden: opts.accumulate !== false,
-    })
-    await sleep(Math.max(hold, run + 260))
-  }
-  // Whatever is left holding a clip — an element whose stop was never reached,
-  // or one filtered out of its own cascade — is handed back here.
-  if (token === montageToken) clearWorking()
-}
-
-/**
- * Is this element scenery rather than a component?
- *
- * Full-bleed layers — chapter grounds, colour fields, `absolute inset-0`
- * backdrops — cover the frame, so clipping one is not a reveal, it is a
- * curtain: the screen goes black and the wipe reads as the page filling from
- * the top. They are never what the viewer is waiting to see arrive, so they
- * stay visible and their CHILDREN do the arriving.
- */
-const isScenery = (el: HTMLElement): boolean => {
-  const b = el.getBoundingClientRect()
-  const stage = innerWidth * innerHeight
-  return stage > 0 && b.width * b.height >= stage * 0.85
-}
-
-/** Clip elements out of sight without touching opacity, and remember what they
- *  carried so every one can be handed back. */
-export function hideUntilRevealed(list: Iterable<HTMLElement>): void {
-  for (const el of list) {
-    if (isScenery(el)) continue
-    remember(el, ['clipPath'])
-    el.style.clipPath = 'inset(0 0 100% 0)'
-  }
-}
-
-/* ── finding the moments: four algorithms ────────────────────────────────── */
-
-export type MomentAlgo = 'appear' | 'beats' | 'changes' | 'structure'
-
-type Timelineish = {
-  getChildren?: (nested?: boolean, tweens?: boolean, timelines?: boolean) => Array<{
-    startTime: () => number
-    duration: () => number
-    targets?: () => unknown[]
-  }>
-}
-
-/** Signature of what is drawn right now, per participating element. */
-const frameState = (pool: HTMLElement[]): Map<HTMLElement, string> => {
-  const m = new Map<HTMLElement, string>()
-  for (const el of pool) {
-    if (!onScreen(el)) continue
-    const b = el.getBoundingClientRect()
-    m.set(el, `${Math.round(b.left / 8)},${Math.round(b.top / 8)},${Math.round(b.width / 8)},${Math.round(b.height / 8)}`)
-  }
-  return m
-}
-
-/**
- * A child can never arrive before its own parent.
- *
- * onScreen is deliberately generous — it does not walk ancestors, because being
- * strict drops a whole component whenever its container is mid-fade at a
- * sampled instant. The cost of that generosity is mis-dated children: opacity
- * is not inherited as a computed value, so a child of an autoAlpha:0 parent
- * reports its own opacity of 1 and looks visible while being invisible.
- *
- * Clamping afterwards fixes it without losing anything — a pass over the moment
- * list rather than a DOM walk during the scan. Shallow to deep, so a chain of
- * ancestors settles in one sweep.
- */
-function clampToAncestors(times: Map<HTMLElement, number>, participates: (n: Element) => boolean): void {
-  const depth = new Map<HTMLElement, number>()
-  for (const el of times.keys()) depth.set(el, depthOf(el, participates))
-  const shallowFirst = [...times.keys()].sort((a, b) => (depth.get(a) ?? 0) - (depth.get(b) ?? 0))
-  for (const el of shallowFirst) {
-    let p = el.parentElement
-    while (p && !times.has(p as HTMLElement)) p = p.parentElement
-    if (!p) continue
-    const parentAt = times.get(p as HTMLElement)
-    const own = times.get(el)
-    if (parentAt != null && own != null && own < parentAt) times.set(el, parentAt)
-  }
-}
-
-/** 1 · APPEAR — first time each element is drawn. Cheap and predictable, but it
- *  only ever fires once per element: a container that exists from t=0 collapses
- *  into the opening moment and its real section never gets one. */
-function byAppearance(pool: HTMLElement[], step: number): Stop[] {
-  const w = window as StageWindow
-  const dur = Number(w.__duration) || 0
-  const found = new Map<HTMLElement, number>()
-  const pending = new Set(pool)
-  for (let t = 0; t <= dur && pending.size; t += step) {
-    w.__renderAt!(t)
-    for (const el of [...pending]) if (onScreen(el)) { found.set(el, t); pending.delete(el) }
-  }
-  clampToAncestors(found, (n) => n.hasAttribute?.('data-reveal') || hasHook(n))
-  return groupStops(found, { bucket: 0.2, maxStops: 999 })
-}
-
-/** 2 · BEATS — read the author's structure straight off the timeline. Every
- *  tween knows when it starts and what it targets, so clusters of tween starts
- *  ARE the beats. No seeking, nothing to miss, and stops land where the
- *  direction meant them to. */
-function byBeats(pool: HTMLElement[], gap = 0.35): Stop[] {
-  const tl = (window as unknown as { __timeline?: Timelineish }).__timeline
-  const kids = tl?.getChildren?.(false, true, true) ?? []
-  const inPool = new Set(pool)
-  const events: Array<{ at: number; end: number; els: HTMLElement[] }> = []
-  for (const k of kids) {
-    const els = (k.targets?.() ?? []).filter(
-      (n): n is HTMLElement => n instanceof HTMLElement && inPool.has(n)
-    )
-    if (!els.length) continue
-    const at = k.startTime()
-    events.push({ at, end: at + (k.duration?.() ?? 0), els })
-  }
-  events.sort((a, b) => a.at - b.at)
-
-  const stops: Stop[] = []
-  for (const e of events) {
-    const prev = stops[stops.length - 1]
-    if (prev && e.at - prev.from < gap) {
-      prev.at = Math.max(prev.at, e.end)
-      prev.els.push(...e.els)
-    } else {
-      stops.push({ at: e.end, from: e.at, els: [...e.els] })
-    }
-  }
-  for (const s of stops) s.els = [...new Set(s.els)]
-  return stops
-}
-
-/** 3 · CHANGES — every transition into view, not just the first. Catches an
- *  element that leaves and returns, which APPEAR silently drops. */
-function byChanges(pool: HTMLElement[], step: number): Stop[] {
-  const w = window as StageWindow
-  const dur = Number(w.__duration) || 0
-  const seen = new Map<HTMLElement, boolean>()
-  const hits: Array<[HTMLElement, number]> = []
-  for (let t = 0; t <= dur; t += step) {
-    w.__renderAt!(t)
-    for (const el of pool) {
-      const now = onScreen(el)
-      if (now && !seen.get(el)) hits.push([el, t])
-      seen.set(el, now)
-    }
-  }
-  // Clamp on FIRST entry per element, then re-apply the shift to its later
-  // entries, so a re-appearance stays relative to the corrected first one.
-  const first = new Map<HTMLElement, number>()
-  for (const [el, t] of hits) if (!first.has(el)) first.set(el, t)
-  const before = new Map(first)
-  clampToAncestors(first, (n) => n.hasAttribute?.('data-reveal') || hasHook(n))
-  const shift = new Map<HTMLElement, number>()
-  for (const [el, t] of first) shift.set(el, t - (before.get(el) ?? t))
-
-  const byBucket = new Map<string, HTMLElement[]>()
-  for (const [el, t] of hits) {
-    const key = (Math.round((t + (shift.get(el) ?? 0)) / 0.2) * 0.2).toFixed(2)
-    const at = byBucket.get(key)
-    if (at) at.push(el)
-    else byBucket.set(key, [el])
-  }
-  return [...byBucket.entries()]
-    .map(([k, els]) => ({ at: Number(k), from: Number(k), els: [...new Set(els)] }))
-    .sort((a, b) => a.at - b.at)
-}
-
-/** 4 · STRUCTURE — diff the whole frame and cut where it changes sharply. Finds
- *  SECTIONS rather than elements: a beat boundary is where a lot of the frame
- *  turns over at once. */
-function byStructure(pool: HTMLElement[], step: number, threshold = 0.22): Stop[] {
-  const w = window as StageWindow
-  const dur = Number(w.__duration) || 0
-  let prev = new Map<HTMLElement, string>()
-  const stops: Stop[] = []
-  for (let t = 0; t <= dur; t += step) {
-    w.__renderAt!(t)
-    const now = frameState(pool)
-    let changed: HTMLElement[] = []
-    for (const [el, sig] of now) if (prev.get(el) !== sig) changed.push(el)
-    for (const el of prev.keys()) if (!now.has(el)) changed.push(el)
-    const churn = changed.length / Math.max(8, now.size || prev.size || 1)
-    if (churn >= threshold) {
-      const arriving = changed.filter((el) => now.has(el))
-      if (arriving.length) stops.push({ at: t, from: t, els: arriving })
-    }
-    prev = now
-  }
-  // collapse runs of consecutive churny frames into one section
-  const merged: Stop[] = []
-  for (const s of stops) {
-    const p = merged[merged.length - 1]
-    if (p && s.at - p.at < 0.5) { p.at = s.at; p.els = [...new Set([...p.els, ...s.els])] }
-    else merged.push(s)
-  }
-  return merged
-}
-
-export function findMoments(algo: MomentAlgo, selectors?: string[], step = 1 / 12): Stop[] {
-  const w = window as StageWindow
-  const pool = collect(selectors)
-  if (!pool.length || !w.__renderAt) return []
-  const back = Number((window as unknown as { __timeline?: { time(): number } }).__timeline?.time() ?? 0)
-  let stops: Stop[]
-  switch (algo) {
-    case 'beats': stops = byBeats(pool); break
-    case 'changes': stops = byChanges(pool, step); break
-    case 'structure': stops = byStructure(pool, step); break
-    default: stops = byAppearance(pool, step)
-  }
-  w.__renderAt(back)
-  ;(window as unknown as { __moments?: unknown }).__moments = {
-    algo, stops: stops.length, elements: pool.length,
-    span: stops.length ? [stops[0].at, stops[stops.length - 1].at] : [0, 0],
-  }
-  return stops
-}
-
-/* ── the revision digest ─────────────────────────────────────────────────── */
-
-export type DigestEntry = {
-  /** Stable across revisions where possible: the editor's path id, else a DOM
-   *  path. Path ids survive edits in place but NOT a wholesale component
-   *  rewrite, which is why every entry also carries the fallback-match fields
-   *  below (tag / text / rect) — see matching notes in the Studio consumer. */
-  key: string
-  /** Fallback identity, in descending reliability. */
-  tag: string
-  /** OWN text only. textContent includes descendants, so a change in one leaf
-   *  would otherwise look like a change in every ancestor above it. */
-  text: string
-  /** EVERY non-studio data-* attribute, as `name=value`, SORTED.
-   *
-   *  For agent-authored drafts this is the real primary key, not a fallback:
-   *  such scenes carry no studio ids at all, and semantic hooks (data-card,
-   *  data-sync-button) survive a wholesale component rewrite because the
-   *  direction.ts targets them — while the DOM path underneath changes
-   *  completely. Recommended match order: studioObjectId -> hooks ->
-   *  (tag + normalized text + rect at tolerance) -> path. Path LAST.
-   *
-   *  Sorted deliberately, and ALL of them rather than the first: "first"
-   *  depends on attribute order, so reordering attributes in a template would
-   *  silently rekey every element. Do not change this to a single value. */
-  hooks: string[]
-  /** First time this is drawn, clamped so a child never precedes its parent.
-   *
-   *  null means UNWITNESSED: the element exists in the markup but the film
-   *  never draws it at any sampled instant. Same concept as the text census's
-   *  "unwitnessed line" (copy the camera never shows), one level down — so we
-   *  use the same word: census says unwitnessed LINE, digest says unwitnessed
-   *  ELEMENT. It is a finding worth surfacing to authors, not an error. */
-  appears: number | null
-  /** Where it sits once it has arrived, in stage coordinates. */
-  rect: { x: number; y: number; w: number; h: number } | null
-  depth: number
-  parent: string | null
-}
-
-export type SceneDigest = {
-  /** Which revision this describes, so the reply is self-labelling and a parent
-   *  holding two hot-swapped bundles cannot mis-file its cache. null when the
-   *  bundle was built without the define (local scenes, older previews). */
-  sourceRevision: number | null
-  duration: number
-  /** wall-clock ms the scan took, so the Studio can decide whether to cache */
-  scanMs: number
-  entries: DigestEntry[]
-}
-
-/** Elements that render nothing but can still carry a data-* attribute. A
- *  bundled-font <style> block would otherwise arrive as an "element" whose
- *  text is several hundred lines of CSS. */
-const NON_VISUAL = new Set(['style', 'script', 'link', 'meta', 'title', 'head', 'base'])
-
-const ownText = (el: HTMLElement): string =>
-  [...el.childNodes]
-    .filter((n) => n.nodeType === 3)
-    .map((n) => n.nodeValue ?? '')
-    .join('')
-    .replace(/\s+/g, ' ')
-    .trim()
-    // this is a matching fingerprint, not content — long is useless and costly
-    .slice(0, 200)
-
-const domPath = (el: HTMLElement): string => {
-  const parts: string[] = []
-  for (let n: HTMLElement | null = el; n && n !== document.body; n = n.parentElement) {
-    const p = n.parentElement
-    parts.unshift(p ? String([...p.children].indexOf(n)) : '0')
-  }
-  return parts.join('.')
-}
-
-const keyOf = (el: HTMLElement): string =>
-  el.dataset.studioObjectId || el.dataset.studioTextId || `path:${domPath(el)}`
-
-const hooksOf = (el: HTMLElement): string[] => {
-  const out: string[] = []
-  for (const k in el.dataset) {
-    if (k === 'reveal' || k.startsWith('studio')) continue
-    out.push(`${k}=${el.dataset[k]}`)
-  }
-  return out.sort()
-}
-
-/** Baked in at build time by buildPreview. Undefined for local scenes. */
-const bundleRevision = (): number | null => {
-  const raw = (import.meta as unknown as { env?: Record<string, string> }).env?.VITE_SOURCE_REVISION
-  const n = Number(raw)
-  return Number.isFinite(n) && raw !== '' && raw != null ? n : null
-}
-
-/**
- * Everything the Studio needs to diff one revision against another.
- *
- * Computed by SEEKING rather than by watching playback: the engine is a pure
- * function of timeline position, so this is exact rather than sampled-and-hoped,
- * and it runs inside the bundle because a cross-origin sandboxed preview cannot
- * be read from the parent at all.
- *
- * Cost is roughly (duration × 1/step) seeks with a shrinking element pool. The
- * result is immutable for a given revision, so the caller should cache it by
- * (draftId, revision) and never compute it twice.
- */
-export function digestScene(opts: { selectors?: string[]; step?: number } = {}): SceneDigest {
-  const t0 = performance.now()
-  const w = window as StageWindow
-  const step = opts.step ?? 1 / 12
-  const duration = Number(w.__duration) || 0
-  const pool = collect(opts.selectors).filter(
-    (el) => !NON_VISUAL.has(el.tagName.toLowerCase()) && document.body.contains(el)
-  )
-  const participates = (n: Element) => n.hasAttribute?.('data-reveal') || hasHook(n)
-
-  const appears = new Map<HTMLElement, number>()
-  const rects = new Map<HTMLElement, { x: number; y: number; w: number; h: number }>()
-
-  if (duration && w.__renderAt) {
-    const back = Number((window as unknown as { __timeline?: { time(): number } }).__timeline?.time() ?? 0)
-    const pending = new Set(pool)
-    for (let t = 0; t <= duration && pending.size; t += step) {
-      w.__renderAt(t)
-      for (const el of [...pending]) {
-        if (!onScreen(el)) continue
-        const b = el.getBoundingClientRect()
-        appears.set(el, t)
-        rects.set(el, { x: b.left, y: b.top, w: b.width, h: b.height })
-        pending.delete(el)
-      }
-    }
-    w.__renderAt(back)
-    clampToAncestors(appears, participates)
-  }
-
-  const keys = new Map<HTMLElement, string>()
-  for (const el of pool) keys.set(el, keyOf(el))
-
-  const entries: DigestEntry[] = pool.map((el) => {
-    let p = el.parentElement
-    while (p && !keys.has(p as HTMLElement)) p = p.parentElement
-    return {
-      key: keys.get(el)!,
-      tag: el.tagName.toLowerCase(),
-      text: ownText(el),
-      hooks: hooksOf(el),
-      appears: appears.has(el) ? appears.get(el)! : null,
-      rect: rects.get(el) ?? null,
-      depth: depthOf(el, participates),
-      parent: p ? keys.get(p as HTMLElement)! : null,
-    }
-  })
-
-  return { sourceRevision: bundleRevision(), duration, scanMs: Math.round(performance.now() - t0), entries }
-}
-
-export function stopMontage(): void {
-  montageToken += 1
-  montagePaused = false
-  // A montage suppresses the whole scene, so abandoning one without restoring
-  // would leave it blank.
-  clearWorking()
-}
-
-const raf = () => new Promise<void>((r) => requestAnimationFrame(() => r()))
-const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
-
-/**
- * Fold raw appearance times into a handful of creation MOMENTS.
- *
- * `bucket` treats near-simultaneous arrivals as one event; `minGap` then keeps
- * moments far enough apart that the film has room to play between them —
- * without it a dense scene produces a hundred stops and reads as a stutter
- * rather than as building.
- */
-type Stop = {
-  /** the LAST appearance in the group — stopping here means every element in
-   *  it is genuinely on screen, which stopping at the first would not */
-  at: number
-  /** the FIRST appearance — when suppression has to begin */
-  from: number
-  els: HTMLElement[]
-}
-
-function groupStops(
-  found: Map<HTMLElement, number>,
-  opts: { bucket?: number; minGap?: number; maxStops?: number } = {}
-): Stop[] {
-  const bucket = opts.bucket ?? 0.15
-  const minGap = opts.minGap ?? 0
-  const maxStops = opts.maxStops ?? 999
-
-  const byTime = new Map<number, HTMLElement[]>()
-  for (const [el, t] of found) {
-    const key = Math.round(t / bucket) * bucket
-    const at = byTime.get(key)
-    if (at) at.push(el)
-    else byTime.set(key, [el])
-  }
-
-  let stops: Stop[] = [...byTime.entries()]
-    .sort((a, b) => a[0] - b[0])
-    .map(([t, els]) => ({ at: t, from: t, els }))
-
-  const fold = (a: Stop, b: Stop): Stop => ({
-    at: Math.max(a.at, b.at),
-    from: Math.min(a.from, b.from),
-    els: [...a.els, ...b.els],
-  })
-
-  if (minGap > 0) {
-    const kept: Stop[] = []
-    for (const s of stops) {
-      const prev = kept[kept.length - 1]
-      if (prev && s.at - prev.at < minGap) kept[kept.length - 1] = fold(prev, s)
-      else kept.push(s)
-    }
-    stops = kept
-  }
-
-  // Merge neighbours rather than truncating, so coverage stays whole-film.
-  while (stops.length > maxStops) {
-    const merged: Stop[] = []
-    for (let i = 0; i < stops.length; i += 2) {
-      const a = stops[i]
-      const b = stops[i + 1]
-      merged.push(b ? fold(a, b) : a)
-    }
-    stops = merged
-  }
-  return stops
-}
-
-/**
- * Play the film for real, and freeze only where something is created.
- *
- * Between moments this is ordinary playback — the scene's own choreography,
- * at speed. At a moment it stops, lets the arrivals cascade in, then picks up
- * from where it paused. That's the difference from the montage, which skips
- * everything between; here you still see the film, you just get a beat to
- * watch each piece land.
- *
- * The playhead is driven by renderAt from our own clock rather than by the
- * timeline's player, because a freeze has to land on an exact frame. The scene
- * stays a pure function of the time we hand it.
- */
-export async function playBuild(
-  opts: {
-    selectors?: string[]
-    /** minimum seconds of playback between freezes */
-    minGap?: number
-    /** minimum ms to hold a freeze */
-    hold?: number
-    /** seconds past the appearance to freeze on */
-    settle?: number
-    maxStops?: number
-    step?: number
-    loop?: boolean
-    reveal?: RevealOptions
-  } = {}
-): Promise<void> {
-  const w = window as StageWindow & { __pause?: () => void }
-  if (!w.__renderAt || reduced()) return
-  stopWatching()
-  clearWorking()
-
-  const token = ++montageToken
-  await settleLayout()
-  if (token !== montageToken) return
-  const dur = Number(w.__duration) || 0
-  if (!dur) return
-
-  const settle = opts.settle ?? 0.45
-  const hold = opts.hold ?? 700
-  const stops = groupStops(scanAppearances(opts.selectors, opts.step), {
-    minGap: opts.minGap ?? 0.9,
-    maxStops: opts.maxStops ?? 16,
-  })
-
-  w.__pause?.() // only our clock drives the playhead from here
-
-  do {
-    let t = 0
-    let i = 0
-    let prev = performance.now()
-    clearWorking()
-    w.__renderAt(0)
-
-    while (t < dur) {
-      if (!(await waitWhilePaused(token))) return
-      await raf()
-      if (token !== montageToken) return
-
-      const now = performance.now()
-      // Cap the step so a stalled tab — or a pause — doesn't jump the playhead
-      // past a creation moment on resume.
-      t += Math.min(0.05, (now - prev) / 1000)
-      prev = now
-
-      const next = stops[i]
-      // Stop past the LAST arrival in the group, so every element in it is
-      // genuinely on screen when we mark it.
-      const target = next ? Math.min(dur, next.at + settle) : Infinity
-
-      if (next && t >= target) {
-        t = target
-        w.__renderAt(t)
-        await raf()
-        if (token !== montageToken) return
-        // Ring only. The scene already animated these in — the freeze is what
-        // gives you time to see them, and re-animating would both duplicate
-        // the entrance and require hiding elements we do not own.
-        for (const el of next.els) stamp(el, hold)
-        await sleep(hold + 160)
-        if (token !== montageToken) return
-        i += 1
-        prev = performance.now()
-        continue
-      }
-      w.__renderAt(t)
-    }
-  } while (opts.loop && token === montageToken)
-
-  if (token === montageToken) clearWorking()
-}
-
-/** Elements the direction could target — the set a reveal participates on. */
-function collect(selectors?: string[]): HTMLElement[] {
-  if (selectors?.length) {
-    const out: HTMLElement[] = []
-    for (const sel of selectors) {
-      try {
-        out.push(...document.querySelectorAll<HTMLElement>(sel))
-      } catch {
-        /* ignore a malformed selector */
-      }
-    }
-    return out
-  }
-  return [...document.querySelectorAll<HTMLElement>('*')].filter(hasHook)
-}
-
-// The local studio runs the stage same-origin and talks to it through direct
-// window access rather than the bridge (which stays dormant without a nonce),
-// so expose the same surface there. Cloud previews keep using the bridge.
-if (typeof window !== 'undefined') {
-  ;(window as unknown as { __workingViews?: unknown }).__workingViews = {
-    montage, stopMontage, setMontagePaused, playBuild, reveal, revealElements,
-    setWorking, watchAppearances, stopWatching, findMoments, clearWorking,
-    digestScene,
-    clearRings,
-  }
-}
-
-/** Remove every trace, including the overlay node itself. */
-export function uninstallWorkingViews(): void {
-  stopMontage()
-  stopWatching()
-  clearWorking()
-  layer?.remove()
-  layer = null
-}
-
-
-/* ------------------------------------------------------------------------- *
- * DRAFT-SIDE INSTALLER — appended by .build-draft-reveal.mjs
- *
- * Present only in the draft-shipped copy of this engine. The engine-side copy
- * is driven by bridge.ts instead; this block is what lets the same code answer
- * the Studio from inside a preview bundle built by the DEPLOYED engine.
- * ------------------------------------------------------------------------- */
-
-declare global {
-  interface Window {
-    __stageBridgeVerbs?: Set<string>
-    __revealDraftInstalled?: boolean
-  }
-}
-
-{
-  const w = window as Window
-
-  // Guard 1 — the engine deploy has landed and bridge.ts owns these verbs now.
-  // Standing down keeps a draft written before the deploy from double-handling
-  // every command for the rest of its life.
-  const engineOwnsVerbs = w.__stageBridgeVerbs?.has('stage-reveal') === true
-
-  // Guard 2 — self. A double import (two kits both pulling this in) must not
-  // install two listeners; the second would run every reveal twice.
-  const alreadyInstalled = w.__revealDraftInstalled === true
-
-  if (!engineOwnsVerbs && !alreadyInstalled) {
-    w.__revealDraftInstalled = true
-
-    // Same derivation as bridge.ts:46. Dormant without a nonce, which is what
-    // keeps the local same-origin studio on direct window access.
-    const nonce = new URLSearchParams(window.location.hash.slice(1)).get('nonce')
-
-    if (nonce) {
-      window.addEventListener('message', (event: MessageEvent<Record<string, any>>) => {
-        const data = event.data
-        if (!data || typeof data !== 'object' || data.nonce !== nonce) return
-
-        switch (data.type) {
-          case 'stage-reveal':
-            reveal(data.root ? document.querySelector(data.root) : document.body, data.options)
-            break
-          case 'stage-working':
-            // An empty list is how the Studio says "finished working here".
-            setWorking(data.selectors ?? [])
-            break
-          case 'stage-watch':
-            if (data.on) watchAppearances({ selectors: data.selectors })
-            else stopWatching()
-            break
-          case 'stage-montage':
-            if (data.on) void montage({ selectors: data.selectors, hold: data.hold, algo: data.algo,
-                                        playBetween: data.playBetween, reveal: data.reveal })
-            else stopMontage()
-            break
-          case 'stage-build':
-            if (data.on) void playBuild({ selectors: data.selectors, loop: data.loop })
-            else stopMontage()
-            break
-          case 'stage-montage-pause':
-            setMontagePaused(data.on)
-            break
-          case 'stage-clear':
-            // Must be handled BEFORE any seek: a reveal restores the values it
-            // captured when it started, so one still running across a seek
-            // writes the old moment's state onto the new frame.
-            clearWorking()
-            break
-          case 'stage-digest': {
-            // Answered on the same channel, token echoed, so a parent awaiting
-            // two revisions can tell the replies apart.
-            const d = digestScene({ selectors: data.selectors, step: data.step })
-            window.parent.postMessage(
-              { type: 'stage-digest-result', nonce, token: data.token ?? null, ...d }, '*')
-            break
-          }
-          default:
-            break
-        }
-      })
-    }
-  }
-}
-
-export {}