@volter/blender-engine 0.1.7 → 0.1.8

package/browser/blender-emscripten-engine.mts

@@ -133,9 +133,37 @@ function moduleFiles(module: BlenderModule): BlenderFiles {
   };
 }
 
+/**
+ * BLENDER'S ARTIFACTS ARE FETCHED ONCE PER BUILD. The wasm (86 MB decoded), the
+ * `.data` package (53 MB) and the Essentials payload are immutable for a build,
+ * and the page keeps them in Cache Storage under the digest the artifact door
+ * reports, so a later open reads them at the browser's own speed instead of
+ * from the editor's server. Measured in the browser substrate, where that
+ * server runs in the tab: the three took 7.2 s per open (4.2 s for the wasm
+ * alone), about half of it decoding their brotli. A file the door gives no
+ * digest for is fetched as it always was.
+ */
+const ARTIFACT_CACHE = 'volter-blender-artifacts';
+
+async function cachedArtifact(file: string, digest: string | undefined): Promise<Response> {
+  const url = artifactUrl(file);
+  if (!digest || typeof caches === 'undefined') return 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 (!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());
+  return kept;
+}
+
 export async function startEmscriptenBlenderEngine(
   options: BlenderEngineOptions,
-  _status: BlenderArtifactStatus,
+  status: BlenderArtifactStatus,
 ): Promise<BlenderEngine> {
   if (!self.crossOriginIsolated)
     throw new Error(
@@ -144,7 +172,17 @@ export async function startEmscriptenBlenderEngine(
         'every response). This worker reports crossOriginIsolated=false.',
     );
   const glueUrl = artifactUrl('blender_browser.js');
-  const factory = await loadFactory(glueUrl);
+  const digests = status.digests ?? {};
+  // 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) => {
+      if (!response.ok) throw new Error(`blender_browser.data: HTTP ${response.status}`);
+      return response.arrayBuffer();
+    }),
+  ]);
+  let bootError: unknown = null;
   const started = performance.now();
   let readyLine: string | null = null;
   // BLENDER'S OWN STREAMS ARE PAGE OUTPUT, NOT EDITOR-CONSOLE CONDITIONS.
@@ -164,6 +202,16 @@ export async function startEmscriptenBlenderEngine(
   const module = await 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 cachedArtifact('blender_browser.wasm', digests['blender_browser.wasm']);
+        if (!response.ok) throw new Error(`blender_browser.wasm: HTTP ${response.status}`);
+        const { instance, module: compiled } = await WebAssembly.instantiateStreaming(response, imports);
+        receive(instance, compiled);
+      })().catch((error: unknown) => { bootError = error; });
+      return {};
+    },
     // The pthreads load the SAME patched glue this worker just evaluated.
     mainScriptUrlOrBlob: glueUrl,
     print: (text: string) => say('log', text),
@@ -209,7 +257,10 @@ export async function startEmscriptenBlenderEngine(
   });
   // `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) await sleep(5);
+  while (readyLine === null) {
+    if (bootError) throw bootError instanceof Error ? bootError : new Error(String(bootError));
+    await sleep(5);
+  }
   const bootMs = performance.now() - started;
   const banner = JSON.parse(readyLine) as { blender: string; engines: string[] };
 
