@volter/blender-engine 0.1.53 → 0.1.55

package/browser/frame-stream.mts

@@ -0,0 +1,71 @@
+/** Bounded, acknowledged frame transport. One value (one mesh/image or the
+ * metadata frame) is assembled at a time; SHA-256 covers every chunk, including
+ * the metadata. Nothing is applied before all of that value has been verified. */
+export const FRAME_CHUNK_BYTES = 1024 * 1024;
+export type FrameChunk =
+  | { kind: 'begin'; lengths: number[] }
+  | { kind: 'bytes'; slot: number; offset: number; bytes: Uint8Array; sha256: string }
+  | { kind: 'end' };
+const arrays = { Uint8Array, Int8Array, Uint16Array, Int16Array, Uint32Array, Int32Array, Float32Array, Float64Array };
+const digest = async (bytes: Uint8Array): Promise<string> =>
+  Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes as Uint8Array<ArrayBuffer>)), b => b.toString(16).padStart(2, '0')).join('');
+
+export async function sendFrameValue(value: unknown, send: (chunk: FrameChunk) => Promise<unknown>): Promise<unknown> {
+  const buffers: Uint8Array[] = [];
+  const json = JSON.stringify(value, (_key, item: unknown) => {
+    if (!ArrayBuffer.isView(item)) return item;
+    const type = item.constructor.name;
+    if (!Object.hasOwn(arrays, type)) throw new Error(`Unsupported frame column ${type}`);
+    buffers.push(new Uint8Array(item.buffer, item.byteOffset, item.byteLength));
+    return { $frameColumn: buffers.length, type };
+  });
+  buffers.unshift(new TextEncoder().encode(json));
+  await send({ kind: 'begin', lengths: buffers.map(b => b.byteLength) });
+  for (const [slot, buffer] of buffers.entries()) {
+    for (let offset = 0; offset < buffer.byteLength; offset += FRAME_CHUNK_BYTES) {
+      const bytes = buffer.slice(offset, offset + FRAME_CHUNK_BYTES);
+      const sha256 = await digest(bytes);
+      await send({ kind: 'bytes', slot, offset, bytes, sha256 });
+    }
+  }
+  return send({ kind: 'end' });
+}
+
+export class FrameStreamReader {
+  private buffers: Uint8Array[] | null = null;
+  private offsets: number[] = [];
+  reset(): void { this.buffers = null; this.offsets = []; }
+  async accept(chunk: FrameChunk): Promise<{ value: unknown } | undefined> {
+    try {
+      if (chunk.kind === 'begin') {
+        if (this.buffers) throw new Error('A frame value is already arriving');
+        if (!chunk.lengths.length || chunk.lengths.length > 4096 || chunk.lengths.reduce((sum, n) => sum + n, 0) > 2 * 1024 ** 3 || chunk.lengths.some(n => !Number.isSafeInteger(n) || n < 0 || n > 1024 ** 3))
+          throw new Error('Invalid frame buffer lengths');
+        this.buffers = chunk.lengths.map(n => new Uint8Array(n));
+        this.offsets = chunk.lengths.map(() => 0);
+        return;
+      }
+      if (!this.buffers) throw new Error('Frame chunk arrived without its manifest');
+      if (chunk.kind === 'bytes') {
+        const buffer = this.buffers[chunk.slot];
+        if (!buffer || !Number.isSafeInteger(chunk.offset) || chunk.offset !== this.offsets[chunk.slot] || chunk.bytes.byteLength > FRAME_CHUNK_BYTES || !chunk.bytes.byteLength || chunk.offset + chunk.bytes.byteLength > buffer.byteLength)
+          throw new Error('Frame chunk is out of order or exceeds its bound');
+        if (await digest(chunk.bytes) !== chunk.sha256) throw new Error('Frame chunk digest mismatch');
+        buffer.set(chunk.bytes, chunk.offset); this.offsets[chunk.slot] = chunk.offset + chunk.bytes.byteLength;
+        return;
+      }
+      if (chunk.kind !== 'end') throw new Error('Unknown frame chunk');
+      const buffers = this.buffers;
+      if (buffers.some((b, i) => b.length !== this.offsets[i])) throw new Error('Frame value is incomplete');
+      const value: unknown = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffers[0]), (_key, item) => {
+        if (!item || typeof item !== 'object' || !('$frameColumn' in item)) return item;
+        const bytes = buffers[item.$frameColumn];
+        const Type = arrays[item.type as keyof typeof arrays];
+        if (!Number.isSafeInteger(item.$frameColumn) || item.$frameColumn < 1 || !bytes || !Object.hasOwn(arrays, item.type) || !Type || bytes.byteLength % Type.BYTES_PER_ELEMENT)
+          throw new Error('Invalid frame column descriptor');
+        return new Type(bytes.buffer as ArrayBuffer);
+      });
+      this.reset(); return { value };
+    } catch (error) { this.reset(); throw error; }
+  }
+}

