@volter/blender-engine 0.1.147 → 0.1.149

package/browser/three/blender-workbench-outline.ts

@@ -0,0 +1,199 @@
+/**
+ * BLENDER'S SOLID OBJECT OUTLINE (`View3DShading.show_object_outline`), as Workbench draws it:
+ * every object is drawn into an object-id buffer (the background is id 0), and each pixel is
+ * darkened toward `object_outline_color` by the share of its four neighbours, one pixel away
+ * (`ui_scale` pixels), whose id differs from its own:
+ *
+ *   opacity = 1 - 0.25 * (number of the four neighbours with the pixel's own id)
+ *   colour  = outline_colour * opacity + colour * (1 - opacity)   (premultiplied alpha over)
+ *
+ * (`workbench_effect_outline_frag.glsl`). So a silhouette against the background and the seam
+ * between two touching objects both carry a band on each side. It is drawn over the shaded frame
+ * in scene-linear, before the view transform, as Blender composites it.
+ *
+ * One object, one id: a mesh the frame presents is one Blender object or one instance of a
+ * collection, each its own draw in Blender's id buffer.
+ */
+import * as THREE from 'three';
+import { FullScreenQuad } from 'three/addons/postprocessing/Pass.js';
+
+const ID_VERTEX = /* glsl */ `
+#include <common>
+#include <batching_pars_vertex>
+#include <morphtarget_pars_vertex>
+#include <skinning_pars_vertex>
+#include <logdepthbuf_pars_vertex>
+#include <clipping_planes_pars_vertex>
+void main() {
+  #include <batching_vertex>
+  #include <skinbase_vertex>
+  #include <morphinstance_vertex>
+  #include <begin_vertex>
+  #include <morphtarget_vertex>
+  #include <skinning_vertex>
+  #include <project_vertex>
+  #include <logdepthbuf_vertex>
+  #include <clipping_planes_vertex>
+}
+`;
+
+const ID_FRAGMENT = /* glsl */ `
+uniform vec3 objectId;
+#include <logdepthbuf_pars_fragment>
+#include <clipping_planes_pars_fragment>
+void main() {
+  #include <clipping_planes_fragment>
+  #include <logdepthbuf_fragment>
+  gl_FragColor = vec4(objectId, 1.0);
+}
+`;
+
+/** The outline itself, over the frame: Blender's four-neighbour test on the id buffer. */
+const OUTLINE_FRAGMENT = /* glsl */ `
+precision highp float;
+uniform sampler2D ids;
+uniform int reach;
+uniform vec3 outlineColor;
+in vec2 vUv;
+out vec4 outputColor;
+vec4 idAt(ivec2 p, ivec2 size) { return texelFetch(ids, clamp(p, ivec2(0), size - 1), 0); }
+void main() {
+  ivec2 size = textureSize(ids, 0);
+  ivec2 p = ivec2(vUv * vec2(size));
+  vec4 centre = idAt(p, size);
+  float same = 0.0;
+  same += all(equal(idAt(p + ivec2(0, reach), size), centre)) ? 1.0 : 0.0;
+  same += all(equal(idAt(p - ivec2(0, reach), size), centre)) ? 1.0 : 0.0;
+  same += all(equal(idAt(p + ivec2(reach, 0), size), centre)) ? 1.0 : 0.0;
+  same += all(equal(idAt(p - ivec2(reach, 0), size), centre)) ? 1.0 : 0.0;
+  float opacity = 1.0 - 0.25 * same;
+  outputColor = vec4(outlineColor * opacity, opacity);
+}
+`;
+
+export class WorkbenchOutline {
+  private target: THREE.WebGLRenderTarget | null = null;
+  private readonly ids = new THREE.ShaderMaterial({
+    name: 'Blender object id',
+    uniforms: { objectId: { value: new THREE.Color() } },
+    vertexShader: ID_VERTEX,
+    fragmentShader: ID_FRAGMENT,
+  });
+  private readonly composite = new THREE.RawShaderMaterial({
+    name: 'Blender object outline',
+    glslVersion: THREE.GLSL3,
+    uniforms: { ids: { value: null }, reach: { value: 1 }, outlineColor: { value: new THREE.Color() } },
+    vertexShader: `precision highp float; in vec3 position; in vec2 uv; out vec2 vUv;
+      void main(){vUv=uv;gl_Position=vec4(position,1.0);}`,
+    fragmentShader: OUTLINE_FRAGMENT,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+    blending: THREE.CustomBlending,
+    blendSrc: THREE.OneFactor,
+    blendDst: THREE.OneMinusSrcAlphaFactor,
+    blendSrcAlpha: THREE.OneFactor,
+    blendDstAlpha: THREE.OneMinusSrcAlphaFactor,
+  });
+  private readonly quad = new FullScreenQuad(this.composite);
+  private readonly idOf = new Map<THREE.Object3D, number>();
+
+  constructor() {
+    // Each draw carries its own object's id; the material is shared by every draw of the pass.
+    this.ids.onBeforeRender = (_renderer, _scene, _camera, _geometry, object) => {
+      const id = this.idOf.get(object) ?? 0;
+      (this.ids.uniforms['objectId']!.value as THREE.Color).setRGB(
+        (id & 0xff) / 255, ((id >> 8) & 0xff) / 255, ((id >> 16) & 0xff) / 255, THREE.LinearSRGBColorSpace);
+      this.ids.uniformsNeedUpdate = true;
+    };
+  }
+
+  /**
+   * Draw the outline over what the renderer's CURRENT target holds (the frame just drawn through
+   * `camera`), `reach` target pixels out. `objects` are the frame's presented objects in its
+   * order, each drawn with its own id where `drawn(object)` says it is drawn; `internal` are the
+   * presenter's own draws standing in for some of them (batches), hidden for the id pass.
+   */
+  draw(
+    renderer: THREE.WebGLRenderer,
+    scene: THREE.Scene,
+    camera: THREE.Camera,
+    objects: Iterable<THREE.Object3D>,
+    drawn: (object: THREE.Object3D) => boolean,
+    internal: readonly THREE.Object3D[],
+    color: readonly [number, number, number],
+    reach: number,
+  ): void {
+    const output = renderer.getRenderTarget();
+    const size = output ? new THREE.Vector2(output.width, output.height) : renderer.getDrawingBufferSize(new THREE.Vector2());
+    if (size.x < 1 || size.y < 1) return;
+    this.target ??= new THREE.WebGLRenderTarget(size.x, size.y, {
+      minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter, generateMipmaps: false, depthBuffer: true,
+    });
+    if (this.target.width !== size.x || this.target.height !== size.y) this.target.setSize(size.x, size.y);
+    this.idOf.clear();
+    const layers = new Map<THREE.Object3D, number>();
+    const shown = new Map<THREE.Object3D, boolean>();
+    let next = 1;
+    for (const object of objects) {
+      if (!(object as THREE.Mesh).isMesh) continue;
+      this.idOf.set(object, next++);
+      // A batched member is drawn by its batch, with its own layer cleared; the id pass draws
+      // the member itself, so it carries its own id.
+      layers.set(object, object.layers.mask);
+      object.layers.mask = drawn(object) ? 1 : 0;
+    }
+    for (const object of internal) {
+      shown.set(object, object.visible);
+      object.visible = false;
+    }
+    const background = scene.background;
+    const override = scene.overrideMaterial;
+    const autoClear = renderer.autoClear;
+    const shadows = renderer.shadowMap.enabled;
+    const clearColor = renderer.getClearColor(new THREE.Color());
+    const clearAlpha = renderer.getClearAlpha();
+    const cameraLayers = camera.layers.mask;
+    try {
+      scene.background = null;
+      scene.overrideMaterial = this.ids;
+      renderer.autoClear = false;
+      renderer.shadowMap.enabled = false;
+      camera.layers.mask = 1;
+      renderer.setRenderTarget(this.target);
+      renderer.setClearColor(0x000000, 0);
+      renderer.clear(true, true, false);
+      renderer.render(scene, camera);
+    } finally {
+      scene.background = background;
+      scene.overrideMaterial = override;
+      renderer.autoClear = autoClear;
+      renderer.shadowMap.enabled = shadows;
+      renderer.setClearColor(clearColor, clearAlpha);
+      camera.layers.mask = cameraLayers;
+      for (const [object, mask] of layers) object.layers.mask = mask;
+      for (const [object, visible] of shown) object.visible = visible;
+      renderer.setRenderTarget(output);
+    }
+    this.composite.uniforms['ids']!.value = this.target.texture;
+    this.composite.uniforms['reach']!.value = Math.max(1, Math.round(reach));
+    (this.composite.uniforms['outlineColor']!.value as THREE.Color).setRGB(color[0], color[1], color[2], THREE.LinearSRGBColorSpace);
+    // Laid OVER the frame: a renderer that clears before every draw (`autoClear`, on wherever no
+    // composer has turned it off) would wipe the frame first and leave the outline alone.
+    renderer.autoClear = false;
+    try {
+      this.quad.render(renderer);
+    } finally {
+      renderer.autoClear = autoClear;
+    }
+  }
+
+  dispose(): void {
+    this.target?.dispose();
+    this.target = null;
+    this.ids.dispose();
+    this.composite.dispose();
+    this.quad.dispose();
+    this.idOf.clear();
+  }
+}

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

