@volter/blender-engine 0.1.148 → 0.1.149

package/browser/volter_three.py

@@ -1,47 +1,4 @@
-"""OUR BLENDER RENDERS WITH THREE.JS -- the ask, shipped INSIDE the Blender.
-
-THE RENDER OVERRIDE IS NOT THE EDITOR'S. `session.py` is the editor tab's
-long-lived session and carries this same override for the session it owns;
-this file is the other delivery of it -- a Blender STARTUP module that ships in
-the pack's resource tree (`scripts/startup/volter_three.py`), so a bare
-`blender -b ... -a` on ANY surface renders with three.js too. Blender imports
-every module in `scripts/startup` and calls its `register()`.
-
-THE ASK SHIPS WITH THE BLENDER; THE ANSWER DOES NOT. What renders is a
-PRESENTER the host attached to this process (`browser/three/attach-presenter.ts`
-around `browser/three/presenter.ts`): a canvas, the frame translated to
-three.js, a camera, the display transform. This file only asks. The channel is
-the directory protocol `session.py`'s header states, with one writer per
-directory:
-
-    <root>/ask/     THIS PROGRAM writes and unlinks; the host only reads.
-    <root>/reply/   the HOST writes and unlinks; this program only reads.
-    <root>/arena.bin  THIS PROGRAM writes (the export door does); host reads.
-
-NO PRESENTER, NO OVERRIDE. `register()` asks `{"op": "hello"}` and waits two
-seconds. Answered, it takes the engine ids and every render is a photograph.
-Unanswered, it prints ONE line naming the root it waited at and registers
-nothing at all, so Blender renders with Cycles -- correct, slow, and never
-silent.
-
-THE ENGINE IS TAKEN ON `load_post`, NOT IN `register()`, and that is a
-measurement. Blender's `bpy.utils.load_scripts` registers every startup module
-BEFORE it enables the add-ons, so at `register()` time `cycles.CyclesRender`
-does not exist yet and taking the `CYCLES` id here would be overwritten by the
-add-on moments later. Measured on the native 5.2.0 LTS oracle
-(`blender -b --python-expr ...` with this module's probe in
-`BLENDER_USER_SCRIPTS`): at `register()` `CYCLES` is unregistered, and the
-FIRST `load_post` -- which Blender fires for the startup file itself, before
-any `--python-expr` runs -- sees `<class 'cycles.CyclesRender'>`. So the
-handler is where the ids are taken, and it runs again after every file load
-because a load re-enables the add-ons and hands `CYCLES` back.
-
-WHAT THIS FILE DOES NOT CARRY, deliberately: the editor session's incremental
-geometry record (every frame ships in full -- `known` is always empty, so no
-presenter can ever be asked about geometry it does not hold), its document,
-its overlays, and its world SHADER reducer. A world here is a CONSTANT
-background or nothing, named as a warning; see `_world`.
-"""
+"""Standalone Blender startup render override. Bare background Blender processes use the presenter’s ask/reply directory protocol, while session.py owns the editor session’s equivalent engine. The package carries protocol and data conversion without importing editor state."""
 
 import base64
 import json
@@ -65,19 +22,7 @@ REPLY = os.path.join(ROOT, "reply")
 EXPORT_BUFFER_PATH = os.environ.get(
     "VOLTER_EXPORT_BUFFER_PATH", os.path.join(ROOT, "arena.bin")
 )
-# THE FRAME'S IDENTITY IS A PAIR, `(session, revision)`, and the presenter
-# refuses a revision that went backwards under a name it already holds. One
-# process is one session; the revision only ever counts up within it.
-#
-# THE PID IS NOT THE NAME, and that is measured rather than cautious. A
-# presenter outlives the Blenders it serves, so two processes' names must
-# differ -- and in the browser the guest's pids START OVER: the second
-# `blender -b ... -a` on one page came up as the same pid, its revision
-# restarted at 1 under a name the view already held at 24, and every render in
-# it died on "The runtime frame is older than the displayed model" (measured
-# 2026-09-20 in the substrate tab; the first run on a freshly loaded page
-# always worked, which is what hid it). The start time is what makes the name
-# this process's own.
+# Identify frames by process session and monotonic revision. Include process start time because guest pids can repeat while a presenter remains alive.
 SESSION = "volter-three:%d-%d" % (os.getpid(), time.time_ns())
 HELLO_TIMEOUT_SECONDS = 2.0
 POLL_SECONDS = 0.002
