@volter/blender-engine 0.1.148 → 0.1.150

package/browser/runtime.ts

@@ -1,13 +1,16 @@
 import type { PullResult } from './pull-job.mts';
+import { describeThrown } from './describe-thrown.mts';
 import { FrameStreamReader } from './frame-stream.mts';
+import { HEAP_GROWTH_REFUSED } from './protocol';
 /**
- * The tab-side handle on a Blender session: spawns the worker, forwards the
- * four tool calls, and hands every presented frame to whoever displays it.
- * One instance per editor tab; the session and its model die with the worker.
+ * 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 documents it opens one after another share
+ * its Blender, and the session and its model die with the worker.
  */
 import type {
   CaptureRequest,
-  FileEntry,
+  DocumentOpened,
   RuntimeStart,
   WorkerReply,
   WorkerRequest,
@@ -15,9 +18,16 @@ import type {
   NativePreviewRequest,
   NativePreviewResult,
   FileListSnapshot,
+  GltfExportAnswer,
+  GltfExportKind,
+  GltfExportPrevious,
+  ScriptRunAnswer,
+  BlenderAssetLibrary,
 } from './protocol';
 import type {
   BlenderActionClip,
+  BlenderSceneMovie,
+  BlenderSoundScene,
   BlenderNodeTree,
   BlenderOutlinerTree,
   BlenderOutlinerWrite,
@@ -30,6 +40,26 @@ import type {
 type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
 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;
+
+/** A save that landed: the document it wrote, and what its script did on the scene it wrote (null where none ran). */
+export interface SavedDocument {
+  readonly document: string;
+  readonly script: ScriptRunAnswer | null;
+}
+
 export interface BlenderRuntimeOptions {
   /** Stage one verified mesh/image without replacing the displayed frame. */
   stage?(part: { session: string; revision: number; evaluation?: 'render'; abort?: boolean; mesh?: string; image?: string; piece?: unknown }): Promise<void> | void;
@@ -56,17 +86,14 @@ export interface BlenderRuntimeOptions {
    *  names the new file and before the call that moved it answers. An observer: a throw here
    *  changes nothing. */
   documentMoved?(moved: { readonly from: string; readonly document: string }): void;
+  /** The worker's save refusal or its recovery, for the named project document. */
+  documentSaving?(state: { readonly document: string; readonly note: string | null }): void;
+  /** The document changed (`true`, at every change) or became its file again (`false`). An
+   *  observer: a throw here changes nothing. */
+  documentDirty?(dirty: boolean): void;
 }
 
-/**
- * What the tab answers a present with.
- *
- * `held` is WHAT THE PRESENTER HELD BEFORE THIS FRAME — the presenter's own
- * report of its state, which the session compares against its record of what
- * it sent (`session.py::_present`). `null` says it held nothing; an ABSENT
- * field says this presenter does not report one (an older editor integration), and
- * the session then judges nothing rather than resetting on every frame.
- */
+/** The presenter’s state before this frame. held is null when it holds no frame; the session compares a reported state with what it sent. */
 export interface PresentAnswer {
   capture?: unknown;
   held?: { session: string; revision: number } | null;
@@ -94,24 +121,7 @@ export interface ScreenshotView {
   target?: number[];
 }
 
-/**
- * HOW LONG THE WORKER TOOK, measured by the PAGE.
- *
- * WHY THE PAGE MEASURES (2026-09-16): a single `blender-execute` held the
- * worker for over 1,800s and wedged the tab, and the only report anyone got
- * was a replay harness timing out. A blocked worker cannot report on itself —
- * the loop that would send the number is the loop that is stuck — so the one
- * vantage point that still works is the side that POSTED the message. Every
- * call goes through {@link BlenderRuntime.metrics}'s meter, which stamps the
- * `postMessage` and the reply.
- *
- * MEASUREMENT ONLY. Nothing here cancels, kills or budgets a call: a budget is
- * a policy decision, and this is the number a policy would have to be made
- * from.
- *
- * Times are milliseconds on `performance.now()`. Counters are monotonic since
- * this runtime was constructed (one per page load).
- */
+/** Measure worker calls from the page between postMessage and reply, so a blocked worker remains observable. Metrics use performance.now milliseconds and monotonic counters for this runtime; they impose no call budget. */
 export interface BlenderCallMetrics {
   /** Age of the OLDEST outstanding call, or null when the worker is idle.
    *  This is the field that has a number during the wedge — the counters
@@ -124,10 +134,10 @@ export interface BlenderCallMetrics {
    *  exactly as long as it keeps running. */
   readonly maxCallMs: number | null;
   /** Operation and load boundary owning the longest request; no payload data. */
-  readonly maxCallLabel?: string | null;
+  readonly maxCallLabel: string | null;
   /** Current cooperative phase and count of settled wire requests; sampled, not pushed per unit. */
-  readonly currentPhase?: string | null;
-  readonly completedCalls?: number;
+  readonly currentPhase: string | null;
+  readonly completedCalls: number;
   /** Calls whose duration passed 5s, counting outstanding ones already past it. */
   readonly callsOver5s: number;
   /** The same at 30s — a call this side of it is slow, past it is a wedge. */
@@ -153,12 +163,22 @@ export interface BlenderCallMetrics {
  *  `blender_web_headless.cmake`). JavaScript cannot read a memory's maximum back. */
 const ENGINE_MEMORY_CEILING_MB = 4096;
 
+/**
+ * Requests in OVERTAKES may overtake queued OVERTAKEN document reads. Export and read-file
+ * operations keep their order relative to edits; skin, movie, Properties, Outliner, node and UV
+ * inspections can yield their queue position.
+ */
+const OVERTAKES: ReadonlySet<string> = new Set(['gltf-export', 'read-file']);
+const OVERTAKEN: ReadonlySet<string> = new Set(['action-clip', 'scene-movie', 'rna', 'rna-context', 'outliner', 'node-tree', 'uv-layout']);
+
 export class BlenderRuntime {
   readonly #worker: Worker;
   readonly #options: BlenderRuntimeOptions;
   /** Blender's own last output lines, which are what says why it died when it dies: they reach
    *  the page as ordinary output, so the failure below carries them. */
   readonly #lastLines: string[] = [];
+  /** The line a thread printed when the browser refused to grow the heap, kept for the failure it causes. */
+  #growthRefused: string | null = null;
   readonly #pending = new Map<
     number,
     { resolve: (value: unknown) => void; reject: (error: Error) => void }
@@ -166,10 +186,15 @@ export class BlenderRuntime {
   #nextId = 0;
   #started: Promise<RuntimeStart> | null = null;
   #stopping: Promise<void> | null = null;
+  /** 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 = '';
   };
@@ -198,33 +223,28 @@ export class BlenderRuntime {
     globalThis.addEventListener?.('beforeunload', this.#beforeUnload);
     this.#worker.onmessage = (event: MessageEvent<WorkerReply>) => void this.#receive(event.data);
     this.#worker.onerror = (event) => {
-      // A module worker that fails to LOAD reports an ErrorEvent with an empty
-      // message, so `${event.message}` alone said "undefined" and named
-      // nothing. Every field the event carries goes in: the thrown error's own
-      // message and stack when there is one, and the file and line otherwise,
-      // which is what a failed nested import leaves behind.
+      // Worker errors include the thrown stack or message and the source location.
+      // Failed module imports may provide only the file and line.
       const thrown = event.error as Error | undefined;
       const where = event.filename ? ` at ${event.filename}:${event.lineno}:${event.colno}` : '';
       const said = thrown?.stack ?? thrown?.message ?? event.message;
-      // AND BLENDER'S OWN LAST WORDS: a thread that dies throws whatever it threw, often not an
-      // Error ("Uncaught [object Object]"), while the reason (an allocation that failed, the file
-      // it was reading) is the last thing Blender printed.
+      // Include Blender's retained output alongside the worker error.
       const last = this.#lastLines.length > 0 ? `\nBlender's last output:\n${this.#lastLines.join('\n')}` : '';
       // OUT OF MEMORY IS SAID AS SUCH, from the heap the worker reported as the thread died.
       const heapMB = this.#wasmBytes === null ? null : Math.round(this.#wasmBytes / 1048576);
-      const exhausted =
-        heapMB !== null && heapMB >= ENGINE_MEMORY_CEILING_MB - 16
+      const refused = this.#growthRefused;
+      const exhausted = refused !== null
+        ? `Blender ran out of memory: the browser would not give its heap more (${refused.slice(HEAP_GROWTH_REFUSED.length + 2)}), ` +
+          "below the in-tab engine's ceiling, which happens when the machine itself is short of memory. " +
+          'Free memory (other editors, tabs, builds) and run the call again. '
+        : heapMB !== null && heapMB >= ENGINE_MEMORY_CEILING_MB - 16
           ? `Blender ran out of memory: its heap reached ${heapMB} MB of the in-tab engine's ` +
             `${ENGINE_MEMORY_CEILING_MB} MB, and this scene needs more. `
           : '';
       const error = new Error(
         `${exhausted}Blender worker failed: ${said || 'the worker script did not load'}${where}${last}`,
       );
-      // The page console is the editor's ledger (`installEditorConsoleReporting`
-      // captures it, source-blind), and this package may import nothing of the
-      // editor to say it any other way. Without this line the failure reached
-      // a toast and `cyclotron console` read 0/0 while no Model document could open
-      // (measured 2026-09-20 from a registry install).
+      // Report initialization failures to the page console, which the editor captures into its session ledger.
       console.error(error.message);
       for (const id of [...this.#pending.keys()]) this.#settled(id);
       for (const pending of this.#pending.values()) pending.reject(error);
@@ -241,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;
   }
@@ -254,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;
     });
@@ -436,6 +442,39 @@ export class BlenderRuntime {
   }
 
 
+  /** Sampled scene animation for Timeline preview and export (`BlenderSceneMovie`). */
+  async sceneMovie(): Promise<BlenderSceneMovie> {
+    await this.#ready();
+    return (await this.#request({ op: 'scene-movie' })) as BlenderSceneMovie;
+  }
+
+  /** THE SCENE'S SOUND for frames `first` to `last` (`./rna.ts`, `BlenderSoundScene`), for the page to mix. */
+  async soundScene(first: number, last: number): Promise<BlenderSoundScene> {
+    await this.#ready();
+    return (await this.#request({ op: 'sound-scene', first, last })) as BlenderSoundScene;
+  }
+
+
+  /**
+   * Export the document as a component or level through Blender’s glTF exporter into the module
+   * filesystem. The answer names the files for the caller to carry into the project; the call holds
+   * the session until completion.
+   */
+  async gltfExport(options: { readonly kind: GltfExportKind; readonly force?: boolean; readonly previous?: GltfExportPrevious; readonly blendSha256?: string; readonly luts?: Readonly<Record<string, string>> }): Promise<GltfExportAnswer> {
+    await this.#ready();
+    return (await this.#request({ op: 'gltf-export', kind: options.kind,
+      ...(options.force ? { force: true } : {}), ...(options.previous ? { previous: options.previous } : {}),
+      ...(options.blendSha256 ? { blendSha256: options.blendSha256 } : {}), ...(options.luts ? { luts: options.luts } : {}) })) as GltfExportAnswer;
+  }
+
+
+
+  /** An asset library in Blender's preferences, set again under its name (Preferences > File Paths). */
+  async setAssetLibrary(library: BlenderAssetLibrary): Promise<void> {
+    await this.#ready();
+    await this.#request({ op: 'asset-library', library });
+  }
+
   /** Write ONE restriction column (the eye, the render camera, a collection's
    *  Exclude). A column Blender draws on no row of that type is refused by
    *  name rather than written somewhere near it. */
@@ -449,16 +488,7 @@ export class BlenderRuntime {
     })) as BlenderOutlinerWrite;
   }
 
-  /**
-   * PRESENT WHAT THE ENGINE HOLDS, with no capture.
-   *
-   * Every mutation presents (`session.py::dispatch`), so in the ordinary
-   * course of a session nothing needs to ask. The exception is the first
-   * frame: opening a `.blend` is not a mutation, so a freshly opened Model
-   * document had nothing to display until something RAN — measured by I1 and
-   * fixed here (WORK.md §Blender in the tab is Blender, "Inspection parity",
-   * I2 decision 6). The document asks on mount.
-   */
+  /** Present the engine’s current state without capture. Documents ask on mount so an opened .blend draws before its first mutation. */
   async present(): Promise<void> {
     await this.#ready();
     await this.#request({ op: 'present' });
@@ -472,6 +502,80 @@ export class BlenderRuntime {
       | { error: string };
   }
 
+  /** Whether the document holds changes its project file does not. */
+  get dirty(): boolean {
+    return this.#dirty;
+  }
+
+  /** 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. 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));
+  }
+
+  /** The document's bytes as a save would write them, carried nowhere. */
+  async snapshotDocument(): Promise<Uint8Array> {
+    await this.#ready();
+    return (await this.#request({ op: 'snapshot-document' })) as Uint8Array;
+  }
+
+  /**
+   * 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));
+  }
+
+  /**
+   * 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> {
     await this.#ready();
     return (await this.#request({ op: 'read-file', path })) as Uint8Array;
@@ -482,11 +586,6 @@ export class BlenderRuntime {
     await this.#request({ op: 'write-file', path, bytes });
   }
 
-  async listFiles(path: string): Promise<FileEntry[]> {
-    await this.#ready();
-    return (await this.#request({ op: 'list-files', path })) as FileEntry[];
-  }
-
   /** Files and their native document identity, without executing Python or
    * exporting/saving the model. The worker serializes this with authoring. */
   async listFilesSnapshot(path: string): Promise<FileListSnapshot> {
@@ -501,15 +600,23 @@ export class BlenderRuntime {
   }
 
   /** Drain accepted calls and persist the document before destroying its only
-   * copy. A failed save keeps the worker alive so the caller can retry. */
-  stop(): Promise<void> {
+   * copy. A failed save keeps the worker alive so the caller can retry. With `retire`, the stop's save is the caller's
+   * too: it runs `retire.after`'s script in its turn, as every save does (`saveDocument`), and `landed` hears it. */
+  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.
       const started = this.#started ? await this.#started.then(() => true, () => false) : false;
-      if (started) await this.#request({ op: 'flush-document' }, true);
+      // (one save, queued behind every request accepted before the stop; none is taken after it)
+      const saved = started ? await this.#inTurn('flush-document', true, () => this.#save(retire?.after)) : null;
+      if (saved !== null) retire?.landed(saved);
       this.terminate();
     })().catch(error => {
       this.#stopping = null;
@@ -518,6 +625,23 @@ export class BlenderRuntime {
     return this.#stopping;
   }
 
+  /** The save, and its script on the scene it wrote, inside one turn. */
+  async #save(after: SaveScript | undefined): Promise<SavedDocument | 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[] };
+    try {
+      script = await named;
+    } catch (error) {
+      return { document, script: { output: '', error: `the save's script could not be read: ${describeThrown(error)}`, files: [], unstaged: [] } };
+    }
+    const dir = `/tmp/volter-script-run/${++this.#scriptRuns}`;
+    return { document, script: (await this.#wire({ op: 'run-script', source: script.source, args: script.args, dir })) as ScriptRunAnswer };
+  }
+
   /** Forced teardown for a lost session; explicit user stops must use stop(). */
   terminate(): void {
     this.#discardStagedFrame();
@@ -546,7 +670,8 @@ export class BlenderRuntime {
    * displaying the frame is main-thread time, which is the long-task observer's
    * subject (the host's `worker-call-metrics.ts`).
    */
-  metrics(now: number = performance.now()): BlenderCallMetrics {
+  metrics(): BlenderCallMetrics {
+    const now = performance.now();
     let oldest: number | null = null;
     let max = this.#maxCompletedMs;
     let maxLabel = this.#maxCompletedLabel;
@@ -594,33 +719,64 @@ export class BlenderRuntime {
 
   #completedCalls = 0;
   #acceptedRequests = 0;
-  #requestTail: Promise<void> = Promise.resolve();
-  #request(request: Request, shutdown = false): Promise<unknown> {
+  /**
+   * Process requests in queue order. gltf-export and read-file may overtake queued document reads
+   * in OVERTAKEN, while preserving the order of edits and other operations.
+   */
+  #waiting: { readonly op: string; readonly start: () => void }[] = [];
+  #busy = false;
+  #enqueue(op: string, start: () => void): void {
+    const item = { op, start };
+    if (OVERTAKES.has(op)) {
+      let at = this.#waiting.length;
+      while (at > 0 && OVERTAKEN.has(this.#waiting[at - 1]!.op)) at--;
+      this.#waiting.splice(at, 0, item);
+    } else this.#waiting.push(item);
+    if (!this.#busy) this.#next();
+  }
+  #next(): void {
+    const item = this.#waiting.shift();
+    this.#busy = item !== undefined;
+    item?.start();
+  }
+  #request(request: Request): Promise<unknown> {
+    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>, 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++;
-    const answer = this.#requestTail.then(async () => {
-      const finishWork = this.#work(`running worker ${request.op}`);
+    const turn = new Promise<void>((start) => this.#enqueue(op, start));
+    const answer = turn.then(async () => {
+      const finishWork = this.#work(`running worker ${op}`);
       endWork = () => { if (this.#operationWork.delete(endWork)) finishWork(); };
       this.#operationWork.add(endWork);
-      this.#loadBoundary = request.op;
-      let result = await this.#wireRequest(request) as PullResult<unknown>;
-      while (result?.load === 'continue') {
-        this.#loadBoundary = result.phase;
-        result = await this.#wireRequest({ op: 'load-next', token: result.token }) as PullResult<unknown>;
-      }
-      return result?.load === 'done' ? result.value : result;
+      return run();
     }).finally(() => {
       this.#acceptedRequests--;
       endWork();
       const totalMs = Math.round(performance.now() - began);
-      try { if (totalMs >= 1000) this.#options.log?.('log', `@@VOLTER-WORK op=${request.op} totalMs=${totalMs}`); } catch { /* diagnostics cannot poison the queue */ }
+      try { if (totalMs >= 1000) this.#options.log?.('log', `@@VOLTER-WORK op=${op} totalMs=${totalMs}`); } catch { /* diagnostics cannot poison the queue */ }
+      this.#next();
     });
-    this.#requestTail = answer.then(() => {}, () => {});
     return answer;
   }
+  /** One request to the worker, a load's continuations included. */
+  async #wire(request: Request): Promise<unknown> {
+    this.#loadBoundary = request.op;
+    let result = await this.#wireRequest(request) as PullResult<unknown>;
+    while (result?.load === 'continue') {
+      this.#loadBoundary = result.phase;
+      result = await this.#wireRequest({ op: 'load-next', token: result.token }) as PullResult<unknown>;
+    }
+    return result?.load === 'done' ? result.value : result;
+  }
 
   #wireRequest(request: Request): Promise<unknown> {
     if (this.#terminated) return Promise.reject(new Error('The Blender session is terminated'));
@@ -683,6 +839,13 @@ export class BlenderRuntime {
       }
       if (reply.op === 'document-dirty') {
         this.#dirty = reply.dirty;
+        try { this.#options.documentDirty?.(reply.dirty); }
+        catch { /* an observer cannot change whether the document changed */ }
+        return;
+      }
+      if (reply.op === 'document-saving') {
+        try { this.#options.documentSaving?.({ document: reply.document, note: reply.note }); }
+        catch { /* an observer cannot change whether the document was saved */ }
         return;
       }
       if (reply.op === 'document-moved') {
@@ -698,6 +861,8 @@ export class BlenderRuntime {
         return;
       }
       if (reply.op === 'log') {
+        // (a heap the browser refused to grow is kept past the aborts it causes, which push it out of the last lines)
+        if (reply.text.startsWith(HEAP_GROWTH_REFUSED)) this.#growthRefused ??= reply.text;
         this.#lastLines.push(reply.text);
         if (this.#lastLines.length > 12) this.#lastLines.shift();
         this.#options.log?.(reply.level, reply.text);
@@ -721,8 +886,8 @@ export class BlenderRuntime {
         this.#worker.postMessage({
           op: 'present-result',
           id: reply.id,
-          ...(answer?.capture === undefined ? {} : { capture: answer.capture }),
-          ...(answer !== null && answer !== undefined && 'held' in answer
+          ...(answer.capture === undefined ? {} : { capture: answer.capture }),
+          ...('held' in answer
             ? { held: answer.held }
             : {}),
         } satisfies WorkerRequest);

package/browser/session-addons.mts

@@ -0,0 +1,33 @@
+/**
+ * THE ADD-ONS THIS BLENDER SHIPS beside Blender's own, as the files each engine writes into the session's root before
+ * Blender starts (`<SESSION_ROOT>/addons/<package>/…`), where `session.py`'s `_enable_addons` enables every package it
+ * finds there for the whole session.
+ *
+ * - `addons/vrm`: saturday06's VRM Add-on for Blender ("VRM format"), the release `addons/vrm.json` names, as it was
+ *   published. Blender reads its Python and its manifest (`common/version.py` reads `blender_manifest.toml` at import)
+ *   and its MToon node-group libraries (`common/*.blend`); its documentation and licence texts stay in the package.
+ *
+ * Text crosses as the module's own source; a `.blend` is bytes, fetched from the URL the bundle gives it.
+ */
+import { SESSION_ROOT } from './blender-engine.mts';
+
+const texts = import.meta.glob<string>(['./addons/vrm/**/*.py', './addons/vrm/blender_manifest.toml'], {
+  query: '?raw',
+  import: 'default',
+  eager: true,
+});
+const libraries = import.meta.glob<string>('./addons/vrm/**/*.blend', { query: '?url', import: 'default', eager: true });
+
+/** Every add-on file, at its path in the module filesystem. */
+export async function sessionAddonFiles(): Promise<readonly { readonly path: string; readonly bytes: Uint8Array }[]> {
+  const at = (key: string): string => `${SESSION_ROOT}/${key.slice('./'.length)}`;
+  const utf8 = new TextEncoder();
+  return [
+    ...Object.entries(texts).map(([key, text]) => ({ path: at(key), bytes: utf8.encode(text) })),
+    ...(await Promise.all(Object.entries(libraries).map(async ([key, url]) => {
+      const answer = await fetch(url);
+      if (!answer.ok) throw new Error(`The add-on file ${key.slice('./'.length)} could not be read: ${url} answered HTTP ${answer.status}`);
+      return { path: at(key), bytes: new Uint8Array(await answer.arrayBuffer()) };
+    }))),
+  ];
+}

package/browser/session-frame.mts

@@ -54,8 +54,9 @@ type Typed =
   | Int16Array
   | Uint16Array;
 
-/** The door's own dtype vocabulary -- the C type each column was written from,
- *  not numpy's codes: the Python exporter that spoke numpy is gone. */
+/**
+ * Column dtype vocabulary matching the C types written by the export door.
+ */
 const READERS: Record<string, (bytes: Uint8Array) => Typed> = {
   f32: (b) => new Float32Array(b.buffer, b.byteOffset, b.byteLength >> 2),
   f64: (b) => new Float64Array(b.buffer, b.byteOffset, b.byteLength >> 3),
@@ -113,34 +114,14 @@ export function columnsToTypedArrays(arena: Uint8Array, frame: unknown): unknown
 
 /** A column as the RECORD of it: what it was, how many bytes, and their digest.
  *  Never the bytes — see `describeFrame`. */
-export interface ColumnDigest {
+interface ColumnDigest {
   dtype: string;
   length: number;
   /** Lowercase hex SHA-256 of exactly the `length` bytes the descriptor names. */
   sha256: string;
 }
 
-/**
- * THE FRAME THIS PRESENT SUBMITTED, as a record that can sit in a JSON file.
- *
- * The presenter is asked, later, whether what it DISPLAYS is what the session
- * SENT (`replay_draw_compare.compare_draws`), and that comparison had no second
- * side: the live document keeps the frame's identity and object table but drops
- * every geometry payload the moment it has built the `BufferGeometry` (850 MB of
- * main-thread heap otherwise — `blender-runtime-view.ts`), and nothing else
- * remembered the frame at all.
- *
- * So the worker records it here, while the arena is still the frame's own: every
- * `{offset, length, dtype, count, stride}` becomes `{dtype, length, sha256}` and
- * everything else — objects, materials, cameras, the world, the counts — is
- * copied as it stands. THE COLUMN BYTES NEVER LEAVE THE TAB; a record of the
- * numbers is not the numbers, and a battery run must not write a scene's meshes
- * to disk a second time.
- *
- * This runs BEFORE `presentToTab` posts, for two reasons that are both fatal
- * otherwise: the buffers are TRANSFERRED (detached the instant they are posted),
- * and the arena is overwritten by the next `export_frame`.
- */
+/** Record the submitted frame’s metadata and hash each arena column before presentToTab transfers its buffers. Geometry bytes stay in the tab; the record identifies the data that was submitted. */
 export async function describeFrame(arena: Uint8Array, frame: unknown): Promise<unknown> {
   const walk = async (value: unknown, key: string): Promise<unknown> => {
     if (isColumnDescriptor(value)) {