package/browser/protocol.ts

@@ -1,3 +1,4 @@
+import type { FrameChunk } from './frame-stream.mts';
 /** Messages between the editor tab and its Blender worker. One session per
  * worker; the model lives in the worker's Python and nowhere else. */
 
@@ -97,6 +98,7 @@ export type WorkerRequest =
     };
 
 export type WorkerReply =
+  | { op: 'frame-stream'; id: number; chunk: FrameChunk }
   | { op: 'document-dirty'; dirty: boolean }
   | { op: 'history'; entries: NativeHistoryEntry[] }
   | { id: number; result: unknown }

package/browser/runtime.ts

@@ -1,3 +1,4 @@
+import { FrameStreamReader } from './frame-stream.mts';
 /**
  * The tab-side handle on a Blender session: spawns the worker, forwards the
  * four tool calls, and hands every presented frame to whoever displays it.
@@ -27,6 +28,8 @@ type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : n
 type Request = DistributiveOmit<WorkerRequest, 'id'>;
 
 export interface BlenderRuntimeOptions {
+  /** Stage one verified mesh/image without replacing the displayed frame. */
+  stage?(part: { session: string; revision: number; abort?: boolean; mesh?: string; image?: string; piece?: unknown }): Promise<void> | void;
   /** Operation-only diagnostics, never request payloads. The optional observer
    * must not affect work, even if it throws. End calls balance overlapping work. */
   work?(label: string): () => void;
