@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/geom/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `@thunderclap-engine/engine/geom`: primitive geometry (box, plane, sphere, icosphere, capsule,
+ * cylinder, torus) in the engine's 3D vertex layout with bounds, merge and transform helpers,
+ * heightfields with bilinear sampling, normals, an exact ray test and a mesh builder, shapes
+ * swept from 2D profiles (extrude, lathe, sweep, tube, polygon, stairs, arch), tangent frames
+ * and per-geometry operations (flat shading, welding, uv projection, fitting).
+ * Pure arithmetic: no GPU, no DOM; `render/` supplies only the layouts and their types.
+ */
+export type { Box2, Capsule, Circle, ColliderBounds, ColliderSource, ColliderTransform, Contact, GeomAabb, GeometryMeshSource, GeometrySource, GridSource, HeightfieldSource, PositionsSource, RayHit, Shape, Shape2, SlideOptions, SlideResult, SourceKind, SourceRecord, Sphere, StaticColliderOptions, SweepHit, TileBox, TileGridSource, TileKind, TileMover, TileQuery, TileSlideOptions, TileSlideResult, Vec3Out, WireframeMode, } from './collide/index.js';
+export { ALL_LAYERS, aabbTriangle, applyTransform, capsuleTriangle, carryBy, closestPointTriangle, closestSegmentSegment, closestSegmentTriangle, colliderTriangle, colliderWireframe, colliderWireframeLength, createContact, createHit, createSlideResult, createStaticCollider, createSweepHit, createTileSlideResult, exportCollider, gridSolid, gridTriangles, importCollider, isAabb, isBox2, isCapsule, overlap, overlap2, raycast, raycast2, raycastReg, SOURCE_GEOMETRY, SOURCE_GRID, SOURCE_HEIGHTFIELD, StaticCollider, shapeBounds, shapeTriangle, slide, slide2, slideTiles, sphereTriangle, sweep as sweepShape, sweep2, TILE_EMPTY, TILE_ONE_WAY, TILE_SOLID, triangleNormal, } from './collide/index.js';
+export type { Geometry, GeometryOptions, Rgba } from './geometry.js';
+export { cloneGeometry, computeBounds, createIndices, GEOMETRY_FLOATS, GeometryWriter, mergeGeometry, transformGeometry, UINT16_MAX_VERTICES, } from './geometry.js';
+export type { Heightfield, HeightfieldGeometryOptions, HeightfieldOptions, HeightfieldRay, HeightfieldVec3, } from './heightfield.js';
+export { createHeightfield, heightAt, heightfieldGeometry, normalAt, raycastHeightfield, rayHeightfield, } from './heightfield.js';
+export type { CollisionProxyOptions } from './hull.js';
+export { collisionProxy, convexHull } from './hull.js';
+export type { Iso, IsoHeightAt, IsoOptions, IsoPoint } from './iso.js';
+export { createIso, ISO_ELEV_DEPTH, isoHiddenBy, isoInverseProbe } from './iso.js';
+export type { LodChain } from './lod.js';
+export { projectedSizePx, selectLod } from './lod.js';
+export type { ProjectUvOptions, UvProjection } from './ops.js';
+export { fitBounds, flatShade, flipWinding, projectUv, recenter, weld } from './ops.js';
+export type { BoxOptions, CapsuleOptions, CylinderOptions, IcosphereOptions, PlaneOptions, SphereOptions, TorusOptions, } from './primitives.js';
+export { box, capsule, cylinder, icosphere, plane, sphere, torus } from './primitives.js';
+export type { ArchOptions, StairsOptions } from './shapes.js';
+export { arch, stairs } from './shapes.js';
+export type { SimplifyOptions, SimplifyResult } from './simplify.js';
+export { createLodChain, simplifyGeometry } from './simplify.js';
+export type { SliceOptions, SlicePlane, SliceResult } from './split.js';
+export { sliceGeometry, splitGeometry } from './split.js';
+export type { ExtrudeOptions, LatheOptions, PolygonOptions, Profile2D, SweepOptions, TubeOptions, } from './sweep.js';
+export { extrude, lathe, polygon, sweep, tube } from './sweep.js';
+export type { GeometryTangent } from './tangents.js';
+export { computeTangents, TANGENT_FLOATS } from './tangents.js';
+export { profileArea2, triangulate } from './triangulate.js';