@@ -131,6 +131,7 @@ export class WorldVolumePass {
     };
     let declarations = '', lighting = '';
     let lightIndex = 0, samplers = 2;
+    const shadowKinds = new Set<string>();
     scene.traverseVisible(object => {
       if (!(object instanceof THREE.PointLight || object instanceof THREE.SpotLight || object instanceof THREE.RectAreaLight)) return;
       const light = object, id = lightIndex++;
@@ -145,18 +146,26 @@ export class WorldVolumePass {
         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) {
+      const depthMap = light instanceof THREE.RectAreaLight || !light.castShadow ? null : light.shadow.map?.depthTexture ?? null;
+      if (!(light instanceof THREE.RectAreaLight) && depthMap) {
+        // THE SHADOW MAP AS THREE.JS (r182+) KEEPS IT: the light's depth, in `shadow.map.depthTexture` (a cube of
+        // depths for a point light). With PCF it is a comparison texture (hardware depth compare, sampled through
+        // a shadow sampler), otherwise plain depths. The pass samples it with functions of its own: three's
+        // `getShadow`/`getPointShadow` exist only for the lights its own programs count, and their signatures
+        // follow its internals.
         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};
+        const point = light instanceof THREE.PointLight, compare = depthMap.compareFunction !== null;
+        uniforms[`sm${id}`] = {value: depthMap};
         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))`;
+        const sampler = point ? (compare ? 'samplerCubeShadow' : 'samplerCube') : (compare ? 'sampler2DShadow' : 'sampler2D');
+        declarations += `uniform ${sampler} sm${id}; uniform mat4 sx${id}; uniform float sb${id},sn${id},sf${id};\n`;
+        visibility = point
+          ? `cubeShadow(sm${id},sb${id},sn${id},sf${id},(sx${id}*vec4(p,1.0)).xyz)`
+          : `planeShadow(sm${id},sb${id},sx${id}*vec4(p,1.0))`;
+        shadowKinds.add(sampler);
       }
       if (light instanceof THREE.RectAreaLight) {
         const rotation = new THREE.Matrix4().extractRotation(light.matrixWorld);
@@ -189,17 +198,60 @@ export class WorldVolumePass {
     const positive = this.medium.extinction.toArray().filter(v => v > 0);
     uniforms['range'] = {value: positive.length ? 20/Math.min(...positive) : 1};
     this.material?.dispose();
+    // Each sampler kind used gets its function; a reversed depth buffer (three's `reversedDepthBuffer`) writes
+    // and compares depths the other way round, as three's own shadow functions handle it.
+    const reversed = renderer.state.buffers.depth.getReversed();
+    let shadowFunctions = reversed ? '#define VOLUME_REVERSED_DEPTH\n' : '';
+    const plane = (sampler: string, test: string) => `float planeShadow(${sampler} map,float bias,vec4 c){
+          if(c.w<=0.) return 1.; c.xyz/=c.w; ${test} }\n`;
+    if (shadowKinds.has('sampler2DShadow'))
+      shadowFunctions += plane('sampler2DShadow', `c.z+=bias;
+          if(c.x<0.||c.x>1.||c.y<0.||c.y>1.||c.z>1.) return 1.;
+          return texture(map,vec3(c.xy,c.z));`);
+    if (shadowKinds.has('sampler2D'))
+      shadowFunctions += plane('sampler2D', `
+          #ifdef VOLUME_REVERSED_DEPTH
+            c.z-=bias;
+          #else
+            c.z+=bias;
+          #endif
+          if(c.x<0.||c.x>1.||c.y<0.||c.y>1.||c.z>1.) return 1.;
+          float stored=texture(map,c.xy).r;
+          #ifdef VOLUME_REVERSED_DEPTH
+            return step(stored,c.z);
+          #else
+            return step(c.z,stored);
+          #endif`);
+    // A point light's cube holds each face's perspective depth along that face's axis (the largest component
+    // of the light-to-point vector), between the shadow camera's near and far.
+    const cube = (sampler: string, test: string) => `float cubeShadow(${sampler} map,float bias,float near,float far,vec3 v){
+          vec3 a=abs(v); float z=max(max(a.x,a.y),a.z);
+          if(z>far||z<near) return 1.;
+          ${test} }\n`;
+    if (shadowKinds.has('samplerCubeShadow'))
+      shadowFunctions += cube('samplerCubeShadow', `
+          #ifdef VOLUME_REVERSED_DEPTH
+            float dp=near*(far-z)/(z*(far-near))-bias;
+          #else
+            float dp=far*(z-near)/(z*(far-near))+bias;
+          #endif
+          return texture(map,vec4(normalize(v),dp));`);
+    if (shadowKinds.has('samplerCube'))
+      shadowFunctions += cube('samplerCube', `float dp=far*(z-near)/(z*(far-near))+bias;
+          float stored=texture(map,normalize(v)).r;
+          #ifdef VOLUME_REVERSED_DEPTH
+            stored=1.-stored;
+          #endif
+          return step(dp,stored);`);
     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}
