@volter/blender-engine 0.1.147 → 0.1.149

package/browser/blender-wali-engine.mts

@@ -56,6 +56,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';
 
 /** Blender's own resource root inside the program, spelled the same way the
  *  standalone skew spells it so `BLENDER_SYSTEM_*` reads identically. */
@@ -81,17 +84,22 @@ interface BrowserFileSystemLike {
   on?(event: 'change' | 'delete', listener: (path: string) => void): unknown;
 }
 
+/** A write that replaces whatever is at `path` (`BlenderFiles.writeFile`). */
+function replaceFileSync(filesystem: BrowserFileSystemLike, path: string, data: string | Uint8Array): void {
+  if (filesystem.existsSync(path)) filesystem.unlinkSync(path);
+  filesystem.writeFileSync(path, data);
+}
+
 interface WaliProgram {
   run(
     argv: readonly string[],
     options: {
       onStdout?(chunk: string): void;
       onStderr?(chunk: string): void;
-      /** The WALI RUNTIME's own word to its host, not the program's stream --
-       *  today the one-shot notice that an unimplemented syscall was answered
-       *  `-ENOSYS` instead of trapping. Declared here because the call site
-       *  passes it (`run(...)` below) and this local shape is the only thing
-       *  that types that call. */
+      /**
+       * The WALI runtime’s diagnostic callback, separate from the program’s output. Reports an
+       * unimplemented syscall answered with -ENOSYS.
+       */
       onDiagnostic?(message: string): void;
     },
   ): Promise<{ exitCode: number; stdout: string; stderr: string }>;
@@ -118,15 +126,8 @@ async function substrate(module: string): Promise<Record<string, unknown>> {
 }
 
 /**
- * Blender's runtime tree — its scripts, datafiles and Python — into the
- * program's filesystem.
- *
- * ONE INDEX AND ONE BLOB, not 2,276 requests. The tree is 78 MB in ~2,300
- * files and every one of them has to exist before Blender's first act, so the
- * editor serves a JSON index and the bytes concatenated in its order
- * (`blender-wasm-artifact.ts`); this walks the index and slices. The
- * standalone skew's equivalent is the packed `.data` payload, and this is the
- * same shape for a filesystem that is not a module's.
+ * Install Blender’s scripts, datafiles and Python into the program filesystem from one index and
+ * concatenated blob. The Emscripten build uses its packed .data payload for the same content.
  */
 async function stageRuntime(
   filesystem: BrowserFileSystemLike,
@@ -149,20 +150,14 @@ async function stageRuntime(
         `Blender runtime ${entry.path}: bytes ${offset}..${offset + entry.size} lie outside ` +
           `the ${blob.byteLength}-byte runtime blob`,
       );
-    // THE PACK'S RENDER OVERRIDE IS NOT STAGED. It is the delivery for a bare
-    // `blender -b` with no session: at startup it asks a presenter at its own
-    // directory and waits two seconds for one. This session registers the same
-    // override itself (`session.py`, `VolterRenderEngine`) and answers through
-    // its own channel, so here the module could only wait out those two
-    // seconds (measured 2026-09-27: every boot printed "no presenter answered
-    // at /tmp/vgai-presenter within 2 s").
+    // Skip the pack’s standalone render override: session.py registers VolterRenderEngine and serves its own presenter channel.
     if (PACK_RENDER_OVERRIDES.has(entry.path)) {
       offset += entry.size;
       continue;
     }
     const path = `${RESOURCES}/${entry.path}`;
     filesystem.mkdirSync(path.slice(0, path.lastIndexOf('/')), { recursive: true });
-    filesystem.writeFileSync(path, blob.subarray(offset, offset + entry.size));
+    replaceFileSync(filesystem, path, blob.subarray(offset, offset + entry.size));
     offset += entry.size;
   }
   if (offset !== blob.byteLength)
@@ -181,15 +176,7 @@ type LayerFromIndex = (
   options: { mtimeMs: number; include?: (path: string) => boolean },
 ) => unknown;
 
-/**
- * Blender's runtime tree as a SHARED LAYER the program reads, never written
- * into this page's filesystem (browser-substrate ADR-0044 §6): the blob is
- * read once, straight into shared memory, and the index names where each file
- * lies in it. Staged file by file, the tree was held twice -- in this page's
- * filesystem and in the layer the substrate made of it for the program's
- * workers -- and took 0.3-0.5 s of every boot (measured 2026-09-27). A
- * substrate without the door (`sharedFileLayerFromIndex`) stages as before.
- */
+/** Build a shared runtime file layer from one blob and its index. The program reads the layer without copying it into the page filesystem. */
 async function sharedRuntime(
   fromIndex: LayerFromIndex,
   log: BlenderEngineOptions['log'],
@@ -220,12 +207,7 @@ async function sharedRuntime(
     throw new Error(`Blender runtime index accounts for ${total} bytes; the blob served ${filled}`);
   const layer = fromIndex(RESOURCES, index.files, shared, {
     mtimeMs: Date.now(),
-    // THE PACK'S RENDER OVERRIDE IS LEFT OUT: it is the delivery for a bare
-    // `blender -b` with no session, and at startup it asks a presenter at its
-    // own directory and waits two seconds for one. This session registers the
-    // same override itself (`session.py`, `VolterRenderEngine`) and answers
-    // through its own channel, so here the module could only wait (measured
-    // 2026-09-27: every boot printed "no presenter answered ... within 2 s").
+    // Skip the standalone render override because session.py registers VolterRenderEngine on this session’s channel.
     include: (path) => !PACK_RENDER_OVERRIDES.has(path),
   });
   log('log', `blender: shared Blender's ${index.files.length}-file runtime tree in ${Math.round(performance.now() - began)} ms`);
@@ -239,16 +221,7 @@ type StoreLayerFromIndex = (
   options: { mtimeMs: number; include?: (path: string) => boolean },
 ) => unknown;
 
-/**
- * Blender's runtime tree as a STORE ON THE ORIGIN'S DISK the program reads
- * (browser-substrate ADR-0048): installed once per version by the
- * substrate's installer worker, and read file by file as Blender opens them,
- * a large file by the ranges it reads. The shared layer before it copied all
- * 96 MB into memory before Blender started (0.9 s of each boot) and held it
- * for the run; a boot reads 268 of the 2,082 files (measured 2026-09-28).
- * Undefined, and said, where it cannot be installed: the shared layer then
- * carries the tree as before.
- */
+/** Install the versioned runtime file store on the origin and read files by range as Blender requests them. The shared layer carries the tree when installation is unavailable. */
 async function installedRuntime(
   fromIndex: StoreLayerFromIndex,
   hold: ((projectId: string) => Promise<void>) | undefined,
@@ -354,7 +327,7 @@ function programFiles(filesystem: BrowserFileSystemLike): BlenderFiles {
     }) } : {}),
     readFile: (path) => filesystem.readFile(path),
     // Not `async`: a write that throws throws here, so `request` never starts `.done` after a failed `.json`.
-    writeFile: (path, data) => { filesystem.writeFileSync(path, data); return Promise.resolve(); },
+    writeFile: (path, data) => { replaceFileSync(filesystem, path, data); return Promise.resolve(); },
     mkdirTree: async (path) => filesystem.mkdirSync(path, { recursive: true }),
     readdir: async (path) => filesystem.readdirSync(path),
     stat: async (path) => {
@@ -377,10 +350,11 @@ export async function startWaliBlenderEngine(
   status: BlenderArtifactStatus,
 ): Promise<BlenderEngine> {
   const started = performance.now();
-  const [wali, runtime, layers] = await Promise.all([
+  const [wali, runtime, layers, addonFiles] = await Promise.all([
     substrate('browser-wali/worker-program.js'),
     substrate('browser-runtime/browser-memory-filesystem.js'),
     substrate('browser-wali/shared-file-layer.js').catch((): Record<string, unknown> => ({})),
+    sessionAddonFiles(),
   ]);
   const WaliWorkerProgram = wali['BrowserWaliWorkerProgram'] as
     | (new (
@@ -398,12 +372,7 @@ export async function startWaliBlenderEngine(
         'does not know.',
     );
 
-  // THE MODULE LOADS WHILE THE RUNTIME LAYER IS BUILT. Blender's 93 MB module
-  // was fetched and compiled by the program's worker only once the program
-  // ran, after the layer below: measured 2026-09-28, the layer 270-975 ms and
-  // then the module 200-250 ms warm, in series. The substrate's preload fills
-  // the cache the program's worker reads; a substrate without it, or a preload
-  // that fails, leaves the worker to load the module as before.
+  // Preload the program module while constructing the runtime layer so fetch and compilation can overlap.
   const preload = wali['preloadWaliModule'] as ((url: string, integrity: string) => Promise<void>) | undefined;
   if (preload && status.integrity) void preload(artifactUrl('blender.wasm'), status.integrity).catch(() => undefined);
 
@@ -427,7 +396,12 @@ export async function startWaliBlenderEngine(
   const runtimeLayer = (fromStore ? await installedRuntime(fromStore, holdTree, options.log) : undefined)
     ?? (fromIndex ? await sharedRuntime(fromIndex, options.log) : undefined);
   if (!runtimeLayer) await stageRuntime(filesystem, options.log);
-  filesystem.writeFileSync(SESSION_SCRIPT, sessionPython);
+  replaceFileSync(filesystem, SESSION_SCRIPT, sessionPython);
+  replaceFileSync(filesystem, `${SESSION_ROOT}/gltf_export.py`, gltfExportPython);
+  for (const { path, bytes } of addonFiles) {
+    filesystem.mkdirSync(path.slice(0, path.lastIndexOf('/')), { recursive: true });
+    replaceFileSync(filesystem, path, bytes);
+  }
 
   const workers = status.workers ?? { pool: 16, blender: 4 };
   const program = new WaliWorkerProgram(filesystem, {
@@ -457,22 +431,11 @@ export async function startWaliBlenderEngine(
       VOLTER_SESSION_ROOT: SESSION_ROOT,
       // THE ARENA'S DOOR ON THIS SKEW. See `readArena`.
       VOLTER_EXPORT_BUFFER_PATH: ARENA_PATH,
-      // OPENIMAGEIO'S POOL AT ONE THREAD, as Blender's own are (`-t 1`,
-      // BLENDER_WALI_WORKERS). Its default pool is built at the CPU count
-      // before `-t` reaches it: measured 2026-09-28, nine of the ten threads
-      // this Blender started were OpenImageIO's, idle for the session, each
-      // holding a pool worker (browser-substrate `programs/blender/5.2.0`
-      // README §(f)).
+      // Limit OpenImageIO’s pool before Blender starts; -t applies to Blender’s own worker pool.
       OPENIMAGEIO_THREADS: '1',
     },
     ...(runtimeLayer ? { layers: [runtimeLayer] } : {}),
-    // BLENDER'S /tmp IS ITS OWN, as it is in the standalone skew's WasmFS:
-    // what it writes there never crosses to this page, so nothing waits for
-    // the page to take it (browser-substrate `privateRoots`, ADR-0046).
-    // Measured 2026-09-27: published, a `.blend` saved to /tmp cost 11 ms
-    // against the standalone skew's 2, most of it the page taking the file
-    // before Blender's next printed line. The session's channel and the
-    // project live elsewhere and still cross.
+    // Keep Blender’s /tmp private to the program. The session channel and project files remain shared with the page.
     privateRoots: ['/tmp'],
     threadPoolSize: workers.pool,
     // Blender talks to nothing. The editor's own routes are this worker's, not
@@ -486,10 +449,7 @@ 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);
-      // BLENDER'S OWN STREAMS ARE PAGE OUTPUT, NOT EDITOR-CONSOLE CONDITIONS
-      // -- the same rule as the standalone engine, and for the same measured
-      // reason: only the session's own named conditions belong in the set an
-      // agent must drive to zero.
+      // Route Blender streams to page output; named session conditions use their own channel.
       options.log(sessionLevel(line), line);
     }
   };
@@ -518,14 +478,8 @@ export async function startWaliBlenderEngine(
       {
         onStdout: say,
         onStderr: say,
-        // NOT Blender's stream, and that is exactly why this one IS a named
-        // condition where `say` is page output. `onDiagnostic` is the WALI
-        // runtime's own word to its host -- today, the one-shot notice that an
-        // unimplemented syscall was answered `-ENOSYS` instead of trapping
-        // (`@volter/browser-wali`'s `runtime.ts`). Answering like a kernel is
-        // only defensible because the CALLER can degrade VISIBLY; without this
-        // the degrade is silent, and before it existed the notice reached a
-        // nested worker's devtools console and nothing else.
+        // Forward the WALI runtime’s unimplemented-syscall diagnostic to page output so a degraded
+        // operation remains visible to the caller.
         onDiagnostic: (message: string) => options.log('error', `@@VOLTER-ERROR ${message}`),
       },
     )

package/browser/describe-thrown.mts

@@ -1,9 +1,6 @@
-/** Anything thrown, rendered so the message SURVIVES the worker boundary.
- *
- * String(object) erased a prior real diagnostic as [object Object]. Preserve
- * named messages or JSON fields, with a safe fallback for cyclic values.
- * Startup wrappers omit Error stacks from their user-visible message; worker
- * replies keep them as before. */
+/** Preserve thrown messages across the worker boundary, including named fields on plain
+ * objects and a printable representation of cyclic values. Startup wrappers omit Error stacks;
+ * worker replies include them. */
 export function describeThrown(error: unknown, includeStack = true): string {
   if (error instanceof Error)
     return (includeStack ? error.stack : undefined) ?? `${error.name}: ${error.message}`;

package/browser/document-chunks.mts

@@ -1,19 +1,7 @@
-/**
- * A saved `.blend` cut into content-defined chunks, the unit a document save travels in
- * (`editor-blender/serving/blender-routes.ts`, `/__editor/blender-document`).
- *
- * WHY CONTENT-DEFINED. A save rewrites the whole file, but an edit changes little of it:
- * MEASURED 2026-09-29, native Blender 5.2 on the Stoneguard bridge, one object moved between two
- * saves changed 1 of 475 one-MiB chunks of a 497 MB file. Fixed offsets would keep that only while
- * no block changes size; an edit that grows a mesh would shift every chunk after it. Cutting where
- * the bytes themselves say (a gear hash, as FastCDC does) re-aligns right after the change, so only
- * the chunks around it are new.
- *
- * The bounds are the transport's: no chunk above {@link CHUNK_MAX}, which the server refuses.
- */
+/** Split saved .blend bytes at content-defined gear-hash boundaries so unchanged ranges retain their identities after size-changing edits. CHUNK_MAX is the server’s transport limit. */
 
-export const CHUNK_MIN = 256 * 1024;
-export const CHUNK_MAX = 4 * 1024 * 1024;
+const CHUNK_MIN = 256 * 1024;
+const CHUNK_MAX = 4 * 1024 * 1024;
 /** 20 bits: a cut about every MiB past the minimum. */
 const CUT_MASK = (1 << 20) - 1;
 
@@ -32,7 +20,7 @@ const GEAR = (() => {
 })();
 
 /** The end offsets of each chunk of `bytes`. */
-export function chunkBoundaries(bytes: Uint8Array): number[] {
+function chunkBoundaries(bytes: Uint8Array): number[] {
   const ends: number[] = [];
   let start = 0;
   while (start < bytes.length) {