package/dist/geom/index.js

@@ -0,0 +1,23 @@
+/**
+ * `@thunderclap-engine/engine/geom`: primitive geometry (box, plane, sphere, icosphere, capsule,
+ * cylinder, torus) in the engine's 3D vertex layout with bounds, merge and transform helpers,
+ * heightfields with bilinear sampling, normals, an exact ray test and a mesh builder, shapes
+ * swept from 2D profiles (extrude, lathe, sweep, tube, polygon, stairs, arch), tangent frames
+ * and per-geometry operations (flat shading, welding, uv projection, fitting).
+ * Pure arithmetic: no GPU, no DOM; `render/` supplies only the layouts and their types.
+ */
+// Collision (ws/collide). The profile `sweep` above keeps its name: the shape sweep is `sweepShape`.
+export { ALL_LAYERS, aabbTriangle, applyTransform, capsuleTriangle, carryBy, closestPointTriangle, closestSegmentSegment, closestSegmentTriangle, colliderTriangle, colliderWireframe, colliderWireframeLength, createContact, createHit, createSlideResult, createStaticCollider, createSweepHit, createTileSlideResult, exportCollider, gridSolid, gridTriangles, importCollider, isAabb, isBox2, isCapsule, overlap, overlap2, raycast, raycast2, raycastReg, SOURCE_GEOMETRY, SOURCE_GRID, SOURCE_HEIGHTFIELD, StaticCollider, shapeBounds, shapeTriangle, slide, slide2, slideTiles, sphereTriangle, sweep as sweepShape, sweep2, TILE_EMPTY, TILE_ONE_WAY, TILE_SOLID, triangleNormal, } from './collide/index.js';
+export { cloneGeometry, computeBounds, createIndices, GEOMETRY_FLOATS, GeometryWriter, mergeGeometry, transformGeometry, UINT16_MAX_VERTICES, } from './geometry.js';
+export { createHeightfield, heightAt, heightfieldGeometry, normalAt, raycastHeightfield, rayHeightfield, } from './heightfield.js';
+export { collisionProxy, convexHull } from './hull.js';
+export { createIso, ISO_ELEV_DEPTH, isoHiddenBy, isoInverseProbe } from './iso.js';
+export { projectedSizePx, selectLod } from './lod.js';
+export { fitBounds, flatShade, flipWinding, projectUv, recenter, weld } from './ops.js';
+export { box, capsule, cylinder, icosphere, plane, sphere, torus } from './primitives.js';
+export { arch, stairs } from './shapes.js';
+export { createLodChain, simplifyGeometry } from './simplify.js';
+export { sliceGeometry, splitGeometry } from './split.js';
+export { extrude, lathe, polygon, sweep, tube } from './sweep.js';
+export { computeTangents, TANGENT_FLOATS } from './tangents.js';
+export { profileArea2, triangulate } from './triangulate.js';

