@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/SplitRenderer.tsx

@@ -2,9 +2,13 @@
 //
 // Mounted INSIDE `ShotRuntime`'s canvas, and only while a second pane is on
 // screen. `renderControl: "external"` is what makes that legal — see the
-// contract in packages/shot/src/ShotRuntime.tsx. `useFrame(…, 1)` is what hands
-// the present over: r3f skips its own render whenever any subscriber has a
-// priority above zero, which is the identical mechanism `PostPipeline` uses.
+// contract in packages/shot/src/ShotRuntime.tsx. `useFrame(…, { phase:
+// "render" })` is what hands the present over: fiber's own render job stands
+// down whenever a user job occupies the render phase (`hasUserJobsInPhase`),
+// the same mechanism ScenePresenter uses. The phase also guarantees the
+// update-phase subscribers (camera write, user `useFrame` code) ran first —
+// the v9 ordering that a legacy `useFrame(cb, 1)` no longer gives, because
+// the v10 scheduler sorts priority DESCENDING within a phase.
 //
 // ── WHY THE CAMERA PANE'S POST GOES THROUGH A RENDER TARGET ──────────────
 //
@@ -78,82 +82,171 @@
 //
 // ── BINS ─────────────────────────────────────────────────────────────────
 //
-// A scene with a `mesh` layer draws in several passes (packages/shot/bins.ts).
-// EVERY render here goes through `renderBins` or a `SceneSource` rather than
-// `gl.render` / `pass()` directly, so both panes agree with each other and with
-// the export about what covers what. `renderBins` degenerates to exactly one
+// A scene with a `mesh` layer draws in several passes, and a mask run draws
+// as a nested matte (packages/shot/bins.ts). EVERY render here goes through
+// `renderSteps` or a `SceneSource` rather than `gl.render` / `pass()`
+// directly, so both panes agree with each other and with the export about what
+// covers what. `renderSteps` degenerates to exactly one
 // `gl.render` when there is nothing to split, so a scene with no model takes
 // the identical call this file always made.
 //
+// ── THE PLAYBACK RENDER SCALE REACHES THE CAMERA PANE ALONE ──────────────
+//
+// While the transport plays and the stage's controller answers a step below 1
+// (`presentationScale`, packages/shot/src/presentationScale.ts), the camera
+// pane's offscreen draws (the transition capture, the post chain, and for a
+// Shot with no post a plain pane target) run inside `withPresentationScale`,
+// so every target they size from the renderer comes out scaled, and the blit
+// into the pane upscales them. The working pane and its furniture keep the
+// canvas's density. At 1 every draw is the one this file always made.
+//
 // ── NOTHING IS ALLOCATED PER FRAME ───────────────────────────────────────
 //
-// The rig, the clay, the blit quad and the scratch colour are all hoisted. The
-// hot path is scissor rects and one uniform write.
-import { useEffect, useMemo } from "react";
-import { useFrame, useThree } from "@react-three/fiber";
+// The rig, appearance-keyed clay, blit quad and scratch colour are all stable
+// between changes. The hot path is scissor rects and one uniform write.
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useFrame, useStore, useThree } from "@react-three/fiber";
 import { Color, ColorManagement, HalfFloatType, Layers, RenderTarget } from "three";
+import { isInsideOutShell } from "./sceneExtent.js";
 import { MeshBasicNodeMaterial, QuadMesh, RenderPipeline } from "three/webgpu";
-import type { ColorSpace } from "three";
+import type { Camera, ColorSpace, Material, Object3D, Scene } from "three";
 import type { WebGPURenderer } from "three/webgpu";
 import { texture, uv } from "three/tsl";
 import {
+  PRESENTER_RIGS_MAX,
+  PresentationSchedule,
   binSceneSource,
   buildPostChain,
+  compileObjectForTarget,
+  compileRenderPipelineForTarget,
+  devicePixels,
+  drawScaleOf,
   hasPostChain,
   passSceneSource,
+  pendingFrameError,
+  pieceOwner,
   postSignature,
-  renderBins,
+  presenterShapesOf,
+  registerSupplementalFrameCompile,
+  renderSteps,
   transitionTap,
+  usePieceFailures,
+  withPresentationScale,
 } from "@dailies-studio/shot";
-import type { RenderBin, SceneEffects } from "@dailies-studio/shot/doc";
+import type { PieceFailureInput, PresentationScaleSource, RenderStep, SceneEffects, SceneSource } from "@dailies-studio/shot";
+import { componentDefsOfCached, isCompositeStep } from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
 import type { StageFeed } from "./feed.js";
 import type { PaneRect } from "./panes.js";
 import { workingDrawPlan } from "./shading.js";
 import type { ShadingMode } from "./shading.js";
 import { EDITOR_LAYER } from "./StageTools.js";
+import { tokenColor } from "./tokenColor.js";
+
+/** A CSS colour as a three `Color`, or `fallback` when three cannot parse it. */
+function tokenColorOf(css: string, fallback: Color): Color {
+  try {
+    return new Color(css);
+  } catch {
+    return fallback;
+  }
+}
+import type { StageTheme } from "./stageTheme.js";
 
 /**
  * The working pane's backdrop and its clay.
  *
- * NOT tokens. These are a GL clear colour and a material colour, so they cannot
- * read the CSS custom properties the overlays use; they are picked to sit just
- * off `--panel` so the pane reads as a workspace rather than as the shot.
+ * They are GL colours, so each is resolved from a CONCRETE CSS token when the
+ * appearance changes. The camera pane never reads them: it keeps the shot's
+ * authored clear colour and remains identical to export.
  */
-export const CLAY_BACKDROP = new Color(0x141417);
-const CLAY_FILL = new Color(0x8a8a93);
-/** The wireframe's line colour. Brighter than the clay so edges read as lines
- *  on the same backdrop rather than as a dimmer clay. */
-const WIRE_FILL = new Color(0xb8b8c2);
-
 /** Scratch for saving the shot's own clear colour across the working pane's. */
 const _prevClear = new Color();
