@volter/blender-engine 0.1.8 → 0.1.10

package/browser/blender-emscripten-engine.mts

@@ -193,9 +193,9 @@ export async function startEmscriptenBlenderEngine(
   // editor's console door is for conditions somebody must resolve, so only the
   // session's OWN named conditions go there.
   const say = (_level: 'log' | 'error', text: string) => {
-    if (text.startsWith('@@VGAI-READY ')) readyLine = text.slice('@@VGAI-READY '.length);
+    if (text.startsWith('@@VOLTER-READY ')) readyLine = text.slice('@@VOLTER-READY '.length);
     options.log(
-      text.startsWith('@@VGAI-WARN') || text.startsWith('@@VGAI-ERROR') ? 'error' : 'log',
+      text.startsWith('@@VOLTER-WARN') || text.startsWith('@@VOLTER-ERROR') ? 'error' : 'log',
       text,
     );
   };
@@ -224,11 +224,11 @@ export async function startEmscriptenBlenderEngine(
           BLENDER_SYSTEM_PYTHON: '/bw/python',
           BLENDER_SYSTEM_SCRIPTS: '/bw/scripts',
           BLENDER_SYSTEM_DATAFILES: '/bw/datafiles',
-          VGAI_SESSION_ROOT: SESSION_ROOT,
+          VOLTER_SESSION_ROOT: SESSION_ROOT,
           HOME: '/root',
           TMPDIR: '/tmp',
         });
-        // VGAI_EXPORT_BUFFER_PATH IS DELIBERATELY UNSET. This engine reads the
+        // VOLTER_EXPORT_BUFFER_PATH IS DELIBERATELY UNSET. This engine reads the
         // arena off `HEAPU8`; asking the door to also write it to a file would
         // cost this skew a megabyte-scale write per present for bytes it
         // already has (`session.py`, EXPORT_BUFFER_PATH).

package/browser/blender-engine.mts

@@ -29,7 +29,7 @@
  * and that IS the answer. There is no manifest field, no setting and no flag,
  * because nothing a user does should depend on the skew -- if it did, the
  * skews would be answering differently, which the ruling forbids.
- * `VGAI_BLENDER_WASM_DIR` is the existing door for pointing the editor at a
+ * `VOLTER_BLENDER_WASM_DIR` is the existing door for pointing the editor at a
  * different build and is how the substrate skew is reached in development.
  *
  * WHAT DIFFERS, and it is four things, all below this line:
@@ -43,7 +43,7 @@
  * implementation over {@link BlenderFiles}.
  */
 
