@driftengine/core 3.61.0

package/dist/math/exact.js

@@ -0,0 +1,262 @@
+/**
+ * Transcendentals that give the same bits on every JavaScript engine.
+ *
+ * **Not more accurate than `Math`, and that is not what they are for.** These are within a couple
+ * of units in the last place of correctly rounded, which is about what a platform `sin` gives you.
+ * What they are is *reproducible*: ECMAScript declines to specify `sin`, `cos`, `exp`, `acos` and
+ * eighteen more, so two engines may differ by an ulp, and an ulp is enough to make two peers running
+ * the same simulation disagree — first invisibly, then completely.
+ *
+ * `scripts/determinism.mjs` is the gate that refuses the unspecified ones inside the simulation set
+ * and names the twenty-two. Its header carries the other half of the argument: `+ - * /` are IEEE
+ * 754 operations by specification, JavaScript permits no fused-multiply-add contraction, and
+ * `Math.sqrt` is required correctly rounded and is *not* on that list. **So everything below uses
+ * only those five operations**, which is the whole design: reproducibility by construction rather
+ * than by hoping two engines chose the same algorithm.
+ *
+ * ---
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * `exactSin`, `exactCos`, `exactExp`, `exactAcos`. Four, because four is what the engine and its
+ * first consumer actually reach for: the terrain binding's slope angle needs `acos`, a lockstep
+ * fixture rotating anything needs `sin` and `cos`, and exponential decay needs `exp`.
+ *
+ * **`atan2` is absent.** It is the obvious fifth and nothing here needs one: `shape.ts` sorts by a
+ * comparison key computed from two in-plane axes rather than by an angle, and `joints.ts` compares
+ * a quaternion component against a half-angle's sine. *Reversed by* a site that genuinely needs a
+ * signed angle from two components, at which point it arrives with its own golden vectors.
+ *
+ * ## Nothing in core imports these
+ *
+ * Deliberately. `core-only` is the one size figure in this repository that every consumer pays, and
+ * a module reachable from `createRenderer` is in it whether anybody calls it or not. These are
+ * reached by the script bindings and by consumers who ask for them, so tree-shaking keeps them out
+ * of a bundle that does not, which is measured rather than assumed.
+ *
+ * ## The coefficients
+ *
+ * The polynomial and rational coefficients are fdlibm's, which is the ancestor of most platform
+ * libms and is public domain. They are written as literals: **a literal is the same number on
+ * every engine, which is the only property being bought.** Their provenance matters less than their
+ * fixity — a coefficient somebody re-derived to one more digit is a different function, and
+ * `exact.test.ts`'s golden bit patterns are what would catch that.
+ */
+/*
+ * π/2 in four pieces, most significant first, so a large multiple of it can be removed without
+ * losing the small remainder in the subtraction.
+ *
+ * **Two pieces are not enough and the measurement says so**: at an angle of 740 radians a two-part
+ * reduction leaves `sin` and `cos` 18.5 ulps out, because `k * PIO2_1` needs more than 53 bits once
+ * `k` grows. Three brings it under two ulps for the cost of two multiplies.
+ *
+ * **`PIO2_TAIL` and `PIO2_TAIL_LO` are one number in two halves, not two successive corrections.**
+ * fdlibm carries a fourth constant, `pio2_1t`, which is the tail for its *single*-iteration path;
+ * `pio2_2` is the same tail rounded differently, with `pio2_2t` as its own tail, and the two paths
+ * are alternatives. Refining the first with the second is not more accurate, it is wrong: it
+ * subtracts the tail twice and took `sin` to 2.2e11 ulps out, which is how this comment came to be
+ * here.
+ */
+const PIO2_1 = 1.5707963267341256;
+const PIO2_TAIL = 6.077100506303966e-11;
+const PIO2_TAIL_LO = 2.0222662487959506e-21;
+const TWO_OVER_PI = 0.6366197723675814;
+const HALF_PI = 1.5707963267948966;
+const PI = 3.141592653589793;
+/* fdlibm's `__kernel_sin` coefficients. */
+const S1 = -1.6666666666666632e-1;
+const S2 = 8.3333333333224894e-3;
+const S3 = -1.984126982985795e-4;
+const S4 = 2.7557313707070068e-6;
+const S5 = -2.5050760253406863e-8;
+const S6 = 1.5896909952115501e-10;
+/* fdlibm's `__kernel_cos` coefficients. */
+const C1 = 4.1666666666666602e-2;
+const C2 = -1.3888888888874109e-3;
+const C3 = 2.480158728947673e-5;
+const C4 = -2.7557314351390663e-7;
+const C5 = 2.0875723212981748e-9;
+const C6 = -1.1359647557788195e-11;
+/* fdlibm's `asin` rational, numerator then denominator. */
+const P0 = 1.6666666666666666e-1;
+const P1 = -3.2556581862240092e-1;
+const P2 = 2.0121253213486293e-1;
+const P3 = -4.0055534500679411e-2;
+const P4 = 7.9153499428981453e-4;
+const P5 = 3.4793310759602117e-5;
+const Q1 = -2.4033949117344142;
+const Q2 = 2.0209457602335057;
+const Q3 = -6.8828397160545329e-1;
+const Q4 = 7.7038150555901935e-2;
+/** ln 2, split for the same reason π/2 is. */
+const LN2_HI = 0.6931471803691238;
+const LN2_LO = 1.9082149292705877e-10;
+const ONE_OVER_LN2 = 1.4426950408889634;
+/** 2^(2^i), for i = 0 to 9. Every one is exact, so a product of them is exact. */
+const POW2 = [
+    2, 4, 16, 256, 65536, 4294967296, 1.8446744073709552e19, 3.402823669209385e38,
+    1.157920892373162e77, 1.3407807929942597e154,
+];
+/**
+ * Two to an integer power, by binary decomposition of the exponent.
+ *
+ * Multiplication by a power of two is exact in IEEE 754, so this is exact wherever it does not
+ * overflow — which is what makes it a legitimate substitute for the `Math.pow` a range reduction
+ * would otherwise reach for.
+ *
+ * A large negative exponent lands on zero instead of a subnormal, because the reciprocal is taken
+ * after the product overflows. That is `exp` underflowing to zero, which is where it was going.
+ */
+function pow2(exponent) {
+    let remaining = exponent < 0 ? -exponent : exponent;
+    let result = 1;
+    let index = 0;
+    while (remaining > 0 && index < POW2.length) {
+        if ((remaining & 1) === 1)
+            result *= POW2[index];
+        remaining >>= 1;
+        index += 1;
+    }
+    return exponent < 0 ? 1 / result : result;
+}
+/** sin on [-π/4, π/4]. */
+function sinKernel(x) {
+    const z = x * x;
+    const poly = S1 + z * (S2 + z * (S3 + z * (S4 + z * (S5 + z * S6))));
+    return x + x * z * poly;
+}
+/** cos on [-π/4, π/4]. */
+function cosKernel(x) {
+    const z = x * x;
+    const poly = C1 + z * (C2 + z * (C3 + z * (C4 + z * (C5 + z * C6))));
+    return 1 - 0.5 * z + z * z * poly;
+}
+/**
+ * Fold an angle into [-π/4, π/4] and say which quadrant it came from.
+ *
+ * Cody-Waite: the multiple of π/2 is removed in pieces, so the subtraction that produces a small
+ * remainder from two large numbers does not lose the bits it is supposed to keep. One-piece
+ * reduction is accurate to about 1e-8 at an angle of a thousand radians, which for a simulation
+ * that accumulates rotation is the difference between an object facing forward and facing sideways
+ * after a few minutes.
+ */
+function reduce(x) {
+    const k = Math.round(x * TWO_OVER_PI);
+    /* The leading piece, whose product with `k` is exact for every `k` a simulation reaches. */
+    const head = x - k * PIO2_1;
+    /*
+     * The tail, in two halves. `head - tail` loses the bits below its own last place, and
+     * `PIO2_TAIL_LO - (head - r - tail)` is exactly those bits recovered — the same
+     * subtract-and-recover fdlibm uses on its two-iteration path.
+     */
+    const tail = k * PIO2_TAIL;
+    let r = head - tail;
+    const lost = k * PIO2_TAIL_LO - (head - r - tail);
+    r = r - lost;
+    return { r, quadrant: ((k % 4) + 4) % 4 };
+}
+/** `Math.sin`, reproducibly. NaN in, NaN out; an infinity answers NaN, as `Math.sin` does. */
+export function exactSin(x) {
+    if (!Number.isFinite(x))
+        return Number.NaN;
+    const { r, quadrant } = reduce(x);
+    switch (quadrant) {
+        case 0:
+            return sinKernel(r);
+        case 1:
+            return cosKernel(r);
+        case 2:
+            return -sinKernel(r);
+        default:
+            return -cosKernel(r);
+    }
+}
+/** `Math.cos`, reproducibly. */
+export function exactCos(x) {
+    if (!Number.isFinite(x))
+        return Number.NaN;
+    const { r, quadrant } = reduce(x);
+    switch (quadrant) {
+        case 0:
+            return cosKernel(r);
+        case 1:
+            return -sinKernel(r);
+        case 2:
+            return -cosKernel(r);
+        default:
+            return sinKernel(r);
+    }
+}
+/**
+ * `Math.exp`, reproducibly.
+ *
+ * Reduce by a multiple of ln 2 into [-ln2/2, ln2/2], sum the Taylor series there, and scale by a
+ * power of two. **A degree-14 series and not a shorter minimax**, because on that interval the
+ * fifteenth term is about 4e-20 — below the precision of a double — so the series is exact to the
+ * representation and there is nothing a fitted polynomial would buy.
+ */
+export function exactExp(x) {
+    if (Number.isNaN(x))
+        return Number.NaN;
+    if (x === Number.POSITIVE_INFINITY)
+        return Number.POSITIVE_INFINITY;
+    if (x === Number.NEGATIVE_INFINITY)
+        return 0;
+    if (x > 709.782712893384)
+        return Number.POSITIVE_INFINITY;
+    if (x < -745.1332191019411)
+        return 0;
+    const k = Math.round(x * ONE_OVER_LN2);
+    const r = x - k * LN2_HI - k * LN2_LO;
+    /* Horner over 1/n!, highest term first. */
+    let sum = 1 / 87178291200; // 1/14!
+    sum = 1 / 6227020800 + r * sum; // 1/13!
+    sum = 1 / 479001600 + r * sum; // 1/12!
+    sum = 1 / 39916800 + r * sum; // 1/11!
+    sum = 1 / 3628800 + r * sum; // 1/10!
+    sum = 1 / 362880 + r * sum; // 1/9!
+    sum = 1 / 40320 + r * sum; // 1/8!
+    sum = 1 / 5040 + r * sum; // 1/7!
+    sum = 1 / 720 + r * sum; // 1/6!
+    sum = 1 / 120 + r * sum; // 1/5!
+    sum = 1 / 24 + r * sum; // 1/4!
+    sum = 1 / 6 + r * sum; // 1/3!
+    sum = 0.5 + r * sum;
+    sum = 1 + r * sum;
+    sum = 1 + r * sum;
+    return sum * pow2(k);
+}
+/** fdlibm's `asin` rational on `z = x²`, valid where `z` is small. */
+function asinRational(z) {
+    const numerator = z * (P0 + z * (P1 + z * (P2 + z * (P3 + z * (P4 + z * P5)))));
+    const denominator = 1 + z * (Q1 + z * (Q2 + z * (Q3 + z * Q4)));
+    return numerator / denominator;
+}
+/**
+ * `Math.acos`, reproducibly. Outside [-1, 1] this answers NaN, as `Math.acos` does.
+ *
+ * Three branches rather than one, and the split at ±0.5 is the reason it is accurate near the ends:
+ * `acos` has infinite derivative at ±1, so a polynomial in `x` loses its footing there. Substituting
+ * `s = sqrt((1 ∓ x)/2)` moves the awkward point to zero, where a polynomial is comfortable — which
+ * is also why `sqrt` being exactly rounded matters here rather than being a convenience.
+ */
+export function exactAcos(x) {
+    if (Number.isNaN(x) || x > 1 || x < -1)
+        return Number.NaN;
+    if (x === 1)
+        return 0;
+    if (x === -1)
+        return PI;
+    if (x >= 0.5) {
+        const z = (1 - x) / 2;
+        const s = Math.sqrt(z);
+        return 2 * (s + s * asinRational(z));
+    }
+    if (x <= -0.5) {
+        const z = (1 + x) / 2;
+        const s = Math.sqrt(z);
+        return PI - 2 * (s + s * asinRational(z));
+    }
+    const z = x * x;
+    return HALF_PI - (x + x * asinRational(z));
+}

