@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/passes/optimize-cache.ts

@@ -0,0 +1,175 @@
+// Post-transform vertex cache: Tom Forsyth's "Linear-Speed Vertex Cache Optimisation" (2006)
+// triangle reorder, the vertex-fetch reorder that follows it, and the ACMR/ATVR analysis that
+// measures both. All integer bookkeeping and fixed tie-breaks (lowest triangle index wins), so
+// the output is byte-deterministic.
+
+const CACHE = 32;
+const DECAY = 1.5;
+const LAST_TRI = 0.75;
+const VALENCE_SCALE = 2;
+const VALENCE_POWER = 0.5;
+const MAX_VALENCE = 64;
+
+const CACHE_SCORE = Float64Array.from({ length: CACHE }, (_, i) =>
+  i < 3 ? LAST_TRI : (1 - (i - 3) / (CACHE - 3)) ** DECAY,
+);
+const VALENCE_SCORE = Float64Array.from({ length: MAX_VALENCE + 1 }, (_, n) =>
+  n === 0 ? 0 : VALENCE_SCALE * n ** -VALENCE_POWER,
+);
+
+const vertexScore = (pos: number, live: number): number =>
+  live === 0
+    ? -1
+    : (pos >= 0 ? (CACHE_SCORE[pos] ?? 0) : 0) + (VALENCE_SCORE[Math.min(live, MAX_VALENCE)] ?? 0);
+
+/** Reorder triangles for an LRU cache of 32 (Forsyth). Returns a new index buffer. */
+export function forsyth(indices: Uint32Array, vertexCount: number): Uint32Array {
+  const triCount = indices.length / 3;
+  if (triCount === 0) return new Uint32Array(0);
+  // CSR adjacency: vertex → triangles; `live[v]` counts the not-yet-emitted prefix.
+  const live = new Int32Array(vertexCount);
+  for (const v of indices) live[v] = (live[v] ?? 0) + 1;
+  const offset = new Int32Array(vertexCount + 1);
+  for (let v = 0; v < vertexCount; v++) offset[v + 1] = (offset[v] ?? 0) + (live[v] ?? 0);
+  const adj = new Int32Array(indices.length);
+  const fill = new Int32Array(vertexCount);
+  for (let t = 0; t < triCount; t++)
+    for (let k = 0; k < 3; k++) {
+      const v = indices[t * 3 + k] ?? 0;
+      adj[(offset[v] ?? 0) + (fill[v] ?? 0)] = t;
+      fill[v] = (fill[v] ?? 0) + 1;
+    }
+  const cachePos = new Int32Array(vertexCount).fill(-1);
+  const score = new Float64Array(vertexCount);
+  for (let v = 0; v < vertexCount; v++) score[v] = vertexScore(-1, live[v] ?? 0);
+  const emitted = new Uint8Array(triCount);
+  const triScoreOf = (t: number): number =>
+    (score[indices[t * 3] ?? 0] ?? 0) +
+    (score[indices[t * 3 + 1] ?? 0] ?? 0) +
+    (score[indices[t * 3 + 2] ?? 0] ?? 0);
+  let best = 0;
+  let top = triScoreOf(0);
+  for (let t = 1; t < triCount; t++) {
+    const s = triScoreOf(t);
+    if (s > top) {
+      top = s;
+      best = t;
+    }
+  }
+  const out = new Uint32Array(indices.length);
+  let cache = new Int32Array(CACHE + 3);
+  let spare = new Int32Array(CACHE + 3);
+  let size = 0;
+  let cursor = 0;
+  for (let n = 0; n < triCount; n++) {
+    if (best < 0) {
+      while (emitted[cursor]) cursor++;
+      best = cursor;
+    }
+    const t = best;
+    emitted[t] = 1;
+    const a = indices[t * 3] ?? 0;
+    const b = indices[t * 3 + 1] ?? 0;
+    const c = indices[t * 3 + 2] ?? 0;
+    out[n * 3] = a;
+    out[n * 3 + 1] = b;
+    out[n * 3 + 2] = c;
+    for (const v of [a, b, c]) {
+      // Remove t from v's live adjacency (swap with the last live entry).
+      const o = offset[v] ?? 0;
+      const l = live[v] ?? 0;
+      for (let i = o; i < o + l; i++)
+        if (adj[i] === t) {
+          adj[i] = adj[o + l - 1] ?? 0;
+          adj[o + l - 1] = t;
+          break;
+        }
+      live[v] = l - 1;
+    }
+    // New LRU: the triangle's vertices first, then the old cache minus them.
+    spare[0] = a;
+    spare[1] = b;
+    spare[2] = c;
+    let m = 3;
+    for (let i = 0; i < size; i++) {
+      const v = cache[i] ?? 0;
+      if (v !== a && v !== b && v !== c) spare[m++] = v;
+    }
+    for (let i = CACHE; i < m; i++) {
+      const v = spare[i] ?? 0;
+      cachePos[v] = -1;
+      score[v] = vertexScore(-1, live[v] ?? 0);
+    }
+    [cache, spare] = [spare, cache];
+    size = Math.min(m, CACHE);
+    for (let i = 0; i < size; i++) {
+      const v = cache[i] ?? 0;
+      cachePos[v] = i;
+      score[v] = vertexScore(i, live[v] ?? 0);
+    }
+    best = -1;
+    let bestScore = -Infinity;
+    for (let j = 0; j < size; j++) {
+      const v = cache[j] ?? 0;
+      const o = offset[v] ?? 0;
+      for (let i = o; i < o + (live[v] ?? 0); i++) {
+        const u = adj[i] ?? 0;
+        const s = triScoreOf(u);
+        if (s > bestScore || (s === bestScore && u < best)) {
+          bestScore = s;
+          best = u;
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** Renumber vertices in order of first use; unreferenced vertices are dropped. */
+export function fetchOrder(
+  indices: Uint32Array,
+  vertexCount: number,
+): { indices: Uint32Array; order: Uint32Array } {
+  const map = new Int32Array(vertexCount).fill(-1);
+  const order: number[] = [];
+  const out = new Uint32Array(indices.length);
+  for (let i = 0; i < indices.length; i++) {
+    const v = indices[i] ?? 0;
+    if ((map[v] ?? -1) < 0) {
+      map[v] = order.length;
+      order.push(v);
+    }
+    out[i] = map[v] ?? 0;
+  }
+  return { indices: out, order: Uint32Array.from(order) };
+}
+
+export interface CacheStats {
+  /** Average cache misses per triangle (0.5 ideal on a regular grid, 3 worst). */
+  readonly acmr: number;
+  /** Misses per unique vertex (1.0 ideal). */
+  readonly atvr: number;
+}
+
+/** Simulate a FIFO post-transform cache (16 entries, the meshoptimizer/NVIDIA convention). */
+export function cacheStats(indices: Uint32Array, vertexCount: number, size = 16): CacheStats {
+  const tris = indices.length / 3;
+  if (tris === 0) return { acmr: 0, atvr: 0 };
+  const stamp = new Int32Array(vertexCount).fill(-1_000_000_000);
+  let misses = 0;
+  for (const v of indices) {
+    // A vertex is cached if it was loaded within the last `size` misses.
+    if (misses - (stamp[v] ?? 0) >= size) {
+      stamp[v] = misses;
+      misses++;
+    }
+  }
+  const seen = new Uint8Array(vertexCount);
+  let used = 0;
+  for (const v of indices)
+    if (!seen[v]) {
+      seen[v] = 1;
+      used++;
+    }
+  return { acmr: misses / tris, atvr: used ? misses / used : 0 };
+}

package/src/passes/optimize-weld.ts

@@ -0,0 +1,147 @@
+// Vertex weld + degenerate/duplicate triangle removal: the "index" step of mesh optimisation.
+// Two vertices merge when position, normal, UV and colour all quantise to the same cell, so hard
+// edges (split normals) and UV seams survive. First occurrence wins; output order is the order of
+// first appearance — deterministic, no hashing of floats into iteration order.
+
+import type { Mesh } from '../core/index.ts';
+
+export interface WeldTolerance {
+  /** Position grid, metres. */
+  readonly position: number;
+  readonly normal: number;
+  readonly uv: number;
+  readonly color: number;
+}
+
+export const DEFAULT_WELD: WeldTolerance = {
+  position: 1e-5,
+  normal: 1e-3,
+  uv: 1e-5,
+  // Below the GLB's unorm16 colour step: welding never changes exported colour.
+  color: 1 / 131072,
+};
+
+export interface Welded {
+  readonly mesh: Mesh;
+  readonly degenerate: number;
+  readonly duplicate: number;
+}
+
+/** The quantised attribute tuple of vertex i (12 ints). */
+function cellOf(m: Mesh, i: number, t: WeldTolerance, out: Int32Array): void {
+  for (let k = 0; k < 3; k++) {
+    out[k] = Math.round((m.positions[i * 3 + k] ?? 0) / t.position);
+    out[3 + k] = Math.round((m.normals[i * 3 + k] ?? 0) / t.normal);
+    out[8 + k] = Math.round((m.colors[i * 3 + k] ?? 0) / t.color);
+  }
+  out[6] = Math.round((m.uvs[i * 2] ?? 0) / t.uv);
+  out[7] = Math.round((m.uvs[i * 2 + 1] ?? 0) / t.uv);
+  out[11] = 0;
+}
+
+const hashCell = (c: Int32Array): number => {
+  let h = 2166136261;
+  for (let k = 0; k < 11; k++) h = Math.imul(h ^ (c[k] ?? 0), 16777619);
+  return h >>> 0;
+};
+
+/** Map each input vertex to its welded representative (open-addressing table, linear probe). */
+function weldMap(m: Mesh, t: WeldTolerance): { remap: Uint32Array; keep: number[] } {
+  const n = m.positions.length / 3;
+  const cells = new Int32Array(n * 12);
+  const remap = new Uint32Array(n);
+  const keep: number[] = [];
+  let cap = 16;
+  while (cap < n * 2) cap *= 2;
+  const table = new Int32Array(cap).fill(-1);
+  const cur = new Int32Array(12);
+  for (let i = 0; i < n; i++) {
+    cellOf(m, i, t, cur);
+    cells.set(cur, i * 12);
+    let slot = hashCell(cur) & (cap - 1);
+    let found = -1;
+    for (;;) {
+      const j = table[slot] ?? -1;
+      if (j < 0) break;
+      const rep = (keep[j] ?? 0) * 12;
+      let same = true;
+      for (let k = 0; k < 11 && same; k++) same = cells[rep + k] === cur[k];
+      if (same) {
+        found = j;
+        break;
+      }
+      slot = (slot + 1) & (cap - 1);
+    }
+    if (found < 0) {
+      found = keep.length;
+      keep.push(i);
+      table[slot] = found;
+    }
+    remap[i] = found;
+  }
+  return { remap, keep };
+}
+
+/** Twice the triangle's area, from welded positions. */
+function area2(p: Float32Array, a: number, b: number, c: number): number {
+  const ax = p[a * 3] ?? 0;
+  const ay = p[a * 3 + 1] ?? 0;
+  const az = p[a * 3 + 2] ?? 0;
+  const ux = (p[b * 3] ?? 0) - ax;
+  const uy = (p[b * 3 + 1] ?? 0) - ay;
+  const uz = (p[b * 3 + 2] ?? 0) - az;
+  const vx = (p[c * 3] ?? 0) - ax;
+  const vy = (p[c * 3 + 1] ?? 0) - ay;
+  const vz = (p[c * 3 + 2] ?? 0) - az;
+  return Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx);
+}
+
+export function weld(m: Mesh, t: WeldTolerance = DEFAULT_WELD): Welded {
+  const { remap, keep } = weldMap(m, t);
+  const pick = (src: Float32Array, w: number): Float32Array => {
+    const out = new Float32Array(keep.length * w);
+    keep.forEach((i, j) => {
+      for (let k = 0; k < w; k++) out[j * w + k] = src[i * w + k] ?? 0;
+    });
+    return out;
+  };
+  const positions = pick(m.positions, 3);
+  const idx: number[] = [];
+  // Duplicate detection: canonical rotation (lowest index first) hashed to a numeric key.
+  const seen = new Map<number, number[]>();
+  let degenerate = 0;
+  let duplicate = 0;
+  for (let f = 0; f < m.indices.length; f += 3) {
+    const a = remap[m.indices[f] ?? 0] ?? 0;
+    const b = remap[m.indices[f + 1] ?? 0] ?? 0;
+    const c = remap[m.indices[f + 2] ?? 0] ?? 0;
+    // Zero area covers no pixel: dropping it cannot open a crack.
+    if (a === b || b === c || a === c || area2(positions, a, b, c) < 1e-12) {
+      degenerate++;
+      continue;
+    }
+    // Same triangle, same winding (any rotation) is pure overdraw; the reverse winding is a
+    // deliberate double-sided face and stays.
+    const [x, y, z] = a < b && a < c ? [a, b, c] : b < c ? [b, c, a] : [c, a, b];
+    const h = (Math.imul(x, 73856093) ^ Math.imul(y, 19349663) ^ Math.imul(z, 83492791)) >>> 0;
+    const list = seen.get(h);
+    if (list?.some((at) => idx[at] === x && idx[at + 1] === y && idx[at + 2] === z)) {
+      duplicate++;
+      continue;
+    }
+    if (list) list.push(idx.length);
+    else seen.set(h, [idx.length]);
+    idx.push(x, y, z);
+  }
+  return {
+    mesh: {
+      positions,
+      normals: pick(m.normals, 3),
+      uvs: pick(m.uvs, 2),
+      colors: pick(m.colors, 3),
+      indices: new Uint32Array(idx),
+    },
+    degenerate,
+    duplicate,
+  };
+}

package/src/passes/optimize.ts

@@ -0,0 +1,85 @@
+// Game-ready optimisation, run on every LOD before export, in meshoptimizer's order: weld
+// duplicate vertices (index) → reorder triangles for the post-transform vertex cache (Forsyth)
+// → reorder vertices for fetch locality. Same geometry, fewer vertices, fewer cache misses.
+// Zero dependencies, byte-deterministic. Reports ACMR/ATVR before and after.
+
+import type { Mesh } from '../core/index.ts';
+import { cacheStats, fetchOrder, forsyth } from './optimize-cache.ts';
+import { DEFAULT_WELD, type WeldTolerance, weld } from './optimize-weld.ts';
+
+export interface OptimizeOptions {
+  /** Merge vertices closer than this (metres) with matching normal/uv/colour. Default 1e-5. */
+  readonly weldEpsilon?: number;
+  /** Reorder for the vertex cache (Forsyth). Default true. */
+  readonly vertexCache?: boolean;
+}
+
+export interface OptimizeReport {
+  readonly verticesBefore: number;
+  readonly verticesAfter: number;
+  readonly trianglesBefore: number;
+  readonly trianglesAfter: number;
+  /** Zero-area / collapsed triangles dropped. */
+  readonly degenerate: number;
+  /** Exact duplicate triangles (same winding) dropped. */
+  readonly duplicate: number;
+  /** Average cache miss ratio per triangle before (FIFO 16). */
+  readonly acmrBefore: number;
+  /** Average cache miss ratio per triangle after reordering (lower is better, ~0.6–0.8 is good). */
+  readonly acmr: number;
+  /** Cache misses per vertex before / after (1.0 is ideal). */
+  readonly atvrBefore: number;
+  readonly atvr: number;
+}
+
+function reorderVertices(m: Mesh, order: Uint32Array, indices: Uint32Array): Mesh {
+  const pick = (src: Float32Array, w: number): Float32Array => {
+    const out = new Float32Array(order.length * w);
+    for (let j = 0; j < order.length; j++)
+      for (let k = 0; k < w; k++) out[j * w + k] = src[(order[j] ?? 0) * w + k] ?? 0;
+    return out;
+  };
+  return {
+    positions: pick(m.positions, 3),
+    normals: pick(m.normals, 3),
+    uvs: pick(m.uvs, 2),
+    colors: pick(m.colors, 3),
+    indices,
+  };
+}
+
+export function optimize(
+  mesh: Mesh,
+  o: OptimizeOptions = {},
+): { mesh: Mesh; report: OptimizeReport } {
+  const vBefore = mesh.positions.length / 3;
+  const before = cacheStats(mesh.indices, vBefore);
+  const tol: WeldTolerance = { ...DEFAULT_WELD, position: o.weldEpsilon ?? DEFAULT_WELD.position };
+  const w = weld(mesh, tol);
+  const vWelded = w.mesh.positions.length / 3;
+  // Forsyth targets an LRU-32 cache; on already-good input (flat strips) it can lose a hair on
+  // the FIFO-16 measure. Keep whichever order measures better — never make a mesh worse.
+  const reordered = o.vertexCache === false ? null : forsyth(w.mesh.indices, vWelded);
+  const tris =
+    reordered && cacheStats(reordered, vWelded).acmr <= cacheStats(w.mesh.indices, vWelded).acmr
+      ? reordered
+      : w.mesh.indices;
+  const fetched = fetchOrder(tris, vWelded);
+  const out = reorderVertices(w.mesh, fetched.order, fetched.indices);
+  const after = cacheStats(out.indices, out.positions.length / 3);
+  return {
+    mesh: out,
+    report: {
+      verticesBefore: vBefore,
+      verticesAfter: out.positions.length / 3,
+      trianglesBefore: mesh.indices.length / 3,
+      trianglesAfter: out.indices.length / 3,
+      degenerate: w.degenerate,
+      duplicate: w.duplicate,
+      acmrBefore: before.acmr,
+      acmr: after.acmr,
+      atvrBefore: before.atvr,
+      atvr: after.atvr,
+    },
+  };
+}

package/src/passes/ray-grid.ts

@@ -0,0 +1,237 @@
+// Ray casting for bakes: triangles bucketed in a uniform 3D grid (CSR, typed arrays), walked
+// with Amanatides–Woo DDA, tested with Möller–Trumbore. Answers "does this ray hit anything
+// within `tMax`?" — all an occlusion bake needs. Allocation-free per ray, deterministic.
+
+import { boundsOf, type Mesh, type Vec3 } from '../core/index.ts';
+
+const CELL_SCALE = 0.3;
+
+export class RayGrid {
+  private readonly tri: Float64Array;
+  /** Per triangle: v0, e1 = v1 − v0, e2 = v2 − v0 (Möller–Trumbore inputs, computed once). */
+  private readonly edges: Float64Array;
+  /** Per triangle: unnormalised plane normal e1 × e2 and its offset n·v0. */
+  private readonly planes: Float64Array;
+  private readonly start: Int32Array;
+  private readonly list: Int32Array;
+  private readonly min: Vec3;
+  private readonly res: [number, number, number];
+  private readonly cell: number;
+  private readonly stamp: Int32Array;
+  private ray = 0;
+
+  constructor(mesh: Mesh) {
+    const n = mesh.indices.length / 3;
+    this.tri = new Float64Array(n * 9);
+    for (let t = 0; t < n; t++)
+      for (let v = 0; v < 3; v++) {
+        const i = (mesh.indices[t * 3 + v] ?? 0) * 3;
+        for (let k = 0; k < 3; k++) this.tri[t * 9 + v * 3 + k] = mesh.positions[i + k] ?? 0;
+      }
+    this.edges = new Float64Array(n * 9);
+    for (let t = 0; t < n; t++) {
+      const o = t * 9;
+      for (let k = 0; k < 3; k++) {
+        const v0 = this.tri[o + k] ?? 0;
+        this.edges[o + k] = v0;
+        this.edges[o + 3 + k] = (this.tri[o + 3 + k] ?? 0) - v0;
+        this.edges[o + 6 + k] = (this.tri[o + 6 + k] ?? 0) - v0;
+      }
+    }
+    this.planes = new Float64Array(n * 4);
+    for (let t = 0; t < n; t++) {
+      const E = this.edges;
+      const o = t * 9;
+      const [ax, ay, az] = [E[o + 3] ?? 0, E[o + 4] ?? 0, E[o + 5] ?? 0];
+      const [bx, by, bz] = [E[o + 6] ?? 0, E[o + 7] ?? 0, E[o + 8] ?? 0];
+      const nx = ay * bz - az * by;
+      const ny = az * bx - ax * bz;
+      const nz = ax * by - ay * bx;
+      this.planes.set(
+        [nx, ny, nz, nx * (E[o] ?? 0) + ny * (E[o + 1] ?? 0) + nz * (E[o + 2] ?? 0)],
+        t * 4,
+      );
+    }
+    const b = boundsOf(mesh);
+    const span = [0, 1, 2].map((k) => Math.max(1e-6, (b.max[k] ?? 0) - (b.min[k] ?? 0)));
+    // Cells ~0.3× the "two triangles per cell if they filled the volume" size: triangles live
+    // on surfaces, so that size leaves a dozen per occupied cell. Measured on tiger_1 and a
+    // sculpted head (0.2–0.5 is flat; larger cells cost 2–4×). Bounded to 256 per axis and
+    // ~4M cells overall. Any cell size gives the same answers; only the speed changes.
+    const vol = (span[0] ?? 1) * (span[1] ?? 1) * (span[2] ?? 1);
+    this.cell = Math.max(
+      CELL_SCALE * Math.cbrt(vol / Math.max(1, n / 2)),
+      Math.max(...span) / 256,
+      Math.cbrt(vol / 4e6),
+      1e-4,
+    );
+    this.min = [b.min[0] - 1e-6, b.min[1] - 1e-6, b.min[2] - 1e-6];
+    this.res = [0, 1, 2].map((k) => Math.max(1, Math.ceil((span[k] ?? 0) / this.cell) + 1)) as [
+      number,
+      number,
+      number,
+    ];
+    const [rx, ry] = this.res;
+    const cells = rx * ry * this.res[2];
+    // Each triangle's cell box once, then a counting pass and a fill pass (CSR, t ascending).
+    const box = new Int32Array(n * 6);
+    const T = this.tri;
+    for (let t = 0; t < n; t++)
+      for (let k = 0; k < 3; k++) {
+        const a = T[t * 9 + k] ?? 0;
+        const b2 = T[t * 9 + 3 + k] ?? 0;
+        const c = T[t * 9 + 6 + k] ?? 0;
+        box[t * 6 + k] = this.coord(Math.min(a, b2, c), k);
+        box[t * 6 + 3 + k] = this.coord(Math.max(a, b2, c), k);
+      }
+    const count = new Int32Array(cells + 1);
+    const visit = (t: number, f: (c: number) => void): void => {
+      const o = t * 6;
+      for (let x = box[o] ?? 0; x <= (box[o + 3] ?? 0); x++)
+        for (let y = box[o + 1] ?? 0; y <= (box[o + 4] ?? 0); y++)
+          for (let z = box[o + 2] ?? 0; z <= (box[o + 5] ?? 0); z++) f((z * ry + y) * rx + x);
+    };
+    const bump = (c: number): void => {
+      count[c + 1] = (count[c + 1] ?? 0) + 1;
+    };
+    for (let t = 0; t < n; t++) visit(t, bump);
+    for (let c = 0; c < cells; c++) count[c + 1] = (count[c + 1] ?? 0) + (count[c] ?? 0);
+    this.start = count;
+    const list = new Int32Array(count[cells] ?? 0);
+    const fill = new Int32Array(cells);
+    for (let t = 0; t < n; t++)
+      visit(t, (c) => {
+        list[(count[c] ?? 0) + (fill[c] ?? 0)] = t;
+        fill[c] = (fill[c] ?? 0) + 1;
+      });
+    this.list = list;
+    this.stamp = new Int32Array(n);
+  }
+
+  private coord(v: number, k: number): number {
+    const r = this.res[k as 0 | 1 | 2];
+    return Math.min(
+      r - 1,
+      Math.max(0, Math.floor((v - (this.min[k as 0 | 1 | 2] ?? 0)) / this.cell)),
+    );
+  }
+
+  /** Any hit of the ray o + t·d (d unit) for 0 < t ≤ tMax. Scalar arguments: no allocation. */
+  hit(
+    ox: number,
+    oy: number,
+    oz: number,
+    dx: number,
+    dy: number,
+    dz: number,
+    tMax: number,
+  ): boolean {
+    const q = ++this.ray;
+    const start = this.start;
+    const list = this.list;
+    const stamp = this.stamp;
+    const size = this.cell;
+    const [rx, ry, rz] = this.res;
+    const [mx, my, mz] = this.min;
+    let cx = this.coord(ox, 0);
+    let cy = this.coord(oy, 1);
+    let cz = this.coord(oz, 2);
+    const sx = dx > 0 ? 1 : -1;
+    const sy = dy > 0 ? 1 : -1;
+    const sz = dz > 0 ? 1 : -1;
+    let nx = Math.abs(dx) < 1e-12 ? Infinity : (mx + (cx + (dx > 0 ? 1 : 0)) * size - ox) / dx;
+    let ny = Math.abs(dy) < 1e-12 ? Infinity : (my + (cy + (dy > 0 ? 1 : 0)) * size - oy) / dy;
+    let nz = Math.abs(dz) < 1e-12 ? Infinity : (mz + (cz + (dz > 0 ? 1 : 0)) * size - oz) / dz;
+    const ddx = Math.abs(dx) < 1e-12 ? Infinity : size / Math.abs(dx);
+    const ddy = Math.abs(dy) < 1e-12 ? Infinity : size / Math.abs(dy);
+    const ddz = Math.abs(dz) < 1e-12 ? Infinity : size / Math.abs(dz);
+    let t = 0;
+    while (t <= tMax) {
+      const c = (cz * ry + cy) * rx + cx;
+      const end = start[c + 1] ?? 0;
+      for (let i = start[c] ?? 0; i < end; i++) {
+        const tri = list[i] ?? 0;
+        if (stamp[tri] === q) continue;
+        stamp[tri] = q;
+        if (this.test(tri, ox, oy, oz, dx, dy, dz, tMax)) return true;
+      }
+      if (nx < ny) {
+        if (nx < nz) {
+          t = nx;
+          cx += sx;
+          if (cx < 0 || cx >= rx) return false;
+          nx = t + ddx;
+        } else {
+          t = nz;
+          cz += sz;
+          if (cz < 0 || cz >= rz) return false;
+          nz = t + ddz;
+        }
+      } else if (ny < nz) {
+        t = ny;
+        cy += sy;
+        if (cy < 0 || cy >= ry) return false;
+        ny = t + ddy;
+      } else {
+        t = nz;
+        cz += sz;
+        if (cz < 0 || cz >= rz) return false;
+        nz = t + ddz;
+      }
+    }
+    return false;
+  }
+
+  /** Möller–Trumbore on cached v0, e1, e2 (the same arithmetic as deriving them per ray). */
+  private test(
+    tri: number,
+    ox: number,
+    oy: number,
+    oz: number,
+    dx: number,
+    dy: number,
+    dz: number,
+    tMax: number,
+  ): boolean {
+    // Plane pre-reject: the hit distance along the ray, from two dot products. Only clear misses
+    // (behind the origin, or past tMax, with margin) are skipped; Möller–Trumbore decides the rest.
+    const P = this.planes;
+    const f = tri * 4;
+    const nx = P[f] ?? 0;
+    const ny = P[f + 1] ?? 0;
+    const nz = P[f + 2] ?? 0;
+    const th0 = ((P[f + 3] ?? 0) - (nx * ox + ny * oy + nz * oz)) / (nx * dx + ny * dy + nz * dz);
+    if (!(th0 > -1e-9 && th0 <= tMax * (1 + 1e-9) + 1e-9)) return false;
+    const E = this.edges;
+    const b = tri * 9;
+    const e1x = E[b + 3] ?? 0;
+    const e1y = E[b + 4] ?? 0;
+    const e1z = E[b + 5] ?? 0;
+    const e2x = E[b + 6] ?? 0;
+    const e2y = E[b + 7] ?? 0;
+    const e2z = E[b + 8] ?? 0;
+    const px = dy * e2z - dz * e2y;
+    const py = dz * e2x - dx * e2z;
+    const pz = dx * e2y - dy * e2x;
+    const det = e1x * px + e1y * py + e1z * pz;
+    if (Math.abs(det) < 1e-14) return false;
+    const inv = 1 / det;
+    const tx = ox - (E[b] ?? 0);
+    const ty = oy - (E[b + 1] ?? 0);
+    const tz = oz - (E[b + 2] ?? 0);
+    const u = (tx * px + ty * py + tz * pz) * inv;
+    if (u < 0 || u > 1) return false;
+    const qx = ty * e1z - tz * e1y;
+    const qy = tz * e1x - tx * e1z;
+    const qz = tx * e1y - ty * e1x;
+    const v = (dx * qx + dy * qy + dz * qz) * inv;
+    if (v < 0 || u + v > 1) return false;
+    const th = (e2x * qx + e2y * qy + e2z * qz) * inv;
+    return th > 0 && th <= tMax;
+  }
+
+  /** True if the ray o + t·d (d unit) hits any triangle for 0 < t ≤ tMax. */
+  occluded(o: Vec3, d: Vec3, tMax: number): boolean {
+    return this.hit(o[0], o[1], o[2], d[0], d[1], d[2], tMax);
+  }
+}