@tinypoly/gpu-renderer 0.0.0-stage → 0.0.0

package/dist/wgsl/surface.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.wgsl.js","sourceRoot":"","sources":["../../src/wgsl/surface.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgxBtC,CAAC"}

package/dist/wgsl/texture.wgsl.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reading a texel by hand, because core WebGPU offers no other way here: there are no binding arrays, and one
+ * texture_2d_array would force a single size and format on a scene that has neither. The filtering, the wrap modes and
+ * the sRGB decode follow texture.js in the CPU renderer so the two agree on what a texture says.
+ *
+ * Only the top level is read. A rasterizer needs mip levels to stop minified texture detail from aliasing, but this
+ * renderer already draws many jittered samples through every pixel, which averages that detail properly instead of
+ * approximating it. Levels would buy memory locality, not correctness, so they can wait.
+ */
+export declare const TEXTURE_WGSL = "\nconst TEXTURE_FLOAT: u32 = 1u;\nconst TEXTURE_SRGB: u32 = 2u;\nconst TEXTURE_NEAREST: u32 = 4u;\nconst TEXTURE_FLIP_Y: u32 = 8u;\n\n// Three's own wrap constants. Anything else clamps, as it does in the CPU renderer.\nconst WRAP_REPEAT: u32 = 1000u;\nconst WRAP_MIRROR: u32 = 1002u;\n\n/** Brings a texel index inside the texture the way the wrap mode says to. */\nfn wrapIndex(index: i32, size: i32, mode: u32) -> i32 {\n  if (mode == WRAP_REPEAT) {\n    return ((index % size) + size) % size;\n  }\n\n  if (mode == WRAP_MIRROR) {\n    let period = size * 2;\n    let folded = ((index % period) + period) % period;\n\n    return select(period - 1 - folded, folded, folded < size);\n  }\n\n  return clamp(index, 0, size - 1);\n}\n\nfn srgbChannelToLinear(value: f32) -> f32 {\n  return select(pow((value + 0.055) / 1.055, 2.4), value / 12.92, value <= 0.04045);\n}\n\n/** One texel, in linear light. Alpha is never encoded, as in Three. */\nfn readTexel(info: TextureInfo, x: i32, y: i32) -> vec4<f32> {\n  let index = u32(y) * info.size.x + u32(x);\n\n  if ((info.flags & TEXTURE_FLOAT) != 0u) {\n    let at = info.offset + index * 4u;\n\n    return vec4<f32>(\n      bitcast<f32>(textures[at]),\n      bitcast<f32>(textures[at + 1u]),\n      bitcast<f32>(textures[at + 2u]),\n      bitcast<f32>(textures[at + 3u]));\n  }\n\n  let word = textures[info.offset + index];\n  let raw = vec4<f32>(\n    f32(word & 0xffu),\n    f32((word >> 8u) & 0xffu),\n    f32((word >> 16u) & 0xffu),\n    f32((word >> 24u) & 0xffu)) / 255.0;\n\n  if ((info.flags & TEXTURE_SRGB) != 0u) {\n    return vec4<f32>(\n      srgbChannelToLinear(raw.r), srgbChannelToLinear(raw.g), srgbChannelToLinear(raw.b), raw.a);\n  }\n\n  return raw;\n}\n\n/** One texture of the table, sampled with its own transform, wrap modes and filter. */\nfn sampleTextureAt(index: u32, uv: vec2<f32>) -> vec4<f32> {\n  let info = textureInfo(index);\n  // The affine transform Three keeps on the texture, one row at a time.\n  let transformed = vec2<f32>(\n    dot(info.rowU.xyz, vec3<f32>(uv, 1.0)),\n    dot(info.rowV.xyz, vec3<f32>(uv, 1.0)));\n\n  return sampleTextureInfo(info, transformed);\n}\n\n/**\n * A texture read the way GLSL's texture2D reads it: at the coordinates given, with no transform. Three applies a\n * texture's matrix in its own materials' shaders, so a shader of the scene's, an environment lookup and a light's\n * projected map do not get it.\n */\nfn sampleTextureRaw(index: u32, uv: vec2<f32>) -> vec4<f32> {\n  return sampleTextureInfo(textureInfo(index), uv);\n}\n\n/** Three's equirectUv: longitude across, and latitude up from the bottom of the image, as GL reads it. */\nfn equirectUv(direction: vec3<f32>) -> vec2<f32> {\n  let d = normalize(direction);\n\n  return vec2<f32>(atan2(d.z, d.x) / (2.0 * PI) + 0.5, asin(clamp(d.y, -1.0, 1.0)) / PI + 0.5);\n}\n\n/** An environment map of the scene's: an equirectangular image, or a cube map the snapshot already unwrapped into one. */\nfn sampleEquirect(index: u32, direction: vec3<f32>) -> vec4<f32> {\n  return sampleTextureRaw(index, equirectUv(direction));\n}\n\nfn sampleTextureInfo(info: TextureInfo, transformed: vec2<f32>) -> vec4<f32> {\n  if (!all(transformed == transformed) || info.size.x == 0u || info.size.y == 0u) {\n    return vec4<f32>(0.0);\n  }\n\n  let flipped = select(transformed.y, 1.0 - transformed.y, (info.flags & TEXTURE_FLIP_Y) != 0u);\n  let size = vec2<i32>(info.size);\n  // The half texel offset that puts a sample in the middle of a texel, as on a graphics pipeline.\n  let centred = vec2<f32>(transformed.x, flipped) * vec2<f32>(info.size) - 0.5;\n\n  if ((info.flags & TEXTURE_NEAREST) != 0u) {\n    let at = vec2<i32>(floor(centred + 0.5));\n\n    return readTexel(info, wrapIndex(at.x, size.x, info.wrapS), wrapIndex(at.y, size.y, info.wrapT));\n  }\n\n  let low = floor(centred);\n  let fraction = centred - low;\n  let base = vec2<i32>(low);\n  let x0 = wrapIndex(base.x, size.x, info.wrapS);\n  let x1 = wrapIndex(base.x + 1, size.x, info.wrapS);\n  let y0 = wrapIndex(base.y, size.y, info.wrapT);\n  let y1 = wrapIndex(base.y + 1, size.y, info.wrapT);\n\n  // The four corners are blended in linear light, which is why the decode happens per texel above.\n  return mix(\n    mix(readTexel(info, x0, y0), readTexel(info, x1, y0), fraction.x),\n    mix(readTexel(info, x0, y1), readTexel(info, x1, y1), fraction.x),\n    fraction.y);\n}\n";
+//# sourceMappingURL=texture.wgsl.d.ts.map

