@volter/editor-threejs 0.5.211 → 0.5.213

package/src/kit/components/StageHost.tsx

@@ -1,9 +1,9 @@
 import { optionalThreeStateOf, threeStateOf } from '../three-state';
-import { ShellStore } from '@volter/sdk/kit/shell-store';
-import type { ToolObject3DAuthoringProps, ToolObject3DDocumentAuthoring, ToolObject3DPreviewSource, ToolViewportDressing } from '../../object3d-contributions';
-import { invalidateStages, stageGeneration } from '@volter/sdk/kit/stage-invalidation';
+import { ShellStore } from '@volter/sdk/shell-store';
+import type { ToolObject3DAuthoringProps, ToolObject3DDocumentAuthoring, ToolObject3DPreviewSource } from '../../object3d-contributions';
+import { invalidateStages, stageGeneration } from '@volter/sdk/stage-invalidation';
 import type { StageTransportSnapshot } from '@volter/sdk/host';
-import { EditorIcon, editorIcons, IconButton, themeVars } from '@volter/sdk/widgets';
+import { EditorBanner, EditorIcon, editorIcons, IconButton, themeVars } from '@volter/sdk/widgets';
 import type { AuthoringAdapter } from '@volter/project/adapter';
 import { contentWorldBounds } from '@volter/editor-threejs/viewport/content-bounds';
 import { isInEditorOwnedSubtree } from '@volter/editor-threejs/viewport/editor-layers';
@@ -25,9 +25,9 @@ import {
 } from 'react';
 import * as THREE from 'three';
 import { DocumentScene } from '../../render/document-scene';
-import { registerStageTransport, StageTransport } from '@volter/sdk/kit/animation/stage-transport';
+import { registerStageTransport, StageTransport } from '@volter/sdk/animation/stage-transport';
 import { scanClipSubjects } from '../animation/three-clips-subject';
-import { liveGestureActive, whenLiveGestureIdle } from '@volter/sdk/kit/live-gesture-lock';
+import { liveGestureActive, whenLiveGestureIdle } from '../live-gesture-lock';
 import {
   type Object3DDocumentPresentationState,
   Object3DDocumentSession,
@@ -37,39 +37,36 @@ import {
 } from '../authoring/object3d-document-session-registry';
 import { Object3DGestureController } from '../authoring/object3d-gesture-controller';
 import { SourceObject3DAuthoringAdapter } from '../authoring/source-object3d-authoring-adapter';
-import { registerDesignTimeSurface } from '@volter/sdk/kit/coverage/design-time-surfaces';
-import { DocumentRendererSession } from '@volter/sdk/kit/document-renderer-session';
-import { useOptionalEditorStats, useOptionalEditorStore } from '@volter/sdk/kit/editor-runtime';
+import { registerDesignTimeSurface } from '@volter/sdk/coverage/design-time-surfaces';
+import { DocumentRendererSession } from '../document-renderer-session';
+import { useOptionalEditorStats, useOptionalEditorStore } from '@volter/sdk/editor-runtime';
 import type { EditorShellStore } from '../editor-shell-store';
 import { EditorViewport } from '../editor-viewport';
 import {
   lookDeclaresViewportColors,
   nativeViewportLook,
   subscribeNativeSelectionTheme,
-} from '@volter/sdk/kit/native-selection-style';
-import {
-  type Object3DDocumentPersistenceSession,
-  object3DDocumentWritePolicy,
-} from '@volter/sdk/kit/object3d-document-write-policy';
-import { registerPerformanceSource } from '@volter/sdk/kit/performance-sources';
+} from '@volter/sdk/native-selection-style';
+import type { AssetDocumentPersistenceSession } from '@volter/sdk/authoring/document-persistence-types';
+import { assetDocumentWritePolicy } from '@volter/sdk/asset-document-write-policy';
 import {
   assetSubjectApplies,
   documentStageContext,
   focusedStageStore,
   identityRowApplies,
   studioStageApplies,
-} from '@volter/sdk/kit/stage-context';
-import { registerStageStore } from '@volter/sdk/kit/stage-store-registry';
-import { announceDocumentStage, registerDocumentViewport } from '@volter/sdk/kit/document-viewports';
+} from '@volter/sdk/stage-context';
+import { registerStageStore } from '@volter/sdk/stage-store-registry';
+import { announceDocumentStage, registerDocumentViewport } from '@volter/sdk/document-viewports';
 import { sceneDocumentViewport } from '../scene-document-viewport';
 import { threeStageTransformChrome } from './stage-transform-chrome';
-import { RetainedDocumentStates } from '@volter/sdk/kit/retained-document-states';
+import { RetainedDocumentStates } from '../retained-document-states';
 import { perspectiveDistanceToFitBox } from '../three-viewport/camera-fit';
 import {
   acquireInteractiveViewportRenderer,
   type InteractiveViewportRendererLease,
 } from '../three-viewport/interactive-renderer';
-import type { ThreeViewportProjection } from '@volter/sdk/kit/three-viewport-presentation';
+import type { ThreeViewportProjection } from '../three-viewport-presentation';
 import {
   activeViewportBreakdownDocumentId,
   markViewportConstructReady,
@@ -77,9 +74,9 @@ import {
   markViewportFirstRenderStart,
   markViewportRafResume,
   markViewportReactActive,
-  markViewportSegment,
+  markViewportFirstRender,
   recordViewportFirstFrame,
-} from '@volter/sdk/kit/viewport-activation-timings';
+} from '@volter/sdk/viewport-activation-timings';
 import { bindViewportRig, runViewportFrame } from '../../viewport-door';
 import type { StageFrameCost } from '../../viewport-api';
 import {
@@ -87,11 +84,11 @@ import {
   openWorkspaceDocuments,
   registerWorkspaceDocumentSelection,
   subscribeWorkspaceDocuments,
-} from '@volter/sdk/kit/workspace-document-registry';
-import { AssetEditorShell } from '@volter/sdk/kit/components/AssetEditorShell';
+} from '@volter/sdk/workspace-document-registry';
+import { AssetEditorShell } from '@volter/sdk/components/AssetEditorShell';
 import { StageOverlays } from './StageOverlays';
 import type { WorldRootStageBinding } from './world-root-binding';
-import { TransportStrip } from '@volter/sdk/kit/transport-strip';
+import { TransportStrip } from '../transport-strip';
 
 // The stage's own keyboard actions, behind the same lazy boundary as the
 // overlays and for the same reason — a bounded host pays for neither
@@ -108,8 +105,8 @@ import {
   watchPaletteBackdrop,
 } from './standard-viewport-dressing';
 import { ViewportFurniture } from './ViewportFurniture';
-import { OBJECT3D_SURFACE_BUILDING, ViewportSurfaceStatus } from '@volter/sdk/kit/viewport-surface-status';
-import { workspaceHistoryService } from '@volter/sdk/kit/components/workspace-history';
+import { Progress } from '@volter/sdk/progress';
+import { workspaceHistoryService } from '@volter/sdk/components/workspace-history';
 import {
   bindViewPresentation,
   DOCUMENT_STUDIO_PRESET,
@@ -123,11 +120,12 @@ import {
   viewPresentation,
   viewPresentationSnapshot,
   type ViewportDrawMode,
-} from '@volter/sdk/kit/viewport-presentation';
-import { subscribeEnvironmentImages } from '@volter/sdk/kit/environment-images';
+} from '@volter/sdk/viewport-presentation';
+import { subscribeEnvironmentImages } from '@volter/sdk/environment-images';
 import { StagePresentationRig } from './standard-viewport-dressing';
 import { threeStoreForHost } from '../three-state';
 import { threeObject } from '../../adapter/three-contract';
+import './StageHost.css';
 
 /** The kind of stage a document's view is, for its starting presentation: the document's own
  *  kind, its id's prefix inside the workspace's `document:` wrapper
@@ -138,13 +136,12 @@ const stageKindOf = (documentId: string): string => {
 };
 
 /** WHERE THIS DOCUMENT'S BYTES GO — the one collaborator the shell installs
- *  (`object3d-document-write-policy.ts`). The tier's source recorder, the
+ *  (`asset-document-write-policy.ts`). The tier's source recorder, the
  *  project file history and the thumbnail manifest all live behind it, so the
- *  Asset Lab 3D document carries no editor transport in its own closure
- *  (ARCHITECTURE-CORE §Editor chrome, "the viewport stack is separable").
+ *  Asset Lab 3D document carries no editor transport in its own closure.
  *  With no shell above it every member refuses by name, which is the same
  *  refusal a read-only tier already produced. */
