@jgengine/core 0.10.0 → 0.11.0

package/dist/world/terrainGuides.js

@@ -0,0 +1,343 @@
+function assertRegion(region) {
+    if (!(region.maxX > region.minX) || !(region.maxZ > region.minZ)) {
+        throw new Error("terrainGuides: region must have maxX > minX and maxZ > minZ");
+    }
+}
+function clampInt(value, min, max) {
+    const v = Math.round(value);
+    return v < min ? min : v > max ? max : v;
+}
+/**
+ * Samples `sampleHeight` on a `(resolution + 1)²` grid across `region`, capturing the min/max seen —
+ * the bounded, budget-capped scan every guide derives from. `resolution` is clamped to `[1, maxSamples]`.
+ * @internal — building block behind the public guide generators.
+ */
+export function sampleHeightGrid(sampleHeight, region, resolution = 128, maxSamples = 256) {
+    assertRegion(region);
+    const res = clampInt(resolution, 1, Math.max(1, Math.round(maxSamples)));
+    const cols = res + 1;
+    const rows = res + 1;
+    const heights = new Float64Array(cols * rows);
+    const spanX = region.maxX - region.minX;
+    const spanZ = region.maxZ - region.minZ;
+    let min = Infinity;
+    let max = -Infinity;
+    for (let r = 0; r < rows; r += 1) {
+        const z = region.minZ + (r / res) * spanZ;
+        for (let c = 0; c < cols; c += 1) {
+            const x = region.minX + (c / res) * spanX;
+            const h = sampleHeight(x, z);
+            heights[r * cols + c] = h;
+            if (h < min)
+                min = h;
+            if (h > max)
+                max = h;
+        }
+    }
+    return { region, cols, rows, heights, min, max };
+}
+function lerpPoint(ax, az, av, bx, bz, bv, level) {
+    const denom = bv - av;
+    const t = denom === 0 ? 0.5 : (level - av) / denom;
+    const clamped = t < 0 ? 0 : t > 1 ? 1 : t;
+    return [ax + (bx - ax) * clamped, az + (bz - az) * clamped];
+}
+/**
+ * Traces surface-following contour lines from a height field via marching squares: samples a bounded
+ * grid over the region, then for every multiple of `interval` strictly inside the sampled height range
+ * emits the iso-line as XZ segments (saddle cells disambiguated by the cell-center average). Because a
+ * contour is exact constant elevation, drawing each segment at `y = level` makes it hug the terrain —
+ * the readable, scale-bearing overlay a flat ground grid cannot give. Pure math, renderer-agnostic.
+ * @capability terrain-contours iso-elevation contour lines that drape on sculpted terrain
+ * @consumer editor terrain-readability overlay; any map/minimap wanting elevation contours
+ */
+export function extractContours(sampleHeight, options) {
+    const { interval } = options;
+    if (!(interval > 0))
+        throw new Error("extractContours: interval must be > 0");
+    const majorEvery = Math.max(1, Math.floor(options.majorEvery ?? 5));
+    const grid = sampleHeightGrid(sampleHeight, options.region, options.resolution ?? 128, options.maxSamples ?? 256);
+    const { cols, heights, region } = grid;
+    const res = cols - 1;
+    const spanX = region.maxX - region.minX;
+    const spanZ = region.maxZ - region.minZ;
+    const worldX = (c) => region.minX + (c / res) * spanX;
+    const worldZ = (r) => region.minZ + (r / res) * spanZ;
+    const lines = [];
+    if (grid.max - grid.min < 1e-9)
+        return lines;
+    const firstStep = Math.ceil(grid.min / interval + 1e-9);
+    const lastStep = Math.floor(grid.max / interval - 1e-9);
+    for (let step = firstStep; step <= lastStep; step += 1) {
+        const level = step * interval;
+        const segments = [];
+        for (let r = 0; r < res; r += 1) {
+            for (let c = 0; c < res; c += 1) {
+                const blv = heights[r * cols + c];
+                const brv = heights[r * cols + c + 1];
+                const trv = heights[(r + 1) * cols + c + 1];
+                const tlv = heights[(r + 1) * cols + c];
+                let code = 0;
+                if (blv > level)
+                    code |= 1;
+                if (brv > level)
+                    code |= 2;
+                if (trv > level)
+                    code |= 4;
+                if (tlv > level)
+                    code |= 8;
+                if (code === 0 || code === 15)
+                    continue;
+                const x0 = worldX(c);
+                const x1 = worldX(c + 1);
+                const z0 = worldZ(r);
+                const z1 = worldZ(r + 1);
+                const eBottom = () => lerpPoint(x0, z0, blv, x1, z0, brv, level);
+                const eRight = () => lerpPoint(x1, z0, brv, x1, z1, trv, level);
+                const eTop = () => lerpPoint(x1, z1, trv, x0, z1, tlv, level);
+                const eLeft = () => lerpPoint(x0, z1, tlv, x0, z0, blv, level);
+                const push = (a, b) => {
+                    segments.push(a[0], a[1], b[0], b[1]);
+                };
+                switch (code) {
+                    case 1:
+                    case 14:
+                        push(eLeft(), eBottom());
+                        break;
+                    case 2:
+                    case 13:
+                        push(eBottom(), eRight());
+                        break;
+                    case 3:
+                    case 12:
+                        push(eLeft(), eRight());
+                        break;
+                    case 4:
+                    case 11:
+                        push(eRight(), eTop());
+                        break;
+                    case 6:
+                    case 9:
+                        push(eBottom(), eTop());
+                        break;
+                    case 7:
+                    case 8:
+                        push(eLeft(), eTop());
+                        break;
+                    case 5: {
+                        const center = (blv + brv + trv + tlv) / 4;
+                        if (center > level) {
+                            push(eLeft(), eTop());
+                            push(eBottom(), eRight());
+                        }
+                        else {
+                            push(eLeft(), eBottom());
+                            push(eRight(), eTop());
+                        }
+                        break;
+                    }
+                    case 10: {
+                        const center = (blv + brv + trv + tlv) / 4;
+                        if (center > level) {
+                            push(eLeft(), eBottom());
+                            push(eRight(), eTop());
+                        }
+                        else {
+                            push(eLeft(), eTop());
+                            push(eBottom(), eRight());
+                        }
+                        break;
+                    }
+                    default:
+                        break;
+                }
+            }
+        }
+        if (segments.length > 0) {
+            lines.push({ level, major: step % majorEvery === 0, segments });
+        }
+    }
+    return lines;
+}
+const NICE_STEPS = [1, 2, 2.5, 5];
+/**
+ * Picks a human-friendly contour interval — a `1/2/2.5/5 × 10ⁿ` step — so an elevation `range` splits
+ * into roughly `targetLines` bands. Drives adaptive contour density: a tall terrain gets a coarse
+ * interval, a shallow one a fine interval, without the author choosing a number. Returns `0` when the
+ * range is non-positive (nothing to contour).
+ * @capability contour-interval readable auto-spacing for elevation contours
+ * @consumer editor terrain-readability overlay density control
+ */
+export function chooseContourInterval(range, targetLines = 12) {
+    if (!(range > 0) || !(targetLines > 0))
+        return 0;
+    const rough = range / targetLines;
+    const magnitude = 10 ** Math.floor(Math.log10(rough));
+    let best = NICE_STEPS[0] * magnitude;
+    let bestErr = Infinity;
+    for (const stepBase of NICE_STEPS) {
+        for (const scale of [magnitude, magnitude * 10]) {
+            const candidate = stepBase * scale;
+            const err = Math.abs(range / candidate - targetLines);
+            if (err < bestErr) {
+                bestErr = err;
+                best = candidate;
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Reads the ground elevation under a world point and its signed delta from a reference plane — the
+ * measurable cursor/hover feedback ("+3.4 above the pad") an author needs to judge sculpted height.
+ * @capability elevation-readout cursor height and delta-from-reference feedback
+ * @consumer editor terrain-readability HUD readout
+ */
+export function sampleElevation(sampleHeight, x, z, reference = 0) {
+    const height = sampleHeight(x, z);
+    return { x, z, height, delta: height - reference, reference };
+}
+/**
+ * Summarises elevation across a region on a bounded sample grid: min, max, mean, relief range, and the
+ * world points of the extremes — the selection min/max and legend feedback the readability overlay
+ * reports, and the input to {@link chooseContourInterval}. Pure math, renderer-agnostic.
+ * @capability elevation-summary selection min/max/mean and relief over a region
+ * @consumer editor terrain-readability legend and selection stats
+ */
+export function summarizeElevation(sampleHeight, region, resolution = 64, maxSamples = 256) {
+    const grid = sampleHeightGrid(sampleHeight, region, resolution, maxSamples);
+    const { cols, rows, heights } = grid;
+    const res = cols - 1;
+    const spanX = region.maxX - region.minX;
+    const spanZ = region.maxZ - region.minZ;
+    let sum = 0;
+    let minAt = [region.minX, region.minZ];
+    let maxAt = [region.minX, region.minZ];
+    for (let r = 0; r < rows; r += 1) {
+        for (let c = 0; c < cols; c += 1) {
+            const h = heights[r * cols + c];
+            sum += h;
+            if (h === grid.min)
+                minAt = [region.minX + (c / res) * spanX, region.minZ + (r / res) * spanZ];
+            if (h === grid.max)
+                maxAt = [region.minX + (c / res) * spanX, region.minZ + (r / res) * spanZ];
+        }
+    }
+    const samples = cols * rows;
+    return {
+        min: grid.min,
+        max: grid.max,
+        mean: sum / samples,
+        range: grid.max - grid.min,
+        minAt,
+        maxAt,
+        samples,
+    };
+}
+/**
+ * Drapes an XZ polyline onto the surface: subdivides each span to at most `spacing` and lifts every
+ * vertex to `sampleHeight + offset`, returning flat `[x, y, z, ...]` world triples. The reusable seam
+ * behind surface-following placement guides and grid lines — a straight guide bends to follow terrain.
+ * @capability surface-drape lift an XZ polyline onto sculpted terrain
+ * @consumer editor placement guides and surface grid overlay
+ */
+export function drapePolyline(sampleHeight, points, options = {}) {
+    const spacing = options.spacing !== undefined && options.spacing > 0 ? options.spacing : 1;
+    const offset = options.offset ?? 0;
+    const out = [];
+    if (points.length === 0)
+        return out;
+    const push = (x, z) => {
+        out.push(x, sampleHeight(x, z) + offset, z);
+    };
+    if (points.length === 1) {
+        push(points[0][0], points[0][1]);
+        return out;
+    }
+    push(points[0][0], points[0][1]);
+    for (let i = 1; i < points.length; i += 1) {
+        const [ax, az] = points[i - 1];
+        const [bx, bz] = points[i];
+        const dist = Math.hypot(bx - ax, bz - az);
+        const steps = Math.max(1, Math.ceil(dist / spacing));
+        for (let s = 1; s <= steps; s += 1) {
+            const t = s / steps;
+            push(ax + (bx - ax) * t, az + (bz - az) * t);
+        }
+    }
+    return out;
+}
+/**
+ * A closed circle draped on the surface — the surface-following placement guide ring under a cursor or
+ * a selected object. Returns flat `[x, y, z, ...]` world triples forming a loop (last vertex repeats
+ * the first). `segments` sets the smoothness of the ring.
+ * @capability surface-ring surface-following placement guide ring
+ * @consumer editor cursor/placement guide
+ */
+export function surfaceRing(sampleHeight, center, radius, segments = 48, options = {}) {
+    const n = Math.max(3, Math.floor(segments));
+    const points = [];
+    for (let i = 0; i <= n; i += 1) {
+        const angle = (i / n) * Math.PI * 2;
+        points.push([center[0] + Math.cos(angle) * radius, center[1] + Math.sin(angle) * radius]);
+    }
+    return drapePolyline(sampleHeight, points, options);
+}
+function gridStops(min, max, spacing) {
+    const stops = [];
+    const first = Math.ceil(min / spacing - 1e-9);
+    const last = Math.floor(max / spacing + 1e-9);
+    for (let step = first; step <= last; step += 1)
+        stops.push(step);
+    return stops;
+}
+/**
+ * Builds a surface-following major/minor grid over a region: constant-`x` and constant-`z` lines at
+ * `spacing`, each draped onto the terrain so the reference grid climbs sculpted surfaces instead of
+ * being occluded by them (the flat `y = 0` grid's core failure). Draping subdivides to
+ * `drape.spacing`. Pure math, renderer-agnostic.
+ * @capability surface-grid terrain-following reference grid that is not occluded by relief
+ * @consumer editor terrain-readability grid overlay
+ */
+export function surfaceGridLines(sampleHeight, options) {
+    const { region, spacing } = options;
+    assertRegion(region);
+    if (!(spacing > 0))
+        throw new Error("surfaceGridLines: spacing must be > 0");
+    const majorEvery = Math.max(1, Math.floor(options.majorEvery ?? 5));
+    const drape = options.drape ?? {};
+    const lines = [];
+    for (const step of gridStops(region.minX, region.maxX, spacing)) {
+        const x = step * spacing;
+        lines.push({
+            axis: "x",
+            at: x,
+            major: step % majorEvery === 0,
+            points: drapePolyline(sampleHeight, [[x, region.minZ], [x, region.maxZ]], drape),
+        });
+    }
+    for (const step of gridStops(region.minZ, region.maxZ, spacing)) {
+        const z = step * spacing;
+        lines.push({
+            axis: "z",
+            at: z,
+            major: step % majorEvery === 0,
+            points: drapePolyline(sampleHeight, [[region.minX, z], [region.maxX, z]], drape),
+        });
+    }
+    return lines;
+}
+/**
+ * Convenience over {@link extractContours} that auto-picks the interval from the field's own relief:
+ * summarises the region, chooses a readable interval for `targetLines` bands, and traces the contours —
+ * the one call the editor overlay makes to turn a `TerrainField` into ready-to-draw guides. Returns an
+ * empty list for flat ground.
+ * @capability terrain-guides one-call adaptive contours for a terrain field
+ * @consumer editor terrain-readability overlay
+ */
+export function terrainContourGuides(field, region, targetLines = 12, resolution = 128) {
+    const summary = summarizeElevation(field.sampleHeight, region, Math.min(resolution, 96));
+    const interval = chooseContourInterval(summary.range, targetLines);
+    const contours = interval > 0 ? extractContours(field.sampleHeight, { region, interval, resolution }) : [];
+    return { interval, summary, contours };
+}

package/dist/world/vec2.d.ts

@@ -0,0 +1,81 @@
+import type { Vec2 } from "./geometry.js";
+/** Sum of two 2D vectors.
+ * @internal
+ */
+export declare function add(a: Vec2, b: Vec2): Vec2;
+/** Difference `a - b` of two 2D vectors.
+ * @internal
+ */
+export declare function sub(a: Vec2, b: Vec2): Vec2;
+/** Scale a 2D vector by a scalar.
+ * @internal
+ */
+export declare function scale(a: Vec2, s: number): Vec2;
+/** Negate a 2D vector.
+ * @internal
+ */
+export declare function negate(a: Vec2): Vec2;
+/** Dot product of two 2D vectors.
+ * @internal
+ */
+export declare function dot(a: Vec2, b: Vec2): number;
+/** 2D cross product (scalar z of the 3D cross), positive when `b` is counter-clockwise from `a`.
+ * @internal
+ */
+export declare function cross(a: Vec2, b: Vec2): number;
+/** Euclidean length of a 2D vector.
+ * @internal
+ */
+export declare function length(a: Vec2): number;
+/** Squared length of a 2D vector; cheaper than `length` when only comparing magnitudes.
+ * @internal
+ */
+export declare function lengthSquared(a: Vec2): number;
+/** Unit vector in the direction of `a`; returns the zero vector when `a` has no length.
+ * @internal
+ */
+export declare function normalize(a: Vec2): Vec2;
+/** Distance between two points.
+ * @internal
+ */
+export declare function distance(a: Vec2, b: Vec2): number;
+/** Squared distance between two points; cheaper than `distance` for radius comparisons.
+ * @internal
+ */
+export declare function distanceSquared(a: Vec2, b: Vec2): number;
+/** Linearly interpolate between points `a` and `b` by fraction `t`.
+ * @internal
+ */
+export declare function lerp(a: Vec2, b: Vec2, t: number): Vec2;
+/** Left-hand perpendicular of `a` (rotated 90° counter-clockwise).
+ * @internal
+ */
+export declare function perp(a: Vec2): Vec2;
+/** Rotate a 2D vector by `radians` about the origin.
+ * @internal
+ */
+export declare function rotate(a: Vec2, radians: number): Vec2;
+/**
+ * Reflect a velocity off a surface with unit `normal`, losing energy by `restitution` (0..1). At
+ * `restitution` 1 the normal component mirrors elastically (`v − 2(v·n)n`); at 0 it is removed so the
+ * vector slides along the surface. Only the normal component is scaled — tangential motion is kept — so
+ * this is the wall/paddle/boundary bounce every arcade ball game hand-rolls.
+  * @internal
+  */
+export declare function reflect(v: Vec2, normal: Vec2, restitution?: number): Vec2;
+/** Unit vector for a heading measured clockwise from +Y (the engine's XZ-plane convention).
+ * @internal
+ */
+export declare function fromHeading(headingRad: number): Vec2;
+/** Heading in radians of a vector, measured clockwise from +Y to match `fromHeading`.
+ * @internal
+ */
+export declare function heading(a: Vec2): number;
+/** Wrap an angle in radians into `[0, 2π)`.
+ * @internal
+ */
+export declare function normalizeAngle(angleRad: number): number;
+/** Wrap an angle in degrees into `[0, 360)`.
+ * @internal
+ */
+export declare function normalizeAngleDeg(angleDeg: number): number;

package/dist/world/vec2.js

@@ -0,0 +1,128 @@
+/** Sum of two 2D vectors.
+ * @internal
+ */
+export function add(a, b) {
+    return [a[0] + b[0], a[1] + b[1]];
+}
+/** Difference `a - b` of two 2D vectors.
+ * @internal
+ */
+export function sub(a, b) {
+    return [a[0] - b[0], a[1] - b[1]];
+}
+/** Scale a 2D vector by a scalar.
+ * @internal
+ */
+export function scale(a, s) {
+    return [a[0] * s, a[1] * s];
+}
+/** Negate a 2D vector.
+ * @internal
+ */
+export function negate(a) {
+    return [-a[0], -a[1]];
+}
+/** Dot product of two 2D vectors.
+ * @internal
+ */
+export function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1];
+}
+/** 2D cross product (scalar z of the 3D cross), positive when `b` is counter-clockwise from `a`.
+ * @internal
+ */
+export function cross(a, b) {
+    return a[0] * b[1] - a[1] * b[0];
+}
+/** Euclidean length of a 2D vector.
+ * @internal
+ */
+export function length(a) {
+    return Math.hypot(a[0], a[1]);
+}
+/** Squared length of a 2D vector; cheaper than `length` when only comparing magnitudes.
+ * @internal
+ */
+export function lengthSquared(a) {
+    return a[0] * a[0] + a[1] * a[1];
+}
+/** Unit vector in the direction of `a`; returns the zero vector when `a` has no length.
+ * @internal
+ */
+export function normalize(a) {
+    const len = Math.hypot(a[0], a[1]);
+    return len < 1e-9 ? [0, 0] : [a[0] / len, a[1] / len];
+}
+/** Distance between two points.
+ * @internal
+ */
+export function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1]);
+}
+/** Squared distance between two points; cheaper than `distance` for radius comparisons.
+ * @internal
+ */
+export function distanceSquared(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    return dx * dx + dy * dy;
+}
+/** Linearly interpolate between points `a` and `b` by fraction `t`.
+ * @internal
+ */
+export function lerp(a, b, t) {
+    return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+}
+/** Left-hand perpendicular of `a` (rotated 90° counter-clockwise).
+ * @internal
+ */
+export function perp(a) {
+    return [-a[1], a[0]];
+}
+/** Rotate a 2D vector by `radians` about the origin.
+ * @internal
+ */
+export function rotate(a, radians) {
+    const c = Math.cos(radians);
+    const s = Math.sin(radians);
+    return [a[0] * c - a[1] * s, a[0] * s + a[1] * c];
+}
+/**
+ * Reflect a velocity off a surface with unit `normal`, losing energy by `restitution` (0..1). At
+ * `restitution` 1 the normal component mirrors elastically (`v − 2(v·n)n`); at 0 it is removed so the
+ * vector slides along the surface. Only the normal component is scaled — tangential motion is kept — so
+ * this is the wall/paddle/boundary bounce every arcade ball game hand-rolls.
+  * @internal
+  */
+export function reflect(v, normal, restitution = 1) {
+    const vn = v[0] * normal[0] + v[1] * normal[1];
+    const j = (1 + restitution) * vn;
+    return [v[0] - j * normal[0], v[1] - j * normal[1]];
+}
+/** Unit vector for a heading measured clockwise from +Y (the engine's XZ-plane convention).
+ * @internal
+ */
+export function fromHeading(headingRad) {
+    return [Math.sin(headingRad), Math.cos(headingRad)];
+}
+/** Heading in radians of a vector, measured clockwise from +Y to match `fromHeading`.
+ * @internal
+ */
+export function heading(a) {
+    return Math.atan2(a[0], a[1]);
+}
+/** Wrap an angle in radians into `[0, 2π)`.
+ * @internal
+ */
+export function normalizeAngle(angleRad) {
+    const twoPi = Math.PI * 2;
+    const a = angleRad % twoPi;
+    return a < 0 ? a + twoPi : a;
+}
+/** Wrap an angle in degrees into `[0, 360)`.
+ * @internal
+ */
+export function normalizeAngleDeg(angleDeg) {
+    const a = angleDeg % 360;
+    return a < 0 ? a + 360 : a;
+}

