@volter/blender-engine 0.1.61 → 0.1.63

package/browser/blender-emscripten-engine.mts

@@ -27,6 +27,7 @@
  *    `session.py` chmods its own root as its first act.
  */
 
+import { checkpointStream } from './pull-job.mts';
 import { writeStreamedFile, type StreamFileSystem } from './stream-file.mts';
 import {
   artifactUrl,
@@ -149,14 +150,17 @@ function moduleFiles(module: BlenderModule): BlenderFiles {
  */
 const ARTIFACT_CACHE = 'volter-blender-artifacts';
 
-async function cachedArtifact(file: string, digest: string | undefined): Promise<Response> {
+async function cachedArtifact(file: string, digest: string | undefined, checkpoint: () => Promise<void>): Promise<Response> {
+  const bounded = (response: Response): Response => response.ok && response.body
+    ? new Response(checkpointStream(response.body, checkpoint), { status: response.status, headers: response.headers })
+    : response;
   const url = artifactUrl(file);
-  if (!digest || typeof caches === 'undefined') return fetch(url);
+  if (!digest || typeof caches === 'undefined') return bounded(await fetch(url));
   const key = `${url}?sha256=${digest}`;
   const cache = await caches.open(ARTIFACT_CACHE);
   const hit = await cache.match(key);
-  if (hit) return hit;
-  const response = await fetch(url);
+  if (hit) return bounded(hit);
+  const response = bounded(await fetch(url));
   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);
@@ -177,15 +181,18 @@ export async function startEmscriptenBlenderEngine(
     );
   const glueUrl = artifactUrl('blender_browser.js');
   const digests = status.digests ?? {};
+  const checkpoint = async (phase: string): Promise<void> => { await options.ask({ checkpoint: phase }); };
+  const artifact = (file: string) => cachedArtifact(file, digests[file], () => checkpoint(`artifact/${file}`));
   // 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([
     loadFactory(glueUrl),
-    cachedArtifact('blender_browser.data', digests['blender_browser.data']).then(async (response) => {
+    artifact('blender_browser.data').then(async (response) => {
       if (!response.ok) throw new Error(`blender_browser.data: HTTP ${response.status}`);
       return response.arrayBuffer();
     }),
   ]);
+  await checkpoint('runtime-package-ready');
   let bootError: unknown = null;
   const started = performance.now();
   let readyLine: string | null = null;
@@ -221,9 +228,10 @@ export async function startEmscriptenBlenderEngine(
     getPreloadedPackage: () => preloaded,
     instantiateWasm: (imports: WebAssembly.Imports, receive: (instance: WebAssembly.Instance, module: WebAssembly.Module) => void) => {
       void (async () => {
-        const response = await cachedArtifact('blender_browser.wasm', digests['blender_browser.wasm']);
+        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);
+        await checkpoint('wasm-instantiated');
         receive(instance, compiled);
       })().catch((error: unknown) => { bootError = error; });
       return {};
@@ -273,6 +281,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.
   while (readyLine === null) {
@@ -337,7 +346,8 @@ export async function startEmscriptenBlenderEngine(
 
   const files = moduleFiles(module);
   FS.chmod('/bw/datafiles', 0o755);
-  await mountEssentials(files, digests['essentials.bin']);
+  await checkpoint('python-ready');
+  await mountEssentials(files, digests['essentials.bin'], checkpoint);
   const { request } = openSessionChannel(files, options);
 
   return {
@@ -364,9 +374,9 @@ 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. */
-async function mountEssentials(files: BlenderFiles, digest: string | undefined): Promise<void> {
+async function mountEssentials(files: BlenderFiles, digest: string | undefined, checkpoint: (phase: string) => Promise<void>): Promise<void> {
   const [indexResponse, payloadResponse] = await Promise.all([
-    fetch(artifactUrl('essentials.json')), cachedArtifact('essentials.bin', digest),
+    fetch(artifactUrl('essentials.json')), 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})`);
@@ -380,6 +390,7 @@ async function mountEssentials(files: BlenderFiles, digest: string | undefined):
   if (payload.byteLength !== index.bytes || hash !== index.sha256)
     throw new Error('Blender Essentials payload does not match its source manifest');
   for (const file of index.files) {
+    await checkpoint('essentials-file');
     if (!file.path || file.path.includes('\\') || file.path.split('/').some(p => !p || p === '.' || p === '..') ||
         !Number.isInteger(file.offset) || !Number.isInteger(file.bytes) ||
         file.offset < 0 || file.bytes < 0 || file.offset + file.bytes > payload.byteLength)

package/browser/blender-engine.mts

@@ -258,6 +258,7 @@ export async function artifactStatus(): Promise<BlenderArtifactStatus> {
  */
 export async function startBlenderEngine(options: BlenderEngineOptions): Promise<BlenderEngine> {
   const status = await artifactStatus();
+  await options.ask({ checkpoint: 'artifact-status' });
   if (!status.available)
     throw new Error(
       `The headless Blender WebAssembly build is not served by this editor: ${status.missing.join('; ')}`,

package/browser/pull-job.mts

@@ -1,7 +1,9 @@
 /** 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 };
+let nextJob = 0;
 export class PullJob<T> {
+  private readonly job = ++nextJob;
   private started = false;
   private finished = false;
   private sequence = 0;
@@ -17,7 +19,7 @@ export class PullJob<T> {
       this.started = true;
       void Promise.resolve().then(() => this.work(phase => new Promise<void>(resolve => {
         this.resume = resolve;
-        this.expected = `load:${++this.sequence}`;
+        this.expected = `load:${this.job}:${++this.sequence}`;
         const waiter = this.waiter!; this.waiter = null;
         waiter.resolve({ load: 'continue', token: this.expected, phase });
       }))).then(value => {

package/browser/runtime.ts

@@ -159,7 +159,7 @@ export class BlenderRuntime {
   #terminated = false;
   #dirty = false;
   readonly #beforeUnload = (event: BeforeUnloadEvent): void => {
-    if (!this.#dirty && this.#pending.size === 0) return;
+    if (!this.#dirty && this.#acceptedRequests === 0) return;
     event.preventDefault();
     event.returnValue = '';
   };
@@ -219,6 +219,8 @@ export class BlenderRuntime {
       for (const id of [...this.#pending.keys()]) this.#settled(id);
       for (const pending of this.#pending.values()) pending.reject(error);
       this.#pending.clear();
+      // Queued logical operations must reject too; this worker cannot answer them.
+      this.terminate();
     };
   }
 
@@ -259,7 +261,7 @@ export class BlenderRuntime {
       );
     this.#project = project;
     this.#document ??= document ?? 'models/model.blend';
-    this.#started ??= this.#load({
+    this.#started ??= this.#request({
       op: 'start',
       project,
       ...(document === undefined ? {} : { document }),
@@ -267,15 +269,6 @@ 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') {
-      this.#loadBoundary = result.phase;
-      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(
@@ -566,9 +559,32 @@ export class BlenderRuntime {
       this.#lastCallWindow = { start: started, end: started + elapsed };
   }
 
+  #acceptedRequests = 0;
+  #requestTail: Promise<void> = Promise.resolve();
   #request(request: Request, shutdown = false): Promise<unknown> {
     if (this.#terminated || (this.#stopping && !shutdown))
       return Promise.reject(new Error('The Blender session is stopping or terminated'));
+    const began = performance.now();
+    this.#acceptedRequests++;
+    const answer = this.#requestTail.then(async () => {
+      this.#loadBoundary = request.op;
+      let result = await this.#wireRequest(request) as PullResult<unknown>;
+      while (result?.load === 'continue') {
+        this.#loadBoundary = result.phase;
+        result = await this.#wireRequest({ op: 'load-next', token: result.token }) as PullResult<unknown>;
+      }
+      return result?.load === 'done' ? result.value : result;
+    }).finally(() => {
+      this.#acceptedRequests--;
+      const totalMs = Math.round(performance.now() - began);
+      try { if (totalMs >= 1000) this.#options.log?.('log', `@@VOLTER-WORK op=${request.op} totalMs=${totalMs}`); } catch { /* diagnostics cannot poison the queue */ }
+    });
+    this.#requestTail = answer.then(() => {}, () => {});
+    return answer;
+  }
+
+  #wireRequest(request: Request): Promise<unknown> {
+    if (this.#terminated) return Promise.reject(new Error('The Blender session is terminated'));
     const id = ++this.#nextId;
     return new Promise((resolve, reject) => {
       this.#pending.set(id, { resolve, reject });

package/browser/session.py

@@ -4421,8 +4421,11 @@ def rna_rig(object_name=None):
         subjects = [obj for obj in bpy.context.view_layer.objects
                     if obj.type == "MESH" and obj.data is not None
                     and obj.find_armature() is not None]
-    return {"frame": scene_frame, "named": object_name,
-            "rigs": [_rig_of(obj) for obj in subjects]}
+    rigs = []
+    for obj in subjects:
+        _asked({"checkpoint": "rig-object"})
+        rigs.append(_rig_of(obj))
+    return {"frame": scene_frame, "named": object_name, "rigs": rigs}
 
 
 def _rig_of(obj):
@@ -4506,7 +4509,11 @@ def _rig_of(obj):
     truncated = 0
     unweighted = 0
     most = 0
+    checkpoint_at = time.monotonic()
     for i, vertex in enumerate(mesh.vertices):
+        if i % 1024 == 0 and time.monotonic() - checkpoint_at >= 0.05:
+            _asked({"checkpoint": "rig-weights"})
+            checkpoint_at = time.monotonic()
         pairs = []
         for element in vertex.groups:
             bone = group_to_bone.get(int(element.group))

package/browser/worker.ts

@@ -573,17 +573,22 @@ async function listSessionFiles(files: BlenderFiles, root: string): Promise<File
   return out;
 }
 
+function pullWork(label: string, work: () => Promise<unknown>): Promise<unknown> {
+  if (loadCheckpoint) throw new Error('The current Blender operation must finish first');
+  loadJob = new PullJob(async checkpoint => {
+    loadCheckpoint = checkpoint;
+    const began = performance.now();
+    try { return await work(); }
+    finally { loadCheckpoint = null; log('log', `@@VOLTER-WORK op=${label} totalMs=${Math.round(performance.now() - began)}`); }
+  });
+  return loadJob.step();
+}
+
 async function handle(request: WorkerRequest): Promise<unknown> {
   switch (request.op) {
     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();
+      return pullWork('start', () => start(request.project, request.document));
     }
     case 'load-next':
       if (!loadJob) throw new Error('No Blender load to continue');
@@ -632,7 +637,7 @@ async function handle(request: WorkerRequest): Promise<unknown> {
     case 'present':
       // Straight through to `session.py`'s own `present` op — the worker adds
       // nothing, and a capture-less present answers `{ presented, revision }`.
-      return ask({ op: 'present' });
+      return pullWork('present', () => ask({ op: 'present' }));
     case 'scene-info':
       return session.sceneInfo();
     case 'object-info':
@@ -698,10 +703,10 @@ async function handle(request: WorkerRequest): Promise<unknown> {
     // because `collection` crossed `runtime.ts` and `session.py` and never
     // this switch, with no error anywhere.
     case 'rig':
-      return ask({
+      return pullWork('rig', () => ask({
         op: 'rig',
         ...(request.object === undefined ? {} : { object: request.object }),
-      });
+      }));
     case 'action-clip':
       return ask({
         op: 'action-clip',
@@ -791,7 +796,7 @@ self.onmessage = (event: MessageEvent<WorkerRequest>) => {
 async function answerRequest(request: WorkerRequest): Promise<void> {
   try {
     const result = await handle(request);
-    if (documentDirty) await saveDocument();
+    if (!loadCheckpoint && documentDirty) await saveDocument();
     await reportHistory();
     post({ id: request.id, result });
   } catch (error) {
@@ -811,7 +816,7 @@ async function answerRequest(request: WorkerRequest): Promise<void> {
 }
 
 async function reportHistory(): Promise<void> {
-  if (!engine || !session) return;
+  if (loadCheckpoint || !engine || !session) return;
   const entries = await engine.request({ op: 'history-events' }) as import('./protocol').NativeHistoryEntry[];
   if (entries.length) post({ op: 'history', entries });
 }

package/package.json

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