+        ${shadowFunctions}
         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;}

package/browser/three/presenter.ts

@@ -1,27 +1,16 @@
 import { createBlenderDisplayTransform, blenderDisplaySettingsForRender } from './blender-display-transform';
 /**
- * THE PRESENTER FOR A HOST WITHOUT A STAGE (WS-AC, cut 1b).
- *
- * "Our Blender renders with three.js" is a translation (`./blender-runtime-view`
- * and the modules beside it) plus one act: point a camera at the translated
- * scene, render into a scene-linear target, read the pixels, run Blender's
- * display transform, answer. The editor performs that act with its own stage
- * and renderer (`packages/editor-blender/host/blender-runtime-host.ts`), which is why
- * the editor never imports THIS file. A host that has no renderer — a bare
- * page with `@volter/browser-wali`, an Emscripten page, the substrate
- * workbench — attaches one of these to the Blender it started, and the guest's
- * `bpy.ops.render.render` comes back as a three.js photograph exactly as it
- * does in the editor.
- *
- * What it does NOT do, on purpose: overlays (modeling chrome, hidden for a
- * render anyway), selection outlines, the editor's supersampled `captureImage`
- * for the Standard transform. Every transform here goes through the linear
- * capture and the same OCIO GPU display processors the editor uses.
+ * Present Blender frames for a host without an editor stage. Translate the scene through
+ * BlenderRuntimeView, render it with a dedicated camera into a scene-linear target, then apply
+ * Blender’s OCIO display transform and return the photograph. Editor hosts wrap the same
+ * translation with their own stage and renderer. This presenter supplies no modeling overlays or
+ * selection outlines.
  */
 import * as THREE from 'three';
 import type { CaptureRequest } from '../protocol';
 import type { PresentAnswer } from '../runtime';
 import { BlenderRuntimeView } from './blender-runtime-view';