package/dist/world/vec3.d.ts

@@ -0,0 +1,49 @@
+import type { Vec3 } from "./geometry.js";
+/** Sum of two 3D vectors.
+ * @internal
+ */
+export declare function add(a: Vec3, b: Vec3): Vec3;
+/** Difference `a - b` of two 3D vectors.
+ * @internal
+ */
+export declare function sub(a: Vec3, b: Vec3): Vec3;
+/** Scale a 3D vector by a scalar.
+ * @internal
+ */
+export declare function scale(a: Vec3, s: number): Vec3;
+/** Negate a 3D vector.
+ * @internal
+ */
+export declare function negate(a: Vec3): Vec3;
+/** Dot product of two 3D vectors.
+ * @internal
+ */
+export declare function dot(a: Vec3, b: Vec3): number;
+/** Cross product `a × b` of two 3D vectors.
+ * @internal
+ */
+export declare function cross(a: Vec3, b: Vec3): Vec3;
+/** Euclidean length of a 3D vector.
+ * @internal
+ */
+export declare function length(a: Vec3): number;
+/** Squared length of a 3D vector; cheaper than `length` when only comparing magnitudes.
+ * @internal
+ */
+export declare function lengthSquared(a: Vec3): number;
+/** Unit vector in the direction of `a`; returns the zero vector when `a` has no length.
+ * @internal
+ */
+export declare function normalize(a: Vec3): Vec3;
+/** Distance between two points.
+ * @internal
+ */
+export declare function distance(a: Vec3, b: Vec3): number;
+/** Squared distance between two points; cheaper than `distance` for radius comparisons on hot paths.
+ * @internal
+ */
+export declare function distanceSquared(a: Vec3, b: Vec3): number;
+/** Linearly interpolate between points `a` and `b` by fraction `t`.
+ * @internal
+ */
+export declare function lerp(a: Vec3, b: Vec3, t: number): Vec3;

