@volter/blender-engine 0.1.130 → 0.1.131

package/browser/protocol.ts

@@ -105,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 }

package/browser/runtime.ts

@@ -52,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;
 }
 
 /**
@@ -237,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;
   }
@@ -674,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

@@ -1464,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
@@ -1964,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
@@ -2011,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.
 
@@ -5329,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-physical-material.ts

@@ -7,6 +7,7 @@ import {z} from 'zod';
 import {applyGraphShader, bindGraphDraw, bindPaletteGraph, borrowGraphDrawBinding, graphProgramKey, graphUvChannels, setGraphViewport} from './blender-graph-material';
 import type {CompiledGraph} from './blender-node-graph';
 import {bindNamedUvChannels} from './blender-texture-samplers';
+import {copyWorldVisibility,worldVisibilityShader,worldVisibilityUniforms} from './blender-world-visibility';
 
 const scalar = z.number().finite();
 const color = z.tuple([scalar, scalar, scalar]);
@@ -55,6 +56,7 @@ function graphShadow(material: THREE.MeshPhysicalMaterial): THREE.MeshPhysicalMa
   // which `copy` replaces with the material's own (it leaves hooks alone).
   applyPhysicalMaterial(shadow);
   shadow.copy(material);
+  copyWorldVisibility(material,shadow);
   const values = uniforms.get(shadow)!;
   if (held) {
     values.blenderCoatIor.value = held.blenderCoatIor.value;
@@ -149,6 +151,7 @@ export function syncPhysicalDrawMaterial(source: THREE.Material, target?: THREE.
     return null;
   }
   copy.copy(source);
+  copyWorldVisibility(source,copy);
   const held = uniforms.get(source)!;
   const values = uniforms.get(copy)!;
   values.blenderCoatIor.value = held.blenderCoatIor.value;
@@ -192,7 +195,7 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
       blenderWorldExtinction: {value: new THREE.Vector3()}};
     uniforms.set(material, values);
     const held = values;
-    material.customProgramCacheKey = () => `blender-principled-physical-v5${graphProgramKey(material)}`;
+    material.customProgramCacheKey = () => `blender-principled-physical-v6${graphProgramKey(material)}`;
     material.onBeforeRender = (renderer, scene, camera, geometry, object) => {
       bindNamedUvChannels(material, geometry);
       bindGraphDraw(material, geometry, renderer, scene, camera, object, graphShadow);
@@ -210,6 +213,12 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
         .map(i => (i <= 3 ? `#ifndef USE_UV${i}\nattribute vec2 uv${i};\n#endif` : `attribute vec2 uv${i};`))
         .join('\n') + '\n' + shader.vertexShader;
       Object.assign(shader.uniforms, held);
+      worldVisibilityUniforms(material,shader.uniforms);
+      shader.vertexShader='varying vec3 blenderWorldPosition;\n'+shader.vertexShader;
+      shader.vertexShader=shader.vertexShader.replace('#include <worldpos_vertex>',
+        '#include <worldpos_vertex>\n#if defined(USE_ENVMAP) || defined(USE_SHADOWMAP) || defined(USE_TRANSMISSION)\nblenderWorldPosition=worldPosition.xyz;\n#else\nblenderWorldPosition=(modelMatrix*vec4(transformed,1.)).xyz;\n#endif');
+      shader.fragmentShader=shader.fragmentShader.replace('#include <envmap_physical_pars_fragment>',
+        '#include <envmap_physical_pars_fragment>\n'+worldVisibilityShader);
       shader.fragmentShader = `uniform float blenderCoatIor;
         uniform vec3 blenderWorldExtinction;
         vec3 blenderInfiniteTransmission() { return vec3(
@@ -255,6 +264,10 @@ export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, inpu
           'rectAreaLight = rectAreaLights[ i ]; rectAreaLight.color *= exp(-blenderWorldExtinction * length(rectAreaLight.position-geometryPosition));')
         .replace('getAmbientLightIrradiance( ambientLightColor )', 'getAmbientLightIrradiance( ambientLightColor ) * blenderInfiniteTransmission()');
       const environment = THREE.ShaderChunk.lights_fragment_maps
+        .replace('getIBLIrradiance( geometryNormal )',
+          'blenderWorldIrradiance( geometryNormal, getIBLIrradiance( geometryNormal ) )')
+        .replaceAll(/(getIBL(?:Radiance|AnisotropyRadiance)\([^;]+\))/g,
+          '$1 * blenderWorldReflectionVisibility(geometryViewDir,geometryNormal,material.roughness)')
         .replaceAll(/(getIBL(?:Irradiance|Radiance|AnisotropyRadiance)\([^;]+\))/g, '$1 * blenderInfiniteTransmission()');
       shader.fragmentShader = shader.fragmentShader.replace('#include <lights_physical_fragment>', physical)
         .replace('#include <lights_fragment_begin>', lighting)

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

@@ -724,6 +724,7 @@ export type WorldData = z.infer<typeof worldSchema>;
  * Constants and linked colors use the same radiometric path. The environment
  * samples the field at 256×128; features below a texel are filtered. */
 export class WorldBackground {
+  lightingTexture():THREE.Texture|null {return this.environmentTexture??this.texture;}
   readonly solarLights: THREE.DirectionalLight[] = [];
   private readonly solarDirections = new Map<THREE.DirectionalLight, THREE.Vector3>();
 

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

@@ -58,6 +58,11 @@ export function fitModelDirectionalShadow(
   casters: THREE.Box3[],
 ): void {
   if (!light.castShadow || !receivers.length) return;
+  // A detached photograph fits before its first render. Newly composed suns
+  // and their targets have not yet passed through Scene.updateMatrixWorld;
+  // fitting in those stale axes produces a different map on the first draw.
+  light.updateWorldMatrix(true, false);
+  light.target.updateWorldMatrix(true, false);
   light.shadow.updateMatrices(light);
   const camera = light.shadow.camera;
   const view = camera.matrixWorldInverse;

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

@@ -26,6 +26,7 @@ import {
   worldSchema,
 } from './blender-runtime-lighting';
 import { fitModelDirectionalShadow, visibleShadowReceivers } from './blender-runtime-shadows';
+import {BlenderWorldVisibility,bindWorldVisibility} from './blender-world-visibility';
 import { volumeMesh, volumeSchema } from './blender-runtime-volume';
 import { applyPhysicalMaterial, applyWorldExtinction, physicalMaterialSchema } from './blender-physical-material';
 import { prepareGraphGeometry, setMaterialGraph } from './blender-graph-material';
@@ -681,6 +682,7 @@ export class BlenderRuntimeView {
   private readonly lights = new Map<string, THREE.Light>();
   private readonly lighting = new ViewportLighting();
   private readonly world = new WorldBackground();
+  private readonly worldVisibility=new BlenderWorldVisibility();
   /**
    * THE INSPECTION OVERLAYS (I4). They are NOT children of {@link root}, and
    * that is the whole design: an overlay is EDITOR FURNITURE, so its
@@ -1333,6 +1335,13 @@ export class BlenderRuntimeView {
       // objects. Fit shadows for that draw, rather than the camera's pose
       // when Rendered shading was first entered. Captures use this path too.
       if (this.rendered) this.applyShadows(true, camera);
+      this.worldVisibility.sync(this.objects.values(),this.world.lightingTexture(),this.root,this.rendered);
+      for(const material of [...this.materials.values(),this.fallback])bindWorldVisibility(material,this.worldVisibility);
+      for(const object of this.objects.values()) {
+        const mesh=object as THREE.Mesh;if(!mesh.isMesh)continue;
+        for(const material of Array.isArray(mesh.material)?mesh.material:[mesh.material])bindWorldVisibility(material,this.worldVisibility);
+      }
+      if(options?.renderer)this.worldVisibility.prepare(options.renderer);
       const opaqueDone = performance.now();
       const motion = this.motionGeometry.prepare(camera, !this.rendered && (this.mode ?? this.frame?.mode) === 'OBJECT' &&
         options?.interactive === true, options?.height ?? 0);
@@ -2222,7 +2231,7 @@ export class BlenderRuntimeView {
   }
 
   drawStatistics() {
-    return {enabled: this.drawBatching, preparation: {...this.drawPreparation}, materialRanges: this.materialRanges.inspect(), opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect(), motion: this.motionGeometry.inspect()};
+    return {enabled: this.drawBatching, preparation: {...this.drawPreparation}, worldVisibility:this.worldVisibility.diagnostics(), materialRanges: this.materialRanges.inspect(), opaque: this.instances.inspect(), transparent: this.transparentInstances.inspect(), motion: this.motionGeometry.inspect()};
   }
 
   snapshot() {
@@ -2404,6 +2413,10 @@ export class BlenderRuntimeView {
         if (disposed) throw new Error('Blender capture snapshot is disposed');
         return detached.setRendered(true, camera);
       },
+      prepareDraw:(renderer:THREE.WebGLRenderer,camera:THREE.Camera)=>{
+        if(disposed)throw new Error('Blender capture snapshot is disposed');
+        return detached.prepareDraw(camera,{interactive:false,height:renderer.domElement.height,renderer});
+      },
       dispose,
     };
   }
@@ -2452,6 +2465,7 @@ export class BlenderRuntimeView {
   }
 
   private clear() {
+    this.worldVisibility.dispose();
     this.objectInfoMaterials.clear();
     this.materialRanges.clear();
     this.motionGeometry.clear();

package/browser/three/blender-world-visibility.ts

@@ -0,0 +1,264 @@
+/** Directional world-light visibility. One shared depth atlas replaces repeated
+ * per-pixel triangle traversal. Geometry/placements are derived draw resources;
+ * Blender data and the visible canvas are never changed. This is finite
+ * directional quadrature, not indirect light transport. */
+import * as THREE from 'three';
+
+const SAMPLE_COUNT=16, TILES=4, TILE_SIZE=512;
+type Segment={mesh:THREE.Mesh; geometry:THREE.BufferGeometry; position:THREE.BufferAttribute|THREE.InterleavedBufferAttribute;
+ index:THREE.BufferAttribute|null; positionVersion:number; indexVersion:number; start:number; count:number;
+ offset:number; matrix:THREE.Matrix4; shown:boolean; bounds:THREE.Box3; dynamic:boolean};
+const version=(attribute:THREE.BufferAttribute|THREE.InterleavedBufferAttribute)=>
+ 'isInterleavedBufferAttribute' in attribute ? attribute.data.version : attribute.version;
+function shown(mesh:THREE.Mesh):boolean {
+ if(!mesh.castShadow || !mesh.layers.isEnabled(0))return false;
+ for(let parent:THREE.Object3D|null=mesh;parent;parent=parent.parent)if(!parent.visible)return false;
+ return true;
+}
+
+export class BlenderWorldVisibility {
+ readonly uniforms={
+  blenderWorldVisibilityEnabled:{value:false},
+  blenderWorldDepth:{value:null as THREE.Texture|null},
+  blenderWorldDynamicDepth:{value:null as THREE.Texture|null},
+  blenderWorldHasDynamicDepth:{value:false},
+  blenderWorldRadiance:{value:null as THREE.Texture|null},
+  blenderWorldDirections:{value:Array.from({length:SAMPLE_COUNT},(_,i)=>{
+   const z=1-2*(i+.5)/SAMPLE_COUNT,angle=i*2.399963229728653;
+   return new THREE.Vector3(Math.sqrt(1-z*z)*Math.cos(angle),z,Math.sqrt(1-z*z)*Math.sin(angle));
+  })},
+  blenderWorldMatrices:{value:Array.from({length:SAMPLE_COUNT},()=>new THREE.Matrix4())},
+  blenderWorldToNative:{value:new THREE.Matrix3()},
+  blenderWorldRayOffset:{value:1e-5},
+ };
+ private target:THREE.WebGLRenderTarget|null=null;
+ private dynamicTarget:THREE.WebGLRenderTarget|null=null;
+ private readonly dynamicScene=new THREE.Scene();
+ private readonly dynamicMeshes=new Map<THREE.Mesh,THREE.Mesh>();
+ private readonly scene=new THREE.Scene();
+ private readonly geometry=new THREE.BufferGeometry();
+ private readonly material=new THREE.MeshDepthMaterial({side:THREE.DoubleSide});
+ private readonly mesh=new THREE.Mesh(this.geometry,this.material);
+ private readonly camera=new THREE.OrthographicCamera();
+ private segments:Segment[]=[];
+ private dirty=true;
+ private staticDirty=true;
+ private dynamicDirty=false;
+ private fittedBounds=new THREE.Box3();
+ private passes=0;
+ private staticPasses=0;
+ private dynamicPasses=0;
+ constructor(){this.mesh.frustumCulled=false;this.scene.add(this.mesh);}
+
+ sync(objects:Iterable<THREE.Object3D>,world:THREE.Texture|null,root:THREE.Object3D,enabled:boolean):void {
+  this.uniforms.blenderWorldVisibilityEnabled.value=enabled && world!==null;
+  this.uniforms.blenderWorldRadiance.value=world;
+  this.uniforms.blenderWorldToNative.value.setFromMatrix4(root.matrixWorld).invert();
+  if(!enabled || !world)return;
+  const meshes=[...objects].filter((object):object is THREE.Mesh=>(object as THREE.Mesh).isMesh===true &&
+   !!(object as THREE.Mesh).geometry.getAttribute('position'));
+  const layoutChanged=meshes.length!==this.segments.length || meshes.some((mesh,i)=>{
+   const previous=this.segments[i],geometry=mesh.geometry;
+   return !previous || previous.mesh!==mesh || previous.geometry!==geometry ||
+    previous.position!==geometry.getAttribute('position') || previous.index!==geometry.index ||
+    previous.start!==geometry.drawRange.start || previous.count!==Math.min(geometry.drawRange.count,
+     (geometry.index?.count ?? geometry.getAttribute('position').count)-geometry.drawRange.start);
+  });
+  if(layoutChanged) {
+   for(const mesh of this.dynamicMeshes.values()){mesh.removeFromParent();mesh.geometry.dispose();}
+   this.dynamicMeshes.clear();this.dynamicDirty=true;this.fittedBounds.makeEmpty();
+   let offset=0;
+   this.segments=meshes.map(mesh=>{
+    const geometry=mesh.geometry,position=geometry.getAttribute('position'),index=geometry.index;
+    const start=geometry.drawRange.start,count=Math.max(0,Math.min(geometry.drawRange.count,(index?.count??position.count)-start));
+    const segment={mesh,geometry,position,index,positionVersion:-1,indexVersion:-1,start,count,
+     offset,matrix:new THREE.Matrix4(),shown:!shown(mesh),bounds:new THREE.Box3(),dynamic:false};
+    offset+=count;return segment;
+   });
+   this.geometry.setAttribute('position',new THREE.BufferAttribute(new Float32Array(offset*3),3));
+   this.dirty=true;this.staticDirty=true;
+  }
+  const attribute=this.geometry.getAttribute('position') as THREE.BufferAttribute|undefined;
+  if(!attribute)return;
+  const point=new THREE.Vector3();
+  for(const segment of this.segments) {
+   const visible=shown(segment.mesh),pv=version(segment.position),iv=segment.index?.version??0;
+   if(segment.shown===visible && segment.matrix.equals(segment.mesh.matrixWorld) &&
+      segment.positionVersion===pv && segment.indexVersion===iv)continue;
+   // Once an object moves/deforms, keep it in the small dynamic atlas. Its
+   // later poses must never redraw every static triangle in the environment.
+   if(!segment.dynamic && segment.positionVersion>=0 &&
+     (!segment.matrix.equals(segment.mesh.matrixWorld) || segment.positionVersion!==pv || segment.indexVersion!==iv)) {
+    const geometry=new THREE.BufferGeometry();
+    geometry.setAttribute('position',new THREE.BufferAttribute(new Float32Array(segment.count*3),3));
+    const mesh=new THREE.Mesh(geometry,this.material);mesh.frustumCulled=false;
+    this.dynamicScene.add(mesh);this.dynamicMeshes.set(segment.mesh,mesh);segment.dynamic=true;
+    (attribute.array as Float32Array).fill(0,segment.offset*3,(segment.offset+segment.count)*3);
+    attribute.addUpdateRange(segment.offset*3,segment.count*3);attribute.needsUpdate=true;this.staticDirty=true;
+   }
+   const dynamicMesh=this.dynamicMeshes.get(segment.mesh);
+   const written=(dynamicMesh?.geometry.getAttribute('position')??attribute) as THREE.BufferAttribute;
+   if(dynamicMesh)dynamicMesh.visible=visible;
+   segment.bounds.makeEmpty();
+   for(let i=0;i<segment.count;i++) {
+    if(visible) {
+     const vertex=segment.index?.getX(segment.start+i) ?? segment.start+i;
+     point.fromBufferAttribute(segment.position,vertex).applyMatrix4(segment.mesh.matrixWorld);
+     segment.bounds.expandByPoint(point);
+    } else point.set(0,0,0); // Degenerate the hidden range without changing its layout.
+    written.setXYZ(dynamicMesh?i:segment.offset+i,point.x,point.y,point.z);
+   }
+   written.addUpdateRange(dynamicMesh?0:segment.offset*3,segment.count*3);written.needsUpdate=true;
+   if(dynamicMesh)this.dynamicDirty=true;else this.staticDirty=true;
+   segment.shown=visible;segment.matrix.copy(segment.mesh.matrixWorld);
+   segment.positionVersion=pv;segment.indexVersion=iv;this.dirty=true;
+  }
+ }
+
+ /** Draw the atlas only when a caster changes. All directional samples share
+  * one texture sampler and one merged depth draw, retaining offscreen casters. */
+ prepare(renderer:THREE.WebGLRenderer):void {
+  if(!this.uniforms.blenderWorldVisibilityEnabled.value || !this.dirty)return;
+  if(!this.target) {
+   const size=TILES*TILE_SIZE;
+   this.target=new THREE.WebGLRenderTarget(size,size,{depthBuffer:true,stencilBuffer:false});
+   this.target.depthTexture=new THREE.DepthTexture(size,size,THREE.UnsignedIntType);
+   this.target.depthTexture.minFilter=this.target.depthTexture.magFilter=THREE.NearestFilter;
+   this.uniforms.blenderWorldDepth.value=this.target.depthTexture;
+  }
+  if(this.dynamicMeshes.size && !this.dynamicTarget) {
+   const size=TILES*TILE_SIZE;
+   this.dynamicTarget=new THREE.WebGLRenderTarget(size,size,{depthBuffer:true,stencilBuffer:false});
+   this.dynamicTarget.depthTexture=new THREE.DepthTexture(size,size,THREE.UnsignedIntType);
+   this.dynamicTarget.depthTexture.minFilter=this.dynamicTarget.depthTexture.magFilter=THREE.NearestFilter;
+   this.uniforms.blenderWorldDynamicDepth.value=this.dynamicTarget.depthTexture;
+  }
+  this.uniforms.blenderWorldHasDynamicDepth.value=this.dynamicMeshes.size>0;
+  const bounds=this.segments.reduce((all,segment)=>all.union(segment.bounds),new THREE.Box3());
+  if(this.fittedBounds.isEmpty() || !this.fittedBounds.containsBox(bounds)) {
+   this.fittedBounds.union(bounds);this.staticDirty=true;
+  }
+  const sphere=this.fittedBounds.getBoundingSphere(new THREE.Sphere());
+  this.mesh.visible=(this.geometry.getAttribute('position')?.count??0)>0;
+  const radius=Math.max(sphere.radius,1e-3),distance=radius*2+1;
+  this.uniforms.blenderWorldRayOffset.value=radius*1e-5;
+  this.camera.left=-radius;this.camera.right=radius;this.camera.top=radius;this.camera.bottom=-radius;
+  this.camera.near=.001;this.camera.far=distance+radius*2;
+  this.camera.updateProjectionMatrix();
+  const target=renderer.getRenderTarget(),autoClear=renderer.autoClear,shadowMap=renderer.shadowMap.enabled;
+  try {
+   renderer.autoClear=false;renderer.shadowMap.enabled=false;
+   const targets:[THREE.WebGLRenderTarget,THREE.Scene,boolean][]=[[this.target,this.scene,this.staticDirty]];
+   if(this.dynamicTarget)targets.push([this.dynamicTarget,this.dynamicScene,this.dynamicDirty||this.staticDirty]);
+   for(const [target,,draw] of targets)if(draw) {
+    target.viewport.set(0,0,TILES*TILE_SIZE,TILES*TILE_SIZE);target.scissorTest=false;
+    renderer.setRenderTarget(target);renderer.clear(true,true,false);
+   }
+   for(let i=0;i<SAMPLE_COUNT;i++) {
+    const direction=this.uniforms.blenderWorldDirections.value[i]!;
+    this.camera.position.copy(sphere.center).addScaledVector(direction,distance);
+    this.camera.up.set(0,1,0);this.camera.lookAt(sphere.center);this.camera.updateMatrixWorld(true);
+    this.uniforms.blenderWorldMatrices.value[i]!.multiplyMatrices(this.camera.projectionMatrix,this.camera.matrixWorldInverse);
+    const x=(i%TILES)*TILE_SIZE,y=Math.floor(i/TILES)*TILE_SIZE;
+    // Render-target viewports use device pixels. Renderer.setViewport uses
+    // logical pixels even offscreen, so a HiDPI view would overlap the tiles.
+    for(const [target,scene,draw] of targets)if(draw) {
+     target.viewport.set(x,y,TILE_SIZE,TILE_SIZE);target.scissor.set(x,y,TILE_SIZE,TILE_SIZE);target.scissorTest=true;
+     renderer.setRenderTarget(target);renderer.render(scene,this.camera);
+    }
+   }
+   if(this.staticDirty){this.passes+=SAMPLE_COUNT;this.staticPasses+=SAMPLE_COUNT;}
+   if(this.dynamicTarget && (this.dynamicDirty||this.staticDirty)){this.passes+=SAMPLE_COUNT;this.dynamicPasses+=SAMPLE_COUNT;}
+   this.dirty=false;this.staticDirty=false;this.dynamicDirty=false;
+  } finally {
+   renderer.setRenderTarget(target);renderer.autoClear=autoClear;renderer.shadowMap.enabled=shadowMap;
+  }
+ }
+ diagnostics(){return {enabled:this.uniforms.blenderWorldVisibilityEnabled.value,world:!!this.uniforms.blenderWorldRadiance.value,
+  depth:!!this.uniforms.blenderWorldDepth.value,passes:this.passes,staticPasses:this.staticPasses,dynamicPasses:this.dynamicPasses,
+  dynamicObjects:this.dynamicMeshes.size,vertices:this.geometry.getAttribute('position')?.count??0,
+  casters:this.segments.filter(segment=>segment.shown).length,dirty:this.dirty};}
+ dispose():void {
+  this.uniforms.blenderWorldVisibilityEnabled.value=false;
+  this.target?.dispose();this.target=null;this.uniforms.blenderWorldDepth.value=null;
+  this.dynamicTarget?.dispose();this.dynamicTarget=null;this.uniforms.blenderWorldDynamicDepth.value=null;
+  this.uniforms.blenderWorldHasDynamicDepth.value=false;
+  for(const mesh of this.dynamicMeshes.values()){mesh.removeFromParent();mesh.geometry.dispose();}this.dynamicMeshes.clear();
+  this.geometry.dispose();this.material.dispose();this.segments=[];
+  this.geometry.deleteAttribute('position');this.dirty=true;this.staticDirty=true;this.dynamicDirty=false;this.fittedBounds.makeEmpty();
+ }
+}
+
+const bindings=new WeakMap<THREE.Material,BlenderWorldVisibility>();
+const compiled=new WeakMap<THREE.Material,Set<THREE.WebGLProgramParametersWithUniforms['uniforms']>>();
+const inactive=new BlenderWorldVisibility();
+export function bindWorldVisibility(material:THREE.Material,visibility:BlenderWorldVisibility):void {
+ if(bindings.get(material)===visibility)return;
+ bindings.set(material,visibility);
+ for(const uniforms of compiled.get(material)??[])Object.assign(uniforms,visibility.uniforms);
+}
+export function copyWorldVisibility(source:THREE.Material,target:THREE.Material):void {
+ const visibility=bindings.get(source);if(visibility)bindWorldVisibility(target,visibility);
+}
+export function worldVisibilityUniforms(material:THREE.Material,uniforms:THREE.WebGLProgramParametersWithUniforms['uniforms']):void {
+ let held=compiled.get(material);if(!held){held=new Set();compiled.set(material,held);}held.add(uniforms);
+ Object.assign(uniforms,(bindings.get(material)??inactive).uniforms);
+}
+
+export const worldVisibilityShader=/* glsl */`
+varying vec3 blenderWorldPosition;
+uniform bool blenderWorldVisibilityEnabled;
+uniform sampler2D blenderWorldDepth, blenderWorldDynamicDepth, blenderWorldRadiance;
+uniform bool blenderWorldHasDynamicDepth;
+uniform vec3 blenderWorldDirections[16];
+uniform mat4 blenderWorldMatrices[16];
+uniform mat3 blenderWorldToNative;
+uniform float blenderWorldRayOffset;
+float blenderWorldVisible(int i, vec3 position, vec3 worldDx, vec3 worldDy) {
+ vec4 clip=blenderWorldMatrices[i]*vec4(position,1.);
+ vec3 point=clip.xyz/clip.w*.5+.5;
+ if(any(lessThan(point,vec3(0.))) || any(greaterThan(point,vec3(1.))))return 1.;
+ vec2 tile=vec2(float(i%4),float(i/4));
+ vec2 samplePoint=clamp((floor(point.xy*512.)+.5)/512.,vec2(.5/512.),vec2(1.-.5/512.));
+ vec2 uv=(tile+samplePoint)/4.;
+ float depth=texture2D(blenderWorldDepth,uv).x;
+ if(blenderWorldHasDynamicDepth)depth=min(depth,texture2D(blenderWorldDynamicDepth,uv).x);
+ // Compare the receiver plane AT THE DEPTH TEXEL, not at its nearby fragment.
+ // A fixed depth bias falsely shadows an unoccluded tilted plane; increasing
+ // that bias leaks through thin walls. Derivatives retain its actual slope.
+ vec3 dx=(blenderWorldMatrices[i]*vec4(worldDx,0.)).xyz*.5;
+ vec3 dy=(blenderWorldMatrices[i]*vec4(worldDy,0.)).xyz*.5;
+ float determinant=dx.x*dy.y-dx.y*dy.x;
+ vec2 gradient=abs(determinant)>1e-12 ? vec2(dx.z*dy.y-dy.z*dx.y,dy.z*dx.x-dx.z*dy.x)/determinant : vec2(0.);
+ float receiverDepth=point.z+dot(gradient,samplePoint-point.xy);
+ return receiverDepth<=depth+1e-6 ? 1. : 0.;
+}
+vec3 blenderWorldIrradiance(vec3 normal, vec3 fallbackIrradiance) {
+ if(!blenderWorldVisibilityEnabled)return fallbackIrradiance;
+ vec3 n=inverseTransformDirection(normal,viewMatrix),sum=vec3(0.);
+ float weights=0.;vec3 origin=blenderWorldPosition+n*blenderWorldRayOffset;
+ vec3 worldDx=dFdx(blenderWorldPosition),worldDy=dFdy(blenderWorldPosition);
+ for(int i=0;i<16;i++) {
+  vec3 direction=blenderWorldDirections[i];float weight=max(0.,dot(n,direction));weights+=weight;
+  if(weight>0. && blenderWorldVisible(i,origin,worldDx,worldDy)>0.) {
+   vec3 nativeDirection=normalize(blenderWorldToNative*direction);
+   vec2 uv=vec2(atan(-nativeDirection.y,nativeDirection.x)/6.28318530718+.5,
+    asin(clamp(nativeDirection.z,-1.,1.))/3.14159265359+.5);
+   sum+=texture2D(blenderWorldRadiance,uv).rgb*weight;
+  }
+ }
+ return sum*(3.14159265359/max(weights,1e-8));
+}
+float blenderWorldReflectionVisibility(vec3 viewDirection,vec3 normal,float roughness) {
+ if(!blenderWorldVisibilityEnabled)return 1.;
+ vec3 n=inverseTransformDirection(normal,viewMatrix),r=inverseTransformDirection(reflect(-viewDirection,normal),viewMatrix);
+ vec3 origin=blenderWorldPosition+n*blenderWorldRayOffset;
+ vec3 worldDx=dFdx(blenderWorldPosition),worldDy=dFdy(blenderWorldPosition);
+ float sum=0.,weights=0.;
+ for(int i=0;i<16;i++) {
+  float weight=pow(max(0.,dot(r,blenderWorldDirections[i])),mix(64.,1.,roughness));
+  weights+=weight;sum+=weight*blenderWorldVisible(i,origin,worldDx,worldDy);
+ }
+ return sum/max(weights,1e-8);
+}
+`;

package/browser/worker.ts

@@ -577,6 +577,43 @@ async function stageProjectFiles(files_: BlenderFiles, project: string): Promise
   return failed;
 }
 
+/** What `session.py::follow_open_file` says after a script changed the file Blender holds. */
+type FollowedDocument =
+  | { moved: true; from: string; document: string }
+  | { moved: false; from: string; outside: string };
+
+/**
+ * THE DOCUMENT FOLLOWS BLENDER'S SAVE AS, and the script's caller is told in its own answer.
+ *
+ * A move retargets the session's saves here (the save this call ends with lands the new file
+ * in the project, which is where the editor's Model tab for it opens from) and tells the tab,
+ * whose runtime handle holds the same path. A file outside the project is refused: the editor
+ * has no document there, so the session keeps its own and keeps saving to it, and says so
+ * naming both files, since the script believes it is now working in the other one.
+ */
+function followDocument(followed: FollowedDocument | undefined): string {
+  if (!followed) return '';
+  if (!followed.moved) {
+    const line = `Blender now has ${followed.outside} open, which is outside the project, so the editor cannot ` +
+      `follow it there: this session's document stays ${followed.from}, and the model keeps saving to ` +
+      `${followed.from}. To move the model to another file, save it inside the project (src/models/<name>.blend).`;
+    log('warn', line);
+    return `\n\n${line}`;
+  }
+  if (!isDocumentPath(followed.document)) {
+    // The session checks the same shape, so this is a broken promise, not a refusal to explain.
+    throw new Error(`Blender moved its document to ${JSON.stringify(followed.document)}, which is not a project .blend path`);
+  }
+  documentPath = followed.document;
+  // Even a present that failed must not leave the new file only in the engine's filesystem.
+  setDocumentDirty(true);
+  post({ op: 'document-moved', from: followed.from, document: followed.document });
+  const line = `Blender now has ${followed.document} open (this code saved or opened it), so the editor follows it: ` +
+    `the model saves to ${followed.document} from now on, and ${followed.from} keeps what it last saved.`;
+  log('log', `@@VOLTER-DOCUMENT-MOVED ${JSON.stringify({ from: followed.from, document: followed.document })}`);
+  return `\n\n${line}`;
+}
+
 /** The failures `stageProjectFiles` answered, as one paragraph a script's caller can read. */
 function stagingNote(failed: readonly string[]): string {
   return failed.length === 0 ? '' :
@@ -678,9 +715,10 @@ async function handle(request: WorkerRequest): Promise<unknown> {
         const note = stagingNote(await stageProjectFiles(files, projectRoot));
         const answer = await ask({ op: 'execute', code: request.code, history: request.history ?? true,
           label: request.label ?? 'Blender Python' }) as {
-          error?: string; result: string;
+          error?: string; result: string; document?: FollowedDocument;
         };
-        return (answer.error ? `Error executing code: ${answer.error}` : `Code executed successfully: ${answer.result}`) + note;
+        return (answer.error ? `Error executing code: ${answer.error}` : `Code executed successfully: ${answer.result}`) +
+          note + followDocument(answer.document);
       }
     case 'present':
       // Straight through to `session.py`'s own `present` op — the worker adds

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.130",
+  "version": "0.1.131",
   "publishConfig": {
     "access": "public"
   },