@volter/editor-blender 0.1.131 → 0.1.133

package/contributions/blender-game-panel.tsx

@@ -163,15 +163,24 @@ function gameState(documentId: string): unknown {
   };
 }
 
-/** The bot's switch and who drives: `bot` while autoplay is on, `person` otherwise, null when
- *  nothing plays. `by` is who made the last change (`takeover`: a person's key or pointer);
- *  `why` says why there is no bot to switch, null when there is one. */
+/** Who drives a playing game: the bot while autoplay is on; the person once their key or pointer
+ *  has reached the game this run; otherwise nobody — the game runs on no input. A tool that
+ *  predates `person` cannot say, and counts autoplay off as the person driving, as it always did. */
+function driverOf(playing: boolean, autoplay: DocumentPlayAutoplay): 'bot' | 'person' | 'none' | null {
+  if (!playing) return null;
+  if (autoplay.on) return 'bot';
+  return autoplay.person === false ? 'none' : 'person';
+}
+
+/** The bot's switch and who drives (`driverOf`), null when nothing plays. `by` is who made the
+ *  last change (`takeover`: a person's key or pointer; `limit`: the run's seconds spent); `state`
+ *  what the bot says it is doing; `why` says why there is no bot to switch, null when there is one. */
 function autoplayState(documentId: string): unknown {
   const found = extension();
   const autoplay = found?.transport?.autoplay?.(documentId) ?? NO_BOT;
   const playing = found?.playing(documentId) ?? false;
   const why = autoplayWhy(playing, found?.transport?.clock(documentId) ?? STILL, autoplay);
-  return { ...autoplay, driver: playing ? (autoplay.on ? 'bot' : 'person') : null, why };
+  return { ...autoplay, driver: driverOf(playing, autoplay), why };
 }
 
 /**
@@ -299,8 +308,9 @@ registerViewVerbs({
       },
     },
     {
-      // THE EDITOR'S AUTOPLAY SWITCH: on drives the game's own bot (`play.autoplay`), off hands
-      // the game back to the person. Off at every Play and Restart.
+      // THE EDITOR'S AUTOPLAY SWITCH: on drives one of the game's bot behaviours (`play.autoplay`)
+      // for at most `for` simulation seconds, off hands the game back to the person. Off at every
+      // Play and Restart. `behavior` is required when the bot offers several.
       id: 'autoplay',
       run: (args) => {
         const documentId = verbDocument(args);
@@ -308,6 +318,11 @@ registerViewVerbs({
         const on = raw === true || raw === 'on' || raw === 'true' ? true
           : raw === false || raw === 'off' || raw === 'false' ? false : undefined;
         if (on === undefined) throw new Error(`autoplay's \`on\` is true or false (\`play autoplay on|off\`); got ${String(raw)}.`);
+        const behavior = typeof args?.['behavior'] === 'string' && args['behavior'] !== '' ? args['behavior'] : null;
+        const rawLimit = args?.['for'] ?? args?.['limit'];
+        const limit = rawLimit === undefined || rawLimit === null ? null : Number(rawLimit);
+        if (limit !== null && !(Number.isFinite(limit) && limit > 0))
+          throw new Error(`autoplay's \`for\` is a positive number of simulation seconds; got ${JSON.stringify(rawLimit)}.`);
         const found = verbExtension();
         const { transport } = found;
         if (transport.setAutoplay === undefined)
@@ -315,7 +330,7 @@ registerViewVerbs({
         // Refused with the reason, stopped or no bot, as `play state`'s `autoplay.why` gives it.
         const why = on ? autoplayWhy(found.playing(documentId), transport.clock(documentId), transport.autoplay?.(documentId) ?? NO_BOT) : null;
         if (why !== null) throw new Error(why);
-        transport.setAutoplay(documentId, on, 'cli');
+        transport.setAutoplay(documentId, on, 'cli', on ? { behavior, limit } : undefined);
         return gameState(documentId);
       },
     },
@@ -635,8 +650,32 @@ function AutoplayControl({ documentId, playing, clock, autoplay, transport }: {
     : unavailable === 'not-running'
       ? armed ? 'Armed — turns on once the game is running' : 'Available once the game is running'
       : null;
+  // THE BEHAVIOUR TO RUN, when the bot offers several: chosen here, as `play autoplay on <behaviour>`
+  // names it. Shown with the one driving (or armed) selected, else the bot's first.
+  const behaviors = autoplay.behaviors ?? [];
+  const [picked, setPicked] = useState<string | null>(null);
+  const behavior = autoplay.on || armed ? autoplay.behavior ?? null : picked !== null && behaviors.includes(picked) ? picked : behaviors[0] ?? null;
+  const driver = driverOf(playing, autoplay);
+  // Said while nobody drives; once the person's input reaches the game, the driver line says they are.
+  const limitNote = driver !== 'none' ? null
+    : autoplay.by === 'limit' && autoplay.limit ? `Autoplay stopped at its ${Math.round(autoplay.limit)} s limit`
+    // An arm the start could not take says why, rather than leaving the person to wonder.
+    : autoplay.refused ? `Autoplay didn’t start: ${autoplay.refused}` : null;
+  const botLine = [autoplay.behavior, autoplay.state].filter(Boolean).join(' — ');
   return (
     <div style={{ display: 'flex', alignItems: 'center', gap: TIMELINE_CHROME.headerGap, minWidth: 0 }}>
+      {behaviors.length > 1 && (
+        <select
+          data-testid="model-play-autoplay-behavior"
+          title="The bot behaviour Autoplay runs"
+          value={behavior ?? ''}
+          disabled={autoplay.on}
+          onChange={(event) => setPicked(event.target.value)}
+          style={{ background: TIMELINE_CHROME.widget, color: TIMELINE_CHROME.widgetText, border: 'none', borderRadius: TIMELINE_CHROME.widgetRadius, font: 'inherit', minWidth: 0 }}
+        >
+          {behaviors.map((name) => <option key={name} value={name}>{name}</option>)}
+        </select>
+      )}
       {/* The tooltip lives on a wrapper too: a disabled button is the one that most needs it. */}
       <span title={label} style={{ display: 'inline-flex' }}>
       {/* KEEP THE KEYBOARD OFF THIS BUTTON (`GameButton`'s `keepFocus`). Left focused, a person
@@ -652,8 +691,8 @@ function AutoplayControl({ documentId, playing, clock, autoplay, transport }: {
         // between the render and the click.
         onClick={() => {
           const now = transport.autoplay?.(documentId) ?? NO_BOT;
-          if (!(extension()?.playing(documentId) ?? false)) transport.armAutoplay?.(documentId, !now.armed);
-          else transport.setAutoplay?.(documentId, !now.on, 'panel');
+          if (!(extension()?.playing(documentId) ?? false)) transport.armAutoplay?.(documentId, !now.armed, { behavior });
+          else transport.setAutoplay?.(documentId, !now.on, 'panel', now.on ? undefined : { behavior });
         }}
       >
         Autoplay
@@ -664,12 +703,17 @@ function AutoplayControl({ documentId, playing, clock, autoplay, transport }: {
           {note}
         </span>
       ) : playing && (
+        // WHO DRIVES, AND WHAT THE BOT SAYS IT IS DOING: "Bot driving · win — heading to nest 2".
+        // Nobody drives a game that runs on no input; the person only once their input reached it.
         <span
           data-testid="model-play-driver"
-          data-driver={autoplay.on ? 'bot' : 'person'}
-          style={{ color: autoplay.on ? TIMELINE_THEME.playhead : TIMELINE_CHROME.widgetText, whiteSpace: 'nowrap' }}
+          data-driver={driver ?? undefined}
+          title={autoplay.state ? `The bot: ${autoplay.state}` : undefined}
+          style={{ color: autoplay.on ? TIMELINE_THEME.playhead : TIMELINE_CHROME.widgetText, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis', minWidth: 0 }}
         >
-          {autoplay.on ? 'Bot driving' : 'You’re driving'}
+          {driver === 'bot' ? `Bot driving${botLine ? ` · ${botLine}` : ''}`
+            : limitNote ? `${limitNote}${autoplay.state ? ` — ${autoplay.state}` : ''}`
+            : driver === 'person' ? 'You’re driving' : 'Nobody’s driving'}
         </span>
       )}
     </div>

package/contributions/blender.command.ts

@@ -57,6 +57,7 @@ export const commands: CommandContribution['commands'] = {
   // Stop drains accepted modeling work and persists it before teardown.
   'blender-stop': verb('none', 30 * 60_000),
   'blender-execute': verb('always', 30 * 60_000),
+  'blender-native-preview': verb('none', 120_000),
   'blender-scene-info': verb('none', 60_000),
   'blender-object-info': verb('none', 60_000),
   'blender-screenshot-view': verb('always', 60_000),

package/dist-node/serving.mjs

@@ -117,9 +117,13 @@ async function blenderWasmStatus(env = process.env) {
         `${dir} holds neither ${BLENDER_WASM_FILES.join(", ")} (the standalone skew) nor ${BLENDER_WALI_ARTIFACT} (the substrate skew)`
       ]
     };
-  return skew === "wali" ? waliStatus(dir) : emscriptenStatus(dir);
+  return skew === "wali" ? waliStatus(dir) : emscriptenStatus(dir, env);
 }
-async function emscriptenStatus(dir) {
+var BROWSER_SUBSTRATE_VARIABLE = "BROWSER_SUBSTRATE_URL";
+function servedFromTab(env = process.env) {
+  return (env[BROWSER_SUBSTRATE_VARIABLE] ?? "").trim() !== "";
+}
+async function emscriptenStatus(dir, env) {
   const sizes = {};
   const encoded = {};
   const missing = [];
@@ -132,7 +136,7 @@ async function emscriptenStatus(dir) {
     sizes[file] = found.size;
     if (found.encoding) encoded[file] = found.encoding;
   }
-  return { available: missing.length === 0, skew: "emscripten", dir, sizes, encoded, missing, digests: await emscriptenDigests(dir) };
+  return { available: missing.length === 0, skew: "emscripten", dir, sizes, encoded, missing, digests: await emscriptenDigests(dir), inTab: servedFromTab(env) };
 }
 async function emscriptenDigests(dir) {
   const digests = {};

package/host/blender-runtime-host.ts

@@ -20,12 +20,9 @@
  * through `capture-active-document`, after `blender-screenshot-view` has
  * presented the model with the viewport's own camera.
  *
- * A RENDER photographs a detached revision through its own camera. three.js is
- * the renderer (ARCHITECTURE-CORE, "No second implementation of a substrate
- * capability ships"), so `bpy.ops.render.render()` arrives here as a present
- * whose capture carries the SCENE camera and `scene.render`'s resolution, and
- * the PNG goes straight back to the operator that asked — the one case where
- * presenting answers with pixels instead of remembering a view.
+ * VOLTER_THREE photographs a detached revision through its own camera.
+ * Native CYCLES renders inside the Blender worker. A native preview is a
+ * read of that document through Cycles, separate from its Three presentation.
  */
 
 import {
@@ -56,8 +53,7 @@ import {
   resolveSceneLinearDisplay,
   type LinearCaptureFrame,
 } from '@volter/editor-threejs/capture/scene';
-import { fitClipPlanes } from '@volter/editor-threejs/viewport/clip-planes';
-import { contentWorldBounds } from '@volter/editor-threejs/viewport/content-bounds';
+import {blenderRenderCamera} from '@volter/blender-engine/browser/three/blender-render-camera';
 import * as THREE from 'three';
 import { blenderEngineSelection, refreshBlenderOutliner } from '../contributions/blender-outliner-model';
 import {
@@ -162,6 +158,7 @@ export async function photographSnapshot(
   await snapshot.prepare(renderCamera);
   assertCurrent();
   const captureOptions = {
+    prepareDraw:snapshot.prepareDraw,
     effect: snapshot.effect,
     width: render.width,
     height: render.height,
@@ -222,16 +219,29 @@ export function bindModelDocument(bound: ModelDocumentBinding | null): () => voi
   };
 }
 
-function modelDocumentConflict(): string | null {
-  const held = runtime?.document;
-  // The finder owns model:<path>, wrapped by the host as document:<entry>.
-  // Read the active address too: activation precedes the contributed pane's
-  // effect, so an immediate command must not slip through that binding gap.
+/** The `.blend` the editor is showing as the Model: the active tab's own file, or the bound one.
+ * The finder owns model:<path>, wrapped by the host as document:<entry>. Read the active address
+ * too: activation precedes the contributed pane's effect, so an immediate command must not slip
+ * through that binding gap. */
+function shownModelBlend(): string | undefined {
   const activeId = editorHost().documents.activeId();
-  const requested = activeId?.startsWith('document:model:')
+  return activeId?.startsWith('document:model:')
     ? activeId.slice('document:model:'.length)
     : boundModel?.blend;
+}
+
+/**
+ * A script's Save As into a project `.blend` that no Model document lists (`followMovedDocument`): Blender edits
+ * that file and saves there, and the tab it left (`from`) keeps showing Blender, since there is no tab to move to.
+ * Without this, every later call was refused as a conflict naming a file no tab can show.
+ */
+let unlistedFollow: { readonly owner: BlenderRuntime; readonly from: string; readonly document: string } | null = null;
+
+function modelDocumentConflict(): string | null {
+  const held = runtime?.document;
+  const requested = shownModelBlend();
   if (!requested || !held || requested === held) return null;
+  if (unlistedFollow !== null && unlistedFollow.owner === runtime && unlistedFollow.document === held && unlistedFollow.from === requested) return null;
   // Say how to get Blender onto the document the editor shows, not only how to go back: an agent told
   // just "return to <held>" took it as the Blender door being unusable and built its level by
   // another route (2026-10-06, the WSL obby run).
@@ -513,12 +523,14 @@ export async function blenderViewShading(shading: 'WIREFRAME' | 'SOLID' | 'MATER
  * a first version read `answer.executed`/`answer.error` off the string, where
  * both are `undefined` — every operator RAN and every caller was told it had
  * failed, which is how an added sphere reached `bpy.data.objects` and the
- * Outliner and was never selected. `sessionDocumentPath` below parses the same
- * two prefixes and records the same lesson from its own bug; this is the
- * second time, so the parse lives at the door now and both read it.
+ * Outliner and was never selected. Read-only metadata uses dedicated native
+ * reads rather than this execute path, which always presents a mutation.
  */
 export async function blenderExecute(code: string, history = true, label = 'Blender Python'): Promise<BlenderExecuteAnswer> {
-  const text = await blenderRuntime().execute(code, history, label);
+  const session = blenderRuntime();
+  const text = await session.execute(code, history, label);
+  // Before the caller hears back: its next call must find the tab on the file Blender now holds.
+  await followMovedDocument(session);
   noteBlenderRnaChanged();
   const failed = /^Error executing code:/.exec(text);
   return {
@@ -529,6 +541,71 @@ export async function blenderExecute(code: string, history = true, label = 'Blen
   };
 }
 
+/**
+ * A Save As the worker reported (`BlenderRuntimeOptions.documentMoved`) that the open Model tab
+ * has not followed yet. Taken by the {@link blenderExecute} whose script moved it, once that
+ * call's own save has landed the new file in the project.
+ */
+let unfollowedMove: { readonly owner: BlenderRuntime; readonly from: string; readonly document: string } | null = null;
+
+/**
+ * THE MODEL TAB FOLLOWS BLENDER'S SAVE AS. The runtime already holds the new file and its saves
+ * go there (`session.py::follow_open_file`); what is left is the tab. Until it moves, the editor
+ * is showing the old file while Blender edits the new one, which `modelDocumentConflict` refuses
+ * on every later call. So the new file's own Model document is opened: it binds to the session
+ * that already holds that file (no stop, no reload), and the old tab, no longer active, releases
+ * its binding. Re-activating the old tab later opens the old file the ordinary way.
+ *
+ * Only a tab that was showing the old file (or the standing Model of a project that had no
+ * `.blend`) is moved; a person who has since switched elsewhere is not pulled back. A new file
+ * no Model document lists (outside the project's model finder) is said, not guessed at.
+ */
+async function followMovedDocument(owner: BlenderRuntime): Promise<void> {
+  const move = unfollowedMove;
+  if (!move || move.owner !== owner) return;
+  unfollowedMove = null;
+  const host = editorHost();
+  // The tab showing Blender: the file Blender left, or, after an earlier Save As to an unlisted file, the tab
+  // that one left.
+  const shownFrom = unlistedFollow !== null && unlistedFollow.owner === owner && unlistedFollow.document === move.from ? unlistedFollow.from : move.from;
+  unlistedFollow = null;
+  const stillShowingOld = () => {
+    if (runtime !== owner || owner.document !== move.document) return false;
+    const shown = shownModelBlend();
+    return shown === shownFrom || (shown === undefined && host.documents.activeId() === BLENDER_RUNTIME_DOCUMENT_ID);
+  };
+  if (!stillShowingOld()) return;
+  try {
+    // The table re-reads the project's files, which now include the file this call saved.
+    const table = await host.project.documentTable();
+    const entry = table.entries.find(candidate => candidate.kind === 'model' && candidate.source?.path === move.document);
+    if (!entry) {
+      if (!stillShowingOld()) return;
+      unlistedFollow = { owner, from: shownFrom, document: move.document };
+      host.console.warn(
+        `Blender now has ${move.document} open and the model saves there. No Model document lists that file ` +
+          `(the project's model finder does not include its folder), so the ${shownFrom} tab keeps showing ` +
+          `Blender, which now edits ${move.document}; ${shownFrom} keeps what it last saved. Save the model ` +
+          `under src/models/ to give it a Model tab of its own.`,
+        'blender-document',
+      );
+      return;
+    }
+    if (!stillShowingOld()) return;
+    if (!await host.workspace.open({ kind: 'document', id: entry.id })) {
+      keepShowing();
+      host.console.warn(`Blender now has ${move.document} open, but its Model document ${entry.id} did not open; the ${shownFrom} tab keeps showing Blender, which edits ${move.document}.`, 'blender-document');
+    }
+  } catch (error) {
+    keepShowing();
+    host.console.error(`The Model tab could not follow Blender to ${move.document}: ${error instanceof Error ? error.message : String(error)}`, 'blender-document');
+  }
+  /** A tab that could not move keeps working on the file Blender holds, as for an unlisted file. */
+  function keepShowing(): void {
+    if (stillShowingOld()) unlistedFollow = { owner, from: shownFrom, document: move!.document };
+  }
+}
+
 /** Coalesce a human gesture; Blender retains the states, Code-OSS the ordering. */
 export function beginBlenderGesture(): void {
   void blenderRuntime().historyGesture('history-begin').catch(error =>
@@ -1033,35 +1110,10 @@ export function blenderRuntime(): BlenderRuntime {
         );
         const focus = new THREE.Vector3(target[0], target[1], target[2]).applyMatrix4(toDocument);
         const upward = new THREE.Vector3(up[0], up[1], up[2]).applyMatrix3(documentBasis);
-        const aspect =
-          Math.min(2048, Math.round(render.width)) / Math.min(2048, Math.round(render.height));
-        // Fit clipping to this snapshot and photograph's eye, independently of
-        // the user's navigation. Editor furniture never enters this scene.
-        const bounds = contentWorldBounds(snapshot.root).getBoundingSphere(new THREE.Sphere());
-        const documentView = fitClipPlanes(eye.distanceTo(bounds.center), bounds.radius);
-        let renderCamera: THREE.Camera;
-        if (render.orthographic) {
-          // An ORTHO scene camera. `fov` carries `ortho_scale` as the VERTICAL
-          // extent in Blender units (`_vertical_extent` applies `sensor_fit`), so
-          // the frustum is stated outright instead of being reverse-derived from
-          // a perspective camera's distance and angle.
-          const halfHeight = render.fov / 2;
-          renderCamera = new THREE.OrthographicCamera(
-            -halfHeight * aspect,
-            halfHeight * aspect,
-            halfHeight,
-            -halfHeight,
-            documentView.near,
-            documentView.far,
-          );
-        } else {
-          renderCamera = new THREE.PerspectiveCamera(
-            render.fov,
-            aspect,
-            documentView.near,
-            documentView.far,
-          );
-        }
+        // The native camera's near/far and lens shift describe this picture.
+        // Geometry bounds are for interactive navigation, not render framing.
+        const documentScale = eye.distanceTo(focus);
+        const renderCamera = blenderRenderCamera(render, documentScale);
         renderCamera.up.copy(upward);
         renderCamera.position.copy(eye);
         renderCamera.lookAt(focus);
@@ -1107,6 +1159,19 @@ export function blenderRuntime(): BlenderRuntime {
     // traceback out of it.
     // biome-ignore lint/suspicious/noConsole: the Blender worker's log is page output by design.
     log: (level, text) => console[level](`[blender] ${text}`),
+    // A SCRIPT'S SAVE AS MOVED THE DOCUMENT. Said in the editor's console, where the change of
+    // file is a fact a person needs; the tab follows once the script's call answers
+    // (`followMovedDocument`), when the new file is in the project to open.
+    documentMoved: (moved) => {
+      const owner = runtime;
+      if (!owner) return;
+      unfollowedMove = { owner, from: moved.from, document: moved.document };
+      editorHost().console.log(
+        `Blender now has ${moved.document} open (a script saved or opened it there), so the model saves to ` +
+          `${moved.document} from now on; ${moved.from} keeps what it last saved.`,
+        'blender-document',
+      );
+    },
   });
   const session = runtime;
   // MEASUREMENT, PUBLISHED THE MOMENT THE SESSION EXISTS. The worker cannot say
@@ -1152,36 +1217,14 @@ const string = (cmd: Record<string, unknown>, key: string): string => {
 /**
  * The project-relative path of the `.blend` the SESSION'S PYTHON currently
  * holds — `bpy.data.filepath`, which a bake script's own `open_mainfile`
- * retargets and the session's bound document does not. Answers `{}` when there
+ * retargets as it runs (the session's document follows only once the call has
+ * ended, and only inside the project). Answers `{}` when there
  * is no file (a scene modelled from scratch has never been saved) or when the
  * path is outside the project, because a record is better absent than wrong.
  */
-async function sessionDocumentPath(session: {
-  execute(code: string, history?: boolean): Promise<string>;
-}): Promise<{ document?: string }> {
+function sessionDocumentPath(filepath: string): { document?: string } {
   const project = editorHost().projectLocalState.projectRootPath();
   if (project === null) return {};
-  let answer: string;
-  try {
-    answer = await session.execute('import bpy\nprint(bpy.data.filepath)\n', false);
-  } catch {
-    return {};
-  }
-  // PARSE WHAT `execute` ACTUALLY ANSWERS, which is the MCP door's shape and
-  // not raw stdout: `Code executed successfully: <stdout>` on ONE line, or
-  // `Error executing code: …`. A first version filtered for lines starting
-  // with `/` and therefore matched nothing, because the path sits after that
-  // prefix on the same line — and a document that cannot be read is
-  // indistinguishable from a session that has none, so the failure was silent
-  // and the nine bakes recorded no input at all.
-  if (/^Error executing code:/m.test(answer)) return {};
-  const filepath =
-    answer
-      .replace(/^Code executed successfully:/, '')
-      .split('\n')
-      .map((line) => line.trim())
-      .filter((line) => line.startsWith('/'))
-      .pop() ?? '';
   if (filepath === '') return {};
   const root = project.endsWith('/') ? project : `${project}/`;
   if (!filepath.startsWith(root)) return {};
@@ -1272,10 +1315,17 @@ export async function handleBlenderCommand(cmd: {
         // project's document is its own `src/models/<name>.blend`, and a
         // `blender-start` that named none is asking for the session this tab
         // is showing, not for a second file beside it.
+        // After a script's Save As to a file no Model lists, the session this tab
+        // shows holds that file (`unlistedFollow`), and a start naming none
+        // asks for it, not for the file the tab was opened on.
+        const shown =
+          unlistedFollow !== null && unlistedFollow.owner === session && unlistedFollow.from === (boundModel?.blend ?? DEFAULT_BLENDER_DOCUMENT)
+            ? unlistedFollow.document
+            : boundModel?.blend;
         const document =
           requestedDocument !== undefined
             ? requestedDocument
-            : (boundModel?.blend ?? DEFAULT_BLENDER_DOCUMENT);
+            : (shown ?? DEFAULT_BLENDER_DOCUMENT);
         return { ok: true, data: { ...(await session.start(project!, document)) } };
       }
       case 'blender-execute': {
@@ -1435,6 +1485,17 @@ export async function handleBlenderCommand(cmd: {
         const document = { kind: 'document', id: boundModel?.entryId ?? 'blender:runtime' };
         return { ok: true, data: { ...await session.screenshotView(maxSize), document } };
       }
+      case 'blender-native-preview': {
+        const camera = cmd['camera'];
+        if (camera !== undefined && typeof camera !== 'string') throw new Error('Native preview camera must be a name');
+        const preview = await session.nativePreview({
+          width: cmd['width'] as number,
+          height: cmd['height'] as number,
+          samples: cmd['samples'] as number,
+          ...(camera === undefined ? {} : { camera }),
+        });
+        return { ok: true, data: { ...preview } };
+      }
       case 'blender-read-file': {
         // The bytes go out as a BODY, not inside this command's answer -- see
         // `/__editor/blender-file` in `server/routes/relay.ts` for the
@@ -1464,13 +1525,13 @@ export async function handleBlenderCommand(cmd: {
         // what it can honestly name is this session and the model state it had
         // reached — taken here, at the instant of the listing, rather than
         // asked for afterwards when another call may have moved it.
-        const entries = await session.listFiles(string(cmd, 'path'));
-        const presented = session.presented;
+        const { entries, document } = await session.listFilesSnapshot(string(cmd, 'path'));
         return {
           ok: true,
           data: {
             entries,
-            ...(presented ? { session: presented.session, revision: presented.revision } : {}),
+            session: document.session,
+            revision: document.revision,
             // AND WHAT THE BYTES WERE MADE FROM. A session-written `.glb` is
             // exported from a `.blend`, and that path is the one fact that
             // lets a reader go DOWN by kind later — from a prefab's glTF to
@@ -1481,14 +1542,14 @@ export async function handleBlenderCommand(cmd: {
             // IT IS ASKED OF PYTHON, NOT OF `boundModel`, and that distinction
             // is a measurement rather than a preference. `boundModel` is the
             // document the TAB opened; a bake script opens its own file with
-            // `wm.open_mainfile`, which `bind_document` deliberately leaves
-            // alone (it retargets `bpy.data.filepath`, not the session's
-            // document). Measured 2026-09-19: reading `boundModel` recorded
+            // `wm.open_mainfile`, which retargets `bpy.data.filepath` at once,
+            // the tab only after the call (`followMovedDocument`), and never
+            // for a file outside the project. Measured 2026-09-19: reading `boundModel` recorded
             // the SAME `.blend` as the input of all three of first-person's
             // characters — whichever one the tab happened to show — which is
             // worse than no record, because it is a confident wrong answer.
             // `bpy.data.filepath` is what the export actually came out of.
-            ...(await sessionDocumentPath(session)),
+            ...sessionDocumentPath(document.filepath),
           },
         };
       }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/editor-blender",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only AND GPL-3.0-or-later",
-  "version": "0.1.131",
+  "version": "0.1.133",
   "publishConfig": {
     "access": "public"
   },
@@ -72,15 +72,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.1",
-    "@volter/blender-engine": "0.1.129",
-    "@volter/editor-threejs": "0.5.192",
+    "@volter/blender-engine": "0.1.131",
+    "@volter/editor-threejs": "0.5.194",
     "zod": "^4.3.6",
     "@fortawesome/free-solid-svg-icons": "^7.2.0"
   },
   "peerDependencies": {
-    "@volter/editor-live": "0.5.192",
-    "@volter/editor-project": "0.5.192",
-    "@volter/editor-sdk": "0.5.192",
+    "@volter/editor-live": "0.5.194",
+    "@volter/editor-project": "0.5.194",
+    "@volter/editor-sdk": "0.5.194",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "three": "^0.180.0",

package/serving/blender-wasm-artifact.ts

@@ -190,6 +190,10 @@ export interface BlenderWasmStatus {
   /** Emscripten: each file's SHA-256 as it decodes (`BUNDLE.json#rawFiles`,
    *  `essentials.json`), so a page can keep the bytes it fetched once. */
   digests?: Record<string, string>;
+  /** Emscripten: this server runs in the page's own tab ({@link servedFromTab}). Only then does
+   *  the page keep the files in its Cache Storage; served by a process on this machine, the
+   *  browser's HTTP cache keeps them (`blender-emscripten-engine.mts`, `cachedArtifact`). */
+  inTab?: boolean;
   /** WALI only: the `sha256-` SRI of `blender.wasm`. The program loader
    *  refuses any non-blob URL without one, so the session names the exact
    *  bytes it ran. */
@@ -236,10 +240,22 @@ export async function blenderWasmStatus(
           `${BLENDER_WALI_ARTIFACT} (the substrate skew)`,
       ],
     };
-  return skew === 'wali' ? waliStatus(dir) : emscriptenStatus(dir);
+  return skew === 'wali' ? waliStatus(dir) : emscriptenStatus(dir, env);
 }
 
-async function emscriptenStatus(dir: string): Promise<BlenderWasmStatus> {
+/**
+ * WHETHER THIS SERVER RUNS IN THE BROWSER TAB IT SERVES. browser-substrate names its page to the
+ * first process it starts (`BROWSER_SUBSTRATE_URL`, its `openProject`), the project's Procfile runs
+ * `edit` as that process, and `edit` hands its environment to the session it spawns
+ * (`launcher/launch.ts`). A session started on this machine has no such variable.
+ */
+export const BROWSER_SUBSTRATE_VARIABLE = 'BROWSER_SUBSTRATE_URL';
+
+export function servedFromTab(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (env[BROWSER_SUBSTRATE_VARIABLE] ?? '').trim() !== '';
+}
+
+async function emscriptenStatus(dir: string, env: NodeJS.ProcessEnv): Promise<BlenderWasmStatus> {
   const sizes: Record<string, number> = {};
   const encoded: Record<string, 'br'> = {};
   const missing: string[] = [];
@@ -252,7 +268,7 @@ async function emscriptenStatus(dir: string): Promise<BlenderWasmStatus> {
     sizes[file] = found.size;
     if (found.encoding) encoded[file] = found.encoding;
   }
-  return { available: missing.length === 0, skew: 'emscripten', dir, sizes, encoded, missing, digests: await emscriptenDigests(dir) };
+  return { available: missing.length === 0, skew: 'emscripten', dir, sizes, encoded, missing, digests: await emscriptenDigests(dir), inTab: servedFromTab(env) };
 }
 
 /** The decoded bytes' digests the build records, for the files it records them for. */