-export const SESSION_ROOT = '/work/.vgai-session';
+export const SESSION_ROOT = '/work/.volter-session';
 export const SESSION_SCRIPT = `${SESSION_ROOT}/session.py`;
 
 /**
@@ -137,7 +137,7 @@ export interface BlenderEngine {
   readonly bootMs: number;
   /** The engine's memory in bytes, now. Linear memory on the standalone skew;
    *  null where the skew cannot see the module's memory from the host, which
-   *  is the WALI case and is why `vgai status` prints "unreported" rather than
+   *  is the WALI case and is why `volter-model-editor status` prints "unreported" rather than
    *  a zero. */
   memoryBytes(): number | null;
   /** Bytes of packed `.data` payload handed back after boot, or null when the
@@ -303,7 +303,7 @@ export function openSessionChannel(
    *
    * The loop below waits for `out/<id>.done` and nothing else. When the
    * program behind the directory DIES, that file is never written, so the
-   * call waits forever: `vgai status` reports it IN FLIGHT for as long as
+   * call waits forever: `volter-model-editor status` reports it IN FLIGHT for as long as
    * anyone looks, `blender-start` keeps answering from the host's cached
    * banner, and the harness has no answer to time out against. MEASURED
    * 2026-09-19 three times on the WALI skew -- 507 s, 621 s and 964 s of a
@@ -404,7 +404,7 @@ export function openSessionChannel(
           `Blender is gone, so this call will never be answered: ${ended}. ` +
             'The session keeps its directory and its cached banner, so every later call would ' +
             'wait on the same missing answer; start a new program with `blender-start {fresh: true}` ' +
-            '(`VGAI_BLENDER_FRESH_SESSION=1` for the battery harness).',
+            '(`VOLTER_BLENDER_FRESH_SESSION=1` for the battery harness).',
         );
       await sleep(pollDelay(performance.now() - began));
     }

package/browser/blender-wali-engine.mts

@@ -245,9 +245,9 @@ export async function startWaliBlenderEngine(
       // `--python-use-system-env` below is what makes Blender read the
       // variable at all.
       PYTHONPATH: `${RESOURCES}/python/lib/numpy313.zip:${RESOURCES}/python/lib/wheels313.zip`,
-      VGAI_SESSION_ROOT: SESSION_ROOT,
+      VOLTER_SESSION_ROOT: SESSION_ROOT,
       // THE ARENA'S DOOR ON THIS SKEW. See `readArena`.
-      VGAI_EXPORT_BUFFER_PATH: ARENA_PATH,
+      VOLTER_EXPORT_BUFFER_PATH: ARENA_PATH,
     },
     threadPoolSize: workers.pool,
     // Blender talks to nothing. The editor's own routes are this worker's, not
@@ -260,13 +260,13 @@ export async function startWaliBlenderEngine(
   const say = (text: string) => {
     for (const line of text.split('\n')) {
       if (line === '') continue;
-      if (line.startsWith('@@VGAI-READY ')) readyLine = line.slice('@@VGAI-READY '.length);
+      if (line.startsWith('@@VOLTER-READY ')) readyLine = line.slice('@@VOLTER-READY '.length);
       // BLENDER'S OWN STREAMS ARE PAGE OUTPUT, NOT EDITOR-CONSOLE CONDITIONS
       // -- the same rule as the standalone engine, and for the same measured
       // reason: only the session's own named conditions belong in the set an
       // agent must drive to zero.
       options.log(
-        line.startsWith('@@VGAI-WARN') || line.startsWith('@@VGAI-ERROR') ? 'error' : 'log',
+        line.startsWith('@@VOLTER-WARN') || line.startsWith('@@VOLTER-ERROR') ? 'error' : 'log',
         line,
       );
     }
@@ -304,7 +304,7 @@ export async function startWaliBlenderEngine(
         // only defensible because the CALLER can degrade VISIBLY; without this
         // the degrade is silent, and before it existed the notice reached a
         // nested worker's devtools console and nothing else.
-        onDiagnostic: (message: string) => options.log('error', `@@VGAI-ERROR ${message}`),
+        onDiagnostic: (message: string) => options.log('error', `@@VOLTER-ERROR ${message}`),
       },
     )
     .then(
@@ -316,7 +316,7 @@ export async function startWaliBlenderEngine(
       },
     )
     .finally(() => {
-      if (ended !== null) options.log('error', `@@VGAI-ERROR the Blender program ended: ${ended}`);
+      if (ended !== null) options.log('error', `@@VOLTER-ERROR the Blender program ended: ${ended}`);
     });
 
   while (readyLine === null) {
@@ -352,7 +352,7 @@ export async function startWaliBlenderEngine(
     readArena: () => filesystem.readFile(ARENA_PATH),
     bootMs,
     // The module's memory is the program worker's and no door reports it.
-    // Null rather than zero: `vgai status` prints "unreported", which is true,
+    // Null rather than zero: `volter-model-editor status` prints "unreported", which is true,
     // where a zero would be a measurement that was never taken.
     memoryBytes: () => null,
     // There is no packed payload on this skew: Blender's runtime tree is

package/browser/rna.ts

@@ -8,7 +8,7 @@
  * (`bl_rna.properties`) — the ruling's "everything Blender SHOWS about a
  * datablock, we show, in OUR panels, read from the engine through bpy and RNA"
  * (ARCHITECTURE-CORE §Blender north star, "Inspection parity, not editing
- * parity"). Nothing in this file is a vgai invention over RNA: every field is
+ * parity"). Nothing in this file is a volter invention over RNA: every field is
  * a `PropertyRNA` member, a `bpy.types` name, or an address `path_from_id()`
  * produced.
  */
