@volter/blender-engine 0.1.129 → 0.1.131

package/browser/blender-emscripten-engine.mts

@@ -140,17 +140,45 @@ function moduleFiles(module: BlenderModule): BlenderFiles {
 }
 
 /**
- * BLENDER'S ARTIFACTS ARE FETCHED ONCE PER BUILD. The wasm (86 MB decoded), the
- * `.data` package (53 MB) and the Essentials payload are immutable for a build,
- * and the page keeps them in Cache Storage under the digest the artifact door
- * reports, so a later open reads them at the browser's own speed instead of
- * from the editor's server. Measured in the browser substrate, where that
- * server runs in the tab: the three took 7.2 s per open (4.2 s for the wasm
- * alone), about half of it decoding their brotli. A file the door gives no
- * digest for is fetched as it always was.
+ * BLENDER'S ARTIFACTS ARE FETCHED ONCE PER BUILD -- WHERE THE SERVER RUNS IN THE TAB. The wasm
+ * (86 MB decoded), the `.data` package (53 MB) and the Essentials payload are immutable for a
+ * build, and a page whose editor server runs in its own tab (browser-substrate; the door says so
+ * as `status.inTab`) keeps them in Cache Storage under the digest the door reports, so a later
+ * open reads them at the browser's own speed instead of from that server. Measured there: the
+ * three took 7.2 s per open (4.2 s for the wasm alone), about half of it decoding their brotli
+ * in the tab. A file the door gives no digest for is fetched as it always was.
+ *
+ * NOT WHERE THE SERVER IS A PROCESS ON THIS MACHINE. There the door answers from local disk over
+ * loopback with `no-cache` and an ETag, brotli as stored to a client that accepts it
+ * (`editor-blender/serving/blender-routes.ts`), so the browser's HTTP cache keeps the bytes as
+ * sent (~38 MB) and a repeat open is a 304 and the browser's own decode. Cache Storage there
+ * held a second, decoded copy (~144 MiB) per origin, and an editor origin is per project folder
+ * (`editor-<id>.localhost:<port>`, before 0.5.190 `127.0.0.1:<port>`): measured 2026-10-07 in
+ * one Chrome profile, 113 origins held ~16.3 GB. The HTTP cache is size-bounded and evicted by the browser; Cache Storage is
+ * kept until the origin deletes it. So such a page fetches through the HTTP cache and releases
+ * any copy an earlier build left in its origin ({@link releaseArtifactCache}).
+ *
+ * The cache was never made persistent (nothing here calls `navigator.storage.persist`), so it is
+ * best-effort storage Chrome may evict under storage pressure; it stays that way.
  */
 const ARTIFACT_CACHE = 'volter-blender-artifacts';
 
+/**
+ * RELEASE THIS ORIGIN'S COPY, on every boot of a page that does not keep one. A page can only
+ * delete its own origin's storage: an origin nobody opens again is reclaimed by Chrome's own
+ * eviction, not here. Best-effort and off the boot's path: a Cache Storage that cannot answer
+ * (see {@link cachedArtifact}) costs one line of page output, never the open.
+ */
+function releaseArtifactCache(note: (text: string) => void): void {
+  if (typeof caches === 'undefined') return;
+  void caches.delete(ARTIFACT_CACHE).then(
+    (released) => {
+      if (released) note(`Released Blender's artifact cache in this origin: this editor's server runs on this machine, so the browser's HTTP cache keeps the engine instead.`);
+    },
+    (error: unknown) => note(`Blender's artifact cache in this origin could not be released (${error instanceof Error ? error.message : String(error)}); Chrome may still evict it.`),
+  );
+}
+
 /**
  * THE CACHE SPEEDS AN OPEN UP; IT NEVER DECIDES WHETHER BLENDER OPENS. A Cache Storage that cannot
  * open or answer (measured 2026-10-07, headless Chrome on Windows: `caches.open` threw "Unexpected
@@ -202,10 +230,14 @@ export async function startEmscriptenBlenderEngine(
         'every response). This worker reports crossOriginIsolated=false.',
     );
   const glueUrl = artifactUrl('blender_browser.js');
-  const digests = status.digests ?? {};
-  const checkpoint = async (phase: string): Promise<void> => { await options.ask({ checkpoint: phase }); };
   // Page output, not an editor-console condition: nothing in the project can resolve the browser's cache.
   const noteCache = (text: string) => options.log('log', text);
+  // Digests are what `cachedArtifact` keeps a file under; with none, every file goes through the
+  // HTTP cache. Only a server in this tab is worth a Cache Storage copy (see ARTIFACT_CACHE).
+  const keepsArtifacts = status.inTab === true;
+  if (!keepsArtifacts) releaseArtifactCache(noteCache);
+  const digests = keepsArtifacts ? (status.digests ?? {}) : {};
+  const checkpoint = async (phase: string): Promise<void> => { await options.ask({ checkpoint: phase }); };
   const artifact = (file: string) => cachedArtifact(file, digests[file], () => checkpoint(`artifact/${file}`), noteCache);
   // The `.data` package is handed to the glue whole (`getPreloadedPackage`),
   // so it is read before the module starts; the wasm streams in beside it.

package/browser/blender-engine.mts

@@ -237,6 +237,9 @@ export interface BlenderArtifactStatus {
   missing: string[];
   /** Emscripten: each file's SHA-256 as it decodes, the key a page keeps it under. */
   digests?: Record<string, string>;
