@volter/blender-engine 0.1.0 → 0.1.2

package/browser/blender-emscripten-engine.mts

@@ -267,6 +267,8 @@ export async function startEmscriptenBlenderEngine(
     }
 
   const files = moduleFiles(module);
+  FS.chmod('/bw/datafiles', 0o755);
+  await mountEssentials(files);
   const { request } = openSessionChannel(files, options);
 
   return {
@@ -287,3 +289,32 @@ export async function startEmscriptenBlenderEngine(
     releasedPayloadBytes,
   };
 }
+
+/** 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> {
+  const [indexResponse, payloadResponse] = await Promise.all([
+    fetch(artifactUrl('essentials.json')), fetch(artifactUrl('essentials.bin')),
+  ]);
+  if (!indexResponse.ok || !payloadResponse.ok)
+    throw new Error(`Blender Essentials assets are missing (${indexResponse.status}/${payloadResponse.status})`);
+  const index = await indexResponse.json() as {
+    bytes: number; sha256: string;
+    files: { path: string; offset: number; bytes: number; sha256: string }[];
+  };
+  const payload = await payloadResponse.arrayBuffer();
+  const hash = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', payload)),
+    (byte) => byte.toString(16).padStart(2, '0')).join('');
+  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) {
+    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)
+      throw new Error(`Invalid Blender Essentials file: ${file.path}`);
+    const path = `/bw/datafiles/assets/${file.path}`;
+    await files.mkdirTree(path.slice(0, path.lastIndexOf('/')));
+    await files.writeFile(path, new Uint8Array(payload, file.offset, file.bytes));
+  }
+}

package/browser/protocol.ts

@@ -2,11 +2,14 @@
  * worker; the model lives in the worker's Python and nowhere else. */
 
 export type WorkerRequest =
+  | { id: number; op: 'flush-document' }
+  | { id: number; op: 'history-begin' | 'history-end' }
+  | { id: number; op: 'history-step'; token: string; direction: 'undo' | 'redo' }
   /** `document` is the session's `.blend`, PROJECT-RELATIVE (`models/model.blend`
    *  by default). An existing one is opened at start; an absent one starts
    *  empty and is created by the first save. */
   | { id: number; op: 'start'; project: string; document?: string }
-  | { id: number; op: 'execute'; code: string }
+  | { id: number; op: 'execute'; code: string; history?: boolean; label?: string }
   | { id: number; op: 'scene-info' }
   | { id: number; op: 'object-info'; name: string }
   | { id: number; op: 'screenshot-view'; maxSize: number }
@@ -32,6 +35,7 @@ export type WorkerRequest =
   | {
       id: number;
       op: 'rna-set';
+      history?: boolean;
       path: string;
       property: string;
       value: unknown;
@@ -90,6 +94,8 @@ export type WorkerRequest =
     };
 
 export type WorkerReply =
+  | { op: 'document-dirty'; dirty: boolean }
+  | { op: 'history'; entries: NativeHistoryEntry[] }
   | { id: number; result: unknown }
   | { id: number; error: string }
   /** The worker asks the tab to display a frame (and to remember the view a
@@ -121,6 +127,12 @@ export type WorkerReply =
    */
   | { op: 'memory'; bytes: number };
 
