@solidrt/3d 0.0.48 → 0.0.49

package/AGENTS.md

@@ -49,9 +49,9 @@ blendMode and pointer events like any element. Design rationale:
 
 | Component | Props |
 | --- | --- |
-| `Scene` | `width`, `height` (target pixels), `clearColor?`, `label?`, `ref?(scene)`, `output?(texture)` |
-| `Group` | `position?`, `rotation?` (Euler radians, XYZ order), `quaternion?` (either, not both), `scale?` (number = uniform), `visible?`, `ref?(node)` |
-| `Mesh` | `geometry`, `material`, transforms as Group, `params?` (per-mesh uniforms, merge semantics - no unset), `ref?(mesh)` |
+| `Scene` | `width`, `height` (target pixels), `clearColor?`, `background?` (fragment GLSL), `label?`, `ref?(scene)`, `output?(texture)`, `events?` (mesh pointer events, default on) |
+| `Group` | `position?`, `rotation?` (Euler radians, XYZ order), `quaternion?` (either, not both), `scale?` (number = uniform), `visible?`, pointer events (below), `ref?(node)` |
+| `Mesh` | `geometry`, `material`, transforms as Group, `params?` (per-mesh uniforms, merge semantics - no unset), pointer events (below), `ref?(mesh)` |
 | `PerspectiveCamera` | `fov?` (vertical DEGREES, default 60), `near?`, `far?`, `position?`, `lookAt?`, `up?` |
 
 Output composition: without `output`, `Scene` emits a minimal
@@ -102,6 +102,40 @@ immediately, so set-then-project in one tick is exact. `scene.viewProj(out?)`
 copies the view-projection matrix for batch work. Never rebuild the
 camera matrices by hand for a HUD.
 