package/dist/wgsl/texture.wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture.wgsl.d.ts","sourceRoot":"","sources":["../../src/wgsl/texture.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,s0IAyHxB,CAAC"}

package/dist/wgsl/texture.wgsl.js

@@ -0,0 +1,132 @@
+/**
+ * Reading a texel by hand, because core WebGPU offers no other way here: there are no binding arrays, and one
+ * texture_2d_array would force a single size and format on a scene that has neither. The filtering, the wrap modes and
+ * the sRGB decode follow texture.js in the CPU renderer so the two agree on what a texture says.
+ *
+ * Only the top level is read. A rasterizer needs mip levels to stop minified texture detail from aliasing, but this
+ * renderer already draws many jittered samples through every pixel, which averages that detail properly instead of
+ * approximating it. Levels would buy memory locality, not correctness, so they can wait.
+ */
+export const TEXTURE_WGSL = /* wgsl */ `
+const TEXTURE_FLOAT: u32 = 1u;
+const TEXTURE_SRGB: u32 = 2u;
+const TEXTURE_NEAREST: u32 = 4u;
+const TEXTURE_FLIP_Y: u32 = 8u;
+
+// Three's own wrap constants. Anything else clamps, as it does in the CPU renderer.
+const WRAP_REPEAT: u32 = 1000u;
+const WRAP_MIRROR: u32 = 1002u;
+
+/** Brings a texel index inside the texture the way the wrap mode says to. */
+fn wrapIndex(index: i32, size: i32, mode: u32) -> i32 {
+  if (mode == WRAP_REPEAT) {
+    return ((index % size) + size) % size;
+  }
+
+  if (mode == WRAP_MIRROR) {
+    let period = size * 2;
+    let folded = ((index % period) + period) % period;
+
+    return select(period - 1 - folded, folded, folded < size);
+  }
+
+  return clamp(index, 0, size - 1);
+}
+
+fn srgbChannelToLinear(value: f32) -> f32 {
+  return select(pow((value + 0.055) / 1.055, 2.4), value / 12.92, value <= 0.04045);
+}
+
+/** One texel, in linear light. Alpha is never encoded, as in Three. */
+fn readTexel(info: TextureInfo, x: i32, y: i32) -> vec4<f32> {
+  let index = u32(y) * info.size.x + u32(x);
+
+  if ((info.flags & TEXTURE_FLOAT) != 0u) {
+    let at = info.offset + index * 4u;
+
+    return vec4<f32>(
+      bitcast<f32>(textures[at]),
+      bitcast<f32>(textures[at + 1u]),
+      bitcast<f32>(textures[at + 2u]),
+      bitcast<f32>(textures[at + 3u]));
+  }
+
+  let word = textures[info.offset + index];
+  let raw = vec4<f32>(
+    f32(word & 0xffu),
+    f32((word >> 8u) & 0xffu),
+    f32((word >> 16u) & 0xffu),
+    f32((word >> 24u) & 0xffu)) / 255.0;
+
+  if ((info.flags & TEXTURE_SRGB) != 0u) {
+    return vec4<f32>(
+      srgbChannelToLinear(raw.r), srgbChannelToLinear(raw.g), srgbChannelToLinear(raw.b), raw.a);
+  }
+
+  return raw;
+}
+
+/** One texture of the table, sampled with its own transform, wrap modes and filter. */
+fn sampleTextureAt(index: u32, uv: vec2<f32>) -> vec4<f32> {
+  let info = textureInfo(index);
+  // The affine transform Three keeps on the texture, one row at a time.
+  let transformed = vec2<f32>(
+    dot(info.rowU.xyz, vec3<f32>(uv, 1.0)),
+    dot(info.rowV.xyz, vec3<f32>(uv, 1.0)));
+
+  return sampleTextureInfo(info, transformed);
+}
+
+/**
+ * A texture read the way GLSL's texture2D reads it: at the coordinates given, with no transform. Three applies a
+ * texture's matrix in its own materials' shaders, so a shader of the scene's, an environment lookup and a light's
+ * projected map do not get it.
+ */
+fn sampleTextureRaw(index: u32, uv: vec2<f32>) -> vec4<f32> {
+  return sampleTextureInfo(textureInfo(index), uv);
+}
+
+/** Three's equirectUv: longitude across, and latitude up from the bottom of the image, as GL reads it. */
+fn equirectUv(direction: vec3<f32>) -> vec2<f32> {
+  let d = normalize(direction);
+
+  return vec2<f32>(atan2(d.z, d.x) / (2.0 * PI) + 0.5, asin(clamp(d.y, -1.0, 1.0)) / PI + 0.5);
+}
+
+/** An environment map of the scene's: an equirectangular image, or a cube map the snapshot already unwrapped into one. */
+fn sampleEquirect(index: u32, direction: vec3<f32>) -> vec4<f32> {
+  return sampleTextureRaw(index, equirectUv(direction));
+}
+
+fn sampleTextureInfo(info: TextureInfo, transformed: vec2<f32>) -> vec4<f32> {
+  if (!all(transformed == transformed) || info.size.x == 0u || info.size.y == 0u) {
+    return vec4<f32>(0.0);
+  }
+
+  let flipped = select(transformed.y, 1.0 - transformed.y, (info.flags & TEXTURE_FLIP_Y) != 0u);
+  let size = vec2<i32>(info.size);
+  // The half texel offset that puts a sample in the middle of a texel, as on a graphics pipeline.
+  let centred = vec2<f32>(transformed.x, flipped) * vec2<f32>(info.size) - 0.5;
+
+  if ((info.flags & TEXTURE_NEAREST) != 0u) {
+    let at = vec2<i32>(floor(centred + 0.5));
+
+    return readTexel(info, wrapIndex(at.x, size.x, info.wrapS), wrapIndex(at.y, size.y, info.wrapT));
+  }
+
+  let low = floor(centred);
+  let fraction = centred - low;
+  let base = vec2<i32>(low);
+  let x0 = wrapIndex(base.x, size.x, info.wrapS);
+  let x1 = wrapIndex(base.x + 1, size.x, info.wrapS);
+  let y0 = wrapIndex(base.y, size.y, info.wrapT);
+  let y1 = wrapIndex(base.y + 1, size.y, info.wrapT);
+
+  // The four corners are blended in linear light, which is why the decode happens per texel above.
+  return mix(
+    mix(readTexel(info, x0, y0), readTexel(info, x1, y0), fraction.x),
+    mix(readTexel(info, x0, y1), readTexel(info, x1, y1), fraction.x),
+    fraction.y);
+}
+`;
+//# sourceMappingURL=texture.wgsl.js.map