package/dist/geom/iso.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Isometric (2:1 diamond) projection and its inverse (ws/ergo-2d-2): the maths every
+ * isometric game rewrote. Tile space `(tx, ty)` is a square grid turned 45° and squashed to
+ * `tileW × tileH` diamonds; elevation `elev` lifts a tile `elevH × elev` px up the screen.
+ *
+ *   x = originX + (tx - ty) × tileW / 2
+ *   y = originY + (tx + ty) × tileH / 2 - elev × elevH
+ *
+ * Pure arithmetic in the caller's 2D space (a layer's logical px, a camera's world px): no
+ * camera, no map, no allocation (`out` params). `isoInverseProbe` is the pointer-to-tile rule
+ * a tactics map needs (the highest elevation whose tile really is that tall wins) and
+ * `isoHiddenBy` tells when a tile's top disappears behind a taller front neighbour.
+ */
+export interface IsoOptions {
+    /** Diamond width and height in px (2:1 is the classic; any ratio works). */
+    tileW: number;
+    tileH: number;
+    /** Px one elevation step lifts a tile. Default `tileH / 2`. */
+    elevH?: number;
+    /** Position of tile `(0, 0)`'s diamond centre at elevation 0. Default `(0, 0)`. */
+    originX?: number;
+    originY?: number;
+}
+/** A point `toScreen` / `toTile` fill: any `{ x, y }` (a `CameraPoint`, a `Vec2`). */
+export interface IsoPoint {
+    x: number;
+    y: number;
+}
+/** Tile heights for `isoInverseProbe` and `isoHiddenBy`: off the map, return a negative number. */
+export type IsoHeightAt = (tx: number, ty: number) => number;
+/**
+ * Depth weight of one elevation step in `Iso.depth`: a tile's key is `tx + ty + elev × this`,
+ * so elevations under 256 never cross into the next diagonal.
+ */
+export declare const ISO_ELEV_DEPTH: number;
+export interface Iso {
+    readonly tileW: number;
+    readonly tileH: number;
+    readonly elevH: number;
+    /** Tile `(0, 0)`'s diamond centre at elevation 0. Mutate in place to move the whole lattice. */
+    originX: number;
+    originY: number;
+    /** Diamond centre of tile `(tx, ty)` (fractional allowed) at `elev`, into `out`. */
+    toScreen(tx: number, ty: number, elev: number, out: IsoPoint): IsoPoint;
+    /**
+     * Fractional tile coordinates of screen point `(sx, sy)` assuming the ground there is at
+     * `elev`, into `out`. Tile centres are integers: round to pick the tile.
+     */
+    toTile(sx: number, sy: number, elev: number, out: IsoPoint): IsoPoint;
+    /**
+     * Painter's-order key: back to front along `tx + ty`, then `elev × ISO_ELEV_DEPTH`. Equal
+     * for the tiles of one diagonal, which never overlap on screen.
+     */
+    depth(tx: number, ty: number, elev: number): number;
+}
+/** Make an `Iso`. Allocates the object once; everything on it is allocation-free. */
+export declare function createIso(opts: IsoOptions): Iso;
+/**
+ * The tile under screen point `(sx, sy)` on a map with elevation: tries every elevation from
+ * `maxElev` down to 0 and keeps the first tile whose `heightAt` is that elevation, so a pointer
+ * over a raised tile's top lands on it and not on the flat tile the same pixel would cover at
+ * ground level. Writes the tile into `out` and returns true; writes `(-1, -1)` and returns
+ * false when no tile matches (off the map, or over a riser between levels).
+ */
+export declare function isoInverseProbe(iso: Iso, sx: number, sy: number, heightAt: IsoHeightAt, maxElev: number, out: IsoPoint): boolean;
+/**
+ * True when the whole top of tile `(tx, ty)` (at `heightAt(tx, ty)`) is covered by taller front
+ * neighbours: a column (top diamond plus the wall down to the ground) whose top is at least
+ * `tileH` px above ours covers our half of the diamond on its side, so the diagonal front
+ * neighbour `(tx + 1, ty + 1)` hides the top alone and `(tx + 1, ty)` with `(tx, ty + 1)` hide
+ * it together. With the default `elevH` that is two elevation steps; one step covers the lower
+ * quarter and leaves the top visible. Off-map neighbours (negative height) hide nothing.
+ */
+export declare function isoHiddenBy(iso: Iso, tx: number, ty: number, heightAt: IsoHeightAt): boolean;

package/dist/geom/iso.js