package/dist/math/frustum.d.ts

@@ -0,0 +1,44 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+/**
+ * The six planes bounding what a camera can see, and whether a sphere is among them.
+ *
+ * **A `Float32Array(24)` rather than six objects**, for the reason every hot path in this engine
+ * gives: a visibility test runs per draw per frame, and an array of plane objects is six
+ * dereferences a test and an allocation per rebuild.
+ *
+ * Planes are stored as `(nx, ny, nz, d)` with the normal pointing *inwards*, so a point is inside
+ * the frustum when `n · p + d >= 0` for all six.
+ */
+export type Frustum = Float32Array;
+export declare function createFrustum(): Frustum;
+/**
+ * Pull the six planes out of a view-projection matrix.
+ *
+ * **This is Gribb and Hartmann, and it is worth naming because it looks like a trick.** A
+ * view-projection takes a world point to clip space, where being inside the frustum is
+ * `-w <= x <= w` and the same for y and z. Writing `x >= -w` as `x + w >= 0` and substituting the
+ * matrix rows gives a plane equation in world coordinates directly — so the left plane is row 4
+ * plus row 1, the right is row 4 minus row 1, and so on. No inversion, no corner extraction.
+ *
+ * **Normalising is not tidiness.** Straight out of the matrix a plane's normal has an arbitrary
+ * length, so `n · p + d` is a distance in some unscaled clip unit. Dividing through by the
+ * normal's length makes it a distance in world units, which is the only form a radius in metres
+ * can be compared against. Skipping it produces a test that is *nearly* right, and wrong by a
+ * factor that changes with the field of view.
+ *
+ * gl-matrix stores column-major, so `m[column * 4 + row]`.
+ */
+export declare function frustumFromViewProjection(m: ReadonlyMat4, out: Frustum): Frustum;
+/**
+ * Whether a world-space sphere is anywhere inside the frustum.
+ *
+ * **The question is "outside any one plane", not "inside every plane".** A sphere is rejected
+ * only when it lies entirely on the far side of a single plane; anything else is kept. Asking
+ * whether the *centre* is inside all six is the version that looks equivalent and is not — it
+ * throws away everything larger than the view, so a room the camera is standing in vanishes.
+ *
+ * Conservative at the corners: a sphere can be outside the frustum and still be within radius of
+ * all six planes, near an edge. That costs a draw that turns out to be invisible and never costs
+ * a draw that was visible, which is the only asymmetry a cull may have.
+ */
+export declare function sphereInFrustum(frustum: Frustum, x: number, y: number, z: number, radius: number): boolean;

