@volter/blender-engine 0.1.0

package/browser/three/blender-triangulate.ts

@@ -0,0 +1,181 @@
+/**
+ * `triangulate` — how a BMesh FACE becomes triangles, and the one place that
+ * decision is made.
+ *
+ * A `BMesh` face is an n-gon; a `BufferGeometry` is triangles. The conversion
+ * used to be a naive fan (`0,1,2`, `0,2,3`, `0,3,4`, …), which is correct for
+ * a CONVEX polygon and silently wrong for a concave one: the fan's later
+ * triangles fold back over the polygon's own reflex corner, so they overlap
+ * each other and face BACKWARDS. That renders as a hole. It shipped as one —
+ * the treasure chest's crescent lid end-cap (docs/BLENDER-PARITY.md §Driver
+ * ladder, "Chest-measured gaps") — and, worse, `validate()` had nothing to say
+ * about it, because every count and every winding on the BMesh side was
+ * perfectly sound. The defect only existed in the export.
+ *
+ * So the export's triangulation is now a real one, and it is the SAME
+ * function `validate` checks, which is what closes the gap: there is no way
+ * for the exporter to fan something the validator did not look at.
+ *
+ * THE RUNG. Ear clipping is not hand-rolled here: `THREE.ShapeUtils
+ * .triangulateShape` is three's own Earcut and ships in the dependency the
+ * kit already has. This module supplies only the two things Earcut cannot do
+ * for a 3D face — pick the plane to flatten onto, and decide whether the
+ * result is trustworthy.
+ *
+ * THE FAN IS STILL THE FAST PATH, and deliberately so. Every face is fanned
+ * FIRST and the fan is kept whenever it is sound, so every convex face — which
+ * is nearly all of them, quads included — exports with byte-identical indices
+ * to before this module existed. Earcut runs only where the fan actually
+ * fails. That is not an optimization: it is what lets an existing model be
+ * rebuilt through the fixed kit and change ONLY where it was broken.
+ */
+
+import * as THREE from 'three';
+
+/** One triangle, as indices into the polygon's own corner order. */
+export type TriangleIndices = readonly [number, number, number];
+
+/** What `triangulatePolygon` decided, and whether to trust it. */
+export interface PolygonTriangulation {
+  /** The triangles, in the polygon's own corner-index space and its own
+   *  winding. Always `n − 2` of them when `sound`; possibly fewer, or
+   *  overlapping, when not. */
+  readonly triangles: readonly TriangleIndices[];
+  /** Whether this is a genuine PARTITION of the polygon: `n − 2` triangles,
+   *  every one wound with the polygon, and their absolute areas summing to
+   *  the polygon's own. Overlap or a fold-back makes the sum exceed the
+   *  polygon area, so the two conditions together are exactly the property
+   *  that fails when a triangulation renders as a hole.
+   *
+   *  FALSE is a real defect and stays visible rather than being smoothed
+   *  over: it means the polygon is self-intersecting or so badly warped that
+   *  no flattening of it is simple, and neither the fan nor Earcut can fix
+   *  that. `validate` reports it as `overlappingTriangulation`. */
+  readonly sound: boolean;
+  /** Which path produced `triangles` — `'fan'` is the untouched legacy
+   *  layout, `'earcut'` is `THREE.ShapeUtils.triangulateShape`. */
+  readonly method: 'fan' | 'earcut';
+}
+
+/** Relative slack on the area-sum test, in units of the polygon's own area.
+ *  Generous enough that float noise on a big polygon never fires it, tight
+ *  enough that a single folded-back ear (which doubles some sub-area) always
+ *  does. */
+const AREA_TOLERANCE = 1e-6;
+
+/** The polygon's Newell area-weighted normal — the standard best-fit plane
+ *  for a possibly non-planar face, and the one whose length is twice the
+ *  projected area. */
+function newellNormal(points: readonly THREE.Vector3[]): THREE.Vector3 {
+  const n = new THREE.Vector3();
+  for (let i = 0; i < points.length; i++) {
+    const a = points[i] as THREE.Vector3;
+    const b = points[(i + 1) % points.length] as THREE.Vector3;
+    n.x += (a.y - b.y) * (a.z + b.z);
+    n.y += (a.z - b.z) * (a.x + b.x);
+    n.z += (a.x - b.x) * (a.y + b.y);
+  }
+  return n.multiplyScalar(0.5);
+}
+
+/** Twice the signed area of a 2D triangle (positive = counter-clockwise). */
+const cross2 = (a: THREE.Vector2, b: THREE.Vector2, c: THREE.Vector2): number =>
+  (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+
+/** The consecutive fan from corner 0 — the layout every export used before
+ *  this module, reproduced exactly so a sound fan stays byte-identical. */
+const fanOf = (n: number): TriangleIndices[] =>
+  Array.from({ length: n - 2 }, (_, i) => [0, i + 1, i + 2] as const);
+
+/** Twice the signed area of the projected polygon (shoelace). */
+function polygonArea2(flat: readonly THREE.Vector2[]): number {
+  let sum = 0;
+  for (let i = 0; i < flat.length; i++) {
+    const a = flat[i] as THREE.Vector2;
+    const b = flat[(i + 1) % flat.length] as THREE.Vector2;
+    sum += a.x * b.y - b.x * a.y;
+  }
+  return sum;
+}
+
+/** Is `triangles` a partition of the projected polygon — right count, all
+ *  wound with it, and no area double-covered? See `PolygonTriangulation
+ *  .sound`. */
+function isSound(
+  triangles: readonly TriangleIndices[],
+  flat: readonly THREE.Vector2[],
+  area2: number,
+): boolean {
+  if (triangles.length !== flat.length - 2) return false;
+  if (!(Math.abs(area2) > 0)) return false;
+  const sign = Math.sign(area2);
+  let covered = 0;
+  for (const [i, j, k] of triangles) {
+    const t = cross2(flat[i] as THREE.Vector2, flat[j] as THREE.Vector2, flat[k] as THREE.Vector2);
+    // A sliver of exactly zero area is harmless (it covers nothing and hides
+    // nothing); a triangle wound AGAINST the polygon is the fold-back.
+    if (t * sign < 0) return false;
+    covered += Math.abs(t);
+  }
+  return Math.abs(covered - Math.abs(area2)) <= AREA_TOLERANCE * Math.abs(area2);
+}
+
+/**
+ * Triangulate one polygon given its corner positions in order.
+ *
+ * The polygon is flattened onto its own Newell plane with a right-handed
+ * basis, so the projection keeps the polygon's winding and the resulting
+ * triangles come back in the corner-index space the caller passed in. Under 3
+ * corners there is nothing to do; at exactly 3 the single triangle IS the
+ * polygon.
+ *
+ * A degenerate face — zero Newell normal, i.e. no plane to flatten onto — is
+ * reported as an unsound fan rather than throwing: `validate` already has
+ * `degenerateFace` for that condition and says it better, and an exporter
+ * that threw here would refuse a mesh it could still write.
+ */
+export function triangulatePolygon(points: readonly THREE.Vector3[]): PolygonTriangulation {
+  const n = points.length;
+  if (n < 3) return { triangles: [], sound: false, method: 'fan' };
+  if (n === 3) return { triangles: [[0, 1, 2]], sound: true, method: 'fan' };
+
+  const normal = newellNormal(points);
+  const length = normal.length();
+  if (!(length > 0) || !Number.isFinite(length)) {
+    return { triangles: fanOf(n), sound: false, method: 'fan' };
+  }
+  const w = normal.clone().divideScalar(length);
+  // Any vector not parallel to w gives a usable in-plane axis.
+  const seed = Math.abs(w.x) < 0.9 ? new THREE.Vector3(1, 0, 0) : new THREE.Vector3(0, 1, 0);
+  const u = new THREE.Vector3().crossVectors(seed, w).normalize();
+  const v = new THREE.Vector3().crossVectors(w, u);
+  const origin = points[0] as THREE.Vector3;
+  const flat = points.map((p) => {
+    const d = p.clone().sub(origin);
+    return new THREE.Vector2(d.dot(u), d.dot(v));
+  });
+  const area2 = polygonArea2(flat);
+
+  const fan = fanOf(n);
+  if (isSound(fan, flat, area2)) return { triangles: fan, sound: true, method: 'fan' };
+
+  // The fan folded back. Hand the flattened contour to three's own Earcut.
+  let earcut: TriangleIndices[] = [];
+  try {
+    earcut = THREE.ShapeUtils.triangulateShape(flat as THREE.Vector2[], []).map(
+      (t) => [t[0] as number, t[1] as number, t[2] as number] as const,
+    );
+  } catch {
+    // Earcut refuses a contour it cannot read at all; the fan is still the
+    // honest thing to hand back, flagged unsound.
+    return { triangles: fan, sound: false, method: 'fan' };
+  }
+  if (isSound(earcut, flat, area2)) return { triangles: earcut, sound: true, method: 'earcut' };
+  // Earcut produced something, but not a partition: keep it (it is still
+  // closer than the fan) and let `validate` name the face.
+  return {
+    triangles: earcut.length > 0 ? earcut : fan,
+    sound: false,
+    method: earcut.length > 0 ? 'earcut' : 'fan',
+  };
+}

package/browser/three/presenter.ts

@@ -0,0 +1,265 @@
+/**
+ * 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/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 encoders the editor uses for AgX and Filmic.
+ */
+import * as THREE from 'three';
+import type { CaptureRequest, RenderRequest } from '../protocol';
+import type { PresentAnswer } from '../runtime';
+import { AGX_LOOK_TABLES, agxEncodeFrame } from './blender-agx';
+import { displayTableUrl } from './blender-display-lut';
+import { filmicEncodeFrame } from './blender-filmic';
+import { BlenderRuntimeView } from './blender-runtime-view';
+import { standardEncodeFrame } from './blender-standard';
+
+export interface PresenterOptions {
+  /** The canvas to render into; an OffscreenCanvas of 1x1 when absent. */
+  canvas?: HTMLCanvasElement | OffscreenCanvas;
+  /** The photograph camera's clipping; the editor's stage camera values. */
+  near?: number;
+  far?: number;
+}
+
+export interface Presenter {
+  /** The translated scene, for a host that also wants to SHOW it. */
+  readonly view: BlenderRuntimeView;
+  readonly scene: THREE.Scene;
+  /** `BlenderRuntimeOptions.present`, answered here. */
+  present(frame: unknown, description: unknown, capture?: CaptureRequest): Promise<PresentAnswer>;
+  dispose(): void;
+}
+
+const MAXIMUM_EDGE = 2048;
+
+const displayTables = new Map<string, Promise<Uint16Array>>();
+function displayTable(file: string): Promise<Uint16Array> {
+  let pending = displayTables.get(file);
+  if (!pending) {
+    pending = fetch(displayTableUrl(file)).then(async (response) => {
+      if (!response.ok)
+        throw new Error(`Blender display table ${file}: ${response.status} ${response.statusText}`);
+      return new Uint16Array(await response.arrayBuffer());
+    });
+    displayTables.set(file, pending);
+  }
+  return pending;
+}
+
+function displayTableFor(render: RenderRequest): string | null {
+  const look = render.look ?? 'None';
+  if (render.toneMapping === 'none') return null;
+  if (render.toneMapping === 'filmic') return 'filmic-srgb.lut';
+  if (render.toneMapping !== 'agx')
+    throw new Error(
+      `Blender's Khronos PBR Neutral view transform has no scene-linear implementation in the ` +
+        `browser (implemented: Standard, AgX, Filmic)`,
+    );
+  if (look === 'None') return 'agx-base-srgb.lut';
+  const file = AGX_LOOK_TABLES[look as keyof typeof AGX_LOOK_TABLES];
+  if (file === undefined) throw new Error(`Blender display transform has no table for look ${look}`);
+  return file;
+}
+
+async function pngBase64(bytes: Uint8Array | Uint8ClampedArray, width: number, height: number): Promise<string> {
+  // The linear capture is bottom-up (GL); the image is top-down.
+  const stride = width * 4;
+  const image = new Uint8ClampedArray(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    const source = (height - 1 - y) * stride;
+    image.set(bytes.subarray(source, source + stride), y * stride);
+  }
+  const data = new ImageData(image, width, height);
+  if (typeof document !== 'undefined') {
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('Blender display transform could not create its image canvas');
+    context.putImageData(data, 0, 0);
+    const dataUrl = canvas.toDataURL('image/png');
+    return dataUrl.slice(dataUrl.indexOf(',') + 1);
+  }
+  const canvas = new OffscreenCanvas(width, height);
+  const context = canvas.getContext('2d');
+  if (!context) throw new Error('Blender display transform could not create its image canvas');
+  context.putImageData(data, 0, 0);
+  const blob = await canvas.convertToBlob({ type: 'image/png' });
+  const raw = new Uint8Array(await blob.arrayBuffer());
+  let binary = '';
+  for (let i = 0; i < raw.length; i += 0x8000)
+    binary += String.fromCharCode(...raw.subarray(i, i + 0x8000));
+  return btoa(binary);
+}
+
+export function createPresenter(options: PresenterOptions = {}): Presenter {
+  const view = new BlenderRuntimeView();
+  const scene = new THREE.Scene();
+  scene.add(view.root);
+  const canvas = options.canvas ?? new OffscreenCanvas(1, 1);
+  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  renderer.shadowMap.enabled = true;
+  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+  renderer.setPixelRatio(1);
+  const near = options.near ?? 0.1;
+  const far = options.far ?? 1000;
+
+  async function present(
+    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;
+    view.recordPresentation(description);
+    const answer = (photograph?: unknown): PresentAnswer => ({
+      ...(photograph === undefined ? {} : { capture: photograph }),
+      held,
+    });
+    const render = capture?.render;
+    if (!render) return answer();
+    const { position, target, up } = capture;
+    if (!position || !target || !up)
+      throw new Error('A Blender render capture must carry the scene camera position, target and up');
+
+    // THE PHOTOGRAPH HAS ITS OWN CAMERA, placed from Blender's frame through the
+    // model root's Z-up -> Y-up matrix and reported back through its inverse —
+    // exactly as the editor's host does, because `session.py` asserts the echo.
+    view.root.updateMatrixWorld(true);
+    const toDocument = view.root.matrixWorld;
+    const toBlender = new THREE.Matrix4().copy(toDocument).invert();
+    const documentBasis = new THREE.Matrix3().setFromMatrix4(toDocument);
+    const blenderBasis = new THREE.Matrix3().setFromMatrix4(toBlender);
+    const eye = new THREE.Vector3(position[0], position[1], position[2]).applyMatrix4(toDocument);
+    const focus = new THREE.Vector3(target[0], target[1], target[2]).applyMatrix4(toDocument);
+    const upward = new THREE.Vector3(up[0], up[1], up[2]).applyMatrix3(documentBasis);
+    const width = Math.min(MAXIMUM_EDGE, Math.round(render.width));
+    const height = Math.min(MAXIMUM_EDGE, Math.round(render.height));
+    const aspect = width / height;
+    const camera: THREE.Camera = render.orthographic
+      ? new THREE.OrthographicCamera(
+          (-render.fov / 2) * aspect,
+          (render.fov / 2) * aspect,
+          render.fov / 2,
+          -render.fov / 2,
+          near,
+          far,
+        )
+      : new THREE.PerspectiveCamera(render.fov, aspect, near, far);
+    camera.up.copy(upward);
+    camera.position.copy(eye);
+    camera.lookAt(focus);
+    camera.updateMatrixWorld(true);
+    const photographedFrom = {
+      position: eye.clone().applyMatrix4(toBlender).toArray(),
+      target: focus.clone().applyMatrix4(toBlender).toArray(),
+      up: upward.clone().applyMatrix3(blenderBasis).toArray(),
+    };
+    view.recordPhotograph({
+      sent: { position, target, up },
+      photographed: photographedFrom,
+      render: { width, height, fov: render.fov, orthographic: render.orthographic },
+    });
+
+    const tableFile = displayTableFor(render);
+    const table = tableFile ? await displayTable(tableFile) : null;
+    const mappings: Record<string, THREE.ToneMapping> = {
+      none: THREE.NoToneMapping,
+      agx: THREE.AgXToneMapping,
+      neutral: THREE.NeutralToneMapping,
+      filmic: THREE.NoToneMapping,
+    };
+    const previousMapping = renderer.toneMapping;
+    const previousExposure = renderer.toneMappingExposure;
+    renderer.toneMapping = mappings[render.toneMapping] ?? THREE.AgXToneMapping;
+    renderer.toneMappingExposure = render.exposure;
+    const sceneTarget = new THREE.WebGLRenderTarget(width, height, { type: THREE.HalfFloatType });
+    try {
+      await view.setRendered(true, camera);
+      let pixels: Uint16Array;
+      if (render.linearInput) {
+        pixels = halfFloatFrame(render.linearInput.base64);
+      } else {
+        renderer.setSize(width, height, false);
+        renderer.setRenderTarget(sceneTarget);
+        const background = scene.background;
+        if (render.transparent) {
+          scene.background = null;
+          renderer.setClearColor(0, 0);
+        }
+        try {
+          renderer.render(scene, camera);
+        } finally {
+          scene.background = background;
+        }
+        pixels = new Uint16Array(width * height * 4);
+        renderer.readRenderTargetPixels(sceneTarget, 0, 0, width, height, pixels);
+        renderer.setRenderTarget(null);
+      }
+      const count = width * height;
+      const bytes =
+        render.toneMapping === 'none'
+          ? standardEncodeFrame(pixels, count, render.exposure)
+          : render.toneMapping === 'filmic'
+            ? filmicEncodeFrame(table!, pixels, count, render.exposure)
+            : agxEncodeFrame(table!, pixels, count, {
+                exposure: render.exposure,
+                composedLook: (render.look ?? 'None') !== 'None',
+              });
+      const photograph: Record<string, unknown> = {
+        base64: await pngBase64(bytes, width, height),
+        mimeType: 'image/png',
+        camera: photographedFrom,
+      };
+      if (render.linear === true) {
+        const raw = new Uint8Array(pixels.buffer, pixels.byteOffset, pixels.byteLength);
+        let binary = '';
+        for (let i = 0; i < raw.length; i += 0x8000)
+          binary += String.fromCharCode(...raw.subarray(i, i + 0x8000));
+        photograph['linearBase64'] = btoa(binary);
+        photograph['linearWidth'] = width;
+        photograph['linearHeight'] = height;
+      }
+      return answer(photograph);
+    } finally {
+      sceneTarget.dispose();
+      renderer.toneMapping = previousMapping;
+      renderer.toneMappingExposure = previousExposure;
+      await view.setRendered(false);
+    }
+  }
+
+  return {
+    view,
+    scene,
+    present,
+    dispose() {
+      renderer.dispose();
+    },
+  };
+}
+
+/** 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);
+  return new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1);
+}

package/browser/three/release.ts

@@ -0,0 +1,27 @@
+/**
+ * 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/vgai-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.
+ */
+export { attachPresenter } from './attach-presenter';
+export type { AttachablePresenter, PresenterFileSystem } from './attach-presenter';
+export { createPresenter } from './presenter';
+export type { Presenter, PresenterOptions } from './presenter';

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

@@ -0,0 +1,45 @@
+/**
+ * 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`.
+ */
+import { precomputeSkyTexture, type SkyParameters } from './blender-sky';
+
+export interface SkyWorkerRequest {
+  id: number;
+  parameters: SkyParameters;
+}
+
+export interface SkyWorkerResponse {
+  id: number;
+  pixels?: Float32Array;
+  error?: string;
+}
+
+const scope = self as unknown as {
+  onmessage: ((event: MessageEvent<SkyWorkerRequest>) => void) | null;
+  postMessage: (message: SkyWorkerResponse, transfer?: Transferable[]) => void;
+};
+
+scope.onmessage = (event) => {
+  const { id, parameters } = event.data;
+  try {
+    const pixels = precomputeSkyTexture(parameters);
+    scope.postMessage({ id, pixels }, [pixels.buffer]);
+  } catch (error) {
+    scope.postMessage({ id, error: error instanceof Error ? error.message : String(error) });
+  }
+};

package/browser/three/sky-worker.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ */
+import { precomputeSkyTexture, type SkyParameters } from './blender-sky';
+import type { SkyWorkerRequest, SkyWorkerResponse } from './sky-precompute-worker';
+
+let worker: Worker | null = null;
+let workerUnavailable = false;
+let nextId = 0;
+const waiting = new Map<
+  number,
+  { resolve: (pixels: Float32Array) => void; reject: (error: Error) => void }
+>();
+
+function ensureWorker(): Worker | null {
+  if (worker || workerUnavailable) return worker;
+  if (typeof Worker === 'undefined') {
+    workerUnavailable = true;
+    return null;
+  }
+  try {
+    worker = new Worker(new URL('./sky-precompute-worker.ts', import.meta.url), {
+      type: 'module',
+    });
+  } catch {
+    workerUnavailable = true;
+    return null;
+  }
+  worker.onmessage = (event: MessageEvent<SkyWorkerResponse>) => {
+    const { id, pixels, error } = event.data;
+    const pending = waiting.get(id);
+    if (!pending) return;
+    waiting.delete(id);
+    if (pixels) pending.resolve(pixels);
+    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
+  // rather than photographing a scene with no sky in it.
+  worker.onerror = (event) => {
+    const failure = new Error(`sky worker failed: ${event.message || 'unknown error'}`);
+    for (const pending of waiting.values()) pending.reject(failure);
+    waiting.clear();
+    worker?.terminate();
+    worker = null;
+    workerUnavailable = true;
+  };
+  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.
+ */
+export function precomputeSkyOffThread(parameters: SkyParameters): Promise<Float32Array> {
+  const active = ensureWorker();
+  if (!active) return Promise.resolve(precomputeSkyTexture(parameters));
+  const id = nextId++;
+  const request: SkyWorkerRequest = { id, parameters };
+  return new Promise<Float32Array>((resolve, reject) => {
+    waiting.set(id, { resolve, reject });
+    active.postMessage(request);
+  });
+}