+Picking: `scene.pick(x, y)` is project()'s inverse - the camera ray
+through a scene pixel, returning `Hit[]` (`{ mesh, distance, point }`,
+world units, nearest first; every hit along the ray, not just the front
+one). `scene.raycast(origin, direction)` is the world-space primitive
+under it. The volume tier: hits test each mesh's local bounding box,
+transformed exactly under any node transform (non-uniform scale
+included), so results are conservative - a ray through a knot's hole
+still hits (no `face`/`uv` fields until a triangle tier exists).
+Broadphase is a dynamic AABB tree (BVH) the sync walk keeps current from
+its own dirty set - maintenance is O(changed), a query O(log meshes) -
+so per-pointer-move picking puts no ceiling on scene size. Both methods
+flush pending writes first (the lookAt/project immediacy contract), and
+both skip invisible meshes.
+
+Mesh pointer events - the element vocabulary one tree deeper:
+`onPointerDown/Move/Up/Enter/Leave` as plain fields on any node (and as
+Mesh/Group props). The nearest hit mesh is the target; down/move/up
+bubble mesh -> ancestor groups (`stopPropagation()` stops the walk);
+enter/leave fire on the mesh alone, pairing on hover changes. A
+pointer-down CAPTURES its mesh until the up: moves and the up keep
+dispatching to it off-mesh (the platform's captured-drag rule), with
+`point`/`distance` null while the ray misses it. The event carries the
+element fields (pointerId, pointerType, button, modifiers) plus `mesh`,
+`currentTarget`, `point`, `distance`, and `x`/`y` in scene pixels.
+Wiring: the built-in `<Scene>` leaf carries `scene.handlers`
+automatically (opt out: `events={false}`); an `output` leaf or
+imperative composition spreads `{...scene.handlers}` onto the element
+showing the texture. `scene.handlers` assumes that leaf is LAID OUT at
+the target size - true for the built-in leaf and a d-texture at natural
+size, under any ancestor transforms or viewBox fits (the hit test
+undoes them; localX/localY arrive in the leaf's layout frame). A leaf
+laid out at a different size (the supersampling pattern) uses
+`scene.handlersFor(() => ({ width, height }))` with its layout size.
+
 Geometry: `box(w?, h?, d?)`; `plane(w?, h?)`, `circle(radius?, seg?)` and
 `ring(inner?, outer?, seg?)` (XY, facing +z - rotate `[-Math.PI/2, 0, 0]`
 for a floor); `sphere(radius?, wSeg?, hSeg?)`;
@@ -175,6 +209,21 @@ Materials:
   disappears from the object keeps its old value; for per-frame values
   prefer `ref` + setMeshParams from onFrame, the setTransform split).
 
+Background: `scene.setBackground(source | null)`, the `background` option
+on createScene, and the reactive `Scene` prop. Fragment GLSL drawn as the
+FIRST entry of the scene's own pass (attributeless fullscreen triangle,
+depth off) - one target instead of a backdrop texture stacked under the
+scene, with no separate resize plumbing. The source gets the
+shader-target fragment contract exactly (vUV 0..1 top-left origin,
+iResolution, fragColor; no `#version` line = the standard preamble), so
+a `createShaderTexture` backdrop ports verbatim. Three's
+`scene.background = color` is `clearColor` here; a texture-id form can
+widen the signature later (a branded TextureId is a number, so
+`string | TextureId` disambiguates at runtime). No app-driven uniforms:
+a background is static art - anything animated is a mesh's own
+shaderMaterial (or, until blend factors land, a separate shader texture
+underneath, which translucent grounds also still need).
+
 Lighting GLSL (`@solidrt/3d/glsl`): exported string constants composed
 into shaderMaterial sources with plain template literals - `LIT_VERTEX`
 (the standard vertex stage: clip position plus vWorldPos/vNormal/vUv
@@ -197,7 +246,10 @@ system.
   and show mesh interiors.
 - `visible: false` keeps the entry, drawn with `instanceCount: 0` (a
   cheap off switch). Hidden meshes skip uModel writes; the fresh matrix is
-  written on unhide.
+  written on unhide. A freshly attached entry starts off the same way and
+  sync() turns it on when it writes uModel - never add one live: it has no
+  world matrix yet, and drawn before the sync microtask it flashes at the
+  world origin for a frame.
 - Alpha does not blend in v1: pipelines are opaque (`blend: "none"`), a
   translucent color overwrites. Transparency waits on blend factors +
   sorting (research note, staging step 4).
@@ -304,3 +356,33 @@ system.
   vertex source - a comment counts - selects the "colored" layout, and
   the material then rejects standard geometry at add(). Do not mention
   aColor you do not read.
+- Picking is the VOLUME tier: a hit means the ray crossed the mesh's
+  transformed bounding box, not its surface. Never present `point` as a
+  surface point (it is the box-entry point), and never add a
+  triangle-accurate path in JS - per-triangle rays at mesh scale are
+  interpreter-hostile; that tier is core work (BVH descent per the
+  differentiators ladder).
+- `scene.handlers` vs `handlersFor`: localX/localY arrive in the leaf's
+  LAYOUT frame (every ancestor transform and viewBox fit is already
+  undone by the element hit test). `handlers` therefore assumes leaf
+  layout == target pixels; scaling by `getBoundingBox` would be WRONG -
+  the box composes transforms, and it would double-correct the built-in
+  leaf under a viewBox. Only a leaf whose layout size deliberately
+  differs from the target (supersampling) needs `handlersFor`, fed the
+  layout size the app itself set.
+- Hover (enter/leave) reacts to pointer MOTION only: a mesh animating
+  under a still pointer fires nothing until the next move - the same
+  limit the element hit test has (hit-test-per-frame is an open platform
+  item). Do not poll pick() per frame to fake it.
+- Geometry local bounds cache on the Geometry (like its GPU buffers):
+  geometry is immutable after creation. Mutating `vertices` after a mesh
+  used them leaves stale bounds AND a stale GPU buffer - make a new
+  Geometry instead.
+- The background covers the whole target with depth off, drawn first: it
+  REPLACES the clearColor visually (the clear still runs; you just never
+  see it), and a translucent mesh does not blend over it in-pass (blend
+  is none|add today - the fade-over-backdrop look still needs the
+  two-layer composition until blend factors land).
+- The background pipeline/program are SCENE-OWNED (unlike shared
+  material pipelines): setBackground(null), replacement, and dispose()
+  destroy them. Do not hand the background's pipeline to anything else.

package/README.md

@@ -51,6 +51,16 @@ Three's `Euler` default, and `getRotation(node)` reads one back. The
 verbs: `quatFromAxisAngle`, `quatMultiply`, and `quatSlerp` (smooth
 tracking, damped follows) round out `quatFromTo`; `examples/aim.tsx`
 shows each aiming style live.
+
+Meshes take pointer events like elements do: `onPointerDown/Move/Up/
+Enter/Leave` props on `<Mesh>` and `<Group>`, with bubbling, capture on
+drag, and hover enter/leave pairs - hit testing runs over a BVH the
+scene maintains incrementally, so events put no ceiling on scene size.
+Underneath sit `scene.pick(x, y)` (the camera ray through a pixel,
+`project()`'s inverse) and `scene.raycast(origin, direction)`; hits are
+bounding-box accurate in v1. A scene also takes a `background` - fragment
+GLSL drawn inside its own pass behind the meshes, replacing the stacked
+backdrop-texture pattern.
 Custom materials get a standard uniform set - per-mesh `uModel`/`uNormal`,
 shared `uViewProj`/`uCamPos`, each written once per change - plus your own
 uniforms per mesh, declaratively via the `params` prop on `<Mesh>` or
@@ -67,8 +77,9 @@ mitred joints, flat `shape`, with `fillet`/`roundRect`/`triangulate`
 helpers), a per-vertex data channel
 (`withColors` adds an `aColor` vec4 - tint, baked AO, any four scalars -
 to any geometry, for materials that read it), one perspective camera
-with an orbit control (`createOrbitCamera`: drag, pinch/wheel zoom, auto-orbit).
-Lights, transparency, model loading and picking are
+with an orbit control (`createOrbitCamera`: drag, pinch/wheel zoom, auto-orbit),
+mesh picking with pointer events, and scene backgrounds.
+Lights, transparency and model loading are
 staged next - see `okf/research/scene-graph-3d.md` for the roadmap. Full
 usage notes and traps: [AGENTS.md](AGENTS.md); runnable examples:
 [examples/](examples/).

package/examples/README.md

@@ -15,3 +15,11 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   target: `lookAt` for a +z solid, `quatFromTo` for aiming a y-axis cone,
   and a `quatSlerp` damped follow that visibly lags; all driven from
   onFrame through refs, no per-frame signals.
+- `pick.tsx` - mesh pointer events: hover tints (enter/leave), click
+  pops (down), a Group hearing its children's clicks through bubbling
+  and one mesh stopping the walk; a STATIC scene rendered only when an
+  event changes something, with hit testing over the scene's BVH.
+- `scene-background.tsx` - a fragment-GLSL background drawn inside the
+  scene's own pass (`<Scene background>`): one target, no stacked
+  backdrop texture, no resize plumbing; the source is shader-target
+  compatible verbatim.

package/examples/pick.tsx

@@ -0,0 +1,98 @@
+// Mesh pointer events: hover to tint (enter/leave), click to pop (down),
+// with a Group seeing its children's clicks through bubbling and one mesh
+// stopping the walk. The scene is STATIC - no onFrame - so it renders only
+// when an event changes something: picking is demand-driven like
+// everything else. Events flow because the built-in <Scene> leaf carries
+// scene.handlers (default on); hit testing runs over the scene's BVH, so a
+// pointer move costs O(log meshes).
+//
+// The volume tier is honest about its shape: hits test each mesh's
+// bounding box, so hovering just outside the ball's silhouette (inside its
+// box corners) still counts. Triangle-accurate hits are a later tier.
+
+import { createSignal, pct, render } from "@solidrt/core"
+import { box, cone, Group, Mesh, PerspectiveCamera, plane, Scene, setMeshParams, setTransform, sphere, torus, unlit } from "@solidrt/3d"
+import type { Geometry, ScenePointerEvent, Vec3 } from "@solidrt/3d"
+
+const SIZE = 720
+
+type Color = [number, number, number]
+
+let [hovered, setHovered] = createSignal("nothing")
+let popped = new Set<object>()
+
+/** A pickable mesh: unlit color that brightens on hover, scale-pop on
+ * click. setMeshParams writes raw uniform values, so the tint premultiplies
+ * here (alpha 1: the rgb passes through). */
+function Pickable(p: { name: string; color: Color; geometry: Geometry; position: Vec3; scale?: number; stop?: boolean }) {
+  let lift = (up: number): [number, number, number, number] => [
+    Math.min(p.color[0] + up, 1),
+    Math.min(p.color[1] + up, 1),
+    Math.min(p.color[2] + up, 1),
+    1,
+  ]
+  return (
+    <Mesh
+      geometry={p.geometry}
+      material={unlit({ color: p.color })}
+      position={p.position}
+      scale={p.scale}
+      onPointerEnter={(e: ScenePointerEvent) => {
+        setHovered(p.name)
+        setMeshParams(e.mesh, { uColor: lift(0.25) })
+        console.log(`enter ${p.name}`)
+      }}
+      onPointerLeave={(e: ScenePointerEvent) => {
+        setHovered("nothing")
+        setMeshParams(e.mesh, { uColor: lift(0) })
+        console.log(`leave ${p.name}`)
+      }}
+      onPointerDown={(e: ScenePointerEvent) => {
+        let pop = !popped.has(e.mesh)
+        if (pop) popped.add(e.mesh)
+        else popped.delete(e.mesh)
+        setTransform(e.mesh, { scale: pop ? (p.scale ?? 1) * 1.25 : (p.scale ?? 1) })
+        let pt = e.point!
+        console.log(`down ${p.name} at ${pt[0].toFixed(2)},${pt[1].toFixed(2)},${pt[2].toFixed(2)} d=${e.distance!.toFixed(2)}`)
+        // The cone demonstrates stopping the bubble: its group never hears it.
+        if (p.stop) e.stopPropagation()
+      }}
+    />
+  )
+}
+
+function App() {
+  let floor = plane(8, 8, "floor")
+  let crate = box()
+  let ball = sphere(0.45)
+  let spike = cone(0.45, 1)
+  let ring = torus(0.4, 0.14)
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.07, 0.07, 0.1, 1]} label="pick">
+          <PerspectiveCamera fov={55} position={[0, 2.6, 5]} lookAt={[0, 0.4, 0]} />
+          <Mesh geometry={floor} material={unlit({ color: [0.15, 0.16, 0.2] })} rotation={[-Math.PI / 2, 0, 0]} />
+          {/* The group hears every child click that is not stopped. */}
+          <Group onPointerDown={() => console.log("group saw down")}>
+            <Pickable name="crate" color={[0.85, 0.3, 0.3]} geometry={crate} position={[-1.6, 0.4, 0]} scale={0.8} />
+            <Pickable name="cone" color={[0.35, 0.65, 0.9]} geometry={spike} position={[1.6, 0.5, 0]} stop />
+          </Group>
+          <Pickable name="ball" color={[0.9, 0.8, 0.35]} geometry={ball} position={[0, 0.45, 0]} />
+          <Pickable name="ring" color={[0.5, 0.85, 0.5]} geometry={ring} position={[0.9, 0.35, -1.6]} />
+        </Scene>
+        <view position="absolute" x={0} y={0} padding={16} gap={4}>
+          <text color="#eef4ff" fontSize={22} fontWeight={700}>
+            {`hover: ${hovered()}`}
+          </text>
+          <text color="#8fa6c8" fontSize={13}>
+            hover tints, click pops - a static scene, rendered only on change
+          </text>
+        </view>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/examples/scene-background.tsx