@@ -0,0 +1,89 @@
+/**
+ * Isometric (2:1 diamond) projection and its inverse (ws/ergo-2d-2): the maths every
+ * isometric game rewrote. Tile space `(tx, ty)` is a square grid turned 45° and squashed to
+ * `tileW × tileH` diamonds; elevation `elev` lifts a tile `elevH × elev` px up the screen.
+ *
+ *   x = originX + (tx - ty) × tileW / 2
+ *   y = originY + (tx + ty) × tileH / 2 - elev × elevH
+ *
+ * Pure arithmetic in the caller's 2D space (a layer's logical px, a camera's world px): no
+ * camera, no map, no allocation (`out` params). `isoInverseProbe` is the pointer-to-tile rule
+ * a tactics map needs (the highest elevation whose tile really is that tall wins) and
+ * `isoHiddenBy` tells when a tile's top disappears behind a taller front neighbour.
+ */
+/**
+ * Depth weight of one elevation step in `Iso.depth`: a tile's key is `tx + ty + elev × this`,
+ * so elevations under 256 never cross into the next diagonal.
+ */
+export const ISO_ELEV_DEPTH = 1 / 256;
+/** Make an `Iso`. Allocates the object once; everything on it is allocation-free. */
+export function createIso(opts) {
+    const { tileW, tileH } = opts;
+    if (!(tileW > 0 && tileH > 0))
+        throw new Error('createIso: tileW and tileH must be > 0');
+    const elevH = opts.elevH ?? tileH / 2;
+    const hw = tileW / 2;
+    const hh = tileH / 2;
+    const iso = {
+        tileW,
+        tileH,
+        elevH,
+        originX: opts.originX ?? 0,
+        originY: opts.originY ?? 0,
+        toScreen(tx, ty, elev, out) {
+            out.x = iso.originX + (tx - ty) * hw;
+            out.y = iso.originY + (tx + ty) * hh - elev * elevH;
+            return out;
+        },
+        toTile(sx, sy, elev, out) {
+            const a = (sx - iso.originX) / hw;
+            const b = (sy - iso.originY + elev * elevH) / hh;
+            out.x = (a + b) / 2;
+            out.y = (b - a) / 2;
+            return out;
+        },
+        depth(tx, ty, elev) {
+            return tx + ty + elev * ISO_ELEV_DEPTH;
+        },
+    };
+    return iso;
+}
+/**
+ * The tile under screen point `(sx, sy)` on a map with elevation: tries every elevation from
+ * `maxElev` down to 0 and keeps the first tile whose `heightAt` is that elevation, so a pointer
+ * over a raised tile's top lands on it and not on the flat tile the same pixel would cover at
+ * ground level. Writes the tile into `out` and returns true; writes `(-1, -1)` and returns
+ * false when no tile matches (off the map, or over a riser between levels).
+ */
+export function isoInverseProbe(iso, sx, sy, heightAt, maxElev, out) {
+    for (let e = Math.floor(maxElev); e >= 0; e--) {
+        iso.toTile(sx, sy, e, out);
+        const tx = Math.floor(out.x + 0.5);
+        const ty = Math.floor(out.y + 0.5);
+        if (heightAt(tx, ty) === e) {
+            out.x = tx;
+            out.y = ty;
+            return true;
+        }
+    }
+    out.x = -1;
+    out.y = -1;
+    return false;
+}
+/**
+ * True when the whole top of tile `(tx, ty)` (at `heightAt(tx, ty)`) is covered by taller front
+ * neighbours: a column (top diamond plus the wall down to the ground) whose top is at least
+ * `tileH` px above ours covers our half of the diamond on its side, so the diagonal front
+ * neighbour `(tx + 1, ty + 1)` hides the top alone and `(tx + 1, ty)` with `(tx, ty + 1)` hide
+ * it together. With the default `elevH` that is two elevation steps; one step covers the lower
+ * quarter and leaves the top visible. Off-map neighbours (negative height) hide nothing.
+ */
+export function isoHiddenBy(iso, tx, ty, heightAt) {
+    const e = heightAt(tx, ty);
+    if (e < 0)
+        return false;
+    const lift = iso.tileH / iso.elevH;
+    if (heightAt(tx + 1, ty + 1) - e >= lift)
+        return true;
+    return heightAt(tx + 1, ty) - e >= lift && heightAt(tx, ty + 1) - e >= lift;
+}

package/dist/geom/lod.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Level-of-detail picking: which entry of a LOD chain to draw for an object at a distance, by
+ * the height its bounding sphere covers on screen. Pure arithmetic, no allocation.
+ */
+import type { Geometry } from './geometry.js';
+/**
+ * A LOD chain: `geometries[0]` is the full mesh and each later entry coarser (`createLodChain`
+ * builds one); `meshes` the GPU meshes made from them, parallel, when the caller keeps them
+ * here; `thresholdsPx[i]` the smallest on-screen height, in pixels, at which level `i` still
+ * draws (descending; a missing entry means level `i` only draws as the last level).
+ */
+export interface LodChain<M = unknown> {
+    geometries: readonly Geometry[];
+    meshes?: readonly M[];
+    thresholdsPx: readonly number[];
+}
+/**
+ * Pixels a bounding sphere of `boundsRadius` covers vertically at `distance` from a perspective
+ * camera with vertical field of view `fovY` (radians) drawing `viewportHeight` pixels: its
+ * diameter over the view height at that distance. A distance of 0 or less is `Infinity`.
+ */
+export declare function projectedSizePx(boundsRadius: number, distance: number, fovY: number, viewportHeight: number): number;
+/**
+ * The level to draw: the first `i` whose `thresholdsPx[i]` the projected size reaches
+ * (`>=`, so a size exactly on a threshold takes that level), else the last level. `chain` is the
+ * level list (only its length is read: a chain's `geometries` or `meshes`) or the level count.
+ * Clamped to `0 .. count - 1`; a count below 1 returns 0.
+ */
+export declare function selectLod(chain: readonly unknown[] | number, boundsRadius: number, distance: number, fovY: number, viewportHeight: number, thresholdsPx: readonly number[]): number;

