@volter/editor-blender 0.1.150 → 0.1.151

package/contributions/blender-runtime.document.tsx

@@ -1,53 +1,27 @@
-/**
- * THE MODEL DOCUMENT — Blender's, and Blender's alone (ARCHITECTURE-CORE §The
- * project model, "A model is Blender data, and a prefab is not a model";
- * WORK.md §Blender in the tab is Blender, "The mesh kit retires", M1).
- *
- * This module declares `documentKind = 'model'`, so the host opens every
- * `model` entry the project's table lists as its OWN document — titled by the
- * entry's label, one per entry — and mounts this with the entry as
- * `props.document`. A `model` entry names a `.blend`
- * (`models.finder.ts`), and opening the document OPENS THAT FILE IN THE
- * ENGINE: `session.py` opens the named file at start and saves back to it, so
- * this is the WS-F save path run backwards.
- *
- * bpy owns every mutation; this document displays them. A gesture is a bpy
- * call the engine records — there is no cage, no append-per-gesture and no
- * TypeScript geometry module. The bpy scripts that authored a `.blend` are
- * ordinary project files beside it (`src/models/<name>.py`); this document
- * does not run them, a person or an agent does, through the session's Blender
- * (`volter blender-mcp`).
- *
- * WITHOUT AN ENTRY it is still the document `blender-start` presents into: a
- * project that lists no `.blend` of its own gets one Model document at the
- * standing `blender:runtime` address (`models.finder.ts` lists it), and
- * the session opens its default `models/model.blend`.
- */
 
-// How the `model` stage this document builds behaves (its starting presentation).
+
 import './blender-properties-context';
-import { liveAnimation, setLiveAnimation } from '../src/play-live';
 import { blenderViewFieldOfView } from '../src/presentation';
 import {
+  type BlenderDrawOptions,
   type BlenderRuntimeView,
   blenderModelView,
 } from '@volter/blender-engine/browser/three/blender-runtime-view';
-import { ownedSurfaceMaterial } from '@volter/blender-engine/browser/three/blender-physical-material';
 import { createBlenderDisplayTransform, type BlenderDisplayTransform } from '@volter/blender-engine/browser/three/blender-display-transform';
-import type { ToolContributionProps, ToolDocumentToolbar } from '@volter/sdk/contributions';
+import type { DocumentWorkingCopy, ToolContributionProps, ToolDocumentToolbar } from '@volter/sdk/contributions';
 import { editorHost } from '@volter/sdk/host';
 import {
   documentViewport,
   documentViewportsVersion,
   subscribeDocumentViewports,
-} from '@volter/sdk/kit/document-viewports';
+} from '@volter/sdk/document-viewports';
 import {
   DOCUMENT_STUDIO_PRESET,
   setViewPresentation,
   subscribeViewportPresentation,
   viewPresentation,
   viewPresentationSnapshot,
-} from '@volter/sdk/kit/viewport-presentation';
+} from '@volter/sdk/viewport-presentation';
 import {
   type MouseEvent as ReactMouseEvent,
   type PointerEvent as ReactPointerEvent,
@@ -57,6 +31,7 @@ import {
   useLayoutEffect,
   useMemo,
   useRef,
+  type RefObject,
   useState,
   useSyncExternalStore,
 } from 'react';
@@ -64,46 +39,51 @@ import * as THREE from 'three';
 import {
   bindModelDocument,
   blenderExecute,
-  blenderRna,
-  blenderRnaContext,
   subscribeBlenderRna,
   blenderViewShading,
   openModelDocumentBlend,
   modelDocumentMayOpen,
   modelDocumentOwnsPresentation,
   blenderActionClip,
+  blenderSceneMovie,
   blenderRnaVersion,
+  blenderPresentDocument,
+  modelDocumentDirty,
+  restoreModelDocument,
+  revertModelDocument,
+  saveModelDocument,
+  snapshotModelDocument,
+  subscribeModelDocumentDirty,
 } from '../host/blender-runtime-host';
 import { BlenderObjectModeHeader } from './blender-header-menus';
 import { blenderOutlinerAuthoringFor, createBlenderOutlinerAuthoring } from './blender-outliner-authoring';
 import { blenderSkin } from './blender-runtime-skin';
-import { playAnimation, type PlayAnimation, type PlayClipCache } from './blender-play-skin';
 
-/** Clip reads per model document, kept across Plays (`PlayClipCache`). */
-const playClipCaches = new Map<string, PlayClipCache>();
 import { areaSplit, subscribeAreaSplit } from '../src/area-split';
-import { noteModelDocument } from '../src/play-mode';
-import { documentPlayExtension, subscribeDocumentPlayExtensions } from '@volter/sdk/kit/document-play-extension';
-import { notifyWorkspaceDocumentSelectionChanged } from '@volter/sdk/kit/workspace-document-registry';
+import { noteModelDocument, noteModelOpening } from '../src/play-mode';
+import { type DocumentPlayEditArea, modelPlayExtension, subscribeModelPlayExtension } from '../src/model-play-extension';
+import { notifyWorkspaceDocumentSelectionChanged } from '@volter/sdk/workspace-document-registry';
 import {
   documentSecondAreaHeader,
   setDocumentSecondArea,
   subscribeDocumentAreas,
-} from '@volter/sdk/kit/document-areas';
+} from '@volter/sdk/document-areas';
 import { createPortal } from 'react-dom';
 import { onViewportStages, viewportStages } from '@volter/editor-threejs/viewport-door';
 import {
   object3DDocumentSession,
+  registerObject3DDocumentPreparation,
   subscribeObject3DDocumentSessions,
 } from '@volter/editor-threejs/kit/authoring/object3d-document-session-registry';
 import type { ToolObject3DAuthoringProps } from '@volter/editor-threejs/object3d-contributions';
-import { stageStore, subscribeStageStores } from '@volter/sdk/kit/stage-store-registry';
-import { surfaceAcceptsKey } from '@volter/sdk/kit/surface-keyboard';
+import { stageStore, subscribeStageStores } from '@volter/sdk/stage-store-registry';
+import { surfaceAcceptsKey } from '@volter/sdk/surface-keyboard';
 import { BlenderModelOpening } from './blender-model-opening';
 import { modelOpeningErrorMessage } from '../src/model-opening-error';