@@ -241,7 +241,7 @@ export interface BlenderRnaWrite {
 // session's scene, as rows (WORK.md §Blender in the tab is Blender,
 // "Inspection parity", I3). Every field below is Blender's own — a `TSE_*`
 // element type, an `ICON_*` name `tree_element_get_icon` picks, a restriction
-// column `outliner_draw_restrictbuts` draws — and nothing here is a vgai
+// column `outliner_draw_restrictbuts` draws — and nothing here is a volter
 // invention over the Outliner.
 
 /**

package/browser/runtime.ts

@@ -69,7 +69,7 @@ export interface PresentAnswer {
  * Read by anything that has to say WHERE a byte came from rather than merely
  * display it — `blender-list-files` answers with it, so the CLI's write-back
  * door can record which session's model a mirrored file was exported from
- * (`packages/vgai-cli/src/blender-mcp.ts`, class Mirror). Null until the
+ * (`packages/volter-cli/src/blender-mcp.ts`, class Mirror). Null until the
  * session's first present.
  */
 export interface PresentedState {
@@ -186,7 +186,7 @@ export class BlenderRuntime {
       // The page console is the editor's ledger (`installEditorConsoleReporting`
       // captures it, source-blind), and this package may import nothing of the
       // editor to say it any other way. Without this line the failure reached
-      // a toast and `vgai console` read 0/0 while no Model document could open
+      // a toast and `volter-model-editor console` read 0/0 while no Model document could open
       // (measured 2026-09-20 from a registry install).
       console.error(error.message);
       for (const id of [...this.#pending.keys()]) this.#settled(id);

package/browser/session.py

@@ -122,7 +122,7 @@ import _blender_web
 _UNKNOWN_GEOMETRY = "RUNTIME_FRAME_UNKNOWN_GEOMETRY"
 _UNKNOWN_IMAGE = "RUNTIME_FRAME_UNKNOWN_IMAGE"
 
-ROOT = os.environ.get("VGAI_SESSION_ROOT", "/work/.vgai-session")
+ROOT = os.environ.get("VOLTER_SESSION_ROOT", "/work/.volter-session")
 IN = os.path.join(ROOT, "in")
 OUT = os.path.join(ROOT, "out")
 ASK = os.path.join(ROOT, "ask")
@@ -142,7 +142,7 @@ REPLY = os.path.join(ROOT, "reply")
 # whose host cannot reach the module's memory at all
 # (`blender-wali-engine.mts`), where the file is not a fallback but the
 # native door onto the same bytes.
-EXPORT_BUFFER_PATH = os.environ.get("VGAI_EXPORT_BUFFER_PATH", "")
+EXPORT_BUFFER_PATH = os.environ.get("VOLTER_EXPORT_BUFFER_PATH", "")
 _real_stderr = sys.stderr
 
 
@@ -172,7 +172,7 @@ def _prepare_directories():
         except FileExistsError:
             pass
         except OSError as error:
-            _say("@@VGAI-ERROR cannot create %s: %r" % (directory, error))
+            _say("@@VOLTER-ERROR cannot create %s: %r" % (directory, error))
         try:
             os.chmod(directory, 0o777)
         except OSError:
@@ -215,7 +215,7 @@ def warn(what):
         return
     _WARNED.add(what)
     _WARNINGS.append(what)
-    _say("@@VGAI-WARN " + what)
+    _say("@@VOLTER-WARN " + what)
 
 
 # ---------------------------------------------------------------- the world
@@ -523,6 +523,10 @@ def draw_camera(obj):
         "shift_x": float(camera.shift_x),
         "shift_y": float(camera.shift_y),
         "matrix": [[float(v) for v in row] for row in obj.matrix_world],
+        # What the 3D View's camera view darkens outside the frame (`drawviewborder`).
+        "passepartout": float(camera.passepartout_alpha) if camera.show_passepartout else 0.0,
+        # The size the overlay draws the camera at (`Camera.display_size`, `cam->drawsize`).
+        "display_size": float(camera.display_size),
     }
 
 
@@ -732,6 +736,107 @@ def _refusal(node):
     return None
 
 
+
+def _empty_display(obj):
+    """An empty's display (`overlay_empty.hh`): its type and size, and for an image empty the
+    picture, where it sits on the object (`empty_image_offset`), how it meets depth, which side
+    shows, in which projections, its opacity when it blends, the object colour the picture is
+    multiplied by (`ucolor`) and whether the image stores premultiplied alpha."""
+    display = {"display": obj.empty_display_type, "size": float(obj.empty_display_size)}
+    if obj.empty_display_type == "IMAGE":
+        display["image"] = {
+            "name": obj.data.name if obj.data is not None else None,
+            "offset": [float(v) for v in obj.empty_image_offset],
+            "depth": obj.empty_image_depth,
+            "side": obj.empty_image_side,
+            "perspective": bool(obj.show_empty_image_perspective),
+            "orthographic": bool(obj.show_empty_image_orthographic),
+            "axis_aligned": bool(obj.show_empty_image_only_axis_aligned),
+            "opacity": float(obj.color[3]) if obj.use_empty_image_alpha else None,
+            "tint": [float(v) for v in obj.color[:3]],
+            "premultiplied": obj.data is not None and obj.data.alpha_mode == "PREMUL",
+        }
+    return display
+
+
+def _saved_view():
+    """The 3D View the file saved, which is where Blender opens it: the `Modeling` workspace's
+    (this editor's Model workspace is Blender's Modeling), else the first 3D View any screen
+    holds. `RegionView3D`'s pivot, rotation (view to world, `(w, x, y, z)`), distance and
+    projection (`PERSP`, `ORTHO`, or `CAMERA` for a view through the scene camera), and the
+    `View3D`'s lens."""
+    workspace = bpy.data.workspaces.get("Modeling")
+    screens = list(workspace.screens) if workspace is not None else []
+    screens.extend(bpy.data.screens)
+    for screen in screens:
+        for area in screen.areas:
+            if area.type != "VIEW_3D":
+                continue
+            space = area.spaces[0]
+            region = space.region_3d
+            return {
+                "lens": float(space.lens),
+                "location": [float(v) for v in region.view_location],
+                "rotation": [float(v) for v in region.view_rotation],
+                "distance": float(region.view_distance),
+                "perspective": region.view_perspective,
+            }
+    return None
+
+
+def _subject_line(scene, view_layer):
+    """The 3D Viewport's second overlay line, as `draw_selected_name` (`view3d_draw.cc`) writes it,
+    less the two parts that follow the playhead: the tab draws `(frame)` and the marker on it
+    from the frame it is showing, which during playback is not `frame_current` (written once, on
+    pause). Here: in Object Mode (or with nothing active) the active collection and a bar, then
+    the active object; outside Object Mode its data's name; the active edit or pose bone, or the
+    active shape key (` (Soloed)` when pinned). The scene's markers go with it, in list order,
+    for `BKE_scene_find_marker_name`. Blender tints the line on a keyframe; that colour is not
+    carried, and the ` (Viewer)` suffix belongs to a viewer path this tab does not show."""
+    parts = []
+    ob = view_layer.objects.active
+    if ob is None or ob.mode == "OBJECT":
+        # `BKE_collection_ui_name_get`: the master collection reads "Scene Collection", which is
+        # also what its RNA name returns.
+        parts.append(" " + view_layer.active_layer_collection.collection.name)
+        if ob is not None:
+            parts.append(" |")
+    if ob is not None:
+        parts.append(" " + ob.name)
+        if ob.mode != "OBJECT" and ob.data is not None:
+            parts.append(" | " + ob.data.name)
+        if ob.type == "ARMATURE":
+            arm = ob.data
+            if ob.mode == "EDIT":
+                if arm.edit_bones.active is not None:
+                    parts.append(" : " + arm.edit_bones.active.name)
+            elif ob.mode == "POSE" and arm.bones.active is not None and _bone_shown(arm.bones.active):
+                parts.append(" : " + arm.bones.active.name)
+        elif ob.type in ("MESH", "LATTICE", "CURVE"):
+            if ob.type == "MESH" and ob.mode == "WEIGHT_PAINT":
+                rig = ob.find_armature()
+                if rig is not None and rig.mode == "POSE":
+                    bone = rig.data.bones.active
+                    if bone is not None and _bone_shown(bone):
+                        parts.append(" : " + bone.name)
+            key = ob.active_shape_key if getattr(ob.data, "shape_keys", None) is not None else None
+            if key is not None:
+                parts.append(" : " + key.name)
+                if ob.show_only_shape_key:
+                    parts.append(" (Soloed)")
+    return {
+        "frame": int(scene.frame_current),
+        "body": "".join(parts),
+        "markers": [[int(m.frame), m.name] for m in scene.timeline_markers],
+    }
+
+
+def _bone_shown(bone):
+    """`ANIM_bonecoll_is_visible_actbone`: a bone in no collection, or in a visible one."""
+    collections = getattr(bone, "collections", None)
+    return not collections or any(c.is_visible for c in collections)
+
+
 class _GraphRefusal(Exception):
     pass
 
@@ -1231,9 +1336,13 @@ class Session:
         """
         scene = bpy.context.scene
         graphs = material_graphs(scene)
+        # An IMAGE EMPTY's picture travels with the graphs' images: the overlay draws it
+        # (`overlay_empty.hh` `image_sync`).
+        empty_images = {obj.data.name for obj in scene.objects
+                        if obj.type == "EMPTY" and obj.empty_display_type == "IMAGE" and obj.data is not None}
         options = {"session": self.session, "evaluate": True, "known": self._known,
                    "graph_materials": sorted(graphs),
-                   "graph_images": sorted({i for g in graphs.values() for i in g["images"]}),
+                   "graph_images": sorted({i for g in graphs.values() for i in g["images"]} | empty_images),
                    "graph_generated": sorted(n for n, g in graphs.items() if g["generated"])}
         # THE ARENA IS WRITTEN BEFORE THE ASK, and on a skew whose channel is
         # an ordered stream of filesystem patches that is the whole
@@ -1288,14 +1397,55 @@ class Session:
                 default_color = getattr(getattr(data, "color_attributes", None), "default_color_name", "")
                 if default_color:
                     row["default_color"] = default_color
+        # THE VIEWPORT DISPLAY of each material -- what Blender's Solid shading colours a surface
+        # by (`View3DShading.color_type` MATERIAL reads `Material.diffuse_color`, `roughness`,
+        # `metallic`; `workbench_world_light_lib.glsl`), not its node graph.
+        for entry in frame["materials"].values():
+            material = bpy.data.materials.get(entry.get("name", ""))
+            if material is not None:
+                entry["viewport"] = {
+                    "color": [float(v) for v in material.diffuse_color],
+                    "roughness": float(material.roughness),
+                    "metallic": float(material.metallic),
+                }
         frame["world"] = draw_world(scene)
         frame["cameras"] = {
             obj.name: draw_camera(obj) for obj in scene.objects if obj.type == "CAMERA"
         }
         frame["volumes"] = {}
+        # THE CAMERA A CAMERA VIEW LOOKS THROUGH (`view3d.view_camera`: the scene's, else a
+        # camera that is active, else the view layer's first) and the frame it draws, the
+        # render's shape with its pixel aspect.
+        render = scene.render
+        frame["camera_view"] = {
+            "scene_camera": scene.camera.name if scene.camera is not None else None,
+            "view_layer_cameras": [o.name for o in bpy.context.view_layer.objects if o.type == "CAMERA"],
+            "aspect": (render.resolution_x * render.pixel_aspect_x) / max(render.resolution_y * render.pixel_aspect_y, 1e-6),
+        }
+        # THE 3D CURSOR, `Scene.cursor`: where Blender's own "to 3D Cursor"
+        # operators place and snap, drawn by the tab as Blender's overlay does
+        # (`overlay_cursor.hh`). Its MATRIX, because the overlay's axis lines
+        # turn with the cursor's rotation in whichever `rotation_mode` it has.
+        frame["cursor"] = [[float(v) for v in row] for row in scene.cursor.matrix]
         # THE OVERLAYS, after the door's frame stands: `_weights` reads the
         # mesh's own revision out of it (see there), so it cannot run before.
         view_layer = bpy.context.view_layer
+        # THE VIEWPORT'S SUBJECT LINE and the units its grid step is named in: Blender composes
+        # both from the scene, so they come from here (`_subject_line`).
+        frame["subject"] = _subject_line(scene, view_layer)
+        # A LIGHT'S DISTANCES, for the overlay's direction line (`overlay_light.hh`: from
+        # `clipsta` to `att_dist` down the light's -Z, for a spot or an area light).
+        frame["light_distances"] = {
+            light.name: [float(light.shadow_buffer_clip_start), float(light.cutoff_distance)]
+            for light in bpy.data.lights
+        }
+        # WHAT THE OVERLAY DRAWS FOR AN EMPTY (`overlay_empty.hh`): its display type and size.
+        frame["empties"] = {obj.name: _empty_display(obj) for obj in scene.objects if obj.type == "EMPTY"}
+        frame["view"] = _saved_view()
+        frame["units"] = {
+            "system": scene.unit_settings.system,
+            "scale_length": float(scene.unit_settings.scale_length),
+        }
         frame["armatures"] = _armatures(view_layer)
         frame["weights"] = _weights(scene, view_layer, frame, self._known)
         warnings = list(frame.get("warnings", ()))
@@ -1670,11 +1820,11 @@ _ASK_SEQUENCE = [0]
 def _drop(path):
     """Remove one of THIS side's own channel files. A failure here means the
     ownership rule was broken by the other side, so it is named rather than
-    swallowed -- and named where `vgai console` reads it, not into a log."""
+    swallowed -- and named where `volter-model-editor console` reads it, not into a log."""
     try:
         os.unlink(path)
     except OSError as error:
-        _say("@@VGAI-WARN the session could not remove its own %s: %r" % (path, error))
+        _say("@@VOLTER-WARN the session could not remove its own %s: %r" % (path, error))
 
 
 def ask(payload):
@@ -1829,7 +1979,7 @@ def _assert_photographed_from(reported, position, target, up):
             )
 
 
-class VgaiRenderEngine(bpy.types.RenderEngine):
+class VolterRenderEngine(bpy.types.RenderEngine):
     """The scene's renderer, so `write_still`, `save_render` and Render Result
     behave as Blender's own.
 
@@ -1839,7 +1989,7 @@ class VgaiRenderEngine(bpy.types.RenderEngine):
     starts a path trace nobody asked for inside the tab.
     """
 
-    bl_idname = "VGAI_THREE"
+    bl_idname = "VOLTER_THREE"
     bl_label = "three.js"
     bl_use_preview = False
 
@@ -1937,7 +2087,7 @@ def _register_engine():
         ("BLENDER_WORKBENCH", "Workbench"),
     ):
         existing = _engine_class(identifier)
-        if existing is not None and issubclass(existing, VgaiRenderEngine):
+        if existing is not None and issubclass(existing, VolterRenderEngine):
             made.append(identifier)
             continue
         if existing is not None:
@@ -1948,8 +2098,8 @@ def _register_engine():
             else:
                 _release_from_owning_addon(existing)
         engine = type(
-            "Vgai" + identifier.title().replace("_", ""),
-            (VgaiRenderEngine,),
+            "Volter" + identifier.title().replace("_", ""),
+            (VolterRenderEngine,),
             {"bl_idname": identifier, "bl_label": label, "bl_use_preview": False},
         )
         try:
@@ -1965,17 +2115,17 @@ def _register_engine():
             # in the start reply and refused by name at the render, never a
             # warning on every boot.
             unavailable.append(identifier)
-    # `VGAI_THREE` is the engine under its own name, registered ONCE: this runs
+    # `VOLTER_THREE` is the engine under its own name, registered ONCE: this runs
     # again after every file load (the ids have to be retaken), and Blender
     # refuses a class it already holds -- which is not a capability anyone
     # lost, so it is not a warning.
-    if _engine_class(VgaiRenderEngine.bl_idname) is None:
+    if _engine_class(VolterRenderEngine.bl_idname) is None:
         try:
-            bpy.utils.register_class(VgaiRenderEngine)
+            bpy.utils.register_class(VolterRenderEngine)
         except Exception as error:  # noqa: BLE001
             warn("could not register the three.js engine: %s" % error)
-    if _engine_class(VgaiRenderEngine.bl_idname) is not None:
-        made.append(VgaiRenderEngine.bl_idname)
+    if _engine_class(VolterRenderEngine.bl_idname) is not None:
+        made.append(VolterRenderEngine.bl_idname)
     return made, unavailable
 
 
@@ -2548,7 +2698,7 @@ def _py_row(target, name, descriptor, owner):
     from what it answers -- an ID is a POINTER, a sequence of them a
     COLLECTION with its count and names, a scalar its scalar. A value no RNA
     type covers is not invented into one: the property is dropped, and
-    nothing here is a vgai field over Blender's data."""
+    nothing here is a volter field over Blender's data."""
     row = {
         "identifier": name,
         "name": name,
@@ -3744,7 +3894,7 @@ def _node_row(node):
 
 
 def _node_tree_of(path, material):
-    """WHICH TREE. Either an explicit RNA address (so a `vgai eval` can open a
+    """WHICH TREE. Either an explicit RNA address (so a `volter-model-editor eval` can open a
     world's or a group's tree with the engine's own spelling), or a material by
     name, or -- given neither -- the active object's active material, which is
     what Blender's own Shading header resolves (`space_node.py:89-93`,
@@ -4002,7 +4152,7 @@ def rna_rig(object_name=None):
     presented frame carries every object at once, and the presenter has to know
     which of its meshes are `THREE.SkinnedMesh`es before it builds them. Asking
     per object would be one round trip per mesh; asking by NAME stays available
-    for a `vgai eval` that wants to read one.
+    for a `volter-model-editor eval` that wants to read one.
     """
     scene_frame = int(bpy.context.scene.frame_current)
     if object_name:
@@ -4625,7 +4775,32 @@ def outliner_set(path, column, value):
         % (column, target.bl_rna.identifier, path))
 
 
+# REQUESTS THAT CAN REMOVE OBJECTS, watched: a removal is reported with its cause, because an
+# object that disappears without a named act is the loss this session must never hide. A scene
+# was once found emptied and saved over its file by a burst of three edits at boot, with nothing
+# recording which requests they were.
+_WATCHED_OPS = ("execute", "rna-set", "outliner-set", "history-step")
+
+
 def dispatch(request):
+    op = request.get("op")
+    if op not in _WATCHED_OPS:
+        return _dispatch_request(request)
+    before = {o.name for o in bpy.data.objects}
+    try:
+        return _dispatch_request(request)
+    finally:
+        removed = before - {o.name for o in bpy.data.objects}
+        if removed:
+            cause = {k: request[k] for k in ("label", "property", "column", "direction", "token", "path")
+                     if k in request}
+            if op == "execute":
+                cause["code"] = str(request.get("code", ""))[:160]
+            _say("@@VOLTER-WARN %s removed objects %s (%s); %d remain" % (
+                op, sorted(removed), json.dumps(cause), len(bpy.data.objects)))
+
+
+def _dispatch_request(request):
     op = request.get("op")
     if op == "history-begin":
         HISTORY.begin()
@@ -4690,14 +4865,14 @@ def _dispatch(request):
         except Exception as thrown:  # noqa: BLE001
             # LOUD, because a present that fails leaves the Model document
             # showing the state BEFORE this call and nothing else says so.
-            # `@@VGAI-PRESENT-FAILED` was not one of the prefixes the engines
+            # `@@VOLTER-PRESENT-FAILED` was not one of the prefixes the engines
             # escalate (`blender-emscripten-engine.mts:159`,
-            # `blender-wali-engine.mts:266` raise `@@VGAI-WARN`/`@@VGAI-ERROR`
+            # `blender-wali-engine.mts:266` raise `@@VOLTER-WARN`/`@@VOLTER-ERROR`
             # to the console and nothing else), so it logged at `log` level and
             # reached no counter -- measured 2026-09-19 (I4), when a throw in
             # the overlay walk froze the viewport through a dozen successful
-            # `blender-execute` calls with `vgai console` silent throughout.
-            _say("@@VGAI-ERROR the present after this call failed, so the Model document is "
+            # `blender-execute` calls with `volter-model-editor console` silent throughout.
+            _say("@@VOLTER-ERROR the present after this call failed, so the Model document is "
                  "showing the state before it: " + repr(thrown))
         return answer
     if op == "scene-info":
@@ -4740,14 +4915,14 @@ def _dispatch(request):
         except Exception as thrown:  # noqa: BLE001
             # LOUD, because a present that fails leaves the Model document
             # showing the state BEFORE this call and nothing else says so.
-            # `@@VGAI-PRESENT-FAILED` was not one of the prefixes the engines
+            # `@@VOLTER-PRESENT-FAILED` was not one of the prefixes the engines
             # escalate (`blender-emscripten-engine.mts:159`,
-            # `blender-wali-engine.mts:266` raise `@@VGAI-WARN`/`@@VGAI-ERROR`
+            # `blender-wali-engine.mts:266` raise `@@VOLTER-WARN`/`@@VOLTER-ERROR`
             # to the console and nothing else), so it logged at `log` level and
             # reached no counter -- measured 2026-09-19 (I4), when a throw in
             # the overlay walk froze the viewport through a dozen successful
-            # `blender-execute` calls with `vgai console` silent throughout.
-            _say("@@VGAI-ERROR the present after this call failed, so the Model document is "
+            # `blender-execute` calls with `volter-model-editor console` silent throughout.
+            _say("@@VOLTER-ERROR the present after this call failed, so the Model document is "
                  "showing the state before it: " + repr(thrown))
         return answer
     if op == "rna-set":
@@ -4761,14 +4936,14 @@ def _dispatch(request):
         except Exception as thrown:  # noqa: BLE001
             # LOUD, because a present that fails leaves the Model document
             # showing the state BEFORE this call and nothing else says so.
-            # `@@VGAI-PRESENT-FAILED` was not one of the prefixes the engines
+            # `@@VOLTER-PRESENT-FAILED` was not one of the prefixes the engines
             # escalate (`blender-emscripten-engine.mts:159`,
-            # `blender-wali-engine.mts:266` raise `@@VGAI-WARN`/`@@VGAI-ERROR`
+            # `blender-wali-engine.mts:266` raise `@@VOLTER-WARN`/`@@VOLTER-ERROR`
             # to the console and nothing else), so it logged at `log` level and
             # reached no counter -- measured 2026-09-19 (I4), when a throw in
             # the overlay walk froze the viewport through a dozen successful
-            # `blender-execute` calls with `vgai console` silent throughout.
-            _say("@@VGAI-ERROR the present after this call failed, so the Model document is "
+            # `blender-execute` calls with `volter-model-editor console` silent throughout.
+            _say("@@VOLTER-ERROR the present after this call failed, so the Model document is "
                  "showing the state before it: " + repr(thrown))
         return answer
     if op == "save-document":
@@ -4796,7 +4971,7 @@ 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,
+_say("@@VOLTER-READY " + json.dumps({"blender": bpy.app.version_string, "engines": ENGINES,
                                    "unavailableEngines": UNAVAILABLE_ENGINES}))
 
 # Markers already dispatched, and the answers whose `out/` files this loop
@@ -4879,7 +5054,7 @@ try:
 except BaseException as _thrown:  # noqa: BLE001
     # The one place a channel death can still be named. Without this the
     # program ends 0 and the page reports only that Blender is gone.
-    _say("@@VGAI-ERROR the session's channel loop raised %s: %s -- the session is over and "
+    _say("@@VOLTER-ERROR the session's channel loop raised %s: %s -- the session is over and "
          "every outstanding call will go unanswered. %s"
          % (type(_thrown).__name__, _thrown, traceback.format_exc().replace("\n", " | ")))
     raise

package/browser/three/attach-presenter.ts

@@ -1,7 +1,7 @@
 /**
  * ONE PRESENTER, ATTACHED TO ONE BLENDER (WS-AC, cut 3).
  *
- * `vgai_three.py` ships inside our Blender and turns every
+ * `volter_three.py` ships inside our Blender and turns every
  * `bpy.ops.render.render` into an ASK on a directory it owns; this is the
  * other half, for a host that holds that directory as a filesystem in its own
  * realm. It is the whole of what a host must do: hand it the filesystem, the

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

@@ -823,15 +823,24 @@ class Compiler {
           if (extension === 'CLIP')
             body.push(`if (any(lessThan(${co}.xy, vec2(0.0))) || any(greaterThan(${co}.xy, vec2(1.0)))) { ${color} = vec4(0.0); ${alpha} = 0.0; }`);
         }
-        // node_shader_gpu_tex_image's Color output, for three's straight-alpha
-        // upload: cleared for ignored/packed/data alpha; premultiplied (and
-        // cleared) when Alpha is used; straight otherwise.
+        // node_shader_gpu_tex_image's Color output over the file's own texels (straight, or
+        // premultiplied for a PREMUL image, as Blender's GPU texture holds them): alpha cleared for
+        // ignored, packed or data alpha; otherwise straight when Alpha is used, so a factor does
+        // not multiply it in twice, and premultiplied when it is not. Measured in Blender 5.2's
+        // EEVEE: a straight red texel at alpha 0.5 emits 0.502 with Alpha unused, 1.0 with it used.
+        // A PREMUL sRGB image differs: the sampler decodes the premultiplied bytes, `decode(r·a)`,
+        // where Blender's texture holds `linear(r)·a`, so its partly transparent texels read darker.
         const mode = prop<string>(node, 'image_alpha_mode');
         const alphaUsed = this.uses(key, 1);
-        if (mode === 'NONE' || mode === 'CHANNEL_PACKED' || prop<boolean>(node, 'image_is_data') || !alphaUsed)
-          body.push(`${outs([0])}.a = 1.0;`);
+        const c = outs([0]);
+        if (mode === 'NONE' || mode === 'CHANNEL_PACKED' || prop<boolean>(node, 'image_is_data'))
+          body.push(`${c}.a = 1.0;`);
+        else if (mode === 'PREMUL')
+          body.push(alphaUsed
+            ? `if (${c}.a != 0.0 && ${c}.a != 1.0) ${c}.rgb /= ${c}.a;`
+            : `${c}.a = 1.0;`);
         else
-          body.push(`${outs([0])} = vec4(${outs([0])}.rgb * ${outs([0])}.a, 1.0);`);
+          body.push(alphaUsed ? `${c}.a = 1.0;` : `${c}.rgb *= ${c}.a;`);
         break;
       }
     }

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

@@ -240,7 +240,7 @@ const BONE_SOLID_VERTEX = /* glsl */ `
  * ONLY THE `_fragment` HALF: three PREPENDS `colorspace_pars_fragment` to every
  * `ShaderMaterial` already, so including it here declared `LinearTransferOETF`,
  * `sRGBTransferEOTF` and `sRGBTransferOETF` twice and the whole program refused
- * to compile ("function already has a body", measured live in `vgai console`).
+ * to compile ("function already has a body", measured live in `volter-model-editor console`).
  */
 const BONE_SOLID_FRAGMENT = /* glsl */ `
   varying vec3 vColor;