@volter/blender-engine 0.1.148 → 0.1.150

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>;
@@ -95,11 +57,13 @@ let loadCheckpoint: ((phase: string) => Promise<void>) | null = null;
 
 // ---- The session's document.
 //
-// One session, one `.blend`. `documentPath` is the PROJECT-RELATIVE spelling —
-// the only one that crosses to the server, which joins it to its own root so
-// no host path is ever on the wire.
+// One `.blend` at a time, the one `open-document` last named (or a script's Save As moved
+// to). `documentPath` is the PROJECT-RELATIVE spelling — the only one that crosses to the
+// server, which joins it to its own root so 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,10 +250,70 @@ 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;
 }
 
-async function startBlender(project: string, document?: string): Promise<unknown> {
+/**
+ * OPEN `document` IN THE RUNNING BLENDER from the project's file, or as `backup` (its unsaved state at a
+ * restart): another `.blend`, or the one it holds again (a revert, a restore). The project's copy is staged
+ * in fresh, 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.
+ *
+ * A failure before Blender's own open (the path, the file's staging, a backup with no project file) leaves
+ * Blender as it was, holding the document it held, and answers `notOpened` with why; one inside Blender's
+ * open throws.
+ */
+async function openDocument(document: string, backup?: Uint8Array): Promise<unknown> {
+  if (!engine || !projectRoot) throw new Error('The Blender session has not started');
+  try {
+    await stageDocument(engine, projectRoot, document, backup);
+  } catch (error) {
+    return { notOpened: describeThrown(error) };
+  }
+  documentPath = document;
+  const opened = await engine.request({ op: 'open-document', document });
+  setDocumentDirty(backup !== undefined);
+  return opened;
+}
+
+/** `document`'s file staged into the engine for its open, from the project or as `backup`. */
+async function stageDocument(engine: BlenderEngine, projectRoot: string, document: string, backup?: Uint8Array): Promise<void> {
+  // The document is the project's own file and is named the project's own way. An absolute path here
+  // would be a host path on the wire and a destination the page chose, which this transport never carries.
+  if (!isDocumentPath(document))
+    throw new Error(
+      `The Blender document must be a project-relative .blend path with no traversal ` +
+        `(models/model.blend); got ${JSON.stringify(document)}`,
+    );
+  // The file given up and the one opened leave the engine and are staged again from the project: the
+  // one given up was saved there, and its copy here is the session's no longer (a script reads it, and a
+  // listing of the session's own files leaves it out, as it does every project file staged in).
+  for (const path of new Set([documentPath, document].flatMap((held) => held === null ? [] : [`${projectRoot}/${held}`]))) {
+    staged.delete(path);
+    try {
+      await engine.files.unlink(path);
+    } catch {
+      /* not in the engine: never staged, or the open already removed it */
+    }
+  }
+  const path = `${projectRoot}/${document}`;
+  // The document itself not reaching the engine is a refusal, not a footnote: the open would
+  // fail on a missing file (or open a stale copy) without saying why.
+  const failed = await stageProjectFiles(engine.files, projectRoot);
+  const mine = failed.find((line) => line.startsWith("The project's files are not readable") || line.startsWith(`${document} `));
+  if (mine) throw new Error(`${document} could not be copied into Blender, so it cannot be opened: ${mine}`);
+  await loadCheckpoint?.('project-imported');
+  if (backup) {
+    const host = staged.get(path)?.host;
+    if (host === undefined) throw new Error(`${document} could not be read from the project`);
+    await engine.files.writeFile(path, backup);
+    staged.set(path, { host, engine: await stampOf(engine.files, path) });
+  }
+}
+
+async function startBlender(project: string): Promise<unknown> {
   // The engine is named through a holder rather than the module-level
   // `engine`, because `ask` is handed to the engine before the engine exists.
   const holder: { engine: BlenderEngine | null } = { engine: null };
@@ -283,8 +323,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,37 +404,9 @@ 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.
-  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.
-    const failed = await stageProjectFiles(started.files, project);
-    const mine = failed.find((line) => line.startsWith("The project's files are not readable") || line.startsWith(`${document} `));
-    if (mine) throw new Error(`${document} could not be copied into Blender, so it cannot be opened: ${mine}`);
-  }
-  await loadCheckpoint?.("project-imported");
-  const banner = (await started.request({
-    op: 'start',
-    project,
-    ...(document ? { document } : {}),
-  })) as Record<string, unknown>;
-  if (document) documentPath = document;
+  // The project's files are staged by each call that reads them: a document's open, a script's run.
+  const banner = (await started.request({ op: 'start', project })) as Record<string, unknown>;
   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 +418,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
@@ -429,19 +446,11 @@ export function projectMount(project: string): string {
   return /^[A-Za-z]:[\\/]/.test(project) ? `/${project.replaceAll('\\', '/')}` : project;
 }
 
-async function start(hostProject: string, document?: string): Promise<unknown> {
+async function start(hostProject: string): Promise<unknown> {
   if (session) throw new Error('The Blender session is already started');
   const project = projectMount(hostProject);
   if (!project.startsWith('/'))
     throw new Error("The Blender session needs the project's absolute path");
-  // The document is the project's own file and is named the project's own way.
-  // An absolute path here would be a host path on the wire and a destination
-  // the page chose, which is the one thing this transport does not carry.
-  if (document !== undefined && !isDocumentPath(document))
-    throw new Error(
-      `The Blender document must be a project-relative .blend path with no traversal ` +
-        `(models/model.blend); got ${JSON.stringify(document)}`,
-    );
   const served = await blenderIsServed();
   if (!served.available)
     throw new Error(
@@ -450,7 +459,7 @@ async function start(hostProject: string, document?: string): Promise<unknown> {
         '(packages/blender-engine/wasm, or the directory VOLTER_BLENDER_WASM_DIR names); nothing stands in for it.',
     );
   projectRoot = project;
-  return startBlender(project, document);
+  return startBlender(project);
 }
 
 /** A project-relative `.blend`, with no traversal and no absolute root. The
@@ -505,26 +514,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 +522,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 +571,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 +582,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 +603,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 +629,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[];
@@ -683,7 +673,7 @@ async function handle(request: WorkerRequest): Promise<unknown> {
   switch (request.op) {
     case 'start': {
       if (loadJob) throw new Error('The Blender load has already started');
-      return pullWork('start', () => start(request.project, request.document));
+      return pullWork('start', () => start(request.project));
     }
     case 'load-next':
       if (!loadJob) throw new Error('No Blender load to continue');
@@ -711,9 +701,20 @@ async function handle(request: WorkerRequest): Promise<unknown> {
     case 'flush-document':
       // A flush lands what is pending; a document nothing changed stays the
       // file it was opened from.
+      // (it names what it saved: the tab's handle may already name the next document)
       if (!documentDirty) return { saved: false };
-      await saveDocument();
-      return { saved: true };
+      {
+        const document = documentPath;
+        return { saved: await saveDocument(), ...(document === null ? {} : { document }) };
+      }
+    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 'open-document':
+      return pullWork('open-document', () => openDocument(request.document, request.bytes));
     case 'history-begin':
     case 'history-end':
       return ask({ op: request.op });
@@ -756,12 +757,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 +797,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 +806,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 +848,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 +872,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) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.148",
+  "version": "0.1.150",
   "publishConfig": {
     "access": "public"
   },
@@ -30,7 +30,7 @@
     }
   },
   "peerDependencies": {
-    "three": "^0.180.0",
+    "three": "^0.186.1",
     "zod": "^3.0.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
@@ -47,5 +47,8 @@
   },
   "dependencies": {
     "meshoptimizer": "1.2.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.25.12"
   }
 }