package/dist/math/frustum.js

@@ -0,0 +1,90 @@
+/** Left, right, bottom, top, near, far — the order the extraction below produces. */
+const PLANE_COUNT = 6;
+export function createFrustum() {
+    return new Float32Array(PLANE_COUNT * 4);
+}
+/**
+ * Pull the six planes out of a view-projection matrix.
+ *
+ * **This is Gribb and Hartmann, and it is worth naming because it looks like a trick.** A
+ * view-projection takes a world point to clip space, where being inside the frustum is
+ * `-w <= x <= w` and the same for y and z. Writing `x >= -w` as `x + w >= 0` and substituting the
+ * matrix rows gives a plane equation in world coordinates directly — so the left plane is row 4
+ * plus row 1, the right is row 4 minus row 1, and so on. No inversion, no corner extraction.
+ *
+ * **Normalising is not tidiness.** Straight out of the matrix a plane's normal has an arbitrary
+ * length, so `n · p + d` is a distance in some unscaled clip unit. Dividing through by the
+ * normal's length makes it a distance in world units, which is the only form a radius in metres
+ * can be compared against. Skipping it produces a test that is *nearly* right, and wrong by a
+ * factor that changes with the field of view.
+ *
+ * gl-matrix stores column-major, so `m[column * 4 + row]`.
+ */
+export function frustumFromViewProjection(m, out) {
+    const m0 = m[0] ?? 0;
+    const m1 = m[1] ?? 0;
+    const m2 = m[2] ?? 0;
+    const m3 = m[3] ?? 0;
+    const m4 = m[4] ?? 0;
+    const m5 = m[5] ?? 0;
+    const m6 = m[6] ?? 0;
+    const m7 = m[7] ?? 0;
+    const m8 = m[8] ?? 0;
+    const m9 = m[9] ?? 0;
+    const m10 = m[10] ?? 0;
+    const m11 = m[11] ?? 0;
+    const m12 = m[12] ?? 0;
+    const m13 = m[13] ?? 0;
+    const m14 = m[14] ?? 0;
+    const m15 = m[15] ?? 0;
+    /* Row 4 ± row 1, 2, 3. Row r of a column-major matrix is m[r], m[4+r], m[8+r], m[12+r]. */
+    setPlane(out, 0, m3 + m0, m7 + m4, m11 + m8, m15 + m12);
+    setPlane(out, 1, m3 - m0, m7 - m4, m11 - m8, m15 - m12);
+    setPlane(out, 2, m3 + m1, m7 + m5, m11 + m9, m15 + m13);
+    setPlane(out, 3, m3 - m1, m7 - m5, m11 - m9, m15 - m13);
+    /*
+     * **Near is `row4 + row3` and not `row3` alone**, which is the WebGL convention where clip z
+     * runs -w..w. WebGPU's runs 0..w and its near plane really is row 3 — but every matrix in this
+     * engine is built by gl-matrix's `perspective`, which is the OpenGL convention, and the
+     * WebGPU backend corrects it with `CLIP_CORRECTION` at the last moment before drawing. So the
+     * matrix reaching here is the OpenGL one on both backends, and one extraction serves both.
+     */
+    setPlane(out, 4, m3 + m2, m7 + m6, m11 + m10, m15 + m14);
+    setPlane(out, 5, m3 - m2, m7 - m6, m11 - m10, m15 - m14);
+    return out;
+}
+function setPlane(out, index, x, y, z, d) {
+    const length = Math.sqrt(x * x + y * y + z * z);
+    /* A degenerate matrix gives a zero-length normal; leaving it unscaled is better than NaN,
+       and the plane then accepts everything, which is the safe direction for a cull to fail. */
+    const scale = length > 1e-12 ? 1 / length : 0;
+    const at = index * 4;
+    out[at] = x * scale;
+    out[at + 1] = y * scale;
+    out[at + 2] = z * scale;
+    out[at + 3] = d * scale;
+}
+/**
+ * Whether a world-space sphere is anywhere inside the frustum.
+ *
+ * **The question is "outside any one plane", not "inside every plane".** A sphere is rejected
+ * only when it lies entirely on the far side of a single plane; anything else is kept. Asking
+ * whether the *centre* is inside all six is the version that looks equivalent and is not — it
+ * throws away everything larger than the view, so a room the camera is standing in vanishes.
+ *
+ * Conservative at the corners: a sphere can be outside the frustum and still be within radius of
+ * all six planes, near an edge. That costs a draw that turns out to be invisible and never costs
+ * a draw that was visible, which is the only asymmetry a cull may have.
+ */
+export function sphereInFrustum(frustum, x, y, z, radius) {
+    for (let plane = 0; plane < PLANE_COUNT; plane += 1) {
+        const at = plane * 4;
+        const distance = (frustum[at] ?? 0) * x +
+            (frustum[at + 1] ?? 0) * y +
+            (frustum[at + 2] ?? 0) * z +
+            (frustum[at + 3] ?? 0);
+        if (distance < -radius)
+            return false;
+    }
+    return true;
+}