+const NORMAL_WORKING_COMPILE_MODE = {};
+/** No steps: `renderSteps`' single plain render. */
+const NO_STEPS: readonly RenderStep[] = Object.freeze([]);
 
 export interface SplitRendererProps {
+  /** Resolved editor theme. It rebuilds only the working-view palette. */
+  theme: StageTheme;
   feed: StageFeed;
+  /** The document on stage: how many post shapes its Shots use sizes the rig
+   *  cache. */
+  doc: Doc3D;
   panes: { working: PaneRect | null; camera: PaneRect | null };
   /** The active scene's effects, or null when nothing is on screen. */
   effects: SceneEffects | null;
   /** The active scene's render bins at this frame. Empty or single = one draw,
    *  which is every scene without a live mesh layer. */
-  bins: readonly RenderBin[];
-  /** Whether the scene contains a mesh layer AT ALL. Static (lifetimes
-   *  ignored), because it picks the post chain's SHAPE — see ShotRuntime. */
-  hasMesh: boolean;
+  bins: readonly RenderStep[];
+  /** Whether the scene contains a mesh or a mask layer AT ALL
+   *  (`sceneNeedsBins`). Static (lifetimes ignored), because it picks the post
+   *  chain's SHAPE — see ShotRuntime. */
+  needsBins: boolean;
   /** MASTER frame — the grain's seed, and the only clock the chain sees. */
   frame: number;
+  /** The frame-exact readers (StageApp's `playhead`): the post values, the
+   *  bins and the master frame at DRAW time. `effects`, `bins` and `frame`
+   *  above are the render's snapshot, which is right about the post chain's
+   *  SHAPE and the bins' kind and may be a frame behind on their values;
+   *  absent, the snapshot is the frame (the test harness). */
+  live?: {
+    at(): { masterFrame: number; effects: SceneEffects | null; bins: readonly RenderStep[]; sceneId?: string | null };
+  };
   /** How the WORKING pane draws. The camera pane is not addressable: it is
    *  always the graded render, whatever this says. */
   shading: ShadingMode;
+  /** The Shot the effects belong to, for a post chain that fails to build or
+   *  to draw: it is reported as that Shot's post stack (pieceFailures.ts). */
+  sceneId?: string | null;
+  /** The component preview's backdrop (bridge v45), a CSS colour the working
+   *  pane clears with in place of `--working-bg`. Absent or null = the
+   *  token. */
+  backdrop?: string | null;
+  /** The playback render scale's source (the stage's controller), asked once
+   *  per played frame for the camera pane: see the header. Absent, nothing
+   *  scales. */
+  presentationScale?: PresentationScaleSource;
+  /** The transport plays and no preparing pass draws: the only frames that
+   *  scale. */
+  playing?: boolean;
 }
 
