@volter/blender-engine 0.1.57 → 0.1.59

package/browser/blender-engine.mts

@@ -127,6 +127,7 @@ export interface BlenderEngineOptions {
  * answered as a whole frame is.
  */
 export interface SessionAsk {
+  checkpoint?: string;
   frame?: unknown;
   hold?: unknown;
   mesh?: string;
@@ -382,15 +383,16 @@ export function openSessionChannel(
   /** Answer any `ask` the session has raised, and retire the replies it has
    *  taken. Called from the poll loop, so a present raised inside a call is
    *  served while that call is outstanding. */
-  async function serveAsks(): Promise<void> {
+  async function serveAsks(): Promise<boolean> {
     let names: string[];
     try {
       names = await files.readdir(`${SESSION_ROOT}/ask`);
     } catch {
-      return;
+      return false;
     }
     const raised = new Set(names.filter((name) => name.endsWith('.done')));
     await retireReplies(raised);
+    let progressed = false;
     for (const name of raised) {
       const id = name.slice(0, -'.done'.length);
       if (Number(id) <= asking) continue;
@@ -410,7 +412,9 @@ export function openSessionChannel(
         files.writeFile(`${SESSION_ROOT}/reply/${id}.done`, '1'),
       ]);
       replied.add(id);
+      progressed = true;
     }
+    return progressed;
   }
 
   async function request(payload: Record<string, unknown>): Promise<unknown> {
@@ -426,9 +430,9 @@ export function openSessionChannel(
       files.writeFile(`${SESSION_ROOT}/in/${id}.json`, JSON.stringify(payload)),
       files.writeFile(`${SESSION_ROOT}/in/${id}.done`, '1'),
     ]);
-    const began = performance.now();
+    let lastProgress = performance.now();
     for (;;) {
-      await serveAsks();
+      if (await serveAsks()) lastProgress = performance.now();
       if (await files.stat(`${SESSION_ROOT}/out/${id}.done`)) {
         const body = JSON.parse(
           decoder.decode(await files.readFile(`${SESSION_ROOT}/out/${id}.json`)),
@@ -458,7 +462,7 @@ export function openSessionChannel(
             'wait on the same missing answer; start a new program with `blender-start {fresh: true}` ' +
             '(`VOLTER_BLENDER_FRESH_SESSION=1` for the battery harness).',
         );
-      const delay = pollDelay(performance.now() - began);
+      const delay = pollDelay(performance.now() - lastProgress);
       await (files.changed ? files.changed(delay) : sleep(delay));
     }
   }

package/browser/protocol.ts

@@ -3,6 +3,7 @@ import type { FrameChunk } from './frame-stream.mts';
  * worker; the model lives in the worker's Python and nowhere else. */
 
 export type WorkerRequest =
+  | { id: number; op: 'load-next'; token: string }
   | { id: number; op: 'flush-document' }
   | { id: number; op: 'history-begin' | 'history-end' }
   | { id: number; op: 'history-step'; token: string; direction: 'undo' | 'redo' }

package/browser/pull-job.mts

@@ -0,0 +1,58 @@
+/** A cooperative job advances only when its owner asks for its next unit.
+ * Checkpoints park the producer; they do not renew a timer while work runs. */
+export type PullResult<T> = { load: 'continue'; token: string; phase: string } | { load: 'done'; value: T };
+export class PullJob<T> {
+  private started = false;
+  private finished = false;
+  private sequence = 0;
+  private expected: string | null = null;
+  private resume: (() => void) | null = null;
+  private waiter: { resolve: (value: PullResult<T>) => void; reject: (error: unknown) => void } | null = null;
+  constructor(private readonly work: (checkpoint: (phase: string) => Promise<void>) => Promise<T>) {}
+  step(token?: string): Promise<PullResult<T>> {
+    if (this.finished || this.waiter || (this.started ? token !== this.expected || !this.resume : token !== undefined))
+      return Promise.reject(new Error('Invalid or replayed load continuation'));
+    const answer = new Promise<PullResult<T>>((resolve, reject) => { this.waiter = { resolve, reject }; });
+    if (!this.started) {
+      this.started = true;
+      void Promise.resolve().then(() => this.work(phase => new Promise<void>(resolve => {
+        this.resume = resolve;
+        this.expected = `load:${++this.sequence}`;
+        const waiter = this.waiter!; this.waiter = null;
+        waiter.resolve({ load: 'continue', token: this.expected, phase });
+      }))).then(value => {
+        this.finished = true;
+        const waiter = this.waiter!; this.waiter = null;
+        waiter.resolve({ load: 'done', value });
+      }, error => {
+        this.finished = true;
+        const waiter = this.waiter!; this.waiter = null;
+        waiter.reject(error);
+      });
+    } else {
+      const resume = this.resume!; this.resume = null; this.expected = null; resume();
+    }
+    return answer;
+  }
+}
+
+/** A streamed import consumes at most one MiB before yielding its producer. */
+export function checkpointStream(body: ReadableStream<Uint8Array>, checkpoint: () => Promise<void>): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  let held: Uint8Array | undefined, offset = 0;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        if (!held || offset === held.length) {
+          const next = await reader.read();
+          if (next.done) { reader.releaseLock(); controller.close(); return; }
+          held = next.value; offset = 0;
+        }
+        await checkpoint();
+        const end = Math.min(held.length, offset + 1024 * 1024);
+        controller.enqueue(held.subarray(offset, end)); offset = end;
+      } catch (error) { await reader.cancel(error).catch(() => {}); controller.error(error); }
+    },
+    async cancel(reason) { await reader.cancel(reason); reader.releaseLock(); },
+  }, { highWaterMark: 0 });
+}