package/dist/wgsl/texture.wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture.wgsl.js","sourceRoot":"","sources":["../../src/wgsl/texture.wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyHtC,CAAC"}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@tinypoly/gpu-renderer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "WebGPU path tracer for Three.js scenes: BVH traversal, progressive accumulation and tone mapping in WGSL compute shaders.",
+  "keywords": [
+    "three",
+    "threejs",
+    "renderer",
+    "webgpu",
+    "wgsl",
+    "path-tracing",
+    "ray-tracing",
+    "global-illumination",
+    "compute-shader"
+  ],
+  "license": "MIT",
+  "author": "Danilo Gadelha",
+  "homepage": "https://github.com/tinypoly/gpu-renderer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tinypoly/gpu-renderer.git"
+  },
+  "bugs": "https://github.com/tinypoly/gpu-renderer/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "src",
+    "!src/**/*.test.ts",
+    "ARCHITECTURE.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@tinypoly/cpu-renderer": "^0.3.0",
+    "naga-wasm": "30.2.0"
+  },
+  "peerDependencies": {
+    "three": ">=0.185.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/node": "^24",
+    "@types/three": "^0.185.4",
+    "@webgpu/types": "^0.1.40",
+    "eslint": "^10.11.0",
+    "globals": "^17.12.0",
+    "three": "^0.185.1",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.63.0",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p example",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "node scripts/verify.mjs",
+    "capture:scenes": "node scripts/capture-scenes.js",
+    "dev": "tsc -p tsconfig.build.json && vite --config example/vite.config.ts",
+    "build:example": "tsc -p tsconfig.build.json && vite build --config example/vite.config.ts"
+  }
 }