@@ -478,6 +481,7 @@ export class BlenderRuntime {
 
   /** Forced teardown for a lost session; explicit user stops must use stop(). */
   terminate(): void {
+    this.#discardStagedFrame();
     if (this.#terminated) return;
     this.#terminated = true;
     globalThis.removeEventListener?.('beforeunload', this.#beforeUnload);
@@ -570,8 +574,39 @@ export class BlenderRuntime {
     } catch { return () => {}; }
   }
 
+  readonly #frameStream = new FrameStreamReader();
+  #stagedIdentity: { session: string; revision: number } | null = null;
+  #discardStagedFrame(): void {
+    this.#frameStream.reset();
+    const part = this.#stagedIdentity; this.#stagedIdentity = null;
+    if (part) {
+      try { void Promise.resolve(this.#options.stage?.({ ...part, abort: true })).catch(() => {}); }
+      catch { /* Cleanup cannot replace the original operation failure. */ }
+    }
+  }
+
   async #receive(reply: WorkerReply): Promise<void> {
     if ('op' in reply) {
+      if (reply.op === 'frame-stream') {
+        try {
+          const decoded = await this.#frameStream.accept(reply.chunk);
+          if (decoded) {
+            const value = decoded.value as ({ op: 'stage'; session: string; revision: number } | Omit<Extract<WorkerReply, { op: 'present' }>, 'id'>);
+            if (value.op === 'present') {
+              await this.#receive({ ...value, id: reply.id } as WorkerReply);
+              return;
+            }
+            if (value.op !== 'stage' || !this.#options.stage) throw new Error('The presenter does not support staged Blender frames');
+            this.#stagedIdentity = { session: value.session, revision: value.revision };
+            await this.#options.stage(value);
+          }
+          this.#worker.postMessage({ op: 'present-result', id: reply.id } satisfies WorkerRequest);
+        } catch (error) {
+          this.#discardStagedFrame();
+          this.#worker.postMessage({ op: 'present-result', id: reply.id, error: error instanceof Error ? error.message : String(error) } satisfies WorkerRequest);
+        }
+        return;
+      }
       if (reply.op === 'document-dirty') {
         this.#dirty = reply.dirty;
         return;
@@ -600,6 +635,7 @@ export class BlenderRuntime {
       const end = this.#work('presenting worker frame');
       try {
         const answer = await this.#options.present(reply.frame, reply.description, reply.capture);
+        this.#stagedIdentity = null;
         this.#worker.postMessage({
           op: 'present-result',
           id: reply.id,
@@ -609,6 +645,7 @@ export class BlenderRuntime {
             : {}),
         } satisfies WorkerRequest);
       } catch (error) {
+        this.#discardStagedFrame();
         this.#worker.postMessage({
           op: 'present-result',
           id: reply.id,
@@ -619,6 +656,7 @@ export class BlenderRuntime {
       }
       return;
     }
+    if ('error' in reply) this.#discardStagedFrame();
     const pending = this.#pending.get(reply.id);
     if (!pending) return;
     this.#pending.delete(reply.id);

package/browser/session-frame.mts

@@ -91,15 +91,14 @@ function readColumn(arena: Uint8Array, name: string, descriptor: ColumnDescripto
  * Every `{offset, length, dtype, count, stride}` in the frame, replaced by its
  * typed array.
  *
- * `co` is widened to `Float64Array` because that is what `MeshColumns`
- * declares and `drawArraysFromColumns` is typed against, while Blender's own
- * vertex array is single precision.
+ * Positions keep Blender's own precision. Widening a float column would
+ * double its transfer/storage without adding information.
  */
 export function columnsToTypedArrays(arena: Uint8Array, frame: unknown): unknown {
   const walk = (value: unknown, key: string): unknown => {
     if (isColumnDescriptor(value)) {
       const view = readColumn(arena, key, value);
-      return key === 'co' ? Float64Array.from(view) : view;
+      return view;
     }
     if (Array.isArray(value)) return value.map((entry) => walk(entry, key));
     if (typeof value === 'object' && value !== null) {

package/browser/three/blender-frame-columns.ts

@@ -78,7 +78,7 @@ export const ATTRIBUTE_LAYOUT: Record<AttributeType, { size: number }> = {
 /** Exactly what the draw reads off a presented mesh. */
 export interface MeshColumns {
   /** 3 * nv */
-  co: Float64Array;
+  co: Float32Array | Float64Array;
   /** Blender-evaluated normals, 3 per corner, independent of UV splits. */
   cornerNormal?: Float32Array | undefined;
   /** 3 * nv, a deformed mesh's Generated coordinates in Blender's stored

package/browser/three/blender-runtime-view.ts

@@ -184,7 +184,7 @@ const unchangedMeshSchema = z
  */
 const columnsSchema = z
   .object({
-    co: z.instanceof(Float64Array),
+    co: z.union([z.instanceof(Float32Array), z.instanceof(Float64Array)]),
     cornerNormal: z.instanceof(Float32Array).optional(),
     orco: z.instanceof(Float32Array).optional(),
     faceStart: z.instanceof(Uint32Array),
@@ -1442,6 +1442,33 @@ export class BlenderRuntimeView {
       group.visible = !this.capturing;
   }
 
+  private staged: { session: string; revision: number; meshes: Map<string, { signature: string; geometry: THREE.BufferGeometry }>; images: Map<string, z.infer<typeof frameImageSchema>> } | null = null;
+
+  /** Prepare one mesh as soon as its bounded transfer completes. Source
+   * columns are released before the next mesh; displayed resources change
+   * only when the final frame manifest is validated. */
+  stageFrame(part: { session: string; revision: number; abort?: boolean; mesh?: string; image?: string; piece?: unknown }): void {
+    if (part.abort || (!part.mesh && !part.image)) {
+      for (const entry of this.staged?.meshes.values() ?? []) entry.geometry.dispose();
+      this.staged = part.abort ? null : { session: part.session, revision: part.revision, meshes: new Map(), images: new Map() };
+      return;
+    }
+    const staged = this.staged;
+    if (!staged || staged.session !== part.session || staged.revision !== part.revision)
+      throw new Error('Blender frame piece does not belong to the pending revision');
+    if (part.mesh !== undefined) {
+      const data = exportedMeshSchema.parse(part.piece);
+      if (staged.meshes.has(part.mesh)) throw new Error('Duplicate Blender mesh piece');
+      const signature = `revision:${data.revision}`;
+      staged.meshes.set(part.mesh, { signature, geometry: geometryFromDrawArrays(drawArraysFromColumns({
+        ...data.columns, attributes: data.attributes as never, activeUv: data.activeUv, renderUv: data.renderUv,
+      }, signature)) });
+    } else if (part.image !== undefined) {
+      if (staged.images.has(part.image)) throw new Error('Duplicate Blender image piece');
+      staged.images.set(part.image, frameImageSchema.parse(part.piece));
+    }
+  }
+
   applyFrame(input: unknown) {
     // WHAT THIS PRESENTER HELD BEFORE THIS FRAME, read before anything is
     // applied, and carried back to the session in the present's answer.
@@ -1459,6 +1486,10 @@ export class BlenderRuntimeView {
     const held =
       this.frame === null ? null : { session: this.frame.session, revision: this.frame.revision };
     const next = frameSchema.parse(input);
+    const staged = this.staged;
+    if (staged && (staged.session !== next.session || staged.revision !== next.revision))
+      throw new Error('Blender frame manifest does not match its staged revision');
+    if (staged) for (const [name, data] of staged.images) next.images[name] = data;
     if (this.retiredSessions.has(next.session))
       throw new Error(
         'The runtime session was replaced; its delayed frame cannot overwrite the active model',
@@ -1503,6 +1534,12 @@ export class BlenderRuntimeView {
       }
       for (const [id, data] of Object.entries(next.meshes)) {
         if ('unchanged' in data) {
+          const incoming = staged?.meshes.get(id);
+          if (incoming) {
+            if (incoming.signature !== `revision:${data.revision}`) throw new Error('Staged Blender mesh revision mismatch');
+            prepared.set(id, incoming);
+            continue;
+          }
           // A REFERENCE, not geometry: the worker says this store has not been
           // written since the frame it last sent, so the resident
           // BufferGeometry stands. If it is not resident the worker's record
@@ -1567,6 +1604,10 @@ export class BlenderRuntimeView {
       }
       throw error;
     }
+    if (staged) {
+      for (const [id, value] of staged.meshes) if (!prepared.has(id)) value.geometry.dispose();
+      this.staged = null;
+    }
     if (this.frame?.session !== next.session) {
       if (this.frame) this.retiredSessions.add(this.frame.session);
       this.clear();
@@ -1929,7 +1970,7 @@ export class BlenderRuntimeView {
     // nested number arrays it arrived as cost ~15x their JSON (the blower's
     // last frame held 850 MB of main-thread heap this way, measured
     // 2026-09-13). Reuse checks compare the per-mesh signatures kept above.
-    this.frame = { ...next, meshes: {}, volumes: {} };
+    this.frame = { ...next, meshes: {}, volumes: {}, images: {} };
     this.worldKey = JSON.stringify(next.world ?? null);
     // THE OVERLAYS, after the graph stands: the weight drawing is laid over
     // the presented mesh's own geometry and the bones over the armature
@@ -2182,6 +2223,8 @@ export class BlenderRuntimeView {
   }
 
   private clear() {
+    for (const entry of this.staged?.meshes.values() ?? []) entry.geometry.dispose();
+    this.staged = null;
     for (const light of this.lights.values()) {
       light.removeFromParent();
       light.dispose();

package/browser/worker.ts

@@ -1,3 +1,4 @@
+import { sendFrameValue } from './frame-stream.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 +40,6 @@
 
 import { type BlenderEngine, type BlenderFiles, startBlenderEngine } from './blender-engine.mts';
 import type { CaptureRequest, FileEntry, WorkerReply, WorkerRequest } from './protocol';
-import { frameTransferBuffers } from './frame-transfer.mts';
 import { documentChunks } from './document-chunks.mts';
 import { columnsToTypedArrays, describeFrame, isColumnDescriptor } from './session-frame.mts';
 
@@ -68,33 +68,20 @@ const pendingPresents = new Map<
   { resolve: (value: PresentAnswer) => void; reject: (error: Error) => void }
 >();
 
-function presentToTab(
-  frame: unknown,
-  description: unknown,
-  capture?: CaptureRequest,
-): Promise<PresentAnswer> {
-  const id = ++presentId;
-  // A drawn mesh's buffers move to the tab rather than being copied: the
-  // frame is the tab's from here on.
-  const transfer = frameTransferBuffers(frame);
-  return new Promise((resolve, reject) => {
-    pendingPresents.set(id, { resolve, reject });
-    try {
-      (self as unknown as Worker).postMessage(
-        {
-          op: 'present',
-          id,
-          frame,
-          description,
-          ...(capture ? { capture } : {}),
-        } satisfies WorkerReply,
-        transfer,
-      );
-    } catch (error) {
-      pendingPresents.delete(id);
-      reject(error);
-    }
-  });
+async function streamToTab(value: unknown): Promise<PresentAnswer> {
+  return await sendFrameValue(value, chunk => {
+    const id = ++presentId;
+    return new Promise<PresentAnswer>((resolve, reject) => {
+      pendingPresents.set(id, { resolve, reject });
+      try {
+        (self as unknown as Worker).postMessage({ op: 'frame-stream', id, chunk } satisfies WorkerReply,
+          chunk.kind === 'bytes' ? [chunk.bytes.buffer as ArrayBuffer] : []);
+      } catch (error) { pendingPresents.delete(id); reject(error); }
+    });
+  }) as PresentAnswer;
+}
+function presentToTab(frame: unknown, description: unknown, capture?: CaptureRequest): Promise<PresentAnswer> {
+  return streamToTab({ op: 'present', frame, description, ...(capture ? { capture } : {}) });
 }
 
 let engine: BlenderEngine | null = null;
@@ -122,6 +109,8 @@ interface Copied {
   description: unknown;
 }
 interface PendingFrame {
+  session: string;
+  revision: number;
   columns: Map<number, Copied>;
   meshes: Map<string, Copied>;
   images: Map<string, Copied>;
@@ -166,7 +155,10 @@ function assemblePending(held: PendingFrame, frame: unknown): { typed: unknown;
         return piece[side];
       }
       const out: Record<string, unknown> = {};
-      for (const [name, entry] of Object.entries(value)) out[name] = walk(entry, [...path, name]);
+      for (const [name, entry] of Object.entries(value)) {
+        const item = walk(entry, [...path, name]);
+        if (item !== undefined) out[name] = item;
+      }
       return out;
     };
     return walk(frame, []);
@@ -285,7 +277,9 @@ async function startBlender(project: string, document?: string): Promise<unknown
       // copied out of the heap as they come, because the next export call frees them; the tab
       // gets the whole frame at `present`.
       if (hold !== undefined) {
-        pending = { columns: await copyColumns(arena, hold), meshes: new Map(), images: new Map() };
+        const identity = hold as { session: string; revision: number };
+        pending = { session: identity.session, revision: identity.revision, columns: await copyColumns(arena, hold), meshes: new Map(), images: new Map() };
+        await streamToTab({ op: 'stage', session: identity.session, revision: identity.revision });
         return {};
       }
       if (mesh !== undefined || image !== undefined) {
@@ -310,8 +304,14 @@ async function startBlender(project: string, document?: string): Promise<unknown
             description: await describeFrame(arena, piece),
           };
         }
-        if (mesh !== undefined) pending.meshes.set(mesh, copied);
-        else pending.images.set(image as string, copied);
+        await streamToTab({ op: 'stage', session: pending.session, revision: pending.revision,
+          ...(mesh !== undefined ? { mesh } : { image }), piece: copied.typed });
+        // Keep only the manifest and digest; the presenter already built this
+        // resource, and the next pull may overwrite the engine arena.
+        if (mesh !== undefined) {
+          const data = copied.typed as { revision: number };
+          pending.meshes.set(mesh, { typed: { revision: data.revision, unchanged: true }, description: copied.description });
+        } else pending.images.set(image as string, { typed: undefined, description: copied.description });
         return {};
       }
       let typed: 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.53",
+  "version": "0.1.55",
   "publishConfig": {
     "access": "public"
   },