+import { bytesFromBase64 } from './blender-base64';
 
 export interface PresenterOptions {
   /** The canvas to render into; an OffscreenCanvas of 1x1 when absent. */
@@ -81,7 +70,8 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
   const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
   renderer.outputColorSpace = THREE.SRGBColorSpace;
   renderer.shadowMap.enabled = true;
-  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+  // PCFShadowMap supplies the soft-shadow filter supported by this three.js release.
+  renderer.shadowMap.type = THREE.PCFShadowMap;
   renderer.setPixelRatio(1);
   const near = options.near ?? 0.1;
   const far = options.far ?? 1000;
@@ -107,11 +97,7 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
     view: BlenderRuntimeView, scene: THREE.Scene, frame: unknown, description: unknown,
     capture?: CaptureRequest,
   ): Promise<PresentAnswer> {
-    const applied = view.applyFrame(frame) as { held?: unknown } | null | undefined;
-    const held =
-      typeof applied === 'object' && applied !== null && 'held' in applied
-        ? (applied.held as { session: string; revision: number } | null)
-        : null;
+    const { held } = view.applyFrame(frame);
     view.recordPresentation(description);
     const answer = (photograph?: unknown): PresentAnswer => ({
       ...(photograph === undefined ? {} : { capture: photograph }),
@@ -233,8 +219,6 @@ export function createPresenter(options: PresenterOptions = {}): Presenter {
 
 /** A composited frame's scene-linear half floats, as `linearInput` carries them. */
 function halfFloatFrame(base64: string): Uint16Array {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  const bytes = bytesFromBase64(base64);
   return new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1);
 }

package/browser/three/release.ts

@@ -1,25 +1,9 @@
 /**
- * THE TRANSLATION, AS OUR BLENDER'S RELEASE SHIPS IT (WS-AC, cut 4).
- *
- * "Our Blender renders with three.js" is one implementation, built once at
- * release time out of this package's source into ONE self-contained ES module
- * (`blender-three.mjs`, three inlined, the display tables beside it) and
- * delivered wherever the wasm is delivered. A host fetches it from the
- * artifact base next to `blender.wasm`, imports it, and attaches ONE presenter
- * to the Blender it started:
- *
- *     const { createPresenter, attachPresenter } = await import(url);
- *     const detach = attachPresenter(filesystem, "/tmp/volter-presenter", createPresenter());
- *
- * NO HOST BUNDLES THIS. The module is GPL because it is part of the Blender
- * release; a host loads it the way it loads the wasm -- by URL, under a pinned
- * hash -- and its own build graph never touches this package. The editor is
- * the one consumer that does NOT load this file: it imports the same source
- * with its own three and wraps its own document around it, because two copies
- * of three on one page is the thing this arrangement exists to prevent.
- *
- * `vite.release.config.ts` beside this package's manifest is the build;
- * `npm run build:blender-three -w @volter/blender-engine` runs it.
+ * Release entry for the self-contained Blender three.js presenter module. The Blender release
+ * delivers it beside the Wasm artifact, with three.js inlined and display tables beside it. Hosts
+ * load the pinned module URL and attach createPresenter() through attachPresenter(). The editor
+ * imports the same source using its shared three.js instance and its own document stage. Build with
+ * vite.release.config.ts or build:blender-three.
  */
 export { attachPresenter } from './attach-presenter';
 export type { AttachablePresenter, PresenterFileSystem } from './attach-presenter';

package/browser/three/sky-precompute-worker.ts

@@ -1,21 +1,4 @@
-/**
- * The sky precompute, in a Worker.
- *
- * `precomputeSkyTexture` is 512x256 texels at 64 in-scattering steps each and
- * MEASURED 15.4 seconds. On the page's thread that is not "slow", it is a FROZEN
- * EDITOR -- the owner saw exactly that, and a spinner could not have helped
- * because a blocked main thread cannot paint one.
- *
- * This module is the whole worker: parameters in, one Float32Array out,
- * TRANSFERRED rather than copied. It names no DOM and no renderer, which is what
- * lets it be a worker at all; `blender-sky.ts` keeps the arithmetic.
- *
- * WHAT MAKES THIS DIFFERENT FROM THE ATTEMPT THAT WAS REVERTED (#6609): nothing
- * here hands out a half-built texture. The worker answers with NUMBERS, the
- * caller primes `blender-sky`'s texture cache with them, and only then does
- * anything build a texture -- and `pendingWorld`/`worldReady()` hold the capture
- * until it has. See `sky-worker.ts` and `WorldBackground.apply`.
- */
+/** Precompute sky texels in a worker and transfer the Float32Array. The caller primes the sky cache before constructing textures, and WorldBackground.ready holds captures until it is complete. */
 import { precomputeSkyTexture, type SkyParameters } from './blender-sky';
 
 export interface SkyWorkerRequest {

package/browser/three/sky-worker.ts

@@ -1,17 +1,5 @@
-/**
- * The page's side of the sky worker: one long-lived worker, one promise per sky.
- *
- * WHY A CLIENT MODULE AND NOT A `new Worker` AT THE CALL SITE: the worker is
- * built once and reused, because constructing one costs a module graph fetch and
- * a sky world re-derives on every sun edit. Requests are keyed by id so several
- * skies (a world split by `Is Camera Ray` has two) ride one worker.
- *
- * The type-only import of the worker module is LOAD-BEARING in two ways. It is
- * the contract for what crosses the boundary, and it is also how the probe
- * project's capability sync finds the worker file at all: that sync follows
- * `from './x'` spellings, and `new URL('./x.ts', import.meta.url)` is not one.
- * Delete the import and the worker silently stops being copied.
- */
+/** Share one long-lived worker across sky requests, keyed by id. The worker request and
+ * response types define the transfer contract. */
 import { precomputeSkyTexture, type SkyParameters } from './blender-sky';
 import type { SkyWorkerRequest, SkyWorkerResponse } from './sky-precompute-worker';
 
@@ -46,7 +34,7 @@ function ensureWorker(): Worker | null {
     else pending.reject(new Error(error ?? 'sky worker returned nothing'));
   };
   // A worker that dies takes every outstanding sky with it. Failing them LOUDLY
-  // is the point: `worldReady()` propagates, so a capture reports the error
+  // is the point: `WorldBackground.ready()` propagates, so a capture reports the error
   // rather than photographing a scene with no sky in it.
   worker.onerror = (event) => {
     const failure = new Error(`sky worker failed: ${event.message || 'unknown error'}`);
@@ -59,14 +47,8 @@ function ensureWorker(): Worker | null {
   return worker;
 }
 
-/**
- * One sky's 512x256 texture, derived OFF the main thread.
- *
- * Falls back to deriving it inline when there is no Worker (Node, a test, a
- * blocked construction). That fallback blocks -- which is the whole complaint --
- * but it is CORRECT, and correct-and-slow is the trade this lane already made
- * once by hand.
- */
+/** Precompute a sky texture off-thread. Environments without a constructible Worker compute
+ * the same texture inline; failures after worker startup reject all pending requests. */
 export function precomputeSkyOffThread(parameters: SkyParameters): Promise<Float32Array> {
   const active = ensureWorker();
   if (!active) return Promise.resolve(precomputeSkyTexture(parameters));

package/browser/three/world-field-sampler.ts

@@ -1,18 +1,4 @@
-/**
- * Sampling a world's radiance field — the expensive half of the world texture,
- * kept in its own module so a WORKER can own it.
- *
- * This is where the time goes. A sky expression derives Blender's
- * multiple-scattering model (`blender-sky.ts`, 512x256 with 64 in-scattering
- * steps per pixel) and then this samples 32,768 directions out of it. MEASURED:
- * 15.4 seconds. On the page's main thread that is not "slow", it is a FROZEN
- * EDITOR — the owner saw exactly that, and a status-bar spinner could not have
- * helped, because a blocked main thread cannot paint one.
- *
- * Nothing here touches the DOM, three's renderer, or any editor state: it takes
- * a description and returns numbers. That is what makes it movable, and it is
- * the reason the split is here rather than around something larger.
- */
+/** Sample a world-radiance description into numeric data. This module touches no DOM, renderer or editor state and can run in a worker. */
 import * as THREE from 'three';
 import { gradientTexture } from './blender-gradient-texture';
 // Type-only, so this module keeps NO runtime edge back to the contribution
@@ -100,10 +86,10 @@ export function worldField(
     // Built ONCE per node: the model precomputes a 512x256 texture, and
     // rebuilding it per direction would be a 65,536-pixel job per texel.
     const field = skyField({
-      ...(expression.sky_model === undefined ? {} : {model: expression.sky_model}),
-      ...(expression.sun_disc === undefined ? {} : {sunDisc: expression.sun_disc}),
-      ...(expression.sun_size === undefined ? {} : {sunSize: expression.sun_size}),
-      ...(expression.sun_intensity === undefined ? {} : {sunIntensity: expression.sun_intensity}),
+      model: expression.sky_model,
+      sunDisc: expression.sun_disc,
+      sunSize: expression.sun_size,
+      sunIntensity: expression.sun_intensity,
       sunElevation: expression.sun_elevation,
       sunRotation: expression.sun_rotation,
       altitude: expression.altitude,
@@ -257,10 +243,10 @@ export function collectSkyParameters(expression: WorldExpression): SkyParameters
     switch (node.kind) {
       case 'sky':
         found.push({
-          ...(node.sky_model === undefined ? {} : {model: node.sky_model}),
-          ...(node.sun_disc === undefined ? {} : {sunDisc: node.sun_disc}),
-          ...(node.sun_size === undefined ? {} : {sunSize: node.sun_size}),
-          ...(node.sun_intensity === undefined ? {} : {sunIntensity: node.sun_intensity}),
+          model: node.sky_model,
+          sunDisc: node.sun_disc,
+          sunSize: node.sun_size,
+          sunIntensity: node.sun_intensity,
           sunElevation: node.sun_elevation,
           sunRotation: node.sun_rotation,
           altitude: node.altitude,
@@ -317,7 +303,7 @@ export function withoutSolarDiscs(expression: WorldExpression): WorldExpression
 
 export function worldSolarIrradiance(expression: WorldExpression): {direction: THREE.Vector3; irradiance: THREE.Vector3}[] {
   const suns = collectSkyParameters(expression).filter(p => p.model === 'SINGLE_SCATTERING' &&
-    p.sunDisc && (p.sunSize ?? 0) > 0 && (p.sunIntensity ?? 1) > 0);
+    p.sunDisc && p.sunSize > 0 && p.sunIntensity > 0);
   if (!suns.length) return [];
   // Window-dependent world shaders need ray origins as well as directions;
   // there is no position-independent directional light for that field.
@@ -336,10 +322,10 @@ export function worldSolarIrradiance(expression: WorldExpression): {direction: T
       ? new THREE.Vector3(0, 0, 1) : new THREE.Vector3(0, 1, 0)).normalize();
     const v = new THREE.Vector3().crossVectors(direction, u);
     const irradiance = new THREE.Vector3(), ray = new THREE.Vector3(), delta = new THREE.Vector3();
-    const solidAngle = 2 * Math.PI * (1 - Math.cos(p.sunSize! / 2));
+    const solidAngle = 2 * Math.PI * (1 - Math.cos(p.sunSize / 2));
     const radial = 32, azimuthal = 32;
     for (let i = 0; i < radial; i++) {
-      const cos = 1 - (i + .5) / radial * (1 - Math.cos(p.sunSize! / 2));
+      const cos = 1 - (i + .5) / radial * (1 - Math.cos(p.sunSize / 2));
       const sin = Math.sqrt(1 - cos * cos);
       for (let j = 0; j < azimuthal; j++) {
         const phi = (j + .5) / azimuthal * 2 * Math.PI;