package/dist/math/intersect.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Ray against shapes, for picking. Pure arithmetic, no allocation, no renderer.
+ *
+ * Separate from `src/render/` because none of it touches a context and all of it is
+ * testable without one — the same split `textLayout.ts` makes for the same reason.
+ */
+/**
+ * The slab method: clip the ray against three pairs of parallel planes and keep the
+ * overlap.
+ *
+ * **The divide by a zero direction component is deliberate.** A ray parallel to an axis
+ * gives ±Infinity for that slab, and the min/max below then either keep the interval
+ * whole (the origin is between the planes) or collapse it (it is not), which is the right
+ * answer both times. Special-casing zero to avoid the divide is how this gets broken.
+ *
+ * Returns the near distance, `0` when the origin is inside, `-1` on a miss. Distance
+ * rather than a boolean because a pick has to choose the nearest of several hits.
+ */
+export declare function rayAabb(origin: ArrayLike<number>, direction: ArrayLike<number>, min: ArrayLike<number>, max: ArrayLike<number>): number;
+/**
+ * Möller–Trumbore, indexed and two-sided.
+ *
+ * Takes vertex *indices* into a flat position array rather than three points, so a caller
+ * walking an index buffer allocates nothing per triangle — which is the whole reason
+ * picking can afford a narrow phase at pointer-move rates.
+ *
+ * **Two-sided deliberately.** Culling back faces would make a pick miss a surface the
+ * camera has got behind, and what that looks like to somebody using it is a click passing
+ * through the object to whatever is beyond it.
+ */
+export declare function rayTriangle(origin: ArrayLike<number>, direction: ArrayLike<number>, positions: ArrayLike<number>, a: number, b: number, c: number): number;
+/**
+ * Where a ray meets an infinite plane, or `-1`.
+ *
+ * The plane is a point and a normal rather than four coefficients, because every caller
+ * here has a point — a gizmo's origin, a target's position — and would otherwise compute
+ * `d` to have it undone one line later.
+ *
+ * **A ray within `1e-6` of parallel is a miss and not a hit at infinity.** The alternative
+ * returns a number that is finite, enormous and wrong, and what a caller does with it is
+ * teleport whatever it was dragging. Callers that grab against a plane depend on this
+ * refusal; see `gizmo.ts`.
+ *
+ * The normal does not have to be unit length, but `direction` and `normal` must be in the
+ * same space, and a plane behind the ray reports `-1` the way every other miss does.
+ */
+export declare function rayPlane(origin: ArrayLike<number>, direction: ArrayLike<number>, point: ArrayLike<number>, normal: ArrayLike<number>): number;
+/**
+ * The closest approach between a ray and an infinite line, written into `out`.
+ *
+ * `out` receives three numbers: the ray's parameter, the line's parameter, and the
+ * distance between the two closest points. Three outputs is why this takes a buffer where
+ * everything else in this file returns a number — a caller picking a gizmo handle needs
+ * all three at once, and needs them without allocating on every pointer move.
+ *
+ * Returns `false` for two lines within `1e-6` of parallel, and **writes nothing in that
+ * case**. There is no closest pair to report: every point on one line is equidistant from
+ * the other, so any answer would be arbitrary, and a caller dragging along the line has to
+ * keep what it had rather than jump to whichever point the arithmetic happened to land on.
+ *
+ * `direction` and `axis` must both be unit length. That is what makes the returned
+ * parameters distances rather than multiples of two different vectors' lengths.
+ */
+export declare function rayClosestOnLine(origin: ArrayLike<number>, direction: ArrayLike<number>, point: ArrayLike<number>, axis: ArrayLike<number>, out: Float32Array): boolean;
+/**
+ * The nearest positive distance along a ray to a sphere's surface, or `-1`.
+ *
+ * **An origin inside the sphere reports the far root rather than a miss**, which is the
+ * same choice `rayAabb` makes for the same reason: a camera that has got inside something
+ * pickable is still looking at it, and reporting a miss makes the object impossible to
+ * click from close up.
+ *
+ * `direction` must be unit length, which is what lets the quadratic drop its leading
+ * coefficient.
+ */
+export declare function raySphere(origin: ArrayLike<number>, direction: ArrayLike<number>, centre: ArrayLike<number>, radius: number): number;

