@volter/blender-engine 0.1.111 → 0.1.113

package/browser/blender-emscripten-engine.mts

@@ -31,6 +31,7 @@ import { checkpointStream } from './pull-job.mts';
 import { writeStreamedFile, type StreamFileSystem } from './stream-file.mts';
 import {
   artifactUrl,
+  startupOperation,
   type BlenderArtifactStatus,
   type BlenderEngine,
   type BlenderEngineOptions,
@@ -83,19 +84,19 @@ type BlenderModuleFactory = (options: Record<string, unknown>) => Promise<Blende
 /** The glue, evaluated in this worker. It is a UMD bundle, so it is given the
  *  `module`/`exports` pair it looks for and hands back the factory. */
 async function loadFactory(glueUrl: string): Promise<BlenderModuleFactory> {
-  const source = await fetch(glueUrl);
+  const source = await startupOperation(glueUrl, 'fetch glue', () => fetch(glueUrl));
   if (!source.ok) throw new Error(`${glueUrl}: HTTP ${source.status}`);
-  const text = await source.text();
+  const text = await startupOperation(glueUrl, 'read glue body', () => source.text());
   const container = { exports: {} as { default?: BlenderModuleFactory } };
-  const evaluate = new Function(
+  const evaluate = await startupOperation(glueUrl, 'compile glue', () => new Function(
     'module',
     'exports',
     'define',
     `${text}\nreturn typeof createBlenderModule === 'function' ? createBlenderModule : module.exports;`,
-  ) as (module: unknown, exports: unknown, define: unknown) => BlenderModuleFactory;
-  const factory = evaluate(container, container.exports, undefined);
+  ) as (module: unknown, exports: unknown, define: unknown) => BlenderModuleFactory);
+  const factory = await startupOperation(glueUrl, 'evaluate glue', () => evaluate(container, container.exports, undefined));
   if (typeof factory !== 'function')
-    throw new Error('blender_browser.js did not produce a module factory');
+    throw new Error(`${glueUrl}: blender_browser.js did not produce a module factory`);
   return factory;
 }
 
@@ -155,17 +156,21 @@ async function cachedArtifact(file: string, digest: string | undefined, checkpoi
     ? new Response(checkpointStream(response.body, checkpoint), { status: response.status, headers: response.headers })
     : response;
   const url = artifactUrl(file);
-  if (!digest || typeof caches === 'undefined') return bounded(await fetch(url));
+  const fetchArtifact = () => startupOperation(url, 'fetch artifact', () => fetch(url));
+  if (!digest || typeof caches === 'undefined') return bounded(await fetchArtifact());
   const key = `${url}?sha256=${digest}`;
-  const cache = await caches.open(ARTIFACT_CACHE);
-  const hit = await cache.match(key);
+  const cache = await startupOperation(url, 'open artifact cache', () => caches.open(ARTIFACT_CACHE));
+  const hit = await startupOperation(url, 'read artifact cache', () => cache.match(key));
   if (hit) return bounded(hit);
-  const response = bounded(await fetch(url));
+  const response = bounded(await fetchArtifact());
   if (!response.ok) return response;
   // One build's bytes per file: an older build's are dropped as this one lands.
-  for (const old of await cache.keys()) if (old.url.startsWith(`${url}?sha256=`) && old.url !== key) await cache.delete(old);
-  const kept = new Response(await response.blob(), { headers: { 'content-type': response.headers.get('content-type') ?? 'application/octet-stream' } });
-  await cache.put(key, kept.clone());
+  await startupOperation(url, 'prune previous artifact cache entries', async () => {
+    for (const old of await cache.keys()) if (old.url.startsWith(`${url}?sha256=`) && old.url !== key) await cache.delete(old);
+  });
+  const body = await startupOperation(url, 'read artifact body for cache', () => response.blob());
+  const kept = new Response(body, { headers: { 'content-type': response.headers.get('content-type') ?? 'application/octet-stream' } });
+  await startupOperation(url, 'write artifact cache', () => cache.put(key, kept.clone()));
   return kept;
 }
 
@@ -188,8 +193,9 @@ export async function startEmscriptenBlenderEngine(
   const [factory, preloaded] = await Promise.all([
     loadFactory(glueUrl),
     artifact('blender_browser.data').then(async (response) => {
-      if (!response.ok) throw new Error(`blender_browser.data: HTTP ${response.status}`);
-      return response.arrayBuffer();
+      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());
     }),
   ]);
   await checkpoint('runtime-package-ready');
@@ -222,15 +228,16 @@ export async function startEmscriptenBlenderEngine(
     return made;
   } as unknown as typeof WebAssembly.Memory;
   const heap = (): Uint8Array => (memory ? new Uint8Array(memory.buffer) : module.HEAPU8);
-  const module = await factory({
+  const module = await startupOperation(glueUrl, 'initialize glue runtime', () => factory({
     arguments: ['--background', '--factory-startup', '--python', SESSION_SCRIPT],
     locateFile: (file: string) => artifactUrl(file),
     getPreloadedPackage: () => preloaded,
     instantiateWasm: (imports: WebAssembly.Imports, receive: (instance: WebAssembly.Instance, module: WebAssembly.Module) => void) => {
       void (async () => {
         const response = await artifact('blender_browser.wasm');
-        if (!response.ok) throw new Error(`blender_browser.wasm: HTTP ${response.status}`);
-        const { instance, module: compiled } = await WebAssembly.instantiateStreaming(response, imports);
+        const url = artifactUrl('blender_browser.wasm');
+        if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`);
+        const { instance, module: compiled } = await startupOperation(url, 'read and instantiate Wasm stream', () => WebAssembly.instantiateStreaming(response, imports));
         await checkpoint('wasm-instantiated');
         receive(instance, compiled);
       })().catch((error: unknown) => { bootError = error; });
@@ -280,7 +287,7 @@ export async function startEmscriptenBlenderEngine(
     ],
   }).finally(() => {
     (WebAssembly as { Memory: unknown }).Memory = Memory;
-  });
+  }));
   await checkpoint('runtime-initialized');
   // `main()` runs on a pthread (`-sPROXY_TO_PTHREAD`), so the factory resolves
   // long before the session exists. The ready line is what says it does.
@@ -375,16 +382,18 @@ export async function startEmscriptenBlenderEngine(
  * does not relink the 86 MB Wasm binary. Both payload and per-file bounds are
  * checked before anything enters Blender's filesystem. */
 async function mountEssentials(files: BlenderFiles, digest: string | undefined, checkpoint: (phase: string) => Promise<void>): Promise<void> {
+  const indexUrl = artifactUrl('essentials.json');
+  const payloadUrl = artifactUrl('essentials.bin');
   const [indexResponse, payloadResponse] = await Promise.all([
-    fetch(artifactUrl('essentials.json')), cachedArtifact('essentials.bin', digest, () => checkpoint('artifact/essentials.bin')),
+    startupOperation(indexUrl, 'fetch Essentials index', () => fetch(indexUrl)), cachedArtifact('essentials.bin', digest, () => checkpoint('artifact/essentials.bin')),
   ]);
   if (!indexResponse.ok || !payloadResponse.ok)
-    throw new Error(`Blender Essentials assets are missing (${indexResponse.status}/${payloadResponse.status})`);
-  const index = await indexResponse.json() as {
+    throw new Error(`Blender Essentials assets are missing (${indexUrl}: HTTP ${indexResponse.status}; ${payloadUrl}: HTTP ${payloadResponse.status})`);
+  const index = await startupOperation(indexUrl, 'decode Essentials index JSON', () => indexResponse.json()) as {
     bytes: number; sha256: string;
     files: { path: string; offset: number; bytes: number; sha256: string }[];
   };
-  const payload = await payloadResponse.arrayBuffer();
+  const payload = await startupOperation(payloadUrl, 'read Essentials payload body', () => payloadResponse.arrayBuffer());
   const hash = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', payload)),
     (byte) => byte.toString(16).padStart(2, '0')).join('');
   if (payload.byteLength !== index.bytes || hash !== index.sha256)

package/browser/blender-engine.mts

@@ -43,6 +43,8 @@
  * implementation over {@link BlenderFiles}.
  */
 
+import { describeThrown } from './describe-thrown.mts';
+
 export const SESSION_ROOT = '/work/.volter-session';
 export const SESSION_SCRIPT = `${SESSION_ROOT}/session.py`;
 
@@ -210,6 +212,19 @@ export function artifactUrl(file: string): string {
   return new URL(`${ARTIFACT_BASE}/${file}`, import.meta.url).href;
 }
 
+/** Attribute a startup failure without repeating the operation. The worker's
+ * document may never publish, so this message must survive as the diagnosis.
+ * For an import, url is the importing module; the browser's resolved failing
+ * module URL, when supplied, stays in the original cause. */
+export async function startupOperation<T>(url: string, operation: string, run: () => T | Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (cause) {
+    const detail = describeThrown(cause, false);
+    throw new Error(`Blender startup ${operation} (${url}): ${detail}`, { cause });
+  }
+}
+
 /** What the editor's artifact door answers. `blender-wasm-artifact.ts` owns it. */
 export interface BlenderArtifactStatus {
   available: boolean;
@@ -231,7 +246,8 @@ export interface BlenderArtifactStatus {
 }
 
 export async function artifactStatus(): Promise<BlenderArtifactStatus> {
-  const answer = await fetch(artifactUrl('status'));
+  const url = artifactUrl('status');
+  const answer = await startupOperation(url, 'fetch status', () => fetch(url));
   if (!answer.ok)
     return {
       available: false,
@@ -241,7 +257,7 @@ export async function artifactStatus(): Promise<BlenderArtifactStatus> {
       encoded: {},
       missing: [`${ARTIFACT_BASE}/status answered ${answer.status}`],
     };
-  return (await answer.json()) as BlenderArtifactStatus;
+  return startupOperation(url, 'decode status JSON', () => answer.json()) as Promise<BlenderArtifactStatus>;
 }
 
 /**
@@ -264,10 +280,10 @@ export async function startBlenderEngine(options: BlenderEngineOptions): Promise
       `The headless Blender WebAssembly build is not served by this editor: ${status.missing.join('; ')}`,
     );
   if (status.skew === 'wali') {
-    const { startWaliBlenderEngine } = await import('./blender-wali-engine.mts');
+    const { startWaliBlenderEngine } = await startupOperation(import.meta.url, 'import WALI engine module from', () => import('./blender-wali-engine.mts'));
     return startWaliBlenderEngine(options, status);
   }
-  const { startEmscriptenBlenderEngine } = await import('./blender-emscripten-engine.mts');
+  const { startEmscriptenBlenderEngine } = await startupOperation(import.meta.url, 'import Emscripten engine module from', () => import('./blender-emscripten-engine.mts'));
   return startEmscriptenBlenderEngine(options, status);
 }
 

package/browser/describe-thrown.mts

@@ -0,0 +1,22 @@
+/** 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. */
+export function describeThrown(error: unknown, includeStack = true): string {
+  if (error instanceof Error)
+    return (includeStack ? error.stack : undefined) ?? `${error.name}: ${error.message}`;
+  if (typeof error === 'object' && error !== null) {
+    const named = error as { name?: unknown; message?: unknown };
+    if (typeof named.message === 'string') {
+      return typeof named.name === 'string' ? `${named.name}: ${named.message}` : named.message;
+    }
+    try {
+      return JSON.stringify(error) ?? Object.prototype.toString.call(error);
+    } catch {
+      return Object.prototype.toString.call(error);
+    }
+  }
+  return String(error);
+}

package/browser/worker.ts

@@ -1,5 +1,7 @@
 import { PullJob, checkpointStream } from './pull-job.mts';
 import { sendFrameValue } from './frame-stream.mts';
+import { describeThrown } from './describe-thrown.mts';
+export { describeThrown } from './describe-thrown.mts';
 /**
  * THE BLENDER IN THE TAB IS BLENDER (ARCHITECTURE-CORE, owner ruling
  * 2026-09-17): the editor's modeling engine is Blender 5.2 LTS compiled to
@@ -39,7 +41,7 @@ import { sendFrameValue } from './frame-stream.mts';
  */
 /// <reference types="vite/client" />
 
-import { type BlenderEngine, type BlenderFiles, startBlenderEngine } from './blender-engine.mts';
+import { startupOperation, type BlenderEngine, type BlenderFiles, startBlenderEngine } from './blender-engine.mts';
 import type { CaptureRequest, FileEntry, WorkerReply, WorkerRequest } from './protocol';
 import { documentChunks } from './document-chunks.mts';
 import { columnsToTypedArrays, describeFrame, isColumnDescriptor } from './session-frame.mts';
@@ -395,10 +397,11 @@ async function startBlender(project: string, document?: string): Promise<unknown
 }
 
 async function blenderIsServed(): Promise<{ available: boolean; missing: string[] }> {
+  const url = '/__editor/blender-wasm/status';
   try {
-    const answer = await fetch('/__editor/blender-wasm/status');
-    if (!answer.ok) return { available: false, missing: [`status answered ${answer.status}`] };
-    return (await answer.json()) as { available: boolean; missing: string[] };
+    const answer = await startupOperation(url, 'fetch initial status', () => fetch(url));
+    if (!answer.ok) return { available: false, missing: [`${url}: HTTP ${answer.status}`] };
+    return await startupOperation(url, 'decode initial status JSON', () => answer.json()) as { available: boolean; missing: string[] };
   } catch (error) {
     return { available: false, missing: [String(error)] };
   }
@@ -737,30 +740,6 @@ async function handle(request: WorkerRequest): Promise<unknown> {
   throw new Error(`Unknown Blender worker request ${(request as { op: string }).op}`);
 }
 
-/** Anything thrown, rendered so the message SURVIVES the boundary.
- *
- * `error instanceof Error ? ... : String(error)` renders a thrown plain object
- * as `[object Object]`, and that is the whole error a script sees: the worker
- * answered `17-workshop-interior` seq 7 with exactly that, which named neither
- * the operation nor the cause and left the next step with nothing to go on.
- * A DOMException carries its name, and a plain object carries its own fields,
- * so both are spelled out rather than coerced. */
-export function describeThrown(error: unknown): string {
-  if (error instanceof Error) return error.stack ?? `${error.name}: ${error.message}`;
-  if (typeof error === 'object' && error !== null) {
-    const named = error as { name?: unknown; message?: unknown };
-    if (typeof named.message === 'string') {
-      return typeof named.name === 'string' ? `${named.name}: ${named.message}` : named.message;
-    }
-    try {
-      return JSON.stringify(error) ?? Object.prototype.toString.call(error);
-    } catch {
-      return Object.prototype.toString.call(error);
-    }
-  }
-  return String(error);
-}
-
 /**
  * Tell the tab how big the engine's memory is now.
  *

package/package.json

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