@@ -87,25 +32,7 @@ _REVISION = [0]
 _WARNED = set()
 _WARNINGS = []
 def _say(line):
-    """One line on Blender's own stderr, resolved at CALL TIME.
-
-    WHERE THIS LINE COMES OUT, and it is not where a reader looks first.
-    MEASURED 2026-09-20 in the substrate tab with the whole command redirected
-    (`blender ... > log 2>&1`): Python's `sys.stderr` in this build is NOT the
-    process's fd 2. `print(..., file=sys.stderr)` and
-    `sys.stderr.buffer.write(...)` BOTH reached the terminal and NEITHER
-    reached the file, while `print()` to stdout reached the file and not the
-    terminal. So the one line this module ever prints -- the one that says
-    Cycles is about to render -- is read on the TERMINAL; a reader who greps
-    only a redirect will conclude the fallback is silent when it is not. That
-    reading cost an hour and a wrong diagnosis; it is written here so it costs
-    nobody else one.
-
-    The stream is taken at call time rather than captured at import because a
-    startup module is imported while Blender is still standing its streams up
-    and nothing here needs the captured one. Both spellings were measured to
-    work; this is the plainer.
-    """
+    """Write to Blender’s current stderr at call time, after the host has attached its streams."""
     print(line, file=sys.stderr or sys.stdout, flush=True)
 
 
@@ -250,8 +177,6 @@ def _export(depsgraph):
 
 
 def _present(depsgraph, capture):
-    if not hasattr(_blender_web, "begin_render_export"):
-        raise RuntimeError("This Blender artifact has no render-evaluated export")
     _blender_web.begin_render_export(depsgraph)
     try:
         answer = ask({"frame": _export(depsgraph), "capture": {**capture, "evaluation": "render"}})
@@ -317,6 +242,8 @@ def _photograph(depsgraph, width, height, linear=False):
         "AgX": "agx",
         "Filmic": "filmic",
         "Khronos PBR Neutral": "neutral",
