@volter/blender-engine 0.1.20 → 0.1.22

package/browser/blender-emscripten-engine.mts

@@ -37,6 +37,7 @@ import {
   PAGE_OWNED_DIRECTORIES,
   SESSION_ROOT,
   SESSION_SCRIPT,
+  sessionLevel,
   sleep,
 } from './blender-engine.mts';
 import sessionPython from './session.py?raw';
@@ -195,10 +196,7 @@ export async function startEmscriptenBlenderEngine(
   // session's OWN named conditions go there.
   const say = (_level: 'log' | 'error', text: string) => {
     if (text.startsWith('@@VOLTER-READY ')) readyLine = text.slice('@@VOLTER-READY '.length);
-    options.log(
-      text.startsWith('@@VOLTER-WARN') || text.startsWith('@@VOLTER-ERROR') ? 'error' : 'log',
-      text,
-    );
+    options.log(sessionLevel(text), text);
   };
   const module = await factory({
     arguments: ['--background', '--factory-startup', '--python', SESSION_SCRIPT],

package/browser/blender-engine.mts

@@ -107,7 +107,7 @@ export interface BlenderFiles {
 export interface BlenderEngineOptions {
   /** The project's absolute path; the engine's filesystem mirrors it there. */
   project: string;
-  log(level: 'log' | 'error', text: string): void;
+  log(level: 'log' | 'warn' | 'error', text: string): void;
   /** What the session asks the TAB for, mid-call: a frame, and sometimes a
    *  photograph of it. Whatever this resolves to is what Python receives.
    *
@@ -161,6 +161,14 @@ export interface BlenderEngine {
 
 export const ARTIFACT_BASE = '/__editor/blender-wasm';
 
+/** The console level of one line the session printed. Only the session's own named conditions
+ *  reach the editor's console, each at the severity it names; Blender's streams stay page output. */
+export function sessionLevel(line: string): 'log' | 'warn' | 'error' {
+  if (line.startsWith('@@VOLTER-ERROR')) return 'error';
+  if (line.startsWith('@@VOLTER-WARN')) return 'warn';
+  return 'log';
+}
+
 /**
  * An artifact URL, resolved against THE MODULE — never against `self.location`.
  *

package/browser/blender-wali-engine.mts

@@ -52,6 +52,7 @@ import {
   PAGE_OWNED_DIRECTORIES,
   SESSION_ROOT,
   SESSION_SCRIPT,
+  sessionLevel,
   sleep,
 } from './blender-engine.mts';
 import sessionPython from './session.py?raw';
@@ -231,6 +232,110 @@ async function sharedRuntime(
   return layer;
 }
 
+type StoreLayerFromIndex = (
+  root: string,
+  files: RuntimeIndex['files'],
+  store: string,
+  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.
+ */
+async function installedRuntime(
+  fromIndex: StoreLayerFromIndex,
+  hold: ((projectId: string) => Promise<void>) | undefined,
+  log: BlenderEngineOptions['log'],
+): Promise<unknown> {
+  const began = performance.now();
+  const indexAnswer = await fetch(artifactUrl('runtime.idx'));
+  if (!indexAnswer.ok)
+    throw new Error(`${ARTIFACT_BASE}/runtime.idx answered ${indexAnswer.status}`);
+  const text = await indexAnswer.text();
+  const index = JSON.parse(text) as RuntimeIndex;
+  // The tree's version is its index: the same files at the same sizes and modes, in the same order,
+  // and its newest file's time (`runtimeTag`'s validator), so a file rebuilt at the same size is a new version.
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)));
+  const tag = [...digest.slice(0, 12)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+  const projectId = `${RUNTIME_STORE_FAMILY}${tag}`;
+  // THIS PAGE HOLDS ITS TREE IN USE from before it is installed to the end of the session, so
+  // another tab installing another version never removes it under this one's runs (ADR-0048).
+  if (hold) {
+    try {
+      await hold(projectId);
+    } catch (error) {
+      log('log', `blender: the runtime tree stays in memory: it cannot be held in use (${error instanceof Error ? error.message : String(error)})`);
+      return undefined;
+    }
+  }
+  let worker: Worker;
+  try {
+    worker = new Worker(artifactUrl('wali/browser-wali/tree-store-worker.js'), { type: 'module' });
+  } catch (error) {
+    log('log', `blender: the runtime tree stays in memory: no installer worker (${error instanceof Error ? error.message : String(error)})`);
+    return undefined;
+  }
+  // A BOUNDED STALL, NOT A BOUNDED INSTALL: an install stalled in another tab (a throttled background
+  // tab) holds this tree's installer lock, or the network stops. Each batch written restarts the wait,
+  // so a slow link still installs. On a stall this boot carries the tree in memory, and the installer
+  // is left to finish for the next boot rather than stopped halfway.
+  const answer = await new Promise<{ ok: boolean; installed?: boolean; bytes?: number; error?: string }>((resolve) => {
+    let settled = false;
+    const settle = (value: { ok: boolean; installed?: boolean; bytes?: number; error?: string }): void => {
+      if (!settled) { settled = true; resolve(value); }
+    };
+    let timer = setTimeout(() => settle({ ok: false, error: `no progress in ${INSTALL_STALL_MS / 1000} s` }), INSTALL_STALL_MS);
+    worker.onmessage = (event) => {
+      clearTimeout(timer);
+      if (typeof event.data?.progress === 'number') {
+        if (!settled) timer = setTimeout(() => settle({ ok: false, error: `no progress in ${INSTALL_STALL_MS / 1000} s` }), INSTALL_STALL_MS);
+        return;
+      }
+      worker.terminate();
+      settle(event.data);
+    };
+    worker.onerror = (event) => {
+      clearTimeout(timer);
+      worker.terminate();
+      settle({ ok: false, error: event.message || 'the installer worker failed to start' });
+    };
+    worker.postMessage({
+      projectId,
+      family: RUNTIME_STORE_FAMILY,
+      root: RESOURCES,
+      files: index.files,
+      blobUrl: new URL(artifactUrl('runtime.bin'), location.href).href,
+      mtimeMs: Date.now(),
+    });
+  });
+  if (!answer.ok) {
+    log('log', `blender: the runtime tree stays in memory: it could not be installed (${answer.error})`);
+    return undefined;
+  }
+  const layer = fromIndex(RESOURCES, index.files, projectId, {
+    mtimeMs: Date.now(),
+    include: (path) => !PACK_RENDER_OVERRIDES.has(path),
+  });
+  log('log', `blender: Blender's ${index.files.length}-file runtime tree is on disk (${answer.installed ? `installed, ${Math.round((answer.bytes ?? 0) / 1e6)} MB` : 'installed before'}) in ${Math.round(performance.now() - began)} ms`);
+  return layer;
+}
+
+/**
+ * Installed runtime trees' store names begin so; installing one removes the others that no tab
+ * reads. `host-tree.` is the substrate's mark of an installed tree (`TREE_STORE_PREFIX`), which no
+ * project may take.
+ */
+const RUNTIME_STORE_FAMILY = 'host-tree.blender-runtime-';
+/** How long a boot waits on an installer that writes nothing before it carries the tree in memory. */
+const INSTALL_STALL_MS = 20_000;
+
 /** The program's filesystem, as {@link BlenderFiles}. */
 function programFiles(filesystem: BrowserFileSystemLike): BlenderFiles {
   // One listener for the engine's life, and one waiter per wait: a change ends
@@ -316,7 +421,10 @@ export async function startWaliBlenderEngine(
   ])
     filesystem.mkdirSync(directory, { recursive: true });
   const fromIndex = layers['sharedFileLayerFromIndex'] as LayerFromIndex | undefined;
-  const runtimeLayer = fromIndex ? await sharedRuntime(fromIndex, options.log) : undefined;
+  const fromStore = layers['storeFileLayerFromIndex'] as StoreLayerFromIndex | undefined;
+  const holdTree = layers['holdTreeStore'] as ((projectId: string) => Promise<void>) | undefined;
+  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);
 
@@ -381,10 +489,7 @@ export async function startWaliBlenderEngine(
       // -- 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.
-      options.log(
-        line.startsWith('@@VOLTER-WARN') || line.startsWith('@@VOLTER-ERROR') ? 'error' : 'log',
-        line,
-      );
+      options.log(sessionLevel(line), line);
     }
   };
   // THE PROGRAM DOES NOT RETURN. `session.py` loops forever, so `run` settles

package/browser/protocol.ts

@@ -109,7 +109,7 @@ export type WorkerReply =
    *  as the record of what the session submitted — the second side a
    *  displayed-versus-submitted comparison otherwise does not have. */
   | { op: 'present'; id: number; frame: unknown; description: unknown; capture?: CaptureRequest }
-  | { op: 'log'; level: 'log' | 'error'; text: string }
+  | { op: 'log'; level: 'log' | 'warn' | 'error'; text: string }
   /**
    * HOW BIG THE MODULE'S LINEAR MEMORY IS, posted after every call.
    *

package/browser/runtime.ts

@@ -44,7 +44,7 @@ export interface BlenderRuntimeOptions {
     description: unknown,
     capture?: CaptureRequest,
   ): Promise<PresentAnswer> | PresentAnswer;
-  log?(level: 'log' | 'error', text: string): void;
+  log?(level: 'log' | 'warn' | 'error', text: string): void;
 }
 
 /**

package/browser/worker.ts

@@ -41,7 +41,7 @@ import type { CaptureRequest, FileEntry, WorkerReply, WorkerRequest } from './pr
 import { columnsToTypedArrays, describeFrame } from './session-frame.mts';
 
 const post = (reply: WorkerReply) => (self as unknown as Worker).postMessage(reply);
-const log = (level: 'log' | 'error', text: string) => post({ op: 'log', level, text });
+const log = (level: 'log' | 'warn' | 'error', text: string) => post({ op: 'log', level, text });
 
 interface Session {
   start(project: string): Promise<unknown>;

package/package.json

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