package/dist/geom/lod.js

@@ -0,0 +1,27 @@
+/**
+ * Pixels a bounding sphere of `boundsRadius` covers vertically at `distance` from a perspective
+ * camera with vertical field of view `fovY` (radians) drawing `viewportHeight` pixels: its
+ * diameter over the view height at that distance. A distance of 0 or less is `Infinity`.
+ */
+export function projectedSizePx(boundsRadius, distance, fovY, viewportHeight) {
+    if (!(distance > 0))
+        return Number.POSITIVE_INFINITY;
+    return (boundsRadius * viewportHeight) / (distance * Math.tan(fovY * 0.5));
+}
+/**
+ * The level to draw: the first `i` whose `thresholdsPx[i]` the projected size reaches
+ * (`>=`, so a size exactly on a threshold takes that level), else the last level. `chain` is the
+ * level list (only its length is read: a chain's `geometries` or `meshes`) or the level count.
+ * Clamped to `0 .. count - 1`; a count below 1 returns 0.
+ */
+export function selectLod(chain, boundsRadius, distance, fovY, viewportHeight, thresholdsPx) {
+    const count = typeof chain === 'number' ? chain : chain.length;
+    const last = Math.max(0, count - 1);
+    const px = projectedSizePx(boundsRadius, distance, fovY, viewportHeight);
+    const n = Math.min(last, thresholdsPx.length);
+    for (let i = 0; i < n; i++) {
+        if (px >= thresholdsPx[i])
+            return i;
+    }
+    return last;
+}

package/dist/geom/ops.d.ts

@@ -0,0 +1,47 @@
+import { type Geometry } from './geometry.js';
+/**
+ * Unshare every vertex: one vertex per triangle corner (`indices.length` of them, indices
+ * `0..n-1`), each carrying its triangle's geometric normal; the other attributes are copied from
+ * the source corner. A degenerate triangle keeps its source normals. New geometry, same layout.
+ */
+export declare function flatShade(g: Geometry): Geometry;
+/**
+ * Merge vertices whose position, normal and uv each lie within `epsilon` (per component) of an
+ * earlier vertex's: a spatial hash over positions finds candidates, the first occurrence is kept,
+ * indices are remapped and shrink to 16-bit when the result fits. Vertex order is otherwise
+ * preserved; colour and tangent are taken from the kept vertex. New geometry, same layout.
+ */
+export declare function weld(g: Geometry, epsilon?: number): Geometry;
+/**
+ * Turn the geometry inside out: every triangle's winding is reversed and every normal negated
+ * (and, in the tangent layout, the handedness, so the bitangent keeps its direction). Bounds are
+ * unchanged. Mutates and returns `g`.
+ */
+export declare function flipWinding(g: Geometry): Geometry;
+/** How `projectUv` maps positions to uvs. */
+export type UvProjection = 'box' | 'planar' | 'cylindrical' | 'spherical';
+export interface ProjectUvOptions {
+    /** Multiplies the projected uvs (one number or `[u, v]`). Default 1: 0..1 across the box. */
+    scale?: number | [number, number];
+    /** `'planar'` only: the axis the plane faces. Default `'y'` (u along x, v along z). */
+    axis?: 'x' | 'y' | 'z';
+}
+/**
+ * Overwrite the uvs from the positions, relative to the geometry's axis-aligned box so each
+ * coordinate spans 0..1 before `scale`:
+ * - `'box'`: each vertex takes the plane facing its normal's dominant axis (x: u = z, v = y;
+ *   y: u = x, v = z; z: u = x, v = y), so a box or a building block tiles on every face;
+ * - `'planar'`: one plane for all vertices, facing `axis`;
+ * - `'cylindrical'`: u is the angle around +y (0 at +z, as `cylinder`), v the height;
+ * - `'spherical'`: u the angle around +y, v the latitude from the box centre (0 at the top).
+ * Mutates and returns `g`.
+ */
+export declare function projectUv(g: Geometry, mode: UvProjection, opts?: ProjectUvOptions): Geometry;
+/**
+ * Scale uniformly about the origin so the longest side of the axis-aligned box equals `size`.
+ * Normals are unchanged (a uniform scale keeps them); bounds are recomputed. An empty or
+ * zero-extent geometry is left as it is. Mutates and returns `g`.
+ */
+export declare function fitBounds(g: Geometry, size: number): Geometry;
+/** Translate so the centre of the axis-aligned box is the origin. Mutates and returns `g`. */
+export declare function recenter(g: Geometry): Geometry;

