@volter/blender-engine 0.1.149 → 0.1.150

package/LICENSE

@@ -34,14 +34,15 @@ this package covered by any commercial licence Volter AI, Inc. offers
 Blender's authors'.
 
 CORRESPONDING SOURCE. The binary in `wasm/` is built from official Blender
-v5.2.0 (`fbe6228777e7d9afefcd61a413844e790ae75db7`) plus the changes reviewed
-at `a4dff7ba16a0cca24504d81ed0086457493e48dc`. The public source snapshot is
-`94d8f20b225d51755a0a93a7fdf1e0cd9f53d09c` in:
+v5.2.0 (`fbe6228777e7d9afefcd61a413844e790ae75db7`) plus Volter's changes, at
+the public source commit `241d224a32033b16b383d5065c6fbc819fcdc1d5` in:
 
   https://github.com/volter-ai/blender
 
-The public release `blender-5.2.0-wasm.1` retains the matching source, build
-instructions, dependency source archives, notices and bundle.
+The public release `blender-5.2.0-wasm.5` retains the matching source archive,
+build instructions, notices and bundle; the dependency source archives the
+source builds with are unchanged since `blender-5.2.0-wasm.1`, which retains
+them. Both stay available for as long as this package is distributed.
 `wasm/BUNDLE.json` records the source pin and artifact hashes;
 `wasm/DEPENDENCY-LICENSES.txt` retains dependency notices. Blender's authorship
 and the GPL terms below are unchanged.

package/browser/blender-emscripten-engine.mts

