@impractical-ai/motion 0.1.5 → 0.1.7

package/assets/kits/reveal.ts

@@ -0,0 +1,1364 @@
+// 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 {}