@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/tier1Export.ts

@@ -0,0 +1,641 @@
+// Tier-1 export for the shot stage (the browser-side sibling of the motion
+// harness's stageExport.ts, a fifth of its size because a shot is ONE canvas):
+// per frame, arm a snapshot, commit the frame on the live ShotRuntime, capture
+// synchronously from its onPresented call stack, and feed the encode worker.
+// whose frameDone ack IS the encoder's backpressure, so memory stays bounded
+// at ~one frame in flight.
+//
+// There is no SnapDOM, no compositing pass and no per-layer split here:
+// ShotRuntime draws every layer kind, text included, onto one WebGL canvas.
+// The default framebuffer is deliberately UNPRESERVED for playback speed, so
+// capture must begin in the same task as the draw, before Chromium presents
+// and retires it. A later canvas read can be a valid-sized all-black image.
+//
+// The loop is a plain awaited while, never rAF. A hidden tab still stops the
+// stage itself (rAF, ResizeObserver and WebGL's rAF-polled program links all
+// halt), so each frame's deadline counts visible time only and the export
+// pauses rather than fails while the tab is behind another. It does not poll
+// either: ClockDriver
+// calls onPresented only after the draw and only when non-draw readiness claims
+// are clear. The exact frame, marker and backing size are checked in that same
+// callback before the armed snapshot is invoked.
+import { CAPABILITY_PROBE_TIMED_OUT, converse, gifFrameStride, gifRate } from "@dailies-studio/shot/tier1";
+import type { Mp4Encoding, Tier1Capability, WorkerLike } from "@dailies-studio/shot/tier1";
+import type { Rational } from "@dailies-studio/engine";
+
+/** What the exporter needs from the stage. Everything here must be honest
+ *  about the CURRENT stage. The exporter never touches stage internals, and
+ *  the tests fake this seam whole. */
+export interface ShotExportHost {
+  /** The export framing's numbers, or null before a document is loaded. */
+  composition(): { width: number; height: number; fps: Rational } | null;
+  /** Frames the requested scope runs, resolved against the CURRENT document
+   *  (the slice the runtime will render), or null for an unknown scene id. */
+  scopeFrames(sceneId: string | undefined): number | null;
+  /** The export-local frames on which a scene begins (always including 0).
+   *  An export never warms the next scene, so each of these is a cold mount:
+   *  models to parse, rasters to draw, programs to link. */
+  sceneStartFrames(sceneId: string | undefined): readonly number[];
+  /** Flip the stage into export framing for `sceneId` (undefined = whole
+   *  timeline) at an uncovered sentinel frame. Remembers what to restore; the
+   *  first armed seek to frame 0 is therefore always a real presentation. */
+  begin(sceneId: string | undefined): void;
+  /** Commit `frame` on the export stage. */
+  seek(frame: number): void;
+  /** Restore the author's framing, playhead and any deferred chrome pushes. */
+  end(): void;
+  /** The live GL canvas, or null before the runtime mounted. */
+  canvas(): HTMLCanvasElement | null;
+  /** True when the stage's LAST COMMIT was the export framing at `frame`.
+   *  the DOM marker StageApp stamps in the same commit that claims the draw
+   *  latch, which is what makes the in-presentation capture race-free. */
+  frameCommitted(frame: number): boolean;
+  /** What the outstanding readiness claims are waiting on, for the timeout
+   *  message: each label with its claim's own description. */
+  waitingOn(): readonly string[];
+  /**
+   * Arm one exact in-draw snapshot before `seek(frame)`.
+   *
+   * The stage resolves it only from ShotRuntime's matching onPresented call,
+   * after advance() drew and while the unpreserved default framebuffer is
+   * still readable. It also requires export framing, the matching DOM commit
+   * marker, and the exact composition-sized backing store. A second arm is a
+   * refusal rather than two consumers racing for one framebuffer.
+   */
+  armCapture(
+    frame: number,
+    size: { width: number; height: number },
+    snapshot: (canvas: HTMLCanvasElement) => Promise<ImageBitmap>,
+  ): Promise<ImageBitmap>;
+  /** Reject the currently armed capture, if any. */
+  cancelCapture(error: Error): void;
+}
+
+export interface ShotExportDeps {
+  createWorker(): WorkerLike;
+  toBitmap(canvas: HTMLCanvasElement): Promise<ImageBitmap>;
+  /** Run `fn` after `ms`, returning a cancel. The only timer this lane needs:
+   *  one refusal deadline per armed frame. */
+  after(ms: number, fn: () => void): () => void;
+  /** A monotonic clock, for charging a frame's deadline visible time only. */
+  now(): number;
+  /** Whether the page is hidden (another tab in front, minimised). */
+  hidden(): boolean;
+  /** Subscribe to visibility changes; returns the unsubscribe. */
+  onVisibilityChange(listener: () => void): () => void;
+  /** An encode worker failed (its `error` event): recorded beside the
+   *  export's own refusal for the stage's health (bridge v35). */
+  onWorkerError?(message: string): void;
+  /** Scale a captured frame to `width`x`height` and encode it as `type`. The
+   *  caller closes the bitmap. */
+  encodeStill(
+    bitmap: ImageBitmap,
+    width: number,
+    height: number,
+    type: string,
+    quality: number | undefined,
+  ): Promise<Blob>;
+}
+
+export interface ShotExportMovieOptions {
+  /** Absent = mp4. A GIF carries no audio and takes no bitrate or quantizer. */
+  format?: "mp4" | "gif" | undefined;
+  sceneId?: string | undefined;
+  /** Master frames of the whole timeline to export (the work area). Never
+   *  with `sceneId`. Absent = the whole scope. */
+  window?: { start: number; frames: number } | undefined;
+  videoBitrate?: number | undefined;
+  /** The fixed H.264 QP the worker encodes at where a hardware encoder
+   *  honours one (`MovieJob.quantizer`). */
+  quantizer?: number | undefined;
+  audio?: { sampleRate: number; channels: Float32Array[] } | undefined;
+  onProgress?: ((framesDone: number, totalFrames: number) => void) | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+/** One exact still of the whole timeline, delivered at `width`x`height`. */
+export interface ShotStillOptions {
+  /** A MASTER frame of the whole timeline. */
+  frame: number;
+  width: number;
+  height: number;
+  type: "image/png" | "image/jpeg" | "image/webp";
+  /** Lossy encoders only. Absent = the browser's default. */
+  quality?: number | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+export interface ShotStageExporter {
+  capability(): Promise<Tier1Capability>;
+  exportMovie(
+    opts: ShotExportMovieOptions,
+  ): Promise<{ blob: Blob; extension: string; audioSkippedReason?: string; encoding?: Mp4Encoding }>;
+  /** The same export framing and in-draw capture as one movie frame, for the
+   *  dashboard poster and the storyboard's "frame from shot". Rejects with the
+   *  reason, and restores the stage on every path. */
+  captureStill(opts: ShotStillOptions): Promise<Blob>;
+}
+
+/** The first frame, and the first frame of every later scene, may re-raster
+ *  every text layer at the export scale, parse models, link programs, decode
+ *  images and settle video seeks (on frame 0, on top of the framing swap).
+ *  This uses the still lane's cold-start budget (settleShotStill's 60 s), not a
+ *  per-frame one. */
+const FIRST_FRAME_TIMEOUT_MS = 60_000;
+const FRAME_TIMEOUT_MS = 20_000;
+const CAPABILITY_TIMEOUT_MS = 20_000;
+/** One inactivity window for worker startup, one encoded frame, or finalize.
+ *  The worker may encode a long audio mix during startup and a software-backed
+ *  4K frame can be legitimately slow, so this is deliberately much larger
+ *  than the presentation deadline. It is still finite: a codec promise that
+ *  never settles must restore the editor rather than own it forever. A GIF's
+ *  finish encodes the whole film and reports each frame ("finishing"), and
+ *  every report starts the window again, so a long GIF is not refused for
+ *  being long. */
+const WORKER_OPERATION_TIMEOUT_MS = 10 * 60_000;
+
+function defaultDeps(): ShotExportDeps {
+  return {
+    createWorker: () =>
+      new Worker(new URL("./exportWorker.ts", import.meta.url), {
+        type: "module",
+      }) as unknown as WorkerLike,
+    toBitmap: (canvas) => createImageBitmap(canvas),
+    after: (ms, fn) => {
+      const timer = setTimeout(fn, ms);
+      return () => clearTimeout(timer);
+    },
+    now: () => performance.now(),
+    // "hidden" only: jsdom and prerendered pages report other states, and a
+    // deadline that never ran would be a hang rather than a pause.
+    hidden: () => typeof document !== "undefined" && document.visibilityState === "hidden",
+    onVisibilityChange: (listener) => {
+      if (typeof document === "undefined") return () => undefined;
+      document.addEventListener("visibilitychange", listener);
+      return () => document.removeEventListener("visibilitychange", listener);
+    },
+    encodeStill: async (bitmap, width, height, type, quality) => {
+      const canvas = new OffscreenCanvas(width, height);
+      const ctx = canvas.getContext("2d");
+      if (ctx === null) throw new Error("a 2d canvas is unavailable, so the still could not be encoded");
+      // A poster is a third of the design width: the default low-quality
+      // (bilinear) filter aliases at that ratio.
+      ctx.imageSmoothingQuality = "high";
+      ctx.drawImage(bitmap, 0, 0, width, height);
+      return canvas.convertToBlob(quality === undefined ? { type } : { type, quality });
+    },
+  };
+}
+
+/** A channel's exact bytes as a standalone ArrayBuffer for the transfer
+ *  list. The mix's Float32Array may be a view into a larger buffer.
+ *
+ *  The mix is made in the CHROME's realm and this runs in the stage iframe's,
+ *  so `instanceof ArrayBuffer` (this realm's constructor) was always false and
+ *  every export copied its whole mix first. The brand check works across
+ *  realms, and still refuses a SharedArrayBuffer, which cannot be transferred.
+ *  The mix is made fresh for each export and not read after it is handed
+ *  over, so transferring it (which detaches it in the chrome) is safe. */
+export function transferableChannel(ch: Float32Array): ArrayBuffer {
+  if (
+    ch.byteOffset === 0 &&
+    ch.byteLength === ch.buffer.byteLength &&
+    Object.prototype.toString.call(ch.buffer) === "[object ArrayBuffer]"
+  ) {
+    return ch.buffer as ArrayBuffer;
+  }
+  return ch.slice().buffer as ArrayBuffer;
+}
+
+export function createShotStageExporter(
+  host: ShotExportHost,
+  overrides: Partial<ShotExportDeps> = {},
+): ShotStageExporter {
+  const deps: ShotExportDeps = { ...defaultDeps(), ...overrides };
+  const capabilityCache = new Map<string, Tier1Capability>();
+  /** A started encode worker, its failures reported beside the refusal the
+   *  conversation raises (`onWorkerError`). A fake without events is left
+   *  as it is. */
+  const startWorker = (): WorkerLike => {
+    const worker = deps.createWorker();
+    const target = worker as unknown as { addEventListener?: (type: string, listener: (event: unknown) => void) => void };
+    target.addEventListener?.("error", (event) => {
+      const message = (event as { message?: unknown }).message;
+      deps.onWorkerError?.(`the export worker failed: ${typeof message === "string" && message !== "" ? message : "its script did not load or threw"}`);
+    });
+    return worker;
+  };
+  let active = false;
+
+  function requireComposition(): { width: number; height: number; fps: Rational } {
+    const comp = host.composition();
+    if (!comp) throw new Error("export needs a loaded shot");
+    return comp;
+  }
+
+  /**
+   * `after`, charging VISIBLE time only. A hidden tab stops rAF, the
+   * ResizeObserver the framing swap waits on, and the rAF-polled completion of
+   * a WebGL program link, so no frame can present while the author has another
+   * tab in front. Counting that time refused exports the author had merely
+   * stopped watching; paused, the export simply resumes when they come back.
+   */
+  function visibleDeadline(ms: number, fn: () => void): () => void {
+    let spent = 0;
+    let visibleSince: number | null = deps.hidden() ? null : deps.now();
+    let cancelTimer = (): void => {};
+    let finished = false;
+    const schedule = (): void => {
+      cancelTimer();
+      cancelTimer = () => {};
+      if (visibleSince === null) return;
+      cancelTimer = deps.after(Math.max(0, ms - spent), () => {
+        if (finished) return;
+        finished = true;
+        unsubscribe();
+        fn();
+      });
+    };
+    const unsubscribe = deps.onVisibilityChange(() => {
+      if (finished) return;
+      if (deps.hidden()) {
+        if (visibleSince === null) return;
+        spent += deps.now() - visibleSince;
+        visibleSince = null;
+      } else {
+        if (visibleSince !== null) return;
+        visibleSince = deps.now();
+      }
+      schedule();
+    });
+    schedule();
+    return () => {
+      finished = true;
+      cancelTimer();
+      unsubscribe();
+    };
+  }
+
+  /** Arm a bounded capture and retain the old gate's actionable timeout. */
+  function captureFrame(
+    frame: number,
+    timeoutMs: number,
+    comp: { width: number; height: number },
+    signal: AbortSignal | undefined,
+  ): Promise<ImageBitmap> {
+    return new Promise<ImageBitmap>((resolve, reject) => {
+      let done = false;
+      const capture = host.armCapture(frame, comp, deps.toBitmap);
+      let cancelDeadline = (): void => {};
+      const cleanup = (): void => {
+        cancelDeadline();
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const cancel = (error: Error): void => {
+        if (done) return;
+        done = true;
+        cleanup();
+        host.cancelCapture(error);
+        reject(error);
+      };
+      const onAbort = (): void => cancel(new Error("export cancelled"));
+      cancelDeadline = visibleDeadline(timeoutMs, () => {
+        const canvas = host.canvas();
+        const size =
+          canvas !== null && (canvas.width !== comp.width || canvas.height !== comp.height)
+            ? `the canvas to reach ${comp.width}x${comp.height} (it is ${canvas.width}x${canvas.height})`
+            : "";
+        const claims = host.waitingOn().join(", ");
+        const commit = host.frameCommitted(frame) ? "" : "the stage to commit";
+        const parts = [claims, size, commit].filter(Boolean);
+        const error = new Error(
+          `export frame ${frame} was not captured within ${Math.round(timeoutMs / 1000)}s of visible time: ` +
+            `waiting on ${parts.join("; ") || "the matching presentation"}`,
+        );
+        cancel(error);
+      });
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+      void capture.then(
+        (bitmap) => {
+          if (done) {
+            bitmap.close();
+            return;
+          }
+          done = true;
+          cleanup();
+          resolve(bitmap);
+        },
+        (error: unknown) => {
+          if (done) return;
+          done = true;
+          cleanup();
+          reject(error);
+        },
+      );
+    });
+  }
+
+  /** Bound one worker request without weakening converse's single-pending
+   *  protocol. The caller still owns teardown: a deadline rejects into the
+   *  existing cancel/terminate/finally path, while a late worker reply is
+   *  ignored after talk.dispose(). `start` gets `alive`, which starts the
+   *  window again: the request's own progress, when it reports any. */
+  function workerDeadline<T>(start: (alive: () => void) => Promise<T>, message: string): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      let settled = false;
+      let cancelDeadline = (): void => {};
+      const arm = (): void => {
+        cancelDeadline();
+        cancelDeadline = deps.after(WORKER_OPERATION_TIMEOUT_MS, () => {
+          if (settled) return;
+          settled = true;
+          reject(new Error(message));
+        });
+      };
+      arm();
+      const promise = start(() => {
+        if (!settled) arm();
+      });
+      void promise.then(
+        (value) => {
+          if (settled) return;
+          settled = true;
+          cancelDeadline();
+          resolve(value);
+        },
+        (error: unknown) => {
+          if (settled) return;
+          settled = true;
+          cancelDeadline();
+          reject(error);
+        },
+      );
+    });
+  }
+
+  /** Reserve the lane and flip the stage into export framing for `scope`. */
+  function enter(scope: string | undefined): void {
+    active = true;
+    try {
+      host.begin(scope);
+    } catch (e) {
+      active = false;
+      throw e;
+    }
+  }
+
+  /** Restore the author's stage and free the lane, on every path. */
+  function leave(): void {
+    try {
+      host.end();
+    } catch (endError) {
+      // A restore that fails must not replace the capture's own outcome: a
+      // finished movie or still is still returned, and a failure still reports
+      // its own cause. The stage has left export framing regardless (`end`
+      // sets that in a finally).
+      console.error("[export] restoring the stage after the export failed", endError);
+    } finally {
+      active = false;
+    }
+  }
+
+  async function capability(signal?: AbortSignal): Promise<Tier1Capability> {
+    const comp = requireComposition();
+    const key = `${comp.width}x${comp.height}`;
+    const cached = capabilityCache.get(key);
+    if (cached) return cached;
+    let worker: WorkerLike;
+    try {
+      worker = startWorker();
+    } catch (e) {
+      const reason = `export worker could not start: ${e instanceof Error ? e.message : String(e)}`;
+      return {
+        mp4: { ok: false, reason },
+        pngSequence: { ok: false, reason },
+        gif: { ok: false, reason },
+        audio: { ok: false, reason },
+      };
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    const relayAbort = (): void => controller.abort();
+    const cancelDeadline = deps.after(CAPABILITY_TIMEOUT_MS, () => {
+      timedOut = true;
+      controller.abort();
+    });
+    signal?.addEventListener("abort", relayAbort, { once: true });
+    if (signal?.aborted) relayAbort();
+    const talk = converse(worker, controller.signal);
+    try {
+      const res = await talk.request(
+        { type: "probe", width: comp.width, height: comp.height },
+        ["capability"],
+      );
+      capabilityCache.set(key, res.capability);
+      return res.capability;
+    } catch (e) {
+      const reason = timedOut
+        ? CAPABILITY_PROBE_TIMED_OUT
+        : signal?.aborted
+          ? "export cancelled"
+          : e instanceof Error
+            ? e.message
+            : String(e);
+      return {
+        mp4: { ok: false, reason },
+        pngSequence: { ok: false, reason },
+        gif: { ok: false, reason },
+        audio: { ok: false, reason },
+      };
+    } finally {
+      cancelDeadline();
+      signal?.removeEventListener("abort", relayAbort);
+      talk.dispose();
+      worker.terminate();
+    }
+  }
+
+  return {
+    capability,
+
+    async exportMovie({ format, sceneId, window, videoBitrate, quantizer, audio, onProgress, signal }) {
+      const gif = format === "gif";
+      if (active) throw new Error("an export is already running");
+      const comp = requireComposition();
+      const scope = sceneId === undefined || sceneId === "" ? undefined : sceneId;
+      const scopeTotal = host.scopeFrames(scope);
+      if (scopeTotal === null) throw new Error(`unknown scene '${sceneId}'`);
+      if (window !== undefined) {
+        if (scope !== undefined) throw new Error("a frame window is for the whole Project, not one Shot");
+        const { start, frames } = window;
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(frames) || start < 0 || frames < 1 || start + frames > scopeTotal) {
+          throw new Error(`frames ${start}..${start + frames} are outside this Project's timeline (0..${scopeTotal})`);
+        }
+      }
+      // The first master frame and how many follow it.
+      const first = window?.start ?? 0;
+      const total = window?.frames ?? scopeTotal;
+      if (total <= 0) throw new Error("the export scope has no frames");
+
+      // Reserve the lane and enter export framing BEFORE the optional async
+      // audio probe. That defers chrome document/playhead pushes while the
+      // sampled composition and duration are in use, and a second export
+      // cannot pass the guard during the probe.
+      enter(scope);
+      try {
+        // Audio is gated on the probe BEFORE any capture work: an unencodable-
+        // audio browser ships silently WITH the reason (the dialog renders it),
+        // never silently-silently, and never crashes mid-encode instead.
+        let audioJob: { sampleRate: number; channels: ArrayBuffer[] } | undefined;
+        let audioSkippedReason: string | undefined;
+        // A GIF has no audio track: the dialog never offers one, and a mix
+        // handed here anyway has nowhere to go.
+        if (audio && !gif) {
+          const cap = await capability(signal);
+          if (signal?.aborted) throw new Error("export cancelled");
+          if (!cap.mp4.ok) {
+            throw new Error(cap.mp4.reason ?? "this browser cannot encode MP4");
+          }
+          if (!cap.audio.ok) {
+            audioSkippedReason = cap.audio.reason;
+          } else {
+            audioJob = {
+              sampleRate: audio.sampleRate,
+              channels: audio.channels.map(transferableChannel),
+            };
+          }
+        }
+
+        // A GIF faster than 50 fps is written at a fraction of the rate,
+        // every `stride`-th frame (`gifFrameStride`): only those are captured,
+        // and the encoder is handed an ordinary film at the GIF's rate.
+        const stride = gif ? gifFrameStride(comp.fps) : 1;
+        const count = Math.ceil(total / stride);
+        const worker = startWorker();
+        const talk = converse(worker, signal);
+        try {
+          const started = await workerDeadline(
+            () =>
+              talk.request(
+                {
+                  type: "start",
+                  kind: gif ? "gif" : "mp4",
+                  width: comp.width,
+                  height: comp.height,
+                  fps: gif ? gifRate(comp.fps) : comp.fps,
+                  totalFrames: count,
+                  ...(audioJob ? { audio: audioJob } : {}),
+                  ...(videoBitrate !== undefined && !gif ? { videoBitrate } : {}),
+                  ...(quantizer !== undefined && !gif ? { quantizer } : {}),
+                },
+                ["started"],
+                audioJob?.channels,
+              ),
+            "export encoder did not start within 600 seconds",
+          );
+          // Every scene's first frame is a cold mount (an export never warms
+          // the next scene), so each gets the cold budget, not only frame 0.
+          // Decimated, that is the first captured frame at or after it.
+          const coldFrames = new Set(
+            host
+              .sceneStartFrames(scope)
+              .filter((start) => start >= first && start < first + total)
+              .map((start) => Math.ceil((start - first) / stride)),
+          );
+          coldFrames.add(0);
+          for (let index = 0; index < count; index++) {
+            if (signal?.aborted) throw new Error("export cancelled");
+            const frame = first + index * stride;
+            const bitmapPromise = captureFrame(
+              frame,
+              coldFrames.has(index) ? FIRST_FRAME_TIMEOUT_MS : FRAME_TIMEOUT_MS,
+              comp,
+              signal,
+            );
+            host.seek(frame);
+            const bitmap = await bitmapPromise;
+            try {
+              // The ack resolves when the encoder can take more, providing backpressure.
+              const ack = await workerDeadline(
+                () =>
+                  talk.request(
+                    { type: "frame", index, bitmap },
+                    ["frameDone"],
+                    [bitmap],
+                  ),
+                `export frame ${frame} was captured, but the encoder did not acknowledge it within 600 seconds`,
+              );
+              if (ack.index !== index) {
+                throw new Error(
+                  `export worker protocol violation: frame ${index} was acknowledged as ${ack.index}`,
+                );
+              }
+            } finally {
+              // If converse refuses before postMessage (an already-aborted
+              // signal or dead channel), ownership never left this thread.
+              // close() is also harmless after a successful transfer.
+              bitmap.close();
+            }
+            onProgress?.(index + 1, count);
+          }
+          const done = await workerDeadline(
+            (alive) => talk.request({ type: "finish" }, ["done"], undefined, () => alive()),
+            "export encoder made no progress finishing the file for 600 seconds",
+          );
+          return {
+            blob: new Blob([done.data], { type: done.mimeType }),
+            extension: done.extension,
+            ...(audioSkippedReason !== undefined ? { audioSkippedReason } : {}),
+            ...(started.encoding !== undefined ? { encoding: started.encoding } : {}),
+          };
+        } catch (e) {
+          // Best-effort worker-side teardown; terminate() below is the backstop.
+          try {
+            worker.postMessage({ type: "cancel" });
+          } catch {
+            // worker already dead
+          }
+          throw e;
+        } finally {
+          talk.dispose();
+          worker.terminate();
+        }
+      } finally {
+        leave();
+      }
+    },
+
+    async captureStill({ frame, width, height, type, quality, signal }) {
+      if (active) throw new Error("an export is already running");
+      const comp = requireComposition();
+      const total = host.scopeFrames(undefined) ?? 0;
+      if (!Number.isSafeInteger(frame) || frame < 0 || frame >= total) {
+        throw new Error(`frame ${frame} is outside this Project's timeline (0..${total - 1})`);
+      }
+      for (const [name, px] of [["width", width], ["height", height]] as const) {
+        if (!Number.isSafeInteger(px) || px < 1) {
+          throw new Error(`still ${name} must be a positive whole number of pixels, got ${px}`);
+        }
+      }
+      let bitmap: ImageBitmap;
+      enter(undefined);
+      try {
+        // Always the cold budget: the still's scene is usually not the one
+        // on screen, and an export never warms ahead.
+        const captured = captureFrame(frame, FIRST_FRAME_TIMEOUT_MS, comp, signal);
+        host.seek(frame);
+        bitmap = await captured;
+      } finally {
+        // The stage goes back to the author before the encode: scaling and
+        // compressing the picture needs the bitmap, not export framing.
+        leave();
+      }
+      try {
+        return await deps.encodeStill(bitmap, width, height, type, quality);
+      } finally {
+        bitmap.close();
+      }
+    },
+  };
+}

