@volter/blender-engine 0.1.128 → 0.1.130

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 }
@@ -139,6 +143,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 +207,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,
@@ -285,6 +288,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 +476,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 {

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()
@@ -1417,7 +1501,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 +1574,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 +1595,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"
@@ -2175,6 +2261,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 +2331,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 +2462,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 +2503,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 +5256,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"]:

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;
+}

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

@@ -26,7 +26,7 @@ interface Binding {
   channels: Record<string, number>;
   borrowedFrom?: Binding;
   borrowedSource?: THREE.MeshPhysicalMaterial;
-  objectInfoUniforms?: {color: THREE.IUniform<THREE.Vector4>; indexRandom: THREE.IUniform<THREE.Vector2>};
+  objectInfoUniforms?: {color: THREE.IUniform<THREE.Vector4>; indexRandom: THREE.IUniform<THREE.Vector2>; particleRandom: THREE.IUniform<number>};
   palette?: {indices: Int32Array; sources: readonly THREE.MeshPhysicalMaterial[]};
 }
 const bindings = new WeakMap<THREE.MeshPhysicalMaterial, Binding>();
@@ -46,7 +46,7 @@ function compatiblePaletteGraphs(sources: readonly THREE.MeshPhysicalMaterial[])
   if (sources.length !== 2 || sources.some(source => pendings.has(source))) return null;
   const graphs = sources.map(source => bindings.get(source)?.compiled);
   const graph = graphs[0];
-  if (!graph || graph.objectInfo || failed.has(graph.key) || graphs.some(other => !other || other.key !== graph.key ||
+  if (!graph || graph.objectInfo || graph.particleInfo || failed.has(graph.key) || graphs.some(other => !other || other.key !== graph.key ||
       other.declarations !== graph.declarations || other.library !== graph.library ||
       JSON.stringify([other.uvs, other.attributes, other.outputs]) !== JSON.stringify([graph.uvs, graph.attributes, graph.outputs]))) return null;
   // Leave room for the physical material's environment and lighting samplers.
@@ -186,17 +186,20 @@ export function borrowGraphDrawBinding(source: THREE.MeshPhysicalMaterial, targe
  * belong to ONE object. A distinct material identity makes Three upload them
  * when it switches between objects sharing an authored material. */
 export function bindGraphObjectInfo(material: THREE.MeshPhysicalMaterial,
-  info: {color: readonly number[]; index: number; random: number}): void {
+  info: {color: readonly number[]; index: number; random: number; particle_random?: number}): void {
   const binding=bindings.get(material);
-  if (!binding?.compiled.objectInfo) return;
+  if (!binding || (!binding.compiled.objectInfo && !binding.compiled.particleInfo)) return;
+  if (binding.compiled.particleInfo && info.particle_random === undefined)
+    throw new Error('Particle Info Random input missing for Blender object');
   const values=binding.objectInfoUniforms ??= {
-    color:{value:new THREE.Vector4()}, indexRandom:{value:new THREE.Vector2()},
+    color:{value:new THREE.Vector4()}, indexRandom:{value:new THREE.Vector2()}, particleRandom:{value:0},
   };
   if (binding.uniforms['blenderObjectColor']!==values.color) {
-    binding.uniforms={...binding.uniforms,blenderObjectColor:values.color,blenderObjectIndexRandom:values.indexRandom};
+    binding.uniforms={...binding.uniforms,blenderObjectColor:values.color,blenderObjectIndexRandom:values.indexRandom, blenderParticleRandom:values.particleRandom};
   }
   values.color.value.fromArray(info.color);
   values.indexRandom.value.set(info.index,info.random);
+  if (info.particle_random !== undefined) values.particleRandom.value=info.particle_random;
 }
 
 /** A binding's values: uniforms, ramp tables and textures. */

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

@@ -49,7 +49,7 @@ export const GRAPH_NODE_TYPES = [
   'ShaderNodeGamma', 'ShaderNodeRGBToBW', 'ShaderNodeSeparateColor', 'ShaderNodeCombineColor',
   'ShaderNodeVectorRotate', 'ShaderNodeFresnel', 'ShaderNodeLayerWeight', 'ShaderNodeBump',
   'ShaderNodeNormalMap', 'ShaderNodeNewGeometry', 'ShaderNodeVertexColor', 'ShaderNodeAttribute',
-  'ShaderNodeRGBCurve', 'ShaderNodeVectorCurve', 'ShaderNodeFloatCurve', 'ShaderNodeObjectInfo',
+  'ShaderNodeRGBCurve', 'ShaderNodeVectorCurve', 'ShaderNodeFloatCurve', 'ShaderNodeObjectInfo', 'ShaderNodeParticleInfo',
 ] as const;
 
 const nodeSchema = z.object({
@@ -145,6 +145,7 @@ export interface CompiledGraph {
   readonly attributes: readonly string[];
   /** Requires a draw identity with this object's native inputs. */
   readonly objectInfo: boolean;
+  readonly particleInfo: boolean;
   /** Which surface inputs the graph drives, each a GLSL global of `type`. */
   readonly outputs: Readonly<Record<string, {readonly global: string; readonly type: GpuType}>>;
   readonly surface: MaterialGraph['surface'];
@@ -433,6 +434,8 @@ class Compiler {
     const [key, index] = source.link;
     const node = this.graph.nodes[key];
     if (!node) throw new Error(`The graph links to ${key}, which it does not carry`);
+    if (node.type === 'ShaderNodeParticleInfo' && node.outputs[index]?.id !== 'Random')
+      throw new Error(`Particle Info output ${node.outputs[index]?.id ?? index} is not compiled by the presenter`);
     const outputs = this.node(key, node);
     const output = outputs[index];
     if (!output) throw new Error(`${key} has no output ${index}`);
@@ -489,6 +492,12 @@ class Compiler {
         body.push(`${outputs[0]!.name} = ${this.uniform(type, prop<number | number[]>(node, 'value'))};`);
         break;
       }
+      case 'ShaderNodeParticleInfo': {
+        // Cycles uses the originating particle's index hash, not Object Info
+        // Random. The exporter refuses other outputs until their data travels.
+        body.push(`${outputs[1]!.name} = blenderParticleRandom;`);
+        break;
+      }
       case 'ShaderNodeObjectInfo': {
         // node_shader_gpu_object_info / node_object_info. Location is the
         // object's origin, never the current fragment's world position.
@@ -959,6 +968,8 @@ class Compiler {
     const program = [
       ...(Object.values(this.graph.nodes).some(n=>n.type==='ShaderNodeObjectInfo')
         ? ['uniform vec4 blenderObjectColor;', 'uniform vec2 blenderObjectIndexRandom;'] : []),
+      ...(Object.values(this.graph.nodes).some(n=>n.type==='ShaderNodeParticleInfo')
+        ? ['uniform float blenderParticleRandom;'] : []),
       ...[...this.s.uniformTypes].map(([n, t]) => `uniform ${t} ${n};`),
       ...this.images.map(i => i.tiled
         ? `uniform highp sampler2DArray ${i.uniform};\nuniform highp sampler2D ${i.uniform}Map;`
@@ -980,6 +991,7 @@ class Compiler {
       uvs: [...this.s.uvs],
       attributes: [...this.s.attributes],
       objectInfo: Object.values(this.graph.nodes).some(n=>n.type==='ShaderNodeObjectInfo'),
+      particleInfo: Object.values(this.graph.nodes).some(n=>n.type==='ShaderNodeParticleInfo'),
       outputs,
       surface: this.graph.surface,
       closure: closure !== undefined,