@@ -0,0 +1,43 @@
+// A scene background: fragment GLSL drawn as the first entry of the
+// scene's own pass - no second target, no stacked texture layers, no
+// resize plumbing. The source below uses only the shader-target contract
+// (vUV, iResolution, fragColor), so it would work unchanged in
+// createShaderTexture; here it costs nothing extra - the one scene pass
+// paints backdrop and meshes together, and a static scene still renders
+// zero passes when idle.
+
+import { pct, render } from "@solidrt/core"
+import { glsl } from "@solidrt/core/gpu"
+import { box, Mesh, PerspectiveCamera, Scene, sphere, torusKnot, unlit } from "@solidrt/3d"
+
+const SIZE = 720
+
+// A radial night-sky gradient with hash grain so the ramp does not band.
+let BACKDROP = glsl`
+  void main() {
+    float d = distance(vUV, vec2(0.5, 0.35));
+    vec3 near = vec3(0.10, 0.13, 0.22);
+    vec3 far = vec3(0.02, 0.03, 0.06);
+    vec3 col = mix(near, far, smoothstep(0.05, 0.9, d));
+    float n = fract(sin(dot(vUV * iResolution, vec2(12.9898, 78.233))) * 43758.5453);
+    col += (n - 0.5) * 0.012;
+    fragColor = vec4(col, 1.0);
+  }
+`
+
+function App() {
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} viewBox={[SIZE, SIZE]}>
+        <Scene width={SIZE} height={SIZE} background={BACKDROP} label="backdrop-demo">
+          <PerspectiveCamera fov={55} position={[0, 1.8, 4.4]} lookAt={[0, 0.4, 0]} />
+          <Mesh geometry={torusKnot(0.7, 0.2, 128, 16)} material={unlit({ color: [0.85, 0.55, 0.25] })} position={[0, 0.9, 0]} />
+          <Mesh geometry={box()} material={unlit({ color: [0.3, 0.5, 0.8] })} position={[-1.5, 0.4, -0.5]} scale={0.8} />
+          <Mesh geometry={sphere(0.4)} material={unlit({ color: [0.4, 0.75, 0.45] })} position={[1.5, 0.4, -0.5]} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.48",
+  "version": "0.0.49",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -16,7 +16,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-beta.31",
-    "@solidrt/core": "0.0.48"
+    "@solidjs/signals": "2.0.0-rc.0",
+    "@solidrt/core": "0.0.49"
   }
 }