+export type NativeHistoryEntry = { reset: true } | {
+  id: string;
+  label: string;
+  resource: string | null;
+};
+
 export interface CaptureRequest {
   /** A viewport screenshot's bound, the longer side of a square frame.
    *  Absent on a render, which states its exact pixel dimensions instead. */

package/browser/runtime.ts

@@ -9,6 +9,7 @@ import type {
   RuntimeStart,
   WorkerReply,
   WorkerRequest,
+  NativeHistoryEntry,
 } from './protocol';
 import type {
   BlenderActionClip,
@@ -26,6 +27,7 @@ type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : n
 type Request = DistributiveOmit<WorkerRequest, 'id'>;
 
 export interface BlenderRuntimeOptions {
+  history?(entries: readonly NativeHistoryEntry[]): void;
   /** Display a frame. A screenshot `capture` has its view REMEMBERED so the
    *  next document capture photographs what the agent asked for; a render
    *  capture (`capture.render`) is photographed here and now, and its answer
@@ -137,6 +139,14 @@ export class BlenderRuntime {
   >();
   #nextId = 0;
   #started: Promise<RuntimeStart> | null = null;
+  #stopping: Promise<void> | null = null;
+  #terminated = false;
+  #dirty = false;
+  readonly #beforeUnload = (event: BeforeUnloadEvent): void => {
+    if (!this.#dirty && this.#pending.size === 0) return;
+    event.preventDefault();
+    event.returnValue = '';
+  };
   /** `performance.now()` at the `postMessage` of every outstanding call. */
   readonly #callStarts = new Map<number, number>();
   #lastCallMs: number | null = null;
@@ -155,6 +165,7 @@ export class BlenderRuntime {
       type: 'module',
       name: 'blender',
     });
+    globalThis.addEventListener?.('beforeunload', this.#beforeUnload);
     this.#worker.onmessage = (event: MessageEvent<WorkerReply>) => void this.#receive(event.data);
     this.#worker.onerror = (event) => {
       // A module worker that fails to LOAD reports an ErrorEvent with an empty
@@ -222,9 +233,20 @@ export class BlenderRuntime {
     return this.start(this.#project);
   }
 
-  async execute(code: string): Promise<string> {
+  async execute(code: string, history = true, label = 'Blender Python'): Promise<string> {
     await this.#ready();
-    return (await this.#request({ op: 'execute', code })) as string;
+    return (await this.#request({ op: 'execute', code, history, label })) as string;
+  }
+
+  async historyGesture(op: 'history-begin' | 'history-end'): Promise<void> {
+    await this.#ready();
+    await this.#request({ op });
+  }
+
+  async historyStep(token: string, direction: 'undo' | 'redo'): Promise<boolean> {
+    await this.#ready();
+    const result = await this.#request({ op: 'history-step', token, direction }) as { moved: boolean };
+    return result.moved;
   }
 
   async sceneInfo(): Promise<string> {
@@ -267,10 +289,12 @@ export class BlenderRuntime {
     property: string,
     value: unknown,
     index?: number,
+    history = true,
   ): Promise<BlenderRnaWrite> {
     await this.#ready();
     return (await this.#request({
       op: 'rna-set',
+      history,
       path,
       property,
       value,
@@ -395,7 +419,29 @@ export class BlenderRuntime {
     return this.#presented;
   }
 
+  /** Drain accepted calls and persist the document before destroying its only
+   * copy. A failed save keeps the worker alive so the caller can retry. */
+  stop(): Promise<void> {
+    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);
+      }
+      this.terminate();
+    })().catch(error => {
+      this.#stopping = null;
+      throw error;
+    });
+    return this.#stopping;
+  }
+
+  /** Forced teardown for a lost session; explicit user stops must use stop(). */
   terminate(): void {
+    if (this.#terminated) return;
+    this.#terminated = true;
+    globalThis.removeEventListener?.('beforeunload', this.#beforeUnload);
     this.#worker.terminate();
     const error = new Error('The Blender session was terminated');
     for (const id of [...this.#pending.keys()]) this.#settled(id);
@@ -455,7 +501,9 @@ export class BlenderRuntime {
       this.#lastCallWindow = { start: started, end: started + elapsed };
   }
 
-  #request(request: Request): Promise<unknown> {
+  #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 id = ++this.#nextId;
     return new Promise((resolve, reject) => {
       this.#pending.set(id, { resolve, reject });
@@ -468,6 +516,14 @@ export class BlenderRuntime {
 
   async #receive(reply: WorkerReply): Promise<void> {
     if ('op' in reply) {
+      if (reply.op === 'document-dirty') {
+        this.#dirty = reply.dirty;
+        return;
+      }
+      if (reply.op === 'history') {
+        this.#options.history?.(reply.entries);
+        return;
+      }
       if (reply.op === 'log') {
         this.#options.log?.(reply.level, reply.text);
         return;

package/browser/session.py

@@ -194,6 +194,7 @@ def _load_post(_arg):
     # in wasm (35 s at 1280x720, 48 samples) and `_photograph` never ran. The
     # engine ids are taken again on every load.
     ENGINES[:], UNAVAILABLE_ENGINES[:] = _register_engine()
+    HISTORY.reset()
 
 
 # ---------------------------------------------------------------- warnings
@@ -352,12 +353,11 @@ def _describe_background(background, camera_ray):
                         "inputs": [{"kind": "math", "operation": "ADD", "clamp": False,
                                     "inputs": products[:2]}, products[2]]}
             if kind == "ShaderNodeMapping" and socket == "Vector":
-                if node.vector_type != "POINT":
-                    raise NotImplementedError("World Mapping vector type %s" % node.vector_type)
                 for name in ("Location", "Rotation", "Scale"):
                     if node.inputs[name].links:
                         raise NotImplementedError("Linked World Mapping " + name)
-                return {"kind": "mapping", "vector": value(node.inputs["Vector"]),
+                return {"kind": "mapping", "vector_type": node.vector_type,
+                        "vector": value(node.inputs["Vector"]),
                         "location": [float(c) for c in node.inputs["Location"].default_value],
                         "rotation": [float(c) for c in node.inputs["Rotation"].default_value],
                         "scale": [float(c) for c in node.inputs["Scale"].default_value]}
@@ -402,9 +402,17 @@ def _describe_background(background, camera_ray):
         finally:
             visiting.remove(key)
 
+    color = value(background.inputs["Color"])
+    strength = value(background.inputs["Strength"])
+    # The field evaluator already implements an unclamped color mix. Mixing
+    # black with radiance at factor strength is exact multiplication, including
+    # spatially varying strength, with no second shader implementation.
+    if not isinstance(strength, (int, float)):
+        color = {"kind": "mix_color", "factor": strength, "a": [0.0, 0.0, 0.0],
+                 "b": color, "clamp_factor": False, "clamp_result": False}
+        strength = 1.0
     return {"color": [float(c) for c in list(background.inputs["Color"].default_value)[:3]],
-            "strength": float(background.inputs["Strength"].default_value),
-            "shader": value(background.inputs["Color"])}
+            "strength": float(strength), "shader": color}
 
 
 def _describe_world(world):
@@ -417,18 +425,17 @@ def _describe_world(world):
     if outputs[0].inputs["Volume"].links:
         raise NotImplementedError("World volume rendering is not implemented")
     background, lighting = _surface_backgrounds(surface[0].from_node)
-    for node in (background, lighting):
-        if node is not None and node.inputs["Strength"].links:
-            raise NotImplementedError("Linked World Background strength is not implemented")
     described = _describe_background(background, camera_ray=True)
     lighting_data = _describe_background(lighting or background, camera_ray=False)
     if lighting_data != described:
         described["lighting"] = lighting_data
-    # A constant Color needs no expression; the presenter reads `color`.
-    if not background.inputs["Color"].is_linked:
+    # Only a wholly constant background can drop the expression: linked
+    # Strength may carry spatial radiance even when Color itself is constant.
+    if not any(background.inputs[name].is_linked for name in ("Color", "Strength")):
         described.pop("shader", None)
-        if "lighting" in described and not (lighting or background).inputs["Color"].is_linked:
-            described["lighting"].pop("shader", None)
+    if "lighting" in described and not any(
+            (lighting or background).inputs[name].is_linked for name in ("Color", "Strength")):
+        described["lighting"].pop("shader", None)
     return described
 
 
@@ -780,9 +787,8 @@ class Session:
             # How many COLUMN BYTES this frame actually shipped: a move ships
             # zero, a vertex edit one mesh's worth.
             "bytes": int(_blender_web.buffer_size()),
-            # Blender's `is_dirty`, carried as an INSTRUMENT only: it is always
-            # False in this build (no undo stack in `--background`), which is
-            # why `save_document` does not read it. See the note there.
+            # Blender's `is_dirty` is instrumentation, not our save predicate:
+            # 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
@@ -1060,13 +1066,10 @@ class Session:
         if self.document is None:
             return {"saved": False, "reason": "no-document"}
         # `bpy.data.is_dirty` IS NOT A PREDICATE HERE, and this is the measurement
-        # rather than a preference. It reports `is_memfile_undo_written`, which
-        # only a GLOBAL UNDO PUSH clears -- and `--background` has no undo stack,
-        # so nothing ever pushes one. MEASURED 2026-09-18 in the tab, straight
-        # after `lantern.py` built fourteen objects: `bpy.data.is_dirty` is
-        # False. It is False before a save, False after one, and False across a
-        # script that models an entire scene; the only state it ever named here
-        # was "saved".
+        # rather than a preference. Before native undo initialization it stayed
+        # False even after a script built fourteen objects; with explicit undo
+        # checkpoints it can stay True across read-only operations. It is not
+        # a reliable change detector for this request-driven background 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
@@ -1419,6 +1422,109 @@ def _register_engine():
     return made, unavailable
 
 
+# ---------------------------------------------------------------- native document history
+
+class NativeHistory:
+    """Blender owns the snapshots. These ids only address its steps from Code-OSS.
+
+    Background mode supports explicit undo_push (ed_undo_push_exec). Initialize
+    after opening the document, then checkpoint at the request boundary, including
+    scripts that mutate and subsequently fail. Never replay a script to redo it.
+    """
+    def __init__(self):
+        self.epoch = 0
+        self.serial = 0
+        self.steps = []
+        self.cursor = 0
+        self.events = []
+        self.initialized = False
+        self.group_depth = 0
+        self.group_label = None
+        self.mutation_serial = 0
+        self.moving = False
+
+    def changed(self):
+        self.mutation_serial += 1
+
+    def native_moved(self):
+        # A script can invoke Blender's undo directly. It must not leave our
+        # tokens addressing a different native cursor. Host-owned moves retain
+        # their ledger; external moves invalidate it and start a fresh baseline.
+        if not self.moving:
+            self.reset()
+
+    def reset(self):
+        self.epoch += 1
+        self.steps = []
+        self.cursor = 0
+        self.initialized = False
+        self.group_depth = 0
+        self.group_label = None
+        self.events = [{"reset": True}]
+
+    def begin(self):
+        if self.initialized:
+            return
+        preferences = bpy.context.preferences.edit
+        preferences.use_global_undo = True
+        # Native eviction may exhaust history before our address ledger. poll()
+        # below then refuses instead of claiming a restoration. Bound memory in
+        # the browser worker; retaining hundreds of full scenes can exhaust wasm.
+        preferences.undo_steps = 32
+        preferences.undo_memory_limit = 256
+        if "FINISHED" not in bpy.ops.ed.undo_push(message="Open document"):
+            raise RuntimeError("Blender could not initialize native undo; the edit was not started")
+        self.initialized = True
+
+    def commit(self, label):
+        self.begin()
+        if self.group_depth:
+            self.group_label = self.group_label or label
+            return
+        bpy.context.view_layer.update()
+        if "FINISHED" not in bpy.ops.ed.undo_push(message=label[:63]):
+            raise RuntimeError("Blender could not checkpoint this edit in native undo")
+        self.serial += 1
+        token = "%s:%s:%s" % (SESSION.session, self.epoch, self.serial)
+        self.steps[self.cursor:] = [token]
+        # Blender keeps at most undo_steps native states, including the baseline.
+        if len(self.steps) > 31:
+            del self.steps[:-31]
+        self.cursor = len(self.steps)
+        self.events.append({"id": token, "label": label,
+                            "resource": SESSION.document_relative})
+
+    def move(self, token, direction):
+        if self.group_depth:
+            raise RuntimeError("Finish the current Blender gesture before undo or redo")
+        index = self.cursor - 1 if direction == "undo" else self.cursor
+        if index < 0 or index >= len(self.steps) or self.steps[index] != token:
+            raise RuntimeError("Blender history expired or changed outside this edit; no other step was restored")
+        operator = bpy.ops.ed.undo if direction == "undo" else bpy.ops.ed.redo
+        if not operator.poll():
+            raise RuntimeError("Blender cannot %s this native step in the current context" % direction)
+        self.moving = True
+        try:
+            if "FINISHED" not in operator():
+                raise RuntimeError("Blender did not finish %s" % direction)
+        finally:
+            self.moving = False
+        self.cursor += -1 if direction == "undo" else 1
+        # Native undo replaces datablocks. Both revision caches must forget their
+        # old pointers before the restored scene is exported to the presenter.
+        _blender_web.session_reset()
+        SESSION.forget()
+        SESSION.present()
+        return {"moved": True}
+
+
+HISTORY = NativeHistory()
+
+
+@bpy.app.handlers.persistent
+def _history_post(_arg):
+    HISTORY.native_moved()
+
 # ---------------------------------------------------------------- the MCP tools
 
 def get_scene_info():
@@ -2049,6 +2155,7 @@ def rna_set(path, identifier, value, index=None):
             setattr(target, identifier, value)
     else:
         getattr(target, identifier)[index] = value
+    HISTORY.changed()
     return {"path": path, "property": identifier, "value": _rna_value(target, prop)}
 
 
@@ -3925,28 +4032,35 @@ def outliner_set(path, column, value):
     if isinstance(target, bpy.types.Object):
         if column == "hide":
             target.hide_set(value, view_layer=bpy.context.view_layer)
+            HISTORY.changed()
             return {"path": path, "column": column, "value": bool(target.hide_get())}
         if column == "render":
             target.hide_render = value
+            HISTORY.changed()
             return {"path": path, "column": column, "value": bool(target.hide_render)}
         if column == "viewport":
             target.hide_viewport = value
+            HISTORY.changed()
             return {"path": path, "column": column, "value": bool(target.hide_viewport)}
     if isinstance(target, bpy.types.LayerCollection):
         if column in ("exclude", "hide"):
             member = "exclude" if column == "exclude" else "hide_viewport"
             setattr(target, member, value)
+            HISTORY.changed()
             return {"path": path, "column": column, "value": bool(getattr(target, member))}
         if column == "render":
             target.collection.hide_render = value
+            HISTORY.changed()
             return {"path": path, "column": column, "value": bool(target.collection.hide_render)}
     if isinstance(target, bpy.types.Modifier):
         member = {"render": "show_render", "viewport": "show_viewport"}.get(column)
         if member is not None:
             setattr(target, member, not value)
+            HISTORY.changed()
             return {"path": path, "column": column, "value": not getattr(target, member)}
     if isinstance(target, bpy.types.Constraint) and column == "hide":
         target.enabled = not value
+        HISTORY.changed()
         return {"path": path, "column": column, "value": not target.enabled}
     raise ValueError(
         "Blender's Outliner draws no %r column on a %s, so nothing was written -- the columns "
@@ -3955,6 +4069,45 @@ def outliner_set(path, column, value):
 
 
 def dispatch(request):
+    op = request.get("op")
+    if op == "history-begin":
+        HISTORY.begin()
+        HISTORY.group_depth += 1
+        return None
+    if op == "history-end":
+        if HISTORY.group_depth == 0:
+            raise RuntimeError("No Blender gesture is open")
+        HISTORY.group_depth -= 1
+        if HISTORY.group_depth == 0 and HISTORY.group_label:
+            label, HISTORY.group_label = HISTORY.group_label, None
+            HISTORY.commit(label)
+        return None
+    if op == "history-events":
+        events, HISTORY.events = HISTORY.events, []
+        return events
+    if op == "history-step":
+        if request["direction"] not in ("undo", "redo"):
+            raise ValueError("Unknown history direction")
+        return HISTORY.move(request["token"], request["direction"])
+    mutation = op in ("execute", "rna-set", "outliner-set") and request.get("history", True)
+    if not mutation:
+        return _dispatch(request)
+    HISTORY.begin()
+    before = HISTORY.mutation_serial
+    epoch = HISTORY.epoch
+    try:
+        return _dispatch(request)
+    finally:
+        # Loading a file resets Blender's native stack. Its final state cannot
+        # serve as both the before and after of an invented undo checkpoint.
+        if HISTORY.epoch == epoch and HISTORY.mutation_serial != before:
+            HISTORY.commit(request.get("label") or {
+                "execute": "Blender Python", "rna-set": "Set " + request.get("property", "property"),
+                "outliner-set": "Set " + request.get("column", "visibility"),
+            }[op])
+
+
+def _dispatch(request):
     op = request.get("op")
     if op == "execute":
         engine = bpy.context.scene.render.engine
@@ -3967,6 +4120,9 @@ def dispatch(request):
         absent = _absent_capability(request["code"])
         if absent is not None:
             return {"executed": False, "result": "", "error": absent}
+        # Arbitrary Python can partially mutate before throwing. Once execution
+        # starts it needs a checkpoint; capability refusals above do not.
+        HISTORY.changed()
         answer = execute(request["code"])
         # Every mutation is presented, the rule: the Model
         # document is what the agent is looking at.
@@ -4076,6 +4232,8 @@ def dispatch(request):
 
 _prepare_directories()
 bpy.app.handlers.load_post.append(_load_post)
+bpy.app.handlers.undo_post.append(_history_post)
+bpy.app.handlers.redo_post.append(_history_post)
 ENGINES, UNAVAILABLE_ENGINES = _register_engine()
 _say("@@VGAI-READY " + json.dumps({"blender": bpy.app.version_string, "engines": ENGINES,
                                    "unavailableEngines": UNAVAILABLE_ENGINES}))

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

@@ -397,6 +397,7 @@ export type WorldExpression =
     }
   | {
       kind: 'mapping';
+      vector_type?: 'POINT' | 'TEXTURE' | 'VECTOR' | 'NORMAL' | undefined;
       vector: WorldExpression;
       location: WorldVector;
       rotation: WorldVector;
@@ -475,6 +476,7 @@ const worldExpression: z.ZodType<WorldExpression> = z.lazy(() =>
     z
       .object({
         kind: z.literal('mapping'),
+        vector_type: z.enum(['POINT', 'TEXTURE', 'VECTOR', 'NORMAL']).optional(),
         vector: worldExpression,
         location: worldVector,
         rotation: worldVector,

package/browser/three/world-field-sampler.ts

@@ -111,24 +111,32 @@ export function worldField(
   }
   if (expression.kind === 'mapping') {
     const source = worldField(expression.vector, windowCoordinates);
-    const matrix = new THREE.Matrix4().compose(
-      new THREE.Vector3(...expression.location),
-      new THREE.Quaternion().setFromEuler(
+    const location = new THREE.Vector3(...expression.location);
+    const scale = new THREE.Vector3(...expression.scale);
+    const rotation = new THREE.Quaternion().setFromEuler(
         new THREE.Euler(
           expression.rotation[0],
           expression.rotation[1],
           expression.rotation[2],
           'ZYX',
         ),
-      ),
-      new THREE.Vector3(...expression.scale),
     );
+    const inverseRotation = rotation.clone().invert();
+    const inverseScale = new THREE.Vector3(...expression.scale.map(v => v === 0 ? 0 : 1 / v));
     const value = new THREE.Vector3();
     return (direction) => {
       const input = source(direction);
       if (typeof input === 'number') value.setScalar(input);
       else value.copy(input);
-      return value.applyMatrix4(matrix);
+      // Blender's gpu_shader_material_mapping.glsl: texture uses inverse
+      // rotation then safe division, normals inverse scale then normalization.
+      // A generic inverse matrix is incorrect when a scale component is zero.
+      switch (expression.vector_type ?? 'POINT') {
+        case 'TEXTURE': return value.sub(location).applyQuaternion(inverseRotation).multiply(inverseScale);
+        case 'VECTOR': return value.multiply(scale).applyQuaternion(rotation);
+        case 'NORMAL': return value.multiply(inverseScale).applyQuaternion(rotation).normalize();
+        case 'POINT': return value.multiply(scale).applyQuaternion(rotation).add(location);
+      }
     };
   }
   if (expression.kind === 'map_range') {

package/browser/worker.ts

@@ -19,18 +19,17 @@
  * before every call, and what the session writes is mirrored back out by the
  * transport (`list-files`/`read-file`).
  *
- * THE DOCUMENT'S DEBOUNCE LIVES HERE, because this is the only side of the
- * session that has a clock. Python's loop cannot ask the tab for anything
+ * THE DOCUMENT'S SAVE BARRIER LIVES HERE. Python's loop cannot ask the tab for anything
  * while it is idle — `serveAsks` only runs inside a request's poll loop, so an
  * `ask` raised between calls is never answered and wedges the Blender pthread.
- * So the session marks a present `saveDue`, this file waits out one idle
- * second, calls `save-document` as an ordinary request (which Python's loop
+ * 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`.
+ * project through `/__editor/blender-document` BEFORE acknowledging the edit.
  *
  * WHY THE CARRY IS NOT THE MIRROR'S JOB (`vgai blender-mcp`, class Mirror):
  * the Mirror is pull-based and runs only after an `execute_blender_code`, so
- * a document saved one idle second after the LAST call of a modeling session
+ * a document saved after the LAST call of a modeling session
  * would never leave the worker — which is exactly the state this closes
  * ("closing the tab loses the model"). The Mirror still lists and mirrors the
  * same file in the MCP lane; it just is not what persistence depends on.
@@ -114,36 +113,29 @@ let engine: BlenderEngine | null = null;
 // the only one that crosses to the server, which joins it to its own root so
 // no host path is ever on the wire.
 let documentPath: string | null = null;
-let saveTimer: ReturnType<typeof setTimeout> | null = null;
-/** Calls the tab is waiting on. A save waits for zero. */
-let callsInFlight = 0;
-
-/** The idle second. One save per second of quiet, however many presents
- *  arrived during it: the timer is RESET by each, so a script presenting in a
- *  tight loop writes the document once, when it stops. */
-const DOCUMENT_SAVE_IDLE_MS = 1_000;
+let documentDirty = false;
+// Commands and saves share one lane. In particular a flush cannot overtake
+// an accepted edit, and a later edit cannot race an upload of older bytes.
+let workTail: Promise<unknown> = Promise.resolve();
+function enqueue<T>(work: () => Promise<T>): Promise<T> {
+  const result = workTail.then(work);
+  workTail = result.catch(() => undefined);
+  return result;
+}
 
-function armDocumentSave(): void {
-  if (documentPath === null) return;
-  if (saveTimer !== null) clearTimeout(saveTimer);
-  saveTimer = setTimeout(() => {
-    saveTimer = null;
-    void saveDocument();
-  }, DOCUMENT_SAVE_IDLE_MS);
+function setDocumentDirty(dirty: boolean): void {
+  documentDirty = dirty;
+  post({ op: 'document-dirty', dirty });
 }
 
 /**
  * Save the document and land it in the project.
  *
- * NEVER MID-CALL: a call still outstanding means a script is running, and its
- * half-built model is not the document. The timer re-arms instead of writing.
+ * Only called inside the command lane, after previous calls have finished.
+ * Failure is a rejection: explicit shutdown must retain the live model.
  */
 async function saveDocument(): Promise<void> {
   if (!engine || documentPath === null) return;
-  if (callsInFlight > 0) {
-    armDocumentSave();
-    return;
-  }
   const relative = documentPath;
   let answer: { saved?: boolean; path?: string; size?: number };
   try {
@@ -151,22 +143,15 @@ async function saveDocument(): Promise<void> {
   } 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.
-    log(
-      'error',
-      `@@VGAI-ERROR the Blender document ${relative} could not be saved: ${describeThrown(error)}`,
-    );
-    return;
+    throw new Error(`The Blender document ${relative} could not be saved: ${describeThrown(error)}`);
   }
-  if (!answer?.saved || typeof answer.path !== 'string') return;
+  if (!answer?.saved || typeof answer.path !== 'string')
+    throw new Error(`Blender did not save the document ${relative}`);
   let bytes: Uint8Array;
   try {
     bytes = await engine.files.readFile(answer.path);
   } catch (error) {
-    log(
-      'error',
-      `@@VGAI-ERROR the Blender document ${relative} was saved but could not be read back out of the engine: ${describeThrown(error)}`,
-    );
-    return;
+    throw new Error(`The Blender document ${relative} could not be read back out of the engine: ${describeThrown(error)}`);
   }
   // The engine's copy is now the newer one, so the stager must stop treating
   // this path as the host's: an entry left in `staged` would make the next
@@ -181,19 +166,12 @@ async function saveDocument(): Promise<void> {
     });
     if (!posted.ok) {
       const said = await posted.text().catch(() => '');
-      log(
-        'error',
-        `@@VGAI-ERROR the Blender document ${relative} was not written to the project: HTTP ${posted.status} ${said}`,
-      );
-      return;
+      throw new Error(`HTTP ${posted.status} ${said}`);
     }
   } catch (error) {
-    log(
-      'error',
-      `@@VGAI-ERROR the Blender document ${relative} was not written to the project: ${describeThrown(error)}`,
-    );
-    return;
+    throw new Error(`The Blender document ${relative} was not written to the project: ${describeThrown(error)}`);
   }
+  setDocumentDirty(false);
   log('log', `@@VGAI-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length })}`);
 }
 
@@ -206,9 +184,8 @@ async function startBlender(project: string, document?: string): Promise<unknown
     log,
     ask: async ({ frame, capture, saveDue }) => {
       if (!holder.engine) throw new Error('The Blender session presented before it started');
-      // The session says this present left the document behind the model. The
-      // clock is here; the write is one idle second away.
-      if (saveDue) armDocumentSave();
+      // Save once after the whole command, never during a partial frame.
+      if (saveDue && documentPath !== null) setDocumentDirty(true);
       // THE ARENA IS READ ONCE, HERE, and both readers share those bytes: the
       // typed arrays the tab draws from, and the record of what was sent
       // (`describeFrame`). After the post the buffers are detached and the
@@ -480,10 +457,24 @@ async function handle(request: WorkerRequest): Promise<unknown> {
    *  shape the caller wants (the RNA door). */
   const ask = engine.request.bind(engine);
   switch (request.op) {
+    case 'flush-document':
+      await saveDocument();
+      return { saved: true };
+    case 'history-begin':
+    case 'history-end':
+      return ask({ op: request.op });
+    case 'history-step':
+      return ask({ op: 'history-step', token: request.token, direction: request.direction });
     case 'execute':
       // Code about to run may open a file the host wrote since the last call.
       await stageProjectFiles(files, projectRoot);
-      return session.execute(request.code);
+      {
+        const answer = await ask({ op: 'execute', code: request.code, history: request.history ?? true,
+          label: request.label ?? 'Blender Python' }) as {
+          error?: string; result: string;
+        };
+        return answer.error ? `Error executing code: ${answer.error}` : `Code executed successfully: ${answer.result}`;
+      }
     case 'present':
       // Straight through to `session.py`'s own `present` op — the worker adds
       // nothing, and a capture-less present answers `{ presented, revision }`.
@@ -517,6 +508,7 @@ async function handle(request: WorkerRequest): Promise<unknown> {
     case 'rna-set':
       return ask({
         op: 'rna-set',
+        history: request.history !== false,
         path: request.path,
         property: request.property,
         value: request.value,
@@ -626,23 +618,39 @@ function reportMemory(): void {
   if (bytes !== null) post({ op: 'memory', bytes });
 }
 
-self.onmessage = async (event: MessageEvent<WorkerRequest>) => {
+self.onmessage = (event: MessageEvent<WorkerRequest>) => {
   const request = event.data;
   if (request.op === 'present-result') {
-    await handle(request);
+    void handle(request);
     return;
   }
-  // Held across the WHOLE call, so the document's save timer can tell "the
-  // session is quiet" from "a script is still running".
-  callsInFlight += 1;
+  void enqueue(() => answerRequest(request));
+};
+
+async function answerRequest(request: WorkerRequest): Promise<void> {
   try {
-    post({ id: request.id, result: await handle(request) });
+    const result = await handle(request);
+    if (documentDirty) await saveDocument();
+    await reportHistory();
+    post({ id: request.id, result });
   } catch (error) {
-    post({ id: request.id, error: describeThrown(error) });
-  } finally {
-    callsInFlight -= 1;
+    // A failed history drain must never strand the request's promise. Preserve
+    // both failures: the edit may have changed Blender before either failed.
+    let message = describeThrown(error);
+    try {
+      await reportHistory();
+    } catch (historyError) {
+      message += `\nUnable to deliver Blender history: ${describeThrown(historyError)}`;
+    }
+    post({ id: request.id, error: message });
   }
   // AFTER the answer, never before it: the reading is a passenger and must not
   // sit between a finished call and the reply the caller is waiting on.
   reportMemory();
-};
+}
+
+async function reportHistory(): Promise<void> {
+  if (!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.0",
+  "version": "0.1.2",
   "publishConfig": {
     "access": "public"
   },

package/wasm/essentials.json

@@ -0,0 +1,112 @@
+{
+  "sourceRepository": "https://github.com/volter-ai/blender",
+  "source": "94d8f20b225d51755a0a93a7fdf1e0cd9f53d09c",
+  "license": "CC0-1.0",
+  "licenseFile": "LICENSE",
+  "bytes": 11821256,
+  "sha256": "4f95016f965b1fd3542a4ae58160c1cb3254027b567111d2a4d23e447f27b7e2",
+  "files": [
+    {
+      "path": "LICENSE",
+      "offset": 0,
+      "bytes": 7048,
+      "sha256": "a2010f343487d3f7618affe54f789f5487602331c0a8d03f49e9a7c547cf0499"
+    },
+    {
+      "path": "blender_assets.cats.txt",
+      "offset": 7048,
+      "bytes": 5933,
+      "sha256": "fe62add99a5201173665682ceeeb606aef646eb81b6cadecfb7120ebb6e1def8"
+    },
+    {
+      "path": "brushes/essentials_brushes-curve_sculpt.blend",
+      "offset": 12981,
+      "bytes": 827070,
+      "sha256": "de873a20947e1fb7f19675b0f0c79dcdb9d58a75e5193aa2606f8ce0cc0b15f1"
+    },
+    {
+      "path": "brushes/essentials_brushes-gp_draw.blend",
+      "offset": 840051,
+      "bytes": 497193,
+      "sha256": "0596dce9286b824c31af67197b96e83a0c4a42ce2dbb36f40dfc8ecab3fe9f06"
+    },
+    {
+      "path": "brushes/essentials_brushes-gp_sculpt.blend",
+      "offset": 1337244,
+      "bytes": 357873,
+      "sha256": "235631a858c91b5cdaf70240ce0ed15bff11ef4474767e983d169a1bbf4723f6"
+    },
+    {
+      "path": "brushes/essentials_brushes-gp_vertex.blend",
+      "offset": 1695117,
+      "bytes": 245965,
+      "sha256": "ee1e9eee2cb898c3e95dbe2c059a51d4a5ec863a0d9bbd8ea1beb7d6a20bed06"
+    },
+    {
+      "path": "brushes/essentials_brushes-gp_weight.blend",
+      "offset": 1941082,
+      "bytes": 196914,
+      "sha256": "ec19a0cbca6a8413c45a25994a3db0ce1c7c8bd002d1968069dc1b558ce8500e"
+    },
+    {
+      "path": "brushes/essentials_brushes-mesh_sculpt.blend",
+      "offset": 2137996,
+      "bytes": 2715184,
+      "sha256": "f8b15126658f5a4ac455b0826a7eeae026576ed7c2ac45562d8880383fbf03bf"
+    },
+    {
+      "path": "brushes/essentials_brushes-mesh_texture.blend",
+      "offset": 4853180,
+      "bytes": 972168,
+      "sha256": "6c57caeaaa1f16e175783a2fbcbabf8772e108414edca92cad52bcc8019110f8"
+    },
+    {
+      "path": "brushes/essentials_brushes-mesh_vertex.blend",
+      "offset": 5825348,
+      "bytes": 600678,
+      "sha256": "7b4b5d973f1bc4a06f7553afc96c7cb0bd9a0c17921cd65903b40395eccd3300"
+    },
+    {
+      "path": "brushes/essentials_brushes-mesh_weight.blend",
+      "offset": 6426026,
+      "bytes": 404988,
+      "sha256": "67b141b9f15b0709f954fcd5e1d846deb95f5da8615ae70f0adcfacb3025d87f"
+    },
+    {
+      "path": "nodes/compositing_nodes_essentials.blend",
+      "offset": 6831014,
+      "bytes": 1329516,
+      "sha256": "8f40be4b9a811f2f4845c117eafb78c0b61dac7d943fb81fec2c7a450c6ac4b4"
+    },
+    {
+      "path": "nodes/geometry_nodes_dynamics_assets.blend",
+      "offset": 8160530,
+      "bytes": 307332,
+      "sha256": "a2e6b4013abfc3b9355927e33b2ae5af2182dc079e820041124652a75ce7b100"
+    },
+    {
+      "path": "nodes/geometry_nodes_essentials.blend",
+      "offset": 8467862,
+      "bytes": 696907,
+      "sha256": "4592ec2a51b1adbd87467812979ddebb09f6606a49aa75549fdd2b40b7ffac86"
+    },
+    {
+      "path": "nodes/principal_components.blend",
+      "offset": 9164769,
+      "bytes": 84028,
+      "sha256": "91cb8cada033daab6c6fbb8aef4767782cf75be867a0c2f38ced742160f38a39"
+    },
+    {
+      "path": "nodes/procedural_hair_node_assets.blend",
+      "offset": 9248797,
+      "bytes": 2488396,
+      "sha256": "b69d8bd8975b9db7f89693f8f19dd7fcb241f5a3786d2edfb0a243e91c1109bb"
+    },
+    {
+      "path": "nodes/shading_nodes_essentials.blend",
+      "offset": 11737193,
+      "bytes": 84063,
+      "sha256": "ffdaf64a4777233f6e47799bad17825a6c1e07c500eb1d9d0c23997f745327ee"
+    }
+  ]
+}