package/src/accumulator.ts

@@ -0,0 +1,64 @@
+/**
+ * Where the samples pile up: one `vec4<f32>` per pixel, rgb summed radiance and w the number of samples that reached
+ * it, then a second `vec4<f32>` per pixel whose x sums the coverage, which is what a transparent background reads as
+ * alpha, y the depth of the first surface, z and w the squared luminance of the diffuse and the specular signal, which
+ * give each its variance. Then the denoiser's guides and signals, each summed: the diffuse albedo with the roughness,
+ * the normal with the distance, the diffuse radiance with the specular hit distance, and the specular albedo. Last comes
+ * one `vec4<f32>` per row, set when a pass traced anything in that row: adaptive sampling reads it back to know which
+ * rows still have pixels that have not converged. A storage buffer rather than a storage texture, because `rgba32float` only allows write access as a texture,
+ * and the presentation pass has to read back what is already there.
+ */
+export class Accumulator {
+  buffer: GPUBuffer;
+  width: number;
+  height: number;
+
+  constructor(private readonly device: GPUDevice, width: number, height: number) {
+    this.width = Math.max(1, Math.floor(width));
+    this.height = Math.max(1, Math.floor(height));
+    this.buffer = this.create();
+  }
+
+  get byteLength(): number {
+    return (this.width * this.height * 6 + this.height) * 16;
+  }
+
+  /** Where the per-row flags start, in bytes. */
+  get rowFlagsOffset(): number {
+    return this.width * this.height * 96;
+  }
+
+  get rowFlagsLength(): number {
+    return this.height * 16;
+  }
+
+  /** Reallocates only when the size actually changed; the caller clears it either way. */
+  resize(width: number, height: number): boolean {
+    const next = { width: Math.max(1, Math.floor(width)), height: Math.max(1, Math.floor(height)) };
+
+    if (next.width === this.width && next.height === this.height) return false;
+
+    this.buffer.destroy();
+    this.width = next.width;
+    this.height = next.height;
+    this.buffer = this.create();
+
+    return true;
+  }
+
+  clear(encoder: GPUCommandEncoder) {
+    encoder.clearBuffer(this.buffer);
+  }
+
+  destroy() {
+    this.buffer.destroy();
+  }
+
+  private create(): GPUBuffer {
+    return this.device.createBuffer({
+      size: this.byteLength,
+      // clearBuffer is a copy into the buffer: without COPY_DST it fails validation and clears nothing.
+      usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+    });
+  }
+}