-import { commandLine } from '@volter/sdk/kit/product-command';
-import { fontSizeVar, spaceVar, themeVars } from '@volter/sdk/widgets';
-import { clearStartupFailure, reportStartupFailure } from '@volter/sdk/kit/startup-failure';
+import { commandLine } from '@volter/sdk/product-command';
+import { Button, fontSizeVar, spaceVar, themeVars } from '@volter/sdk/widgets';
+import { modelDocumentSaveNotice, subscribeModelDocumentSaving } from '../src/model-document-saving';
+import { clearStartupFailure, reportStartupFailure } from '@volter/sdk/startup-failure';
 
 /** This document's model open, as a source in the page's startup-failure registry. */
 const MODEL_OPEN_STARTUP_SOURCE = 'blender-model-open';
@@ -132,37 +112,28 @@ const overlaysOpened = new WeakSet<object>();
 export const point = 'workspace.document';
 export const title = 'Blender Model';
 
-/**
- * THE DOCUMENT'S HEADER IS BLENDER'S 3D VIEWPORT HEADER — Select, Add and
- * Object, the menu words `VIEW3D_MT_editor_menus` draws in Object Mode. The
- * rows, their order and what View's absence means are
- * `blender-header-menus.tsx`'s own header; this is the one line the host's
- * strip mounts (`ToolDocumentToolbar`, `DocumentHeaderStrip`).
- */
+/** Object-mode menus mounted in the document toolbar. */
 export const Toolbar: ToolDocumentToolbar = ({ documentId, notify }) => (
   <BlenderObjectModeHeader documentId={documentId} notify={notify} />
 );
 /** The kind this document EDITS: every `model` table entry opens here. */
 export const documentKind = 'model';
-/**
- * ON A MODEL DOCUMENT THE PROPERTIES RAIL IS BLENDER'S, AND BLENDER'S ALONE
- * (owner ruling; WORK.md §Blender in the tab is Blender, "Inspection parity",
- * I2 decision 1).
- *
- * Blender's Properties editor draws the tabs `ED_buttons_tabs_list` returns
- * (`space_buttons/space_buttons.cc:201-255`) and nothing else. A rail that
- * carried the host's own Preview, Transform, generic Object, Geometry and
- * Materials blocks beside Blender's sixteen would not be Blender's rail — it
- * would be Blender's rail plus another editor's, and the second editor would
- * be showing three.js's reading of data Blender owns.
- *
- * Declaring this stands the host's sections down for THIS document only: the
- * composer keeps the sections contributed by this contribution's own package
- * (`@volter/editor-blender`) and nothing else (`inspection/compose.ts`,
- * `OwnedInspectorRail`). `inspectorBuiltins` is empty — there is no host block
- * a Blender tab does not already answer for, and the Preview in particular is
- * the document's own viewport, which is the whole centre of the screen.
- */
+
+/** The Model is a workbench working copy: the workbench owns dirty state, Save, Revert, autosave and backup. Blender writes the file; the session’s delta route carries only changed chunks. */
+export const workingCopy: DocumentWorkingCopy = {
+  dirty: (document) => document.source !== undefined && modelDocumentDirty(document.source.path),
+  subscribe: subscribeModelDocumentDirty,
+  save: (document) => saveModelDocument(blendOf(document)),
+  revert: (document) => revertModelDocument(blendOf(document)),
+  backup: (document) => snapshotModelDocument(blendOf(document)),
+  restore: (document, content) => restoreModelDocument(blendOf(document), content),
+};
+
+function blendOf(document: { readonly source?: { readonly path: string } }): string {
+  if (!document.source) throw new Error('A model document without a .blend has no working copy.');
+  return document.source.path;
+}
+/** The Model document owns its Properties rail. Compose only this package’s sections and no host inspector builtins; Blender’s tabs inspect the data while the central viewport supplies the preview. */
 export const inspectorRail = 'owned';
 export const inspectorBuiltins: readonly string[] = [];
 
@@ -244,6 +215,19 @@ function readsOf(view: AreaView): AreaReads {
   return reads;
 }
 