package/browser/runtime.ts

@@ -1,3 +1,4 @@
+import type { PullResult } from './pull-job.mts';
 import { FrameStreamReader } from './frame-stream.mts';
 /**
  * The tab-side handle on a Blender session: spawns the worker, forwards the
@@ -253,7 +254,7 @@ export class BlenderRuntime {
       );
     this.#project = project;
     this.#document ??= document ?? 'models/model.blend';
-    this.#started ??= this.#request({
+    this.#started ??= this.#load({
       op: 'start',
       project,
       ...(document === undefined ? {} : { document }),
@@ -261,6 +262,14 @@ export class BlenderRuntime {
     return this.#started;
   }
 
+  async #load(request: Extract<Request, { op: 'start' }>): Promise<RuntimeStart> {
+    let result = await this.#request(request) as PullResult<RuntimeStart>;
+    while (result?.load === 'continue') {
+      result = await this.#request({ op: 'load-next', token: result.token }) as PullResult<RuntimeStart>;
+    }
+    return result?.load === 'done' ? result.value : result as unknown as RuntimeStart;
+  }
+
   #ready(): Promise<RuntimeStart> {
     if (this.#project === null)
       return Promise.reject(

package/browser/session.py

@@ -1402,7 +1402,11 @@ class Session:
             options["defer"] = True
         if hasattr(_blender_web, "memory_reset_peak"):
             _blender_web.memory_reset_peak()
-        exported = _blender_web.export_frame(json.dumps(options))
+        if hasattr(_blender_web, "export_frame_chunked"):
+            exported = _blender_web.export_frame_chunked(json.dumps(options),
+                lambda: _asked({"checkpoint": "native-export"}))
+        else:
+            exported = _blender_web.export_frame(json.dumps(options))
         _mark("export:door")
         frame = json.loads(exported)
         del exported
@@ -1847,9 +1851,18 @@ class Session:
         self.document = os.path.join(self.project, relative_path)
         if not os.path.exists(self.document):
             return {"document": relative_path, "opened": False}
+        _asked({"checkpoint": "document-open"})
         _mark("open:before")
-        bpy.ops.wm.open_mainfile(filepath=self.document)
+        checkpointed_read = hasattr(_blender_web, "set_read_checkpoint")
+        if checkpointed_read:
+            _blender_web.set_read_checkpoint(lambda: _asked({"checkpoint": "file-read"}))
+        try:
+            bpy.ops.wm.open_mainfile(filepath=self.document)
+        finally:
+            if checkpointed_read:
+                _blender_web.set_read_checkpoint(None)
         _mark("open:after")
+        _asked({"checkpoint": "document-opened"})
         size = os.path.getsize(self.document)
         # THE STAGED COPY GOES ONCE BLENDER HAS READ IT. It sits in the engine's heap (WasmFS keeps
         # file data in linear memory) and nothing reads it again: the load took everything into

package/browser/worker.ts

@@ -1,3 +1,4 @@
+import { PullJob, checkpointStream } from './pull-job.mts';
 import { sendFrameValue } from './frame-stream.mts';
 /**
  * THE BLENDER IN THE TAB IS BLENDER (ARCHITECTURE-CORE, owner ruling
@@ -69,7 +70,8 @@ const pendingPresents = new Map<
 >();
 
 async function streamToTab(value: unknown): Promise<PresentAnswer> {
-  return await sendFrameValue(value, chunk => {
+  return await sendFrameValue(value, async chunk => {
+    await loadCheckpoint?.("frame-transfer");
     const id = ++presentId;
     return new Promise<PresentAnswer>((resolve, reject) => {
       pendingPresents.set(id, { resolve, reject });
@@ -85,6 +87,8 @@ function presentToTab(frame: unknown, description: unknown, capture?: CaptureReq
 }
 
 let engine: BlenderEngine | null = null;
+let loadJob: PullJob<unknown> | null = null;
+let loadCheckpoint: ((phase: string) => Promise<void>) | null = null;
 
 // ---- The session's document.
 //
@@ -263,7 +267,8 @@ async function startBlender(project: string, document?: string): Promise<unknown
   const started = await startBlenderEngine({
     project,
     log,
-    ask: async ({ frame, hold, mesh, image, piece, present, capture, saveDue }) => {
+    ask: async ({ frame, hold, mesh, image, piece, present, capture, saveDue, checkpoint }) => {
+      if (typeof checkpoint === 'string') { await loadCheckpoint?.(checkpoint); return {}; }
       if (!holder.engine) throw new Error('The Blender session presented before it started');
       // Save once after the whole command, never during a partial frame.
       if (saveDue && documentPath !== null) setDocumentDirty(true);
@@ -337,12 +342,14 @@ async function startBlender(project: string, document?: string): Promise<unknown
     },
   });
   holder.engine = started;
+  await loadCheckpoint?.("engine-ready");
   engine = started;
   // THE PROJECT'S FILES BEFORE THE SESSION'S FIRST ACT, because that act may
   // be `open_mainfile` on the document — which lives on the host's disk and is
   // not in the engine's filesystem until it is staged. Every other call stages
   // on its way in (`execute`); start had nothing to open before it did.
   if (document) await stageProjectFiles(started.files, project);
+  await loadCheckpoint?.("project-imported");
   const banner = (await started.request({
     op: 'start',
     project,
@@ -526,7 +533,7 @@ async function stageProjectFiles(files_: BlenderFiles, project: string): Promise
     const dir = path.slice(0, path.lastIndexOf('/'));
     if (dir) await files_.mkdirTree(dir);
     if (files_.writeFileStream && answer.body) {
-      await files_.writeFileStream(path, answer.body, file.size);
+      await files_.writeFileStream(path, loadCheckpoint ? checkpointStream(answer.body, () => loadCheckpoint!("file-import")) : answer.body, file.size);
     } else {
       await files_.writeFile(path, new Uint8Array(await answer.arrayBuffer()));
     }
@@ -567,8 +574,19 @@ async function listSessionFiles(files: BlenderFiles, root: string): Promise<File
 
 async function handle(request: WorkerRequest): Promise<unknown> {
   switch (request.op) {
-    case 'start':
-      return start(request.project, request.document);
+    case 'start': {
+      if (loadJob) throw new Error('The Blender load has already started');
+      loadJob = new PullJob(async checkpoint => {
+        loadCheckpoint = checkpoint;
+        const began = performance.now();
+        try { return await start(request.project, request.document); }
+        finally { loadCheckpoint = null; log('log', `@@VOLTER-LOAD totalMs=${Math.round(performance.now() - began)}`); }
+      });
+      return loadJob.step();
+    }
+    case 'load-next':
+      if (!loadJob) throw new Error('No Blender load to continue');
+      return loadJob.step(request.token);
     case 'present-result': {
       const pending = pendingPresents.get(request.id);
       pendingPresents.delete(request.id);
@@ -582,6 +600,7 @@ async function handle(request: WorkerRequest): Promise<unknown> {
       return undefined;
     }
   }
+  if (loadCheckpoint) throw new Error('The Blender load must finish before another command');
   if (!session || !projectRoot || !engine) throw new Error('The Blender session has not started');
   const files = engine.files;
   /** The session channel itself, for the requests whose answer is already the

package/package.json

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

package/wasm/BUNDLE.json

@@ -1,9 +1,9 @@
 {
   "blender": "5.2.0 LTS",
-  "source": "54e4af619a285c6d76c56ef960dc99d45aca5084",
+  "source": "9fdd05db03bf0e4aa1028607be3e113be7f98d01",
   "upstream": "fbe6228777e7d9afefcd61a413844e790ae75db7",
   "sourceRepository": "https://github.com/volter-ai/blender",
-  "sourceRecipe": "https://github.com/volter-ai/blender/blob/54e4af619a285c6d76c56ef960dc99d45aca5084/build_files/emscripten/RELEASE.md",
+  "sourceRecipe": "https://github.com/volter-ai/blender/blob/9fdd05db03bf0e4aa1028607be3e113be7f98d01/build_files/emscripten/RELEASE.md",
   "factoryEngine": "BLENDER_EEVEE",
   "files": {
     "blender_browser.js": "raw",
@@ -16,8 +16,8 @@
       "sha256": "0c63c29e7d4b1ba1fce4e94057778b0757767b25ea4f6f01d329e99351568f30"
     },
     "blender_browser.wasm": {
-      "bytes": 86332914,
-      "sha256": "15c4b7072ebc655418849da79a6fefed8bff26774e7446ade8d3a54bd6ad7a61"
+      "bytes": 86337036,
+      "sha256": "9d8cb5bd0dbb34fa7f04858fb6bc831195d0b06e8b82bb26889f3c6d807a9588"
     },
     "blender_browser.data": {
       "bytes": 52698568,
@@ -30,8 +30,8 @@
       "sha256": "0c63c29e7d4b1ba1fce4e94057778b0757767b25ea4f6f01d329e99351568f30"
     },
     "blender_browser.wasm.br": {
-      "bytes": 18601239,
-      "sha256": "8cd29a87fcce046c292c52cc62523fe0ebbd1db8f05b19503d56311ae12c84c5"
+      "bytes": 18604996,
+      "sha256": "782c1f8519851e8b901d5309d239429ecd07c4ed374adaf117214f9ac22f84c9"
     },
     "blender_browser.data.br": {
       "bytes": 8056563,
@@ -45,6 +45,6 @@
   "note": "Stoneguard c7/c14/c15 engine. Emscripten 6.0.5, Release -O3 objects and -O2 link. Portable native arm64 matrix reciprocal plus fused generic OpenSubdiv stencil and patch accumulation; bodice four-stage comparison 28/28 arrays exact. Full-scene comparison and memory scope recorded in provenance/stoneguard-memory.json. Historical battery absent; no full-battery or hosted acceptance claim.",
   "callTrampoline": "CPython 3.13.13 is compiled with PY_CALL_TRAMPOLINE for Blender CPython slot arity casts. This applies to CPython dispatch, not arbitrary indirect calls.",
   "engineIds": "The existing session registers Python render engines under CYCLES, BLENDER_EEVEE and BLENDER_WORKBENCH; the headless build permits built-in IDs to be shadowed.",
-  "exportDoor": "The source-owned bpy_web_export.cc exports Principled physical inputs, normal images, eight named UV layers and evaluated corner normals, and takes graph_materials/graph_images/graph_generated (a graph-drawn shader mix reduced to the one Principled BSDF it reaches, graph images at the door revisions with every UDIM tile, orco for deformed meshes whose graph reads Generated coordinates). A frame can defer its changed meshes and pictures (defer) for the caller to pull one at a time (export_mesh, export_image), each call freeing the previous one's columns and a picture it decoded; an undo step keeps the revisions when Blender kept the depsgraph (session_undo); Blender's CPU subdivision descriptor is released once a mesh is read; the memory door reports malloc in-use and free. Datablock revisions are keyed by session_uid. writefile.cc writes one copy of the document per save in the browser build. CPU evaluators adopt stencil tables without cloning; browser subdivision descriptors are released immediately after CPU tessellation/deformation. Native evaluated corner triangles accompany corner normals. Consumed local conversion stencils are released before later UV channels are constructed.",
+  "exportDoor": "The source-owned bpy_web_export.cc exports Principled physical inputs, normal images, eight named UV layers and evaluated corner normals, and takes graph_materials/graph_images/graph_generated (a graph-drawn shader mix reduced to the one Principled BSDF it reaches, graph images at the door revisions with every UDIM tile, orco for deformed meshes whose graph reads Generated coordinates). A frame can defer its changed meshes and pictures (defer) for the caller to pull one at a time (export_mesh, export_image), each call freeing the previous one's columns and a picture it decoded; an undo step keeps the revisions when Blender kept the depsgraph (session_undo); Blender's CPU subdivision descriptor is released once a mesh is read; the memory door reports malloc in-use and free. Datablock revisions are keyed by session_uid. writefile.cc writes one copy of the document per save in the browser build. CPU evaluators adopt stencil tables without cloning; browser subdivision descriptors are released immediately after CPU tessellation/deformation. Native evaluated corner triangles accompany corner normals. Consumed local conversion stencils are released before later UV channels are constructed. Caller-thread file-read, evaluated-object and subdivision checkpoints provide backpressure for resumable startup. Shared geometry revisions advance once per frame. Existing synchronous export remains available.",
   "preloadedPayload": "releasePreloadedFileData releases the JS preload buffer after session ready. The measured working payload exclusions are retained."
 }