package/src/bvh.ts

@@ -0,0 +1,272 @@
+/**
+ * Binned SAH bounding volume hierarchy, built straight into the layout the shader reads: eight words per node, the
+ * first four a minimum corner and a left child or leaf start, the last four a maximum corner and a right child or
+ * triangle count, matching `struct BvhNode` in `wgsl/bvh.wgsl.ts`.
+ *
+ * The bounds are computed from the same `Float32Array` the shader traverses, so every corner is already a float and
+ * needs no widening. Building from double precision positions, as the CPU renderer does, would need each minimum
+ * rounded down and each maximum rounded up before they reach the GPU.
+ */
+
+/** Words per node in the packed buffer. */
+export const NODE_WORDS = 8;
+
+/** Triangles a leaf may hold. */
+const MAX_LEAF_SIZE = 4;
+
+/** Candidate split positions evaluated per axis. */
+const BIN_COUNT = 12;
+
+/** What descending one more level costs, relative to intersecting one triangle. */
+const TRAVERSAL_COST = 0.125;
+
+/**
+ * Deepest node the builder produces. The shader traverses with a fixed stack, and one entry per level is enough
+ * because a node only pushes its far child. Depth is capped rather than trusted.
+ */
+export const MAX_BVH_DEPTH = 32;
+
+export interface PackedBvh {
+  /** `nodeCount * NODE_WORDS` words, read as floats for the corners and as signed integers for the links. */
+  nodes: ArrayBuffer;
+  nodeCount: number;
+  /** Triangle indices in leaf order: a leaf covers `order[start] .. order[start + count - 1]`. */
+  order: Uint32Array;
+  maxDepth: number;
+}
+
+interface Range {
+  start: number;
+  count: number;
+  node: number;
+  depth: number;
+}
+
+/** Axis aligned bounds under construction, in doubles so the sweep does not accumulate rounding. */
+class Bounds {
+  min = [Infinity, Infinity, Infinity];
+  max = [-Infinity, -Infinity, -Infinity];
+
+  reset() {
+    this.min = [Infinity, Infinity, Infinity];
+    this.max = [-Infinity, -Infinity, -Infinity];
+  }
+
+  addPoint(x: number, y: number, z: number) {
+    const point = [x, y, z];
+
+    for (let axis = 0; axis < 3; axis++) {
+      if (point[axis] < this.min[axis]) this.min[axis] = point[axis];
+      if (point[axis] > this.max[axis]) this.max[axis] = point[axis];
+    }
+  }
+
+  addBounds(other: Bounds) {
+    for (let axis = 0; axis < 3; axis++) {
+      if (other.min[axis] < this.min[axis]) this.min[axis] = other.min[axis];
+      if (other.max[axis] > this.max[axis]) this.max[axis] = other.max[axis];
+    }
+  }
+
+  /** Surface area, the cost the split heuristic weighs each side by. Empty bounds cost nothing. */
+  area(): number {
+    const x = this.max[0] - this.min[0], y = this.max[1] - this.min[1], z = this.max[2] - this.min[2];
+
+    return x < 0 || y < 0 || z < 0 ? 0 : 2 * (x * y + y * z + z * x);
+  }
+}
+
+/** Per-triangle bounds and centroids, the only inputs the split needs. */
+function triangleBounds(positions: Float32Array, triangleCount: number) {
+  const min = new Float32Array(triangleCount * 3);
+  const max = new Float32Array(triangleCount * 3);
+  const centroid = new Float64Array(triangleCount * 3);
+
+  for (let triangle = 0; triangle < triangleCount; triangle++) {
+    for (let axis = 0; axis < 3; axis++) {
+      const a = positions[triangle * 9 + axis];
+      const b = positions[triangle * 9 + 3 + axis];
+      const c = positions[triangle * 9 + 6 + axis];
+
+      min[triangle * 3 + axis] = Math.min(a, b, c);
+      max[triangle * 3 + axis] = Math.max(a, b, c);
+      centroid[triangle * 3 + axis] = (a + b + c) / 3;
+    }
+  }
+
+  return { min, max, centroid };
+}
+
+export function buildBvh(positions: Float32Array, triangleCount: number): PackedBvh {
+  const order = new Uint32Array(triangleCount);
+
+  for (let i = 0; i < triangleCount; i++) order[i] = i;
+
+  if (triangleCount === 0)
+    return { nodes: new ArrayBuffer(0), nodeCount: 0, order, maxDepth: 0 };
+
+  const { min, max, centroid } = triangleBounds(positions, triangleCount);
+  // The heuristic may split down to one triangle per leaf, so the pool starts at the common case and grows.
+  let nodes = new ArrayBuffer(Math.max(4, Math.ceil(triangleCount / 2)) * NODE_WORDS * 4);
+  let floats = new Float32Array(nodes);
+  let ints = new Int32Array(nodes);
+
+  const reserve = (needed: number) => {
+    if (needed * NODE_WORDS * 4 <= nodes.byteLength) return;
+
+    const grown = new ArrayBuffer(Math.max(needed, Math.ceil(nodes.byteLength / (NODE_WORDS * 4) * 1.6))
+      * NODE_WORDS * 4);
+
+    new Float32Array(grown).set(floats);
+    nodes = grown;
+    floats = new Float32Array(nodes);
+    ints = new Int32Array(nodes);
+  };
+
+  const stack: Range[] = [{ start: 0, count: triangleCount, node: 0, depth: 0 }];
+  const bounds = new Bounds();
+  let nodeCount = 1;
+  let maxDepth = 0;
+
+  while (stack.length) {
+    const range = stack.pop() as Range;
+
+    maxDepth = Math.max(maxDepth, range.depth);
+    bounds.reset();
+
+    for (let i = range.start; i < range.start + range.count; i++) {
+      const triangle = order[i] * 3;
+
+      bounds.addPoint(min[triangle], min[triangle + 1], min[triangle + 2]);
+      bounds.addPoint(max[triangle], max[triangle + 1], max[triangle + 2]);
+    }
+
+    const word = range.node * NODE_WORDS;
+
+    floats[word] = bounds.min[0];
+    floats[word + 1] = bounds.min[1];
+    floats[word + 2] = bounds.min[2];
+    floats[word + 4] = bounds.max[0];
+    floats[word + 5] = bounds.max[1];
+    floats[word + 6] = bounds.max[2];
+
+    const split = range.count > MAX_LEAF_SIZE && range.depth + 1 < MAX_BVH_DEPTH
+      ? partition(order, centroid, min, max, range, bounds.area())
+      : -1;
+
+    if (split < 0) {
+      // A leaf points into `order` instead of into the node array, which the sign of the first link tells apart.
+      ints[word + 3] = -1 - range.start;
+      ints[word + 7] = range.count;
+      continue;
+    }
+
+    reserve(nodeCount + 2);
+
+    const left = nodeCount++;
+    const right = nodeCount++;
+
+    ints[word + 3] = left;
+    ints[word + 7] = right;
+    stack.push({ start: range.start, count: split - range.start, node: left, depth: range.depth + 1 });
+    stack.push({ start: split, count: range.start + range.count - split, node: right, depth: range.depth + 1 });
+  }
+
+  return { nodes: nodes.slice(0, nodeCount * NODE_WORDS * 4), nodeCount, order, maxDepth };
+}
+
+/**
+ * Reorders `order` in place so the range splits in two, and returns where the right side starts, or -1 when no split
+ * beats keeping the range as a leaf. Bins the centroids on all three axes and sweeps the surface area heuristic.
+ */
+function partition(order: Uint32Array, centroid: Float64Array, min: Float32Array, max: Float32Array,
+  range: Range, parentArea: number): number {
+  if (parentArea <= 0) return -1;
+
+  const end = range.start + range.count;
+  const centroidBounds = new Bounds();
+
+  for (let i = range.start; i < end; i++) {
+    const triangle = order[i] * 3;
+
+    centroidBounds.addPoint(centroid[triangle], centroid[triangle + 1], centroid[triangle + 2]);
+  }
+
+  // Splitting costs a traversal step, so a split only wins when it beats shading the whole range as one leaf.
+  let bestCost = range.count, bestAxis = -1, bestBin = -1, bestScale = 0;
+
+  for (let axis = 0; axis < 3; axis++) {
+    const extent = centroidBounds.max[axis] - centroidBounds.min[axis];
+
+    // Every centroid sits at the same place on this axis: no split here separates anything.
+    if (extent <= 0) continue;
+
+    const scale = BIN_COUNT / extent;
+    const binBounds = Array.from({ length: BIN_COUNT }, () => new Bounds());
+    const binCounts = new Int32Array(BIN_COUNT);
+
+    for (let i = range.start; i < end; i++) {
+      const triangle = order[i] * 3;
+      const bin = binOf(centroid[triangle + axis], centroidBounds.min[axis], scale);
+
+      binCounts[bin]++;
+      binBounds[bin].addPoint(min[triangle], min[triangle + 1], min[triangle + 2]);
+      binBounds[bin].addPoint(max[triangle], max[triangle + 1], max[triangle + 2]);
+    }
+
+    // Sweeping once from each side turns the heuristic into two passes instead of one per candidate split.
+    const rightArea = new Float64Array(BIN_COUNT);
+    const rightCount = new Int32Array(BIN_COUNT);
+    const accumulated = new Bounds();
+    let running = 0;
+
+    for (let bin = BIN_COUNT - 1; bin > 0; bin--) {
+      accumulated.addBounds(binBounds[bin]);
+      running += binCounts[bin];
+      rightArea[bin] = accumulated.area();
+      rightCount[bin] = running;
+    }
+
+    accumulated.reset();
+    running = 0;
+
+    for (let bin = 0; bin < BIN_COUNT - 1; bin++) {
+      accumulated.addBounds(binBounds[bin]);
+      running += binCounts[bin];
+
+      if (!running || !rightCount[bin + 1]) continue;
+
+      const cost = TRAVERSAL_COST
+        + (accumulated.area() * running + rightArea[bin + 1] * rightCount[bin + 1]) / parentArea;
+
+      if (cost < bestCost) {
+        bestCost = cost;
+        bestAxis = axis;
+        bestBin = bin;
+        bestScale = scale;
+      }
+    }
+  }
+
+  if (bestAxis < 0) return -1;
+
+  const pivot = centroidBounds.min[bestAxis];
+  let left = range.start;
+
+  for (let i = range.start; i < end; i++) {
+    if (binOf(centroid[order[i] * 3 + bestAxis], pivot, bestScale) <= bestBin) {
+      const swap = order[i];
+
+      order[i] = order[left];
+      order[left] = swap;
+      left++;
+    }
+  }
+
+  // The sweep only proposes splits both sides occupy, so this is a guard against rounding, not an expected outcome.
+  return left === range.start || left === end ? -1 : left;
+}
+
+function binOf(value: number, origin: number, scale: number): number {
+  return Math.min(BIN_COUNT - 1, Math.max(0, Math.floor((value - origin) * scale)));
+}

