@volter/blender-engine 0.1.5 → 0.1.6

package/browser/runtime.ts

@@ -27,6 +27,9 @@ type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : n
 type Request = DistributiveOmit<WorkerRequest, 'id'>;
 
 export interface BlenderRuntimeOptions {
+  /** Operation-only diagnostics, never request payloads. The optional observer
+   * must not affect work, even if it throws. End calls balance overlapping work. */
+  work?(label: string): () => void;
   history?(entries: readonly NativeHistoryEntry[]): void;
   /** Display a frame. A screenshot `capture` has its view REMEMBERED so the
    *  next document capture photographs what the agent asked for; a render
@@ -149,6 +152,7 @@ export class BlenderRuntime {
   };
   /** `performance.now()` at the `postMessage` of every outstanding call. */
   readonly #callStarts = new Map<number, number>();
+  readonly #callWork = new Map<number, () => void>();
   #lastCallMs: number | null = null;
   #maxCompletedMs = 0;
   #completedOver5s = 0;
@@ -442,7 +446,8 @@ export class BlenderRuntime {
     if (this.#terminated) return;
     this.#terminated = true;
     globalThis.removeEventListener?.('beforeunload', this.#beforeUnload);
-    this.#worker.terminate();
+    const end = this.#work('terminating worker');
+    try { this.#worker.terminate(); } finally { end(); }
     const error = new Error('The Blender session was terminated');
     for (const id of [...this.#pending.keys()]) this.#settled(id);
     for (const pending of this.#pending.values()) pending.reject(error);
@@ -489,6 +494,8 @@ export class BlenderRuntime {
 
   /** Close a call's window, whether it answered, threw, or was terminated. */
   #settled(id: number): void {
+    this.#callWork.get(id)?.();
+    this.#callWork.delete(id);
     const started = this.#callStarts.get(id);
     if (started === undefined) return;
     this.#callStarts.delete(id);
@@ -510,10 +517,24 @@ export class BlenderRuntime {
       const started = performance.now();
       this.#callStarts.set(id, started);
       this.#lastCallWindow = { start: started, end: null };
-      this.#worker.postMessage({ ...request, id });
+      this.#callWork.set(id, this.#work(`waiting for worker ${request.op}`));
+      try {
+        this.#worker.postMessage({ ...request, id });
+      } catch (error) {
+        this.#pending.delete(id);
+        this.#settled(id);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
     });
   }
 
+  #work(label: string): () => void {
+    try {
+      const end = this.#options.work?.(label);
+      return () => { try { end?.(); } catch { /* diagnostics never fail work */ } };
+    } catch { return () => {}; }
+  }
+
   async #receive(reply: WorkerReply): Promise<void> {
     if ('op' in reply) {
       if (reply.op === 'document-dirty') {
@@ -539,6 +560,7 @@ export class BlenderRuntime {
       const frame = reply.frame as { session?: unknown; revision?: unknown } | null;
       if (typeof frame?.session === 'string' && typeof frame.revision === 'number')
         this.#presented = { session: frame.session, revision: frame.revision };
+      const end = this.#work('presenting worker frame');
       try {
         const answer = await this.#options.present(reply.frame, reply.description, reply.capture);
         this.#worker.postMessage({
@@ -555,6 +577,8 @@ export class BlenderRuntime {
           id: reply.id,
           error: error instanceof Error ? error.message : String(error),
         } satisfies WorkerRequest);
+      } finally {
+        end();
       }
       return;
     }

package/browser/session.py

@@ -283,8 +283,8 @@ def _surface_backgrounds(node):
     return branches[0], branches[1]
 
 
-def _describe_background(background, camera_ray):
-    """The Background's Color as the presenter's world expression (its grammar
+def _describe_world_socket(root_socket, camera_ray):
+    """A World input as the presenter's expression (its grammar
     is `blender-runtime-lighting.ts`'s `worldExpression`); anything outside it
     is refused BY NAME through NotImplementedError."""
     visiting = set()
@@ -402,8 +402,12 @@ def _describe_background(background, camera_ray):
         finally:
             visiting.remove(key)
 
-    color = value(background.inputs["Color"])
-    strength = value(background.inputs["Strength"])
+    return value(root_socket)
+
+
+def _describe_background(background, camera_ray):
+    color = _describe_world_socket(background.inputs["Color"], camera_ray)
+    strength = _describe_world_socket(background.inputs["Strength"], camera_ray)
     # The field evaluator already implements an unclamped color mix. Mixing
     # black with radiance at factor strength is exact multiplication, including
     # spatially varying strength, with no second shader implementation.
@@ -415,20 +419,65 @@ def _describe_background(background, camera_ray):
             "strength": float(strength), "shader": color}
 
 
+def _describe_world_volume(socket, weight=1.0, visiting=None):
+    """Volume closures and their authored inputs, not a guessed fog color.
+    Mix/Add preserve individual scatter lobes rather than averaging anisotropy."""
+    links = list(socket.links)
+    if not links:
+        return []
+    node = links[0].from_node
+    visiting = set() if visiting is None else visiting
+    key = node.as_pointer()
+    if key in visiting:
+        raise NotImplementedError("World volume contains a cycle")
+    visiting.add(key)
+    try:
+        kind = node.bl_idname
+        if kind == "NodeReroute":
+            return _describe_world_volume(node.inputs[0], weight, visiting)
+        if kind == "ShaderNodeAddShader":
+            return sum((_describe_world_volume(s, weight, visiting) for s in node.inputs), [])
+        if kind == "ShaderNodeMixShader":
+            factor = _describe_world_socket(node.inputs[0], False)
+            factor = {"kind": "math", "operation": "MULTIPLY", "clamp": True, "inputs": [factor, 1.0]}
+            first = {"kind": "math", "operation": "SUBTRACT", "clamp": False, "inputs": [1.0, factor]}
+            return sum((_describe_world_volume(node.inputs[i + 1],
+                {"kind": "math", "operation": "MULTIPLY", "clamp": False, "inputs": [weight, f]}, visiting)
+                for i, f in enumerate((first, factor))), [])
+        kinds = {"ShaderNodeVolumeAbsorption": "absorption", "ShaderNodeVolumeScatter": "scatter",
+                 "ShaderNodeVolumePrincipled": "principled", "ShaderNodeEmission": "emission"}
+        if kind not in kinds:
+            raise NotImplementedError("World volume shader %s" % kind)
+        def read(name, default):
+            value = node.inputs.get(name)
+            return _describe_world_socket(value, False) if value is not None else default
+        return [{"kind": kinds[kind], "weight": weight,
+                 "phase": getattr(node, "phase", "HENYEY_GREENSTEIN"), "alpha": read("Alpha", 0.0),
+                 "color": read("Color", [1.0, 1.0, 1.0]), "density": read("Density", 0.0),
+                 "anisotropy": read("Anisotropy", 0.0), "absorption_color": read("Absorption Color", [0.0, 0.0, 0.0]),
+                 "emission_color": read("Emission Color", [1.0, 1.0, 1.0]),
+                 "emission_strength": read("Strength" if kinds[kind] == "emission" else "Emission Strength", 0.0),
+                 "blackbody_intensity": read("Blackbody Intensity", 0.0), "temperature": read("Temperature", 1000.0),
+                 "blackbody_tint": read("Blackbody Tint", [1.0, 1.0, 1.0])}]
+    finally:
+        visiting.remove(key)
+
+
 def _describe_world(world):
     outputs = [n for n in world.node_tree.nodes if n.bl_idname == "ShaderNodeOutputWorld" and n.is_active_output]
     if len(outputs) != 1:
         raise NotImplementedError("World rendering needs one active World Output")
     surface = list(outputs[0].inputs["Surface"].links)
-    if len(surface) != 1:
-        raise NotImplementedError("World Surface must connect to Background")
-    if outputs[0].inputs["Volume"].links:
-        raise NotImplementedError("World volume rendering is not implemented")
+    volume = _describe_world_volume(outputs[0].inputs["Volume"])
+    if not surface:
+        return {"color": [0.0, 0.0, 0.0], "strength": 0.0, "volume": volume}
     background, lighting = _surface_backgrounds(surface[0].from_node)
     described = _describe_background(background, camera_ray=True)
     lighting_data = _describe_background(lighting or background, camera_ray=False)
     if lighting_data != described:
         described["lighting"] = lighting_data
+    if volume:
+        described["volume"] = volume
     # Only a wholly constant background can drop the expression: linked
     # Strength may carry spatial radiance even when Color itself is constant.
     if not any(background.inputs[name].is_linked for name in ("Color", "Strength")):
@@ -870,7 +919,7 @@ class Session:
         """
         carried = frame.get("images") or {}
         for material in (frame.get("materials") or {}).values():
-            for slot in ("texture", "roughness_texture"):
+            for slot in ("texture", "roughness_texture", "normal_texture"):
                 reference = material.get(slot)
                 if not isinstance(reference, dict):
                     continue

package/browser/three/blender-frame-columns.ts

@@ -79,6 +79,8 @@ export const ATTRIBUTE_LAYOUT: Record<AttributeType, { size: number }> = {
 export interface MeshColumns {
   /** 3 * nv */
   co: Float64Array;
+  /** Blender-evaluated normals, 3 per corner, independent of UV splits. */
+  cornerNormal?: Float32Array | undefined;
   /** nf + 1 */
   faceStart: Uint32Array;
   /** faceStart[nf] entries: vertex index per loop */

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

@@ -0,0 +1,132 @@
+/** Principled socket values stay Blender-owned; this file applies them to the
+ * actual Three material. Units cross the wire unchanged (turns and nanometres).
+ * Shader adjustments cover the coat IOR/tint and specular grazing behavior
+ * that MeshPhysicalMaterial does not expose as properties. */
+import * as THREE from 'three';
+import {z} from 'zod';
+import {bindNamedUvChannels} from './blender-texture-samplers';
+
+const scalar = z.number().finite();
+const color = z.tuple([scalar, scalar, scalar]);
+export const physicalMaterialSchema = z.object({
+  coat: scalar, coat_roughness: scalar, coat_ior: scalar, coat_tint: color,
+  sheen: scalar, sheen_roughness: scalar, sheen_tint: color,
+  anisotropy: scalar, anisotropy_rotation: scalar,
+  specular_level: scalar, specular_tint: color,
+  film_thickness: scalar, film_ior: scalar,
+}).strict();
+type Physical = z.infer<typeof physicalMaterialSchema>;
+const defaults: Physical = {
+  coat: 0, coat_roughness: 0.03, coat_ior: 1.5, coat_tint: [1, 1, 1],
+  sheen: 0, sheen_roughness: 0.5, sheen_tint: [1, 1, 1],
+  anisotropy: 0, anisotropy_rotation: 0,
+  specular_level: 0.5, specular_tint: [1, 1, 1], film_thickness: 0, film_ior: 1.33,
+};
+const uniforms = new WeakMap<THREE.MeshPhysicalMaterial, {
+  blenderCoatIor: {value: number}; blenderCoatTint: {value: THREE.Color};
+  blenderMapClip: {value: boolean}; blenderRoughnessClip: {value: boolean}; blenderNormalClip: {value: boolean};
+  blenderWorldExtinction: {value: THREE.Vector3};
+}>();
+
+export function applyWorldExtinction(material: THREE.MeshPhysicalMaterial, extinction: THREE.Vector3): void {
+  if (!uniforms.has(material)) applyPhysicalMaterial(material);
+  uniforms.get(material)!.blenderWorldExtinction.value.copy(extinction);
+}
+
+export function applyPhysicalMaterial(material: THREE.MeshPhysicalMaterial, input?: Physical,
+  clips: {map?: boolean; roughness?: boolean; normal?: boolean} = {}): void {
+  const data = input ?? defaults;
+  material.clearcoat = data.coat;
+  material.clearcoatRoughness = data.coat_roughness;
+  material.sheen = data.sheen;
+  material.sheenRoughness = data.sheen_roughness;
+  material.sheenColor.setRGB(...data.sheen_tint, THREE.LinearSRGBColorSpace);
+  material.anisotropy = data.anisotropy;
+  material.anisotropyRotation = data.anisotropy_rotation * Math.PI * 2;
+  material.specularIntensity = data.specular_level * 2;
+  material.specularColor.setRGB(...data.specular_tint, THREE.LinearSRGBColorSpace);
+  material.iridescence = data.film_thickness > 0 ? 1 : 0;
+  material.iridescenceIOR = data.film_ior;
+  material.iridescenceThicknessRange = [data.film_thickness, data.film_thickness];
+  let values = uniforms.get(material);
+  if (!values) {
+    values = {blenderCoatIor: {value: 1.5}, blenderCoatTint: {value: new THREE.Color(1, 1, 1)},
+      blenderMapClip: {value: false}, blenderRoughnessClip: {value: false}, blenderNormalClip: {value: false},
+      blenderWorldExtinction: {value: new THREE.Vector3()}};
+    uniforms.set(material, values);
+    const held = values;
+    material.customProgramCacheKey = () => 'blender-principled-physical-v5';
+    material.onBeforeRender = (_renderer, _scene, _camera, geometry) => bindNamedUvChannels(material, geometry);
+    material.onBeforeCompile = shader => {
+      // Three declares channels 0..3. Blender has eight named UV maps in
+      // addition to the default channel; only the used attributes survive GLSL.
+      shader.vertexShader = [4, 5, 6, 7, 8, 9].map(i => `attribute vec2 uv${i};`).join('\n') + '\n' + shader.vertexShader;
+      Object.assign(shader.uniforms, held);
+      shader.fragmentShader = `uniform float blenderCoatIor;
+        uniform vec3 blenderWorldExtinction;
+        vec3 blenderInfiniteTransmission() { return vec3(
+          blenderWorldExtinction.x>0.?0.:1., blenderWorldExtinction.y>0.?0.:1., blenderWorldExtinction.z>0.?0.:1.); }
+        uniform vec3 blenderCoatTint;
+        uniform bool blenderMapClip, blenderRoughnessClip, blenderNormalClip;
+        vec4 blenderImageSample(sampler2D image, vec2 uv, bool clipImage) {
+          vec4 pixel = texture2D(image, uv);
+          if (clipImage && (any(lessThan(uv, vec2(0.0))) || any(greaterThan(uv, vec2(1.0))))) pixel = vec4(0.0);
+          return pixel;
+        }
+      ` + shader.fragmentShader;
+      const physical = THREE.ShaderChunk.lights_physical_fragment
+        .replace('material.specularF90 = mix( specularIntensityFactor, 1.0, metalnessFactor );',
+          'material.specularF90 = 1.0;')
+        .replace('material.clearcoatF0 = vec3( 0.04 );',
+          'material.clearcoatF0 = vec3( pow2( ( blenderCoatIor - 1.0 ) / ( blenderCoatIor + 1.0 ) ) );');
+      const normals = THREE.ShaderChunk.normal_fragment_maps
+        .replace('normal = texture2D( normalMap, vNormalMapUv ).xyz * 2.0 - 1.0;',
+          'vec3 blenderBaseNormal = normal; normal = texture2D( normalMap, vNormalMapUv ).xyz * 2.0 - 1.0; normal.y *= normalScale.y < 0.0 ? -1.0 : 1.0;')
+        .replace('normal = normalize( normalMatrix * normal );',
+          'normal = normalize(mix(blenderBaseNormal, normalize(normalMatrix * normal), max(0.0, normalScale.x)));')
+        .replace('mapN.xy *= normalScale;',
+          'mapN.xy *= normalScale; mapN.z = mix(1.0, mapN.z, clamp(normalScale.x, 0.0, 1.0));')
+        .replaceAll('texture2D( normalMap, vNormalMapUv )', 'blenderImageSample(normalMap, vNormalMapUv, blenderNormalClip)');
+      const baseMap = THREE.ShaderChunk.map_fragment
+        .replace('texture2D( map, vMapUv )', 'blenderImageSample(map, vMapUv, blenderMapClip)')
+        // Blender's Color socket does not connect Image Alpha to Principled Alpha.
+        .replace('diffuseColor *= sampledDiffuseColor;', 'diffuseColor.rgb *= sampledDiffuseColor.rgb;');
+      const roughnessMap = THREE.ShaderChunk.roughnessmap_fragment
+        .replace('texture2D( roughnessMap, vRoughnessMapUv )', 'blenderImageSample(roughnessMap, vRoughnessMapUv, blenderRoughnessClip)');
+      const lighting = THREE.ShaderChunk.lights_fragment_begin
+        .replace('getPointLightInfo( pointLight, geometryPosition, directLight );',
+          'getPointLightInfo( pointLight, geometryPosition, directLight ); directLight.color *= exp(-blenderWorldExtinction * length(pointLight.position-geometryPosition));')
+        .replace('getSpotLightInfo( spotLight, geometryPosition, directLight );',
+          'getSpotLightInfo( spotLight, geometryPosition, directLight ); directLight.color *= exp(-blenderWorldExtinction * length(spotLight.position-geometryPosition));')
+        .replace('getDirectionalLightInfo( directionalLight, directLight );',
+          'getDirectionalLightInfo( directionalLight, directLight ); directLight.color *= blenderInfiniteTransmission();')
+        // LTC integrates the rectangle without participating media. Its center
+        // distance is the attenuation approximation; the volume pass samples
+        // the rectangle itself. Neither is claimed as path-traced area lighting.
+        .replace('rectAreaLight = rectAreaLights[ i ];',
+          'rectAreaLight = rectAreaLights[ i ]; rectAreaLight.color *= exp(-blenderWorldExtinction * length(rectAreaLight.position-geometryPosition));')
+        .replace('getAmbientLightIrradiance( ambientLightColor )', 'getAmbientLightIrradiance( ambientLightColor ) * blenderInfiniteTransmission()');
+      const environment = THREE.ShaderChunk.lights_fragment_maps
+        .replaceAll(/(getIBL(?:Irradiance|Radiance|AnisotropyRadiance)\([^;]+\))/g, '$1 * blenderInfiniteTransmission()');
+      shader.fragmentShader = shader.fragmentShader.replace('#include <lights_physical_fragment>', physical)
+        .replace('#include <lights_fragment_begin>', lighting)
+        .replace('#include <lights_fragment_maps>', environment)
+        .replace('#include <normal_fragment_maps>', normals)
+        .replace('#include <map_fragment>', baseMap)
+        .replace('#include <roughnessmap_fragment>', roughnessMap)
+        .replace('vec3 Fcc = F_Schlick', `
+          // Blender's slab_transmittance_at_angle (gpu_shader_material_principled.glsl):
+          // Beer-Lambert attenuation through a refracting coat at this view angle.
+          float coatPath = blenderCoatIor * inversesqrt(max(1e-8,
+            blenderCoatIor * blenderCoatIor - (1.0 - dotNVcc * dotNVcc)));
+          outgoingLight *= mix(vec3(1.0), pow(max(blenderCoatTint, vec3(0.0)), vec3(coatPath)), material.clearcoat);
+          vec3 Fcc = F_Schlick`);
+    };
+    material.needsUpdate = true;
+  }
+  values.blenderCoatIor.value = Math.max(1, data.coat_ior);
+  values.blenderCoatTint.value.setRGB(...data.coat_tint, THREE.LinearSRGBColorSpace);
+  values.blenderMapClip.value = clips.map === true;
+  values.blenderRoughnessClip.value = clips.roughness === true;
+  values.blenderNormalClip.value = clips.normal === true;
+}

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

@@ -39,6 +39,8 @@ export interface DrawArrays {
   normals: Float32Array | null;
   /** Per drawn vertex, or null when the mesh has no UV map. */
   uv: Float32Array | null;
+  /** All named UV layers; material inputs choose their own layer per draw. */
+  uvLayers?: {name: string; data: Float32Array}[] | undefined;
   indices: Uint32Array;
   groups: { start: number; count: number; materialIndex: number }[];
   /** THE BLENDER VERTEX EACH DRAWN VERTEX CAME FROM, one per drawn vertex.
@@ -58,6 +60,7 @@ export interface DrawArrays {
 interface DrawView {
   vertexCount: number;
   normals: Normal[] | null;
+  cornerNormal?: Float32Array | undefined;
   co(i: number): THREE.Vector3;
   /** CSR faces: corner `starts[i]..starts[i+1]` hold vertex indices. */
   starts: Uint32Array;
@@ -69,6 +72,7 @@ interface DrawView {
   sharp: Iterable<[number, number]>;
   /** A corner's UV, or undefined when the mesh has no map. */
   uv: ((corner: number) => [number, number]) | null;
+  uvLayers?: {name: string; read: (corner: number) => [number, number]}[];
 }
 
 function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
@@ -147,28 +151,32 @@ function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
   const positions = new Float32Array(capacity * 3),
     texcoords = new Float32Array(capacity * 2);
   const sourceVertex = new Uint32Array(capacity);
+  const uvLayers = (view.uvLayers ?? []).map(layer => ({...layer, data: new Float32Array(capacity * 2)}));
   const indices = new Uint32Array(capacity),
     shared = new Map<string, number>();
   const groups: DrawArrays['groups'] = [];
-  const normals = view.normals ? new Float32Array(capacity * 3) : null;
+  const normals = view.normals || view.cornerNormal ? new Float32Array(capacity * 3) : null;
   let count = 0,
     indexCount = 0;
-  const emit = (v: number, texture?: [number, number], normal?: Normal): number => {
+  const emit = (v: number, texture?: [number, number], normal?: Normal, sourceCorner?: number): number => {
     const index = count++;
     sourceVertex[index] = v;
     view.co(v).toArray(positions, index * 3);
     if (texture) texcoords.set(texture, index * 2);
     if (normal) normals!.set(normal, index * 3);
+    if (sourceCorner !== undefined) for (const layer of uvLayers) layer.data.set(layer.read(sourceCorner), index * 2);
     return index;
   };
   const corner = (c: number): number => {
     const texture = uv?.(c);
-    const normal = view.normals?.[c];
-    if (!mixed) return emit(cornerVerts[c]!, texture, normal);
-    const key = `${smooth[c] ? find(c) : c}${texture ? `:${texture[0]}:${texture[1]}` : ''}${normal ? `:n${normal.join(':')}` : ''}`;
+    const normal: Normal | undefined = view.cornerNormal
+      ? [view.cornerNormal[c * 3]!, view.cornerNormal[c * 3 + 1]!, view.cornerNormal[c * 3 + 2]!]
+      : view.normals?.[c];
+    if (!mixed) return emit(cornerVerts[c]!, texture, normal, c);
+    const key = `${smooth[c] ? find(c) : c}${texture ? `:${texture[0]}:${texture[1]}` : ''}${normal ? `:n${normal.join(':')}` : ''}${uvLayers.map(layer => ':' + layer.read(c).join(':')).join('')}`;
     let index = shared.get(key);
     if (index === undefined) {
-      index = emit(cornerVerts[c]!, texture, normal);
+      index = emit(cornerVerts[c]!, texture, normal, c);
       shared.set(key, index);
     }
     return index;
@@ -191,6 +199,7 @@ function drawCore(view: DrawView): Omit<DrawArrays, 'hash'> {
     positions: positions.slice(0, count * 3),
     normals: normals?.slice(0, count * 3) ?? null,
     uv: uv ? texcoords.slice(0, count * 2) : null,
+    uvLayers: uvLayers.map(layer => ({name: layer.name, data: layer.data.slice(0, count * 2)})),
     indices: indices.slice(0, indexCount),
     sourceVertex: sourceVertex.slice(0, count),
     groups,
@@ -207,6 +216,15 @@ export function geometryFromDrawArrays(
     new THREE.BufferAttribute(arrays.uv ?? new Float32Array((arrays.positions.length / 3) * 2), 2),
   );
   geometry.setIndex(new THREE.BufferAttribute(arrays.indices, 1));
+  const channels: Record<string, number> = Object.create(null);
+  for (const [index, layer] of (arrays.uvLayers ?? []).entries()) {
+    // Blender's MAX_MTFACE is eight. Channel zero is the active render map;
+    // named inputs use their independently selectable channel, including it.
+    if (index >= 8) throw new Error('A Blender mesh supports at most eight UV maps');
+    channels[layer.name] = index + 1;
+    geometry.setAttribute(`uv${index + 1}`, new THREE.BufferAttribute(layer.data, 2));
+  }
+  geometry.userData['blenderUvChannels'] = channels;
   for (const group of arrays.groups)
     geometry.addGroup(group.start, group.count, group.materialIndex);
   if (arrays.normals) geometry.setAttribute('normal', new THREE.BufferAttribute(arrays.normals, 3));
@@ -233,7 +251,7 @@ export function drawArraysFromColumns(c: MeshColumns, hash: string): DrawArrays
   for (let i = 0; i < ne; i++) edges[i] = [c.edge[i * 2]!, c.edge[i * 2 + 1]!];
   const sharp: [number, number][] = [];
   for (let i = 0; i < ne; i++) if (c.edgeSharp[i] === 1) sharp.push(edges[i]!);
-  const custom = c.attributes.find((a) => a.name === 'custom_normal');
+  const custom = c.cornerNormal ? undefined : c.attributes.find((a) => a.name === 'custom_normal');
   const normalMesh = custom
     ? {
         v: Array.from(
@@ -269,6 +287,7 @@ export function drawArraysFromColumns(c: MeshColumns, hash: string): DrawArrays
   const view: DrawView = {
     vertexCount: nv,
     normals: normalMesh ? customCornerNormals(normalMesh, customData) : null,
+    cornerNormal: c.cornerNormal,
     co: (i) => scratch.set(c.co[i * 3]!, c.co[i * 3 + 1]!, c.co[i * 3 + 2]!).clone(),
     starts: c.faceStart,
     cornerVerts: c.corner,
@@ -277,6 +296,8 @@ export function drawArraysFromColumns(c: MeshColumns, hash: string): DrawArrays
     edges,
     sharp,
     uv: uvData ? (corner) => [uvData[corner * 2]!, uvData[corner * 2 + 1]!] : null,
+    uvLayers: maps.map(layer => ({name: layer.name, read: (corner: number) =>
+      [Number(layer.data[corner * 2]), Number(layer.data[corner * 2 + 1])] as [number, number]})),
   };
   if (map && ATTRIBUTE_LAYOUT.FLOAT2.size !== 2) throw new Error('FLOAT2 layout');
   return { ...drawCore(view), hash };
@@ -337,6 +358,8 @@ export function drawRuntimeGeometry(data: MeshData): THREE.BufferGeometry {
     edges: data.edge_order ?? data.e ?? null,
     sharp: data.sharp ?? [],
     uv: uv ? (corner) => uv[corner]! : null,
+    uvLayers: maps.map(layer => ({name: layer.name, read: (corner: number) =>
+      (layer.data as [number, number][])[corner]!})),
   };
   return geometryFromDrawArrays(drawCore(view));
 }

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

@@ -531,6 +531,14 @@ const worldRadiance = z.object({
 });
 export const worldSchema = worldRadiance
   .extend({
+    volume: z.array(z.object({
+      kind: z.enum(['absorption', 'scatter', 'principled', 'emission']),
+      phase: z.string(), alpha: worldExpression,
+      weight: worldExpression, color: worldExpression, density: worldExpression,
+      anisotropy: worldExpression, absorption_color: worldExpression,
+      emission_color: worldExpression, emission_strength: worldExpression,
+      blackbody_intensity: worldExpression, temperature: worldExpression, blackbody_tint: worldExpression,
+    }).strict()).optional(),
     /** The world that LIGHTS the scene, present only when Blender's Light Path
      * `Is Camera Ray` split it from the world the camera photographs -- one
      * sky at two strengths is how a scene gets a bright backdrop and

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

@@ -24,6 +24,9 @@ import {
 } from './blender-runtime-lighting';
 import { fitModelDirectionalShadow, visibleShadowReceivers } from './blender-runtime-shadows';
 import { volumeMesh, volumeSchema } from './blender-runtime-volume';
+import { applyPhysicalMaterial, applyWorldExtinction, physicalMaterialSchema } from './blender-physical-material';
+import {worldMedium, WorldVolumePass} from './blender-world-volume';
+import { BlenderTextureSamplers } from './blender-texture-samplers';
 import { WeightOverlay, weightsSchema } from './blender-runtime-weights';
 
 const scalar = z.number().finite();
@@ -103,6 +106,7 @@ const drawArraysSchema = z
     positions: z.instanceof(Float32Array),
     normals: z.instanceof(Float32Array).nullable(),
     uv: z.instanceof(Float32Array).nullable(),
+    uvLayers: z.array(z.object({name: z.string(), data: z.instanceof(Float32Array)}).strict()).optional(),
     indices: z.instanceof(Uint32Array),
     groups: z.array(
       z
@@ -158,6 +162,7 @@ const unchangedMeshSchema = z
 const columnsSchema = z
   .object({
     co: z.instanceof(Float64Array),
+    cornerNormal: z.instanceof(Float32Array).optional(),
     faceStart: z.instanceof(Uint32Array),
     corner: z.instanceof(Uint32Array),
     cornerEdge: z.instanceof(Int32Array),
@@ -321,8 +326,8 @@ const frameImageSchema = z.union([rasterImageSchema, pngImageSchema]);
 const textureReferenceSchema = z
   .object({
     image: z.object({ name: z.string(), revision: z.number().int().nonnegative() }).strict(),
-    /** Blender's `extension`; CLIP never arrives -- the reducer refuses it. */
-    extension: z.enum(['REPEAT', 'EXTEND', 'MIRROR']).default('REPEAT'),
+    /** CLIP is transparent black outside the image, applied in the shader. */
+    extension: z.enum(['REPEAT', 'EXTEND', 'MIRROR', 'CLIP']).default('REPEAT'),
     uv: z.string(),
     /** A constant the texture is multiplied by -- Blender's MULTIPLY mix at
      *  full factor, which is what `map * color` already is. */
@@ -337,6 +342,11 @@ const materialSchema = z
     metallic: scalar,
     transmission: scalar,
     ior: scalar,
+    physical: physicalMaterialSchema.optional(),
+    normal_texture: textureReferenceSchema.optional(),
+    normal_strength: scalar.default(1),
+    normal_space: z.enum(['TANGENT', 'OBJECT']).default('TANGENT'),
+    normal_directx: z.boolean().default(false),
     /** A Base Color image, NAMED. Its bytes travel in the frame's `images`
      *  map, once per `(name, revision)`. */
     texture: textureReferenceSchema.optional(),
@@ -480,7 +490,7 @@ export class BlenderRuntimeView {
   private readonly armatureRoot = new THREE.Group();
   private readonly weightRoot = new THREE.Group();
   private rendered = false;
-  private readonly fallback = new THREE.MeshStandardMaterial({ color: 0xb9bec6, roughness: 0.72 });
+  private readonly fallback = new THREE.MeshPhysicalMaterial({ color: 0xb9bec6, roughness: 0.72 });
   /** Base Color images, by image name -- ONE texture per image however many
    *  materials read it, and the cache OWNS it: a material points at one and
    *  never disposes it. Held with the size and revision the resident bytes
@@ -501,6 +511,7 @@ export class BlenderRuntimeView {
   private readonly textureNames = new Map<string, string>();
   /** Which runtime image each material's roughness map is, by material id. */
   private readonly roughnessTextureNames = new Map<string, string>();
+  private readonly textureSamplers = new BlenderTextureSamplers();
   private frame: Frame | null = null;
   private readonly retiredSessions = new Set<string>();
   private geometryBuilds = 0;
@@ -706,6 +717,8 @@ export class BlenderRuntimeView {
    * distinction Blender draws between its solid viewport and a render.
    */
   async setRendered(rendered: boolean, camera?: THREE.Camera): Promise<void> {
+    const extinction = (rendered ? worldMedium(this.frame?.world)?.extinction : null) ?? new THREE.Vector3();
+    for (const material of [...this.materials.values(), this.fallback]) applyWorldExtinction(material, extinction);
     // An area light cannot be DRAWN until its lookup tables are uploaded, and a
     // render is one photograph with no second chance at it.
     // A sky is derived off the main thread now, so a render waits for it the
@@ -1059,6 +1072,33 @@ export class BlenderRuntimeView {
       material.metalness = data.metallic;
       material.transmission = data.transmission;
       material.ior = data.ior;
+      applyPhysicalMaterial(material, data.physical, {
+        map: data.texture?.extension === 'CLIP',
+        roughness: data.roughness_texture?.extension === 'CLIP',
+        normal: data.normal_texture?.extension === 'CLIP',
+      });
+      const normalName = data.normal_texture?.image.name;
+      if (normalName === undefined) {
+        if (material.normalMap) {
+          this.textureSamplers.delete(`${id}:normal`);
+          material.normalMap = null;
+          material.needsUpdate = true;
+        }
+      } else {
+        const held = this.textures.get(normalName);
+        if (!held) throw new Error(`${UNKNOWN_IMAGE}: missing normal image ${normalName}`);
+        const normalMap = this.textureSamplers.get(`${id}:normal`, held.texture, data.normal_texture!.extension, held.ready, data.normal_texture!.uv);
+        if (material.normalMap !== normalMap) {
+          material.normalMap = normalMap;
+          material.needsUpdate = true;
+        }
+        const normalType = data.normal_space === 'OBJECT' ? THREE.ObjectSpaceNormalMap : THREE.TangentSpaceNormalMap;
+        if (material.normalMapType !== normalType) {
+          material.normalMapType = normalType;
+          material.needsUpdate = true;
+        }
+        material.normalScale.set(data.normal_strength, data.normal_strength * (data.normal_directx ? -1 : 1));
+      }
       if (data.emission) {
         material.emissive.setRGB(
           data.emission.color[0],
@@ -1077,6 +1117,7 @@ export class BlenderRuntimeView {
       const roughnessWanted = data.roughness_texture?.image.name ?? null;
       if (roughnessWanted === null) {
         if (this.roughnessTextureNames.has(id)) {
+          this.textureSamplers.delete(`${id}:roughness`);
           material.roughnessMap = null;
           this.roughnessTextureNames.delete(id);
           material.needsUpdate = true;
@@ -1088,18 +1129,8 @@ export class BlenderRuntimeView {
             `${UNKNOWN_IMAGE}: the presenter does not hold runtime image ${roughnessWanted} ` +
               `(revision ${data.roughness_texture!.image.revision})`,
           );
-        const roughnessMap = heldRoughness.texture;
-        const roughnessWrap =
-          data.roughness_texture!.extension === 'EXTEND'
-            ? THREE.ClampToEdgeWrapping
-            : data.roughness_texture!.extension === 'MIRROR'
-              ? THREE.MirroredRepeatWrapping
-              : THREE.RepeatWrapping;
-        if (roughnessMap.wrapS !== roughnessWrap || roughnessMap.wrapT !== roughnessWrap) {
-          roughnessMap.wrapS = roughnessWrap;
-          roughnessMap.wrapT = roughnessWrap;
-          if (roughnessMap.image) roughnessMap.needsUpdate = true;
-        }
+        const roughnessMap = this.textureSamplers.get(`${id}:roughness`, heldRoughness.texture,
+          data.roughness_texture!.extension, heldRoughness.ready, data.roughness_texture!.uv);
         if (material.roughnessMap !== roughnessMap) {
           material.roughnessMap = roughnessMap;
           this.roughnessTextureNames.set(id, roughnessWanted);
@@ -1113,6 +1144,7 @@ export class BlenderRuntimeView {
       const wanted = data.texture?.image.name ?? null;
       if (wanted === null) {
         if (this.textureNames.has(id)) {
+          this.textureSamplers.delete(`${id}:color`);
           material.map = null;
           this.textureNames.delete(id);
           material.needsUpdate = true;
@@ -1129,35 +1161,7 @@ export class BlenderRuntimeView {
             `${UNKNOWN_IMAGE}: the presenter does not hold runtime image ${wanted} ` +
               `(revision ${data.texture!.image.revision})`,
           );
-        const map = held.texture;
-        // REPEAT, because that is what Blender's Image Texture node does:
-        // its `extension` defaults to REPEAT (asked the oracle), while
-        // three's wrapping defaults to ClampToEdge. Any UV outside [0,1]
-        // then smears the edge pixel across the whole surface, which is the
-        // "weirdly stretched" texture the owner saw on the courtyard.
-        //
-        // `extension`, as the description carries it. CLIP never arrives:
-        // the reducer refuses it by name, which is why three modes are
-        // mapped here and not four.
-        const wrap =
-          data.texture!.extension === 'EXTEND'
-            ? THREE.ClampToEdgeWrapping
-            : data.texture!.extension === 'MIRROR'
-              ? THREE.MirroredRepeatWrapping
-              : THREE.RepeatWrapping;
-        if (map.wrapS !== wrap || map.wrapT !== wrap) {
-          map.wrapS = wrap;
-          map.wrapT = wrap;
-          // ONLY IF THERE IS AN IMAGE TO RE-UPLOAD. A wrap change is a sampler
-          // parameter and three re-reads it when the texture's version moves,
-          // so an already-resident map needs the bump -- but bumping one whose
-          // `createImageBitmap` is still in flight is exactly what three warns
-          // about, and it did, 34 times on one courtyard replay:
-          // `THREE.WebGLRenderer: Texture marked for update but no image data
-          // found`. The decode sets `needsUpdate` itself when the bitmap
-          // lands, and it carries whatever wrap is on the texture by then.
-          if (map.image) map.needsUpdate = true;
-        }
+        const map = this.textureSamplers.get(`${id}:color`, held.texture, data.texture!.extension, held.ready, data.texture!.uv);
         // RE-POINTED WHENEVER THE TEXTURE OBJECT CHANGED, which is how a
         // RESIZED image reaches a material: the cache disposes the old texture
         // and builds a new one. A repaint at the same size keeps this exact
@@ -1242,6 +1246,7 @@ export class BlenderRuntimeView {
       }
     for (const [id, material] of this.materials)
       if (!next.materials[id]) {
+        for (const slot of ['normal', 'roughness', 'color']) this.textureSamplers.delete(`${id}:${slot}`);
         material.dispose();
         this.materials.delete(id);
       }
@@ -1323,6 +1328,11 @@ export class BlenderRuntimeView {
         positions,
         normals: attribute('normal'),
         uv: attribute('uv'),
+        uvLayers: Object.entries(geometry.userData['blenderUvChannels'] as Record<string, number> ?? {}).map(([name, channel]) => {
+          const data = attribute(`uv${channel}`);
+          if (!data) throw new Error(`Blender capture mesh ${id} is missing UV layer ${name}`);
+          return {name, data};
+        }),
         indices: index
           ? new Uint32Array(index.array)
           : Uint32Array.from({ length: positions.length / 3 }, (_, i) => i),
@@ -1337,7 +1347,7 @@ export class BlenderRuntimeView {
       frame.volumes[id] = volumeSchema.parse(JSON.parse(signature));
     const images = new Set(
       Object.values(frame.materials).flatMap((material) =>
-        [material.texture?.image.name, material.roughness_texture?.image.name].filter(
+        [material.texture?.image.name, material.roughness_texture?.image.name, material.normal_texture?.image.name].filter(
           (name): name is string => name !== undefined,
         ),
       ),
@@ -1360,11 +1370,13 @@ export class BlenderRuntimeView {
         };
       }
     }
+    const effect = this.createWorldVolumePass();
     const detached = new BlenderRuntimeView();
     let disposed = false;
     const dispose = () => {
       if (disposed) return;
       disposed = true;
+      effect?.dispose();
       detached.dispose();
       detached.root.removeFromParent();
     };
@@ -1378,6 +1390,7 @@ export class BlenderRuntimeView {
       throw error;
     }
     return {
+      effect,
       root: detached.root,
       session: source.session,
       revision: source.revision,
@@ -1389,6 +1402,11 @@ export class BlenderRuntimeView {
     };
   }
 
+  createWorldVolumePass(): WorldVolumePass | undefined {
+    const medium = worldMedium(this.frame?.world);
+    return medium ? new WorldVolumePass(medium) : undefined;
+  }
+
   /** Keep the description that arrived with this frame. Called by the tab's
    *  Blender host right after `applyFrame`, so a refused frame records
    *  nothing: the record must describe what is DISPLAYED. */
@@ -1446,6 +1464,8 @@ export class BlenderRuntimeView {
     for (const { texture } of this.textures.values()) texture.dispose();
     this.textures.clear();
     this.textureNames.clear();
+    this.roughnessTextureNames.clear();
+    this.textureSamplers.clear();
     this.volumes.clear();
     this.objects.clear();
     this.meshes.clear();

package/browser/three/blender-texture-samplers.ts

@@ -0,0 +1,77 @@
+import * as THREE from 'three';
+
+export type TextureExtension = 'REPEAT' | 'EXTEND' | 'MIRROR' | 'CLIP';
+
+/** A shared material may draw meshes whose named layers have different
+ * channel positions. Resolve at Three's per-draw hook, before program choice. */
+export function bindNamedUvChannels(material: THREE.MeshPhysicalMaterial, geometry: THREE.BufferGeometry): void {
+  const channels = geometry.userData['blenderUvChannels'] as Record<string, number> | undefined;
+  for (const texture of [material.map, material.roughnessMap, material.normalMap]) {
+    if (!texture) continue;
+    const name = texture.userData['blenderUvName'] as string | undefined;
+    let channel = name ? channels?.[name] : 0;
+    if (channel === undefined) {
+      // Blender's missing named surface attribute is zero, not the active UV
+      // map and not an error. Shared materials routinely cover meshes without
+      // that layer. Reserve a separate zero channel so other slots retain UV0.
+      channel = 9;
+      const count = geometry.getAttribute('position')?.count;
+      if (count === undefined) throw new Error('A textured Blender draw has no positions');
+      if (geometry.getAttribute('uv9')?.count !== count)
+        geometry.setAttribute('uv9', new THREE.BufferAttribute(new Float32Array(count*2),2));
+    }
+    if (texture.channel !== channel) {
+      texture.channel = channel;
+      material.needsUpdate = true;
+    }
+  }
+}
+
+/** Image pixels are shared; sampler state belongs to each material input.
+ * Clones share Three's Source, including asynchronous PNG decoding, but their
+ * upload versions are independent and must follow repaints explicitly. */
+export class BlenderTextureSamplers {
+  private readonly bindings = new Map<string, {
+    source: THREE.Texture; texture: THREE.Texture; version: number; disposed: boolean;
+  }>();
+
+  get(key: string, source: THREE.Texture, extension: TextureExtension, ready?: Promise<void>, uv = ''): THREE.Texture {
+    let binding = this.bindings.get(key);
+    if (!binding || binding.source !== source) {
+      this.delete(key);
+      binding = {source, texture: source.clone(), version: -1, disposed: false};
+      this.bindings.set(key, binding);
+      const held = binding;
+      // The owner awaits and reports decode failures. Avoid an unhandled
+      // rejection here, and never upload a clone removed during the decode.
+      if (ready) void ready.then(() => {
+        if (!held.disposed) {
+          held.texture.needsUpdate = true;
+          held.version = source.version;
+        }
+      }, () => {});
+    }
+    const wrap = extension === 'REPEAT' ? THREE.RepeatWrapping :
+      extension === 'MIRROR' ? THREE.MirroredRepeatWrapping : THREE.ClampToEdgeWrapping;
+    const changed = binding.texture.wrapS !== wrap || binding.texture.wrapT !== wrap;
+    binding.texture.wrapS = binding.texture.wrapT = wrap;
+    binding.texture.userData['blenderUvName'] = uv;
+    if (source.image && (changed || binding.version !== source.version)) {
+      binding.texture.needsUpdate = true;
+      binding.version = source.version;
+    }
+    return binding.texture;
+  }
+
+  delete(key: string): void {
+    const binding = this.bindings.get(key);
+    if (!binding) return;
+    binding.disposed = true;
+    binding.texture.dispose();
+    this.bindings.delete(key);
+  }
+
+  clear(): void {
+    for (const key of this.bindings.keys()) this.delete(key);
+  }
+}

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

@@ -0,0 +1,235 @@
+/** Homogeneous World transport, in scene-linear radiance. Surface depth bounds
+ * the camera segment; a World with no hit is unbounded, not a camera-far fog box.
+ * Absorption/emission are analytic. Local-light single scattering is numerical;
+ * multiple scattering and heterogeneous fields are not implemented here. */
+import * as THREE from 'three';
+import type {WorldData, WorldExpression} from './blender-runtime-lighting';
+import {worldField} from './world-field-sampler';
+
+export interface WorldMedium {
+  extinction: THREE.Vector3;
+  emission: THREE.Vector3;
+  lobes: {coefficient: THREE.Vector3; g: number; alpha: number}[];
+}
+
+function constant(expression: WorldExpression): number | THREE.Vector3 {
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== 'object') return;
+    if ('kind' in value && ['direction', 'window', 'sky'].includes(String(value.kind)))
+      throw new Error(`World volume spatial input ${value.kind} is not implemented`);
+    for (const child of Object.values(value)) visit(child);
+  };
+  visit(expression);
+  const value = worldField(expression)(new THREE.Vector3());
+  const components = typeof value === 'number' ? [value] : value.toArray();
+  if (!components.every(Number.isFinite)) throw new Error('World volume input is not finite');
+  return value;
+}
+function scalar(expression: WorldExpression): number {
+  const value = constant(expression);
+  if (typeof value !== 'number') throw new Error('World volume scalar input resolved to a color');
+  return Math.max(0, value);
+}
+function color(expression: WorldExpression): THREE.Vector3 {
+  const value = constant(expression);
+  return (typeof value === 'number' ? new THREE.Vector3().setScalar(value) : value.clone()).max(new THREE.Vector3());
+}
+
+// Blender IMB_colormanagement_blackbody_temperature_to_rgb, default linear Rec.709.
+// Coefficients from source/blender/imbuf/intern/colormanagement.cc (GPL-2.0-or-later).
+export function blackbody(t: number): THREE.Vector3 {
+  if (t < 800) return new THREE.Vector3(5.413294490189271, 0, 0);
+  if (t >= 12000) return new THREE.Vector3(.8262954810464208, .9945080501520986, 1.566307710274283);
+  const i = [965,1167,1449,1902,3315,6365].filter(limit => t >= limit).length;
+  const r = [[1619.19106,-.00205010916,5.02995757],[2488.45471,-.00111330907,3.22621544],
+    [3341.43193,-.000486551192,1.76486769],[4094.61742,-.000127446582,.725731635],
+    [4670.28036,.0000291258199,.126703442],[4595.09185,.0000287495649,.150345020],
+    [3787.17450,.00000935907826,.399075871]][i]!;
+  const g = [[-488.999748,.000604330754,-.0755807526],[-755.994277,.000316730098,.478306139],
+    [-1023.63977,.000120223470,.936662319],[-1265.71316,.00000487340896,1.27054498],
+    [-1425.29332,-.0000401150431,1.43972784],[-1175.54822,-.0000216378048,1.30408023],
+    [-500.799571,-.00000459832026,1.09098763]][i]!;
+  const b = [[5.96945309e-11,-4.85742887e-8,-9.70622247e-5,-.00407936148],
+    [2.40430366e-11,5.55021075e-8,-1.98503712e-4,.0289312858],
+    [-1.40949732e-11,1.89878968e-7,-3.56632824e-4,.0910767778],
+    [-3.61460868e-11,2.84822009e-7,-4.93211319e-4,.156723440],
+    [-1.97075738e-11,1.75359352e-7,-2.50542825e-4,-.0222783266],
+    [-1.61997957e-13,-1.64216008e-8,3.86216271e-4,-.738077418],
+    [6.72650283e-13,-2.73078809e-8,4.24098264e-4,-.752335691]][i]!;
+  return new THREE.Vector3(r[0]!/t+r[1]!*t+r[2]!, g[0]!/t+g[1]!*t+g[2]!,
+    ((b[0]!*t+b[1]!)*t+b[2]!)*t+b[3]!).max(new THREE.Vector3());
+}
+
+export function worldMedium(world: WorldData | null | undefined): WorldMedium | null {
+  if (!world?.volume?.length) return null;
+  const medium: WorldMedium = {extinction: new THREE.Vector3(), emission: new THREE.Vector3(), lobes: []};
+  for (const node of world.volume) {
+    const weight = scalar(node.weight);
+    if (weight === 0) continue;
+    const c = color(node.color), density = scalar(node.density);
+    const absorption = new THREE.Vector3(), scatter = new THREE.Vector3();
+    if (node.kind === 'absorption') absorption.set(1-c.x,1-c.y,1-c.z).max(new THREE.Vector3()).multiplyScalar(density);
+    if (node.kind === 'scatter' || node.kind === 'principled') {
+      scatter.copy(c).multiplyScalar(density);
+      const phase = node.kind === 'principled' ? 'HENYEY_GREENSTEIN' : node.phase;
+      if (!['HENYEY_GREENSTEIN','DRAINE','RAYLEIGH'].includes(phase))
+        throw new Error(`World volume ${phase} phase is not implemented`);
+      const anisotropy = constant(node.anisotropy);
+      if (typeof anisotropy !== 'number') throw new Error('World volume anisotropy must be scalar');
+      medium.lobes.push({coefficient: scatter.clone().multiplyScalar(weight),
+        g: phase === 'RAYLEIGH' ? 0 : THREE.MathUtils.clamp(anisotropy, -.999, .999),
+        alpha: phase === 'RAYLEIGH' ? 1 : phase === 'DRAINE' ? scalar(node.alpha) : 0});
+    }
+    if (node.kind === 'principled') {
+      const a = color(node.absorption_color);
+      absorption.set(Math.max(1-c.x,0)*Math.max(1-Math.sqrt(a.x),0),
+        Math.max(1-c.y,0)*Math.max(1-Math.sqrt(a.y),0), Math.max(1-c.z,0)*Math.max(1-Math.sqrt(a.z),0)).multiplyScalar(density);
+      const bb = scalar(node.blackbody_intensity);
+      if (bb > .001) {
+        const t = scalar(node.temperature);
+        const power = 5.670373e-14 / Math.PI * (1 + bb * (t**4 - 1));
+        medium.emission.add(blackbody(t).multiply(color(node.blackbody_tint)).multiplyScalar(power * weight));
+      }
+    }
+    if (node.kind === 'principled' || node.kind === 'emission')
+      medium.emission.add((node.kind === 'emission' ? c : color(node.emission_color)).multiplyScalar(scalar(node.emission_strength)*weight));
+    medium.extinction.add(absorption.add(scatter).multiplyScalar(weight));
+  }
+  for (const axis of ['x','y','z'] as const)
+    if (medium.extinction[axis] === 0 && medium.emission[axis] > 0)
+      throw new Error('Unbounded emissive World volume with zero extinction has divergent radiance');
+  return medium;
+}
+
+/** Integral of exp(-sigma*t) on a finite or infinite segment. */
+export function mediumIntegral(sigma: number, distance: number): number {
+  return sigma > 0 ? -Math.expm1(-sigma*distance)/sigma : distance;
+}
+
+export function phaseDraine(cosine: number, g: number, alpha: number): number {
+  return (1-g*g)*(1+alpha*cosine*cosine) /
+    (4*Math.PI*(1+alpha*(1+2*g*g)/3)*Math.pow(1+g*g-2*g*cosine,1.5));
+}
+
+/** Caller owns the returned target until dispose. Construct per revision-owned
+ * capture, so a concurrent model edit cannot change its medium or resources. */
+export class WorldVolumePass {
+  private readonly target = new THREE.WebGLRenderTarget(1,1,{type: THREE.HalfFloatType, depthBuffer: false});
+  private readonly geometry = new THREE.PlaneGeometry(2,2);
+  private readonly scene = new THREE.Scene();
+  private readonly camera = new THREE.Camera();
+  private material: THREE.ShaderMaterial | undefined;
+  constructor(readonly medium: WorldMedium) {}
+
+  render(renderer: THREE.WebGLRenderer, input: THREE.WebGLRenderTarget, scene: THREE.Scene, camera: THREE.Camera): THREE.WebGLRenderTarget {
+    if (!input.depthTexture) throw new Error('World volume render requires surface depth');
+    const uniforms: Record<string, THREE.IUniform> = {
+      surface: {value: input.texture}, depth: {value: input.depthTexture},
+      inverseProjection: {value: camera.projectionMatrixInverse}, cameraWorld: {value: camera.matrixWorld},
+      orthographic: {value: (camera as THREE.OrthographicCamera).isOrthographicCamera === true},
+      sigma: {value: this.medium.extinction}, emission: {value: this.medium.emission},
+    };
+    let declarations = '', lighting = '';
+    let lightIndex = 0, samplers = 2;
+    scene.traverseVisible(object => {
+      if (!(object instanceof THREE.PointLight || object instanceof THREE.SpotLight || object instanceof THREE.RectAreaLight)) return;
+      const light = object, id = lightIndex++;
+      const position = light.getWorldPosition(new THREE.Vector3());
+      uniforms[`lp${id}`] = {value: position};
+      uniforms[`lc${id}`] = {value: light.color.clone().multiplyScalar(light.intensity)};
+      declarations += `uniform vec3 lp${id}, lc${id};\n`;
+      let visibility = '1.0', spot = '1.0';
+      if (light instanceof THREE.SpotLight) {
+        uniforms[`ld${id}`] = {value: light.target.getWorldPosition(new THREE.Vector3()).sub(position).normalize()};
+        uniforms[`cone${id}`] = {value: new THREE.Vector2(Math.cos(light.angle), Math.cos(light.angle*(1-light.penumbra)))};
+        declarations += `uniform vec3 ld${id}; uniform vec2 cone${id};\n`;
+        spot = `smoothstep(cone${id}.x, max(cone${id}.x+1e-6,cone${id}.y),dot(-L,ld${id}))`;
+      }
+      if (!(light instanceof THREE.RectAreaLight) && light.castShadow && light.shadow.map) {
+        if (++samplers > renderer.capabilities.maxTextures) throw new Error('World volume shadow samplers exceed this GPU texture-unit limit');
+        uniforms[`sm${id}`] = {value: light.shadow.map.texture};
+        uniforms[`sx${id}`] = {value: light.shadow.matrix};
+        uniforms[`ss${id}`] = {value: light.shadow.mapSize};
+        uniforms[`sb${id}`] = {value: light.shadow.bias};
+        uniforms[`sn${id}`] = {value: light.shadow.camera.near};
+        uniforms[`sf${id}`] = {value: light.shadow.camera.far};
+        declarations += `uniform sampler2D sm${id}; uniform mat4 sx${id}; uniform vec2 ss${id}; uniform float sb${id},sn${id},sf${id};\n`;
+        visibility = light instanceof THREE.PointLight
+          ? `getPointShadow(sm${id},ss${id},1.0,sb${id},1.0,sx${id}*vec4(p,1.0),sn${id},sf${id})`
+          : `getShadow(sm${id},ss${id},1.0,sb${id},1.0,sx${id}*vec4(p,1.0))`;
+      }
+      if (light instanceof THREE.RectAreaLight) {
+        const rotation = new THREE.Matrix4().extractRotation(light.matrixWorld);
+        uniforms[`lx${id}`] = {value: new THREE.Vector3(light.width,0,0).applyMatrix4(rotation)};
+        uniforms[`ly${id}`] = {value: new THREE.Vector3(0,light.height,0).applyMatrix4(rotation)};
+        uniforms[`ln${id}`] = {value: new THREE.Vector3(0,0,-1).transformDirection(rotation)};
+        declarations += `uniform vec3 lx${id},ly${id},ln${id};\n`;
+        lighting += `for(int ax=0;ax<4;ax++) for(int ay=0;ay<4;ay++) {
+          vec3 delta=lp${id}+lx${id}*((float(ax)+.5)/4.-.5)+ly${id}*((float(ay)+.5)/4.-.5)-p;
+          float d=length(delta); vec3 L=delta/max(d,1e-6);
+          sum+=lc${id}*exp(-sigma*d)*phase(dot(L,ray))*max(dot(-L,ln${id}),0.)*
+            length(lx${id})*length(ly${id})/(16.*max(d*d,1e-4)); }\n`;
+      } else {
+        uniforms[`cut${id}`] = {value: light.distance};
+        uniforms[`decay${id}`] = {value: light.decay};
+        declarations += `uniform float cut${id},decay${id};\n`;
+        lighting += `{ vec3 delta=lp${id}-p; float d=length(delta); vec3 L=delta/max(d,1e-6);
+          float cutoff=cut${id}>0.?pow(clamp(1.-pow(d/cut${id},4.),0.,1.),2.):1.;
+          sum+=lc${id}*exp(-sigma*d)*phase(dot(L,ray))*${spot}*${visibility}*cutoff/max(pow(d,decay${id}),.01); }\n`;
+      }
+    });
+    let phase = 'vec3 result=vec3(0.);';
+    this.medium.lobes.forEach((lobe,i) => {
+      uniforms[`scatter${i}`] = {value: lobe.coefficient};
+      uniforms[`g${i}`] = {value: lobe.g}; uniforms[`a${i}`] = {value: lobe.alpha};
+      declarations += `uniform vec3 scatter${i}; uniform float g${i},a${i};\n`;
+      phase += `result+=scatter${i}*(1.-g${i}*g${i})*(1.+a${i}*c*c)/(12.56637061436*(1.+a${i}*(1.+2.*g${i}*g${i})/3.)*pow(1.+g${i}*g${i}-2.*g${i}*c,1.5));`;
+    });
+    // The finite quadrature tail is bounded at 20 optical depths (2e-9).
+    const positive = this.medium.extinction.toArray().filter(v => v > 0);
+    uniforms['range'] = {value: positive.length ? 20/Math.min(...positive) : 1};
+    this.material?.dispose();
+    this.material = new THREE.ShaderMaterial({uniforms, depthTest: false, depthWrite: false, toneMapped: false,
+      defines: {USE_SHADOWMAP: '', NUM_DIR_LIGHT_SHADOWS: 0, NUM_SPOT_LIGHT_SHADOWS: 0, NUM_POINT_LIGHT_SHADOWS: 0, NUM_SPOT_LIGHT_COORDS: 0},
+      vertexShader: 'varying vec2 vUv; void main(){vUv=uv;gl_Position=vec4(position.xy,0.,1.);}',
+      fragmentShader: `
+        #include <common>
+        #include <packing>
+        #include <shadowmap_pars_fragment>
+        varying vec2 vUv; uniform sampler2D surface,depth;
+        uniform mat4 inverseProjection,cameraWorld; uniform bool orthographic;
+        uniform vec3 sigma,emission; uniform float range;
+        ${declarations}
+        vec3 phase(float c){${phase} return result;}
+        vec3 incident(vec3 p,vec3 ray){vec3 sum=vec3(0.);${lighting}return sum;}
+        float integral(float s,float d){float x=s*d;return x<.001 ? d*(1.-x*.5+x*x/6.) : (1.-exp(-x))/s;}
+        void main(){
+          float z=texture2D(depth,vUv).r; vec4 base=texture2D(surface,vUv);
+          vec4 v=inverseProjection*vec4(vUv*2.-1.,z*2.-1.,1.);v/=v.w;
+          vec3 hit=(cameraWorld*v).xyz;
+          vec3 origin=cameraWorld[3].xyz;
+          if(orthographic) origin=(cameraWorld*vec4(v.xy,0.,1.)).xyz;
+          vec3 ray=normalize(hit-origin); float d=length(hit-origin); bool background=z>=1.;
+          vec3 tr=exp(-sigma*d);
+          vec3 integrals=vec3(integral(sigma.x,d),integral(sigma.y,d),integral(sigma.z,d));
+          if(background){tr=vec3(sigma.x>0.?0.:1.,sigma.y>0.?0.:1.,sigma.z>0.?0.:1.);
+            integrals=vec3(sigma.x>0.?1./sigma.x:0.,sigma.y>0.?1./sigma.y:0.,sigma.z>0.?1./sigma.z:0.);}
+          vec3 radiance=base.rgb*tr+emission*integrals;
+          float end=background?range:min(range,d);
+          for(int i=0;i<256;i++){
+            float lo=end*pow(float(i)/256.,3.); float hi=end*pow(float(i+1)/256.,3.);
+            float t=(lo+hi)*.5;
+            radiance+=incident(origin+ray*t,ray)*exp(-sigma*t)*(hi-lo);
+          }
+          gl_FragColor=vec4(radiance,base.a+(1.-base.a)*(1.-dot(tr,vec3(1./3.))));
+        }`});
+    this.scene.clear();
+    this.scene.add(new THREE.Mesh(this.geometry,this.material));
+    this.target.setSize(input.width,input.height);
+    const previous = renderer.getRenderTarget();
+    try { renderer.setRenderTarget(this.target); renderer.render(this.scene,this.camera); }
+    finally { renderer.setRenderTarget(previous); }
+    return this.target;
+  }
+  dispose(): void {this.material?.dispose();this.geometry.dispose();this.target.dispose();this.scene.clear();}
+}

package/browser/three/presenter.ts

@@ -191,7 +191,10 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
     renderer.toneMapping = mappings[render.toneMapping] ?? THREE.AgXToneMapping;
     renderer.toneMappingExposure = render.exposure;
     const sceneTarget = new THREE.WebGLRenderTarget(width, height, { type: THREE.HalfFloatType });
+    let effect: ReturnType<BlenderRuntimeView['createWorldVolumePass']>;
     try {
+      effect = render.linearInput ? undefined : view.createWorldVolumePass();
+      if (effect) sceneTarget.depthTexture = new THREE.DepthTexture(width, height);
       await view.setRendered(true, camera);
       let pixels: Uint16Array;
       if (render.linearInput) {
@@ -210,7 +213,8 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
           scene.background = background;
         }
         pixels = new Uint16Array(width * height * 4);
-        renderer.readRenderTargetPixels(sceneTarget, 0, 0, width, height, pixels);
+        const resolved = effect?.render(renderer, sceneTarget, scene, camera) ?? sceneTarget;
+        renderer.readRenderTargetPixels(resolved, 0, 0, width, height, pixels);
         renderer.setRenderTarget(null);
       }
       const count = width * height;
@@ -239,6 +243,7 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
       }
       return answer(photograph);
     } finally {
+      effect?.dispose();
       sceneTarget.dispose();
       renderer.toneMapping = previousMapping;
       renderer.toneMappingExposure = previousExposure;

package/package.json

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

package/wasm/BUNDLE.json

@@ -1,12 +1,12 @@
 {
   "blender": "5.2.0 LTS",
-  "source": "94d8f20b225d51755a0a93a7fdf1e0cd9f53d09c",
-  "reviewedSource": "a4dff7ba16a0cca24504d81ed0086457493e48dc",
+  "source": "68bba09924c2cf08cbceb6608be4a9e1500a62bb",
+  "reviewedSource": "68bba09924c2cf08cbceb6608be4a9e1500a62bb",
   "upstream": "fbe6228777e7d9afefcd61a413844e790ae75db7",
   "sourceRepository": "https://github.com/volter-ai/blender",
-  "sourceRecipe": "https://github.com/volter-ai/blender/blob/94d8f20b225d51755a0a93a7fdf1e0cd9f53d09c/build_files/emscripten/RELEASE.md",
-  "sourceRelease": "https://github.com/volter-ai/blender/releases/tag/blender-5.2.0-wasm.1",
-  "verification": "https://github.com/volter-ai/blender/blob/94d8f20b225d51755a0a93a7fdf1e0cd9f53d09c/build_files/emscripten/VERIFICATION.json",
+  "sourceRecipe": "https://github.com/volter-ai/blender/blob/68bba09924c2cf08cbceb6608be4a9e1500a62bb/build_files/emscripten/RELEASE.md",
+  "sourceRelease": "https://github.com/volter-ai/blender/releases/tag/blender-5.2.0-wasm.2",
+  "verification": "https://github.com/volter-ai/blender/releases/download/blender-5.2.0-wasm.2/VERIFICATION.json",
   "factoryEngine": "BLENDER_EEVEE",
   "files": {
     "blender_browser.js": "raw",
@@ -19,8 +19,8 @@
       "sha256": "2a5d4dbcc90cab571eb16eef9672ef8583e1c0a3638d0b85165d1944d191d9a7"
     },
     "blender_browser.wasm": {
-      "bytes": 86289759,
-      "sha256": "cdf49c116bd5ce56bc4e1c87f7b5da306310eeb86bdf237487b8673e4d6f54a0"
+      "bytes": 86296622,
+      "sha256": "fcc411449beadda7e7a73ec151844f62e0beaf1371f41d43a04a53b884c81c4d"
     },
     "blender_browser.data": {
       "bytes": 52698568,
@@ -33,12 +33,12 @@
       "sha256": "2a5d4dbcc90cab571eb16eef9672ef8583e1c0a3638d0b85165d1944d191d9a7"
     },
     "blender_browser.wasm.br": {
-      "bytes": 18238560,
-      "sha256": "58c481c0500009276041dfee684ad5e5d392917fb1b569d7192225b395aa7501"
+      "bytes": 18601052,
+      "sha256": "1038c911623c80cf08d1aeee2a0395097c8e6736a0c7d339c0f3b4c69be7840e"
     },
     "blender_browser.data.br": {
-      "bytes": 7969535,
-      "sha256": "9bb922432659580c938b0124d84c3b95d1f54797e3df0ebe26463bbf0be7284c"
+      "bytes": 8056563,
+      "sha256": "1d63c1250e2ab9538df36d7d07338396b271577c49227508ae7530f7bde2ee4a"
     },
     "DEPENDENCY-LICENSES.txt": {
       "bytes": 241352,
@@ -48,18 +48,26 @@
   "note": "Official Blender v5.2.0 plus our headless wasm changes and our existing export/session integration. Dependencies are rebuilt from pinned official sources. No third-party Blender port commits or build scripts are inputs. PROXY_TO_PTHREAD, WasmFS, 512 MiB initial / 4 GiB maximum memory, twelve-worker pool. Build information is disabled. The source release includes the exact source tree, materialized startup.blend, dependency archives, pure Python wheels, and notices.",
   "callTrampoline": "CPython 3.13.13 is compiled with PY_CALL_TRAMPOLINE for Blender CPython slot arity casts. This applies to CPython dispatch, not arbitrary indirect calls.",
   "engineIds": "The existing session registers Python render engines under CYCLES, BLENDER_EEVEE and BLENDER_WORKBENCH; the headless build permits built-in IDs to be shadowed.",
-  "exportDoor": "Our existing bpy_web_export.cc and blender_web_session.cc are retained unchanged.",
+  "exportDoor": "The source-owned bpy_web_export.cc now exports Principled physical inputs, normal images, eight named UV layers and evaluated corner normals; blender_web_session.cc is unchanged.",
   "preloadedPayload": "releasePreloadedFileData releases the JS preload buffer after session ready. The measured working payload exclusions are retained.",
   "verificationSummary": {
     "completedCalls": 362,
     "expectedCalls": 362,
     "freshEnginePerModel": true,
     "harnessFailures": 0,
-    "baselineLimitations": [
-      "The original working bundle also has the recorded geometry/image differences; no oracle or comparison threshold was changed.",
-      "On the current editor host both bundles produce the same courier render getX errors (27 total recorded error positions); the historical host recorded four.",
-      "Both bundles report geometry-less curve profile nodes in bridge/tram presentation.",
-      "The current shared-engine board stalled on the frozen baseline; the historical fresh-engine-per-model mode was used for this comparison."
+    "modelResults": {
+      "16-market-courtyard": "match",
+      "17-workshop-interior": "match",
+      "18-riverside-bridge": "different",
+      "19-tram-stop": "different",
+      "20-rigged-courier": "different"
+    },
+    "limitations": [
+      "Exact native geometry comparisons remain different for bridge and courier; thresholds and oracles are unchanged.",
+      "All 70 bridge snapshots match the previous accepted binary byte-for-byte. Courier matches that binary after index remapping except two normal components differing by 0.000001.",
+      "Bridge/tram retain the previous geometry-less curve helper presentation reports.",
+      "Native Cycles image equality is not claimed. All photographed camera poses match.",
+      "The release adapter changes package imports, product document addressing and project setup, not frozen requests or comparison rules."
     ]
   }
 }