package/dist/world/vec3.js

@@ -0,0 +1,76 @@
+/** Sum of two 3D vectors.
+ * @internal
+ */
+export function add(a, b) {
+    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+/** Difference `a - b` of two 3D vectors.
+ * @internal
+ */
+export function sub(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+/** Scale a 3D vector by a scalar.
+ * @internal
+ */
+export function scale(a, s) {
+    return [a[0] * s, a[1] * s, a[2] * s];
+}
+/** Negate a 3D vector.
+ * @internal
+ */
+export function negate(a) {
+    return [-a[0], -a[1], -a[2]];
+}
+/** Dot product of two 3D vectors.
+ * @internal
+ */
+export function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/** Cross product `a × b` of two 3D vectors.
+ * @internal
+ */
+export function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+/** Euclidean length of a 3D vector.
+ * @internal
+ */
+export function length(a) {
+    return Math.hypot(a[0], a[1], a[2]);
+}
+/** Squared length of a 3D vector; cheaper than `length` when only comparing magnitudes.
+ * @internal
+ */
+export function lengthSquared(a) {
+    return a[0] * a[0] + a[1] * a[1] + a[2] * a[2];
+}
+/** Unit vector in the direction of `a`; returns the zero vector when `a` has no length.
+ * @internal
+ */
+export function normalize(a) {
+    const len = Math.hypot(a[0], a[1], a[2]);
+    return len < 1e-9 ? [0, 0, 0] : [a[0] / len, a[1] / len, a[2] / len];
+}
+/** Distance between two points.
+ * @internal
+ */
+export function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+/** Squared distance between two points; cheaper than `distance` for radius comparisons on hot paths.
+ * @internal
+ */
+export function distanceSquared(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    const dz = a[2] - b[2];
+    return dx * dx + dy * dy + dz * dz;
+}
+/** Linearly interpolate between points `a` and `b` by fraction `t`.
+ * @internal
+ */
+export function lerp(a, b, t) {
+    return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+}