@volter/blender-engine 0.1.147 → 0.1.149

package/browser/addons/vrm.json

@@ -0,0 +1,18 @@
+{
+  "name": "VRM Add-on for Blender",
+  "addon": "VRM format",
+  "version": "4.10.3",
+  "repository": "https://github.com/saturday06/VRM-Addon-for-Blender",
+  "release": "v4.10.3",
+  "commit": "8c0fd6aaef3925b125cf35208cee2458e257164c",
+  "archive": {
+    "name": "VRM_Addon_for_Blender-4_10_3.zip",
+    "url": "https://github.com/saturday06/VRM-Addon-for-Blender/releases/download/v4.10.3/VRM_Addon_for_Blender-4_10_3.zip",
+    "sha256": "dcf6d55f3d28de8c0de2f72abcc7fe06b2b300195e6b4da2e9cf476fd59165a2",
+    "root": "VRM_Addon_for_Blender-release"
+  },
+  "blender": { "min": "4.2.0", "maxExclusive": "5.3.0" },
+  "license": "MIT OR GPL-3.0-or-later",
+  "conveyedUnder": "GPL-3.0-or-later",
+  "copyright": ["2018 iCyP", "2022 saturday06", "2020 Isamu Mogi"]
+}

package/browser/blender-emscripten-engine.mts

@@ -1,33 +1,7 @@
-/**
- * The STANDALONE skew: Blender in this worker's own WebAssembly module.
- *
- * `blender-engine.mts` is the seam and says how the skew is chosen; this is
- * one of its two implementations, and the one `@volter/editor-blender` ships. It has no
- * in-house dependency of any kind and reaches nothing but the editor's own
- * routes.
- *
- * THREE THINGS THE BUILD REQUIRES, each measured rather than assumed:
- *
- * 1. CROSS-ORIGIN ISOLATION. The build is `-sPROXY_TO_PTHREAD` with pthreads,
- *    so it needs `SharedArrayBuffer`. The editor's dev server already sets
- *    `Cross-Origin-Opener-Policy: same-origin` and
- *    `Cross-Origin-Embedder-Policy: credentialless` ahead of every route
- *    (`packages/editor/server/dev.ts`) — `credentialless` rather than
- *    `require-corp` precisely so cross-origin images and iframes keep loading.
- *    A worker without `crossOriginIsolated` is refused BY NAME here rather
- *    than left to fail inside the runtime.
- *
- * 2. THE GLUE IS PATCHED SERVER-SIDE, not here, because the runtime spawns its
- *    pthreads by loading that same URL as a classic worker
- *    (`Module.mainScriptUrlOrBlob`). See `blender-wasm-artifact.ts`.
- *
- * 3. FILES ARE STAGED WITH `FS_createDataFile`, before the runtime starts.
- *    This is a WasmFS build: `Module.FS` exists and works from this thread,
- *    but its preload directories come out non-writable, which is why
- *    `session.py` chmods its own root as its first act.
- */
+
 
 import { checkpointStream } from './pull-job.mts';
