@volter/blender-engine 0.1.44 → 0.1.46

package/browser/document-chunks.mts

@@ -0,0 +1,72 @@
+/**
+ * A saved `.blend` cut into content-defined chunks, the unit a document save travels in
+ * (`editor-blender/serving/blender-routes.ts`, `/__editor/blender-document`).
+ *
+ * WHY CONTENT-DEFINED. A save rewrites the whole file, but an edit changes little of it:
+ * MEASURED 2026-09-29, native Blender 5.2 on the Stoneguard bridge, one object moved between two
+ * saves changed 1 of 475 one-MiB chunks of a 497 MB file. Fixed offsets would keep that only while
+ * no block changes size; an edit that grows a mesh would shift every chunk after it. Cutting where
+ * the bytes themselves say (a gear hash, as FastCDC does) re-aligns right after the change, so only
+ * the chunks around it are new.
+ *
+ * The bounds are the transport's: no chunk above {@link CHUNK_MAX}, which the server refuses.
+ */
+
+export const CHUNK_MIN = 256 * 1024;
+export const CHUNK_MAX = 4 * 1024 * 1024;
+/** 20 bits: a cut about every MiB past the minimum. */
+const CUT_MASK = (1 << 20) - 1;
+
+/** The gear table: 256 fixed pseudo-random words (xorshift32 from a fixed seed), so every page
+ *  cuts the same bytes the same way. */
+const GEAR = (() => {
+  const table = new Uint32Array(256);
+  let state = 0x9e3779b9;
+  for (let index = 0; index < 256; index += 1) {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    table[index] = state >>> 0;
+  }
+  return table;
+})();
+
+/** The end offsets of each chunk of `bytes`. */
+export function chunkBoundaries(bytes: Uint8Array): number[] {
+  const ends: number[] = [];
+  let start = 0;
+  while (start < bytes.length) {
+    const limit = Math.min(bytes.length, start + CHUNK_MAX);
+    let end = limit;
+    let hash = 0;
+    for (let at = start + Math.min(CHUNK_MIN, limit - start); at < limit; at += 1) {
+      hash = ((hash << 1) + GEAR[bytes[at]!]!) >>> 0;
+      if ((hash & CUT_MASK) === 0) {
+        end = at + 1;
+        break;
+      }
+    }
+    ends.push(end);
+    start = end;
+  }
+  return ends;
+}
+
+export interface DocumentChunk {
+  readonly hash: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+/** Each chunk of `bytes` with its SHA-256, in file order. */
+export async function documentChunks(bytes: Uint8Array): Promise<DocumentChunk[]> {
+  const chunks: DocumentChunk[] = [];
+  let start = 0;
+  for (const end of chunkBoundaries(bytes)) {
+    // `slice`, not `subarray`: WebCrypto refuses a view of shared memory, which an engine read may be.
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes.slice(start, end)));
+    chunks.push({ hash: Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join(''), start, end });
+    start = end;
+  }
+  return chunks;
+}

package/browser/runtime.ts

@@ -225,6 +225,12 @@ export class BlenderRuntime {
     return this.#document;
   }
 
