@tinypoly/gpu-renderer 0.0.0-stage → 0.0.1

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,80 @@
 {
   "name": "@tinypoly/gpu-renderer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "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"
+    },
+    "./bvhWorker.js": "./dist/bvhWorker.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,336 @@
+/**
+ * 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;
+}
+
+/** 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);
+  };
+
+  // The pending ranges, four integers each: start, count, node and depth. Typed, so the loop allocates nothing.
+  let stack = new Int32Array(4 * 2 * MAX_BVH_DEPTH + 8);
+  let top = 1;
+  const bins = new Bins();
+  let nodeCount = 1;
+  let maxDepth = 0;
+
+  stack[0] = 0;
+  stack[1] = triangleCount;
+  stack[2] = 0;
+  stack[3] = 0;
+
+  while (top) {
+    top--;
+
+    const start = stack[top * 4], count = stack[top * 4 + 1], node = stack[top * 4 + 2], depth = stack[top * 4 + 3];
+    const end = start + count;
+
+    if (depth > maxDepth) maxDepth = depth;
+
+    // The node's bounds and its centroids' bounds, in one pass. Doubles, so the corners are exactly the floats read.
+    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    let cMinX = Infinity, cMinY = Infinity, cMinZ = Infinity, cMaxX = -Infinity, cMaxY = -Infinity, cMaxZ = -Infinity;
+
+    for (let i = start; i < end; i++) {
+      const triangle = order[i] * 3;
+      let value = min[triangle];
+
+      if (value < minX) minX = value;
+      value = min[triangle + 1];
+      if (value < minY) minY = value;
+      value = min[triangle + 2];
+      if (value < minZ) minZ = value;
+      value = max[triangle];
+      if (value > maxX) maxX = value;
+      value = max[triangle + 1];
+      if (value > maxY) maxY = value;
+      value = max[triangle + 2];
+      if (value > maxZ) maxZ = value;
+      value = centroid[triangle];
+      if (value < cMinX) cMinX = value;
+      if (value > cMaxX) cMaxX = value;
+      value = centroid[triangle + 1];
+      if (value < cMinY) cMinY = value;
+      if (value > cMaxY) cMaxY = value;
+      value = centroid[triangle + 2];
+      if (value < cMinZ) cMinZ = value;
+      if (value > cMaxZ) cMaxZ = value;
+    }
+
+    const word = node * NODE_WORDS;
+
+    floats[word] = minX;
+    floats[word + 1] = minY;
+    floats[word + 2] = minZ;
+    floats[word + 4] = maxX;
+    floats[word + 5] = maxY;
+    floats[word + 6] = maxZ;
+
+    let split = -1;
+
+    if (count > MAX_LEAF_SIZE && depth + 1 < MAX_BVH_DEPTH) {
+      bins.centroidMin[0] = cMinX;
+      bins.centroidMin[1] = cMinY;
+      bins.centroidMin[2] = cMinZ;
+      bins.centroidMax[0] = cMaxX;
+      bins.centroidMax[1] = cMaxY;
+      bins.centroidMax[2] = cMaxZ;
+      split = partition(order, centroid, min, max, start, end, area(minX, minY, minZ, maxX, maxY, maxZ), bins);
+    }
+
+    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 - start;
+      ints[word + 7] = count;
+      continue;
+    }
+
+    reserve(nodeCount + 2);
+
+    const left = nodeCount++;
+    const right = nodeCount++;
+
+    ints[word + 3] = left;
+    ints[word + 7] = right;
+
+    if ((top + 2) * 4 > stack.length) {
+      const grown = new Int32Array(stack.length * 2);
+
+      grown.set(stack);
+      stack = grown;
+    }
+
+    // Left first, then right, so the right side is built first, as the order the tree was always built in.
+    stack.set([start, split - start, left, depth + 1, split, end - split, right, depth + 1], top * 4);
+    top += 2;
+  }
+
+  return { nodes: nodes.slice(0, nodeCount * NODE_WORDS * 4), nodeCount, order, maxDepth };
+}
+
+/** Surface area, the cost the split heuristic weighs each side by. Empty bounds cost nothing. */
+function area(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number {
+  const x = maxX - minX, y = maxY - minY, z = maxZ - minZ;
+
+  return x < 0 || y < 0 || z < 0 ? 0 : 2 * (x * y + y * z + z * x);
+}
+
+/** Scratch space for one split, kept across every node so binning allocates nothing. */
+class Bins {
+  readonly centroidMin = new Float64Array(3);
+  readonly centroidMax = new Float64Array(3);
+  /** Six doubles per bin and axis: the minimum corner, then the maximum. */
+  readonly bounds = new Float64Array(3 * BIN_COUNT * 6);
+  readonly counts = new Int32Array(3 * BIN_COUNT);
+  readonly rightArea = new Float64Array(BIN_COUNT);
+  readonly rightCount = new Int32Array(BIN_COUNT);
+  readonly scale = new Float64Array(3);
+
+  reset() {
+    const bounds = this.bounds;
+
+    for (let i = 0; i < bounds.length; i += 6) {
+      bounds[i] = bounds[i + 1] = bounds[i + 2] = Infinity;
+      bounds[i + 3] = bounds[i + 4] = bounds[i + 5] = -Infinity;
+    }
+
+    this.counts.fill(0);
+  }
+}
+
+/**
+ * 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 in one pass and sweeps the surface area
+ * heuristic on each.
+ */
+function partition(order: Uint32Array, centroid: Float64Array, min: Float32Array, max: Float32Array,
+  start: number, end: number, parentArea: number, bins: Bins): number {
+  if (parentArea <= 0) return -1;
+
+  const { centroidMin, centroidMax, bounds, counts, rightArea, rightCount, scale } = bins;
+  let binned = false;
+
+  for (let axis = 0; axis < 3; axis++) {
+    const extent = centroidMax[axis] - centroidMin[axis];
+
+    // Every centroid sits at the same place on this axis: no split here separates anything.
+    scale[axis] = extent > 0 ? BIN_COUNT / extent : 0;
+    binned ||= extent > 0;
+  }
+
+  if (!binned) return -1;
+
+  bins.reset();
+
+  for (let i = start; i < end; i++) {
+    const triangle = order[i] * 3;
+    const x0 = min[triangle], y0 = min[triangle + 1], z0 = min[triangle + 2];
+    const x1 = max[triangle], y1 = max[triangle + 1], z1 = max[triangle + 2];
+
+    for (let axis = 0; axis < 3; axis++) {
+      if (scale[axis] === 0) continue;
+
+      const bin = axis * BIN_COUNT + binOf(centroid[triangle + axis], centroidMin[axis], scale[axis]);
+      const at = bin * 6;
+
+      counts[bin]++;
+
+      if (x0 < bounds[at]) bounds[at] = x0;
+      if (y0 < bounds[at + 1]) bounds[at + 1] = y0;
+      if (z0 < bounds[at + 2]) bounds[at + 2] = z0;
+      if (x1 > bounds[at + 3]) bounds[at + 3] = x1;
+      if (y1 > bounds[at + 4]) bounds[at + 4] = y1;
+      if (z1 > bounds[at + 5]) bounds[at + 5] = z1;
+    }
+  }
+
+  // Splitting costs a traversal step, so a split only wins when it beats shading the whole range as one leaf.
+  let bestCost = end - start, bestAxis = -1, bestBin = -1;
+
+  for (let axis = 0; axis < 3; axis++) {
+    if (scale[axis] === 0) continue;
+
+    // Sweeping once from each side turns the heuristic into two passes instead of one per candidate split.
+    let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    let running = 0;
+
+    for (let bin = BIN_COUNT - 1; bin > 0; bin--) {
+      const at = (axis * BIN_COUNT + bin) * 6;
+
+      if (bounds[at] < minX) minX = bounds[at];
+      if (bounds[at + 1] < minY) minY = bounds[at + 1];
+      if (bounds[at + 2] < minZ) minZ = bounds[at + 2];
+      if (bounds[at + 3] > maxX) maxX = bounds[at + 3];
+      if (bounds[at + 4] > maxY) maxY = bounds[at + 4];
+      if (bounds[at + 5] > maxZ) maxZ = bounds[at + 5];
+      running += counts[axis * BIN_COUNT + bin];
+      rightArea[bin] = area(minX, minY, minZ, maxX, maxY, maxZ);
+      rightCount[bin] = running;
+    }
+
+    minX = minY = minZ = Infinity;
+    maxX = maxY = maxZ = -Infinity;
+    running = 0;
+
+    for (let bin = 0; bin < BIN_COUNT - 1; bin++) {
+      const at = (axis * BIN_COUNT + bin) * 6;
+
+      if (bounds[at] < minX) minX = bounds[at];
+      if (bounds[at + 1] < minY) minY = bounds[at + 1];
+      if (bounds[at + 2] < minZ) minZ = bounds[at + 2];
+      if (bounds[at + 3] > maxX) maxX = bounds[at + 3];
+      if (bounds[at + 4] > maxY) maxY = bounds[at + 4];
+      if (bounds[at + 5] > maxZ) maxZ = bounds[at + 5];
+      running += counts[axis * BIN_COUNT + bin];
+
+      if (!running || !rightCount[bin + 1]) continue;
+
+      const cost = TRAVERSAL_COST
+        + (area(minX, minY, minZ, maxX, maxY, maxZ) * running + rightArea[bin + 1] * rightCount[bin + 1]) / parentArea;
+
+      if (cost < bestCost) {
+        bestCost = cost;
+        bestAxis = axis;
+        bestBin = bin;
+      }
+    }
+  }
+
+  if (bestAxis < 0) return -1;
+
+  const pivot = centroidMin[bestAxis];
+  const bestScale = scale[bestAxis];
+  let left = start;
+
+  for (let i = 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 === 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)));
+}