+        "ACES 1.3": "aces13",
+        "ACES 2.0": "aces20",
     }.get(view.view_transform)
     if transform is None:
         raise RuntimeError(
@@ -349,20 +276,9 @@ def _photograph(depsgraph, width, height, linear=False):
 
 
 def _assert_photographed_from(reported, position, target, up):
-    """The photograph answers with the pose it ACTUALLY used, back in Blender's
-    frame, and it must be the pose that was sent -- exactly, with no tolerance.
-
-    This is an instrument, not a nicety. A render's image is allowed to differ
-    from Cycles (three.js is the renderer), so a camera placed in the wrong
-    frame produces a picture nobody can call wrong: the lane shipped for its
-    whole life photographing the model's underside from below the floor because
-    Blender's Z-up numbers were read as three.js world space.
-
-    The check is exact because the conversion is exact: the model root's world
-    matrix is a signed axis permutation, so a vector through it and its inverse
-    is bit-identical. A mismatch is the conversion being wrong, never the check
-    being too strict -- do not widen it.
-    """
+    """Require the photograph’s camera pose transformed back into Blender’s frame to equal the sent
+    pose exactly. The model root uses a signed axis permutation, so its transform and inverse
+    preserve values without a floating-point tolerance."""
     sent = {"position": position, "target": target, "up": up}
     if not isinstance(reported, dict):
         raise RuntimeError(
@@ -417,19 +333,7 @@ class VolterRenderEngine(bpy.types.RenderEngine):
 
 
 def _fill_result(engine, result, answer, png, width, height):
-    """THE RENDER RESULT HOLDS SCENE-LINEAR PIXELS, and Blender runs the scene's
-    view transform over them wherever it shows or saves one (`write_still`, the
-    Image Editor), as it does over Cycles'. The photograph's PNG is the display
-    image -- the transform already ran -- so loading it put every render
-    through AgX or Filmic twice. Measured 2026-09-28 by Cyclotron's
-    render view: a background 53 against the viewport's 59, a shadow's blue 2
-    against 7. The same capture's linear frame goes in instead: half floats,
-    RGBA, bottom row first, which is Blender's own row order. Linear 0.005,
-    0.05, 0.5 and 4.0 then save under AgX as 8, 58, 170 and 234 (the PNG
-    path saved 3, 53, 160 and 190), and under Standard as 15, 64, 188 and 255,
-    as the PNG path did.
-
-    A renderer that sends no linear frame gets the old path, and says so."""
+    """Load scene-linear capture pixels into RenderResult so Blender applies the view transform once. A presenter without linear pixels uses the declared PNG path."""
     linear = answer.get("linearBase64") if isinstance(answer, dict) else None
     if linear and answer.get("linearWidth") == width and answer.get("linearHeight") == height:
         import numpy

package/browser/worker.ts

@@ -2,47 +2,11 @@ import { PullJob, checkpointStream } from './pull-job.mts';
 import { sendFrameValue } from './frame-stream.mts';
 import { describeThrown } from './describe-thrown.mts';
 export { describeThrown } from './describe-thrown.mts';
-/**
- * THE BLENDER IN THE TAB IS BLENDER (ARCHITECTURE-CORE, owner ruling
- * 2026-09-17): the editor's modeling engine is Blender 5.2 LTS compiled to
- * WebAssembly, running headless in this worker (`blender-engine.mts`), with
- * `session.py` as its one door and three.js as its renderer. The artifact is
- * served by the editor (`/__editor/blender-wasm/*`, `blender-wasm-artifact.ts`);
- * when it is not served, `start` refuses BY NAME. There is no other engine.
- *
- * NOTHING HERE KNOWS WHICH SKEW ANSWERED. Since the 2026-09-18 amendment there
- * are two builds -- the standalone Emscripten module and Blender as a WALI
- * program on browser-substrate -- and `blender-engine.mts` is where they meet.
- * Above that seam this file uses `engine.files`, `engine.readArena()` and
- * `engine.memoryBytes()` and could not tell them apart; ONE GATE, BOTH SKEWS
- * is what that buys.
- *
- * Nothing here touches a server beyond the editor's own routes. A frame
- * leaves through `present` to the Model document; a photograph comes back the
- * same way. The project's own files are staged into the engine's filesystem
- * before every call, and what the session writes is mirrored back out by the
- * transport (`list-files`/`read-file`).
- *
- * THE DOCUMENT'S SAVE BARRIER LIVES HERE. Python's loop cannot ask the tab for anything
- * while it is idle — `serveAsks` only runs inside a request's poll loop, so an
- * `ask` raised between calls is never answered and wedges the Blender pthread.
- * So the session marks a present `saveDue`, this file finishes the command,
- * calls `save-document` as an ordinary request (which Python's loop
- * picks up BETWEEN calls, never mid-call), and carries the bytes to the
- * project through `/__editor/blender-document` BEFORE acknowledging the edit —
- * as a delta: the chunks the server does not hold (`document-chunks.mts`).
- *
- * WHY THE CARRY IS NOT THE MIRROR'S JOB (`volter blender-mcp`, class Mirror):
- * the Mirror is pull-based and runs only after an `execute_blender_code`, so
- * a document saved after the LAST call of a modeling session
- * would never leave the worker — which is exactly the state this closes
- * ("closing the tab loses the model"). The Mirror still lists and mirrors the
- * same file in the MCP lane; it just is not what persistence depends on.
- */
+
 /// <reference types="vite/client" />
 
 import { startupOperation, type BlenderEngine, type BlenderFiles, startBlenderEngine } from './blender-engine.mts';
-import type { CaptureRequest, FileEntry, WorkerReply, WorkerRequest } from './protocol';
+import type { CaptureRequest, FileEntry, ScriptRunAnswer, WorkerReply, WorkerRequest } from './protocol';
 import { documentChunks } from './document-chunks.mts';
 import { columnsToTypedArrays, describeFrame, isColumnDescriptor } from './session-frame.mts';
 
@@ -50,8 +14,6 @@ const post = (reply: WorkerReply) => (self as unknown as Worker).postMessage(rep
 const log = (level: 'log' | 'warn' | 'error', text: string) => post({ op: 'log', level, text });
 
 interface Session {
-  start(project: string): Promise<unknown>;
-  execute(code: string): Promise<unknown>;
   sceneInfo(): Promise<unknown>;
   objectInfo(name: string): Promise<unknown>;
   screenshotView(maxSize: number): Promise<unknown>;
@@ -100,6 +62,8 @@ let loadCheckpoint: ((phase: string) => Promise<void>) | null = null;
 // no host path is ever on the wire.
 let documentPath: string | null = null;
 let documentDirty = false;
+/** The revision the last reported change was. */
+let dirtyRevision: number | null = null;
 // Commands and saves share one lane. In particular a flush cannot overtake
 // an accepted edit, and a later edit cannot race an upload of older bytes.
 let workTail: Promise<unknown> = Promise.resolve();
@@ -180,26 +144,14 @@ function setDocumentDirty(dirty: boolean): void {
 }
 
 /**
- * Save the document and land it in the project.
- *
- * Only called inside the command lane, after previous calls have finished.
- * Failure is a rejection: explicit shutdown must retain the live model.
+ * The document saved into the engine's own filesystem, and its bytes read back out: what a save
+ * carries to the project and a backup keeps. `null` when Blender holds another file's model, so
+ * the session wrote nothing over the document (said, where the person looks).
  */
-async function saveDocument(): Promise<void> {
-  if (!engine || documentPath === null) return;
-  const relative = documentPath;
-  // Each phase's milliseconds, reported with the save: on a large document the save is the
-  // edit's cost, and where it goes differs by host (a tab-served project runs the server here).
-  const ms: Record<string, number> = {};
-  let mark = performance.now();
-  const lap = (phase: string) => {
-    const now = performance.now();
-    ms[phase] = Math.round(now - mark);
-    mark = now;
-  };
+async function engineDocument(relative: string, lap: (phase: string) => void): Promise<{ readonly path: string; readonly bytes: Uint8Array } | null> {
   let answer: { saved?: boolean; path?: string; size?: number; reason?: string; holds?: string };
   try {
-    answer = (await engine.request({ op: 'save-document' })) as typeof answer;
+    answer = (await engine!.request({ op: 'save-document' })) as typeof answer;
     lap('save');
   } catch (error) {
     // A document that cannot be written is the session's work at risk, so it
@@ -210,25 +162,53 @@ async function saveDocument(): Promise<void> {
   // the document. Said each time an edit goes unsaved, where the person looks: the document on
   // disk is the last one saved, and what they see now is not being kept.
   if (answer?.saved === false && answer.reason === 'not-the-document') {
-    setDocumentDirty(false);
-    log('warn', `@@VOLTER-WARN ${relative} is not being saved: Blender holds ${answer.holds ?? 'another file'}, ` +
-      `not its model. Save As a .blend under src/models to keep this as a document of its own, or open ${relative} again to return to it.`);
-    return;
+    const note = `${relative} is not being saved: Blender holds ${answer.holds ?? 'another file'}, ` +
+      `not its model. Save As a .blend under src/models to keep this as a document of its own, or reopen ${relative} to return to it.`;
+    post({ op: 'document-saving', document: relative, note });
+    log('warn', `@@VOLTER-WARN ${note}`);
+    return null;
   }
   if (!answer?.saved || typeof answer.path !== 'string')
     throw new Error(`Blender did not save the document ${relative}`);
-  let bytes: Uint8Array;
   try {
-    bytes = await engine.files.readFile(answer.path);
+    const bytes = await engine!.files.readFile(answer.path);
     lap('read');
+    return { path: answer.path, bytes };
   } catch (error) {
     throw new Error(`The Blender document ${relative} could not be read back out of the engine: ${describeThrown(error)}`);
   }
+}
+
+/**
+ * Save the document and land it in the project: true once the project holds it, false when there was nothing to
+ * save to (no engine or document, or Blender holds another file's model).
+ *
+ * Only called inside the command lane, after previous calls have finished.
+ * Failure is a rejection: explicit shutdown must retain the live model.
+ */
+async function saveDocument(): Promise<boolean> {
+  if (!engine || documentPath === null) return false;
+  const relative = documentPath;
+  // Each phase's milliseconds, reported with the save: on a large document the save is the
+  // edit's cost, and where it goes differs by host (a tab-served project runs the server here).
+  const ms: Record<string, number> = {};
+  let mark = performance.now();
+  const lap = (phase: string) => {
+    const now = performance.now();
+    ms[phase] = Math.round(now - mark);
+    mark = now;
+  };
+  const saved = await engineDocument(relative, lap);
+  if (saved === null) {
+    setDocumentDirty(false);
+    return false;
+  }
+  const { bytes } = saved;
   // The engine's copy is now the newer one, so the stager must stop treating
   // this path as the host's: an entry left in `staged` would make the next
   // call re-fetch the whole document over the session's own save, and would
-  // hide it from `list-files` (which lists only what the SESSION owns).
-  staged.delete(answer.path);
+  // hide it from `list-files-snapshot` (which lists only what the SESSION owns).
+  staged.delete(saved.path);
   let sent = 0;
   try {
     const chunks = await documentChunks(bytes);
@@ -270,7 +250,35 @@ async function saveDocument(): Promise<void> {
     throw new Error(`The Blender document ${relative} was not written to the project: ${describeThrown(error)}`);
   }
   setDocumentDirty(false);
+  post({ op: 'document-saving', document: relative, note: null });
   log('log', `@@VOLTER-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length, sent, ms })}`);
+  return true;
+}
+
+/**
+ * REOPEN THE DOCUMENT from the project's file, or as `backup` (its unsaved state at a restart).
+ * The project's copy is staged in as it is at start, so the stager keeps its host stamp and does
+ * not fetch the file again once Blender has read and removed it (`session.py::bind_document`); a
+ * backup is then written over it. Blender presents what it opened.
+ */
+async function reopenDocument(backup?: Uint8Array): Promise<void> {
+  if (!engine || !projectRoot || documentPath === null) throw new Error('The Blender session holds no document to reopen');
+  const path = `${projectRoot}/${documentPath}`;
+  staged.delete(path);
+  try {
+    await engine.files.unlink(path);
+  } catch {
+    /* the open already removed it */
+  }
+  await stageProjectFiles(engine.files, projectRoot);
+  const host = staged.get(path)?.host;
+  if (host === undefined) throw new Error(`${documentPath} could not be read from the project`);
+  if (backup) {
+    await engine.files.writeFile(path, backup);
+    staged.set(path, { host, engine: await stampOf(engine.files, path) });
+  }
+  await engine.request({ op: 'reopen-document' });
+  setDocumentDirty(backup !== undefined);
 }
 
 async function startBlender(project: string, document?: string): Promise<unknown> {
@@ -283,8 +291,15 @@ async function startBlender(project: string, document?: string): Promise<unknown
     ask: async ({ frame, hold, mesh, image, piece, present, capture, saveDue, checkpoint, evaluation }) => {
       if (typeof checkpoint === 'string') { await loadCheckpoint?.(checkpoint); return {}; }
       if (!holder.engine) throw new Error('The Blender session presented before it started');
-      // Save once after the whole command, never during a partial frame.
-      if (saveDue && documentPath !== null) setDocumentDirty(true);
+      // A CHANGE IS A NEW REVISION: every present of an unsaved document carries `saveDue`, and
+      // reporting each one would tell the workbench's backup the content changed when it did not.
+      if (saveDue && documentPath !== null) {
+        const revision = (frame as { revision?: unknown } | null)?.revision;
+        if (!documentDirty || (typeof revision === 'number' && revision !== dirtyRevision)) {
+          if (typeof revision === 'number') dirtyRevision = revision;
+          setDocumentDirty(true);
+        }
+      }
       // THE ARENA IS READ ONCE PER ASK, and both readers share those bytes: the
       // typed arrays the tab draws from, and the record of what was sent
       // (`describeFrame`). After the post the buffers are detached and the
@@ -357,10 +372,8 @@ async function startBlender(project: string, document?: string): Promise<unknown
   holder.engine = started;
   await loadCheckpoint?.("engine-ready");
   engine = started;
-  // THE PROJECT'S FILES BEFORE THE SESSION'S FIRST ACT, because that act may
-  // be `open_mainfile` on the document — which lives on the host's disk and is
-  // not in the engine's filesystem until it is staged. Every other call stages
-  // on its way in (`execute`); start had nothing to open before it did.
+  // Stage the project’s files before the session starts, including the .blend opened by its first
+  // operation. Later execute calls stage their inputs on entry.
   if (document) {
     // The document itself not reaching the engine is a refusal, not a footnote: the open below
     // would fail on a missing file (or open a stale copy) without saying why.
@@ -376,18 +389,6 @@ async function startBlender(project: string, document?: string): Promise<unknown
   })) as Record<string, unknown>;
   if (document) documentPath = document;
   session = {
-    start: async () => banner,
-    execute: async (code: string) => {
-      const answer = (await started.request({ op: 'execute', code })) as {
-        executed: boolean;
-        result: string;
-        error?: string;
-      };
-      // The MCP door's own shape: a script's failure is TEXT, not a rejection.
-      return answer.error
-        ? `Error executing code: ${answer.error}`
-        : `Code executed successfully: ${answer.result}`;
-    },
     sceneInfo: async () => JSON.stringify(await started.request({ op: 'scene-info' }), null, 2),
     objectInfo: async (name: string) =>
       JSON.stringify(await started.request({ op: 'object-info', name }), null, 2),
@@ -399,12 +400,10 @@ async function startBlender(project: string, document?: string): Promise<unknown
   return {
     ...banner,
     engine: 'blender-wasm',
-    // WHICH BUILD ANSWERED. One gate, both skews: a board that cannot say
-    // which one it measured cannot call a difference a defect in either.
+    // Report the engine build that answered.
     skew: started.skew,
     bootMs: Math.round(started.bootMs),
-    // What the boot handed back (`blender-engine.mts`). Null says this bundle
-    // has no release door and is carrying the payload twice.
+    // Released packed-payload size; WALI has no packed payload and reports null.
     releasedPayloadMB:
       started.releasedPayloadBytes === null
         ? null
@@ -505,26 +504,7 @@ async function projectIndex(project: string): Promise<ProjectFile[] | string> {
   return files;
 }
 
-/**
- * The project files this session has staged IN, and the two stamps that say
- * so: `host`, what the host's index reported (so a re-stage can skip a file
- * that has not moved on disk), and `engine`, what the file looked like in the
- * engine's own filesystem the instant after it was written there.
- *
- * THE SECOND ONE IS WHY THIS IS A PAIR. Ownership is not a property of the
- * PATH, it is a property of the BYTES: a staged file Python never touched is
- * the host's, and the same path after `export_scene.gltf` has written over it
- * is the session's output and has to reach the project. Keyed on the path
- * alone, a re-bake of an artifact that already exists — which is what every
- * bake after the first one is — was listed by nobody and silently went
- * nowhere, while a first bake of a NEW path worked, so nothing about the door
- * looked broken (measured 2026-09-19 re-baking cinematic-story's sky city).
- *
- * `engine` is `size:mtimeMs`, which is what both skews' `stat` answers. A
- * rewrite that lands in the same millisecond at exactly the same length would
- * read as untouched; a bake is seconds long and this is the strongest signal
- * the filesystem offers.
- */
+/** For each staged project file, retain the host stamp and its size:mtimeMs stamp immediately after writing into the engine. A changed engine stamp identifies output that must return to the project even when its path was staged before. */
 const staged = new Map<string, { host: string; engine: string }>();
 
 async function stampOf(files_: BlenderFiles, path: string): Promise<string> {
@@ -532,16 +512,7 @@ async function stampOf(files_: BlenderFiles, path: string): Promise<string> {
   return info ? `${info.size}:${info.mtimeMs}` : '';
 }
 
-/**
- * Copy the project's changed files into the engine, and answer what could NOT be copied.
- *
- * THE ANSWER IS THE POINT (2026-10-06 audit: files that failed to copy were "reported to the
- * console only"). `say` writes the page console once per line, which nobody running a script
- * reads; a script that then opens or loads the missing file fails, or worse succeeds on a
- * stale copy, with no word of why. So every call returns its failures, and the callers put
- * them where the caller of THAT is looking: `execute` appends them to the script's answer, and
- * `start` refuses when the document itself is among them.
- */
+/** Stage changed project files and return copy failures. execute appends them to its answer; start refuses when its document failed to stage. */
 async function stageProjectFiles(files_: BlenderFiles, project: string): Promise<string[]> {
   const files = await projectIndex(project);
   if (typeof files === 'string') return [files];
@@ -590,7 +561,8 @@ async function stageProjectFiles(files_: BlenderFiles, project: string): Promise
 /** What `session.py::follow_open_file` says after a script changed the file Blender holds. */
 type FollowedDocument =
   | { moved: true; from: string; document: string }
-  | { moved: false; from: string; outside: string };
+  | { moved: false; from: string; outside: string }
+  | { moved: false; from: string; notSaving: true; note: string };
 
 /**
  * THE DOCUMENT FOLLOWS BLENDER'S SAVE AS, and the script's caller is told in its own answer.
@@ -600,9 +572,16 @@ type FollowedDocument =
  * whose runtime handle holds the same path. A file outside the project is refused: the editor
  * has no document there, so the session keeps its own and keeps saving to it, and says so
  * naming both files, since the script believes it is now working in the other one.
+ * A notSaving answer is a different state: the engine protects the bound file and writes nothing to it.
  */
 function followDocument(followed: FollowedDocument | undefined): string {
   if (!followed) return '';
+  if ('notSaving' in followed) {
+    post({ op: 'document-saving', document: followed.from,
+      note: `${followed.from} is not being saved because Blender holds another scene. Save this scene as a new .blend inside the project to keep it, or reopen the saved document to return to it.` });
+    log('warn', followed.note);
+    return `\n\n${followed.note}`;
+  }
   if (!followed.moved) {
     const line = `Blender now has ${followed.outside} open, which is outside the project, so the editor cannot ` +
       `follow it there: this session's document stays ${followed.from}, and the model keeps saving to ` +
@@ -614,6 +593,7 @@ function followDocument(followed: FollowedDocument | undefined): string {
     // The session checks the same shape, so this is a broken promise, not a refusal to explain.
     throw new Error(`Blender moved its document to ${JSON.stringify(followed.document)}, which is not a project .blend path`);
   }
+  post({ op: 'document-saving', document: followed.from, note: null });
   documentPath = followed.document;
   // Even a present that failed must not leave the new file only in the engine's filesystem.
   setDocumentDirty(true);
@@ -639,9 +619,9 @@ async function listSessionFiles(files: BlenderFiles, hostRoot: string): Promise<
   const root = projectMount(hostRoot);
   const out: FileEntry[] = [];
   // A root the engine has no directory at holds no output yet, and that is an honest empty
-  // listing. A directory that exists and cannot be read is NOT: until 2026-10-06 every readdir
-  // failure was answered as "no files", which is how a Windows root the engine never had (the
-  // host's `C:\…` instead of `/C:/…`) reported success while nothing reached disk.
+  // listing. A directory that exists and cannot be read is NOT: answering "no files" would let a
+  // root the engine never had (a Windows host's `C:\…` instead of `/C:/…`) report success while
+  // nothing reached disk.
   if ((await files.stat(root)) === null) return out;
   const walk = async (dir: string): Promise<void> => {
     let names: string[];
@@ -712,8 +692,19 @@ async function handle(request: WorkerRequest): Promise<unknown> {
       // A flush lands what is pending; a document nothing changed stays the
       // file it was opened from.
       if (!documentDirty) return { saved: false };
-      await saveDocument();
-      return { saved: true };
+      return { saved: await saveDocument() };
+    case 'snapshot-document': {
+      if (documentPath === null) throw new Error('The Blender session holds no document');
+      const snapshot = await engineDocument(documentPath, () => {});
+      if (snapshot === null) throw new Error(`Blender holds another file's model, not ${documentPath}`);
+      return snapshot.bytes;
+    }
+    case 'revert-document':
+      await reopenDocument();
+      return undefined;
+    case 'restore-document':
+      await reopenDocument(request.bytes);
+      return undefined;
     case 'history-begin':
     case 'history-end':
       return ask({ op: request.op });
@@ -756,12 +747,7 @@ async function handle(request: WorkerRequest): Promise<unknown> {
         ...(request.names === undefined ? {} : { names: request.names }),
       });
     case 'rna-context':
-      // EVERY FIELD IS NAMED HERE, and the omission is silent: this switch
-      // REBUILDS the request rather than forwarding it, so a field added at
-      // `runtime.ts` and read in `session.py` still arrives as `None` and the
-      // door answers about something else entirely. Measured 2026-09-19 (I4
-      // follow-up (a)): `collection` crossed both ends and never the middle,
-      // and the Collection tab simply did not stand.
+      // Forward each request field explicitly to the Python session.
       return ask({
         op: 'rna-context',
         ...(request.object === undefined ? {} : { object: request.object }),
@@ -801,10 +787,7 @@ async function handle(request: WorkerRequest): Promise<unknown> {
         ...(request.object === undefined ? {} : { object: request.object }),
         ...(request.uvLayer === undefined ? {} : { uvLayer: request.uvLayer }),
       });
-    // THE RIG AND CLIP DOORS, every field named for the same reason — and the
-    // reason is a measured defect: I4's Collection tab simply did not stand
-    // because `collection` crossed `runtime.ts` and `session.py` and never
-    // this switch, with no error anywhere.
+    // Forward the clip request fields to the Python session.
     case 'action-clip':
       return ask({
         op: 'action-clip',
@@ -813,6 +796,30 @@ async function handle(request: WorkerRequest): Promise<unknown> {
         ...(request.action === undefined ? {} : { action: request.action }),
         ...(request.summary === undefined ? {} : { summary: request.summary }),
       });
+    case 'scene-movie':
+      return ask({ op: 'scene-movie' });
+    case 'sound-scene':
+      return ask({ op: 'sound-scene', first: request.first, last: request.last });
+    case 'gltf-export':
+      return ask({ op: 'gltf-export', kind: request.kind, force: request.force === true,
+        ...(request.previous ? { previous: request.previous } : {}),
+        ...(request.blendSha256 ? { blendSha256: request.blendSha256 } : {}), ...(request.luts ? { luts: request.luts } : {}) });
+    // A script reads the project's files as `execute`'s does, so they are copied in first; what could not be is
+    // answered beside its run.
+    // (the files a run wrote are read here and taken away, so its answer carries them and no later run can touch them)
+    case 'run-script': {
+      const unstaged = await stageProjectFiles(files, projectRoot);
+      const ran = await ask({ op: 'run-script', source: request.source, args: request.args, dir: request.dir }) as
+        { output: string; error: string | null; files: string[] };
+      const written: { path: string; bytes: Uint8Array }[] = [];
+      for (const path of ran.files) {
+        written.push({ path, bytes: (await files.readFile(`${request.dir}/${path}`)).slice() });
+        await files.unlink(`${request.dir}/${path}`);
+      }
+      return { output: ran.output, error: ran.error, files: written, unstaged } satisfies ScriptRunAnswer;
+    }
+    case 'asset-library':
+      return ask({ op: 'asset-library', library: request.library });
     case 'outliner-set':
       return ask({
         op: 'outliner-set',
@@ -831,33 +838,19 @@ async function handle(request: WorkerRequest): Promise<unknown> {
       staged.delete(request.path);
       return undefined;
     }
-    case 'list-files':
-      return listSessionFiles(files, request.path);
   }
   throw new Error(`Unknown Blender worker request ${(request as { op: string }).op}`);
 }
 
-/**
- * Tell the tab how big the engine's memory is now.
- *
- * O(1) on the standalone skew — a read of the `HEAPU8` view's length — and
- * posted after every call because that is when it can have changed. It is the
- * engine's memory as opposed to the page's: the census already carries
- * `heapUsedMB` (the PAGE's JS heap) and had no field at all for the wasm,
- * which is the larger half. Before the session exists there is nothing to read
- * and nothing is posted, and the substrate skew answers null — its module's
- * memory lives in a worker with no memory door, and a zero there would be a
- * measurement nobody took.
- */
+/** Post the current engine memory size after calls. Before initialization there is no reading; WALI reports null because its memory lives in a separate worker. */
 function reportMemory(): void {
   if (!engine) return;
   const bytes = engine.memoryBytes();
   if (bytes !== null) post({ op: 'memory', bytes });
 }
 
-// A BLENDER THREAD THAT DIES IS WEIGHED FIRST: its error reaches this scope before the page's
-// `onerror`, so the heap it died at is posted ahead of the failure, and the page can say whether
-// the engine ran out of memory (`runtime.ts`) instead of "Uncaught [object Object]".
+// Report heap size before the page handles a worker error so its diagnostic
+// includes the engine's memory state.
 self.addEventListener('error', reportMemory);
 
 self.onmessage = (event: MessageEvent<WorkerRequest>) => {
@@ -869,10 +862,22 @@ self.onmessage = (event: MessageEvent<WorkerRequest>) => {
   void enqueue(() => answerRequest(request));
 };
 
+/** How often the engine's memory is reported while a call runs (`reportMemory`). */
+const MEMORY_REPORT_MS = 5_000;
+
 async function answerRequest(request: WorkerRequest): Promise<void> {
+  // Sample heap size while a long call runs; this worker remains responsive while Blender executes on its pthread.
+  const weighing = setInterval(reportMemory, MEMORY_REPORT_MS);
+  try {
+    await answerRequestNow(request);
+  } finally {
+    clearInterval(weighing);
+  }
+}
+
+async function answerRequestNow(request: WorkerRequest): Promise<void> {
   try {
     const result = await handle(request);
-    if (!loadCheckpoint && documentDirty) await saveDocument();
     await reportHistory();
     post({ id: request.id, result });
   } catch (error) {