+  /** Blender's last lines of output (the worker's log, newest last): what a status read shows,
+   *  including each document save's size and phase timings (`@@VOLTER-DOCUMENT`). */
+  get lastOutput(): readonly string[] {
+    return [...this.#lastLines];
+  }
+
   /** Idempotent: the first call boots Blender at `project`'s
    *  absolute path; later calls await it (a different path is refused).
    *

package/browser/worker.ts

@@ -25,7 +25,8 @@
  * So the session marks a present `saveDue`, this file finishes the command,
  * calls `save-document` as an ordinary request (which Python's loop
  * picks up BETWEEN calls, never mid-call), and carries the bytes to the
- * project through `/__editor/blender-document` BEFORE acknowledging the edit.
+ * project through `/__editor/blender-document` BEFORE acknowledging the edit —
+ * as a delta: the chunks the server does not hold (`document-chunks.mts`).
  *
  * WHY THE CARRY IS NOT THE MIRROR'S JOB (`volter blender-mcp`, class Mirror):
  * the Mirror is pull-based and runs only after an `execute_blender_code`, so
@@ -38,6 +39,7 @@
 
 import { 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';
 
 const post = (reply: WorkerReply) => (self as unknown as Worker).postMessage(reply);
@@ -196,9 +198,19 @@ function setDocumentDirty(dirty: boolean): void {
 async function saveDocument(): Promise<void> {
   if (!engine || documentPath === null) return;
   const relative = documentPath;
+  // Each phase's milliseconds, reported with the save: on a large document the save is the
+  // edit's cost, and where it goes differs by host (a tab-served project runs the server here).
+  const ms: Record<string, number> = {};
+  let mark = performance.now();
+  const lap = (phase: string) => {
+    const now = performance.now();
+    ms[phase] = Math.round(now - mark);
+    mark = now;
+  };
   let answer: { saved?: boolean; path?: string; size?: number };
   try {
     answer = (await engine.request({ op: 'save-document' })) as typeof answer;
+    lap('save');
   } catch (error) {
     // A document that cannot be written is the session's work at risk, so it
     // is a named condition in the editor's console, not a debug line.
@@ -209,6 +221,7 @@ async function saveDocument(): Promise<void> {
   let bytes: Uint8Array;
   try {
     bytes = await engine.files.readFile(answer.path);
+    lap('read');
   } catch (error) {
     throw new Error(`The Blender document ${relative} could not be read back out of the engine: ${describeThrown(error)}`);
   }
@@ -217,21 +230,48 @@ async function saveDocument(): Promise<void> {
   // call re-fetch the whole document over the session's own save, and would
   // hide it from `list-files` (which lists only what the SESSION owns).
   staged.delete(answer.path);
+  let sent = 0;
   try {
-    const posted = await fetch(`/__editor/blender-document?path=${encodeURIComponent(relative)}`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/octet-stream' },
-      body: new Blob([bytes as BlobPart]),
-    });
-    if (!posted.ok) {
-      const said = await posted.text().catch(() => '');
-      throw new Error(`HTTP ${posted.status} ${said}`);
+    const chunks = await documentChunks(bytes);
+    lap('chunk');
+    const query = `path=${encodeURIComponent(relative)}`;
+    const manifest = JSON.stringify({ chunks: chunks.map(({ hash, start, end }) => [hash, end - start]) });
+    // The manifest asks for what the server lacks; after those are sent it commits. A second
+    // refusal can only be a file changed underneath between the two, so a third ask is the bound.
+    for (let round = 0; ; round += 1) {
+      const posted = await fetch(`/__editor/blender-document?${query}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: manifest,
+      });
+      const said = (await posted.json().catch(() => null)) as
+        | { ok?: boolean; missing?: string[]; error?: string; ms?: Record<string, number> }
+        | null;
+      lap(`manifest${round}`);
+      if (!posted.ok) throw new Error(`HTTP ${posted.status} ${said?.error ?? ''}`);
+      if (said?.ok) {
+        for (const [phase, value] of Object.entries(said.ms ?? {})) ms[`server.${phase}`] = value;
+        break;
+      }
+      if (round === 2 || !Array.isArray(said?.missing)) throw new Error(`the server still lacks ${said?.missing?.length ?? '?'} chunks`);
+      const wanted = new Set(said.missing);
+      for (const chunk of chunks) {
+        if (!wanted.delete(chunk.hash)) continue;
+        const part = await fetch(`/__editor/blender-document-chunk?${query}&hash=${chunk.hash}`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/octet-stream' },
+          body: new Blob([bytes.subarray(chunk.start, chunk.end) as BlobPart]),
+        });
+        if (!part.ok) throw new Error(`HTTP ${part.status} ${await part.text().catch(() => '')}`);
+        sent += chunk.end - chunk.start;
+      }
+      lap(`send${round}`);
     }
   } catch (error) {
     throw new Error(`The Blender document ${relative} was not written to the project: ${describeThrown(error)}`);
   }
   setDocumentDirty(false);
-  log('log', `@@VOLTER-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length })}`);
+  log('log', `@@VOLTER-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length, sent, ms })}`);
 }
 
 async function startBlender(project: string, document?: 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.44",
+  "version": "0.1.46",
   "publishConfig": {
     "access": "public"
   },