@@ -268,7 +319,7 @@ export async function startEmscriptenBlenderEngine(
 
   const files = moduleFiles(module);
   FS.chmod('/bw/datafiles', 0o755);
-  await mountEssentials(files);
+  await mountEssentials(files, digests['essentials.bin']);
   const { request } = openSessionChannel(files, options);
 
   return {
@@ -293,9 +344,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): Promise<void> {
+async function mountEssentials(files: BlenderFiles, digest: string | undefined): Promise<void> {
   const [indexResponse, payloadResponse] = await Promise.all([
-    fetch(artifactUrl('essentials.json')), fetch(artifactUrl('essentials.bin')),
+    fetch(artifactUrl('essentials.json')), cachedArtifact('essentials.bin', digest),
   ]);
   if (!indexResponse.ok || !payloadResponse.ok)
     throw new Error(`Blender Essentials assets are missing (${indexResponse.status}/${payloadResponse.status})`);

package/browser/blender-engine.mts

@@ -179,6 +179,8 @@ export interface BlenderArtifactStatus {
   encoded: Record<string, 'br'>;
   /** Why it is unavailable, named. Empty when it is available. */
   missing: string[];
+  /** Emscripten: each file's SHA-256 as it decodes, the key a page keeps it under. */
+  digests?: Record<string, string>;
   /** WALI only: the `sha256-` SRI of `blender.wasm`, which the program loader
    *  requires for any non-blob URL. */
   integrity?: string;

package/browser/runtime.ts

@@ -434,10 +434,10 @@ export class BlenderRuntime {
     if (this.#terminated) return Promise.resolve();
     if (this.#stopping) return this.#stopping;
     this.#stopping = (async () => {
-      if (this.#started) {
-        await this.#started;
-        await this.#request({ op: 'flush-document' }, true);
-      }
+      // A start that failed opened no document, so there is nothing to flush: its stale
+      // rejection must not refuse every later close.
+      const started = this.#started ? await this.#started.then(() => true, () => false) : false;
+      if (started) await this.#request({ op: 'flush-document' }, true);
       this.terminate();
     })().catch(error => {
       this.#stopping = null;
@@ -470,7 +470,7 @@ export class BlenderRuntime {
    * A `present` is not counted separately — the worker only presents from
    * inside a call this meter is already holding open, and the page-side cost of
    * displaying the frame is main-thread time, which is the long-task observer's
-   * subject (`packages/editor/src/blender-tab-metrics.ts`).
+   * subject (the host's `worker-call-metrics.ts`).
    */
   metrics(now: number = performance.now()): BlenderCallMetrics {
     let oldest: number | null = null;

package/browser/session.py

@@ -1343,16 +1343,15 @@ class Session:
             # its value also depends on native undo initialization/checkpoints.
             "dirty": bool(bpy.data.is_dirty),
         }
-        # A PRESENT IS WHAT LEAVES THE DOCUMENT STALE, and the predicate is the
-        # present itself rather than what the frame shipped. `columns`/`images`
-        # above count BYTES THAT CROSSED, which is a different question: a MOVE
-        # ships zero columns (the comment above says so) and a DELETION ships
-        # nothing at all, yet both are changes a document that loses them is
-        # wrong. The cost this predicate could waste is bounded by the tab's
-        # one-save-per-idle-second debounce, and `save_document` still asks
-        # Blender whether anything actually changed before it writes.
-        if self.document is not None:
-            self.save_due = True
+        # A PRESENT DOES NOT MAKE THE DOCUMENT STALE; a request that can change
+        # the model does (`mark_changed`, from `dispatch`). The predicate was the
+        # present itself, and a present also runs with no change behind it --
+        # opening the document, rebinding its view. MEASURED 2026-09-24 on
+        # `arena`: opening a Model document and doing nothing rewrote its
+        # `.blend` with 556 bytes changed, so a file a person only looked at read
+        # as modified. `columns`/`images` above stay the wrong question for the
+        # same reason as before: a MOVE ships zero columns and a DELETION ships
+        # nothing, and both come from a request `mark_changed` sees.
         for key, mesh in frame["meshes"].items():
             self._known["mesh:" + key] = mesh["revision"]
         for name, image in frame["images"].items():
@@ -1540,6 +1539,12 @@ class Session:
                 "objects": len(bpy.data.objects),
                 "size": os.path.getsize(self.document)}
 
+    def mark_changed(self):
+        """A request that can change the model ran: the next present carries
+        `saveDue`, and the tab saves after an idle second."""
+        if self.document is not None:
+            self.save_due = True
+
     def save_document(self):
         """Write the document -- Blender's own format, by Blender's own operator.
 
@@ -1625,11 +1630,11 @@ class Session:
         #
         # It was briefly used to skip a redundant write, and it froze the
         # document after its first save -- a reopened session could model all
-        # day and never write again. The predicate is `_present`'s instead: a
-        # present is what leaves the document stale. Coarser (a read-only
-        # script rewrites the file once), bounded by the tab's idle-second
-        # debounce, and it cannot miss a change. The reading still rides in the
-        # answer, as an instrument.
+        # day and never write again. The predicate is `mark_changed`'s instead:
+        # a request that can change the model ran. Coarser than a diff (a
+        # read-only script rewrites the file once), bounded by the tab's
+        # idle-second debounce, and it cannot miss a change. The reading still
+        # rides in the answer, as an instrument.
         dirty = bool(bpy.data.is_dirty)
         existed = os.path.exists(self.document)
         directory = os.path.dirname(self.document)
@@ -4640,6 +4645,7 @@ def dispatch(request):
     if op == "history-step":
         if request["direction"] not in ("undo", "redo"):
             raise ValueError("Unknown history direction")
+        SESSION.mark_changed()
         return HISTORY.move(request["token"], request["direction"])
     mutation = op in ("execute", "rna-set", "outliner-set") and request.get("history", True)
     if not mutation:
@@ -4675,6 +4681,7 @@ def _dispatch(request):
         # Arbitrary Python can partially mutate before throwing. Once execution
         # starts it needs a checkpoint; capability refusals above do not.
         HISTORY.changed()
+        SESSION.mark_changed()
         answer = execute(request["code"])
         # Every mutation is presented, the rule: the Model
         # document is what the agent is looking at.
@@ -4723,6 +4730,7 @@ def _dispatch(request):
     if op == "outliner":
         return rna_outliner(request.get("selected"))
     if op == "outliner-set":
+        SESSION.mark_changed()
         answer = outliner_set(request["path"], request["column"], request["value"])
         # A COLUMN IS A WRITE, and a write presents -- the same rule `rna-set`
         # follows: hiding an object in the Outliner must change what the
@@ -4743,6 +4751,7 @@ def _dispatch(request):
                  "showing the state before it: " + repr(thrown))
         return answer
     if op == "rna-set":
+        SESSION.mark_changed()
         answer = rna_set(request["path"], request["property"], request["value"],
                          request.get("index"))
         # A WRITE IS PRESENTED, exactly as `execute` presents: the Model

package/browser/three/blender-graph-material.ts

@@ -143,6 +143,11 @@ export function graphProgramKey(material: THREE.MeshPhysicalMaterial): string {
   return `${binding.compiled.key}|${JSON.stringify(binding.channels)}`;
 }
 
+/** The UV channels the material's graph reads on the current draw. */
+export function graphUvChannels(material: THREE.MeshPhysicalMaterial): number[] {
+  return Object.values(bindings.get(material)?.channels ?? {});
+}
+
 /** The channel each named UV layer is in on `geometry` (a layer the mesh
  *  lacks reads zeros from channel 9, Blender's missing attribute). */
 function channelsFor(compiled: CompiledGraph, geometry: THREE.BufferGeometry): Record<string, number> {
@@ -305,7 +310,6 @@ export function applyGraphShader(material: THREE.MeshPhysicalMaterial, shader: T
   const {compiled, channels} = binding;
   Object.assign(shader.uniforms, binding.uniforms, {blenderViewport: {value: viewport}});
   const attribute = (channel: number) => (channel === 0 ? 'uv' : `uv${channel}`);
-  const guards = [1, 2, 3].map(i => `#ifndef USE_UV${i}\nattribute vec2 uv${i};\n#endif`).join('\n');
   const varyings = `varying vec3 vBlenderObjectPosition;
 varying vec3 vBlenderObjectNormal;
 varying vec3 vBlenderWorldPosition;
@@ -314,7 +318,7 @@ varying vec3 vBlenderOrco;
 ${compiled.attributes.map(n => `varying vec4 ${attributeVarying(n)};`).join('\n')}
 ${compiled.uvs.map(n => `varying vec2 ${uvVarying(n)};`).join('\n')}`;
   const attributes = compiled.attributes.map(n => `attribute vec4 ${graphAttributeName(n)};`).join('\n');
-  shader.vertexShader = `${guards}\nattribute vec3 blenderOrco;\n${attributes}\n${varyings}\n${shader.vertexShader}`.replace(
+  shader.vertexShader = `attribute vec3 blenderOrco;\n${attributes}\n${varyings}\n${shader.vertexShader}`.replace(
     '#include <project_vertex>',
     `vBlenderObjectPosition = transformed;
 vBlenderObjectNormal = objectNormal;

package/browser/three/blender-physical-material.ts

@@ -4,7 +4,7 @@
  * that MeshPhysicalMaterial does not expose as properties. */
 import * as THREE from 'three';
 import {z} from 'zod';
-import {applyGraphShader, bindGraphDraw, graphProgramKey, setGraphViewport} from './blender-graph-material';
+import {applyGraphShader, bindGraphDraw, graphProgramKey, graphUvChannels, setGraphViewport} from './blender-graph-material';
 import {bindNamedUvChannels} from './blender-texture-samplers';
 
 const scalar = z.number().finite();
@@ -85,9 +85,16 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
       setGraphViewport(renderer);
     };
     material.onBeforeCompile = shader => {
-      // Three declares channels 0..3. Blender has eight named UV maps in
-      // addition to the default channel; only the used attributes survive GLSL.
-      shader.vertexShader = [4, 5, 6, 7, 8, 9].map(i => `attribute vec2 uv${i};`).join('\n') + '\n' + shader.vertexShader;
+      // Three declares channels 1..3 only for its own maps, and none past 3.
+      // Blender has eight named UV maps beside the default channel (9 is the
+      // missing layer's zeros). Declare only the channels this draw reads: a
+      // driver may count every declared attribute against its sixteen, and
+      // six idle ones leave a graph with a few attributes no room.
+      const read = new Set([material.map, material.roughnessMap, material.normalMap]
+        .flatMap(texture => (texture ? [texture.channel] : [])).concat(graphUvChannels(material)));
+      shader.vertexShader = [...read].filter(i => i > 0).sort((a, b) => a - b)
+        .map(i => (i <= 3 ? `#ifndef USE_UV${i}\nattribute vec2 uv${i};\n#endif` : `attribute vec2 uv${i};`))
+        .join('\n') + '\n' + shader.vertexShader;
       Object.assign(shader.uniforms, held);
       shader.fragmentShader = `uniform float blenderCoatIor;
         uniform vec3 blenderWorldExtinction;

package/browser/worker.ts

@@ -458,6 +458,9 @@ async function handle(request: WorkerRequest): Promise<unknown> {
   const ask = engine.request.bind(engine);
   switch (request.op) {
     case 'flush-document':
+      // A flush lands what is pending; a document nothing changed stays the
+      // file it was opened from.
+      if (!documentDirty) return { saved: false };
       await saveDocument();
       return { saved: true };
     case 'history-begin':

package/package.json

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