+/** A canvas as a PNG data URL, encoded by `toBlob` (off the main thread); null when it cannot be. */
+function pngDataUrl(canvas: HTMLCanvasElement): Promise<string | null> {
+  return new Promise((resolve) => {
+    canvas.toBlob((blob) => {
+      if (!blob) { resolve(null); return; }
+      const reader = new FileReader();
+      reader.onload = () => resolve(String(reader.result));
+      reader.onerror = () => resolve(null);
+      reader.readAsDataURL(blob);
+    }, 'image/png');
+  });
+}
+
 export default function BlenderModelDocument(props: ToolContributionProps) {
   const { active, document, documentId, notify, publishContext } = props;
   const blend = document?.source?.path;
@@ -253,6 +237,7 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
   /** What a slow open is waiting on, once it has been slow (`MODEL_OPEN_NOTE_AFTER_MS`). */
   const [stillOpening, setStillOpening] = useState<string | null>(null);
   const [attempt, setAttempt] = useState(0);
+  const saveNotice = useSyncExternalStore(subscribeModelDocumentSaving, () => modelDocumentSaveNotice(blend), () => null);
   const project = editorHost().projectLocalState.projectRootPath();
   const preview = useSyncExternalStore(subscribeModelDocumentPreview, () => modelDocumentPreview(project), () => null);
   const viewportVersion = useSyncExternalStore(subscribeDocumentViewports, documentViewportsVersion, documentViewportsVersion);
@@ -261,6 +246,10 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
   callbacks.current = { notify, publishContext };
 
   useEffect(() => editorHost().session.onEnded(clearModelDocumentPreview), []);
+  // WHILE ITS FILE OPENS, the Game panel's verbs wait for this document rather than answer that no model is open
+  // (`../src/play-mode.ts`, `noteModelOpening`); once presented, its viewport serves the panel (`noteModelDocument`).
+  const presented = opened?.key === key;
+  useEffect(() => (active === false || !documentId || presented ? undefined : noteModelOpening(documentId)), [active, documentId, presented]);
   // Retain a bounded photograph while the stage is healthy. Teardown can
   // already have changed its scene/camera, so it is too late to re-render then.
   useEffect(() => {
@@ -285,7 +274,10 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
           const context = copy.getContext('2d');
           if (context) {
             context.drawImage(frame, 0, 0, copy.width, copy.height);
-            lastFrame.current = { project, entryId, path: blend ?? 'Model', image: copy.toDataURL('image/png'), capturedAt: performance.now() };
+            // Encode the PNG with toBlob off the main thread to keep Play frames responsive.
+            const image = await pngDataUrl(copy);
+            if (cancelled || !image) return;
+            lastFrame.current = { project, entryId, path: blend ?? 'Model', image, capturedAt: performance.now() };
             rememberModelDocumentPreview(lastFrame.current);
           }
         }
@@ -334,7 +326,8 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
       declined = false;
       try {
         if (binding) {
-          if (!await openModelDocumentBlend(binding, publish)) { declined = true; return; }
+          const reload = attempt > 0 && modelDocumentSaveNotice(binding.blend) !== null;
+          if (!await openModelDocumentBlend(binding, publish, reload)) { declined = true; return; }
         } else {
           // The standing Model document is the explicit blender-start target.
           publish();
@@ -365,10 +358,7 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
         starting = false;
       }
     };
-    // A SLOW OPEN SAYS WHAT IT IS WAITING ON (2026-10-06 audit: "Opening model…" had no word
-    // past its spinner, and a declined open sat there indefinitely). It is progress, never an
-    // error, and it offers no Retry (#147 review): the open is still running, and a second one
-    // would queue behind it. A real failure arrives through the catch above.
+    // A long open reports progress while its request runs. Retry is offered only for an actual failure, avoiding a second queued open.
     const slow = setInterval(() => {
       if (cancelled || finished) return;
       setStillOpening(declined
@@ -409,6 +399,17 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
   />;
   return <>
     <BlenderModelViewport {...props} />
+    {saveNotice && <div role="alert" data-testid="blender-model-not-saving"
+      style={{ position: 'absolute', top: spaceVar[3], left: spaceVar[3], right: spaceVar[3], zIndex: 2,
+        background: themeVars.surface.chrome, color: themeVars.content.primary,
+        border: `1px solid ${themeVars.semantic.warning}`, padding: spaceVar[3], fontSize: fontSizeVar.sm }}>
+      <strong>Model is not being saved</strong>
+      <div style={{ marginTop: spaceVar[2], marginBottom: spaceVar[3], userSelect: 'text' }}>{saveNotice}</div>
+      <div style={{ marginBottom: spaceVar[3] }}>Reopening replaces this scene with the last saved file.</div>
+      <Button variant="secondary" onClick={() => { setOpened(null); setAttempt(value => value + 1); }}>
+        Reopen saved document
+      </Button>
+    </div>}
     {!documentViewport(documentId) && <BlenderModelOpening documentId={documentId} path={blend ?? 'Model'} error={null}
       preparingView preview={preview} retry={() => {}} returnToPreview={() => {}} />}
   </>;
@@ -422,79 +423,73 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
  * camera. Each area has its own stage, shading, navigation and camera view; the model, its
  * selection and its history are the document's.
  *
- * PLAYING (the composed Play tool), the area shows a DETACHED copy of the model
- * (`BlenderRuntimeView.detach`) on a stage of its own, which the project's play script moves
- * (the document Play extension). The model's own stage stays mounted underneath, hidden, so Stop
- * returns to the same view of the same model: nothing a game does reaches Blender.
+ * PLAYING (the composed Play tool), the area shows a DETACHED copy of the model's World
+ * (`BlenderRuntimeView.detach`) on a stage of its own, where the level's game draws (the document Play extension).
+ * The model's own stage stays mounted underneath, hidden, so Stop returns to the same view of the same model:
+ * nothing a game does reaches Blender.
  */
 function BlenderModelViewport(props: ToolContributionProps) {
   const { documentId } = props;
   const blend = props.document?.source?.path;
   // THE BOTTOM AREA SERVES THIS DOCUMENT while it is the model on screen (`../src/play-mode.ts`):
-  // the Game panel drives this id's run, and Game or Movie is chosen by this file's play script.
+  // the Game panel drives this id's run, and Game or Animation is chosen by whether this level has a game.
   useEffect(() => (documentId ? noteModelDocument(documentId, blend) : undefined), [documentId, blend]);
-  // Rendered areas and Play use the scene's display transform, just as a
-  // photograph does. Solid keeps its studio transform. RNA also announces
-  // colour settings that change without changing the presented geometry.
+  // Rendered areas and Play use the display transform carried by the presented frame. Solid uses its studio transform. Document preparation waits for that frame’s transform before photographs.
   useEffect(() => {
     if (!documentId) return;
     let cancelled = false;
-    let revision = 0;
-    let applied: { key: string; transform: BlenderDisplayTransform } | null = null;
+    let applied: BlenderDisplayTransform | null = null;
+    let wanted: string | null = null;
+    let settled: Promise<void> = Promise.resolve();
     const ids = [documentId, `${documentId}#area-2`, `${documentId}#play`];
     const attach = () => {
-      for (const id of ids) object3DDocumentSession(id)?.setDisplayTransform(applied?.transform ?? null);
+      for (const id of ids) object3DDocumentSession(id)?.setDisplayTransform(applied);
     };
-    const read = async () => {
-      const mine = ++revision;
-      const context = await blenderRnaContext();
-      if (!context) return;
-      const [settings, displaySettings] = await Promise.all([
-        blenderRna(`${context.scene}.view_settings`),
-        blenderRna(`${context.scene}.display_settings`),
-      ]);
-      if (cancelled || mine !== revision || settings?.kind !== 'struct' || settings.type !== 'ColorManagedViewSettings') return;
-      if (displaySettings?.kind === 'struct') {
-        const device = displaySettings.groups.flatMap(group => group.rows).find(row => row.identifier === 'display_device')?.value;
-        if (typeof device === 'string' && device !== 'sRGB')
-          throw new Error(`Blender display device ${device} has no browser display processor yet`);
-      }
-      const rows = settings.groups.flatMap(group => group.rows);
-      const transform = rows.find(row => row.identifier === 'view_transform')?.value;
-      const stops = rows.find(row => row.identifier === 'exposure')?.value;
-      const look = rows.find(row => row.identifier === 'look')?.value;
-      const gamma = rows.find(row => row.identifier === 'gamma')?.value;
-      const exposure = typeof stops === 'number' ? 2 ** stops : 1;
-      const display = {
-        transform: typeof transform === 'string' ? transform : 'AgX',
-        look: typeof look === 'string' ? look : 'None',
-        exposure, gamma: typeof gamma === 'number' ? gamma : 1,
-      };
+    const follow = (): Promise<void> => {
+      const display = view.displaySettings();
+      if (!display) return settled;
       const key = JSON.stringify(display);
-      if (applied?.key === key) return;
-      const resolved = await createBlenderDisplayTransform(display);
-      if (cancelled || mine !== revision) { resolved.dispose(); return; }
-      const previous = applied;
-      applied = { key, transform: resolved };
-      attach();
-      previous?.transform.dispose();
-      for (const id of ids) {
-        setViewPresentation(id, { modes: {
-          rendered: { lighting: { tone: { mapper: 'none', exposure: 1 } } },
-          preview: { lighting: { tone: { mapper: 'none', exposure: 1 } } },
-        } });
-      }
+      if (key === wanted) return settled;
+      wanted = key;
+      settled = (async () => {
+        if (display.device !== 'sRGB')
+          throw new Error(`Blender display device ${display.device} has no browser display processor yet`);
+        const resolved = await createBlenderDisplayTransform(display);
+        if (cancelled || wanted !== key) { resolved.dispose(); return; }
+        const previous = applied;
+        applied = resolved;
+        attach();
+        previous?.dispose();
+        for (const id of ids) {
+          setViewPresentation(id, { modes: {
+            rendered: { lighting: { tone: { mapper: 'none', exposure: 1 } } },
+            preview: { lighting: { tone: { mapper: 'none', exposure: 1 } } },
+          } });
+        }
+      })().catch((error: unknown) => editorHost().console.error(String(error), 'blender-colour'));
+      return settled;
     };
-    const update = () => { void read().catch(error => editorHost().console.error(String(error), 'blender-colour')); };
-    const stopRna = subscribeBlenderRna(update);
-    const stopSessions = subscribeObject3DDocumentSessions(attach);
-    update();
+    // A photograph of each shading type is anti-aliased as Blender's viewport accumulates it.
+    const sample = () => {
+      const sampling = view.photographSampling();
+      for (const id of ids) object3DDocumentSession(id)?.setPhotographSampling(sampling);
+    };
+    const stopFrames = view.subscribeFrames(() => { sample(); void follow(); });
+    const stopSessions = subscribeObject3DDocumentSessions(() => { attach(); sample(); });
+    sample();
+    // A view presented on this document is drawn (and photographed) once the frame on screen has
+    // its display transform and everything it is still decoding or settling (`drawReady`).
+    const stopPreparation = registerObject3DDocumentPreparation(documentId, async () => {
+      await follow();
+      await view.drawReady();
+    });
+    void follow();
     return () => {
-      cancelled = true; stopRna(); stopSessions();
+      cancelled = true; stopFrames(); stopSessions(); stopPreparation();
       const previous = applied;
       applied = null;
       attach();
-      previous?.transform.dispose();
+      previous?.dispose();
     };
   }, [documentId]);
   const split = useSyncExternalStore(
@@ -518,17 +513,26 @@ function BlenderModelViewport(props: ToolContributionProps) {
     };
   }, [split, documentId]);
   const playing = useSyncExternalStore(
-    subscribeDocumentPlayExtensions,
-    () => (documentId ? documentPlayExtension('model')?.playing(documentId) ?? false : false),
+    subscribeModelPlayExtension,
+    () => (documentId ? modelPlayExtension()?.playing(documentId) ?? false : false),
     () => false,
   );
   const [played, setPlayed] = useState<ReturnType<AreaView['detach']> | null>(null);
   const playAspect = useSyncExternalStore(
-    subscribeDocumentPlayExtensions,
-    () => (documentId ? documentPlayExtension('model')?.aspectRatio?.(documentId) ?? null : null),
+    subscribeModelPlayExtension,
+    () => (documentId ? modelPlayExtension()?.aspectRatio?.(documentId) ?? null : null),
     () => null,
   );
   const [playedReady, setPlayedReady] = useState(false);
+  /** THE PLAY OVERLAY: a layer over the editing area and the play area alike, where the Play tool puts its view
+   *  controls (`DocumentPlayStage.overlay`), so they stand whichever area is in front. It takes no press itself;
+   *  the controls in it take their own. */
+  const playOverlay = useRef<HTMLDivElement>(null);
+  /** WHERE THE MODEL'S OWN AREA STANDS WHILE THE GAME RUNS (`DocumentPlayStage.edit`): hidden behind the game, live in
+   *  front of it, or drawing in a box of the stage (a tile), taking no press; null while the tool has placed it
+   *  nowhere, and again when the game ends. A tool that places it switches it at once; otherwise it fades as the game
+   *  draws its first frame. */
+  const [editArea, setEditArea] = useState<DocumentPlayEditArea | null>(null);
   /**
    * RESTART IS A NEW GENERATION OF THE SAME PLAY (`DocumentPlayTransport.generation`): the copy
    * below is detached per generation, so a restart disposes the played copy and detaches a fresh
@@ -540,12 +544,11 @@ function BlenderModelViewport(props: ToolContributionProps) {
    * therefore taken in two steps: a layout effect photographs the old play stage while it still
    * stands (`capture`, the frame it draws) and only then moves `shownGeneration`, which is what
    * detaches the new copy. The photograph covers the play area until the new runner's first
-   * frame (`onPlayReady`), the model area stays hidden throughout, and the old runner, no longer
-   * the current generation, stands still meanwhile (`play-script.ts`).
+   * frame (`onPlayReady`), and the model area stays hidden throughout.
    */
   const generation = useSyncExternalStore(
-    subscribeDocumentPlayExtensions,
-    () => (documentId ? documentPlayExtension('model')?.transport?.generation(documentId) ?? 0 : 0),
+    subscribeModelPlayExtension,
+    () => (documentId ? modelPlayExtension()?.transport?.generation(documentId) ?? 0 : 0),
     () => 0,
   );
   const [shownGeneration, setShownGeneration] = useState(generation);
@@ -573,7 +576,7 @@ function BlenderModelViewport(props: ToolContributionProps) {
    * update), so the cover would stand over it while the panel said Playing. The runner says so
    * on the clock (`DocumentPlayClock.failure`); the cover drops and the stage shows what it has.
    */
-  const transport = documentPlayExtension('model')?.transport;
+  const transport = modelPlayExtension()?.transport;
   const subscribeFailure = useCallback(
     (listener: () => void) => transport?.subscribeClock(listener) ?? (() => {}),
     [transport],
@@ -599,6 +602,7 @@ function BlenderModelViewport(props: ToolContributionProps) {
     const playId = `${documentId}#play`;
     // A game is seen as the render is: Rendered shading, chosen before the stage binds.
     setViewPresentation(playId, { drawMode: 'rendered' });
+    // The game brings its own objects: the copy is the World alone.
     const copy = view.detach();
     const restart = restarting.current;
     restarting.current = false;
@@ -613,17 +617,20 @@ function BlenderModelViewport(props: ToolContributionProps) {
     return () => {
       // Read at cleanup: the layout effect above has already marked a restart, whose new copy
       // takes over in this same commit with the play mode unchanged.
-      if (restarting.current && documentPlayExtension('model')?.playing(documentId)) {
+      if (restarting.current && modelPlayExtension()?.playing(documentId)) {
         retired.current.push(copy);
         return;
       }
       copy.dispose();
       for (const old of retired.current.splice(0)) old.dispose();
       awaitingDraw.current = false;
+      setEditArea(null);
       setPlayed(null);
       setRestartStill(null);
       view.setPlaying(false);
       notifyWorkspaceDocumentSelectionChanged(documentId);
+      // Present the document after Play ends. Preserve action revisions so the next edit does not rebake unchanged clips.
+      void blenderPresentDocument().catch(() => {});
     };
   }, [playing, documentId, shownGeneration]);
   useEffect(() => {
@@ -636,7 +643,7 @@ function BlenderModelViewport(props: ToolContributionProps) {
   // The document closing or going inactive ends its game; a game never outlives its stage.
   useEffect(() => {
     if (!documentId) return;
-    return () => documentPlayExtension('model')?.setPlaying(documentId, false);
+    return () => modelPlayExtension()?.setPlaying(documentId, false);
   }, [documentId]);
   const game = playing ? played : null;
   const playFrame = playAspect === null ? { position: 'absolute', inset: 0 } as const : {
@@ -650,7 +657,8 @@ function BlenderModelViewport(props: ToolContributionProps) {
     if (!modelViewport) return;
     // registerObject3DDocumentSession creates this document's own viewport object; capture may follow its visible play area.
     const capture = modelViewport.capture;
-    const playCapture = (size: Parameters<NonNullable<typeof capture>>[0]) => documentViewport(`${documentId}#play`)?.capture?.(size) ?? null;
+    const playCapture = (size: Parameters<NonNullable<typeof capture>>[0]) =>
+      documentViewport(`${documentId}#play`)?.capture?.(size) ?? null;
     modelViewport.capture = playCapture;
     return () => {
       if (modelViewport.capture !== playCapture) return;
@@ -658,22 +666,23 @@ function BlenderModelViewport(props: ToolContributionProps) {
       else delete modelViewport.capture;
     };
   }, [game, documentId]);
+  // (the model's keys are the player's while the game is in front, and the editor's while the area is live)
+  useEffect(() => { if (game) view.setPlaying(editArea !== 'live'); }, [game, editArea, view]);
   if (!documentId) return null;
   const second = split ? follower : null;
   // Keep both authoring areas mounted across Play/Stop. Remounting a stage discards
   // its pose/session and repeats the second area's initial scene-camera setup.
   const area = { position: 'relative', flex: '1 1 0', minWidth: 0, margin: 12 } as const;
-  // THE HIDDEN MODEL AREA IS INERT, not merely `pointer-events: none`. It lies OVER the play
-  // area (z-index 2, faded out once the game has drawn), and the stage inside it sets its own
-  // `pointer-events: auto` (`StageHost`'s viewport box), which a parent's `none` does not reach:
-  // a real click on the game hit the invisible editing canvas, never the play surface, so the
-  // runner's takeover (`play-script.ts`, which asks whether the press landed in the game) never
-  // saw it and the game never got it — while keys, read off the window, took over fine. `inert`
-  // takes the whole subtree out of hit testing and focus.
-  const hidden = game !== null && playedReady;
+  // Make the hidden Model area inert so its subtree receives neither pointer presses nor focus. A live overlay or tile uses the box supplied by the Play tool.
+  const tile = game !== null && typeof editArea === 'object' ? editArea : null;
+  const hidden = game !== null && playedReady && (editArea === null || editArea === 'hidden');
+  const modelBox = tile === null ? { inset: 12 } : {
+    left: `calc(12px + (100% - 24px) * ${tile.left})`, top: `calc(12px + (100% - 24px) * ${tile.top})`,
+    width: `calc((100% - 24px) * ${tile.width})`, height: `calc((100% - 24px) * ${tile.height})`,
+  };
   return (
     <div style={game || second ? { position: 'absolute', inset: -12, display: 'flex', gap: 2 } : { display: 'contents' }}>
-      <div key="model" inert={hidden || undefined} style={game ? { position: 'absolute', inset: 12, zIndex: 2, opacity: playedReady ? 0 : 1, pointerEvents: playedReady ? 'none' : 'auto', transition: 'opacity 160ms ease-out' } : second ? area : { display: 'contents' }}>
+      <div key="model" inert={hidden || tile !== null || undefined} style={game ? { position: 'absolute', ...modelBox, zIndex: 2, opacity: hidden ? 0 : 1, pointerEvents: hidden || tile !== null ? 'none' : 'auto', transition: editArea === null ? 'opacity 160ms ease-out' : 'none' } : second ? area : { display: 'contents' }}>
         <BlenderViewportArea {...props} view={view} main />
       </div>
       {game && (
@@ -682,15 +691,14 @@ function BlenderModelViewport(props: ToolContributionProps) {
         <div key={`play-${playCopyKey(game)}`} style={{ position: 'absolute', inset: 12, containerType: 'size' }} data-testid="blender-play-area">
           <div data-volter-play-frame style={playFrame}>
           <BlenderViewportArea {...props} documentId={`${documentId}#play`} view={game.view} main={false} playing
-            onPlayReady={() => { awaitingDraw.current = false; setPlayedReady(true); setRestartStill(null); }} onPlayReturn={() => setPlayedReady(false)} />
+            onPlayReady={() => { awaitingDraw.current = false; setPlayedReady(true); setRestartStill(null); }}
+            onPlayEdit={setEditArea} playOverlay={playOverlay} />
           </div>
         </div>
       )}
+      {game && <div key="play-overlay" ref={playOverlay} data-testid="blender-play-overlay" style={{ position: 'absolute', inset: 12, zIndex: 5, pointerEvents: 'none' }} />}
       {game && failure !== null && (
-        // A PLAY WITH NO GAME, said over the area itself. When the script did not start (or the
-        // stage could not be prepared) the game never draws and the model area stays in front,
-        // so the area looked like plain editing while Play was on and the reason was a toast
-        // that had already gone (2026-10-06 audit). The Game panel says the same in its line.
+        // Display a failed Play start over the area until it draws; the Game panel repeats the same refusal.
         <div key="play-failure" role="alert" data-testid="blender-play-failure"
           style={{ position: 'absolute', left: 24, right: 24, top: 24, zIndex: 4, padding: `${spaceVar[2]} ${spaceVar[3]}`,
             background: themeVars.surface.chrome, border: `1px solid ${themeVars.semantic.danger}`, borderRadius: themeVars.shape.small,
@@ -713,17 +721,11 @@ function BlenderModelViewport(props: ToolContributionProps) {
   );
 }
 
-/**
- * THE SECOND AREA'S OWN HEADER, as each of Blender's areas has one: the editor menus (their
- * View ▸ Area ▸ Close Area closes this area), then THIS area's view, shading and helpers, the
- * header controls its own stage registered, so its shading cells change this area and not the
- * other.
- */
 /**
  * THE SECOND AREA'S OWN HEADER AND SHELF, as each of Blender's areas has them.
  *
  * The area is declared to the host as the document's second area
- * (`@volter/sdk/kit/document-areas`). Its HEADER stands in the document's header row over
+ * (`@volter/sdk/document-areas`). Its HEADER stands in the document's header row over
  * this area: the host reserves this area's width at the row's trailing edge, so the first area's
  * header ends where the first area does, and this renders into the region it draws there: the
  * editor menus (their View ▸ Area ▸ Close Area closes this area), then THIS area's view, shading
@@ -789,17 +791,19 @@ function BlenderViewportArea({
   main,
   playing = false,
   onPlayReady,
-  onPlayReturn,
-}: ToolContributionProps & { readonly view: AreaView; readonly main: boolean; readonly playing?: boolean; readonly onPlayReady?: () => void; readonly onPlayReturn?: () => void }) {
+  onPlayEdit,
+  playOverlay,
+}: ToolContributionProps & { readonly view: AreaView; readonly main: boolean; readonly playing?: boolean; readonly onPlayReady?: () => void;
+  readonly onPlayEdit?: (area: DocumentPlayEditArea) => void; readonly playOverlay?: RefObject<HTMLDivElement | null> }) {
   const reads = readsOf(view);
   const build = useCallback(
     () => ({
       root: view.root,
-      prepareDraw: (camera: THREE.Camera, options?: {interactive: boolean; height: number; multiDraw?: boolean; renderer?: THREE.WebGLRenderer}) => view.prepareDraw(camera, options),
+      prepareDraw: (camera: THREE.Camera, options?: BlenderDrawOptions) => view.prepareDraw(camera, options),
       // What the view draws changes with each frame and the work after it,
-      // and with the skin's poses when the Timeline scrubs. A PLAYING copy announces nothing:
-      // its script moves it every frame, and a source that announces nothing is drawn every
-      // frame (`ToolObject3DPreviewSource.onChange`).
+      // and with the skin's poses when the Timeline scrubs. A PLAYING copy announces nothing, and
+      // a source that announces nothing is drawn every frame (`ToolObject3DPreviewSource.onChange`):
+      // the play stage's frames are what start the Play tool's run once the stage stands.
       ...(playing
         ? {}
         : {
@@ -872,9 +876,8 @@ function BlenderViewportArea({
     };
   }, [main, playing, documentId, view]);
   /**
-   * THE PLAYING COPY IS MOVED BY THE PROJECT'S PLAY SCRIPT (the document Play extension), on this
-   * stage's own frame hook, once the stage stands. The stage's orbit stands down while it runs,
-   * so the script's camera is not argued with, and Escape stops the game.
+   * THE LEVEL'S GAME PLAYS IN THIS STAGE (the document Play extension), once the stage stands: the Play tool draws the
+   * game in its container, in place of the hidden copy, and Escape stops the game.
    */
   const notifyRef = useRef(notify);
   const surfaceRef = useRef<HTMLDivElement>(null);
@@ -882,15 +885,15 @@ function BlenderViewportArea({
   notifyRef.current = notify;
   const playReadyRef = useRef(onPlayReady);
   playReadyRef.current = onPlayReady;
-  const playReturnRef = useRef(onPlayReturn);
-  playReturnRef.current = onPlayReturn;
+  const playEditRef = useRef(onPlayEdit);
+  playEditRef.current = onPlayEdit;
   useEffect(() => {
     if (!playing || !documentId) return;
     if (blend === undefined) {
       notifyRef.current?.({
         tone: 'error',
-        title: 'This model has no play script',
-        detail: 'A play script stands beside a model\'s .blend file, and this model has no file of its own.',
+        title: 'This model has no game',
+        detail: 'A level\'s game is its project\'s, and this model has no file of its own in the project.',
       });
       return;
     }
@@ -901,116 +904,26 @@ function BlenderViewportArea({
     surfaceRef.current?.appendChild(layers);
     setPlayReady(false);
     let stopped = false;
-    let preparing = false;
     let stopScript: (() => void) | null = null;
-    let orbit: { enabled: boolean } | null = null;
-    let animation: PlayAnimation | null = null;
+    let hiddenCopy: boolean | null = null;
     const start = (): void => {
-      if (stopScript || preparing || stopped) return;
+      if (stopScript || stopped) return;
       const stage = viewportStages().find((one) => one.documentId === documentId);
       if (!stage || !view.root.parent) return;
-      preparing = true;
-      orbit = stage.rig().orbit;
-      orbit.enabled = false;
-      // THE COPY'S CHARACTERS ANIMATE: its view bound their skins from the copied frame, and each
-      // armature plays the action the file assigns it until the game sets another
-      // (`blender-play-skin.ts`). Nothing is read before the game starts.
-      // A LOADING PHASE, said on screen: the game starts only once its stage is drawn and every
-      // character's starting clips are baked (`PlayAnimation.prepare`). Started before them, a
-      // character whose clip Blender had not answered yet stood frozen in its rest pose, and a
-      // clip whose read failed stayed frozen for the whole run. That is the suspected cause of
-      // "sometimes none of the animations work" (a busy Blender was measured to delay the clips).
-      // THE WAIT IS BOUNDED AND SAID: after LOADING_SAY the overlay names the clips still
-      // awaited; at LOADING_LIMIT the game starts without them and the console names them (each
-      // still plays once Blender answers). A thrown `prepare` is named too; the game always starts.
-      const loading = window.document.createElement('div');
-      loading.dataset['testid'] = 'model-play-loading';
-      loading.textContent = 'Loading…';
-      Object.assign(loading.style, {
-        position: 'absolute', inset: '0', display: 'flex', alignItems: 'center', justifyContent: 'center',
-        background: 'rgba(0, 0, 0, 0.35)', color: '#e6e6e6', font: '600 14px system-ui, sans-serif', pointerEvents: 'none',
-      });
-      layers.appendChild(loading);
-      void view.prepareRendered(stage.rig().drawCamera(), 'render').then(async () => {
-        if (stopped) return;
-        // No session answers null: a read that failed, asked again, not a clip that animates nothing.
-        // A SETUP THAT THROWS still starts the game, without animation and said so; left
-        // outside any catch it left the loading overlay up and the script never ran.
-        let cache = playClipCaches.get(modelId);
-        if (!cache) playClipCaches.set(modelId, cache = new Map());
-        let loaded: PlayAnimation | null = null;
-        try {
-          loaded = playAnimation(view, async (armature, action) => {
-            const clip = await blenderActionClip({ object: armature, action, summary: false });
-            if (clip === null) throw new Error("Blender's session is not started");
-            return clip;
-          }, cache);
-        } catch (error) {
-          editorHost().console.error(`The game's animation could not be set up, so the game starts without it: ${error instanceof Error ? error.message : String(error)}`, 'blender-animation');
-        }
-        animation = loaded;
-        if (!loaded) {
-          loading.remove();
-          if (stopped) return;
-        }
-        if (loaded) {
-          const anim = loaded;
-          const LOADING_SAY = 3_000, LOADING_LIMIT = 20_000;
-          const clips = (names: readonly string[]): string => `${names.length} clip${names.length === 1 ? '' : 's'}`;
-          const say = window.setInterval(() => {
-            const pending = anim.pending();
-            if (pending.length > 0) loading.textContent = `Loading… waiting on Blender for ${clips(pending)}: ${pending.slice(0, 6).join(', ')}${pending.length > 6 ? ` and ${pending.length - 6} more` : ''}`;
-          }, LOADING_SAY);
-          let limit = 0;
-          const outcome = await Promise.race([
-            anim.prepare().then(({ failed }) => ({ failed, waiting: [] as readonly string[] }), (error: unknown) => ({ failed: [`the loading phase failed: ${error instanceof Error ? error.message : String(error)}`], waiting: [] as readonly string[] })),
-            new Promise<{ failed: readonly string[]; waiting: readonly string[] }>((resolve) => {
-              limit = window.setTimeout(() => resolve({ failed: [], waiting: anim.pending() }), LOADING_LIMIT);
-            }),
-          ]);
-          window.clearInterval(say);
-          window.clearTimeout(limit);
-          loading.remove();
-          if (stopped) return;
-          if (outcome.failed.length > 0)
-            editorHost().console.warn(`The game started without ${clips(outcome.failed)} it starts on: ${outcome.failed.join('; ')}`, 'blender-animation');
-          if (outcome.waiting.length > 0)
-            editorHost().console.warn(`The game started after ${LOADING_LIMIT / 1000} s still waiting on Blender for ${clips(outcome.waiting)}; each plays once Blender answers: ${outcome.waiting.join(', ')}`, 'blender-animation');
-          anim.prefetch();
-        }
-        setLiveAnimation(animation);
-        stopScript = documentPlayExtension('model')?.run({
-          ...(animation ? { animation } : {}),
-          documentId: modelId,
-          container: layers,
-          ready: () => { if (!stopped) { setPlayReady(true); playReadyRef.current?.(); } },
-          returning: () => { if (!stopped) playReturnRef.current?.(); },
-          sourcePath: blend,
-          root: view.root,
-          camera: () => stage.rig().drawCamera(),
-          editingCamera: () => viewportStages().find(one => one.documentId === modelId)?.rig().drawCamera() ?? stage.rig().drawCamera(),
-          onFrame: (fn) => stage.onFrame(fn),
-          ownMaterial: (material) => ownedSurfaceMaterial(material as THREE.Material),
-          report: (title, detail) => {
-            editorHost().console.error(`${title}: ${detail}`, 'blender-play');
-            notifyRef.current?.({ tone: 'error', title, detail });
-          },
-        }) ?? null;
-      }, error => {
-        loading.remove();
-        if (stopped) return;
-        const failure = `The game's stage could not be prepared for a rendered draw: ${error instanceof Error ? error.message : String(error)}`;
-        editorHost().console.error(failure, 'model-play');
-        // SAID WHERE THE PERSON IS LOOKING: on the run's clock, which the Game panel and the
-        // play area draw, and in the play log. Turning Play off (what this did until
-        // 2026-10-06) erased the only trace a person could have seen.
-        const extension = documentPlayExtension('model');
-        if (extension?.transport?.fail) extension.transport.fail(modelId, blend, failure);
-        else {
-          notifyRef.current?.({ tone: 'error', title: 'Play could not start', detail: failure });
-          extension?.setPlaying(modelId, false);
-        }
-      });
+      hiddenCopy = view.root.visible;
+      view.root.visible = false;
+      stopScript = modelPlayExtension()?.run({
+        documentId: modelId,
+        container: layers,
+        ready: () => { if (!stopped) { setPlayReady(true); playReadyRef.current?.(); } },
+        edit: (area) => { if (!stopped) playEditRef.current?.(area); },
+        ...(playOverlay?.current ? { overlay: playOverlay.current } : {}),
+        sourcePath: blend,
+        report: (title, detail) => {
+          editorHost().console.error(`${title}: ${detail}`, 'blender-play');
+          notifyRef.current?.({ tone: 'error', title, detail });
+        },
+      }) ?? null;
     };
     start();
     let waitingStage: ReturnType<typeof viewportStages>[number] | undefined;
@@ -1027,14 +940,13 @@ function BlenderViewportArea({
     const stopStages = onViewportStages(waitForDraw);
     const onEscape = (event: KeyboardEvent): void => {
       if (event.key !== 'Escape' || !surfaceAcceptsKey(event)) return;
-      // Decided once the event has finished dispatching: a play script that claims Escape (a
+      // Decided once the event has finished dispatching: a game that claims Escape (a
       // game's pause, registered after this listener) prevents its default, and the Escape that
-      // frees a game's mouse look is the person taking their mouse back. Both used to stop Play
-      // (three playtests of a Cyclotron game lost a mission each to it).
+      // frees a game's mouse look is the person taking their mouse back. Neither stops Play.
       if (globalThis.document.pointerLockElement || performance.now() - lastPointerUnlockAt < 500) return;
       setTimeout(() => {
         if (event.defaultPrevented) return;
-        const extension = documentPlayExtension('model');
+        const extension = modelPlayExtension();
         if (extension?.escape) extension.escape(modelId);
         else extension?.setPlaying(modelId, false);
       }, 0);
@@ -1050,12 +962,8 @@ function BlenderViewportArea({
       stopPrepareFrames?.();
       window.removeEventListener('keydown', onEscape, true);
       stopScript?.();
-      // Only this run's animation is cleared: a restart's new run may already hold the slot.
-      if (liveAnimation() === animation) setLiveAnimation(null);
-      animation?.dispose();
-      animation = null;
+      if (hiddenCopy !== null) { view.root.visible = hiddenCopy; hiddenCopy = null; }
       layers.remove();
-      if (orbit) orbit.enabled = true;
     };
   }, [playing, documentId, blend, view]);
   /**
@@ -1095,20 +1003,7 @@ function BlenderViewportArea({
     opened();
     return subscribeStageStores(opened);
   }, [main, documentId]);
-  /**
-   * THE INSPECTION OVERLAYS ARE HELPERS, and the Helpers menu owns them
-   * (WORK.md §Blender in the tab is Blender, "Inspection parity", I4).
-   *
-   * Blender's viewport overlay has a Bones checkbox (`View3DOverlay.
-   * show_bones`, `rna_space.cc:5125-5129`, drawn by `space_view3d.py:7161`)
-   * and this editor's Helpers menu already has a Skeletons row; a weight
-   * display had no member and gained one (`weights`). Handing each group to
-   * the stage through `setHelper` is the whole wiring: the host marks it
-   * editor-owned — out of the hierarchy, out of the raycast — sets its
-   * visibility from that kind's checkbox on the spot, keeps it across the
-   * stage's remounts, and toggles it afterwards. Nothing here reads or
-   * mirrors the toggle's state, which is why there is no second copy of it.
-   */
+  /** Register bone and weight overlays as helpers. The host owns their visibility, excludes them from hierarchy and raycast, and restores them across stage remounts. */
   useEffect(() => {
     if (!documentId) return;
     const groups = view.overlayGroups();
@@ -1135,8 +1030,9 @@ function BlenderViewportArea({
     if (!documentId || !main) return;
     let live = true;
     void blenderSkin.sync(view, {
-      clip: (armature) => blenderActionClip({ object: armature }),
+      clip: (armature) => blenderActionClip(armature === null ? {} : { object: armature }),
       bake: (armature, action) => blenderActionClip({ object: armature, action, summary: false }),
+      movie: () => blenderSceneMovie(),
     }).catch((thrown: unknown) => {
       if (live) editorHost().console.warn(`This file's action could not be read: ${thrown instanceof Error ? thrown.message : String(thrown)}`, 'blender-skin');
     });
@@ -1316,16 +1212,7 @@ function BlenderViewportArea({
       cameraView={reads.cameraView}
       build={build}
       audit={false}
-      // ON A MODEL DOCUMENT THE HIERARCHY IS BLENDER'S OUTLINER, for the same
-      // reason the Properties rail is Blender's rail: the rows this panel drew
-      // were the PRESENTER's three.js graph — a reading of Blender's data by
-      // the thing that photographs it — where Blender's own Outliner shows the
-      // VIEW LAYER's datablock tree. `blender-outliner-authoring.ts` is the
-      // provider; the default adapter it delegates to still answers everything
-      // about the presentation (WORK.md §Blender in the tab is Blender,
-      // "Inspection parity", I3).
-      // A PLAYING COPY HAS NO AUTHORING: it is read-only to the editor, and what moves it is its
-      // script. With none given the stage is the native read-only one.
+      // The authoring hierarchy is Blender’s View Layer Outliner; the default adapter supplies presentation access. A playing copy has no authoring adapter and uses the read-only stage.
       {...(playing ? {} : { authoring })}
       cameraDirection={[0.8187, 0.4458, 0.3617]}
       // FOR A FILE THAT SAVED NO 3D VIEW: Blender's factory Modeling direction, standing back
@@ -1342,33 +1229,24 @@ function BlenderViewportArea({
         const saved = view.savedView();
         if (!saved) return null;
         const camera = { fov: blenderViewFieldOfView(saved.lens) };
+        // Solid and Wireframe use the saved view's resolved theme, World or viewport colour.
+        const behind = { backdrop: { source: 'color' as const, color: saved.background } };
         return main && saved.drawMode ? {
           camera, drawMode: saved.drawMode,
-          modes: { preview: {
-            lighting: { source: saved.sceneWorld ? 'scene' as const : 'preview' as const, preview: { sceneLights: saved.sceneLights } },
-            backdrop: { source: saved.sceneWorld ? 'scene' as const : 'fill' as const },
-          } },
-        } : { camera };
+          modes: {
+            solid: behind,
+            wireframe: behind,
+            preview: {
+              lighting: { source: saved.sceneWorld ? 'scene' as const : 'preview' as const, preview: { sceneLights: saved.sceneLights } },
+              backdrop: { source: saved.sceneWorld ? 'scene' as const : 'fill' as const },
+            },
+          },
+        } : { camera, modes: { solid: behind, wireframe: behind } };
       })()}
       // Every entry this document opens is a `model` stage, the standing `blender:runtime`
       // address included (its id carries no `model:` prefix).
       stageKind={documentKind}
-      // SOLID SHADING IS BLENDER'S, and Blender's Solid mode has NO world
-      // light: `light_ambient` is (0,0,0), there is no IBL, and the model is
-      // lit by four studio lights stated in VIEW space. So this document
-      // turns the editor's studio dressing off — its RoomEnvironment IBL and
-      // its one warm key, which between them were the blow-out row 1
-      // measured (the factory cube read (240,240,239)/(231,231,231)/
-      // (227,226,225) against Blender's (141,143,145)/(129,131,131)/
-      // (111,112,113), a spread of 13 against 30) — and hands the stage
-      // Blender's own four instead. `keyLight: false` also stands down the
-      // editor's design-time light rig, which answers the same question.
-      // The BACKGROUND stays the dressing's, because the Blender palette
-      // already paints the viewport its own flat grey.
-      //
-      // THE VIEW TRANSFORM IS EACH SHADING MODE'S OWN (`src/presentation.ts`: Standard for Solid,
-      // AgX for Material Preview and Rendered), so the dressing states none: a document mapper
-      // would outrank every mode's.
+      // Solid shading uses Blender’s four view-space studio lights without IBL or an editor key light. Keep the palette background; each shading mode owns its own view transform.
       dressing={{
         environment: false,
         keyLight: false,