+import { watchHeapGrowthSource } from './heap-growth.mts';
 import { writeStreamedFile, type StreamFileSystem } from './stream-file.mts';
 import {
   artifactUrl,
@@ -44,6 +18,9 @@ import {
   sleep,
 } from './blender-engine.mts';
 import sessionPython from './session.py?raw';
+// Imported by session.py’s gltf-export operation from the same directory.
+import gltfExportPython from './gltf_export.py?raw';
+import { sessionAddonFiles } from './session-addons.mts';
 
 /** What the module factory is, in the only shape this file uses. */
 interface BlenderModule {
@@ -59,13 +36,8 @@ interface BlenderModule {
   ENV: Record<string, string>;
   /** The export door's arena, read by `readArena`. */
   HEAPU8: Uint8Array;
-  /**
-   * Hand back the packed `.data` payload, once. Linked in by the bundle's
-   * `--post-js` (the spike's `recipe/release-preloaded-file-data.js`, whose
-   * header carries the measurement); absent means the module predates it,
-   * which is why the call below is guarded and says so.
-   */
-  releasePreloadedFileData?(): { files: number; bytes: number };
+  /** Release the packed preload payload after WasmFS has copied its files into linear memory. */
+  releasePreloadedFileData(): { files: number; bytes: number };
   _blender_web_export_buffer(): number;
   _blender_web_export_buffer_size(): number;
   FS_createPath(parent: string, name: string, canRead: boolean, canWrite: boolean): void;
@@ -100,6 +72,19 @@ async function loadFactory(glueUrl: string): Promise<BlenderModuleFactory> {
   return factory;
 }
 
+/** Report uncaught pthread stacks through Module.printErr before the error crosses to the parent worker. Wasm function indices can be resolved with a symbol map from the same build. */
+function pthreadEntry(glueUrl: string): string {
+  const source = `${watchHeapGrowthSource("(line) => postMessage({ cmd: 9, handler: 'printErr', args: [line] })")}
+self.addEventListener('error', (event) => {
+  const error = event.error;
+  const stack = error && error.stack ? String(error.stack) : String(event.message) + ' at ' + event.filename + ':' + event.lineno + ':' + event.colno;
+  try { postMessage({ cmd: 9, handler: 'printErr', args: ['Blender thread crashed: ' + stack] }); } catch (_) {}
+});
+importScripts(${JSON.stringify(new URL(glueUrl, self.location.href).href)});
+`;
+  return URL.createObjectURL(new Blob([source], { type: 'text/javascript' }));
+}
+
 const utf8 = new TextEncoder();
 
 function mkdirp(module: BlenderModule, directory: string): void {
@@ -117,7 +102,11 @@ function moduleFiles(module: BlenderModule): BlenderFiles {
   return {
     readFile: async (path) => FS.readFile(path),
     // Not `async`: a write that throws throws here, so `request` never starts `.done` after a failed `.json`.
-    writeFile: (path, data) => { FS.writeFile(path, data); return Promise.resolve(); },
+    writeFile: (path, data) => {
+      try { FS.unlink(path); } catch { /* nothing there to replace */ }
+      FS.writeFile(path, data);
+      return Promise.resolve();
+    },
     writeFileStream: (path, body, size) => writeStreamedFile(FS, path, body, size),
     mkdirTree: async (path) => FS.mkdirTree(path),
     readdir: async (path) => FS.readdir(path),
@@ -139,28 +128,7 @@ function moduleFiles(module: BlenderModule): BlenderFiles {
   };
 }
 
-/**
- * BLENDER'S ARTIFACTS ARE FETCHED ONCE PER BUILD -- WHERE THE SERVER RUNS IN THE TAB. The wasm
- * (86 MB decoded), the `.data` package (53 MB) and the Essentials payload are immutable for a
- * build, and a page whose editor server runs in its own tab (browser-substrate; the door says so
- * as `status.inTab`) keeps them in Cache Storage under the digest the door reports, so a later
- * open reads them at the browser's own speed instead of from that server. Measured there: the
- * three took 7.2 s per open (4.2 s for the wasm alone), about half of it decoding their brotli
- * in the tab. A file the door gives no digest for is fetched as it always was.
- *
- * NOT WHERE THE SERVER IS A PROCESS ON THIS MACHINE. There the door answers from local disk over
- * loopback with `no-cache` and an ETag, brotli as stored to a client that accepts it
- * (`editor-blender/serving/blender-routes.ts`), so the browser's HTTP cache keeps the bytes as
- * sent (~38 MB) and a repeat open is a 304 and the browser's own decode. Cache Storage there
- * held a second, decoded copy (~144 MiB) per origin, and an editor origin is per project folder
- * (`editor-<id>.localhost:<port>`, before 0.5.190 `127.0.0.1:<port>`): measured 2026-10-07 in
- * one Chrome profile, 113 origins held ~16.3 GB. The HTTP cache is size-bounded and evicted by the browser; Cache Storage is
- * kept until the origin deletes it. So such a page fetches through the HTTP cache and releases
- * any copy an earlier build left in its origin ({@link releaseArtifactCache}).
- *
- * The cache was never made persistent (nothing here calls `navigator.storage.persist`), so it is
- * best-effort storage Chrome may evict under storage pressure; it stays that way.
- */
+/** Cache immutable artifacts by digest when the server runs in the tab. Process-backed sessions use the browser HTTP cache and release this origin’s artifact-cache copies. Cache Storage remains best-effort storage. */
 const ARTIFACT_CACHE = 'volter-blender-artifacts';
 
 /**
@@ -179,12 +147,7 @@ function releaseArtifactCache(note: (text: string) => void): void {
   );
 }
 
-/**
- * THE CACHE SPEEDS AN OPEN UP; IT NEVER DECIDES WHETHER BLENDER OPENS. A Cache Storage that cannot
- * open or answer (measured 2026-10-07, headless Chrome on Windows: `caches.open` threw "Unexpected
- * internal error", and the model failed to open on it) means the artifact is fetched from the editor
- * as it would be with no digest; bytes that cannot be kept are used anyway. `note` says which, per artifact, as page output (not an unresolved console entry).
- */
+/** Fetch from the editor when Cache Storage cannot answer; report cache failures as page output without preventing Blender from opening. */
 async function cachedArtifact(file: string, digest: string | undefined, checkpoint: () => Promise<void>, note: (text: string) => void): Promise<Response> {
   const bounded = (response: Response): Response => response.ok && response.body
     ? new Response(checkpointStream(response.body, checkpoint), { status: response.status, headers: response.headers })
@@ -223,11 +186,12 @@ export async function startEmscriptenBlenderEngine(
   options: BlenderEngineOptions,
   status: BlenderArtifactStatus,
 ): Promise<BlenderEngine> {
-  if (!self.crossOriginIsolated)
+  if (!self.crossOriginIsolated || typeof SharedArrayBuffer === 'undefined')
     throw new Error(
-      'Headless Blender needs SharedArrayBuffer, so the editor page has to be cross-origin ' +
-        'isolated (Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy on ' +
-        'every response). This worker reports crossOriginIsolated=false.',
+      'Blender needs browser isolation and shared memory that this page does not provide. ' +
+        'Open this address in a current desktop Chrome or Edge. If this message remains there, ' +
+        'the site must serve Cross-Origin-Opener-Policy: same-origin and a ' +
+        'Cross-Origin-Embedder-Policy on every response before Blender can start.',
     );
   const glueUrl = artifactUrl('blender_browser.js');
   // Page output, not an editor-console condition: nothing in the project can resolve the browser's cache.
@@ -241,36 +205,26 @@ export async function startEmscriptenBlenderEngine(
   const artifact = (file: string) => cachedArtifact(file, digests[file], () => checkpoint(`artifact/${file}`), noteCache);
   // The `.data` package is handed to the glue whole (`getPreloadedPackage`),
   // so it is read before the module starts; the wasm streams in beside it.
-  const [factory, preloaded] = await Promise.all([
+  const [factory, preloaded, addonFiles] = await Promise.all([
     loadFactory(glueUrl),
     artifact('blender_browser.data').then(async (response) => {
       const url = artifactUrl('blender_browser.data');
       if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`);
       return startupOperation(url, 'read data package body', () => response.arrayBuffer());
     }),
+    sessionAddonFiles(),
   ]);
   await checkpoint('runtime-package-ready');
   let bootError: unknown = null;
   const started = performance.now();
   let readyLine: string | null = null;
-  // BLENDER'S OWN STREAMS ARE PAGE OUTPUT, NOT EDITOR-CONSOLE CONDITIONS.
-  // Measured on the first live run: routing `printErr` at `error` put every
-  // ordinary startup line -- the WebGPU preinit notice, a Python
-  // DeprecationWarning, the ready banner itself -- into the session's
-  // unresolved console set, which is the set an agent must drive to zero. The
-  // editor's console door is for conditions somebody must resolve, so only the
-  // session's OWN named conditions go there.
+  // 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);
     options.log(sessionLevel(text), text);
   };
-  // THE HEAP ITSELF, not a view of it. Blender runs on a pthread, so when its heap grows there
-  // this worker's `module.HEAPU8` keeps the length it had until the glue next refreshes it -- and
-  // no export the door calls does. MEASURED 2026-09-29 on the Stoneguard scene from
-  // game-benchmarks main: a mesh's columns at 1.14 GB were read through a 433 MB view, and the
-  // pull failed "outside the export arena". The glue builds its memory with `new
-  // WebAssembly.Memory` and exports no handle to it, so that constructor is observed while the
-  // factory runs; every read below takes a fresh view of `memory.buffer`.
+  // 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.
+  new Function('report', watchHeapGrowthSource('report'))((line: string) => say('error', line));
   const Memory = WebAssembly.Memory;
   let memory: WebAssembly.Memory | null = null;
   (WebAssembly as { Memory: unknown }).Memory = function (descriptor: WebAssembly.MemoryDescriptor) {
@@ -294,8 +248,9 @@ export async function startEmscriptenBlenderEngine(
       })().catch((error: unknown) => { bootError = error; });
       return {};
     },
-    // The pthreads load the SAME patched glue this worker just evaluated.
-    mainScriptUrlOrBlob: glueUrl,
+    // The pthreads load the SAME patched glue this worker just evaluated, behind a line that sends
+    // a crashing thread's own stack here (`pthreadEntry`).
+    mainScriptUrlOrBlob: pthreadEntry(glueUrl),
     print: (text: string) => say('log', text),
     printErr: (text: string) => say('error', text),
     preRun: [
@@ -334,6 +289,12 @@ export async function startEmscriptenBlenderEngine(
           true,
           true,
         );
+        mod.FS_createDataFile(SESSION_ROOT, 'gltf_export.py', utf8.encode(gltfExportPython), true, true, true);
+        for (const { path, bytes } of addonFiles) {
+          const at = path.lastIndexOf('/');
+          mkdirp(mod, path.slice(0, at));
+          mod.FS_createDataFile(path.slice(0, at), path.slice(at + 1), bytes, true, true, true);
+        }
       },
     ],
   }).finally(() => {
@@ -349,43 +310,18 @@ export async function startEmscriptenBlenderEngine(
   const bootMs = performance.now() - started;
   const banner = JSON.parse(readyLine) as { blender: string; engines: string[] };
 
-  // THE PAYLOAD EXISTS TWICE UNTIL THIS CALL. `--preload-file` reads the whole
-  // `.data` package into one ArrayBuffer, WasmFS copies every file out of it
-  // into the wasm heap during its own init, and then emscripten keeps the
-  // subarrays forever in `wasmFSPreloadedFiles` -- so a booted session holds
-  // ~55 MB of JS-side bytes that are already in linear memory and will never
-  // be read again. Measured 2026-09-18: Node's `arrayBuffers` sat at 55 MB
-  // from `factory resolved` through every later call, and two forced GCs did
-  // not move it. Here is the one moment it is safe to drop: WasmFS flushed
-  // long before the ready line, and anything staged after this takes
-  // `FS_createDataFile`'s post-flush branch, which never consults the array.
-  let releasedPayloadBytes: number | null = null;
-  if (typeof module.releasePreloadedFileData === 'function') {
-    const released = module.releasePreloadedFileData();
-    releasedPayloadBytes = released.bytes;
-    options.log(
-      'log',
-      `blender: released the preloaded ${(released.bytes / 1048576).toFixed(0)} MB ` +
-        `payload (${released.files} files); WasmFS already holds it`,
-    );
-  } else {
-    options.log(
-      'error',
-      'blender: this bundle has no releasePreloadedFileData, so the ~55 MB packed ' +
-        '.data payload stays resident beside the copy WasmFS made of it — relink with ' +
-        "the recipe's --post-js (recipe/release-preloaded-file-data.js).",
-    );
-  }
+  // WasmFS has copied the preload package before the ready line. Release its redundant JS buffers before staging project files through the post-flush filesystem path.
+  const released = module.releasePreloadedFileData();
+  const releasedPayloadBytes = released.bytes;
+  options.log(
+    'log',
+    `blender: released the preloaded ${(released.bytes / 1048576).toFixed(0)} MB ` +
+      `payload (${released.files} files); WasmFS already holds it`,
+  );
 
   const FS = module.FS;
 
-  // A DIRECTORY MADE BY THE PRELOAD DOOR IS NOT WRITABLE. `FS_createPath`
-  // ignores its `canWrite` argument in this build, so the project root and
-  // everything above it come out read-only and the first `mkdirTree` under
-  // them raises `ErrnoError` -- measured on the first live round trip
-  // (2026-09-17: `stageProjectFiles` threw before any project file was
-  // staged). The session chmods its own root from Python for the same reason;
-  // this is the other half, for the paths Python never touches.
+  // FS_createPath ignores canWrite in this build. Make preloaded ancestors writable before staging project files.
   let climb = '';
   for (const part of `${options.project}`.split('/').filter(Boolean)) {
     climb += `/${part}`;
@@ -413,12 +349,7 @@ export async function startEmscriptenBlenderEngine(
     banner,
     files,
     request,
-    // A VIEW, NOT A COPY. The arena is wasm linear memory and under
-    // `-sPROXY_TO_PTHREAD` that memory is SHARED, so `session-frame.mts`
-    // slices every column it reads out of here; this call itself is free.
-    // A DIRECT ARENA (address 0) IS THE WHOLE HEAP, at its length now: the size the door reports
-    // is `emscripten_get_heap_size()`, which is Blender's pthread's own view of the heap and is as
-    // stale as this worker's was (measured: 431 MB while a column lay at 2.0 GB).
+    // Return a view of shared wasm memory; session-frame.mts copies the transferred columns. A direct arena spans the current memory buffer.
     readArena: async () => {
       const base = module._blender_web_export_buffer();
       return base === 0 ? heap() : heap().subarray(base, base + module._blender_web_export_buffer_size());
@@ -429,9 +360,10 @@ export async function startEmscriptenBlenderEngine(
   };
 }
 
-/** Assets are data, not a second engine. Ship them separately so a data update
- * does not relink the 86 MB Wasm binary. Both payload and per-file bounds are
- * checked before anything enters Blender's filesystem. */
+/**
+ * Load assets separately from the engine so data updates do not require relinking Wasm. Check
+ * payload and per-file bounds before writing Blender’s filesystem.
+ */
 async function mountEssentials(files: BlenderFiles, digest: string | undefined, checkpoint: (phase: string) => Promise<void>, noteCache: (text: string) => void): Promise<void> {
   const indexUrl = artifactUrl('essentials.json');
   const payloadUrl = artifactUrl('essentials.bin');

package/browser/blender-engine.mts

@@ -1,47 +1,4 @@
-/**
- * Headless Blender, running in the editor tab's worker -- THE SEAM, and the
- * choice of which Blender answers it.
- *
- * THE BLENDER IN THE TAB IS BLENDER (ARCHITECTURE-CORE, owner ruling
- * 2026-09-17), and since the 2026-09-18 amendment there are TWO BUILDS of it
- * and neither retires the other:
- *
- *   emscripten -- the STANDALONE skew. Blender in this worker's own module,
- *                 `@volter/editor-blender` with zero in-house dependencies. What the
- *                 package ships under `wasm/`.
- *   wali       -- the SUBSTRATE skew. The same Blender linked for
- *                 `wasm32-wali-linux-musl` and run as an ordinary Linux
- *                 program through `@volter/browser-wali`: argv, stdio, an
- *                 exit code, syscalls, a filesystem.
- *
- * ONE GATE, BOTH SKEWS: the scene battery passes on each at the same counts,
- * from the same `session.py`. A skew may REFUSE a capability by name; it may
- * not answer the same question differently. So this file is where the two
- * meet and everything above it -- `worker.ts`, `session-frame.mts`,
- * `blender-runtime-host.ts`, the presenter, the battery, the document -- is
- * written once.
- *
- * HOW THE SKEW IS CHOSEN: IT IS NOT. It is READ off the artifact this editor
- * serves, through the door that already exists for "is there a Blender here at
- * all" (`/__editor/blender-wasm/status`, `blender-wasm-artifact.ts`). One
- * editor serves one Blender; the served directory holds either a
- * `blender_browser.js` bundle or a `blender.wasm` beside its `runtime/` tree,
- * and that IS the answer. There is no manifest field, no setting and no flag,
- * because nothing a user does should depend on the skew -- if it did, the
- * skews would be answering differently, which the ruling forbids.
- * `VOLTER_BLENDER_WASM_DIR` is the existing door for pointing the editor at a
- * different build and is how the substrate skew is reached in development.
- *
- * WHAT DIFFERS, and it is four things, all below this line:
- *   1. how the module is booted (a `--post-js` glue factory / a WALI program);
- *   2. where the session's `in`/`out`/`ask` files live (`Module.FS` / the
- *      program's filesystem);
- *   3. how the export door's arena is read (`HEAPU8` / the file
- *      `export_frame`'s `buffer_path` names -- see `readArena`);
- *   4. cross-origin isolation, which only the Emscripten build asks of the page.
- * Everything else, including the request/ask protocol below, is one
- * implementation over {@link BlenderFiles}.
- */
+
 
 import { describeThrown } from './describe-thrown.mts';
 
@@ -49,22 +6,16 @@ export const SESSION_ROOT = '/work/.volter-session';
 export const SESSION_SCRIPT = `${SESSION_ROOT}/session.py`;
 
 /**
- * THE TWO CHANNEL DIRECTORIES THIS PAGE OWNS, and the reason they are a
- * constant instead of two literals per engine.
- *
- * ONE WRITER PER DIRECTORY is the channel's ownership rule (see
- * {@link openSessionChannel}), and a directory's owner is also the side that
- * CREATES it: `in/` and `reply/` are made here, before the program starts;
- * `out/` and `ask/` are made by `session.py`, which owns them. An engine that
- * pre-created all four put a guest `mkdir`/`chmod` on a path the page had
- * already touched, which is the same crossing edit at a smaller scale.
+ * The page creates and writes the in/ and reply/ directories before the program starts. session.py
+ * creates and writes out/ and ask/. Keep one writer per directory so snapshot-backed filesystem
+ * patches do not cross another writer’s edits.
  */
 export const PAGE_OWNED_DIRECTORIES = [`${SESSION_ROOT}/in`, `${SESSION_ROOT}/reply`] as const;
 
 /** Which build of Blender this editor serves. */
-export type BlenderSkew = 'emscripten' | 'wali';
+type BlenderSkew = 'emscripten' | 'wali';
 
-export interface BlenderFileStat {
+interface BlenderFileStat {
   size: number;
   /** The raw mode, S_IFDIR and all: `listModuleFiles` reads the type bits. */
   mode: number;
@@ -78,14 +29,11 @@ export interface BlenderFileStat {
  * a `BrowserFileSystem` whose bytes are a promise by contract. The Emscripten
  * side answers from `Module.FS` and resolves immediately.
  *
- * `stat` ANSWERS NULL FOR AN ABSENT PATH rather than throwing. The poll loop
- * asks "is the answer there yet" thousands of times per call, and the version
- * of this that threw sorted a genuine failure from an expected absence by
- * matching `/ENOENT|no such|FS error|errno/i` against the message -- a filter
- * that swallows any real error whose text happens to say "errno".
+ * `stat` returns null for an absent path and propagates other filesystem failures.
  */
 export interface BlenderFiles {
   readFile(path: string): Promise<Uint8Array>;
+  /** Replace the contents at path, including when the file already exists. */
   writeFile(path: string, data: string | Uint8Array): Promise<void>;
   /** Stream a known-size file into the engine without a second whole-file JS buffer.
    * A failed transfer leaves the previous file intact. */
@@ -95,17 +43,7 @@ export interface BlenderFiles {
   /** Null when the path is not there. */
   stat(path: string): Promise<BlenderFileStat | null>;
   unlink(path: string): Promise<void>;
-  /**
-   * Resolves at the next change to this filesystem or after `within` ms,
-   * whichever is first, when the engine can say so. The call loop waits on it
-   * in place of its poll's sleep, so an answer is read when it lands rather
-   * than at the next timer: a browser clamps a chain of `setTimeout(1)` to
-   * 4 ms, which was most of a no-op call's return leg (measured 2026-09-28:
-   * 6-7 ms of 8-10). Each wait is its own and is gone when it resolves; racing
-   * one shared promise against every poll's sleep kept a reaction per poll
-   * until the next change (review of d36c8004: 43 MB in an hour-long call).
-   * Without it the loop sleeps as before.
-   */
+  /** Resolve on the next filesystem change or after within milliseconds. Each wait releases its own subscription when it settles; without this capability, the call loop polls. */
   changed?(within: number): Promise<void>;
 }
 
@@ -128,7 +66,7 @@ export interface BlenderEngineOptions {
  * each of them (`mesh` or `image`, with its `piece`), then the frame again with `present`, which is
  * answered as a whole frame is.
  */
-export interface SessionAsk {
+interface SessionAsk {
   evaluation?: 'render';
   checkpoint?: string;
   frame?: unknown;
@@ -142,9 +80,7 @@ export interface SessionAsk {
 }
 
 export interface BlenderEngine {
-  /** Which build answered. Reported out of `blender-start`, because a number
-   *  that differs between the skews is a defect in one of them and the board
-   *  has to be able to say which one it measured. */
+  /** The engine build identity reported by blender-start. */
   readonly skew: BlenderSkew;
   readonly banner: { blender: string; engines: string[] };
   /** The session's filesystem. */
@@ -193,22 +129,7 @@ export function sessionLevel(line: string): 'log' | 'warn' | 'error' {
   return 'log';
 }
 
-/**
- * An artifact URL, resolved against THE MODULE — never against `self.location`.
- *
- * A worker's `location` is where its SCRIPT was loaded from, and that is not
- * always an http url of this editor: when the page is a frame this editor does
- * not own (the Code-OSS workbench, docs/CODE-OSS.md §Boot, DESKTOP), a
- * cross-origin worker can only be constructed through a same-origin `blob:`
- * doorway, so `self.location.href` reads `blob:vscode-file://vscode-app/<uuid>`
- * — an opaque base against which `new URL('/__editor/...', base)` THROWS
- * `TypeError: Invalid URL`. Measured 2026-09-19: that is what `blender-start`
- * answered on the desktop shape once its message reached the worker at all.
- *
- * `import.meta.url` is this module's own url and is always the http one the
- * editor served, whatever loaded the worker. Every artifact url is built from
- * it, and nothing here reads `self.location`.
- */
+/** Resolve artifacts against import.meta.url. Cross-origin workers may run through a blob URL, which cannot resolve the editor’s artifact paths. */
 export function artifactUrl(file: string): string {
   return new URL(`${ARTIFACT_BASE}/${file}`, import.meta.url).href;
 }
@@ -239,7 +160,7 @@ export interface BlenderArtifactStatus {
   /** Emscripten: each file's SHA-256 as it decodes, the key a page keeps it under. */
   digests?: Record<string, string>;
   /** Emscripten: the server answering runs in this tab (browser-substrate). Only then are the
-   *  digests used to keep the files in Cache Storage; absent (an older server) means false. */
+   *  digests used to keep the files in Cache Storage; absent means false. */
   inTab?: boolean;
   /** WALI only: the `sha256-` SRI of `blender.wasm`, which the program loader
    *  requires for any non-blob URL. */
@@ -249,7 +170,7 @@ export interface BlenderArtifactStatus {
   workers?: { pool: number; blender: number };
 }
 
-export async function artifactStatus(): Promise<BlenderArtifactStatus> {
+async function artifactStatus(): Promise<BlenderArtifactStatus> {
   const url = artifactUrl('status');
   const answer = await startupOperation(url, 'fetch status', () => fetch(url));
   if (!answer.ok)
@@ -303,83 +224,11 @@ export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve
 
 const decoder = new TextDecoder();
 
-/**
- * THE DIRECTORY CHANNEL, written once for both skews.
- *
- * `session.py`'s header states the other half and says why it is a directory
- * rather than stdin. Nothing here is toolchain-specific: a request is
- * `in/<id>.json` then `in/<id>.done`, an answer is `out/<id>.json` +
- * `out/<id>.done`, and an `ask` the session raises mid-call is served from
- * inside this poll loop -- which is why `saveDocument` cannot be raised from
- * Python's idle loop (`worker.ts` holds that clock).
- *
- * ONE WRITER PER DIRECTORY. This is the channel's single structural rule and
- * it is what keeps the WALI skew alive for a whole session:
- *
- *     in/     the PAGE writes and the PAGE unlinks; the guest only reads.
- *     out/    the GUEST writes and the GUEST unlinks; the page only reads.
- *     ask/    the GUEST writes and the GUEST unlinks; the page only reads.
- *     reply/  the PAGE writes and the PAGE unlinks; the guest only reads.
- *
- * WHY IT IS STRUCTURAL AND NOT A TUNING. Under WALI the two sides are two
- * snapshot-backed views of one tree, reconciled by patches: the guest sends
- * the paths IT changed, and `applyProcessFilesystemPatch` refuses the patch
- * (`assertPatchBase`) when a path in it no longer holds what the guest's base
- * said -- after which the host TERMINATES the program's worker. A path can
- * only disagree if somebody other than the patch's author moved it. So with
- * the sets of paths the two sides mutate DISJOINT, the assertion has nothing
- * left to fire on. MEASURED 2026-09-19 (WS-X): with this page unlinking four
- * files in the guest's own `out/` after every answer, a render loop died at
- * call 37 (`base`: a file, `current`: null) and at call 14 (a different
- * mtime), and narrowing the window moved the death 1 -> 13 -> 37 without
- * closing it.
- *
- * THE ACK IS THE REQUEST FILE'S DISAPPEARANCE, so it costs no file and no
- * extra write. Each side needs to know when the other has taken what it left:
- *
- *   - this page unlinks `in/<id>.json` and then `in/<id>.done` ONLY after it
- *     has read `out/<id>.json`. So `in/<id>.done` being gone IS "the page
- *     took the answer" -- a fact the guest reads out of a directory it never
- *     writes to, from the `listdir` its loop already does. It then removes
- *     its own `out/<id>.*`.
- *   - the session unlinks `ask/<id>.json` and then `ask/<id>.done` only after
- *     it has read `reply/<id>.json`, so `ask/<id>.done` being gone is "the
- *     guest took the reply" -- read here out of the `readdir` `serveAsks`
- *     already does, after which this page removes its own `reply/<id>.*`.
- *
- * `.done` IS ALWAYS UNLINKED LAST, on both sides, because `.done` is the
- * token the other side watches: a `.done` without its `.json` would be a
- * half-visible message.
- *
- * NOTHING HERE CATCHES ITS OWN UNLINK. These are files this page wrote into a
- * directory nothing else writes to; an ENOENT would mean the ownership rule
- * had been broken, and the loud failure of the call that found it is the
- * proof the rule holds.
- */
+/** Directory protocol for both engines: requests use in/<id>.json then in/<id>.done; answers use out/<id>.json then out/<id>.done. The page owns writes and cleanup in in/ and reply/; the guest owns out/ and ask/. Each writer removes .done last after the peer has acknowledged by removing its request. Disjoint writer sets keep WALI filesystem patches consistent. */
 export function openSessionChannel(
   files: BlenderFiles,
   options: BlenderEngineOptions,
-  /**
-   * WHY THE POLL LOOP NEEDS A LIVENESS PREDICATE, and it is the difference
-   * between a board and a wasted afternoon.
-   *
-   * The loop below waits for `out/<id>.done` and nothing else. When the
-   * program behind the directory DIES, that file is never written, so the
-   * call waits forever: `cyclotron status` reports it IN FLIGHT for as long as
-   * anyone looks, `blender-start` keeps answering from the host's cached
-   * banner, and the harness has no answer to time out against. MEASURED
-   * 2026-09-19 three times on the WALI skew -- 507 s, 621 s and 964 s of a
-   * battery model spent waiting on a Blender that had already ended with
-   * `[object WebAssembly.Exception]`, each ending in a killed process and no
-   * result record at all.
-   *
-   * This returns null while the program is alive and the reason it ended
-   * otherwise. A caller that supplies one turns that infinite wait into a
-   * named failure naming the recovery door. The standalone skew supplies
-   * none: its module is the worker, so a death there ends the worker rather
-   * than stranding a reader, and inventing a predicate for a failure nobody
-   * has measured would be a fiction.
-   */
+  /** Return null while the program is alive, or its termination reason. The WALI call loop uses this to refuse a request whose program ended; standalone failures end the worker itself. */
   programEnded?: () => string | null,
 ): {
   request(payload: Record<string, unknown>): Promise<unknown>;
@@ -440,13 +289,7 @@ export function openSessionChannel(
 
   async function request(payload: Record<string, unknown>): Promise<unknown> {
     const id = String(++sequence);
-    // BOTH WRITES BEGIN IN ONE TURN, `.done` second. Both engines write
-    // synchronously inside `writeFile` and throw from it, so the order is kept
-    // and a failed `.json` never leaves a `.done` behind; and the WALI
-    // engine carries one turn's writes to the program as one patch, where an
-    // await between them sent the request as two imports in series, the
-    // second waiting for the first's acknowledgement (measured 2026-09-28:
-    // most of a no-op call's 1.4-1.9 ms inbound leg).
+    // Begin the JSON and .done writes in one turn, in that order. Both engines write synchronously, and WALI carries that turn as one filesystem patch.
     await Promise.all([
       files.writeFile(`${SESSION_ROOT}/in/${id}.json`, JSON.stringify(payload)),
       files.writeFile(`${SESSION_ROOT}/in/${id}.done`, '1'),
@@ -458,18 +301,9 @@ export function openSessionChannel(
         const body = JSON.parse(
           decoder.decode(await files.readFile(`${SESSION_ROOT}/out/${id}.json`)),
         ) as { result?: unknown; error?: string };
-        // THE PAGE UNLINKS WHAT THE PAGE WROTE, AND ONLY THAT. `out/<id>.*`
-        // is the session's to remove; this loop does not touch it. Doing so
-        // is what killed a WALI session mid-run (see the ownership rule
-        // above): the guest's patch for `out/<id>.done` crossed this page's
-        // unlink of it, `assertPatchBase` refused the patch, and the host
-        // terminated the program's worker -- no guest exit path ran, which is
-        // why every instrument on `SYS_exit` was silent through it.
-        //
-        // These two unlinks are also the ACK. The session watches for
-        // `in/<id>.done` to vanish and takes that as "the page has the
-        // answer", so `.done` goes last and neither is attempted before
-        // `out/<id>.json` has been read.
+        // Unlink only the page-owned in/ request files after reading out/<id>.json. Removing
+        // in/<id>.done last acknowledges the answer to the session, which removes its own out/
+        // files.
         await files.unlink(`${SESSION_ROOT}/in/${id}.json`);
         await files.unlink(`${SESSION_ROOT}/in/${id}.done`);
         if (body.error) throw new Error(body.error);