-const projectWrites = () => object3DDocumentWritePolicy();
+const projectWrites = () => assetDocumentWritePolicy();
 
 /**
  * How far a BARE dock-panel stage bleeds past the box a person sees, so the
@@ -157,34 +154,6 @@ const projectWrites = () => object3DDocumentWritePolicy();
  */
 const STAGE_BLEED_PX = 12;
 
-function boxFromFrameBounds(
-  bounds:
-    | {
-        readonly min: readonly [number, number, number];
-        readonly max: readonly [number, number, number];
-      }
-    | undefined,
-): THREE.Box3 | null {
-  if (!bounds) return null;
-  const box = new THREE.Box3(
-    new THREE.Vector3(bounds.min[0], bounds.min[1], bounds.min[2]),
-    new THREE.Vector3(bounds.max[0], bounds.max[1], bounds.max[2]),
-  );
-  return box.isEmpty() ? null : box;
-}
-
-/**
- * Per-document overrides of the standard viewport dressing
- * (`standard-viewport-dressing.ts`) — explicit opt-outs/opt-ins, never
- * re-implementations. Omitted means the standard look.
- *
- * THE SHAPE IS THE SDK'S (`ToolViewportDressing`), because a contributed
- * document is what asks for it: `@volter/editor-blender`'s Model document hands over
- * its view-locked studio through this door. One declaration, so the public
- * surface and the host cannot drift.
- */
-export type StandardDressingProps = ToolViewportDressing;
-
 /** What an editor-side source lane gets to build its authoring adapter over
  *  the document's own store and scene. */
 export interface SourceDocumentAuthoringContext {
@@ -246,63 +215,23 @@ export interface Object3DDocumentViewportProps
    * SOURCE (a mounted R3F composition's stamped JSX, today). The caller that
    * knows the source lane supplies the adapter; this document constructs
    * none of them, so it stays mountable without any source lane in its
-   * closure (ARCHITECTURE-CORE §Editor chrome, "the viewport stack is
-   * separable"). Raw model/artifact documents omit this and remain honestly
+   * closure. Raw model/artifact documents omit this and remain honestly
    * read-only through the native source adapter. Consulted only when the
    * project `authoring` factory declined. MUST be referentially stable for
    * the document's lifetime, like `build`: it is an activation dependency.
    */
   readonly sourceAuthoring?: SourceDocumentAuthoringFactory;
-  /**
-   * Where this viewport's `WebGLRenderer` comes from.
-   *
-   * `own` (the default) constructs one for this mount — the right answer for a
-   * document that lives as long as its panel does. `inspector-preview` draws
-   * through the shared inspector-preview renderer
-   * (`inspector-preview-renderer.ts`): that lane REMOUNTS PER SELECTION, and a
-   * renderer construction there is ~1.9 s of frozen main thread plus a cold
-   * shader cache and a fresh PMREM bake, every time you click something.
-   */
+  /** Use the shared inspector-preview renderer for mounts replaced per selection; other
+   * document mounts own their renderer and shader cache for their lifetime. */
   readonly rendererLane?: 'own' | 'inspector-preview';
-  /**
-   * Double-click on a picked node — the document's "open THIS" gesture,
-   * reported with the node's own `Object3D` so the owner can resolve whatever
-   * it means by it. Single click stays plain selection; a document that
-   * declares no handler has no open gesture at all.
-   *
-   * Sole caller: the `3D` board, where an exhibit opens that
-   * story's own turntable document (`three-board/ThreeBoardDocument.tsx`).
-   */
-  readonly onOpenNode?: (object: THREE.Object3D) => void;
-  /**
-   * When set, Frame with no selection and the view presets fit THIS box
-   * instead of `contentWorldBounds(root)`. The 3D board passes the union of
-   * each exhibit's presence as its true-scale overview.
-   */
-  readonly frameBounds?: {
-    readonly min: readonly [number, number, number];
-    readonly max: readonly [number, number, number];
-  };
-  /** Optional first-paint frame distinct from the document's Frame fallback.
-   * The 3D component board opens on one readable exhibit, while clearing the
-   * selection and pressing Frame still restores its true-scale overview. */
-  readonly openingFrameBounds?: {
-    readonly min: readonly [number, number, number];
-    readonly max: readonly [number, number, number];
-  };
   /** Multiplies the opening fit distance; `1` fills the view. */
   readonly openingFit?: number;
   /** The kind of stage this view is, for its starting presentation
-   *  (`@volter/sdk/kit/viewport-presentation`): the document's own kind (`'model'`).
+   *  (`@volter/sdk/viewport-presentation`): the document's own kind (`'model'`).
    *  Without it the kind is read off the document id's prefix. */
   readonly stageKind?: string;
 }
 
-/**
- * Distinguishes the chromeless mounts of ONE document from each other and from
- * that document's viewport, so each publishes its own design-time surface
- * instead of overwriting a sibling's (see the registration below).
- */
 /** The draw modes a view's presentation carries (`ViewportDrawMode`). */
 const VIEW_DRAW_MODES: readonly ViewportDrawMode[] = [
   'solid',
@@ -316,6 +245,11 @@ const VIEW_DRAW_MODES: readonly ViewportDrawMode[] = [
   'overdraw',
 ];
 
+/**
+ * Distinguishes the chromeless mounts of ONE document from each other and from
+ * that document's viewport, so each publishes its own design-time surface
+ * instead of overwriting a sibling's (see the registration below).
+ */
 let chromelessSurfaceSequence = 0;
 
 interface RetainedObject3DStageState {
@@ -375,11 +309,11 @@ function mountViewportSurface(
   lane: 'own' | 'inspector-preview',
   displayName: string,
   initialSize: { readonly width: number; readonly height: number },
-  onContextLost?: () => void,
+  onContextLost: () => void,
 ): {
   canvas: HTMLCanvasElement;
   renderer: THREE.WebGLRenderer;
-  lease: InspectorPreviewLease | InteractiveViewportRendererLease | null;
+  lease: InspectorPreviewLease | InteractiveViewportRendererLease;
 } {
   if (lane === 'inspector-preview') {
     const lease = acquireInspectorPreviewRenderer();
@@ -406,7 +340,6 @@ function mountViewportSurface(
  * Source lifetimes borrow it; closing waits for any asynchronous gesture
  * cleanup to return its borrow before releasing the context. */
 
-
 interface DocumentContentBinding {
   readonly scene: THREE.Scene;
   settle(): Promise<void>;
@@ -416,7 +349,7 @@ interface DocumentContentBinding {
 /** Persistent editor state. Source revisions own only their content binding. */
 class Object3DDocumentHost {
   readonly scene = new DocumentScene();
-  /** This document's store, optionally supplied by its owner. */
+  /** This document's store, supplied by its owner. */
   readonly store: EditorShellStore;
   readonly cleanups: Array<() => void> = [];
   readonly rendererSession = new DocumentRendererSession(
@@ -427,7 +360,7 @@ class Object3DDocumentHost {
   session: Object3DDocumentSession | null = null;
   dressing: StandardViewportDressing | null = null;
   /** The stage's lighting, tone and exposure, from its view's presentation
-   *  (`standard-viewport-dressing.ts`, `kit/viewport-presentation`). */
+   *  (`standard-viewport-dressing.ts`, `@volter/sdk/viewport-presentation`). */
   presentationRig: StagePresentationRig | null = null;
   /** Re-apply the view's presentation (after the viewport and session exist). */
   applyPresentation: (() => void) | null = null;
@@ -487,18 +420,15 @@ class Object3DDocumentHost {
     return this.closed;
   }
 
-  /** THIS STAGE's transport — the one holder of the content-time door below.
-   *  Built from this stage's own store, because `driver` is that store's
-   *  `playState` and nothing else (`animation/stage-transport.ts`). */
-  readonly transport: StageTransport;
+  /** THIS STAGE's transport — the one holder of the content-time door below. */
+  readonly transport = new StageTransport();
 
   constructor(
     readonly lane: 'own' | 'inspector-preview',
-    readonly surface: ReturnType<typeof mountViewportSurface>,
-    store?: EditorShellStore,
+    readonly surface: ReturnType<typeof mountViewportSurface> | ReturnType<WorldRootStageBinding['mountWorldRootSurface']>,
+    store: EditorShellStore,
   ) {
-    this.store = store ?? threeStateOf(new ShellStore());
-    this.transport = new StageTransport(this.store.shell);
+    this.store = store;
   }
 
   borrow(): () => void {
@@ -529,7 +459,7 @@ class Object3DDocumentHost {
   private releaseIfClosed(): void {
     if (!this.closed || this.users !== 0 || this.released) return;
     this.released = true;
-    const { lease, renderer, canvas } = this.surface;
+    const { lease, canvas } = this.surface;
     for (const cleanup of [
       ...this.cleanups.splice(0),
       () => this.session?.dispose(),
@@ -537,9 +467,7 @@ class Object3DDocumentHost {
       () => this.rendererSession.dispose(),
       () => this.dressing?.dispose(),
       () => canvas.removeAttribute('data-volter-root-surface'),
-      ...(lease
-        ? [() => lease.release()]
-        : [() => renderer.dispose(), () => renderer.forceContextLoss(), () => canvas.remove()]),
+      () => lease?.release(),
     ]) {
       try {
         cleanup();
@@ -551,33 +479,7 @@ class Object3DDocumentHost {
   }
 }
 
-/**
- * Editor-owned authoring host for a project-supplied native Object3D factory.
- * Project code supplies only source construction; this component owns the
- * real EditorViewport, document-scoped AuthoringAdapter, selection, framing,
- * animation preview, resize, and teardown.
- *
- * ## TIME ON THIS SURFACE — the one policy, inherited by everything mounted here
- *
- * This host is the shared stack: Asset Lab documents, story turntables, 3D board
- * exhibits and the inspector's preview card all render through it. So the
- * Edit-static rule is enforced HERE, once, rather than at each of them:
- *
- *  - PRESENTATION time always advances — orbit damping, the view cube, the
- *    standard dressing, the editor's own helpers and overlays. It is
- *    editor-owned and it moves while the editor is in Edit.
- *  - CONTENT time does NOT. The source's own `update(dt)` and any clip a
- *    subject shows move only through the stage TRANSPORT, and only while a
- *    human is holding it (`animation/stage-transport.ts`, WORK.md §The stage
- *    transport and the animation door). A mounted
- *    document plays nothing on its own: that is the defect this closes (a GLB
- *    train animating in the Asset Lab while every instrument called the editor
- *    still, owner find 2026-08-15).
- *
- * Whatever content time this surface has reached is published as its content
- * clock (`coverage/design-time-surfaces.ts`), so the Edit-static vitals row
- * measures THIS surface by name instead of speaking only for the Scene view.
- */
+/** Shared Object3D authoring host: owns viewport, adapter, selection, framing, resize and disposal. Presentation time advances independently; source update and clips advance only through the stage transport. Publish content time for this surface. */
 export function Object3DDocumentViewport({
   documentId,
   sourcePath,
@@ -601,9 +503,6 @@ export function Object3DDocumentViewport({
   sourceAuthoring,
   dressing,
   rendererLane = 'own',
-  onOpenNode,
-  frameBounds,
-  openingFrameBounds,
   openingFit,
   openingView,
   presentation: documentPresentation,
@@ -624,40 +523,12 @@ export function Object3DDocumentViewport({
     if (chromeless) return;
     return announceDocumentStage(documentId);
   }, [documentId, chromeless]);
-  // The SHELL store, not this host's own: what a stage is showing is a fact
-  // about the workspace's document, and `stage-context.ts` is where every
-  // stage capability asks it (ARCHITECTURE-CORE §One stage). OPTIONAL because
-  // this host is a bounded-host surface — `@volter/editor-blender`'s Model document
-  // mounts it with no `EditorProvider` above it, and the throwing hook took
-  // that document off the screen with "useEditorStore must be used within
-  // <EditorProvider>" (measured live, 2026-09-18). No shell, no shell frame.
+  // Shell React context is optional for a bounded stage. Shell overlays mount only when that provider is present.
   const shellStore = optionalThreeStateOf(useOptionalEditorStore());
-  /**
-   * THE STORE THE STAGE CONTEXT IS ASKED AGAINST — the session's own, reached
-   * without a React provider.
-   *
-   * `optionalThreeStateOf(useOptionalEditorStore())` above answers a NARROWER question than the
-   * context needs: it is whether the shell's own React tree is above this
-   * host, and for every package-contributed document it is not.
-   * `@volter/editor-blender`'s Model document mounts this host through `ToolHost`, so the
-   * context store is null there — and reading only it left `stageCtx` null,
-   * which made EVERY condition in `stage-context.ts` unanswerable for that
-   * document. That is a capability decided by where a document's React tree
-   * happens to mount, which is the origin-deciding reading §One stage
-   * retired. Without the context, the studio arm of `studioStageApplies`
-   * could never fire for a model no matter what the look declared.
-   *
-   * `shellStoreForHost()` supplies the session store that
-   * `focusedStageStore()` falls back to. It is deliberately NOT used for the
-   * overlay set or the shell readout below: those are the SHELL's estate and
-   * their condition is the shell's React presence, exactly as §One stage
-   * unit 3 measured it — a stage that is not inside the shell has no shell
-   * overlays. That gap is real and named, not closed here: unit 1's bar is
-   * that the Model document's Blender frame does not move.
-   */
+  /** Use the host’s session store for stage conditions even when ToolHost mounts outside the shell’s React tree. Shell overlays still require the shell provider. */
   const contextStore = shellStore ?? threeStoreForHost();
   /**
-   * WHAT THIS STAGE IS SHOWING, asked once (ARCHITECTURE-CORE §One stage).
+   * WHAT THIS STAGE IS SHOWING, asked once.
    * `chrome` is the host's own answer and nothing infers it: an EMBEDDED
    * preview has no workspace document at all, which is exactly why the
    * subject would come back `unknown` for one.
@@ -668,10 +539,8 @@ export function Object3DDocumentViewport({
   /**
    * THE STUDIO PRESENTATION — the alpha clear, the suppressed palette
    * backdrop, the identity-row frame and the asset flavour of this stage's
-   * provenance. It replaced a `documentKind` prop the CALLER chose, which is
-   * exactly the origin-of-the-document reading §One stage retired: every
-   * mount that passed `documentKind="asset"` is a story, an artifact or an
-   * embedded preview, and each still answers true.
+   * provenance. It follows the stage context and look; stories, artifacts
+   * and embedded previews each use studio presentation.
    */
   // The LOOK is one of `studioStageApplies`'s live inputs (a data subject takes
   // the studio only where the look leaves the backdrop to the editor), and the
@@ -695,11 +564,8 @@ export function Object3DDocumentViewport({
   const hasShell = stageCtx !== null && identityRowApplies(stageCtx);
   const hasShellRef = useRef(hasShell);
   hasShellRef.current = hasShell;
-  // The ASSET FLAVOUR of this stage's provenance: the source adapter's
-  // `documentKind` ("derived asset", `model-asset`) and the performance
-  // source's kind. It is the studio presentation MINUS the data arm — a mesh
-  // module opens in an isolation scene but is not a derived asset — and was
-  // read off `studioStage` while the two were the same answer.
+  // Use the asset-stage flavor for the source adapter’s document kind and performance source.
+  // Studio presentation also applies to source modules, which are not derived assets.
   const assetSubject = stageCtx !== null && assetSubjectApplies(stageCtx);
   const assetSubjectRef = useRef(assetSubject);
   assetSubjectRef.current = assetSubject;
@@ -775,15 +641,6 @@ export function Object3DDocumentViewport({
       documentHostRef.current = null;
     };
   }, [documentId, rendererLane, retainedState, surfaceAttached, worldRoot]);
-  // Read through a ref: the one big lifetime effect below owns the canvas
-  // listener, and re-running it on a new handler identity would tear the whole
-  // renderer down and rebuild it.
-  const onOpenNodeRef = useRef(onOpenNode);
-  onOpenNodeRef.current = onOpenNode;
-  const frameBoundsRef = useRef(frameBounds);
-  frameBoundsRef.current = frameBounds;
-  const openingFrameBoundsRef = useRef(openingFrameBounds);
-  openingFrameBoundsRef.current = openingFrameBounds;
   const openingViewRef = useRef(openingView);
   openingViewRef.current = openingView;
   const documentPresentationRef = useRef(documentPresentation);
@@ -817,14 +674,13 @@ export function Object3DDocumentViewport({
     root: THREE.Object3D;
     animations: readonly THREE.AnimationClip[];
   } | null>(null);
-  const persistenceSessionRef = useRef<Promise<Object3DDocumentPersistenceSession> | null>(null);
+  const persistenceSessionRef = useRef<Promise<AssetDocumentPersistenceSession> | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [surfaceStatus, setSurfaceStatus] = useState<'building' | 'ready'>('building');
   // A world root's own mount state and the binding that draws its overlays.
   const [worldRootBinding, setWorldRootBinding] = useState<WorldRootStageBinding | null>(null);
   const [designMountStatus, setDesignMountStatus] = useState<'mounting' | 'ready'>('mounting');
   const [designRootIds, setDesignRootIds] = useState<readonly string[]>([]);
-  const cameraPreviewRef = useRef<HTMLDivElement | null>(null);
   const [projection, setProjection] = useState<ThreeViewportProjection>('perspective');
   // The live authoring adapter this document's inspection composes from. It
   // only exists once the graph is built, so it is state rather than a ref:
@@ -864,7 +720,8 @@ export function Object3DDocumentViewport({
       const canvasHost = canvasHostRef.current;
       if (!container || !canvasHost || documentHostRef.current) return;
       const stats = shellStatsRef.current;
-      if (!stats) {
+      const store = threeStoreForHost();
+      if (!stats || !store) {
         // The world root IS the shell's own subject — its readout, its
         // adoption stack, its transport. A bounded host has none of that.
         setError('The world root needs the editor shell above it; this host has none.');
@@ -880,7 +737,7 @@ export function Object3DDocumentViewport({
         // The world is the session's own subject: Play adoption, ingest, the
         // project history and the host door's hierarchy facet all address the
         // SESSION store, so this stage runs on it rather than a private one.
-        threeStoreForHost() ?? undefined,
+        store,
       );
       documentHostRef.current = host;
       host.cleanups.push(registerStageStore(documentId, host.store.shell));
@@ -898,7 +755,6 @@ export function Object3DDocumentViewport({
         canvas: host.surface.canvas,
         renderer: host.surface.renderer,
         stats,
-        cameraPreview: () => cameraPreviewRef.current,
         onMountStatus: setDesignMountStatus,
         onRootIds: setDesignRootIds,
         runFrame: (delta) => runViewportFrame(documentId, delta),
@@ -910,21 +766,16 @@ export function Object3DDocumentViewport({
         settle: () => Promise.resolve(),
         dispose: async () => stage.dispose(),
       };
-      // The world's tree arrives asynchronously and keeps changing, so its
-      // clip subjects are rescanned on the store's change notification,
-      // throttled, and not while Play drives time.
-      // The scene the stage DRAWS: an R3F world renders the session store's
-      // scene, not the stage's own (`world-root-stage.ts`), and scanning the
-      // latter found no subject on a world whose enemies each had a mixer.
+      // Rescan clip subjects on throttled store changes as the world tree mounts and updates.
+      // Inspect the scene the stage draws, including a session store’s scene.
       const clipScan = scanClipSubjects(() => host.store.scene ?? stage.scene, host.transport, {
         // A game makes its mixers as its world runs, not when the store changes.
-        rescanOnLiveMixers: () => host.store.shell.playState === 'stopped',
+        rescanOnLiveMixers: true,
       });
       let lastClipScan = 0;
       host.cleanups.push(() => clipScan.dispose());
       host.cleanups.push(
         host.store.shell.subscribe(() => {
-          if (host.store.shell.playState !== 'stopped') return;
           const now = performance.now();
           if (now - lastClipScan < CLIP_RESCAN_INTERVAL_MS) return;
           lastClipScan = now;
@@ -939,9 +790,10 @@ export function Object3DDocumentViewport({
             camera: stage.viewport.camera,
             drawCamera: () => stage.viewport.renderCamera,
             orbit: stage.viewport.orbitControls,
+            projection: stage.viewport.projectionOwner,
             scene: stage.scene,
+            renderer: host.surface.renderer,
           },
-          stage.present,
           stage.setHelper,
           { documentId },
         ),
@@ -1015,7 +867,7 @@ export function Object3DDocumentViewport({
       const { renderer, canvas, lease } = host.surface;
       const store = host.store;
       // This stage's store, reachable by the shared panels through
-      // `focusedStageStore()` (ARCHITECTURE-CORE §One stage unit 4). A
+      // `focusedStageStore()`. A
       // CHROMELESS preview is not a stage anything can focus — it has no
       // workspace document — so it registers nothing.
       if (!chromeless) {
@@ -1038,7 +890,7 @@ export function Object3DDocumentViewport({
       const documentState = { root: source.root, animations: source.root.animations };
       let defaultAdapter: SourceObject3DAuthoringAdapter | null = null;
       let projectAuthoring: ToolObject3DDocumentAuthoring | null = null;
-      let activePersistenceSession: Promise<Object3DDocumentPersistenceSession> | null = null;
+      let activePersistenceSession: Promise<AssetDocumentPersistenceSession> | null = null;
       let interactionExtension: ReturnType<NonNullable<typeof interaction>['setup']> | null = null;
       let gestureController: Object3DGestureController | null = null;
       let pointerDownListener: ((event: PointerEvent) => void) | null = null;
@@ -1109,8 +961,6 @@ export function Object3DDocumentViewport({
               // animation binding writes through — checksum-guarded whole-file
               // replace, recorded in canonical history — never the resource
               // route, which refuses executable source by rule.
-              if (!document)
-                throw new Error('Project history is unavailable; the edit was not saved.');
               const history = workspaceHistoryService();
               if (!history) {
                 throw new Error('Project history is unavailable; the edit was not saved.');
@@ -1133,7 +983,7 @@ export function Object3DDocumentViewport({
             if (!persistence) {
               throw new Error('This Asset Lab document has no persistence binding.');
             }
-            if (!activePersistenceSession || !document) {
+            if (!activePersistenceSession) {
               throw new Error('Project history is unavailable; the edit was not saved.');
             }
             // The pipe's ack for THIS commit: `persisted` is whether a byte moved
@@ -1181,11 +1031,8 @@ export function Object3DDocumentViewport({
           });
           defaultAdapter.dispose();
         }
-        // Project authoring may establish the module-local artifact that its
-        // serializers read (a rig document is the concrete example). Open the
-        // persistence baseline only after that factory has adopted the root;
-        // opening it before authoring made every clean rig mount reject with
-        // "Object3D is not a project rig artifact."
+        // Open the persistence baseline after the authoring factory adopts the root and
+        // establishes any module-local artifact its serializers read.
         activePersistenceSession =
           persistence && history
             ? projectWrites().openPersistence({
@@ -1214,7 +1061,8 @@ export function Object3DDocumentViewport({
           // operator into every `toneMapped` program.
           renderer.toneMapping = dressingToneMapping ?? THREE.ACESFilmicToneMapping;
           renderer.shadowMap.enabled = true;
-          renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+          // PCFShadowMap supplies the soft-shadow filter supported by this three.js release.
+          renderer.shadowMap.type = THREE.PCFShadowMap;
           renderer.info.autoReset = false;
           renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
           if (studioStage) renderer.setClearColor(0x000000, 0);
@@ -1235,8 +1083,6 @@ export function Object3DDocumentViewport({
               !studioStage &&
               background === undefined &&
               dressingBackground !== false,
-            // The stage's lights are the presentation rig's, below.
-            keyLight: false,
             grid: dressingGrid === true,
             content: source.root,
           });
@@ -1334,7 +1180,7 @@ export function Object3DDocumentViewport({
           const idOf = (start: THREE.Object3D | null): string | null => {
             for (let object = start; object; object = object.parent) {
               const id =
-                presentation?.hierarchy.idForObject3D?.(object) ?? current.hierarchy.idForObject3D?.(object);
+                presentation?.hierarchy.idForNativeObject?.(object) ?? current.hierarchy.idForNativeObject?.(object);
               if (id) return id;
             }
             return null;
@@ -1382,25 +1228,10 @@ export function Object3DDocumentViewport({
             // The same expression that places the DOM furniture, for the one
             // piece of furniture that is drawn on the canvas instead.
             chromeInsetPx: chromeless || hasShell || fillContainer ? 0 : STAGE_BLEED_PX,
-            // A document that turns the dressing's key light off has said it
-            // lights itself, and the editor's design-time rig answers exactly
-            // the same question. MEASURED on the Model stage before this
-            // existed: the rig's ambient 0.5 + directional 1.0 sit on
-            // `EDITOR_LAYER`, but three filters lights by the CAMERA's layers
-            // (`WebGLRenderer.projectObject`) and the one camera that draws
-            // this stage enables that layer to see the grid and the gizmo —
-            // so the layer scopes them away from nothing at all and they lit
-            // the content.
+            // View presentation supplies the lighting; disable the viewport's built-in rig.
             lightRig: false,
           });
           if (dressingGrid === true) host.viewport.grid.removeFromParent();
-          const open = (event: MouseEvent) => {
-            const id = pick(event.clientX, event.clientY);
-            const object = id && host.adapter ? threeObject(host.adapter.hierarchy, id) : null;
-            if (object) onOpenNodeRef.current?.(object);
-          };
-          container.addEventListener('dblclick', open);
-          host.cleanups.push(() => container.removeEventListener('dblclick', open));
         }
         const viewport = host.viewport;
         if (dressingViewLocked) {
@@ -1492,19 +1323,7 @@ export function Object3DDocumentViewport({
             event.stopPropagation();
           };
           pointerDownListener = (event) => {
-            // A control painted OVER the stage owns its own press. These
-            // listeners sit on the CONTAINER in the capture phase, so they run
-            // before that control's own handler and a `stopPropagation` there
-            // would be too late: pressing the rolled-back-operation notice's
-            // Dismiss also started a box-select on the mesh (measured — the
-            // notice's text changed from the failed op to "Box select").
-            // The viewport's navigation cluster (`ViewportFurniture`) is the
-            // same case and was missing here: its Pan button drives the camera
-            // from `onPointerDown`, which React dispatches at the root, so
-            // claiming the press here meant `startPan` never ran and the
-            // control was inert (measured — the camera floats were identical
-            // before and after a full pointer gesture, while the cluster's
-            // `onClick` buttons beside it moved the camera every time).
+            // Let controls painted over the stage own their pointer presses before the container’s capture listeners begin selection.
             if (
               event.target instanceof Element &&
               event.target.closest('[role="alert"], [role="toolbar"]') !== null
@@ -1566,7 +1385,6 @@ export function Object3DDocumentViewport({
         const previousPersistence = persistenceSessionRef.current;
         const previousInteraction = interactionExtensionRef.current;
         const previousBackground = host.session?.neutralBackgroundTexture();
-        const previousLights = host.dressing.lights.map((light) => light.visible);
         const cleanupCount = host.cleanups.length;
         const wasInitialized = host.initialized;
         rollback = () => {
@@ -1587,7 +1405,7 @@ export function Object3DDocumentViewport({
           store.objectMap.clear();
           for (const [id, object] of previousObjects) store.objectMap.set(id, object);
           if (previous)
-            store.bindScene(previous.scene, renderer, viewport.batchedRenderer, viewport.camera);
+            store.bindScene(previous.scene, renderer, viewport.camera);
           if (previousRoot && previousAdapter)
             host.session?.replaceContent(previousRoot, previousAdapter);
           documentStateRef.current = previousDocument;
@@ -1597,9 +1415,6 @@ export function Object3DDocumentViewport({
           setDocumentAdapter(previousAdapter);
           if (previousBackground !== undefined)
             host.session?.setNeutralBackground(previousBackground);
-          host.dressing?.lights.forEach((light, index) => {
-            light.visible = previousLights[index] ?? true;
-          });
           if (previousRoot) {
             host.dressing?.frameContent(previousRoot);
             host.presentationRig?.placeFloor(previousRoot);
@@ -1612,7 +1427,7 @@ export function Object3DDocumentViewport({
         host.adapter = adapter;
         host.presentationAdapter = presentationAdapter;
         host.content = binding;
-        store.bindScene(scene, renderer, viewport.batchedRenderer, viewport.camera);
+        store.bindScene(scene, renderer, viewport.camera);
         store.setOrbitTarget(viewport.orbitControls.target);
         store.objectMap.clear();
         scene.traverse((object) => {
@@ -1622,12 +1437,10 @@ export function Object3DDocumentViewport({
           // too. A Blender document names its objects only once the engine's outliner rows
           // arrive, often after this bind; the presentation ids exist from the first frame.
           const id =
-            presentationAdapter?.hierarchy.idForObject3D?.(object) ?? adapter.hierarchy.idForObject3D?.(object);
+            presentationAdapter?.hierarchy.idForNativeObject?.(object) ?? adapter.hierarchy.idForNativeObject?.(object);
           if (id) store.objectMap.set(id, object);
         });
         if (!host.session) {
-          const overviewFrame = boxFromFrameBounds(frameBoundsRef.current);
-          const openingFrame = boxFromFrameBounds(openingFrameBoundsRef.current) ?? overviewFrame;
           // The view's camera (`ViewportCamera`): its field of view, and the direction it opens
           // from when the document states none.
           const viewCamera = viewPresentation(documentId).camera;
@@ -1642,7 +1455,7 @@ export function Object3DDocumentViewport({
               .copy(target)
               .addScaledVector(new THREE.Vector3(...viewCamera.opening).normalize(), distance);
           }
-          if (!openingFrame) viewport.focusOn(source.root);
+          viewport.focusOn(source.root);
           if (stated) {
             const target = new THREE.Vector3(...stated.target);
             const direction = new THREE.Vector3(...stated.direction).normalize();
@@ -1653,7 +1466,7 @@ export function Object3DDocumentViewport({
             if (stated.up) viewport.camera.up.set(...stated.up);
             viewport.orbitControls.target.copy(target);
           } else if (statedDirection) {
-            const box = openingFrame ?? contentWorldBounds(source.root);
+            const box = contentWorldBounds(source.root);
             const center = box.getCenter(new THREE.Vector3());
             const direction = new THREE.Vector3(cameraX, cameraY, cameraZ).normalize();
             const distance =
@@ -1674,7 +1487,6 @@ export function Object3DDocumentViewport({
               : background === undefined
                 ? host.dressing.backgroundTexture
                 : new THREE.Color(background),
-            overviewFrame,
           );
           host.session.selectionOutlineEnabled = !shared && selectionOutlineRef.current;
           host.session.setCameraViewSource(cameraViewRef.current ?? null);
@@ -1686,13 +1498,8 @@ export function Object3DDocumentViewport({
             const session = host.session;
             host.cleanups.push(
               watchPaletteBackdrop(() => {
-                // THE LOOK'S BACKDROP, in both directions and through the
-                // session's neutral backdrop, which repaints what is showing: a
-                // palette's flat viewport background when it names one, the
-                // dressing's gradient re-derived for the palette otherwise.
-                // Painting the flat colour straight onto the scene left it there
-                // when the next palette named none (Plotter's paper stayed under
-                // Classic).
+                // Refresh the session's neutral backdrop from the palette's flat background,
+                // or a newly derived gradient when the palette names no flat background.
                 const flat = nativeViewportLook(canvas).background;
                 const previous = host.defaultBackground;
                 host.defaultBackground =
@@ -1771,12 +1578,7 @@ export function Object3DDocumentViewport({
           if (viewPresentation(documentId).drawMode !== mode)
             setViewPresentation(documentId, { drawMode: mode as ViewportDrawMode });
         };
-        // A document whose FILE states its draw mode keeps a person's pick there (a .blend's 3D
-        // View), so the file's statement is where the session starts. Otherwise a mode the person
-        // chose and the view restored is theirs. Only a view with neither is given the session's.
-        // Then the view takes the session's mode either way: a stored choice older than the file's
-        // statement would otherwise keep lighting the view for the mode it no longer draws (the
-        // Blender presenter dressed in Solid's materials under a Material Preview cell).
+        // Initialize draw mode from the document’s file, then the restored view, then the session default. Synchronize the view to the resulting session mode.
         const restoredMode = ownLayer?.drawMode ?? viewPresentationSnapshot(documentId).drawMode;
         if (restoredMode !== undefined && viewModes.has(restoredMode) && host.session)
           host.session.setMode(restoredMode);
@@ -1900,7 +1702,8 @@ export function Object3DDocumentViewport({
                 ? host.darkenContentLights()
                 : 0;
             rig.update(documentSession.camera());
-            reportViewDraw(documentId, {
+            // A sampled photograph draws many times; it is one draw to report.
+            if (documentSession.photographSampleIndex() === 0) reportViewDraw(documentId, {
               source: drawSource,
               presetId: rig.presetId(),
               presetLights: rig.lightsVisible(),
@@ -1919,24 +1722,21 @@ export function Object3DDocumentViewport({
           host.syncHostScene?.();
           const mode = documentSession.presentation().mode;
           const navigation = interactive && ['solid', 'preview', 'clay', 'unlit', 'matcap'].includes(mode);
-          return source.prepareDraw?.(documentSession.camera(), {interactive: navigation, height: renderer.domElement.height, multiDraw: renderer.extensions.has('WEBGL_multi_draw'), renderer});
+          return source.prepareDraw?.(documentSession.camera(), {interactive: navigation, height: renderer.domElement.height, multiDraw: renderer.extensions.has('WEBGL_multi_draw'), renderer, drawMode: mode, pixelScale: documentSession.drawPixelScale(), photograph: documentSession.photographing()});
         });
         // This loop draws the compass and every other overlay pass over the
         // document's own render, so it — and only it — can serve the chrome
         // door a frame that matches the screen.
         documentSession.setPresentsFrames(true);
-        // THE CONTENT-TIME DOOR, re-created in Step 3 with exactly one caller
-        // (the transport's `tick` below). The mixer line the deleted estate
-        // had here is gone for good: subjects seek THEMSELVES, so content time
-        // is only ever the bookkeeping plus the source's own update.
+        // Advance content-time bookkeeping and the source’s update. Animation subjects seek
+        // themselves through their own transport.
         const advanceContent = (deltaSeconds: number): void => {
           if (disposed || !(deltaSeconds > 0) || !Number.isFinite(deltaSeconds)) return;
           host.contentSeconds += deltaSeconds;
           host.transportAdvances++;
           source.update?.(deltaSeconds);
         };
-        // What this stage can show at a time. Scanned once here; the world
-        // root's stage rescans (below) because its tree arrives later.
+        // Scan this source's animation subjects once. World-root stages rescan as their trees update.
         const clipScan = scanClipSubjects(source.root, host.transport);
         host.cleanups.push(() => clipScan.dispose());
         const retainedTransport = retainedState.transport;
@@ -1951,37 +1751,41 @@ export function Object3DDocumentViewport({
           retainedState.transport = null;
         }
         let previousTime = performance.now();
-        // DRAWING ON CHANGE. A source that announces its changes
-        // (`ToolObject3DPreviewSource.onChange`) is drawn only when something
-        // changed; one that does not is drawn every frame, as before. The loop
-        // itself still runs every frame -- transport, controls, flights and
-        // presence advance there -- and what is skipped is the render: the
-        // scene, the composer's passes and the compass. MEASURED before: an
-        // idle Model document spent 43% of the main thread drawing the same
-        // picture (4 s at load ~30: 372 frames, 1.7 s in the loop, 0.18 s of
-        // it WebGL calls, the rest three's render and the outline passes).
-        //
-        // What draws a frame: the content's own announcement; the stage
-        // store; pointer, wheel and key input on the stage (hover and gizmo
-        // highlights follow the pointer); the editor acting on a stage from
-        // outside those (`stage-invalidation.ts`); a moved camera or a resized
-        // surface; playback; a flight or a pending photograph
-        // (`needsFrame`); another participant's markers; particle systems;
-        // and an interaction extension that refines every frame.
+        // Draw on announced content changes, stage state or interaction, camera/size changes, playback, flights, captures, presence, particles and active interaction extensions. Sources without onChange draw each frame; the presentation loop always advances.
         const drawsOnChange = typeof source.onChange === 'function';
         let dirty = true;
+        // Every signal, counted: a signal that arrives while a frame draws (a source answering its
+        // own draw) is not cleared by that frame, and the count is the content's REVISION, which a
+        // live accumulation's sum belongs to.
+        let changeCount = 0;
         const markDirty = (): void => {
           dirty = true;
+          changeCount++;
+        };
+        // A pointer moving over the stage draws a frame (hover highlights follow it), but it is a
+        // change of the picture only when it changes what the stage draws: the furniture's hover
+        // and drag state (`EditorViewport.interactionState`) or the camera, both compared below.
+        // A press, a release, the wheel and keys still count as changes, and so does a move with
+        // a button held: a drag moves things whether or not what it moves signals (a gizmo drag in
+        // a Blender view writes the object's matrix in place). An active drag or gesture is a
+        // change on every frame too (`changedSinceDrawn`).
+        let inputPending = false;
+        const markInput = (event: Event): void => {
+          if ((event as PointerEvent).buttons) markDirty();
+          else inputPending = true;
         };
         if (drawsOnChange) {
           const stopSource = source.onChange!(markDirty);
           const stopStore = store.shell.subscribe(markDirty);
-          const inputs = ['pointerdown', 'pointermove', 'pointerup', 'pointerleave', 'wheel', 'keydown', 'keyup'] as const;
-          for (const type of inputs) container.addEventListener(type, markDirty, { capture: true, passive: true });
+          const changes = ['pointerdown', 'pointerup', 'wheel', 'keydown', 'keyup'] as const;
+          const moves = ['pointermove', 'pointerleave'] as const;
+          for (const type of changes) container.addEventListener(type, markDirty, { capture: true, passive: true });
+          for (const type of moves) container.addEventListener(type, markInput, { capture: true, passive: true });
           stopDrawSignals = () => {
             stopSource();
             stopStore();
-            for (const type of inputs) container.removeEventListener(type, markDirty, { capture: true });
+            for (const type of changes) container.removeEventListener(type, markDirty, { capture: true });
+            for (const type of moves) container.removeEventListener(type, markInput, { capture: true });
           };
         }
         let drawnGeneration = -1;
@@ -1992,13 +1796,36 @@ export function Object3DDocumentViewport({
         let drawnBackground: unknown = undefined;
         let drawnToneMapping: THREE.ToneMapping | null = null;
         let drawnExposure = Number.NaN;
-        const mustDraw = (advanced: number): boolean => {
+        let drawnInteraction = '';
+        // The signals already taken when the frame being drawn began.
+        let changeCountAtDraw = 0;
+        let generationAtDraw = -1;
+        // What a draw mirrors into the stage's scene (the host's world, its tone), BY VALUE: a
+        // backdrop colour is handed over as a fresh instance on every draw, so identity would read
+        // every draw as a change. A still frame that changes it is followed by a changed one.
+        const valueOf = (value: THREE.Color | THREE.Texture | null): string =>
+          !value ? '-' : (value as THREE.Color).isColor ? `#${(value as THREE.Color).getHexString()}` : (value as THREE.Texture).uuid;
+        const mirroredState = (): readonly unknown[] => {
+          const fog = host.scene.fog as (THREE.Fog & THREE.FogExp2) | null;
+          return [
+            valueOf(host.scene.background as THREE.Color | THREE.Texture | null),
+            valueOf(host.scene.environment),
+            fog ? `${fog.color.getHexString()}|${fog.near}|${fog.far}|${fog.density}` : '-',
+            host.scene.backgroundIntensity, host.scene.backgroundBlurriness, host.scene.environmentIntensity,
+            renderer.toneMapping, renderer.toneMappingExposure,
+          ];
+        };
+        // What changed since the last drawn frame. A frame drawn with nothing changed (a
+        // presented-frame request, the live view's accumulation going on) is a still one.
+        const changedSinceDrawn = (advanced: number): boolean => {
           if (!drawsOnChange || dirty || advanced > 0) return true;
           if (stageGeneration() !== drawnGeneration) return true;
-          if (documentSession.needsFrame() || host.presence?.live()) return true;
+          if (host.presence?.live()) return true;
           if (interactionExtension?.prepareFrame || interactionExtension?.update) return true;
           if (((viewport.batchedRenderer as unknown as { batches?: readonly unknown[] }).batches?.length ?? 0) > 0)
             return true;
+          if (viewport.interacting() || gestureController?.hasActiveGesture()) return true;
+          if (viewport.interactionState() !== drawnInteraction) return true;
           const camera = documentSession.camera();
           camera.updateMatrixWorld();
           renderer.getDrawingBufferSize(currentSize);
@@ -2010,8 +1837,10 @@ export function Object3DDocumentViewport({
             renderer.toneMappingExposure !== drawnExposure;
         };
         const noteDrawn = (): void => {
-          dirty = false;
-          drawnGeneration = stageGeneration();
+          dirty = changeCount !== changeCountAtDraw;
+          inputPending = false;
+          drawnGeneration = generationAtDraw;
+          drawnInteraction = viewport.interactionState();
           const camera = documentSession.camera();
           drawnCamera.copy(camera.matrixWorld);
           drawnProjection.copy(camera.projectionMatrix);
@@ -2022,15 +1851,12 @@ export function Object3DDocumentViewport({
         };
         let navigationMeasurement: THREE.Quaternion | null = null;
         const animate = (time: number, resumed: boolean) => {
-          if (disposed || !renderer || !viewport) return;
+          if (disposed) return;
           const activeRenderer = renderer;
           const activeViewport = viewport;
-          const profiler = documentSession?.profiler;
-          profiler?.beginFrame();
           if (resumed) previousTime = time;
           const delta = Math.min((time - previousTime) / 1000, 0.1);
           previousTime = time;
-          profiler?.beginPhase();
           // CONTENT TIME moves ONLY through the stage transport, and only
           // while a human is holding it: `tick` is inert unless playing and
           // the editor drives, and it returns exactly the seconds it advanced.
@@ -2038,8 +1864,6 @@ export function Object3DDocumentViewport({
           if (advanced > 0) advanceContent(advanced);
           interactionExtension?.prepareFrame?.(delta);
           interactionExtension?.update?.(delta);
-          profiler?.endPhase('animation');
-          profiler?.beginPhase();
           host.presence?.syncMarkers(delta);
           viewport.update(delta);
           // This stage's frame hook. After viewport.update, the same order the
@@ -2052,12 +1876,15 @@ export function Object3DDocumentViewport({
             camera.updateMatrixWorld(true);
           }
           viewport.batchedRenderer.update(delta);
-          profiler?.endPhase('editor');
-          if (!resumed && !mustDraw(advanced)) {
-            profiler?.endFrame();
+          // THE LIVE VIEW ACCUMULATES while nothing changes, one sample a frame, as Blender's
+          // viewport does (`Object3DDocumentSession.renderViewport`'s `still`).
+          const changed = resumed || navigationMeasurement !== null || changedSinceDrawn(advanced);
+          if (!changed && !inputPending && !documentSession.needsFrame() && !documentSession.accumulating()) {
             return;
           }
-          profiler?.beginPhase();
+          changeCountAtDraw = changeCount;
+          generationAtDraw = stageGeneration();
+          const mirroredBefore = changed ? null : mirroredState();
           activeRenderer.info.reset();
           const timeFirstRender =
             !firstFrameGateRef.current && activeViewportBreakdownDocumentId() === documentId;
@@ -2072,33 +1899,30 @@ export function Object3DDocumentViewport({
               // Photographs and the default frame-cost reading draw the
               // full resident scene. Only navigation may use source-owned
               // temporary geometry; the source restores it after the draw.
-              documentSession.renderViewport(delta, navigationMeasurement !== null || (!resumed && !documentSession.needsFrame()));
+              documentSession.renderViewport(
+                delta,
+                navigationMeasurement !== null || (!resumed && !documentSession.needsFrame()),
+                !changed,
+                `${changeCountAtDraw}/${generationAtDraw}`,
+              );
               activeViewport.renderViewCube(activeRenderer);
             });
           } finally {
             host.scene.overrideMaterial = presentationOverride;
           }
+          // A still frame whose draw changed what the stage mirrors starts the sum over next frame.
+          if (mirroredBefore && mirroredState().some((value, index) => value !== mirroredBefore[index])) markDirty();
           // Inside the frame that drew them — the canvas has no
           // preserveDrawingBuffer, so this is the only moment its pixels exist.
           documentSession.servePresentedFrame();
           noteDrawn();
           if (!firstFrameGateRef.current) {
             firstFrameGateRef.current = true;
-            if (timeFirstRender) markViewportSegment('first-render', Date.now() - tFirstRender);
+            if (timeFirstRender) markViewportFirstRender(Date.now() - tFirstRender);
             recordViewportFirstFrame(documentId);
             setSurfaceStatus('ready');
           }
-          profiler?.reportRender({
-            gpuMs: null,
-            drawCalls: activeRenderer.info.render.calls,
-            triangles: activeRenderer.info.render.triangles,
-            geometries: activeRenderer.info.memory.geometries,
-            textures: activeRenderer.info.memory.textures,
-          });
-          profiler?.endPhase('render');
-          profiler?.endFrame();
-          // THE SHELL'S READOUT IS THE FOCUSED STAGE'S (ARCHITECTURE-CORE
-          // §One stage unit 4). `CameraInfo` and `StatsOverlay` read one
+          // THE SHELL'S READOUT IS THE FOCUSED STAGE'S. `CameraInfo` and `StatsOverlay` read one
           // struct the shell owns; the stage the panels are following fills
           // it, so a model or prefab document reports ITS frame and ITS
           // camera. Inactive documents leave the shared readout alone.
@@ -2124,8 +1948,7 @@ export function Object3DDocumentViewport({
          * resumed so it draws, run back to back and each waited out on the GPU with a one-pixel
          * read, which a real frame never does; the first frame warms and is not counted.
          */
-        const measureFrameCost = (frames: number, quality: 'full' | 'navigation' = 'full'): StageFrameCost => {
-          if (!renderer) throw new Error('This stage has no renderer yet.');
+        const measureFrameCost = (frames: number, quality: 'full' | 'navigation'): StageFrameCost => {
           const activeRenderer = renderer;
           const gl = activeRenderer.getContext();
           const pixel = new Uint8Array(4);
@@ -2170,17 +1993,17 @@ export function Object3DDocumentViewport({
             sceneTriangles += Math.floor(count / 3) * ((mesh as THREE.InstancedMesh).count ?? 1);
           });
           const sorted = [...times].sort((a, b) => a - b);
-          const at = (q: number) => sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))] ?? 0;
+          const at = (q: number) => sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))]!;
           const size = activeRenderer.getDrawingBufferSize(new THREE.Vector2());
           const ratio = activeRenderer.getPixelRatio();
           const round = (value: number) => Math.round(value * 100) / 100;
-          const median = (values: number[]) => round(values.sort((a, b) => a - b)[Math.floor(values.length / 2)] ?? 0);
+          const median = (values: number[]) => round(values.sort((a, b) => a - b)[Math.floor(values.length / 2)]!);
           return {
             frames,
             quality,
             medianMs: round(at(0.5)),
             p95Ms: round(at(0.95)),
-            minMs: round(sorted[0] ?? 0),
+            minMs: round(sorted[0]!),
             submitMedianMs: median(submitTimes),
             completionWaitMedianMs: median(completionTimes),
             width: size.x,
@@ -2197,13 +2020,7 @@ export function Object3DDocumentViewport({
         if (!host.initialized) {
           if (!chromeless) {
             // --- The viewport door (viewport-door.ts) ---
-            // This host is ONE STAGE among the mounted 3D documents
-            // (ARCHITECTURE-CORE §One stage), and it binds under the id of the
-            // document it draws, so an SDK reader reaches THIS stage's rig,
-            // helper sink and frame loop through the viewport door's `viewportStages()`.
-            // It presents no live roots yet — Play's adoption is the world
-            // root's, and moves onto this host in unit 3 — so the presenter
-            // declines every root rather than pretending to a subject.
+            // Bind this document's rig, helper sink and frame loop. Its presenter declines live roots.
             // A CHROMELESS mount (the inspector's object preview) binds
             // nothing: it is a thumbnail of a document, not a stage of its own,
             // and several can be alive for one document id at once.
@@ -2213,23 +2030,17 @@ export function Object3DDocumentViewport({
                   camera: viewport.camera,
                   drawCamera: () => host.session?.camera() ?? viewport.camera,
                   orbit: viewport.orbitControls,
+                  projection: viewport.projectionOwner,
                   scene: host.scene,
+                  renderer: host.surface.renderer,
                   frameCost: (frames, quality) => measureFrameCost(frames, quality),
                 },
-                () => null,
                 (kind, object) => viewport.setHelper(kind, object),
                 { documentId },
               ),
             );
-            // --- The other participants, on THIS stage ---
-            // Presence was the scene panel's, so only the world root had it.
-            // It is a capability with a condition — a stage painting a three
-            // surface — and a `build` stage always paints one, so every
-            // document with chrome mounts it and a prefab story shows the
-            // same camera frusta, selection boxes and pointer rays the Scene
-            // does (ARCHITECTURE-CORE §One stage; WORK.md §Presence and the
-            // substrate, presence unit 4). Dynamically imported: it reaches
-            // the collaboration client, which a bounded host must not pay for.
+            // Mount participant camera frusta, selection boxes and pointer rays on chromed three.js
+            // stages. Load the collaboration client dynamically so bounded hosts do not import it.
             void import('./stage-presence-markers').then((markers) => {
               if (host.isClosed || documentHostRef.current !== host || host.presence) return;
               const binding = markers.bindStagePresenceMarkers({
@@ -2259,24 +2070,13 @@ export function Object3DDocumentViewport({
             host.cleanups.push(
               registerObject3DDocumentSession(documentSession, threeStageTransformChrome(documentId)),
             );
-            host.cleanups.push(
-              registerPerformanceSource({
-                id: documentId,
-                label: displayName,
-                kind: assetSubject ? 'asset' : 'source',
-                profiler: documentSession.profiler,
-              }),
-            );
           }
           // EXACTLY ONE registrar of this document's workspace selection: the
           // identity-row shell does it through its own `selection` prop, so
-          // the host does it wherever that shell is absent. The condition was
-          // `!studioStage` while the shell and the studio were the same
-          // answer; they parted when a DATA subject gained the studio
-          // (§A model is data), and reading the old one left the Model
-          // document with NEITHER registrar — the Hierarchy said "No
-          // authoring adapter" and the mesh inspector emptied (measured live
-          // on the models scaffold, 2026-09-18).
+          // the host does it wherever that shell is absent. The shell and the
+          // studio are different answers (a data subject has the studio),
+          // so `!studioStage` would leave the Model document
+          // with NEITHER registrar.
           if (!chromeless && !hasShell) {
             host.cleanups.push(
               registerWorkspaceDocumentSelection(documentId, () => ({
@@ -2296,12 +2096,8 @@ export function Object3DDocumentViewport({
               transportAdvances: () => host.transportAdvances,
             }),
           );
-          // THE VIEWPORT ACTION BUS, on a document stage. The world root has
-          // answered these since the scene panel existed; a document stage
-          // never did, which is why Frame (`F`) was inert on a prefab or a
-          // model — the hotkey pushes `focus-selection` onto the stage's own
-          // store and nothing was listening (ARCHITECTURE-CORE §One stage:
-          // the capability is present wherever its condition holds).
+          // Listen to the document stage’s viewport action bus so commands such as focus-selection
+          // reach the stage’s own store.
           host.cleanups.push(
             store.shell.onViewportAction((action) => {
               switch (action.type) {
@@ -2469,6 +2265,8 @@ export function Object3DDocumentViewport({
     }
     // A world root keeps its clock while another document holds focus.
     session.setActive(active || worldRoot);
+    // A hidden stage keeps no live accumulation (its targets are the drawing buffer's size).
+    if (!active) documentHostRef.current?.session?.releaseLive();
   }, [active, documentId, worldRoot]);
 
   // The stage's own handle for the capabilities that drive it directly (the
@@ -2518,12 +2316,7 @@ export function Object3DDocumentViewport({
         style={{ position: 'absolute', inset: 0, minHeight: 0, overflow: 'hidden' }}
       >
         <ViewportSurface canvasHostRef={canvasHostRef} />
-        {/* WHICH KEYS THIS STAGE ANSWERS — the transform modes, the view
-            presets, Frame, pivot, snap. Beside the stage rather than inside
-            the overlay set, because a package-contributed document mounts
-            with no shell above it and reached none of them
-            (`stage-keyboard.tsx`). The registry holds ONE stage's set, so the
-            condition is the ACTIVE document's stage. */}
+        {/* The active document's stage owns transform, view, Frame, pivot and snap keys. */}
         {active && stageHandle && !chromeless ? (
           <Suspense fallback={null}>
             <LazyStageKeyboard stage={stageHandle} />
@@ -2547,47 +2340,16 @@ export function Object3DDocumentViewport({
           <worldRootBinding.Overlays
             store={shellStore}
             documentId={documentId}
-            cameraPreviewRef={cameraPreviewRef}
             mountStatus={designMountStatus}
             rootIds={designRootIds}
           />
         ) : null}
-        {/* A ROLLED-BACK operation (an animation write, a capture, a source
-            write the history guarded) — every writer of `error` restores the
-            prior state, so the surface below is live and must stay visible.
-            It used to mount a full-bleed opaque curtain with no dismiss: the
-            stage read as dead until the session restarted (measured). A
-            notice over the stage, dismissible, and cleared by the next
-            gesture that succeeds. */}
+        {/* Show a dismissible error notice over any stage that remains available. */}
         {error && (
-          <div
-            role="alert"
-            style={{
-              position: 'absolute',
-              insetInline: 0,
-              top: 0,
-              display: 'flex',
-              justifyContent: 'center',
-              padding: 'var(--volter-space-3)',
-              pointerEvents: 'none',
-            }}
-          >
-            <div
-              className="volter-chrome-island"
-              style={{
-                display: 'flex',
-                alignItems: 'center',
-                gap: 'var(--volter-space-3)',
-                maxWidth: '80%',
-                padding: 'var(--volter-space-2) var(--volter-space-3)',
-                borderRadius: 'var(--volter-radius-md)',
-                border: `var(--volter-stroke-resting) solid ${themeVars.semantic.danger}`,
-                background: themeVars.surface.raised,
-                color: themeVars.semantic.danger,
-                pointerEvents: 'auto',
-              }}
-            >
-              <span>{error}</span>
+          <EditorBanner
+            tone="error"
+            style={{ position: 'absolute', insetInline: 0, top: 0 }}
+            actions={
               <IconButton
                 size="compact"
                 aria-label="Dismiss"
@@ -2596,21 +2358,15 @@ export function Object3DDocumentViewport({
               >
                 <EditorIcon icon={editorIcons.action.close} />
               </IconButton>
-            </div>
-          </div>
+            }
+          >
+            {error}
+          </EditorBanner>
         )}
-        {!error && surfaceStatus === 'building' && (
-          <ViewportSurfaceStatus testId="object3d-document-status">
-            {OBJECT3D_SURFACE_BUILDING}
-          </ViewportSurfaceStatus>
+        {!error && !chromeless && surfaceStatus === 'building' && (
+          <Progress documentId={documentId} title="Preparing the viewport" />
         )}
-        {/* The stage BLEEDS 12px under the dock panel's padding (`inset: -12`
-            above) so the rendered image fills it edge to edge. The furniture is
-            CHROME, not image: it has to sit inside the panel the person can
-            actually see, so it gets that bleed back. Without this the view text
-            started at page x=-6 — the "U" of "User Perspective" was clipped off
-            the window — and the navigation cluster's right edge landed 4px past
-            the panel, under the Inspector's section rail (both measured). */}
+        {/* Inset furniture by the canvas bleed so chrome stays inside the visible panel. */}
         <div
           style={{
             position: 'absolute',
@@ -2654,9 +2410,6 @@ export function Object3DDocumentViewport({
     >
       <div className="volter-object3d-asset-workspace">
         {viewport}
-        {/* Where the deleted preview strip was. It draws nothing until this
-            stage's transport has a subject, so a document with nothing to show
-            at a time is unchanged. */}
         <TransportStrip transport={documentHostRef.current?.transport ?? null} />
       </div>
     </AssetEditorShell>