package/dist/math/intersect.js

@@ -0,0 +1,185 @@
+/**
+ * Ray against shapes, for picking. Pure arithmetic, no allocation, no renderer.
+ *
+ * Separate from `src/render/` because none of it touches a context and all of it is
+ * testable without one — the same split `textLayout.ts` makes for the same reason.
+ */
+/**
+ * The slab method: clip the ray against three pairs of parallel planes and keep the
+ * overlap.
+ *
+ * **The divide by a zero direction component is deliberate.** A ray parallel to an axis
+ * gives ±Infinity for that slab, and the min/max below then either keep the interval
+ * whole (the origin is between the planes) or collapse it (it is not), which is the right
+ * answer both times. Special-casing zero to avoid the divide is how this gets broken.
+ *
+ * Returns the near distance, `0` when the origin is inside, `-1` on a miss. Distance
+ * rather than a boolean because a pick has to choose the nearest of several hits.
+ */
+export function rayAabb(origin, direction, min, max) {
+    let near = -Infinity;
+    let far = Infinity;
+    for (let axis = 0; axis < 3; axis++) {
+        const inverse = 1 / direction[axis];
+        let t0 = (min[axis] - origin[axis]) * inverse;
+        let t1 = (max[axis] - origin[axis]) * inverse;
+        if (t0 > t1) {
+            const swap = t0;
+            t0 = t1;
+            t1 = swap;
+        }
+        if (t0 > near)
+            near = t0;
+        if (t1 < far)
+            far = t1;
+        if (near > far)
+            return -1;
+    }
+    if (far < 0)
+        return -1;
+    return near < 0 ? 0 : near;
+}
+/**
+ * Möller–Trumbore, indexed and two-sided.
+ *
+ * Takes vertex *indices* into a flat position array rather than three points, so a caller
+ * walking an index buffer allocates nothing per triangle — which is the whole reason
+ * picking can afford a narrow phase at pointer-move rates.
+ *
+ * **Two-sided deliberately.** Culling back faces would make a pick miss a surface the
+ * camera has got behind, and what that looks like to somebody using it is a click passing
+ * through the object to whatever is beyond it.
+ */
+export function rayTriangle(origin, direction, positions, a, b, c) {
+    const ax = positions[a * 3];
+    const ay = positions[a * 3 + 1];
+    const az = positions[a * 3 + 2];
+    const e1x = positions[b * 3] - ax;
+    const e1y = positions[b * 3 + 1] - ay;
+    const e1z = positions[b * 3 + 2] - az;
+    const e2x = positions[c * 3] - ax;
+    const e2y = positions[c * 3 + 1] - ay;
+    const e2z = positions[c * 3 + 2] - az;
+    const px = direction[1] * e2z - direction[2] * e2y;
+    const py = direction[2] * e2x - direction[0] * e2z;
+    const pz = direction[0] * e2y - direction[1] * e2x;
+    const determinant = e1x * px + e1y * py + e1z * pz;
+    /* Near zero is a ray in the triangle's own plane: no single crossing to report. */
+    if (determinant > -1e-9 && determinant < 1e-9)
+        return -1;
+    const inverse = 1 / determinant;
+    const tx = origin[0] - ax;
+    const ty = origin[1] - ay;
+    const tz = origin[2] - az;
+    const u = (tx * px + ty * py + tz * pz) * inverse;
+    if (u < 0 || u > 1)
+        return -1;
+    const qx = ty * e1z - tz * e1y;
+    const qy = tz * e1x - tx * e1z;
+    const qz = tx * e1y - ty * e1x;
+    const v = (direction[0] * qx +
+        direction[1] * qy +
+        direction[2] * qz) *
+        inverse;
+    if (v < 0 || u + v > 1)
+        return -1;
+    const distance = (e2x * qx + e2y * qy + e2z * qz) * inverse;
+    return distance > 1e-6 ? distance : -1;
+}
+/**
+ * Where a ray meets an infinite plane, or `-1`.
+ *
+ * The plane is a point and a normal rather than four coefficients, because every caller
+ * here has a point — a gizmo's origin, a target's position — and would otherwise compute
+ * `d` to have it undone one line later.
+ *
+ * **A ray within `1e-6` of parallel is a miss and not a hit at infinity.** The alternative
+ * returns a number that is finite, enormous and wrong, and what a caller does with it is
+ * teleport whatever it was dragging. Callers that grab against a plane depend on this
+ * refusal; see `gizmo.ts`.
+ *
+ * The normal does not have to be unit length, but `direction` and `normal` must be in the
+ * same space, and a plane behind the ray reports `-1` the way every other miss does.
+ */
+export function rayPlane(origin, direction, point, normal) {
+    const denominator = direction[0] * normal[0] +
+        direction[1] * normal[1] +
+        direction[2] * normal[2];
+    if (denominator > -1e-6 && denominator < 1e-6)
+        return -1;
+    const numerator = (point[0] - origin[0]) * normal[0] +
+        (point[1] - origin[1]) * normal[1] +
+        (point[2] - origin[2]) * normal[2];
+    const distance = numerator / denominator;
+    return distance >= 0 ? distance : -1;
+}
+/**
+ * The closest approach between a ray and an infinite line, written into `out`.
+ *
+ * `out` receives three numbers: the ray's parameter, the line's parameter, and the
+ * distance between the two closest points. Three outputs is why this takes a buffer where
+ * everything else in this file returns a number — a caller picking a gizmo handle needs
+ * all three at once, and needs them without allocating on every pointer move.
+ *
+ * Returns `false` for two lines within `1e-6` of parallel, and **writes nothing in that
+ * case**. There is no closest pair to report: every point on one line is equidistant from
+ * the other, so any answer would be arbitrary, and a caller dragging along the line has to
+ * keep what it had rather than jump to whichever point the arithmetic happened to land on.
+ *
+ * `direction` and `axis` must both be unit length. That is what makes the returned
+ * parameters distances rather than multiples of two different vectors' lengths.
+ */
+export function rayClosestOnLine(origin, direction, point, axis, out) {
+    const dx = direction[0];
+    const dy = direction[1];
+    const dz = direction[2];
+    const ax = axis[0];
+    const ay = axis[1];
+    const az = axis[2];
+    const dotDA = dx * ax + dy * ay + dz * az;
+    /* Both are unit, so this is 1 - cos²: the squared sine of the angle between them. */
+    const denominator = 1 - dotDA * dotDA;
+    if (denominator < 1e-6)
+        return false;
+    const wx = origin[0] - point[0];
+    const wy = origin[1] - point[1];
+    const wz = origin[2] - point[2];
+    const dotDW = dx * wx + dy * wy + dz * wz;
+    const dotAW = ax * wx + ay * wy + az * wz;
+    const rayT = (dotDA * dotAW - dotDW) / denominator;
+    const lineS = (dotAW - dotDA * dotDW) / denominator;
+    const px = wx + dx * rayT - ax * lineS;
+    const py = wy + dy * rayT - ay * lineS;
+    const pz = wz + dz * rayT - az * lineS;
+    out[0] = rayT;
+    out[1] = lineS;
+    out[2] = Math.sqrt(px * px + py * py + pz * pz);
+    return true;
+}
+/**
+ * The nearest positive distance along a ray to a sphere's surface, or `-1`.
+ *
+ * **An origin inside the sphere reports the far root rather than a miss**, which is the
+ * same choice `rayAabb` makes for the same reason: a camera that has got inside something
+ * pickable is still looking at it, and reporting a miss makes the object impossible to
+ * click from close up.
+ *
+ * `direction` must be unit length, which is what lets the quadratic drop its leading
+ * coefficient.
+ */
+export function raySphere(origin, direction, centre, radius) {
+    const ox = origin[0] - centre[0];
+    const oy = origin[1] - centre[1];
+    const oz = origin[2] - centre[2];
+    const b = ox * direction[0] + oy * direction[1] + oz * direction[2];
+    const c = ox * ox + oy * oy + oz * oz - radius * radius;
+    const discriminant = b * b - c;
+    if (discriminant < 0)
+        return -1;
+    const root = Math.sqrt(discriminant);
+    const near = -b - root;
+    if (near >= 0)
+        return near;
+    const far = -b + root;
+    return far >= 0 ? far : -1;
+}