package/src/camera.ts

@@ -0,0 +1,77 @@
+import { Matrix4, OrthographicCamera, PerspectiveCamera } from "three";
+import type { CameraState } from "./upstream.js";
+
+/**
+ * Everything the renderer derives from a camera snapshot. Rays are cast through the inverse of the camera's own
+ * projection, so zoom, film offsets, `setViewOffset` and any custom projection come out exactly as Three draws them,
+ * and so do the near and far planes, which clip a camera ray the way they clip a rasterized fragment.
+ */
+export interface CameraMatrices {
+  /** Column-major, as Three stores them. */
+  cameraWorld: number[];
+  view: number[];
+  projection: number[];
+  inverseProjection: number[];
+  orthographic: boolean;
+  near: number;
+  far: number;
+  /** Vertical field of view in degrees, for the lens; 50 when the snapshot has none. */
+  fov: number;
+  position: number[];
+}
+
+/** The camera's projection: the snapshot's own when it has one, otherwise rebuilt from its parameters. */
+export function cameraProjection(camera: CameraState, aspect: number): Matrix4 {
+  if (camera.projectionMatrix) return new Matrix4().fromArray(camera.projectionMatrix);
+
+  const projection = camera.type === "orthographic"
+    ? new OrthographicCamera(camera.left, camera.right, camera.top, camera.bottom, camera.near, camera.far)
+    : new PerspectiveCamera(camera.fov ?? 50, camera.aspect ?? aspect, camera.near, camera.far);
+
+  projection.zoom = camera.zoom ?? 1;
+  projection.updateProjectionMatrix();
+
+  return projection.projectionMatrix;
+}
+
+export function cameraMatrices(camera: CameraState, width: number, height: number): CameraMatrices {
+  const world = new Matrix4().fromArray(camera.matrixWorld);
+  const projection = cameraProjection(camera, width / height);
+  const orthographic = camera.type === "orthographic" || (projection.elements[11] === 0 && projection.elements[15] === 1);
+
+  return {
+    cameraWorld: world.toArray(),
+    view: world.clone().invert().toArray(),
+    projection: projection.toArray(),
+    inverseProjection: projection.clone().invert().toArray(),
+    orthographic,
+    near: camera.near,
+    far: camera.far,
+    fov: camera.fov ?? 50,
+    position: [camera.matrixWorld[12], camera.matrixWorld[13], camera.matrixWorld[14]],
+  };
+}
+
+/** A column-major 4x4 matrix times a point, with the w it produced. */
+export function transform4(matrix: ArrayLike<number>, x: number, y: number, z: number, w = 1): number[] {
+  return [
+    matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12] * w,
+    matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13] * w,
+    matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14] * w,
+    matrix[3] * x + matrix[7] * y + matrix[11] * z + matrix[15] * w,
+  ];
+}
+
+/** A point in clip space back to world space, through the camera that produced it. */
+export function clipToWorld(camera: CameraMatrices, clip: readonly number[]): number[] {
+  const view = transform4(camera.inverseProjection, clip[0], clip[1], clip[2], clip[3]);
+  const w = view[3] || 1e-30;
+
+  return transform4(camera.cameraWorld, view[0] / w, view[1] / w, view[2] / w).slice(0, 3);
+}
+
+export function worldToClip(camera: CameraMatrices, point: readonly number[]): number[] {
+  const view = transform4(camera.view, point[0], point[1], point[2]);
+
+  return transform4(camera.projection, view[0], view[1], view[2], view[3]);
+}

package/src/canvas.ts

@@ -0,0 +1,13 @@
+import type { GpuRenderer } from "./renderer.js";
+
+/**
+ * Sends the renderer's output to a canvas. It configures the WebGPU context, sizes the canvas to the render
+ * resolution and presents after every submit, so the image refines in place while it converges.
+ *
+ * Returns the function that detaches it.
+ */
+export function attachCanvas(renderer: GpuRenderer, canvas: HTMLCanvasElement): () => void {
+  renderer.setOutputCanvas(canvas);
+
+  return () => renderer.setOutputCanvas(null);
+}