package/dist/geom/ops.js

@@ -0,0 +1,285 @@
+/**
+ * Per-geometry operations a level builder reaches for: `flatShade`, `weld`, `flipWinding`,
+ * `projectUv`, `fitBounds`, `recenter`. They read the 3D prefix every supported layout shares
+ * (position at float 0, normal at 3, uv at 6) and step by `layout.floats`, so they take
+ * `VERTEX_LAYOUT_3D` and `VERTEX_LAYOUT_3D_TANGENT` geometry alike. `flipWinding`, `projectUv`,
+ * `fitBounds` and `recenter` mutate and return their input; `flatShade` and `weld` return a new
+ * geometry (their vertex counts change).
+ */
+import { VERTEX_LAYOUT_3D, VERTEX_LAYOUT_3D_TANGENT } from '../render/mesh.js';
+import { computeBounds, createIndices } from './geometry.js';
+const TAU = Math.PI * 2;
+function floatsOf(g, what) {
+    if (g.layout !== VERTEX_LAYOUT_3D && g.layout !== VERTEX_LAYOUT_3D_TANGENT) {
+        throw new Error(`geom: ${what} needs a 3D vertex layout, got '${g.layout.name}'`);
+    }
+    return g.layout.floats;
+}
+/** Axis-aligned box of the positions: `[minX, minY, minZ, maxX, maxY, maxZ]` (zeros when empty). */
+function aabb(v, F, out) {
+    if (v.length === 0) {
+        out.fill(0);
+        return out;
+    }
+    out[0] = out[1] = out[2] = Number.POSITIVE_INFINITY;
+    out[3] = out[4] = out[5] = Number.NEGATIVE_INFINITY;
+    for (let o = 0; o < v.length; o += F) {
+        for (let k = 0; k < 3; k++) {
+            const c = v[o + k];
+            if (c < out[k])
+                out[k] = c;
+            if (c > out[3 + k])
+                out[3 + k] = c;
+        }
+    }
+    return out;
+}
+// ------------------------------------------------------------------ flatShade
+/**
+ * Unshare every vertex: one vertex per triangle corner (`indices.length` of them, indices
+ * `0..n-1`), each carrying its triangle's geometric normal; the other attributes are copied from
+ * the source corner. A degenerate triangle keeps its source normals. New geometry, same layout.
+ */
+export function flatShade(g) {
+    const F = floatsOf(g, 'flatShade');
+    const src = g.vertices;
+    const idx = g.indices;
+    const count = idx.length;
+    const out = new Float32Array(count * F);
+    const indices = createIndices(count, count);
+    for (let t = 0; t < count; t += 3) {
+        const a = idx[t] * F;
+        const b = idx[t + 1] * F;
+        const c = idx[t + 2] * F;
+        const abx = src[b] - src[a];
+        const aby = src[b + 1] - src[a + 1];
+        const abz = src[b + 2] - src[a + 2];
+        const acx = src[c] - src[a];
+        const acy = src[c + 1] - src[a + 1];
+        const acz = src[c + 2] - src[a + 2];
+        let nx = aby * acz - abz * acy;
+        let ny = abz * acx - abx * acz;
+        let nz = abx * acy - aby * acx;
+        const len = Math.hypot(nx, ny, nz);
+        const flat = len > 1e-20;
+        if (flat) {
+            nx /= len;
+            ny /= len;
+            nz /= len;
+        }
+        for (let k = 0; k < 3; k++) {
+            const s = idx[t + k] * F;
+            const o = (t + k) * F;
+            out.set(src.subarray(s, s + F), o);
+            if (flat) {
+                out[o + 3] = nx;
+                out[o + 4] = ny;
+                out[o + 5] = nz;
+            }
+            indices[t + k] = t + k;
+        }
+    }
+    return { vertices: out, indices, bounds: computeBounds(out, F), layout: g.layout };
+}
+// ------------------------------------------------------------------ weld
+/**
+ * Merge vertices whose position, normal and uv each lie within `epsilon` (per component) of an
+ * earlier vertex's: a spatial hash over positions finds candidates, the first occurrence is kept,
+ * indices are remapped and shrink to 16-bit when the result fits. Vertex order is otherwise
+ * preserved; colour and tangent are taken from the kept vertex. New geometry, same layout.
+ */
+export function weld(g, epsilon = 1e-5) {
+    const F = floatsOf(g, 'weld');
+    const src = g.vertices;
+    const n = src.length / F;
+    const inv = 1 / epsilon;
+    const cells = new Map();
+    const remap = new Uint32Array(n);
+    const keep = new Uint32Array(n);
+    let kept = 0;
+    const key = (cx, cy, cz) => 
+    // Three 21-bit cell coordinates folded into one double (exact below 2^53).
+    ((cx & 0x1fffff) * 2097152 + (cy & 0x1fffff)) * 2097152 + (cz & 0x1fffff);
+    const same = (a, b) => {
+        for (let k = 0; k < 8; k++)
+            if (Math.abs(src[a + k] - src[b + k]) > epsilon)
+                return false;
+        return true;
+    };
+    for (let i = 0; i < n; i++) {
+        const o = i * F;
+        const cx = Math.round(src[o] * inv);
+        const cy = Math.round(src[o + 1] * inv);
+        const cz = Math.round(src[o + 2] * inv);
+        let found = -1;
+        search: for (let dx = -1; dx <= 1; dx++) {
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dz = -1; dz <= 1; dz++) {
+                    const bucket = cells.get(key(cx + dx, cy + dy, cz + dz));
+                    if (!bucket)
+                        continue;
+                    for (const j of bucket) {
+                        if (same(o, j * F)) {
+                            found = j;
+                            break search;
+                        }
+                    }
+                }
+            }
+        }
+        if (found >= 0) {
+            remap[i] = remap[found];
+            continue;
+        }
+        remap[i] = kept;
+        keep[kept++] = i;
+        const k = key(cx, cy, cz);
+        const bucket = cells.get(k);
+        if (bucket)
+            bucket.push(i);
+        else
+            cells.set(k, [i]);
+    }
+    const vertices = new Float32Array(kept * F);
+    for (let i = 0; i < kept; i++) {
+        const s = keep[i] * F;
+        vertices.set(src.subarray(s, s + F), i * F);
+    }
+    const indices = createIndices(kept, g.indices.length);
+    for (let t = 0; t < g.indices.length; t++)
+        indices[t] = remap[g.indices[t]];
+    return { vertices, indices, bounds: computeBounds(vertices, F), layout: g.layout };
+}
+// ------------------------------------------------------------------ flipWinding
+/**
+ * Turn the geometry inside out: every triangle's winding is reversed and every normal negated
+ * (and, in the tangent layout, the handedness, so the bitangent keeps its direction). Bounds are
+ * unchanged. Mutates and returns `g`.
+ */
+export function flipWinding(g) {
+    const F = floatsOf(g, 'flipWinding');
+    const idx = g.indices;
+    for (let t = 0; t + 2 < idx.length; t += 3) {
+        const b = idx[t + 1];
+        idx[t + 1] = idx[t + 2];
+        idx[t + 2] = b;
+    }
+    const v = g.vertices;
+    const tangent = F >= 16;
+    for (let o = 0; o < v.length; o += F) {
+        v[o + 3] = -v[o + 3];
+        v[o + 4] = -v[o + 4];
+        v[o + 5] = -v[o + 5];
+        if (tangent)
+            v[o + 15] = -v[o + 15];
+    }
+    return g;
+}
+/**
+ * Overwrite the uvs from the positions, relative to the geometry's axis-aligned box so each
+ * coordinate spans 0..1 before `scale`:
+ * - `'box'`: each vertex takes the plane facing its normal's dominant axis (x: u = z, v = y;
+ *   y: u = x, v = z; z: u = x, v = y), so a box or a building block tiles on every face;
+ * - `'planar'`: one plane for all vertices, facing `axis`;
+ * - `'cylindrical'`: u is the angle around +y (0 at +z, as `cylinder`), v the height;
+ * - `'spherical'`: u the angle around +y, v the latitude from the box centre (0 at the top).
+ * Mutates and returns `g`.
+ */
+export function projectUv(g, mode, opts = {}) {
+    const F = floatsOf(g, 'projectUv');
+    const v = g.vertices;
+    const box = aabb(v, F, AABB);
+    const sx = box[3] - box[0] || 1;
+    const sy = box[4] - box[1] || 1;
+    const sz = box[5] - box[2] || 1;
+    const cx = (box[0] + box[3]) / 2;
+    const cy = (box[1] + box[4]) / 2;
+    const cz = (box[2] + box[5]) / 2;
+    const s = opts.scale ?? 1;
+    const su = typeof s === 'number' ? s : s[0];
+    const sv = typeof s === 'number' ? s : s[1];
+    const planarAxis = opts.axis ?? 'y';
+    for (let o = 0; o < v.length; o += F) {
+        const x = (v[o] - box[0]) / sx;
+        const y = (v[o + 1] - box[1]) / sy;
+        const z = (v[o + 2] - box[2]) / sz;
+        let u;
+        let w;
+        if (mode === 'box' || mode === 'planar') {
+            let axis = planarAxis;
+            if (mode === 'box') {
+                const ax = Math.abs(v[o + 3]);
+                const ay = Math.abs(v[o + 4]);
+                const az = Math.abs(v[o + 5]);
+                axis = ax >= ay && ax >= az ? 'x' : ay >= az ? 'y' : 'z';
+            }
+            if (axis === 'x') {
+                u = z;
+                w = y;
+            }
+            else if (axis === 'y') {
+                u = x;
+                w = z;
+            }
+            else {
+                u = x;
+                w = y;
+            }
+        }
+        else {
+            const dx = v[o] - cx;
+            const dz = v[o + 2] - cz;
+            u = 0.5 + Math.atan2(dx, dz) / TAU;
+            if (mode === 'cylindrical') {
+                w = 1 - y;
+            }
+            else {
+                const dy = v[o + 1] - cy;
+                const len = Math.hypot(dx, dy, dz);
+                w = len > 0 ? Math.acos(Math.max(-1, Math.min(1, dy / len))) / Math.PI : 0;
+            }
+        }
+        v[o + 6] = u * su;
+        v[o + 7] = w * sv;
+    }
+    return g;
+}
+const AABB = new Float64Array(6);
+// ------------------------------------------------------------------ fitBounds / recenter
+/**
+ * Scale uniformly about the origin so the longest side of the axis-aligned box equals `size`.
+ * Normals are unchanged (a uniform scale keeps them); bounds are recomputed. An empty or
+ * zero-extent geometry is left as it is. Mutates and returns `g`.
+ */
+export function fitBounds(g, size) {
+    const F = floatsOf(g, 'fitBounds');
+    const v = g.vertices;
+    const box = aabb(v, F, AABB);
+    const longest = Math.max(box[3] - box[0], box[4] - box[1], box[5] - box[2]);
+    if (!(longest > 0))
+        return g;
+    const k = size / longest;
+    for (let o = 0; o < v.length; o += F) {
+        v[o] = v[o] * k;
+        v[o + 1] = v[o + 1] * k;
+        v[o + 2] = v[o + 2] * k;
+    }
+    computeBounds(v, F, g.bounds);
+    return g;
+}
+/** Translate so the centre of the axis-aligned box is the origin. Mutates and returns `g`. */
+export function recenter(g) {
+    const F = floatsOf(g, 'recenter');
+    const v = g.vertices;
+    const box = aabb(v, F, AABB);
+    const cx = (box[0] + box[3]) / 2;
+    const cy = (box[1] + box[4]) / 2;
+    const cz = (box[2] + box[5]) / 2;
+    for (let o = 0; o < v.length; o += F) {
+        v[o] = v[o] - cx;
+        v[o + 1] = v[o + 1] - cy;
+        v[o + 2] = v[o + 2] - cz;
+    }
+    computeBounds(v, F, g.bounds);
+    return g;
+}