+  /** Emscripten: the server answering runs in this tab (browser-substrate). Only then are the
+   *  digests used to keep the files in Cache Storage; absent (an older server) means false. */
+  inTab?: boolean;
   /** WALI only: the `sha256-` SRI of `blender.wasm`, which the program loader
    *  requires for any non-blob URL. */
   integrity?: string;

package/browser/index.ts

@@ -1,4 +1,4 @@
-export type { CaptureRequest, FileEntry, RuntimeStart } from './protocol';
+export type { CaptureRequest, FileEntry, RuntimeStart, NativePreviewRequest, NativePreviewResult, NativeDocumentInfo, FileListSnapshot } from './protocol';
 export {
   BlenderRuntime,
   type BlenderRuntimeOptions,

package/browser/protocol.ts

@@ -12,6 +12,10 @@ export type WorkerRequest =
    *  empty and is created by the first save. */
   | { id: number; op: 'start'; project: string; document?: string }
   | { id: number; op: 'execute'; code: string; history?: boolean; label?: string }
+  /** A native Cycles photograph, isolated from authoring/history and the
+   * Three frame exporter. This is a preview request, not a modeling edit. */
+  | { id: number; op: 'native-preview'; width: number; height: number; samples: number; camera?: string }
+  | { id: number; op: 'list-files-snapshot'; path: string }
   | { id: number; op: 'scene-info' }
   | { id: number; op: 'object-info'; name: string }
   | { id: number; op: 'screenshot-view'; maxSize: number }
@@ -101,6 +105,11 @@ export type WorkerRequest =
 export type WorkerReply =
   | { op: 'frame-stream'; id: number; chunk: FrameChunk }
   | { op: 'document-dirty'; dirty: boolean }
+  /** THE DOCUMENT FOLLOWED BLENDER: a script's `save_as_mainfile` (or `open_mainfile`) left
+   *  another project `.blend` open, and the session's saves now go there
+   *  (`session.py::follow_open_file`). Both paths are project-relative. Posted before the
+   *  call's own answer, so the tab's handle already names the new file when the call returns. */
+  | { op: 'document-moved'; from: string; document: string }
   | { op: 'history'; entries: NativeHistoryEntry[] }
   | { id: number; result: unknown }
   | { id: number; error: string }
@@ -139,6 +148,36 @@ export type NativeHistoryEntry = { reset: true } | {
   resource: string | null;
 };
 
+export interface NativePreviewRequest {
+  width: number;
+  height: number;
+  samples: number;
+  camera?: string;
+}
+
+export interface NativePreviewResult {
+  path: string;
+  renderer: 'CYCLES';
+  session: string;
+  revision: number;
+  camera: string;
+  width: number;
+  height: number;
+  samples: number;
+  seconds: number;
+}
+
+export interface NativeDocumentInfo {
+  filepath: string;
+  session: string;
+  revision: number;
+}
+
+export interface FileListSnapshot {
+  entries: FileEntry[];
+  document: NativeDocumentInfo;
+}
+
 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. */
@@ -173,6 +212,12 @@ export interface RenderRequest {
   height: number;
   /** The camera's VERTICAL field of view, in degrees. */
   fov: number;
+  /** Authored camera clipping and sensor shift; not viewport navigation. */
+  clipStart?: number;
+  clipEnd?: number;
+  shiftX?: number;
+  shiftY?: number;
+  horizontalFit?: boolean;
   /** The scene's own view transform, as the three.js tone mapping of the same
    *  NAME (`bpy/_render_three.py`). A transform with no curve here never
    *  reaches this point: Python refuses it. */

package/browser/runtime.ts

@@ -12,6 +12,9 @@ import type {
   WorkerReply,
   WorkerRequest,
   NativeHistoryEntry,
+  NativePreviewRequest,
+  NativePreviewResult,
+  FileListSnapshot,
 } from './protocol';
 import type {
   BlenderActionClip,
@@ -49,6 +52,11 @@ export interface BlenderRuntimeOptions {
     capture?: CaptureRequest,
   ): Promise<PresentAnswer> | PresentAnswer;
   log?(level: 'log' | 'warn' | 'error', text: string): void;
+  /** The session's document followed Blender to another project `.blend` (a script's Save As,
+   *  `protocol.ts`'s `document-moved`). Called after {@link BlenderRuntime.document} already
+   *  names the new file and before the call that moved it answers. An observer: a throw here
+   *  changes nothing. */
+  documentMoved?(moved: { readonly from: string; readonly document: string }): void;
 }
 
 /**
@@ -234,7 +242,9 @@ export class BlenderRuntime {
     return this.#project;
   }
 
-  /** The startup document owned by this worker, including while boot is pending. */
+  /** The document owned by this worker, including while boot is pending: the startup one, until
+   *  a script's Save As leaves Blender holding another project `.blend` and the session follows
+   *  it there (`session.py::follow_open_file`). */
   get document(): string | null {
     return this.#document;
   }
@@ -285,6 +295,13 @@ export class BlenderRuntime {
     return (await this.#request({ op: 'execute', code, history, label })) as string;
   }
 
+  /** Render in native Cycles without changing or re-exporting the document.
+   * The returned PNG is read through readFile; no pixels cross the JSON relay. */
+  async nativePreview(request: NativePreviewRequest): Promise<NativePreviewResult> {
+    await this.#ready();
+    return await this.#request({ op: 'native-preview', ...request }) as NativePreviewResult;
+  }
+
   async historyGesture(op: 'history-begin' | 'history-end'): Promise<void> {
     await this.#ready();
     await this.#request({ op });
@@ -466,6 +483,13 @@ export class BlenderRuntime {
     return (await this.#request({ op: 'list-files', path })) as FileEntry[];
   }
 
+  /** Files and their native document identity, without executing Python or
+   * exporting/saving the model. The worker serializes this with authoring. */
+  async listFilesSnapshot(path: string): Promise<FileListSnapshot> {
+    await this.#ready();
+    return await this.#request({ op: 'list-files-snapshot', path }) as FileListSnapshot;
+  }
+
   /** The session and revision of the last frame this runtime forwarded; null
    *  before the first present. See {@link PresentedState}. */
   get presented(): PresentedState | null {
@@ -657,6 +681,14 @@ export class BlenderRuntime {
         this.#dirty = reply.dirty;
         return;
       }
+      if (reply.op === 'document-moved') {
+        // The worker already saves to the new file; this handle must claim it too, or the
+        // editor refuses the new file's own Model tab as a resource conflict.
+        this.#document = reply.document;
+        try { this.#options.documentMoved?.({ from: reply.from, document: reply.document }); }
+        catch { /* an observer cannot undo the move Blender made */ }
+        return;
+      }
       if (reply.op === 'history') {
         this.#options.history?.(reply.entries);
         return;

package/browser/session.py

@@ -207,13 +207,8 @@ def _load_post(_arg):
     # The DOOR resets its own revision table on LOAD_POST (it holds ID pointers
     # into the Main that just went away); this is the session's half.
     SESSION.forget()
-    # A factory reset reloads every add-on (`bpy.utils.load_scripts(reload_scripts=True)`
-    # runs inside `read_factory_settings`), and the Cycles add-on's own engine
-    # class comes back under `CYCLES` while ours is gone -- measured in the tab:
-    # after the battery's opening reset, `scene.render.engine = 'CYCLES'`
-    # resolved to `cycles.CyclesRender`, every render was a real path trace
-    # in wasm (35 s at 1280x720, 48 samples) and `_photograph` never ran. The
-    # engine ids are taken again on every load.
+    # Factory reset reloads add-ons. Preserve native Cycles and re-register
+    # only the headless GPU presenters we own.
     ENGINES[:], UNAVAILABLE_ENGINES[:] = _register_engine()
     HISTORY.reset()
 
@@ -413,7 +408,9 @@ def _describe_world_socket(root_socket, camera_ray):
                 vector = node.inputs.get("Vector")
                 if vector is not None and vector.links:
                     raise NotImplementedError("Linked World Sky Texture Vector")
-                return {"kind": "sky", "sky_model": model, "sun_elevation": float(node.sun_elevation),
+                return {"kind": "sky", "sky_model": model, "sun_disc": bool(node.sun_disc),
+                        "sun_size": float(node.sun_size), "sun_intensity": float(node.sun_intensity),
+                        "sun_elevation": float(node.sun_elevation),
                         "sun_rotation": float(node.sun_rotation), "altitude": float(node.altitude),
                         "air_density": float(node.air_density), "aerosol_density": float(node.aerosol_density),
                         "ozone_density": float(node.ozone_density)}
@@ -608,7 +605,7 @@ _GRAPH_NODES = frozenset((
     "ShaderNodeGamma", "ShaderNodeRGBToBW", "ShaderNodeSeparateColor", "ShaderNodeCombineColor",
     "ShaderNodeVectorRotate", "ShaderNodeFresnel", "ShaderNodeLayerWeight", "ShaderNodeBump",
     "ShaderNodeNormalMap", "ShaderNodeNewGeometry", "ShaderNodeVertexColor", "ShaderNodeAttribute",
-    "ShaderNodeRGBCurve", "ShaderNodeVectorCurve", "ShaderNodeFloatCurve", "ShaderNodeObjectInfo",
+    "ShaderNodeRGBCurve", "ShaderNodeVectorCurve", "ShaderNodeFloatCurve", "ShaderNodeObjectInfo", "ShaderNodeParticleInfo",
 ))
 # The surfaces whose inputs map onto the presenter's standard material, and
 # the inputs of each the presenter reads from a graph.
@@ -937,6 +934,8 @@ class _MaterialGraph:
             return self.source(stack[:-1], outer_socket)
         if kind not in _GRAPH_NODES:
             raise _GraphRefusal("%s (%s) is not compiled by the presenter" % (node.name, kind))
+        if kind == "ShaderNodeParticleInfo" and socket.name != "Random":
+            raise _GraphRefusal("Particle Info output %s is not compiled by the presenter" % socket.name)
         refusal = _refusal(node)
         if refusal is not None:
             raise _GraphRefusal(refusal)
@@ -1164,6 +1163,91 @@ def _object_info_random(name):
     return struct.unpack("f", struct.pack("f", c / 4294967296.0))[0]
 
 
+def _particle_info_random(index=0):
+    """Cycles Particle Info Random: hash_uint2(particle.index, 0).
+
+    Native sync_dupli_particle excludes child particles; they and objects
+    without a particle record use the zero-index dummy KernelParticle.
+    This is distinct from Object Info's placement random_id.
+    """
+    import struct
+    mask = 0xffffffff
+    a = (0xdeadbeef + 21 + index) & mask
+    b = c = (0xdeadbeef + 21) & mask
+    def rotate(x, bits):
+        return ((x << bits) | (x >> (32 - bits))) & mask
+    c = ((c ^ b) - rotate(b, 14)) & mask
+    a = ((a ^ c) - rotate(c, 11)) & mask
+    b = ((b ^ a) - rotate(a, 25)) & mask
+    c = ((c ^ b) - rotate(b, 16)) & mask
+    a = ((a ^ c) - rotate(c, 4)) & mask
+    b = ((b ^ a) - rotate(a, 14)) & mask
+    c = ((c ^ b) - rotate(b, 24)) & mask
+    return struct.unpack("f", struct.pack("f", c / 4294967296.0))[0]
+
+
+def _depsgraph_placements(frame, depsgraph):
+    """Placement metadata only; every vertex stays in the native C++ arena.
+
+    Keep this table separate from authoring objects. No realization, datablock
+    edits, vertex arrays or generated scene objects.
+    """
+    import struct
+    by_name = {row["name"]: row for row in frame["objects"]}
+    for row in frame["objects"]:
+        source = bpy.data.objects.get(row["name"])
+        if source is not None:
+            row["shadow_visible"] = bool(source.visible_shadow)
+    # Frame-local native addresses are comparison tokens, not authoring IDs.
+    # Consume them here so neither the presenter nor saved projects retain them.
+    geometry = frame.pop("instance_geometry", {})
+    placements = []
+    for instance in depsgraph.object_instances:
+        source = instance.object.original
+        row = by_name.get(source.name)
+        if not instance.is_instance:
+            if row is not None:
+                row["render_visible"] = row["render_visible"] and not source.hide_render
+                row["viewport_show_self"] = bool(instance.show_self)
+                row["render_show_self"] = not source.is_instancer or source.show_instancer_for_render
+            continue
+        if not instance.show_self:
+            continue
+        if (instance.instance_object is not None and instance.object.data != instance.instance_object.data and
+                (instance.object.data is None or geometry.get(source.name) != instance.object.data.as_pointer())):
+            raise NotImplementedError("Depsgraph instance geometry differs from its native source: %s" % source.name)
+        if row is None or (source.type == "MESH" and row["mesh"] is None):
+            raise NotImplementedError("Depsgraph instance source has no native exported geometry: %s" % source.name)
+        if row["mesh"] is None:
+            if source.type not in ("EMPTY", "CAMERA"):
+                warn("Depsgraph instance %r of type %s is not drawn" % (source.name, source.type))
+            continue
+        owner = instance.parent.original if instance.parent is not None else None
+        owner_row = by_name.get(owner.name) if owner is not None else None
+        if owner is not None and owner_row is None:
+            raise NotImplementedError("Depsgraph instance owner is not exported: %s" % owner.name)
+        persistent = list(instance.persistent_id)
+        particle_index = persistent[0]
+        psys = instance.particle_system
+        if psys is None or not 0 <= particle_index < len(psys.particles):
+            particle_index = 0
+        random = struct.unpack("f", struct.pack("f", (int(instance.random_id) & 0xffffffff) / 4294967296.0))[0]
+        placements.append({
+            "id": "@instance:" + json.dumps([owner.name if owner else None, source.name, persistent], separators=(",", ":"), ensure_ascii=False),
+            "source": row["id"], "owner": owner_row["id"] if owner_row is not None else None,
+            "matrix": [[float(v) for v in r] for r in instance.matrix_world],
+            "visible": True,
+            "render_visible": not source.hide_render and (owner is None or not owner.hide_render) and
+                (owner_row is None or bool(owner_row["render_visible"])),
+            # Cycles intersects source and instancer ray visibility.
+            "shadow_visible": bool(source.visible_shadow) and (owner is None or bool(owner.visible_shadow)),
+            "random": random,
+            "particle_random": _particle_info_random(particle_index),
+            "color": [float(v) for v in instance.object.color],
+        })
+    return placements
+
+
 def material_graphs(scene):
     """Every graph the scene's materials need, by material name."""
     _TREE_LINKS.clear()
@@ -1380,6 +1464,9 @@ class Session:
         # Set by a present that left the document behind the model; cleared by
         # the save. The tab reads it as `saveDue` beside the frame.
         self.save_due = False
+        # The OUTSIDE-THE-PROJECT file Blender was last found holding, once said
+        # (`follow_open_file`): the refusal is told once per file, not per call.
+        self._outside_file = None
         # WHAT THE PRESENTER LAST REPORTED HOLDING, as an instrument: the
         # `(session, revision)` it held BEFORE the last frame, None when it
         # held nothing, and the string "unreported" for a presenter that does
@@ -1417,7 +1504,7 @@ class Session:
         # (`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,
+        options = {"session": self.session, "evaluate": True, "known": self._known, "instance_sources": True,
                    "graph_materials": sorted(graphs),
                    "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"])}
@@ -1490,6 +1577,7 @@ class Session:
                         "color": [float(v) for v in obj.color],
                         "index": float(obj.pass_index),
                         "random": _object_info_random(obj.name),
+                        "particle_random": _particle_info_random(),
                     }
                 data = obj.evaluated_get(depsgraph).data if obj is not None else None
                 if getattr(data, "use_auto_texspace", True) is False:
@@ -1510,6 +1598,7 @@ class Session:
                     "roughness": float(material.roughness),
                     "metallic": float(material.metallic),
                 }
+        frame["instances"] = _depsgraph_placements(frame, bpy.context.evaluated_depsgraph_get())
         frame["world"] = draw_world(scene)
         frame["cameras"] = {
             obj.name: draw_camera(obj) for obj in scene.objects if obj.type == "CAMERA"
@@ -1878,10 +1967,11 @@ class Session:
     def bind_document(self, relative_path):
         """Name the session's document and OPEN it when the project has one.
 
-        One session holds one document. The path is stated at start and never
-        moves afterwards: a script's own `save_as_mainfile` to somewhere else
-        is an ordinary thing for a script to do and is left alone -- it retargets
-        Blender's `bpy.data.filepath`, not this.
+        One session holds one document. The path is stated at start and moves
+        only where Blender itself moved: a script's own `save_as_mainfile` (or
+        `open_mainfile`) to another `.blend` in the project retargets
+        `bpy.data.filepath`, and `follow_open_file` moves the document with it
+        after the call.
 
         `open_mainfile` runs the session's `_load_post` like any other load
         (the export door's revision table is reset, the render engine ids are
@@ -1925,6 +2015,58 @@ class Session:
         if self.document is not None:
             self.save_due = True
 
+    def follow_open_file(self):
+        """FOLLOW BLENDER'S SAVE AS: the document is the file Blender has open.
+
+        Read after every `execute`, because a script is the one request that can
+        change which file Blender holds. `save_as_mainfile(filepath=X)` writes X
+        and leaves X OPEN -- `bpy.data.filepath` becomes X, and Blender's next
+        Save goes there. The session used to keep saving to the file it was
+        started on, so the model a script had just saved as X was written over
+        the OLD file on the next idle save, and the editor refused X's own tab
+        because the worker still claimed the old one. SEEN 2026-10-07: an
+        agent built an obby through the Blender MCP, saved it as
+        `src/models/obby.blend`, and its level landed in `src/models/cube.blend`
+        instead -- so Play looked for `cube.play.ts`.
+
+        What does NOT move, by Blender's own rules rather than ours:
+        `save_mainfile()` and a Save As to the same path leave the path where it
+        is, and `save_as_mainfile(copy=True)` writes a copy and keeps the
+        original open (which is also how `save_document` writes, so the
+        session's own save never moves anything). `open_mainfile` does move it:
+        Blender then holds that file, and saving the old path would write one
+        file's model over another's.
+
+        Answers None when nothing moved, `{"moved": True, "from", "document"}`
+        when the document followed Blender to another project `.blend`, and
+        `{"moved": False, "from", "outside"}` -- once per file -- when Blender
+        holds a file outside the project: the editor has no document there, so
+        the session keeps its own and keeps saving to it.
+        """
+        if self.document is None or not bpy.data.filepath:
+            return None
+        current = os.path.normpath(os.path.abspath(bpy.data.filepath))
+        if current == os.path.normpath(self.document):
+            self._outside_file = None
+            return None
+        root = os.path.normpath(self.project)
+        relative = current[len(root) + 1:] if current.startswith(root + "/") else None
+        # The same shape the worker and the server check (`worker.ts::isDocumentPath`).
+        if (relative is not None and relative.endswith(".blend") and "\\" not in relative
+                and all(part not in ("", ".", "..") for part in relative.split("/"))):
+            previous = self.document_relative
+            self.document = current
+            self.document_relative = relative
+            self._outside_file = None
+            # The file Blender wrote sits only in the engine's filesystem until the
+            # session's own save carries it to the project.
+            self.save_due = True
+            return {"moved": True, "from": previous, "document": relative}
+        if current == self._outside_file:
+            return None
+        self._outside_file = current
+        return {"moved": False, "from": self.document_relative, "outside": current}
+
     def save_document(self):
         """Write the document -- Blender's own format, by Blender's own operator.
 
@@ -2175,6 +2317,12 @@ def _photograph(depsgraph, width, height, linear=False):
         "width": int(width),
         "height": int(height),
         "fov": _vertical_extent(camera.data, int(width), int(height)),
+        "clipStart": float(camera.data.clip_start),
+        "clipEnd": float(camera.data.clip_end),
+        "shiftX": float(camera.data.shift_x),
+        "shiftY": float(camera.data.shift_y),
+        "horizontalFit": camera.data.sensor_fit == "HORIZONTAL" or
+            (camera.data.sensor_fit == "AUTO" and width >= height),
         "toneMapping": transform,
         "exposure": float(2.0 ** view.exposure),
         "gamma": float(view.gamma),
@@ -2239,10 +2387,8 @@ class VolterRenderEngine(bpy.types.RenderEngine):
     """The scene's renderer, so `write_still`, `save_render` and Render Result
     behave as Blender's own.
 
-    Registered under the three engine ids a script names. The port has real
-    Cycles compiled in, so the Cycles add-on's own engine is unregistered
-    first -- otherwise `scene.render.engine = 'CYCLES'` resolves to it and
-    starts a path trace nobody asked for inside the tab.
+    Registered as VOLTER_THREE and for headless GPU-engine substitutes.
+    CYCLES remains Blender's compiled CPU path tracer.
     """
 
     bl_idname = "VOLTER_THREE"
@@ -2372,22 +2518,21 @@ def _release_from_owning_addon(existing):
 
 
 def _register_engine():
-    """Take the three engine ids a script can name.
-
-    Blender refuses two classes with one `bl_idname`, so the add-on's engine
-    class is unregistered first and the bundle's patched registration sets a
-    built-in type aside; `bpy.utils.register_class` on a subclass whose
-    `bl_idname` is `CYCLES` (or `BLENDER_EEVEE`, the factory default) then
-    makes `scene.render.engine` resolve here. `BLENDER_EEVEE` is the factory engine's id in 5.x (measured on the
-    oracle: the enum holds exactly that name; `BLENDER_EEVEE_NEXT` was 4.2's). Only the Cycles ENGINE CLASS goes: the add-on stays enabled, because
-    `scene.cycles` is the add-on's property group and a script sets `samples`,
-    `use_denoising` and the rest on it (disabling the add-on removed it, and
-    every workshop render died on `'Scene' object has no attribute 'cycles'`
-    before it reached the photograph).
+    """Keep native Cycles and install the headless GPU presenters.
+
+    Native Cycles needs no browser GPU. Replacing its class with a Combined-only
+    Three photograph drops evaluated instances, GI, shader closures and other
+    compositor pass inputs. VOLTER_THREE is the explicit raster photograph;
+    the live viewport and Play use Three independently of this engine choice.
     """
     made, unavailable = [], []
+    cycles = _engine_class("CYCLES")
+    if cycles is not None and not issubclass(cycles, VolterRenderEngine):
+        made.append("CYCLES")
+    else:
+        # Do not report a raster substitute as an available native path tracer.
+        unavailable.append("CYCLES")
     for identifier, label in (
-        ("CYCLES", "Cycles"),
         ("BLENDER_EEVEE", "EEVEE"),
         ("BLENDER_WORKBENCH", "Workbench"),
     ):
@@ -2414,7 +2559,7 @@ def _register_engine():
             # Upstream Blender refuses to let a Python engine take a BUILT-IN
             # id ("is built-in"); the shipped bundle carries a patch that sets
             # the built-in type aside instead, since headless has no GPU for it
-            # to render with, so all three ids are taken there (measured
+            # to render with, so the two GPU ids are taken there (measured
             # 2026-09-17). A bundle without that patch keeps `BLENDER_EEVEE`
             # and `BLENDER_WORKBENCH`: that is a fact about the build, stated
             # in the start reply and refused by name at the render, never a
@@ -5167,8 +5312,63 @@ def _dispatch_request(request):
             }[op])
 
 
+def _native_preview(request):
+    """Native Cycles in an owned scene copy, never in the authoring scene.
+
+    Preview settings, Render Result and temporary files are derived render
+    resources. No history checkpoint, save, frame export or revision bump is
+    owed by this operation. Remove the owned scene before another operation
+    can serialize a project or enumerate its scene datablocks.
+    """
+    for key, maximum in (("width", 1024), ("height", 1024), ("samples", 512)):
+        value = request.get(key)
+        if type(value) is not int or not 1 <= value <= maximum:
+            raise ValueError("Native preview %s must be an integer from 1 to %d" % (key, maximum))
+    engine = _engine_class("CYCLES")
+    if engine is None or issubclass(engine, VolterRenderEngine):
+        raise RuntimeError("Native Cycles is unavailable; a Three photograph cannot answer this request")
+    original = bpy.context.scene
+    camera = original.objects.get(request["camera"]) if request.get("camera") else original.camera
+    if camera is None or camera.type != "CAMERA":
+        raise ValueError("Native preview needs a camera belonging to this scene")
+    preview = original.copy()
+    path = os.path.join(ROOT, "native-preview.png")
+    try:
+        preview.camera = camera
+        preview.render.engine = "CYCLES"
+        preview.render.resolution_x = request["width"]
+        preview.render.resolution_y = request["height"]
+        preview.render.resolution_percentage = 100
+        # Rendered viewport shading precedes the compositor and uses its own
+        # sampling budget; the authoring scene's settings remain untouched.
+        preview.render.use_compositing = False
+        preview.render.use_persistent_data = False
+        preview.cycles.samples = request["samples"]
+        preview.cycles.use_denoising = False
+        preview.render.image_settings.file_format = "PNG"
+        preview.render.image_settings.color_mode = "RGBA"
+        preview.render.image_settings.color_depth = "8"
+        preview.render.filepath = path
+        if os.path.exists(path):
+            os.unlink(path)
+        start = time.perf_counter()
+        result = bpy.ops.render.render(write_still=True, scene=preview.name, layer=bpy.context.view_layer.name)
+        if "FINISHED" not in result or not os.path.isfile(path):
+            raise RuntimeError("Native Cycles preview did not produce its PNG")
+        return {"path": path, "renderer": "CYCLES", "session": SESSION.session,
+                "revision": SESSION.revision, "camera": camera.name,
+                "width": request["width"], "height": request["height"],
+                "samples": request["samples"], "seconds": time.perf_counter() - start}
+    finally:
+        bpy.data.scenes.remove(preview, do_unlink=True)
+
+
 def _dispatch(request):
     op = request.get("op")
+    if op == "native-preview":
+        return _native_preview(request)
+    if op == "document-info":
+        return {"filepath": bpy.data.filepath, "session": SESSION.session, "revision": SESSION.revision}
     if op == "execute":
         engine = bpy.context.scene.render.engine
         if engine in UNAVAILABLE_ENGINES and "render.render" in request["code"]:
@@ -5185,6 +5385,11 @@ def _dispatch(request):
         HISTORY.changed()
         SESSION.mark_changed()
         answer = execute(request["code"])
+        # Read before the present, so the save that present asks for goes to the
+        # file Blender now holds (`Session.follow_open_file`).
+        followed = SESSION.follow_open_file()
+        if followed is not None:
+            answer["document"] = followed
         # Every mutation is presented, the rule: the Model
         # document is what the agent is looking at.
         try:

package/browser/three/blender-depsgraph-placements.ts

@@ -0,0 +1,27 @@
+/** Disposable draw records only. The native frame's authoring objects remain
+ * unchanged; followers receive these records without expanding them twice. */
+type Placement = {
+  id:string;source:string;owner:string|null;matrix:number[][];
+  visible:boolean;render_visible:boolean;shadow_visible?:boolean | undefined;random:number;color:number[];particle_random?:number | undefined;
+};
+type DrawSource = {
+  id:string;name:string;parent:string|null;selected:boolean;
+  object_info?:{random:number;particle_random?:number | undefined} | undefined;
+};
+export function expandDrawPlacements<T extends {objects:DrawSource[];instances?:Placement[] | undefined}>(frame: T): T {
+  if (!frame.instances?.length) return frame;
+  const sources = new Map(frame.objects.map(row => [row.id,row]));
+  const draws = frame.instances.map(instance => {
+    const source = sources.get(instance.source), owner = instance.owner === null ? null : sources.get(instance.owner);
+    if (!source) throw new Error(`Missing native instance source ${instance.source}`);
+    if (instance.owner !== null && !owner) throw new Error(`Missing native instance owner ${instance.owner}`);
+    return {...source,id:instance.id,name:owner?.name ?? source.name,parent:instance.owner,
+      instance_owner:instance.owner,matrix:instance.matrix,visible:instance.visible,
+      viewport_show_self:true,render_show_self:true,
+      render_visible:instance.render_visible,selected:owner?.selected ?? false,
+      shadow_visible:instance.shadow_visible ?? true,
+      ...(source.object_info ? {object_info:{...source.object_info,random:instance.random,color:instance.color,particle_random:instance.particle_random}} : {})};
+  });
+  const {instances: _placements,...rest} = frame;
+  return {...rest,objects:[...frame.objects,...draws]} as T;
+}