package/src/stage/tokenColor.ts

@@ -2,19 +2,24 @@
 //
 // Every editor-only object in the working pane is drawn with a MATERIAL colour,
 // and a material colour cannot read a CSS custom property the way an SVG fill
-// can. Resolving one at mount, inside the stage document — which imports
-// shotTokens.css — is what lets the gizmo, the grid and the SVG overlay share
-// the single definition in that file instead of each carrying its own literal.
-//
-// Not for GL CLEAR colours: SplitRenderer's clay backdrop is hard-coded because
-// it is written before any style has resolved.
+// can. Resolving one when the appearance-keyed material is built inside the
+// stage document is what lets the gizmo, grid, clear colours and SVG overlay
+// share the single definitions in shotTokens.css instead of carrying literals.
 import { Color } from "three";
 
+export const STAGE_THEME_TOKENS_ID = "shot-stage-theme-tokens";
+
+/** Read from the editor-only probe when the real stage boot installed it.
+ *  Tests and isolated component mounts keep the original root fallback. */
+export function tokenValue(name: string, fallback: string): string {
+  if (typeof document === "undefined") return fallback;
+  const source = document.getElementById(STAGE_THEME_TOKENS_ID) ?? document.documentElement;
+  return getComputedStyle(source).getPropertyValue(name).trim() || fallback;
+}
+
 export function tokenColor(name: string, fallback: string): Color {
   const backstop = new Color(fallback);
-  if (typeof document === "undefined") return backstop;
-  const token = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
-  if (token.length === 0) return backstop;
+  const token = tokenValue(name, fallback);
   try {
     return new Color(token);
   } catch {