@driftengine/core 4.5.0 → 4.6.1

package/CHANGELOG.json

@@ -1,4 +1,66 @@
 [
+ {
+  "version": "4.6.1",
+  "date": "2026-10-01",
+  "entries": [
+   {
+    "kind": "fixed",
+    "short": "A mesh with no triangles is skipped by every pass instead of drawn as nothing, so a game's console no longer fills with WebGPU warnings about empty draws.",
+    "text": "**A mesh with no triangles draws nothing, in every pass, on both backends.** A game's world can hold an empty mesh, for a level with none of that kind of geometry, and every pass it reached issued a draw of zero indices: WebGPU answers each with a warning, five on one game's first screen (the frame, its reflection, the sun's static and peeled maps and a lamp's shadow faces), and WebGL2 counted draws that drew nothing. `GpuMesh.indexCount` and `Mesh.indexCount` carry the rule, and every place a mesh enters a pass skips an empty one beside its other checks: meshes, translucent meshes, instanced batches, light volumes, shadow casters, glass depth and the motion pass. A game that already skipped its empty meshes itself can keep doing so."
+   }
+  ]
+ },
+ {
+  "version": "4.6.0",
+  "date": "2026-10-01",
+  "entries": [
+   {
+    "kind": "added",
+    "short": "A whole city streamed from one container: regions arrive near the eye first, each drawn at the detail its distance asks for, with its collision, navigation and entities.",
+    "text": "**Container 1.23 carries a world built from a kit.** An assembly is painted copies of kit pieces rather than its own vertices, a region (`REGN`) names the assemblies, instance groups, occluders and collision of one square of the world, and a world's finest level is paged: `writeDrft` writes the regions nearest a starting point first, and `texturesFirst` puts the pictures ahead of the geometry so every region can wear them as it lands. `buildKit`, `buildAssembly`, `expandAssembly` and `planRegions` are the format's halves, and a mesh's sway, sky and opacity channel now survives a bake.\n\n**`DrftLoader` hands a streamed world over a region at a time**, never merged into its parts, as `LoadedRegion`s with their levels, collision, navigation and entities; `onMesh` takes the meshes no region holds and `onImage` each picture as it decodes. `StaticRegions` collides a scene's scenery a region at a time. **`HlodSet` picks each region's level of detail by its geometric error on screen**, with a band no still eye can cross, and `setDitherFade` crossfades two levels with a screen-door dither on both backends.\n\nMeasured on a two-kilometre city of 484 regions and 18.8 million triangles at its finest: the 14 regions within 150 m of the start are whole after 13 MB of a 130 MB file."
+   },
+   {
+    "kind": "added",
+    "short": "Instancing that culls: a batch spread across a city is tested against the view and the occluders whole, then instance by instance on the GPU, and small batches are drawn whole.",
+    "text": "**`createInstanced(mesh, capacity, { cull: true })`** tests the whole batch against the view and the declared box occluders (`occludedBox`) on the CPU, then keeps each instance only where its sphere meets the view: as compute into an indirect draw on WebGPU, on the CPU on WebGL2. A scene may hold as many batches of one mesh as it has regions.\n\n**A batch too small to repay that is drawn whole** (`cullsInstances`, 16,384 indices). Chrome's GPU process validates each indirect draw at about 8 µs, so a per-instance cull of a few lamps cost more than drawing them: on a city street, 633 indirect draws a frame became 108 and the frame went from 19.5 to 10.8 ms, pixel-identical. Shadow, motion and blended draws still see every instance."
+   },
+   {
+    "kind": "added",
+    "short": "Texture arrays per face, and per-layer surface effects: rooms behind windows, windows lit by night, wear, scrolling and flickering signs, and rain: a whole block of facades in one draw.",
+    "text": "**`createSurfaceTextureArray(sources, { effects })`**: every surface texture is an array, and a mesh names which layer each face wears, so one merged mesh wearing many images is one draw. Each layer may carry a `SurfaceLayerEffect`: **rooms behind its windows** (interior mapping from a room layer in the same array), **windows lit by night** (`Environment.litWindows`, with `lateWindows` the share that stays lit latest, and the light itself carried per building on the vertices so a style shared by forty facades still lights each its own way), **wear** (dust, grime, streaks), **animation** (scroll, pulse, flicker, flipbook frames and a fade with distance, on the caller's `surfaceTime` so a held clock holds it) and **rain** (`Environment.wetness`, with `dry` for a covered surface).\n\nThe effects are a texel row per layer (`packSurfaceEffects`, `SURFACE_EFFECT_TEXELS`), the same on both backends."
+   },
+   {
+    "kind": "added",
+    "short": "Every lamp in a city lit: a world's lights summed offline into one dense volume read past the exact lights, and the exact ones chosen through a grid instead of a scan.",
+    "text": "**`bakeDenseField`** sums a whole world's fixed lights offline into one dense volume, sample for sample what the bricks hold, carried in the container as `LVOL` in runs of dark, solid and lit samples. **`WorldLightField`** (`createWorldLightField`) takes it whole and lights every surface past the exact lights on both backends, so a street three blocks away is lit by its own lamps without spending a shadow or a slot on them.\n\n**`createLightGrid` and `selectGridLights`** find the frame's exact lights through a grid, choosing exactly what the full scan chose field for field, so a city of seven thousand lamps picks its nearest without visiting them all. A tie for a shadow map now goes to the lamp listed first rather than to the way its distance rounded."
+   },
+   {
+    "kind": "added",
+    "short": "Solids and booleans: closed, outward solids from a box to a torus, transforms that keep normals true, and exact booleans that split only what the other operand reaches.",
+    "text": "**Solids in the barrel**: `solidBox`, `solidCylinder`, `solidSphere`, `solidTorus`, `solidLathe`, `solidExtrude`, `solidSweep` and the rest, each closed and wound outward, with `transformSolid` keeping normals true under any scale, `mergeSolids`, `smoothSolidNormals` and `solidToMesh`.\n\n**Booleans**: `solidUnion`, `solidSubtract` and `solidIntersect` through a BSP that splits only what the other operand reaches, and `solidBoxBoolean` exact on axis-aligned boxes, which is most of what a building is cut from."
+   },
+   {
+    "kind": "added",
+    "short": "A translucent draw can add its light instead of covering, and a glow lying on a surface can be reconstructed with it; added light now fades in fog instead of greying.",
+    "text": "**`TranslucentMeshOptions.additive`**: the surface's colour times its opacity is added and nothing is darkened, as a glow or a pool of light under a lamp is. Order does not matter to a sum, so an additive draw is never held for the order-independent pass. **Added light fades in the medium** (`uFogEnabled` at 2): mixed toward the fog's colour and then added, a glow put the haze into the frame twice, and every lamp's light cone drew by day as a grey solid, greyer the thicker the air.\n\n**`TranslucentMeshOptions.reconstructed`**: a translucent surface that moves with what it lies on, such as a glow on a wall or a pane in a window, is drawn into the picture the reconstruction resolves rather than after it, so it is resolved with the edge it lies against. A street's glows went from 34,757 pixels changing between still frames to 2,999 (2,470 with the reconstruction off)."
+   },
+   {
+    "kind": "fixed",
+    "short": "Still frames hold still under reconstruction: thin edges, rails and glows no longer shimmer, bloom halos and ambient occlusion no longer pulse with the jitter.",
+    "text": "**DriftTR keeps the temporal resolve's anti-flicker, over its own period.** Each output pixel keeps a record of its gathered luma, and once two periods running repeat while still its box widens by its own spread and it keeps more history; the width follows the period (`flickerRule`), since eighteen phases wear a spread down further between catches than eight. **A still pixel whose depth has been seen to swing is not a disocclusion**: a held peak of how far last frame's depth missed widens its depth tolerance, so a rail finer than a texel no longer drops its history every period. **The camera's motion goes through one reprojection matrix multiplied in double precision**: the single-precision round trip through a world position read a few hundredths of a pixel of motion on a still camera, crept every still history and kept every pixel from counting as still. A still city view: 1,156 pixels changing between frames to 355 (184 native).\n\n**Glows and panes after the upscale** are tested against each render texel's surface carried to the pixel's centre, not the nearest of four, which let a glow along an edge through on one frame in two. **A reconstruction blooms the resolved picture**, not the jittered render, whose sub-texel bright points pulsed their halos. **The composite reads ambient occlusion where the frame's jitter put it**, under the temporal resolve and the reconstruction alike. **An interface drawn after the present is not jittered and opens no temporal frame**: every consumer drawing its HUD after `endFrame` had half the temporal resolve's jitter sequence and no anti-flicker at all."
+   },
+   {
+    "kind": "changed",
+    "short": "The generated WGSL stores each shared function once: core's WebGPU shaders are 185 KB smaller.",
+    "text": "**Each shared item of the generated WGSL is stored once** and renumbered per function, where every permutation carried its own copy: the lit-shader helpers cost once, and core's WebGPU shader source is 185 KB smaller. Nothing about what a device compiles changes."
+   },
+   {
+    "kind": "fixed",
+    "short": "Smaller fixes: one-cell pixel-font strokes, a WebGPU inset after the present, materials on instanced batches, a kerb a character walks off, and no rain bars across the frame.",
+    "text": "- **The pixel font's strokes are one cell wide wherever the line is drawn**, and its brackets are whole; text under a perspective tilt divides about each cell's centre.\n- **An inset opened after the present on WebGPU** draws, as it did on WebGL2.\n- **A material setter reaches every WebGL2 flat program**, so an instanced batch wears what its caller set rather than the defaults.\n- **A material with no maps leaves an array stand-in on every WebGL2 surface unit**, and sprites borrow the last unit of the pool, not one the lit pass binds.\n- **A character stands on a triangle mesh's kerb and walks on**, and a round body near a mesh edge reports its real gap.\n- **A raindrop passing the eye is not drawn** (`RainFieldOptions.clearM`, a metre by default): a streak is a world-space width, so a drop 30 cm from the camera drew fourteen pixels thick and as long as the frame. It keeps falling, as a sheltered drop does; pass 0 to draw drops in macro."
+   }
+  ]
+ },
  {
   "version": "4.5.0",
   "date": "2026-09-29",

package/README.md

@@ -2,7 +2,7 @@
 
 The runtime everything needs: renderer, loop, camera, input, geometry. Collision and dynamics live in [`@driftengine/physics`](../physics/README.md), which this package depends on and re-exports whole, so reaching for them through this barrel works as it always did.
 
-**Cost: 887.4 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 699.0 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/geometry/boxCsg.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Booleans on axis-aligned boxes, exactly and with as few faces as the result has.
+ *
+ * **Why beside `csg.ts` rather than in it.** A BSP boolean splits every face along every plane that
+ * crosses it, unrelated cutters included, and never re-merges: a wall of seven boxes with twenty
+ * window openings cut out of it came back as 325,187 triangles and took a minute. Boxes that share
+ * their axes need none of that. Every face of the result lies on a plane some box already has, so
+ * the space splits into the grid of all their coordinates, each cell is in or out by applying the
+ * operations to its centre in order, and the surface is the faces between cells that differ —
+ * merged greedily into the largest rectangles that fit. The same wall is a few hundred triangles,
+ * in milliseconds.
+ *
+ * **What it gives up.** Only boxes, only on the three axes: a box turned off them is the BSP's.
+ * Merged rectangles meet with T-junctions, as the BSP's pieces do, so the result is closed as a
+ * surface — its volume exact — but not edge for edge. Texture coordinates run 0..1 across the
+ * result's own extent on each face's plane, which is what `solidBox` gives a single box. The grid
+ * costs a byte a cell, so a caller with hundreds of boxes should check `boxBooleanCells` first.
+ */
+import type { Solid } from './solid.ts';
+export interface BoxOperation {
+    /** Minimum and maximum corners: `[x0, y0, z0, x1, y1, z1]`. */
+    readonly box: readonly [number, number, number, number, number, number];
+    readonly op: 'union' | 'subtract' | 'intersect';
+}
+/** How many grid cells `solidBoxBoolean` would allocate for `operations`. */
+export declare function boxBooleanCells(operations: readonly BoxOperation[]): number;
+/** The solid the operations make, applied left to right from nothing. */
+export declare function solidBoxBoolean(operations: readonly BoxOperation[]): Solid;

package/dist/geometry/boxCsg.js

@@ -0,0 +1,139 @@
+import { emptySolid } from './solid.js';
+import { SolidWriter } from './solidWriter.js';
+/** Coordinates within this distance are one. */
+const SAME = 1e-6;
+function axis(operations, a) {
+    const values = operations
+        .flatMap((o) => [o.box[a], o.box[a + 3]])
+        .sort((p, q) => p - q);
+    const out = [];
+    for (const v of values)
+        if (out.length === 0 || v - out[out.length - 1] > SAME)
+            out.push(v);
+    return out;
+}
+/** How many grid cells `solidBoxBoolean` would allocate for `operations`. */
+export function boxBooleanCells(operations) {
+    return ((axis(operations, 0).length - 1) *
+        (axis(operations, 1).length - 1) *
+        (axis(operations, 2).length - 1));
+}
+/** The solid the operations make, applied left to right from nothing. */
+export function solidBoxBoolean(operations) {
+    if (operations.length === 0)
+        return emptySolid();
+    const xs = axis(operations, 0);
+    const ys = axis(operations, 1);
+    const zs = axis(operations, 2);
+    const nx = xs.length - 1;
+    const ny = ys.length - 1;
+    const nz = zs.length - 1;
+    if (nx <= 0 || ny <= 0 || nz <= 0)
+        return emptySolid();
+    const inside = new Uint8Array(nx * ny * nz);
+    const at = (i, j, k) => (k * ny + j) * nx + i;
+    for (let k = 0; k < nz; k += 1) {
+        const cz = (zs[k] + zs[k + 1]) / 2;
+        for (let j = 0; j < ny; j += 1) {
+            const cy = (ys[j] + ys[j + 1]) / 2;
+            for (let i = 0; i < nx; i += 1) {
+                const cx = (xs[i] + xs[i + 1]) / 2;
+                let state = false;
+                for (const o of operations) {
+                    const b = o.box;
+                    const hit = cx > b[0] && cx < b[3] && cy > b[1] && cy < b[4] && cz > b[2] && cz < b[5];
+                    if (o.op === 'union')
+                        state ||= hit;
+                    else if (o.op === 'subtract')
+                        state &&= !hit;
+                    else
+                        state &&= hit;
+                }
+                inside[at(i, j, k)] = state ? 1 : 0;
+            }
+        }
+    }
+    const filled = (i, j, k) => i >= 0 && j >= 0 && k >= 0 && i < nx && j < ny && k < nz && inside[at(i, j, k)] === 1;
+    const out = new SolidWriter();
+    const coords = [xs, ys, zs];
+    const counts = [nx, ny, nz];
+    const lo = [xs[0], ys[0], zs[0]];
+    const span = [
+        xs[nx] - lo[0],
+        ys[ny] - lo[1],
+        zs[nz] - lo[2],
+    ];
+    for (let d = 0; d < 3; d += 1) {
+        /* The face plane's two in-plane axes, ordered so (u × v) is +d. */
+        const u = (d + 1) % 3;
+        const v = (d + 2) % 3;
+        const nu = counts[u];
+        const nv = counts[v];
+        for (let s = 0; s <= counts[d]; s += 1) {
+            for (const sign of [1, -1]) {
+                /* Faces on plane s facing `sign`: the cell behind is in, the one in front is out. */
+                const mask = new Uint8Array(nu * nv);
+                for (let b = 0; b < nv; b += 1) {
+                    for (let a = 0; a < nu; a += 1) {
+                        const cell = [0, 0, 0];
+                        cell[u] = a;
+                        cell[v] = b;
+                        cell[d] = sign > 0 ? s - 1 : s;
+                        const front = [...cell];
+                        front[d] = sign > 0 ? s : s - 1;
+                        const inCell = filled(cell[0], cell[1], cell[2]);
+                        const inFront = filled(front[0], front[1], front[2]);
+                        if (inCell && !inFront)
+                            mask[b * nu + a] = 1;
+                    }
+                }
+                for (let b = 0; b < nv; b += 1) {
+                    for (let a = 0; a < nu; a += 1) {
+                        if (mask[b * nu + a] !== 1)
+                            continue;
+                        let a1 = a + 1;
+                        while (a1 < nu && mask[b * nu + a1] === 1)
+                            a1 += 1;
+                        let b1 = b + 1;
+                        grow: while (b1 < nv) {
+                            for (let x = a; x < a1; x += 1)
+                                if (mask[b1 * nu + x] !== 1)
+                                    break grow;
+                            b1 += 1;
+                        }
+                        for (let y = b; y < b1; y += 1)
+                            for (let x = a; x < a1; x += 1)
+                                mask[y * nu + x] = 0;
+                        quad(out, d, u, v, sign, coords[d][s], [
+                            coords[u][a],
+                            coords[u][a1],
+                            coords[v][b],
+                            coords[v][b1],
+                        ], lo, span);
+                    }
+                }
+            }
+        }
+    }
+    return out.finish();
+}
+function quad(out, d, u, v, sign, plane, [u0, u1, v0, v1], lo, span) {
+    const corner = (cu, cv) => {
+        const p = [0, 0, 0];
+        p[d] = plane;
+        p[u] = cu;
+        p[v] = cv;
+        const n = [0, 0, 0];
+        n[d] = sign;
+        return out.vertex(p[0], p[1], p[2], n[0], n[1], n[2], (cu - lo[u]) / (span[u] || 1), (cv - lo[v]) / (span[v] || 1));
+    };
+    const a = corner(u0, v0);
+    const b = corner(u1, v0);
+    const c = corner(u1, v1);
+    const e = corner(u0, v1);
+    /* Counter-clockwise from outside: (u × v) is +d, so a facing +d winds a b c, a facing −d reverses. */
+    if (sign > 0)
+        out.quad(a, b, c, e);
+    else
+        out.quad(a, e, c, b);
+}

package/dist/geometry/csg.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Boolean operations on closed solids — union, subtraction, intersection — by binary space
+ * partitioning.
+ *
+ * The algorithm is the one Evan Wallace's csg.js made well known, implemented afresh here — named
+ * at the point it is used, as `CREDITS.md` asks of a published method: each operand becomes a BSP tree of its own polygons, each tree clips the
+ * other's polygons to the region it keeps, and the survivors are rebuilt into one tree. Polygons
+ * carry position, normal and texture coordinates, interpolated where a plane splits them, so a cut
+ * face keeps the texture of the face it was cut from.
+ *
+ * **Only what the other operand reaches is split.** Each tree is used for its planes alone: an
+ * operand's own polygons are clipped as they arrived, never as its tree's construction cut them,
+ * and a polygon whose bounds clear the other operand's is passed through whole — kept or dropped
+ * as the operation says of everything outside that operand. The result is the two clipped lists
+ * side by side, where the published method rebuilds one tree from them and splits the second list
+ * along every plane of the first on the way. Neither changes the surface; together they are what
+ * kept a wall cut five times with its end faces at two triangles each instead of eight, and a
+ * city's worth of cut towers out of the millions.
+ *
+ * **What it gives up.** A polygon the other operand does reach is still split along every plane of
+ * its tree that crosses it, and nothing is re-merged, so a heavily cut solid grows, and the pieces
+ * meet with T-junctions: closed as a surface — its volume exact — but not edge for edge. Welding
+ * and simplification are the caller's afterwards. The tree is built iteratively, so a large
+ * operand cannot overflow the stack; clipping recurses to the tree's depth, which a solid of a few
+ * thousand faces keeps shallow.
+ *
+ * **Empty operands are answered before any tree is built**, because clipping against an empty tree
+ * keeps everything — which is the right answer for a union and the wrong one for an intersection.
+ */
+import type { Solid } from './solid.ts';
+/** Everything inside either solid. */
+export declare function solidUnion(a: Solid, b: Solid): Solid;
+/** Everything inside `a` and outside `b`. */
+export declare function solidSubtract(a: Solid, b: Solid): Solid;
+/** Everything inside both solids. */
+export declare function solidIntersect(a: Solid, b: Solid): Solid;

package/dist/geometry/csg.js

@@ -0,0 +1,329 @@
+import { emptySolid } from './solid.js';
+import { SolidWriter } from './solidWriter.js';
+/** Distance within which a point counts as on a plane. */
+const EPSILON = 1e-5;
+const COPLANAR = 0;
+const FRONT = 1;
+const BACK = 2;
+const SPANNING = 3;
+function planeFrom(a, b, c) {
+    const ux = b.x - a.x;
+    const uy = b.y - a.y;
+    const uz = b.z - a.z;
+    const vx = c.x - a.x;
+    const vy = c.y - a.y;
+    const vz = c.z - a.z;
+    let nx = uy * vz - uz * vy;
+    let ny = uz * vx - ux * vz;
+    let nz = ux * vy - uy * vx;
+    const len = Math.hypot(nx, ny, nz);
+    if (len < 1e-12)
+        return null;
+    nx /= len;
+    ny /= len;
+    nz /= len;
+    return { nx, ny, nz, w: nx * a.x + ny * a.y + nz * a.z };
+}
+function flipPolygon(p) {
+    const vertices = p.vertices
+        .slice()
+        .reverse()
+        .map((v) => ({ ...v, nx: -v.nx, ny: -v.ny, nz: -v.nz }));
+    return { vertices, plane: { nx: -p.plane.nx, ny: -p.plane.ny, nz: -p.plane.nz, w: -p.plane.w } };
+}
+function lerp(a, b, t) {
+    let nx = a.nx + (b.nx - a.nx) * t;
+    let ny = a.ny + (b.ny - a.ny) * t;
+    let nz = a.nz + (b.nz - a.nz) * t;
+    const len = Math.hypot(nx, ny, nz) || 1;
+    nx /= len;
+    ny /= len;
+    nz /= len;
+    return {
+        x: a.x + (b.x - a.x) * t,
+        y: a.y + (b.y - a.y) * t,
+        z: a.z + (b.z - a.z) * t,
+        nx,
+        ny,
+        nz,
+        u: a.u + (b.u - a.u) * t,
+        v: a.v + (b.v - a.v) * t,
+    };
+}
+/**
+ * Sort `polygon` against `plane` into the four lists, splitting it where it spans. A coplanar
+ * polygon goes to the front list when it faces the same way as the plane, the back one otherwise.
+ */
+function split(plane, polygon, coplanarFront, coplanarBack, front, back) {
+    let kind = 0;
+    const types = [];
+    for (const v of polygon.vertices) {
+        const t = plane.nx * v.x + plane.ny * v.y + plane.nz * v.z - plane.w;
+        const type = t < -EPSILON ? BACK : t > EPSILON ? FRONT : COPLANAR;
+        kind |= type;
+        types.push(type);
+    }
+    if (kind === COPLANAR) {
+        const facing = plane.nx * polygon.plane.nx + plane.ny * polygon.plane.ny + plane.nz * polygon.plane.nz;
+        (facing > 0 ? coplanarFront : coplanarBack).push(polygon);
+    }
+    else if (kind === FRONT) {
+        front.push(polygon);
+    }
+    else if (kind === BACK) {
+        back.push(polygon);
+    }
+    else if (kind === SPANNING) {
+        const f = [];
+        const b = [];
+        const n = polygon.vertices.length;
+        for (let i = 0; i < n; i++) {
+            const j = (i + 1) % n;
+            const ti = types[i] ?? COPLANAR;
+            const tj = types[j] ?? COPLANAR;
+            const vi = polygon.vertices[i];
+            const vj = polygon.vertices[j];
+            if (!vi || !vj)
+                continue;
+            if (ti !== BACK)
+                f.push(vi);
+            if (ti !== FRONT)
+                b.push(vi);
+            if ((ti | tj) === SPANNING) {
+                const di = plane.nx * vi.x + plane.ny * vi.y + plane.nz * vi.z;
+                const dj = plane.nx * vj.x + plane.ny * vj.y + plane.nz * vj.z;
+                const t = (plane.w - di) / (dj - di);
+                const mid = lerp(vi, vj, t);
+                f.push(mid);
+                b.push({ ...mid });
+            }
+        }
+        if (f.length >= 3)
+            front.push({ vertices: f, plane: polygon.plane });
+        if (b.length >= 3)
+            back.push({ vertices: b, plane: polygon.plane });
+    }
+}
+/** A BSP tree of an operand's planes. Its polygons only choose the planes and are not kept. */
+class Node {
+    plane = null;
+    front = null;
+    back = null;
+    /** Add `polygons`' planes to the tree, splitting down it, without recursion. */
+    build(polygons) {
+        const work = [[this, polygons]];
+        const coplanar = [];
+        while (work.length > 0) {
+            const item = work.pop();
+            if (!item)
+                break;
+            const [node, list] = item;
+            if (list.length === 0)
+                continue;
+            const first = list[0];
+            if (!node.plane && first)
+                node.plane = { ...first.plane };
+            const plane = node.plane;
+            if (!plane)
+                continue;
+            const f = [];
+            const b = [];
+            for (const p of list)
+                split(plane, p, coplanar, coplanar, f, b);
+            coplanar.length = 0;
+            if (f.length > 0) {
+                node.front ??= new Node();
+                work.push([node.front, f]);
+            }
+            if (b.length > 0) {
+                node.back ??= new Node();
+                work.push([node.back, b]);
+            }
+        }
+    }
+    /** Turn the tree inside out: every plane reversed, front and back swapped. */
+    invert() {
+        const stack = [this];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (!node)
+                break;
+            if (node.plane) {
+                node.plane = {
+                    nx: -node.plane.nx,
+                    ny: -node.plane.ny,
+                    nz: -node.plane.nz,
+                    w: -node.plane.w,
+                };
+            }
+            const f = node.front;
+            node.front = node.back;
+            node.back = f;
+            if (node.front)
+                stack.push(node.front);
+            if (node.back)
+                stack.push(node.back);
+        }
+        return this;
+    }
+    /** The parts of `polygons` outside this tree's solid. */
+    clipPolygons(polygons) {
+        if (!this.plane)
+            return polygons.slice();
+        let f = [];
+        let b = [];
+        for (const p of polygons)
+            split(this.plane, p, f, b, f, b);
+        if (this.front)
+            f = this.front.clipPolygons(f);
+        b = this.back ? this.back.clipPolygons(b) : [];
+        return f.concat(b);
+    }
+}
+function boundsOf(polygons) {
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    for (const p of polygons) {
+        for (const v of p.vertices) {
+            if (v.x < min[0])
+                min[0] = v.x;
+            if (v.y < min[1])
+                min[1] = v.y;
+            if (v.z < min[2])
+                min[2] = v.z;
+            if (v.x > max[0])
+                max[0] = v.x;
+            if (v.y > max[1])
+                max[1] = v.y;
+            if (v.z > max[2])
+                max[2] = v.z;
+        }
+    }
+    return { min, max };
+}
+/**
+ * `polygons` split into those that may meet `bounds` and those clear of it by more than the plane
+ * tolerance on some axis — which are outside the solid `bounds` encloses, with no tree to ask.
+ */
+function partition(polygons, bounds) {
+    const near = [];
+    const clear = [];
+    const { min, max } = bounds;
+    for (const p of polygons) {
+        let lx = Infinity;
+        let ly = Infinity;
+        let lz = Infinity;
+        let hx = -Infinity;
+        let hy = -Infinity;
+        let hz = -Infinity;
+        for (const v of p.vertices) {
+            lx = Math.min(lx, v.x);
+            ly = Math.min(ly, v.y);
+            lz = Math.min(lz, v.z);
+            hx = Math.max(hx, v.x);
+            hy = Math.max(hy, v.y);
+            hz = Math.max(hz, v.z);
+        }
+        const apart = hx < min[0] - EPSILON ||
+            hy < min[1] - EPSILON ||
+            hz < min[2] - EPSILON ||
+            lx > max[0] + EPSILON ||
+            ly > max[1] + EPSILON ||
+            lz > max[2] + EPSILON;
+        (apart ? clear : near).push(p);
+    }
+    return [near, clear];
+}
+const flipAll = (polygons) => polygons.map(flipPolygon);
+function toPolygons(solid) {
+    const out = [];
+    const p = solid.positions;
+    const n = solid.normals;
+    const uv = solid.uvs;
+    const vertex = (i) => ({
+        x: p[i * 3] ?? 0,
+        y: p[i * 3 + 1] ?? 0,
+        z: p[i * 3 + 2] ?? 0,
+        nx: n[i * 3] ?? 0,
+        ny: n[i * 3 + 1] ?? 0,
+        nz: n[i * 3 + 2] ?? 0,
+        u: uv[i * 2] ?? 0,
+        v: uv[i * 2 + 1] ?? 0,
+    });
+    for (let t = 0; t < solid.indices.length; t += 3) {
+        const a = vertex(solid.indices[t] ?? 0);
+        const b = vertex(solid.indices[t + 1] ?? 0);
+        const c = vertex(solid.indices[t + 2] ?? 0);
+        const plane = planeFrom(a, b, c);
+        if (plane)
+            out.push({ vertices: [a, b, c], plane });
+    }
+    return out;
+}
+/** Polygons back to a solid, each fanned from its first corner — they are convex. */
+function fromPolygons(polygons) {
+    const out = new SolidWriter();
+    for (const polygon of polygons) {
+        const base = out.vertexCount;
+        for (const v of polygon.vertices)
+            out.vertex(v.x, v.y, v.z, v.nx, v.ny, v.nz, v.u, v.v);
+        for (let i = 1; i + 1 < polygon.vertices.length; i++)
+            out.triangle(base, base + i, base + i + 1);
+    }
+    return out.finish();
+}
+function tree(polygons) {
+    const node = new Node();
+    node.build(polygons);
+    return node;
+}
+const isEmpty = (s) => s.indices.length === 0;
+/**
+ * Both operands' polygons, each split by the other's bounds. The three operations below are the
+ * published method's steps written over these lists, with the clear polygons settled by the rule
+ * each operation applies to everything outside the other operand.
+ */
+function operands(a, b) {
+    const pa = toPolygons(a);
+    const pb = toPolygons(b);
+    const [aNear, aClear] = partition(pa, boundsOf(pb));
+    const [bNear, bClear] = partition(pb, boundsOf(pa));
+    return { pa, pb, aNear, aClear, bNear, bClear };
+}
+/** Everything inside either solid. */
+export function solidUnion(a, b) {
+    if (isEmpty(b))
+        return a;
+    if (isEmpty(a))
+        return b;
+    const { pa, pb, aNear, aClear, bNear, bClear } = operands(a, b);
+    const ta = tree(pa);
+    const aKept = tree(pb).clipPolygons(aNear);
+    /* B outside A, then without the faces lying on A's facing the same way, which A already has. */
+    const bKept = flipAll(ta.clipPolygons(flipAll(ta.clipPolygons(bNear))));
+    return fromPolygons([...aClear, ...aKept, ...bClear, ...bKept]);
+}
+/** Everything inside `a` and outside `b`. */
+export function solidSubtract(a, b) {
+    if (isEmpty(a))
+        return emptySolid();
+    if (isEmpty(b))
+        return a;
+    const { pa, pb, aNear, aClear, bNear } = operands(a, b);
+    const outside = tree(pa).invert();
+    const aKept = flipAll(tree(pb).clipPolygons(flipAll(aNear)));
+    /* B inside A, turned to face into the cavity it leaves. */
+    const bKept = outside.clipPolygons(flipAll(outside.clipPolygons(bNear)));
+    return fromPolygons([...aClear, ...aKept, ...bKept]);
+}
+/** Everything inside both solids. */
+export function solidIntersect(a, b) {
+    if (isEmpty(a) || isEmpty(b))
+        return emptySolid();
+    const { pa, pb, aNear, bNear } = operands(a, b);
+    const outsideA = tree(pa).invert();
+    const outsideB = tree(pb).invert();
+    const aKept = flipAll(outsideB.clipPolygons(flipAll(aNear)));
+    const bKept = flipAll(outsideA.clipPolygons(flipAll(outsideA.clipPolygons(bNear))));
+    return fromPolygons([...aKept, ...bKept]);
+}

package/dist/geometry/meshBuilder.js

@@ -109,6 +109,7 @@ export class MeshBuilder {
      * inverse transpose, and nothing here has wanted that yet.
      */
     addMesh(mesh, x, y, z, scale = 1) {
+        refuseLayers(mesh);
         const base = this.vertexCount;
         const count = mesh.positions.length / 3;
         for (let i = 0; i < count; i++) {
@@ -157,6 +158,7 @@ export class MeshBuilder {
      * @param scale uniform, applied in the local frame before the basis.
      */
     addOrientedMesh(mesh, origin, right, up, forward, scale = 1) {
+        refuseLayers(mesh);
         assertOrthonormal(right, up, forward);
         const base = this.vertexCount;
         const count = mesh.positions.length / 3;
@@ -1186,3 +1188,14 @@ const CORNERS = [
     [1, 1],
     [-1, 1],
 ];
+/**
+ * A builder has no layer channel, so merging a layered mesh would keep its texture coordinates and
+ * silently put every face on layer 0 — the first image of the array, which reads as the wrong
+ * facade everywhere rather than as an error. Refused instead; `concatMeshes` joins layered meshes.
+ */
+function refuseLayers(mesh) {
+    if (mesh.layers === undefined)
+        return;
+    throw new Error('MeshBuilder: this mesh names texture-array layers, which a builder does not carry — merging ' +
+        'it here would put every face on layer 0. Join layered meshes with concatMeshes instead.');
+}

package/dist/geometry/meshConcat.js

@@ -26,6 +26,7 @@ const OPTIONAL = [
     ['channel', 4],
     ['joints', 4],
     ['weights', 4],
+    ['layers', 1],
 ];
 /**
  * `mesh` scaled uniformly and then moved by `x, y, z`. The same object when the fit is the

package/dist/geometry/pixelFont.js

@@ -66,6 +66,8 @@ const GLYPHS = {
     "'": [0b00100, 0b00100, 0, 0, 0, 0, 0],
     '(': [0b00010, 0b00100, 0b01000, 0b01000, 0b01000, 0b00100, 0b00010],
     ')': [0b01000, 0b00100, 0b00010, 0b00010, 0b00010, 0b00100, 0b01000],
+    '[': [0b01110, 0b01000, 0b01000, 0b01000, 0b01000, 0b01000, 0b01110],
+    ']': [0b01110, 0b00010, 0b00010, 0b00010, 0b00010, 0b00010, 0b01110],
     '%': [0b11001, 0b11010, 0b00010, 0b00100, 0b01000, 0b01011, 0b10011],
     '·': [0, 0, 0, 0b01100, 0b01100, 0, 0],
     '×': [0, 0b10001, 0b01010, 0b00100, 0b01010, 0b10001, 0],