package/src/bvh.ts

@@ -0,0 +1,258 @@
+// A dynamic bounding-volume hierarchy - the physics-broadphase AABB tree
+// (Box2D/Bullet lineage): a binary tree over the items' world boxes, NOT a
+// subdivision of space. Leaves store FAT boxes (a margin around the tight
+// bounds) so an item moving a little refits nothing; an item escaping its
+// fat box is removed and re-inserted along the cheapest path (least area
+// growth). A ray query walks O(log n) nodes instead of testing every item,
+// which is what keeps per-pointer-move picking off the O(meshes) path.
+//
+// The scene keeps the tree current from its own sync walk: transforms that
+// changed are exactly the leaves to update, so maintenance is O(changed)
+// per frame - the same delta discipline as rendering, and a static scene
+// pays nothing. Storage is flat parallel arrays indexed by node id (no
+// per-node objects, no allocation at steady state past tree growth).
+//
+// Pure module by design: no engine imports, so the differential check rig
+// (checks/pick-check.ts) runs it under plain bun against a linear oracle.
+
+/** Fat-margin fraction of a leaf's largest extent. Bigger = fewer
+ * re-inserts while moving, worse query pruning; 5% is the usual trade. */
+const MARGIN = 0.05
+
+type Visit<T> = (item: T) => void
+
+export type Bvh<T> = {
+  /** Insert an item with its tight world box; returns the leaf handle. */
+  insert(item: T, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number
+  /** Update a leaf's tight box. Free while it stays inside the fat box;
+   * otherwise the leaf re-inserts. Returns true when it moved. */
+  update(leaf: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): boolean
+  /** Remove a leaf (the handle is dead afterwards). */
+  remove(leaf: number): void
+  /** Visit every item whose FAT box the ray hits (t >= 0). Broadphase
+   * only: the caller narrowphases against its own tight volumes. */
+  raycast(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, visit: Visit<T>): void
+}
+
+/**
+ * Entry distance of a ray against a box: the smallest t >= 0 with
+ * origin + t * direction inside [min, max] (0 when the origin starts
+ * inside), or -1 for a miss. The direction need not be normalized - t is
+ * in units of its length, which is what keeps a ray transformed into a
+ * mesh's local space reporting world distances. Shared by the tree's
+ * broadphase and the scene's narrowphase.
+ */
+export function rayBoxDistance(
+  ox: number, oy: number, oz: number,
+  dx: number, dy: number, dz: number,
+  minX: number, minY: number, minZ: number,
+  maxX: number, maxY: number, maxZ: number,
+): number {
+  let tNear = 0
+  let tFar = Infinity
+  // Per axis: a zero direction component never crosses the slab, so the
+  // origin must already be inside it (the multiply-by-inverse shortcut
+  // turns that case into NaN, hence the explicit branch).
+  if (dx === 0) {
+    if (ox < minX || ox > maxX) return -1
+  } else {
+    let inv = 1 / dx
+    let t1 = (minX - ox) * inv
+    let t2 = (maxX - ox) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  if (dy === 0) {
+    if (oy < minY || oy > maxY) return -1
+  } else {
+    let inv = 1 / dy
+    let t1 = (minY - oy) * inv
+    let t2 = (maxY - oy) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  if (dz === 0) {
+    if (oz < minZ || oz > maxZ) return -1
+  } else {
+    let inv = 1 / dz
+    let t1 = (minZ - oz) * inv
+    let t2 = (maxZ - oz) * inv
+    if (t1 > t2) { let t = t1; t1 = t2; t2 = t }
+    if (t1 > tNear) tNear = t1
+    if (t2 < tFar) tFar = t2
+  }
+  return tFar >= tNear ? tNear : -1
+}
+
+export function createBvh<T>(): Bvh<T> {
+  // Node storage, 6 bounds floats per node; child1 === -1 marks a leaf.
+  let bounds: number[] = []
+  let parent: number[] = []
+  let child1: number[] = []
+  let child2: number[] = []
+  let items: (T | undefined)[] = []
+  let free: number[] = []
+  let root = -1
+  // Traversal stack, reused across queries.
+  let stack: number[] = []
+
+  let allocate = (): number => {
+    let node = free.pop()
+    if (node === undefined) {
+      node = parent.length
+      bounds.push(0, 0, 0, 0, 0, 0)
+      parent.push(-1)
+      child1.push(-1)
+      child2.push(-1)
+      items.push(undefined)
+    }
+    return node
+  }
+
+  // Half the surface area - the SAH cost of a node's box. Degenerate
+  // (flat) boxes still cost via their other faces, which is what makes
+  // the heuristic sane for planes.
+  let area = (n: number): number => {
+    let i = n * 6
+    let w = bounds[i + 3]! - bounds[i]!
+    let h = bounds[i + 4]! - bounds[i + 1]!
+    let d = bounds[i + 5]! - bounds[i + 2]!
+    return w * (h + d) + h * d
+  }
+
+  let unionArea = (n: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number => {
+    let i = n * 6
+    let w = Math.max(bounds[i + 3]!, maxX) - Math.min(bounds[i]!, minX)
+    let h = Math.max(bounds[i + 4]!, maxY) - Math.min(bounds[i + 1]!, minY)
+    let d = Math.max(bounds[i + 5]!, maxZ) - Math.min(bounds[i + 2]!, minZ)
+    return w * (h + d) + h * d
+  }
+
+  // Recompute an internal node's box as the union of its children.
+  let refit = (n: number): void => {
+    let a = child1[n]! * 6
+    let b = child2[n]! * 6
+    let i = n * 6
+    bounds[i] = Math.min(bounds[a]!, bounds[b]!)
+    bounds[i + 1] = Math.min(bounds[a + 1]!, bounds[b + 1]!)
+    bounds[i + 2] = Math.min(bounds[a + 2]!, bounds[b + 2]!)
+    bounds[i + 3] = Math.max(bounds[a + 3]!, bounds[b + 3]!)
+    bounds[i + 4] = Math.max(bounds[a + 4]!, bounds[b + 4]!)
+    bounds[i + 5] = Math.max(bounds[a + 5]!, bounds[b + 5]!)
+  }
+
+  let insertLeaf = (leaf: number): void => {
+    if (root === -1) {
+      root = leaf
+      parent[leaf] = -1
+      return
+    }
+    let i = leaf * 6
+    let minX = bounds[i]!, minY = bounds[i + 1]!, minZ = bounds[i + 2]!
+    let maxX = bounds[i + 3]!, maxY = bounds[i + 4]!, maxZ = bounds[i + 5]!
+    // Descend toward the sibling that grows the least (the classic
+    // incremental surface-area heuristic).
+    let sibling = root
+    while (child1[sibling] !== -1) {
+      let a = child1[sibling]!
+      let b = child2[sibling]!
+      let costA = unionArea(a, minX, minY, minZ, maxX, maxY, maxZ) - area(a)
+      let costB = unionArea(b, minX, minY, minZ, maxX, maxY, maxZ) - area(b)
+      sibling = costA < costB ? a : b
+    }
+    let oldParent = parent[sibling]!
+    let newParent = allocate()
+    parent[newParent] = oldParent
+    child1[newParent] = sibling
+    child2[newParent] = leaf
+    items[newParent] = undefined
+    parent[sibling] = newParent
+    parent[leaf] = newParent
+    if (oldParent === -1) {
+      root = newParent
+    } else if (child1[oldParent] === sibling) {
+      child1[oldParent] = newParent
+    } else {
+      child2[oldParent] = newParent
+    }
+    for (let n = newParent; n !== -1; n = parent[n]!) refit(n)
+  }
+
+  let removeLeaf = (leaf: number): void => {
+    if (leaf === root) {
+      root = -1
+      return
+    }
+    let p = parent[leaf]!
+    let sibling = child1[p] === leaf ? child2[p]! : child1[p]!
+    let grand = parent[p]!
+    parent[sibling] = grand
+    if (grand === -1) {
+      root = sibling
+    } else {
+      if (child1[grand] === p) child1[grand] = sibling
+      else child2[grand] = sibling
+      for (let n = grand; n !== -1; n = parent[n]!) refit(n)
+    }
+    child1[p] = -1
+    items[p] = undefined
+    free.push(p)
+  }
+
+  let setFat = (leaf: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): void => {
+    let m = MARGIN * Math.max(maxX - minX, maxY - minY, maxZ - minZ)
+    let i = leaf * 6
+    bounds[i] = minX - m
+    bounds[i + 1] = minY - m
+    bounds[i + 2] = minZ - m
+    bounds[i + 3] = maxX + m
+    bounds[i + 4] = maxY + m
+    bounds[i + 5] = maxZ + m
+  }
+
+  return {
+    insert(item, minX, minY, minZ, maxX, maxY, maxZ) {
+      let leaf = allocate()
+      items[leaf] = item
+      setFat(leaf, minX, minY, minZ, maxX, maxY, maxZ)
+      insertLeaf(leaf)
+      return leaf
+    },
+    update(leaf, minX, minY, minZ, maxX, maxY, maxZ) {
+      let i = leaf * 6
+      if (
+        bounds[i]! <= minX && bounds[i + 1]! <= minY && bounds[i + 2]! <= minZ &&
+        bounds[i + 3]! >= maxX && bounds[i + 4]! >= maxY && bounds[i + 5]! >= maxZ
+      ) {
+        return false
+      }
+      removeLeaf(leaf)
+      setFat(leaf, minX, minY, minZ, maxX, maxY, maxZ)
+      insertLeaf(leaf)
+      return true
+    },
+    remove(leaf) {
+      removeLeaf(leaf)
+      items[leaf] = undefined
+      free.push(leaf)
+    },
+    raycast(ox, oy, oz, dx, dy, dz, visit) {
+      if (root === -1) return
+      stack.length = 0
+      stack.push(root)
+      while (stack.length > 0) {
+        let n = stack.pop()!
+        let i = n * 6
+        let t = rayBoxDistance(ox, oy, oz, dx, dy, dz, bounds[i]!, bounds[i + 1]!, bounds[i + 2]!, bounds[i + 3]!, bounds[i + 4]!, bounds[i + 5]!)
+        if (t < 0) continue
+        if (child1[n] === -1) {
+          visit(items[n] as T)
+        } else {
+          stack.push(child1[n]!, child2[n]!)
+        }
+      }
+    },
+  }
+}