-export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shading }: SplitRendererProps): null {
+export function SplitRenderer({
+  theme,
+  feed,
+  doc,
+  panes,
+  effects,
+  bins: snapshotBins,
+  needsBins,
+  frame,
+  live,
+  shading,
+  sceneId = null,
+  backdrop = null,
+  presentationScale,
+  playing = false,
+}: SplitRendererProps): null {
   // The runtime class IS `WebGPURenderer` (createStageGl builds one, WebGL2 is
   // a BACKEND of it, not a different class); r3f types `gl` as the classic
   // renderer, so the cast happens once here rather than at five call sites.
   const gl = useThree((s) => s.gl) as unknown as WebGPURenderer;
+  const store = useStore();
   const scene = useThree((s) => s.scene);
   const shotCamera = useThree((s) => s.camera);
   const size = useThree((s) => s.size);
+  const workingPalette = useMemo(
+    () => ({
+      backdrop: tokenColor("--working-bg", "#141414"),
+      clay: tokenColor("--working-clay", "#8a8a93"),
+      wire: tokenColor("--working-wire", "#b8b8c2"),
+    }),
+    [theme],
+  );
+  // The preview's backdrop over the token, or the token when the colour is
+  // not one three can parse (`tokenColor`'s rule).
+  const clearBackdrop = useMemo(() => (backdrop === null ? workingPalette.backdrop : tokenColorOf(backdrop, workingPalette.backdrop)), [backdrop, workingPalette]);
 
   /**
    * The clay override, ONE dedicated instance and never shared.
@@ -161,7 +254,8 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
    * `depthTest`/`depthWrite` stay OFF, matching every layer material. It is
    * tempting to turn them on "because the working pane is the 3D one", and it
    * would be a second truth: this lane's paint order is `renderOrder =
-   * layer.order` and nothing else (see ShotRuntime's header), so a depth-tested
+   * layer.order`, the layer lists' walk, and nothing else (see ShotRuntime's
+   * header), so a depth-tested
    * working pane would disagree with the camera pane about what covers what —
    * and, because layers default to z = 0, would z-fight the common case.
    *
@@ -172,7 +266,7 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
    */
   const overrides = useMemo(() => {
     const clay = new MeshBasicNodeMaterial();
-    clay.color.copy(CLAY_FILL);
+    clay.color.copy(workingPalette.clay);
     clay.depthTest = false;
     clay.depthWrite = false;
     clay.toneMapped = false;
@@ -180,13 +274,13 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
     // depth/tone rationale above holds unchanged, because a wireframe pane's
     // paint order is still `renderOrder` and nothing else.
     const wire = new MeshBasicNodeMaterial();
-    wire.color.copy(WIRE_FILL);
+    wire.color.copy(workingPalette.wire);
     wire.wireframe = true;
     wire.depthTest = false;
     wire.depthWrite = false;
     wire.toneMapped = false;
     return { clay, wire };
-  }, []);
+  }, [workingPalette]);
   useEffect(
     () => () => {
       overrides.clay.dispose();
@@ -195,66 +289,88 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
     [overrides],
   );
 
-  const signature = effects === null ? "" : `${postSignature(effects)}::${hasMesh}`;
-  const post = useMemo(() => {
-    if (effects === null || !hasPostChain(effects)) return null;
-    // Layer 0 only. This source is what feeds the graded image, so pinning it is
-    // what makes "an editor-only object can never appear in the camera pane"
-    // true by construction rather than by everyone remembering to set a mask.
-    // Both sources honour it identically.
-    const source = hasMesh
-      ? binSceneSource(scene, shotCamera, new Layers())
-      : passSceneSource(scene, shotCamera, new Layers());
-    const chain = buildPostChain(source.textureNode, effects);
-    const pipeline = new RenderPipeline(
-      gl as unknown as ConstructorParameters<typeof RenderPipeline>[0],
-    );
-    pipeline.outputNode = chain.outputNode;
-    pipeline.outputColorTransform = false; // see the colour note in the header
-    // Half float, working space: the chain's output is scene-referred light and
-    // an 8-bit sRGB hop here would band every gradient the bloom touches.
-    const target = new RenderTarget(1, 1, {
-      type: HalfFloatType,
-      // Read off ColorManagement rather than written as `LinearSRGBColorSpace`:
-      // the pipeline forces the WORKING space for the chain, so this target has
-      // to be whatever that is, not whatever it is today.
-      colorSpace: ColorManagement.workingColorSpace as ColorSpace,
-    });
-    const material = new MeshBasicNodeMaterial();
-    material.colorNode = texture(target.texture, uv());
-    material.depthTest = false;
-    material.depthWrite = false;
-    material.toneMapped = false;
-    // THREE'S OWN full-screen primitive, not a hand-rolled plane. Its geometry
-    // carries the v-FLIPPED uv three uses everywhere it blits a render target
-    // (`QuadGeometry`: the bottom-left vertex is uv 0,1), and its camera covers
-    // NDC exactly — so uv 0..1 lands on the current VIEWPORT, whatever pane
-    // that is, and the image comes out the same way up on both backends. A
-    // `PlaneGeometry` looks equivalent and is upside down.
-    const blit = new QuadMesh(material);
-    return { source, chain, pipeline, target, material, blit };
-    // `effects` is deliberately not a dependency: its VALUES are uniforms
-    // written every frame, and only the SIGNATURE changes the graph's shape.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [gl, scene, shotCamera, signature]);
-
+  const signature = effects === null ? "" : `${postSignature(effects)}::${needsBins}`;
+  // ── THE RIGS ARE KEPT BY SHAPE ──────────────────────────────────────────
+  //
+  // `PresenterRigCache`'s reason (ShotRuntime.tsx), in the layouts it does
+  // not reach: a cut to another post shape built a new chain and its
+  // pipelines on the cut's first frame and disposed the old one, so every
+  // cut back paid again, on every loop. Kept here, a shape that comes back
+  // finds its rig, and with it the registration identity ClockDriver already
+  // compiled. Sized to the film's shapes and capped as the presenter's is:
+  // each rig holds pane- and canvas-sized targets. One cache per renderer,
+  // scene and camera, since a rig is built against all three.
+  const rigs = useMemo(
+    () => ({ camera: new SplitRigCache(releaseCameraPost), working: new SplitRigCache(releaseWorkingPost) }),
+    [gl, scene, shotCamera],
+  );
   useEffect(
     () => () => {
-      if (post === null) return;
-      post.chain.dispose();
-      post.pipeline.dispose();
-      post.source.dispose();
-      post.target.dispose();
-      post.material.dispose();
+      rigs.camera.dispose();
+      rigs.working.dispose();
     },
-    [post],
+    [rigs],
+  );
+  const rigCapacity = useMemo(
+    () => Math.min(PRESENTER_RIGS_MAX, Math.max(1, presenterShapesOf(doc, componentDefsOfCached(doc)))),
+    [doc],
   );
+  useEffect(() => {
+    rigs.camera.resize(rigCapacity);
+    rigs.working.resize(rigCapacity);
+  }, [rigs, rigCapacity]);
+  // ── A POST STACK THAT FAILS IS ONE PIECE ────────────────────────────────
+  //
+  // With the runtime's isolation log (pieceFailures.ts), a chain that cannot
+  // be built leaves its pane ungraded and a pass that throws while drawing
+  // leaves that frame ungraded; both are reported as the Shot's post stack.
+  // Without one, the throw is the stage's, as before. A rig that threw is
+  // never kept.
+  const pieces = usePieceFailures();
+  const postBuild = useMemo((): { rig: CameraPost | null; error: unknown } => {
+    if (effects === null || !hasPostChain(effects)) return { rig: null, error: null };
+    const build = (): CameraPost => rigs.camera.acquire(signature, () => buildCameraPost(gl, scene, shotCamera, needsBins, effects));
+    if (pieces === null) return { rig: build(), error: null };
+    try {
+      return { rig: build(), error: null };
+    } catch (error) {
+      return { rig: null, error };
+    }
+    // `effects` is deliberately not a dependency: its VALUES are uniforms
+    // written every frame, and only the SIGNATURE changes the graph's shape.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [gl, scene, shotCamera, signature, pieces, rigs]);
+  const post = postBuild.rig;
+
+  useLayoutEffect(() => {
+    if (post === null) return;
+    const source = post.source;
+    return registerSupplementalFrameCompile(
+      gl,
+      post,
+      async () => {
+        await source.compile(gl);
+        await compileRenderPipelineForTarget(gl, post.pipeline, post.target);
+        await compileObjectForTarget(gl, post.blit, post.blit.camera, null);
+      },
+      [post.blit],
+      // THE UPCOMING SCENE, AND A CHANGED OBJECT, UNDER THIS SOURCE'S OWN
+      // TARGET, as ScenePresenter registers its source. Without it a cut's
+      // warm-up compiled nothing for this target, and ClockDriver's targeted
+      // path compiled a registration with no warm WHOLE, the live scene,
+      // while the played frame waited.
+      source.compileWarm === undefined
+        ? undefined
+        : (warmScene, warmCamera, subject, side) =>
+            side === "outgoing" ? Promise.resolve() : source.compileWarm!(gl, warmScene, warmCamera, subject),
+    );
+  }, [gl, post]);
 
   /**
    * The WORKING pane's own post rig, for "rendered" shading. Mirrors `post`
    * with two deliberate differences:
    *
-   *  1. Its OWN source target, drawn by `renderBins` at FRAME time with
+   *  1. Its OWN source target, drawn by `renderSteps` at FRAME time with
    *     `feed.workingCamera` — never `pass()`/`binSceneSource`, which bake a
    *     camera at build time. The working slot's camera OBJECT is swapped by
    *     isolation (StageTools puts an orthographic head-on rig in it), so the
@@ -270,62 +386,199 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
    * the source to the pane does not reach that, and no call here can — it
    * needs a pass whose target aspect may differ from the canvas's.
    *
-   * Keyed on the mode so the rig exists only while rendered shading is on:
-   * solid users pay nothing, and leaving the mode disposes the pipeline. It
-   * is keyed on the EFFECTS signature alone and not on `signature`, which
-   * carries `hasMesh`: that bit picks the camera pane's SOURCE KIND (bin vs
-   * pass) and this rig has neither — it always draws its own target with
-   * `renderBins` — so folding it in would tear down and recompile the whole
-   * working pipeline every time a mesh layer entered or left the scene.
+   * Kept only while rendered shading is on: solid users pay nothing, and
+   * leaving the mode disposes its rigs. Kept by the EFFECTS signature alone
+   * and not by `signature`, which carries `needsBins`: that bit picks the
+   * camera pane's SOURCE KIND (bin vs pass) and this rig has neither (it
+   * always draws its own target with `renderSteps`), so folding it in would
+   * build and compile another working pipeline every time a mesh or mask
+   * layer entered or left the scene.
    */
-  const wantWorkingGrade = shading === "rendered";
+  // THROUGH THE PLAN, never a second `=== "rendered"`: what a mode means is
+  // shading.ts's to say, and the draw below already asks it there. `hasChain`
+  // is true here because whether a chain EXISTS is the next line's question,
+  // not this one's.
+  const wantWorkingGrade = workingDrawPlan(shading, true).graded;
   const workingSignature = effects === null ? "" : postSignature(effects);
-  const wpost = useMemo(() => {
-    if (!wantWorkingGrade || effects === null || !hasPostChain(effects)) return null;
-    const src = new RenderTarget(1, 1, { type: HalfFloatType });
-    const chain = buildPostChain(texture(src.texture, uv()), effects);
-    const pipeline = new RenderPipeline(
-      gl as unknown as ConstructorParameters<typeof RenderPipeline>[0],
-    );
-    pipeline.outputNode = chain.outputNode;
-    pipeline.outputColorTransform = false; // one encode, at the blit — header
-    const target = new RenderTarget(1, 1, {
-      type: HalfFloatType,
-      colorSpace: ColorManagement.workingColorSpace as ColorSpace,
-    });
-    const material = new MeshBasicNodeMaterial();
-    material.colorNode = texture(target.texture, uv());
-    material.depthTest = false;
-    material.depthWrite = false;
-    material.toneMapped = false;
-    const blit = new QuadMesh(material);
-    return { src, chain, pipeline, target, material, blit };
+  const wpostBuild = useMemo((): { rig: WorkingPost | null; error: unknown } => {
+    if (!wantWorkingGrade || effects === null || !hasPostChain(effects)) return { rig: null, error: null };
+    const build = (): WorkingPost => rigs.working.acquire(workingSignature, () => buildWorkingPost(gl, effects));
+    if (pieces === null) return { rig: build(), error: null };
+    try {
+      return { rig: build(), error: null };
+    } catch (error) {
+      return { rig: null, error };
+    }
     // Same rule as `post`: `effects` values are uniforms written per frame,
     // only the SIGNATURE changes the graph's shape.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [gl, workingSignature, wantWorkingGrade]);
-
+  }, [gl, workingSignature, wantWorkingGrade, pieces, rigs]);
+  const wpost = wpostBuild.rig;
+  useEffect(() => {
+    if (!wantWorkingGrade) rigs.working.dispose();
+  }, [rigs, wantWorkingGrade]);
+  // A chain that could not be built, reported once for the two panes (they
+  // build the same effects): the pane that failed draws ungraded.
+  const buildOwner = useMemo(() => pieceOwner("split-post"), []);
+  const drawOwner = useMemo(() => pieceOwner("split-post-draw"), []);
+  const buildError = postBuild.error ?? wpostBuild.error;
+  useLayoutEffect(() => {
+    if (pieces === null) return;
+    pieces.set(buildOwner, buildError === null ? [] : [postPiece(sceneId, buildError)]);
+  }, [pieces, buildOwner, buildError, sceneId]);
+  useLayoutEffect(
+    () => () => {
+      pieces?.set(buildOwner);
+      pieces?.set(drawOwner);
+    },
+    [pieces, buildOwner, drawOwner],
+  );
+  /** A pass that threw while drawing, until a frame draws clean. */
+  const drawFailed = useRef(false);
+  /** When the camera pane's scale may move (cuts, transition windows). */
+  const [schedule] = useState(() => new PresentationSchedule());
+  /** The camera pane's plain draw below 1 (step 1a), made with a scale source
+   *  so its blit compiles ahead, as the grade's blit does (below): built at
+   *  the first scaled frame instead, nothing else had built that blit's
+   *  pipeline on a film with no post, and the frame built it synchronously.
+   *  Its target holds memory only while the scale is below 1. */
+  const scales = presentationScale !== undefined;
+  const plainPane = useMemo(() => (scales ? buildPlainPane() : null), [gl, scales]);
   useEffect(
     () => () => {
-      if (wpost === null) return;
-      wpost.chain.dispose();
-      wpost.pipeline.dispose();
-      wpost.src.dispose();
-      wpost.target.dispose();
-      wpost.material.dispose();
+      if (plainPane !== null) releasePlainPane(plainPane);
     },
-    [wpost],
+    [plainPane],
   );
+  useLayoutEffect(() => {
+    if (plainPane === null) return;
+    return registerSupplementalFrameCompile(
+      gl,
+      plainPane,
+      () => compileObjectForTarget(gl, plainPane.blit, plainPane.blit.camera, null),
+      [plainPane.blit],
+    );
+  }, [gl, plainPane]);
+
+  useLayoutEffect(() => {
+    if (wpost === null) return;
+    return registerSupplementalFrameCompile(
+      gl,
+      wpost,
+      async () => {
+        await compileRenderPipelineForTarget(gl, wpost.pipeline, wpost.target);
+        await compileObjectForTarget(gl, wpost.blit, wpost.blit.camera, null);
+      },
+      [wpost.blit],
+    );
+  }, [gl, wpost]);
+
+  // ONE READING OF THE PLAN for both the compile mode and the compile's own
+  // override below. They were two hand-written copies of shading.ts's
+  // `override` arm, so a fifth mode (or moving an existing one's override)
+  // compiled clean here and left the warm path disagreeing with the draw path,
+  // which shows up as a first-frame stall rather than as an error.
+  const workingOverride = ((tag) =>
+    tag === "wire" ? overrides.wire : tag === "clay" ? overrides.clay : null)(
+    workingDrawPlan(shading, wpost !== null).override,
+  );
+  const workingCompileMode: object = workingOverride ?? wpost ?? NORMAL_WORKING_COMPILE_MODE;
+  const workingCompileIdentity = useRef<{
+    camera: Camera | null;
+    mode: object;
+    identity: object;
+  }>({ camera: null, mode: NORMAL_WORKING_COMPILE_MODE, identity: {} });
+  useLayoutEffect(() => {
+    if (panes.working === null) return;
+    const workingCamera = feed.prepareWorkingCamera?.() ?? feed.workingCamera;
+    if (workingCamera === null) return;
+    if (
+      workingCompileIdentity.current.camera !== workingCamera ||
+      workingCompileIdentity.current.mode !== workingCompileMode
+    ) {
+      workingCompileIdentity.current = {
+        camera: workingCamera,
+        mode: workingCompileMode,
+        identity: {},
+      };
+    }
+    const identity = workingCompileIdentity.current.identity;
+    const override = workingOverride;
+    const source = wpost;
+    // One compile shape for the live scene and for the upcoming one: the same
+    // targets, the same masks, the same override, so a cut finds every
+    // working-pane pipeline resident (see `WarmCompile`).
+    const compileScene = async (target: Scene, camera: Camera, subject: Object3D): Promise<void> => {
+      if (source !== null) {
+        // This is the target the priority-1 draw actually fills before the
+        // working post chain reads it. A canvas compile is not equivalent:
+        // target format and samples are part of Three's pipeline context.
+        source.src.samples = gl.samples;
+        source.src.texture.type = gl.getOutputBufferType();
+        await compileObjectForTarget(
+          gl,
+          subject,
+          camera,
+          source.src,
+          target,
+          () => configureWorkingSceneCompile(target, camera, 1, null),
+        );
+        // Rendered shading overpaints the editor layer after the graded blit.
+        // It is a separate canvas draw and therefore a separate compile
+        // context from the half-float source above.
+        await compileObjectForTarget(
+          gl,
+          subject,
+          camera,
+          null,
+          target,
+          () => configureWorkingSceneCompile(target, camera, 1 << EDITOR_LAYER, null),
+        );
+        return;
+      }
+      const mask = workingCamera.layers.mask;
+      await compileObjectForTarget(
+        gl,
+        subject,
+        camera,
+        null,
+        target,
+        () => configureWorkingSceneCompile(target, camera, mask, override),
+      );
+    };
+    return registerSupplementalFrameCompile(
+      gl,
+      identity,
+      () => compileScene(scene, workingCamera, scene),
+      [],
+      (warmScene, warmCamera, subject, side) =>
+        side === "outgoing" ? Promise.resolve() : compileScene(warmScene, warmCamera, subject),
+    );
+    // Deliberately every commit. StageTools publishes the current camera in a
+    // layout effect rather than React state. Re-registering the SAME identity
+    // updates this closure without forcing a compile; a camera or draw-mode
+    // change mints an identity above and makes ClockDriver compile once.
+  });
 
   // The props are read straight out of the closure. r3f re-points `useFrame`'s
   // callback ref in a layout effect on every render, and `ClockDriver` — the
   // LAST child of the scene — is what calls `advance`, so the callback that
   // draws is always the one this render produced.
   useFrame(() => {
+    // A subscriber in this tick threw (the error is parked, ClockDriver
+    // consumes it right after advance): do NOT present the crashed frame.
+    // The canvas keeps the last good picture, matching the v9 latch.
+    // Isolating, the throw is one piece (ClockDriver records it) and the
+    // frame draws around it, so the rest of the Shot keeps moving.
+    if (pieces === null && pendingFrameError(store)) return;
     const working = panes.working;
     const camera = panes.camera;
-    const fx = effects;
-    const at = frame;
+    // The values of THIS draw's frame, when the stage drives by clock; the
+    // props' otherwise. The chain's shape came from the props either way.
+    const now = live?.at();
+    const fx = now === undefined ? effects : effects === null ? null : now.effects;
+    const at = now === undefined ? frame : now.masterFrame;
+    const bins = now === undefined ? snapshotBins : now.bins;
     const workingCamera = feed.workingCamera;
 
     // The shot's own clear colour is ShotBackground's, written on a layout
@@ -341,33 +594,59 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
     //    for the same reason, at the PANE's size so the blend is not stretched
     //    across a frustum it was not rendered for. Without this the editor
     //    would show hard cuts in split view where the export dissolves.
-    const blend = camera === null ? null : transitionTap();
+    //    A capture that threw answers false (the compositor reported it as
+    //    the transition): the pane shows the incoming Shot, a hard cut.
+    let blend = camera === null ? null : transitionTap();
+    // The camera pane's playback scale (header): asked once per played frame,
+    // and held through a transition window by the schedule.
+    let scale = 1;
+    if (presentationScale !== undefined && playing && camera !== null) {
+      scale = schedule.next(presentationScale, now?.sceneId ?? sceneId, blend !== null, at);
+    } else schedule.stop();
     if (blend !== null && camera !== null) {
       gl.setScissorTest(false);
-      blend.capture(camera.width, camera.height);
+      const tap = blend;
+      let captured = true;
+      withPresentationScale(gl, scale, () => {
+        captured = tap.capture(camera.width, camera.height);
+      });
+      if (!captured) blend = null;
     }
 
+    // A post pass that throws while drawing leaves its pane ungraded for this
+    // frame, and is reported (see `postBuild`). Without the log it throws.
+    // Inline try blocks and module functions, not closures: this runs every
+    // frame. The one closure per offscreen draw is the scale's seam
+    // (`withPresentationScale`), which at 1 only calls it.
+    let drawError: unknown = null;
+
     // 1. The camera pane's post chain, OFFSCREEN and UNSCISSORED. See the
     //    header for why this cannot go straight to the canvas. Skipped inside a
     //    window: the compositor rendered this scene into its own operand target
     //    already, with the same chain.
+    let graded = post !== null && fx !== null;
     if (blend === null && camera !== null && post !== null && fx !== null) {
-      // The target is PANE sized, in device px: the pane gets its own
-      // resolution for free, and `setSize` already no-ops when it matches.
-      const dpr = gl.getPixelRatio();
-      post.target.setSize(
-        Math.max(1, Math.round(camera.width * dpr)),
-        Math.max(1, Math.round(camera.height * dpr)),
-      );
-      post.chain.write(fx, at);
-      gl.setScissorTest(false);
-      // The bins first, into whatever the source owns. A `pass()`-backed source
-      // no-ops here and renders itself from inside `pipeline.render()` below,
-      // which is the untouched single-render path.
-      post.source.draw(gl, bins);
-      gl.setRenderTarget(post.target);
-      post.pipeline.render();
-      gl.setRenderTarget(null);
+      try {
+        withPresentationScale(gl, scale, () => drawCameraPost(gl, post, camera, fx, at, bins));
+      } catch (error) {
+        if (pieces === null) throw error;
+        drawError ??= error;
+        gl.setRenderTarget(null);
+        graded = false;
+      }
+    }
+
+    // 1a. A pane with no grade to blit, while the scale is below 1: the plain
+    //     draw goes offscreen too, into a pane-sized target at the scale, and
+    //     step 3 blits it up, because a canvas pass cannot draw below the
+    //     canvas's density. At 1 it stays step 3's direct draw.
+    let plain: PlainPane | null = null;
+    if (scale < 1 && blend === null && camera !== null && !graded && plainPane !== null) {
+      withPresentationScale(gl, scale, () => drawPlainPane(gl, plainPane, camera, scene, shotCamera, bins));
+      plain = plainPane;
+    } else if (scale === 1 && plainPane?.held === true) {
+      plainPane.held = false;
+      plainPane.target.dispose();
     }
 
     // 1b. The WORKING pane's grade, offscreen and unscissored — rendered
@@ -379,28 +658,29 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
     //     this camera's mask is per-draw state we restore. The clear colour is
     //     still the shot's own (`_prevClear`): a graded working pane previews
     //     the export's image, so it sits on the export's background.
+    let workingGraded = wpost !== null;
     if (working !== null && workingCamera !== null && wpost !== null && fx !== null) {
-      const dpr = gl.getPixelRatio();
-      const w = Math.max(1, Math.round(working.width * dpr));
-      const h = Math.max(1, Math.round(working.height * dpr));
-      // Mirrors binSceneSource's target discipline: the renderer's own sample
-      // count and output buffer type, so the image is scene-referred with MSAA
-      // on the model silhouettes.
-      wpost.src.samples = gl.samples;
-      wpost.src.texture.type = gl.getOutputBufferType();
-      wpost.src.setSize(w, h);
-      wpost.target.setSize(w, h);
-      wpost.chain.write(fx, at);
-      gl.setScissorTest(false);
       const prevMask = workingCamera.layers.mask;
-      workingCamera.layers.mask = 1; // bit 0 only
-      gl.setRenderTarget(wpost.src);
-      renderBins(gl, scene, workingCamera, bins);
-      gl.setRenderTarget(null);
+      try {
+        drawWorkingPost(gl, wpost, working, workingCamera, fx, at, scene, bins);
+      } catch (error) {
+        if (pieces === null) throw error;
+        drawError ??= error;
+        gl.setRenderTarget(null);
+        workingGraded = false;
+      }
       workingCamera.layers.mask = prevMask;
-      gl.setRenderTarget(wpost.target);
-      wpost.pipeline.render();
-      gl.setRenderTarget(null);
+    }
+
+    // What this frame's grade did, reported once for both panes.
+    if (pieces !== null) {
+      if (drawError !== null) {
+        drawFailed.current = true;
+        pieces.set(drawOwner, [postPiece(now?.sceneId ?? sceneId, drawError)]);
+      } else if (drawFailed.current) {
+        drawFailed.current = false;
+        pieces.set(drawOwner);
+      }
     }
 
     gl.setScissorTest(true);
@@ -430,9 +710,9 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
     //        plan, which is what `workingDrawPlan` returns for it.
     //    The camera pane is always the one that matches the export.
     if (working !== null && workingCamera !== null) {
-      const plan = workingDrawPlan(shading, wpost !== null);
+      const plan = workingDrawPlan(shading, wpost !== null && workingGraded);
       applyRect(gl, working);
-      if (plan.graded && wpost !== null) {
+      if (plan.graded && wpost !== null && workingGraded) {
         // The graded image already carries the shot's own background, so the
         // pane clears with it rather than the clay backdrop.
         gl.setClearColor(_prevClear, prevAlpha);
@@ -449,9 +729,25 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
         gl.autoClear = prevAutoClear;
         workingCamera.layers.mask = prevMask;
       } else if (plan.override !== null) {
-        gl.setClearColor(CLAY_BACKDROP, 1);
+        gl.setClearColor(clearBackdrop, 1);
         scene.overrideMaterial = plan.override === "wire" ? overrides.wire : overrides.clay;
-        renderBins(gl, scene, workingCamera, bins);
+        // An override draws every object with ITS side (three 0.185.1 copies
+        // the source material's side onto an override only for shadow
+        // passes), so a `BackSide` sky dome becomes a front-faced clay ball
+        // around the whole world. It is hidden for this draw and put back.
+        const insideOut = hideInsideOut(scene);
+        try {
+          // ONE PASS FOR ONE COLOUR. Clay and wire are depth-off and the
+          // same colour everywhere, so drawing the bins in order paints
+          // nothing one pass of all of them does not (one colour blended over
+          // itself commutes), and each bin was a whole render: a projection
+          // walk, a canvas-size MSAA pass and an output quad. A matte or a
+          // blur still cuts what it covers, so a plan with one keeps its steps.
+          renderSteps(gl, scene, workingCamera, bins.some(isCompositeStep) ? bins : NO_STEPS);
+        } finally {
+          for (const o of insideOut) o.visible = true;
+          insideOut.length = 0;
+        }
         scene.overrideMaterial = null;
       } else {
         // RENDERED WITHOUT A CHAIN keeps the SHOT's backdrop, not the clay
@@ -463,22 +759,23 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
         // Material mode keeps the clay backdrop on purpose: it previews the
         // MATERIALS against the workspace, not the shot.
         if (shading === "rendered") gl.setClearColor(_prevClear, prevAlpha);
-        else gl.setClearColor(CLAY_BACKDROP, 1);
-        renderBins(gl, scene, workingCamera, bins);
+        else gl.setClearColor(clearBackdrop, 1);
+        renderSteps(gl, scene, workingCamera, bins);
       }
     }
 
     // 3. The camera pane: the blit, or a plain render when the scene has no
     //    post at all (no pass, no target, no cost — the same call ShotRuntime
-    //    would have made).
+    //    would have made), or below 1 the plain draw's blit (step 1a).
     if (camera !== null) {
       applyRect(gl, camera);
       gl.setClearColor(_prevClear, prevAlpha);
       // `QuadMesh.render` is `renderer.render(quad, itsOwnCamera)` — the same
       // call, through the object that owns the right camera for it.
       if (blend !== null) blend.quad.render(gl);
-      else if (post !== null && fx !== null) post.blit.render(gl);
-      else renderBins(gl, scene, shotCamera, bins);
+      else if (post !== null && fx !== null && graded) post.blit.render(gl);
+      else if (plain !== null) plain.blit.render(gl);
+      else renderSteps(gl, scene, shotCamera, bins);
     }
 
     // 4. Hand the renderer back exactly as it was found. Every one of these is
@@ -489,11 +786,300 @@ export function SplitRenderer({ feed, panes, effects, bins, hasMesh, frame, shad
     gl.setViewport(0, 0, size.width, size.height);
     gl.setScissor(0, 0, size.width, size.height);
     gl.setClearColor(_prevClear, prevAlpha);
-  }, 1);
+  }, { phase: "render" });
 
   return null;
 }
 
+interface CameraPost {
+  source: SceneSource;
+  chain: ReturnType<typeof buildPostChain>;
+  pipeline: RenderPipeline;
+  target: RenderTarget;
+  material: MeshBasicNodeMaterial;
+  blit: QuadMesh;
+}
+
+/**
+ * The CAMERA pane's post rig: its scene source, the chain, the pipeline that
+ * renders it offscreen and the blit that brings it into the pane.
+ *
+ * Layer 0 only. This source is what feeds the graded image, so pinning it is
+ * what makes "an editor-only object can never appear in the camera pane" true
+ * by construction rather than by everyone remembering to set a mask. Both
+ * sources honour it identically. A build that throws part-way disposes the
+ * source it made (the caller isolates the throw, see `postBuild`).
+ */
+function buildCameraPost(
+  gl: WebGPURenderer,
+  scene: Scene,
+  shotCamera: Camera,
+  needsBins: boolean,
+  effects: SceneEffects,
+): CameraPost {
+  const source = needsBins
+    ? binSceneSource(scene, shotCamera, new Layers())
+    : passSceneSource(scene, shotCamera, new Layers());
+  let chain: ReturnType<typeof buildPostChain>;
+  try {
+    chain = buildPostChain(source.textureNode, effects);
+  } catch (error) {
+    source.dispose();
+    throw error;
+  }
+  const pipeline = new RenderPipeline(gl as unknown as ConstructorParameters<typeof RenderPipeline>[0]);
+  pipeline.outputNode = chain.outputNode;
+  pipeline.outputColorTransform = false; // see the colour note in the header
+  // Half float, working space: the chain's output is scene-referred light and
+  // an 8-bit sRGB hop here would band every gradient the bloom touches.
+  const target = new RenderTarget(1, 1, {
+    type: HalfFloatType,
+    // Read off ColorManagement rather than written as `LinearSRGBColorSpace`:
+    // the pipeline forces the WORKING space for the chain, so this target has
+    // to be whatever that is, not whatever it is today.
+    colorSpace: ColorManagement.workingColorSpace as ColorSpace,
+  });
+  return { source, chain, pipeline, target, ...blitOf(target) };
+}
+
+/** A target brought into the current viewport: drawn with no depth and no
+ *  tone mapping of its own, so the canvas's one output pass encodes it. */
+function blitOf(target: RenderTarget): { material: MeshBasicNodeMaterial; blit: QuadMesh } {
+  const material = new MeshBasicNodeMaterial();
+  material.colorNode = texture(target.texture, uv());
+  material.depthTest = false;
+  material.depthWrite = false;
+  material.toneMapped = false;
+  // THREE'S OWN full-screen primitive, not a hand-rolled plane. Its geometry
+  // carries the v-FLIPPED uv three uses everywhere it blits a render target
+  // (`QuadGeometry`: the bottom-left vertex is uv 0,1), and its camera covers
+  // NDC exactly — so uv 0..1 lands on the current VIEWPORT, whatever pane that
+  // is, and the image comes out the same way up on both backends. A
+  // `PlaneGeometry` looks equivalent and is upside down.
+  return { material, blit: new QuadMesh(material) };
+}
+
+interface WorkingPost {
+  src: RenderTarget;
+  chain: ReturnType<typeof buildPostChain>;
+  pipeline: RenderPipeline;
+  target: RenderTarget;
+  material: MeshBasicNodeMaterial;
+  blit: QuadMesh;
+}
+
+/** The WORKING pane's post rig (rendered shading): its own source target,
+ *  the chain over it, the pipeline and the blit. See `wpost`. */
+function buildWorkingPost(gl: WebGPURenderer, effects: SceneEffects): WorkingPost {
+  // In the WORKING space, the canvas frame-buffer target's own label: WebGPU
+  // keys a pipeline on its target's colour space, so a material drawn here
+  // and on the canvas builds one pipeline instead of two. The format stays
+  // half float, and sampling a working-space texture into the working space
+  // converts nothing, so no byte of the pane moves.
+  const src = new RenderTarget(1, 1, {
+    type: HalfFloatType,
+    colorSpace: ColorManagement.workingColorSpace as ColorSpace,
+  });
+  let chain: ReturnType<typeof buildPostChain>;
+  try {
+    chain = buildPostChain(texture(src.texture, uv()), effects);
+  } catch (error) {
+    src.dispose();
+    throw error;
+  }
+  const pipeline = new RenderPipeline(gl as unknown as ConstructorParameters<typeof RenderPipeline>[0]);
+  pipeline.outputNode = chain.outputNode;
+  pipeline.outputColorTransform = false; // one encode, at the blit — header
+  const target = new RenderTarget(1, 1, {
+    type: HalfFloatType,
+    colorSpace: ColorManagement.workingColorSpace as ColorSpace,
+  });
+  return { src, chain, pipeline, target, ...blitOf(target) };
+}
+
+/** The camera pane's plain draw below 1 (the draw's step 1a): its target and
+ *  the blit that brings it into the pane. */
+interface PlainPane {
+  target: RenderTarget;
+  material: MeshBasicNodeMaterial;
+  blit: QuadMesh;
+  /** The target holds memory: drawn since the scale was last at 1. */
+  held: boolean;
+}
+
+/** Of the canvas frame-buffer target's own kind (half float, the working
+ *  space, depth, and the renderer's samples at the draw), so every pipeline
+ *  the scene built for the canvas draws into it too. */
+function buildPlainPane(): PlainPane {
+  const target = new RenderTarget(1, 1, {
+    type: HalfFloatType,
+    colorSpace: ColorManagement.workingColorSpace as ColorSpace,
+  });
+  return { target, ...blitOf(target), held: false };
+}
+
+function releasePlainPane(pane: PlainPane): void {
+  pane.target.dispose();
+  pane.material.dispose();
+}
+
+function releaseCameraPost(post: CameraPost): void {
+  post.chain.dispose();
+  post.pipeline.dispose();
+  post.source.dispose();
+  post.target.dispose();
+  post.material.dispose();
+}
+
+function releaseWorkingPost(wpost: WorkingPost): void {
+  wpost.chain.dispose();
+  wpost.pipeline.dispose();
+  wpost.src.dispose();
+  wpost.target.dispose();
+  wpost.material.dispose();
+}
+
+/**
+ * The split rigs by shape, least recently used first: `PresenterRigCache`
+ * (ShotRuntime.tsx) for this file's two rigs, with the release passed in.
+ * The mounted rig is always the most recent acquire, so it is never the one
+ * evicted while the cache holds two or more.
+ *
+ * ponytail: the third copy of this LRU (with `TransitionRigCache` and
+ * `PresenterRigCache`), because the runtime's are typed to their own rigs
+ * and not exported. One generic cache in the shot package retires all three.
+ */
+class SplitRigCache<R> {
+  readonly #rigs = new Map<string, R>();
+  readonly #release: (rig: R) => void;
+  #capacity = 1;
+
+  constructor(release: (rig: R) => void) {
+    this.#release = release;
+  }
+
+  resize(capacity: number): void {
+    this.#capacity = Math.max(1, capacity);
+    this.#evict();
+  }
+
+  acquire(key: string, make: () => R): R {
+    const hit = this.#rigs.get(key);
+    if (hit !== undefined) {
+      this.#rigs.delete(key);
+      this.#rigs.set(key, hit);
+      return hit;
+    }
+    const rig = make();
+    this.#rigs.set(key, rig);
+    this.#evict();
+    return rig;
+  }
+
+  dispose(): void {
+    for (const rig of this.#rigs.values()) this.#release(rig);
+    this.#rigs.clear();
+  }
+
+  #evict(): void {
+    while (this.#rigs.size > this.#capacity) {
+      const oldest = this.#rigs.keys().next().value as string;
+      const victim = this.#rigs.get(oldest)!;
+      this.#rigs.delete(oldest);
+      this.#release(victim);
+    }
+  }
+}
+
+/** A Shot's post stack, as a failed piece. */
+/** The camera pane's grade, offscreen (see the draw's step 1). */
+function drawCameraPost(
+  gl: WebGPURenderer,
+  post: CameraPost,
+  camera: PaneRect,
+  fx: SceneEffects,
+  at: number,
+  bins: readonly RenderStep[],
+): void {
+  // The target is PANE sized, in device px: the pane gets its own
+  // resolution for free, and `setSize` already no-ops when it matches. Sized
+  // as three sizes the pane's viewport (`devicePixels`), so the blit draws it
+  // back one texel to a pixel; rounded, it was a pixel wider than the pane at
+  // a fractional density.
+  const dpr = gl.getPixelRatio();
+  post.target.setSize(devicePixels(camera.width, dpr), devicePixels(camera.height, dpr));
+  // The pixel-sized knobs at the pane's playback scale (`drawScaleOf`).
+  post.chain.write(fx, at, drawScaleOf(gl));
+  gl.setScissorTest(false);
+  // The bins first, into whatever the source owns. A `pass()`-backed
+  // source no-ops here and renders itself from inside
+  // `pipeline.render()` below, which is the untouched single-render path.
+  post.source.draw(gl, bins);
+  gl.setRenderTarget(post.target);
+  post.pipeline.render();
+  gl.setRenderTarget(null);
+}
+
+/** The camera pane's plain draw, offscreen and pane sized like the grade's
+ *  (see the draw's step 1a). The clear colour is still the Shot's. */
+function drawPlainPane(
+  gl: WebGPURenderer,
+  pane: PlainPane,
+  camera: PaneRect,
+  scene: Scene,
+  shotCamera: Camera,
+  bins: readonly RenderStep[],
+): void {
+  const dpr = gl.getPixelRatio();
+  pane.target.samples = gl.samples;
+  pane.target.texture.type = gl.getOutputBufferType();
+  pane.target.setSize(devicePixels(camera.width, dpr), devicePixels(camera.height, dpr));
+  pane.held = true;
+  gl.setScissorTest(false);
+  gl.setRenderTarget(pane.target);
+  renderSteps(gl, scene, shotCamera, bins);
+  gl.setRenderTarget(null);
+}
+
+/** The working pane's grade, offscreen (see the draw's step 1b). The caller
+ *  restores the camera's mask, thrown or not. */
+function drawWorkingPost(
+  gl: WebGPURenderer,
+  wpost: WorkingPost,
+  working: PaneRect,
+  workingCamera: Camera,
+  fx: SceneEffects,
+  at: number,
+  scene: Scene,
+  bins: readonly RenderStep[],
+): void {
+  const prevMask = workingCamera.layers.mask;
+  const dpr = gl.getPixelRatio();
+  const w = devicePixels(working.width, dpr);
+  const h = devicePixels(working.height, dpr);
+  // Mirrors binSceneSource's target discipline: the renderer's own sample
+  // count and output buffer type, so the image is scene-referred with
+  // MSAA on the model silhouettes.
+  wpost.src.samples = gl.samples;
+  wpost.src.texture.type = gl.getOutputBufferType();
+  wpost.src.setSize(w, h);
+  wpost.target.setSize(w, h);
+  wpost.chain.write(fx, at);
+  gl.setScissorTest(false);
+  workingCamera.layers.mask = 1; // bit 0 only
+  gl.setRenderTarget(wpost.src);
+  renderSteps(gl, scene, workingCamera, bins);
+  gl.setRenderTarget(null);
+  workingCamera.layers.mask = prevMask;
+  gl.setRenderTarget(wpost.target);
+  wpost.pipeline.render();
+  gl.setRenderTarget(null);
+}
+
+function postPiece(sceneId: string | null, error: unknown): PieceFailureInput {
+  return { key: "post", kind: "post", sceneId: sceneId ?? "", fieldPath: "effects", error };
+}
+
 /**
  * Point the renderer at one pane.
  *
@@ -509,3 +1095,64 @@ function applyRect(gl: WebGPURenderer, rect: PaneRect): void {
   gl.setViewport(rect.x, rect.y, rect.width, rect.height);
   gl.setScissor(rect.x, rect.y, rect.width, rect.height);
 }
+
+/**
+ * Make compileAsync see the working draw's exact scene state, then hand back a
+ * synchronous restore. `compileObjectForTarget` invokes both around its
+ * synchronous scene walk, so no camera, scene, object, or renderer state is
+ * held while shader compilation awaits the backend.
+ *
+ * Frustum culling is disabled for the walk on purpose. An orbit can reveal an
+ * already-mounted object without changing its material signature, and that
+ * later first draw must not be where its pipeline is created.
+ */
+/** Scratch for `hideInsideOut`: the meshes hidden for one override draw. */
+const _insideOut: Object3D[] = [];
+
+/**
+ * Hide every showing mesh whose material(s) are ALL `BackSide` and return
+ * them, so the caller can put them back after the draw. Such a mesh is a
+ * shell meant to be seen from inside (a sky dome, an environment sphere);
+ * under a single-sided override it is a wall around everything else. The same
+ * predicate the camera body's bounds walk skips by (sceneExtent).
+ *
+ * WALKED AT EVERY DRAW, over what shows (a shell under a hidden parent draws
+ * nothing anyway). A list kept between draws went stale on changes no key it
+ * had could see: a cut or a seek into a resident Shot only re-parents that
+ * Shot's group, and a code component's module, its own Suspense or a child it
+ * renders on a prop commits a subtree with no layer mounting. A shell the
+ * list missed drew as a clay ball over the whole pane.
+ */
+export function hideInsideOut(scene: Scene): Object3D[] {
+  _insideOut.length = 0;
+  scene.traverseVisible((o) => {
+    if (!isInsideOutShell(o)) return;
+    o.visible = false;
+    _insideOut.push(o);
+  });
+  return _insideOut;
+}
+
+export function configureWorkingSceneCompile(
+  scene: Scene,
+  camera: Camera,
+  mask: number,
+  override: Material | null,
+): () => void {
+  const previousMask = camera.layers.mask;
+  const previousOverride = scene.overrideMaterial;
+  const culled: Array<{ object: Object3D & { frustumCulled: boolean }; value: boolean }> = [];
+  camera.layers.mask = mask;
+  scene.overrideMaterial = override;
+  scene.traverse((object) => {
+    if (!("frustumCulled" in object) || typeof object.frustumCulled !== "boolean") return;
+    const renderable = object as Object3D & { frustumCulled: boolean };
+    culled.push({ object: renderable, value: renderable.frustumCulled });
+    renderable.frustumCulled = false;
+  });
+  return () => {
+    for (const entry of culled) entry.object.frustumCulled = entry.value;
+    scene.overrideMaterial = previousOverride;
+    camera.layers.mask = previousMask;
+  };
+}