@@ -218,9 +218,12 @@ export async function startEmscriptenBlenderEngine(
   let bootError: unknown = null;
   const started = performance.now();
   let readyLine: string | null = null;
+  /** The steps of the session's start it has said it began (`@@VOLTER-PHASE`), not yet made load boundaries. */
+  const phases: string[] = [];
   // Route Blender’s stdout and stderr to page output; session conditions use their own reporting channel.
   const say = (_level: 'log' | 'error', text: string) => {
     if (text.startsWith('@@VOLTER-READY ')) readyLine = text.slice('@@VOLTER-READY '.length);
+    if (text.startsWith('@@VOLTER-PHASE ')) { phases.push(text.slice('@@VOLTER-PHASE '.length)); return; }
     options.log(sessionLevel(text), text);
   };
   // Observe the factory’s WebAssembly.Memory and read a fresh buffer view after pthread heap growth. Module.HEAPU8 can retain its previous length until the glue refreshes it.
@@ -305,7 +308,9 @@ export async function startEmscriptenBlenderEngine(
   // long before the session exists. The ready line is what says it does.
   while (readyLine === null) {
     if (bootError) throw bootError instanceof Error ? bootError : new Error(String(bootError));
-    await sleep(5);
+    const phase = phases.shift();
+    if (phase !== undefined) await checkpoint(`session/${phase}`);
+    else await sleep(5);
   }
   const bootMs = performance.now() - started;
   const banner = JSON.parse(readyLine) as { blender: string; engines: string[] };

package/browser/blender-wali-engine.mts

@@ -449,6 +449,8 @@ export async function startWaliBlenderEngine(
     for (const line of text.split('\n')) {
       if (line === '') continue;
       if (line.startsWith('@@VOLTER-READY ')) readyLine = line.slice('@@VOLTER-READY '.length);
+      // (a start step's mark is a load boundary for a staged load, which this start is not)
+      if (line.startsWith('@@VOLTER-PHASE ')) continue;
       // Route Blender streams to page output; named session conditions use their own channel.
       options.log(sessionLevel(line), line);
     }

package/browser/index.ts

@@ -1,6 +1,7 @@
 export type { CaptureRequest, FileEntry, RuntimeStart, NativePreviewRequest, NativePreviewResult, NativeDocumentInfo, FileListSnapshot } from './protocol';
 export {
   BlenderRuntime,
+  DocumentNotOpened,
   type BlenderRuntimeOptions,
   type PresentAnswer,
   type SavedDocument,

package/browser/protocol.ts

@@ -12,16 +12,15 @@ export type WorkerRequest =
   /** The document's bytes as a save would write them, for a backup: nothing is carried to the
    *  project and the document stays dirty. */
   | { id: number; op: 'snapshot-document' }
-  /** Reopen the document from the project's file, discarding what it holds. */
-  | { id: number; op: 'revert-document' }
-  /** Reopen the document as `bytes` (a backup), which is then its unsaved state. */
-  | { id: number; op: 'restore-document'; bytes: Uint8Array }
+  /** Open `document` in the running Blender, as Blender's own File > Open does, from the project's file, or as
+   *  `bytes` (a backup), which is then its unsaved state. `document` is the session's `.blend` from then on,
+   *  PROJECT-RELATIVE (`models/model.blend`): an existing one is opened, an absent one opens as Blender's empty file and
+   *  is created by the first save. Naming the document the session holds reopens it (a revert, a restore). */
+  | { id: number; op: 'open-document'; document: string; bytes?: Uint8Array }
   | { id: number; op: 'history-begin' | 'history-end' }
   | { id: number; op: 'history-step'; token: string; direction: 'undo' | 'redo' }
-  /** `document` is the session's `.blend`, PROJECT-RELATIVE (`models/model.blend`
-   *  by default). An existing one is opened at start; an absent one starts
-   *  empty and is created by the first save. */
-  | { id: number; op: 'start'; project: string; document?: string }
+  /** Blender started at `project`, holding no document until `open-document` names one. */
+  | { id: number; op: 'start'; project: string }
   | { id: number; op: 'execute'; code: string; history?: boolean; label?: string }
   /** A native Cycles photograph, isolated from authoring/history and the
    * Three frame exporter. This is a preview request, not a modeling edit. */
@@ -340,9 +339,13 @@ export interface RuntimeStart {
   python: string;
   /** The engine implementation that answered: standalone Emscripten or WALI on browser-substrate. */
   skew: 'emscripten' | 'wali';
-  /** The session's document, project-relative, when one was named. */
-  document?: string;
+}
+
+/** What `open-document` answers (`session.py::bind_document`). */
+export interface DocumentOpened {
+  /** The session's document, project-relative. */
+  document: string;
   /** True when the project already held that `.blend` and it was OPENED —
-   *  false when the session started empty and will create it on first save. */
-  opened?: boolean;
+   *  false when it opened as Blender's empty file and is created by the first save. */
+  opened: boolean;
 }

package/browser/runtime.ts

@@ -5,10 +5,12 @@ import { HEAP_GROWTH_REFUSED } from './protocol';
 /**
  * The tab-side handle on a Blender session: spawns the worker, forwards wire
  * requests, and hands every presented frame to whoever displays it.
- * One instance per editor tab; the session and its model die with the worker.
+ * One instance per editor tab; the documents it opens one after another share
+ * its Blender, and the session and its model die with the worker.
  */
 import type {
   CaptureRequest,
+  DocumentOpened,
   RuntimeStart,
   WorkerReply,
   WorkerRequest,
@@ -39,6 +41,15 @@ type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : n
 type Request = DistributiveOmit<WorkerRequest, 'id'>;
 
 
+/** An open that failed before Blender's own open (the path, the file's staging): Blender is as it was, holding the
+ *  document it held. */
+export class DocumentNotOpened extends Error {}
+
+/** Calls a Blender giving up its document still takes ({@link BlenderRuntime.releaseDocument}): a backup's read of
+ *  the document it saves, and an asset library in its preferences, which no file holds. Each runs in its turn,
+ *  before the next document's open. */
+const RELEASE_ADMITS: ReadonlySet<string> = new Set(['snapshot-document', 'asset-library']);
+
 /** A script every save of a document runs in the save's own turn (`BlenderRuntime.saveDocument`), as the caller names
  *  it for the document saved: null for none. */
 export type SaveScript = (document: string) => Promise<{ readonly source: string; readonly args: readonly string[] }> | null;
@@ -178,9 +189,12 @@ export class BlenderRuntime {
   /** The script runs this runtime has made, each in a directory of its own. */
   #scriptRuns = 0;
   #terminated = false;
+  /** The document being given up for the next one ({@link releaseDocument}), and its last save. */
+  #release: { readonly document: string; readonly next: string; readonly saved: Promise<SavedDocument | null> } | null = null;
   #dirty = false;
   readonly #beforeUnload = (event: BeforeUnloadEvent): void => {
-    if (!this.#dirty && this.#acceptedRequests === 0) return;
+    // (a Blender holding no document has nothing to lose: its start is not work in progress)
+    if (this.#document === null || (!this.#dirty && this.#acceptedRequests === 0)) return;
     event.preventDefault();
     event.returnValue = '';
   };
@@ -247,9 +261,10 @@ export class BlenderRuntime {
     return this.#project;
   }
 
-  /** The document owned by this worker, including while boot is pending: the startup one, until
-   *  a script's Save As leaves Blender holding another project `.blend` and the session follows
-   *  it there (`session.py::follow_open_file`). */
+  /** The document owned by this worker, from the moment its open is asked for: the one
+   *  {@link openDocument} last named, until a script's Save As leaves Blender holding another
+   *  project `.blend` and the session follows it there (`session.py::follow_open_file`). Null
+   *  while Blender holds none. */
   get document(): string | null {
     return this.#document;
   }
@@ -260,30 +275,15 @@ export class BlenderRuntime {
     return [...this.#lastLines];
   }
 
-  /** Idempotent: the first call boots Blender at `project`'s
-   *  absolute path; later calls await it (a different path is refused).
-   *
-   *  `document` is the session's `.blend`, project-relative. An explicit
-   *  different file is a resource conflict, including while boot is pending.
-   *  Omitting it on an already-started handle means await that same session. */
-  start(project: string, document?: string): Promise<RuntimeStart> {
+  /** Idempotent: the first call boots Blender at `project`'s absolute path, holding no
+   *  document; later calls await it (a different path is refused). */
+  start(project: string): Promise<RuntimeStart> {
     if (this.#project !== null && this.#project !== project)
       return Promise.reject(
         new Error(`The Blender session is bound to ${this.#project}, not ${project}`),
       );
-    if (document !== undefined && this.#document !== null && this.#document !== document)
-      return Promise.reject(
-        new Error(
-          `Blender resource conflict: the session holds ${this.#document}; cannot open ${document}`,
-        ),
-      );
     this.#project = project;
-    this.#document ??= document ?? 'models/model.blend';
-    this.#started ??= (this.#request({
-      op: 'start',
-      project,
-      ...(document === undefined ? {} : { document }),
-    }) as Promise<RuntimeStart>).catch((error: unknown) => {
+    this.#started ??= (this.#request({ op: 'start', project }) as Promise<RuntimeStart>).catch((error: unknown) => {
       this.#startFailed = true;
       throw error;
     });
@@ -510,9 +510,11 @@ export class BlenderRuntime {
   /** A save of the document, and in the same turn, before any other request reaches this Blender, the script `after`
    *  names for the document it wrote (as the worker holds it once saved, a move accepted before it included), run on
    *  the scene just saved, in a working directory of its own, its files carried back in its answer. Null when there
-   *  was nothing to save. */
+   *  was nothing to save. While the document is being given up, the save is the release's own: this resolves when it
+   *  lands, with null (its listeners hear it once, from the release), and fails with it. */
   async saveDocument(after?: SaveScript): Promise<SavedDocument | null> {
     await this.#ready();
+    if (this.#release !== null) return this.#release.saved.then(() => null);
     return this.#inTurn('flush-document', false, () => this.#save(after));
   }
 
@@ -522,16 +524,56 @@ export class BlenderRuntime {
     return (await this.#request({ op: 'snapshot-document' })) as Uint8Array;
   }
 
-  /** Reopen the document from its project file, discarding its changes. */
-  async revertDocument(): Promise<void> {
-    await this.#ready();
-    await this.#request({ op: 'revert-document' });
+  /**
+   * Open `document` (project-relative) in this Blender, once it has started, as its File > Open does: from
+   * the project's file, or as `bytes`, its unsaved state (a backup). Naming the document it holds reopens
+   * it, discarding its changes (a revert, a restore). The handle claims the document at the call, so a
+   * request made after it waits for the open and finds it; the one held before is the caller's to save
+   * first ({@link releaseDocument}). A failure before Blender's own open rejects with {@link DocumentNotOpened}, and
+   * the handle names the document it held again.
+   */
+  openDocument(document: string, bytes?: Uint8Array): Promise<DocumentOpened> {
+    const held = this.#document;
+    this.#document = document;
+    const request = { op: 'open-document', document, ...(bytes === undefined ? {} : { bytes }) } as const;
+    return this.#ready().then(() => this.#inTurn('open-document', false, async () => {
+      // The open the release was for: the document given up is no longer held.
+      if (this.#release?.next === document) this.#release = null;
+      // From this turn on, a frame presented is the opened file's: the last one's is no longer on screen as its.
+      this.#presented = null;
+      const answer = (await this.#wire(request)) as DocumentOpened | { readonly notOpened: string };
+      if (!('notOpened' in answer)) return answer;
+      if (this.#document === document) this.#document = held;
+      throw new DocumentNotOpened(answer.notOpened);
+    }, document));
   }
 
-  /** Reopen the document as `bytes`, its unsaved state. */
-  async restoreDocument(bytes: Uint8Array): Promise<void> {
-    await this.#ready();
-    await this.#request({ op: 'restore-document', bytes });
+  /**
+   * THE DOCUMENT GIVEN UP FOR `next`, ITS LAST SAVE FIRST, as a stop's is: queued behind every request accepted before
+   * it, with `retire.after`'s script in its turn, heard by `landed`. From the call on, no edit is taken, so none lands
+   * after the save, until `next`'s {@link openDocument} has its turn or {@link keepDocument} returns to the document;
+   * a save asked for meanwhile is this one, and a backup's read and an asset library still run in their turns
+   * (`RELEASE_ADMITS`). A save that fails, or a listener that throws, keeps the document, and edits are taken again.
+   */
+  releaseDocument(next: string, retire?: { readonly after?: SaveScript; readonly landed: (saved: SavedDocument) => void }): Promise<void> {
+    if (this.#terminated || this.#stopping) return Promise.reject(new Error('The Blender session is stopping or terminated'));
+    const document = this.#document;
+    if (document === null) return Promise.resolve();
+    const saved = this.#ready().then(() => this.#inTurn('flush-document', true, () => this.#save(retire?.after)));
+    const release = { document, next, saved };
+    this.#release = release;
+    return saved
+      .then((value) => { if (value !== null) retire?.landed(value); })
+      .catch((error: unknown) => {
+        if (this.#release === release) this.#release = null;
+        throw error;
+      });
+  }
+
+  /** The document given up ({@link releaseDocument}) is kept after all, while the handle still names it: edits are
+   *  taken again. Once the next document's open is asked for, that open ends the release instead. */
+  keepDocument(): void {
+    if (this.#release !== null && this.#release.document === this.#document) this.#release = null;
   }
 
   async readFile(path: string): Promise<Uint8Array> {
@@ -563,6 +605,11 @@ export class BlenderRuntime {
   stop(retire?: { readonly after?: SaveScript; readonly landed: (saved: SavedDocument) => void }): Promise<void> {
     if (this.#terminated) return Promise.resolve();
     if (this.#stopping) return this.#stopping;
+    // Holding no document, it has nothing to save, and its start is not waited for.
+    if (this.#document === null) {
+      this.terminate();
+      return Promise.resolve();
+    }
     this.#stopping = (async () => {
       // A start that failed opened no document, so there is nothing to flush: its stale
       // rejection must not refuse every later close.
@@ -580,9 +627,9 @@ export class BlenderRuntime {
 
   /** The save, and its script on the scene it wrote, inside one turn. */
   async #save(after: SaveScript | undefined): Promise<SavedDocument | null> {
-    const { saved } = (await this.#wire({ op: 'flush-document' })) as { saved: boolean };
-    const document = this.#document;
-    if (!saved || document === null) return null;
+    // The document the worker wrote, as it says: this handle may already name the next one.
+    const { saved, document } = (await this.#wire({ op: 'flush-document' })) as { saved: boolean; document?: string };
+    if (!saved || document === undefined) return null;
     const named = after?.(document) ?? null;
     if (named === null) return { document, script: null };
     let script: { readonly source: string; readonly args: readonly string[] };
@@ -696,9 +743,12 @@ export class BlenderRuntime {
     return this.#inTurn(request.op, false, () => this.#wire(request));
   }
   /** One turn of the queue: `run` alone talks to the worker until it is done, whatever it sends. */
-  #inTurn<T>(op: string, shutdown: boolean, run: () => Promise<T>): Promise<T> {
+  #inTurn<T>(op: string, shutdown: boolean, run: () => Promise<T>, opens?: string): Promise<T> {
     if (this.#terminated || (this.#stopping && !shutdown))
       return Promise.reject(new Error('The Blender session is stopping or terminated'));
+    const release = this.#release;
+    if (release !== null && !shutdown && !RELEASE_ADMITS.has(op) && opens !== release.next)
+      return Promise.reject(new Error(`Blender is saving ${release.document} before opening ${release.next}, and takes no edit until ${release.next} is open.`));
     const began = performance.now();
     let endWork = () => {};
     this.#acceptedRequests++;

package/browser/session.py

@@ -1,5 +1,10 @@
 """The tab’s long-lived Blender session. A directory protocol carries requests and replies while one bpy.data remains alive on Blender’s pthread. The page owns in/ and reply/; the guest owns out/ and ask/. Each writer cleans its own files after acknowledgement and removes .done last. Explicit saves write Blender’s native format and let worker.ts return changed output to the project."""
 
+import sys
+
+# The session module begins loading (a start step: see `main`).
+print("@@VOLTER-PHASE module", file=sys.stderr, flush=True)
+
 import array
 import base64
 import hashlib
@@ -8,7 +13,6 @@ import json
 import math
 import os
 import re
-import sys
 import time
 import traceback
 from contextlib import redirect_stdout
@@ -107,6 +111,7 @@ def _load_post(_arg):
     # The DOOR resets its own revision table on LOAD_POST (it holds ID pointers
     # into the Main that just went away); this is the session's half.
     SESSION.forget()
+    SESSION.renew()
     SESSION.loaded()
     # Factory reset reloads add-ons. Preserve native Cycles and re-register
     # only the headless GPU presenters we own.
@@ -1421,10 +1426,10 @@ class Session:
         self._known = {}
         # The last frame's accounting (`_present`), read by `dispatch`.
         self.last_shipped = None
-        # THE SESSION'S DOCUMENT: the `.blend` it opens at start and saves back
+        # THE SESSION'S DOCUMENT: the `.blend` it last opened and saves back
         # into. Absolute (the module filesystem mirrors the project at its own
         # host path) plus the project-relative spelling the tab needs to name
-        # the destination. None until `blender-start` states one.
+        # the destination. None until `open-document` names one.
         self.document = None
         self.document_relative = None
         # Set by a present that left the document behind the model; cleared by
@@ -1452,6 +1457,15 @@ class Session:
         self._known.clear()
         self._action_revisions = {}
 
+    def renew(self):
+        """A NEW PRESENTATION SESSION FOR EACH FILE LOAD: the editor's open of a document, a
+        script's `open_mainfile` or `read_homefile` alike. A load restarts the revisions the export
+        door numbers its datablocks with, and the view keeps a mesh whose session and revision it
+        already holds (`blender-runtime-view.ts`), so another file's "Cube" at the same revision
+        would be drawn as the last one's. A new id makes the view clear what it held and refuse the
+        last file's late frames."""
+        self.session = "blender-%d" % time.time_ns()
+
     def _kept_action_revisions(self, door):
         """Keep action revisions stable across evaluation-only updates. An edit advances
         _ACTION_EDITS and permits the native revision to replace the retained revision. All
@@ -1905,23 +1919,33 @@ class Session:
     def bind_document(self, relative_path):
         """Name the session's document and OPEN it when the project has one.
 
-        One session holds one document. The path is stated at start and moves
-        only where Blender itself moved: a script's own `save_as_mainfile` (or
-        `open_mainfile`) to another `.blend` in the project retargets
-        `bpy.data.filepath`, and `follow_open_file` moves the document with it
-        after the call.
+        The session holds one document at a time: the one the editor last opened
+        here (`open-document`), and it moves otherwise only where Blender itself
+        moved: a script's own `save_as_mainfile` (or `open_mainfile`) to another
+        `.blend` in the project retargets `bpy.data.filepath`, and
+        `follow_open_file` moves the document with it after the call.
 
         `open_mainfile` runs the session's `_load_post` like any other load
         (the export door's revision table is reset, the render engine ids are
         retaken), and the one present afterwards is what puts the reopened
-        model on the tab's screen.
+        model on the tab's screen, as a new presentation session (`renew`).
         """
         self.document_relative = relative_path
         self.document = os.path.join(self.project, relative_path)
         self._foreign = False
         self._foreign_said = False
+        self._outside_file = None
         if not os.path.exists(self.document):
-            return {"document": relative_path, "opened": False}
+            # A DOCUMENT NOT YET WRITTEN OPENS EMPTY: Blender's empty file
+            # (`read_homefile(use_empty=True)`: its scenes, windows and workspaces alone), loaded as the session's
+            # own open, so its first save writes the new model, never the factory startup's cube, light and camera
+            # a fresh worker holds, or the file it held before.
+            self._binding = True
+            try:
+                bpy.ops.wm.read_homefile(use_empty=True)
+            finally:
+                self._binding = False
+            return {"document": relative_path, "opened": False, "presented": self._present_opened(relative_path)}
         _asked({"checkpoint": "document-open"})
         _mark("open:before")
         _blender_web.set_read_checkpoint(lambda: _asked({"checkpoint": "file-read"}))
@@ -1941,10 +1965,19 @@ class Session:
         # Remove the staged .blend after Blender loads it to release its WasmFS bytes before
         # presentation. The worker keeps its host stamp, and the next save rewrites the file.
         os.remove(self.document)
-        # A DOCUMENT BLENDER OPENED IS OPEN, whatever its first present does: a present that
-        # failed the open would leave a saved document unopenable and every MCP call refused.
-        # The model is in Blender, so the session keeps it and says loudly that the view is behind;
-        # the next edit presents again, and can remove whatever the presenter could not take.
+        presented = self._present_opened(relative_path)
+        return {"document": relative_path, "opened": True,
+                "objects": len(bpy.data.objects),
+                "size": size, "presented": presented}
+
+    def _present_opened(self, relative_path):
+        """The first present of a document just opened, and whether it was taken.
+
+        A DOCUMENT BLENDER OPENED IS OPEN, whatever its first present does: a present that
+        failed the open would leave a saved document unopenable and every MCP call refused.
+        The model is in Blender, so the session keeps it and says loudly that the view is behind;
+        the next edit presents again, and can remove whatever the presenter could not take.
+        """
         presented = True
         try:
             self.present()
@@ -1959,9 +1992,7 @@ class Session:
                      "document does not show it yet: %r" % (relative_path, thrown))
         # The load did not dirty anything: what is in memory IS the file.
         self.save_due = False
-        return {"document": relative_path, "opened": True,
-                "objects": len(bpy.data.objects),
-                "size": size, "presented": presented}
+        return presented
 
     def loaded(self):
         """Track file loads that replace the session’s document model. The session’s own document
@@ -5828,23 +5859,19 @@ def _dispatch(request):
         return answer
     if op == "save-document":
         return SESSION.save_document()
-    if op == "reopen-document":
-        # The document's file in the engine's filesystem was just rewritten (a revert, a
-        # backup); open it again as the model.
-        return SESSION.bind_document(SESSION.document_relative)
+    if op == "open-document":
+        # The worker just staged the document's file into the engine's filesystem (another
+        # `.blend`, or this one again for a revert or a backup); open it as the model.
+        return SESSION.bind_document(request["document"])
     if op == "start":
         SESSION.project = request.get("project", SESSION.project)
         try:
             os.chdir(SESSION.project)
         except OSError:
             pass
-        answer = {"session": SESSION.session, "python": sys.version,
-                  "blender": bpy.app.version_string, "engines": ENGINES,
-                  "unavailableEngines": UNAVAILABLE_ENGINES}
-        document = request.get("document")
-        if document:
-            answer.update(SESSION.bind_document(document))
-        return answer
+        return {"session": SESSION.session, "python": sys.version,
+                "blender": bpy.app.version_string, "engines": ENGINES,
+                "unavailableEngines": UNAVAILABLE_ENGINES}
     raise ValueError("Unknown session op %r" % (op,))
 
 
@@ -5931,6 +5958,7 @@ def _enable_addons():
     import addon_utils
     sys.path.insert(0, _ADDONS)
     for name in sorted(os.listdir(_ADDONS)):
+        _say("@@VOLTER-PHASE addon/%s" % name)
         failed = []
         addon_utils.enable(name, default_set=True, persistent=True, handle_error=failed.append)
         if failed:
@@ -5942,10 +5970,14 @@ def main():
     global ENGINES, UNAVAILABLE_ENGINES
     if _blender_web is None:
         raise RuntimeError("The session worker needs Blender with the _blender_web native door")
+    # Each step of the session's start says it began (`@@VOLTER-PHASE`): the page makes each a load boundary, so the
+    # wait for the ready line is timed step by step, Blender's and Python's own start being the wait before the first.
+    _say("@@VOLTER-PHASE session")
     _prepare_directories()
     bpy.app.handlers.load_post.append(_load_post)
     bpy.app.handlers.undo_post.append(_history_post)
     bpy.app.handlers.redo_post.append(_history_post)
+    _say("@@VOLTER-PHASE engines")
     ENGINES, UNAVAILABLE_ENGINES = _register_engine()
     _enable_addons()
     _say("@@VOLTER-READY " + json.dumps({"blender": bpy.app.version_string, "engines": ENGINES,

package/browser/three/blender-runtime-view.ts

@@ -1185,16 +1185,7 @@ export class BlenderRuntimeView {
   }
 
   stageMode(): string | null {
-    return this.playing ? 'PLAY' : this.mode;
-  }
-
-  /** PLAY IS A MODE OF THE STAGE: while the document plays, the keys are the player's, and the
-   *  mode this context publishes is what the frame's key rules stand down on
-   *  (`volter.stage.mode != 'PLAY'`). Blender's own mode returns on stop. */
-  private playing = false;
-
-  setPlaying(playing: boolean): void {
-    this.playing = playing;
+    return this.mode;
   }
 
   /**
@@ -2594,13 +2585,6 @@ export class BlenderRuntimeView {
     return this.frame;
   }
 
-  /** The frame this view holds with no objects in it: its World, render and view settings. */
-  private worldFrame(): Frame {
-    const source = this.frame;
-    if (!source) throw new Error('Blender capture requires a presented frame');
-    return structuredClone({ ...source, objects: [], meshes: {}, materials: {}, instances: [], lights: {}, volumes: {}, images: {}, armatures: {}, weights: null });
-  }
-
   /** Everything this view holds, as ONE self-contained frame another view can be built from:
    *  every mesh's resident geometry and every resident image, with no reference to what a
    *  receiver already holds. */
@@ -2717,26 +2701,6 @@ export class BlenderRuntimeView {
     };
   }
 
-  /**
-   * THE WORLD OF THE MODEL, FOR PLAY: a view of the World and the scene's settings this view holds now, with none of
-   * the model's objects (a game over the standard artifact brings its own, RFC 0007), handed nothing afterwards.
-   * Blender's data and this view never see it, and disposing it is the whole undo.
-   */
-  detach(): { readonly view: BlenderRuntimeView; dispose(): void } {
-    const detached = new BlenderRuntimeView();
-    if (this.frame) detached.applyFrame(this.worldFrame());
-    let disposed = false;
-    return {
-      view: detached,
-      dispose: () => {
-        if (disposed) return;
-        disposed = true;
-        detached.dispose();
-        detached.root.removeFromParent();
-      },
-    };
-  }
-
   /**
    * A revision-owned render presenter, never a clone of the mounted scene.
    * Copy the resident draw arrays and image bytes synchronously, then rebuild

package/browser/worker.ts

@@ -57,9 +57,9 @@ 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. */
@@ -256,32 +256,64 @@ async function saveDocument(): Promise<boolean> {
 }
 
 /**
- * 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.
+ * 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 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);
+async function openDocument(document: string, backup?: Uint8Array): Promise<unknown> {
+  if (!engine || !projectRoot) throw new Error('The Blender session has not started');
   try {
-    await engine.files.unlink(path);
-  } catch {
-    /* the open already removed it */
+    await stageDocument(engine, projectRoot, document, backup);
+  } catch (error) {
+    return { notOpened: describeThrown(error) };
   }
-  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`);
+  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) });
   }
-  await engine.request({ op: 'reopen-document' });
-  setDocumentDirty(backup !== undefined);
 }
 
-async function startBlender(project: string, document?: string): Promise<unknown> {
+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 };
@@ -372,22 +404,8 @@ async function startBlender(project: string, document?: string): Promise<unknown
   holder.engine = started;
   await loadCheckpoint?.("engine-ready");
   engine = started;
-  // 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.
-    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 = {
     sceneInfo: async () => JSON.stringify(await started.request({ op: 'scene-info' }), null, 2),
     objectInfo: async (name: string) =>
@@ -428,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(
@@ -449,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
@@ -663,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');
@@ -691,20 +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 };
-      return { saved: await saveDocument() };
+      {
+        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 'revert-document':
-      await reopenDocument();
-      return undefined;
-    case 'restore-document':
-      await reopenDocument(request.bytes);
-      return undefined;
+    case 'open-document':
+      return pullWork('open-document', () => openDocument(request.document, request.bytes));
     case 'history-begin':
     case 'history-end':
       return ask({ op: request.op });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.149",
+  "version": "0.1.150",
   "publishConfig": {
     "access": "public"
   },