@driftengine/core 3.61.0

package/src/render/colourGrade.ts

@@ -0,0 +1,109 @@
+/**
+ * A colour grade: a lookup table over display values, applied where the output transform is.
+ *
+ * **A look, not a conversion, and the difference decides where it goes.** `outputTransform.ts` is
+ * the conversion from scene units to display values and every pass has to agree about it. A grade
+ * is what a colourist did afterwards — the same three numbers in, three different numbers out —
+ * and it is *display-referred*, which is what every `.cube` a grading tool exports is. So it is
+ * applied **after** the transform and never before it.
+ *
+ * **It rides the composite and needs `screenEffects`, which is the same rule `hdrScene` already
+ * carries and in the same words**: without a composite there is nothing at the end to grade in.
+ * Every forward pass grades *itself* when nothing follows it, so a lookup table applied there
+ * would need a sampler in six programs to reach a consumer who has deliberately switched
+ * post-processing off — and a consumer who switched post-processing off did not ask for a grade.
+ * `setColourGrade` says so out loud rather than doing nothing, because a look that silently does
+ * not apply is the failure this repository's rules exist to prevent.
+ *
+ * **`RGBA8` and trilinear, which is what a lookup table is everywhere.** The alpha channel is
+ * unused and opaque; a three-channel texture would save a quarter and is not a format WebGL2 can
+ * filter as a 3D target. The filtering is what makes a 32-lattice table smooth — without it the
+ * grade bands, which is the one artefact a grade must never introduce.
+ */
+
+/** A cube of display values: `size` on each axis, `size ** 3 * 4` bytes, red varying fastest. */
+export interface ColourGradeLut {
+  /** Lattice points along each axis. 32 and 33 are what grading tools export. */
+  readonly size: number;
+  /** `RGBA8`, `size ** 3 * 4` bytes, indexed `((b * size + g) * size + r) * 4`. */
+  readonly data: Uint8Array;
+}
+
+/**
+ * The lattice the placeholder is built at, and **two is exact rather than merely small**.
+ *
+ * Identity is a linear function and a trilinear fetch through a lattice whose corners hold their
+ * own coordinates reproduces a linear function exactly. So the texture bound when nothing is
+ * graded is the right answer if anything ever samples it, rather than an inert stand-in that
+ * happens not to be read — which is the same reasoning the ambient-occlusion and bloom
+ * placeholders give for being a real texture rather than an unbound unit.
+ */
+export const GRADE_PLACEHOLDER_SIZE = 2;
+
+/**
+ * The largest lattice accepted, because the cost is cubic and a caller will not feel it.
+ *
+ * 64 is a megabyte of texture; 128 would be eight. Refused by name rather than resampled, because
+ * a resample is a look the caller did not choose — and a grade that is quietly not the grade
+ * somebody authored is worse than one that will not load.
+ */
+export const MAX_GRADE_SIZE = 64;
+
+/**
+ * A table that changes nothing.
+ *
+ * Live code rather than a test fixture: it is what a frame with no grade has bound, and it is what
+ * a consumer starts from when building one by hand.
+ */
+export function identityGradeLut(size: number): ColourGradeLut {
+  const data = new Uint8Array(size * size * size * 4);
+  const last = size > 1 ? size - 1 : 1;
+  let at = 0;
+  /*
+   * Blue slowest, red fastest — the order a 3D texture is stored in, and the order the fetch
+   * assumes. Walking it the other way builds a table that is valid, filters correctly, and swaps
+   * the picture's colour axes, which reads as a bad export rather than as a packing bug.
+   */
+  for (let b = 0; b < size; b++) {
+    for (let g = 0; g < size; g++) {
+      for (let r = 0; r < size; r++) {
+        data[at] = Math.round((r / last) * 255);
+        data[at + 1] = Math.round((g / last) * 255);
+        data[at + 2] = Math.round((b / last) * 255);
+        data[at + 3] = 255;
+        at += 4;
+      }
+    }
+  }
+  return { size, data };
+}
+
+/**
+ * Refuse a table that is not one, at init, naming what was expected.
+ *
+ * **Fail fast and loud is the rule and this is where it applies**: a lookup table of the wrong
+ * length is a file read wrongly, and it still uploads, still filters and still draws a picture —
+ * one whose colours are a scrambled function of the right ones. Nothing downstream can tell.
+ */
+export function validateGradeLut(lut: ColourGradeLut): void {
+  if (!Number.isInteger(lut.size) || lut.size < 2) {
+    throw new Error(
+      `setColourGrade: a lookup table needs at least 2 lattice points a side, got ${lut.size}. ` +
+        'A single texel is a constant colour, not a grade.',
+    );
+  }
+  if (lut.size > MAX_GRADE_SIZE) {
+    throw new Error(
+      `setColourGrade: ${lut.size} lattice points a side is past the ceiling of ` +
+        `${MAX_GRADE_SIZE}, which is a megabyte of texture. Resample it yourself if that is ` +
+        'what you meant — this will not do it silently, because a resample is a look.',
+    );
+  }
+  const expected = lut.size ** 3 * 4;
+  if (lut.data.length !== expected) {
+    throw new Error(
+      `setColourGrade: a ${lut.size}-lattice table expects ${expected} bytes of RGBA8 and this ` +
+        `one has ${lut.data.length}. Red varies fastest, then green, then blue.`,
+    );
+  }
+}

package/src/render/compute.ts

@@ -0,0 +1,83 @@
+import { createHandleRegistry, definitionAt, type HandleRegistry } from './handleRegistry.ts';
+
+/**
+ * A compute definition a package contributes, and the two things it is handed.
+ *
+ * **This is `pass.ts` again, for the one stage that only one backend has.** A package that wants
+ * a radix sort, a light binner or a skinning kernel has nowhere to put it: the renderer's verb
+ * surface is fixed and nothing outside `render/` can add to it. `registerPass` answered that for
+ * drawing; this answers it for the stage before drawing.
+ */
+
+/**
+ * What a registered definition is handed once, at registration, to build its resources.
+ *
+ * **There is no WebGL2 arm, and that absence is the type saying so.** `PassDevice` is a union
+ * because both backends can draw. WebGL2 has no compute shaders — not "not yet", the language has
+ * none — so a second arm would be a shape a contributor could switch on and never reach.
+ * `Renderer.computeSupported` answers `false` there and `registerCompute` refuses in words.
+ *
+ * Tagged all the same, so that a second arm arriving later is a compile error at every
+ * contributor rather than a silent widening, and so this reads as the same shape as `PassDevice`
+ * to somebody who has just read that one.
+ */
+export type ComputeDevice = { readonly backend: 'webgpu'; readonly device: GPUDevice };
+
+/**
+ * What it is handed at each dispatch.
+ *
+ * **The engine opens the pass and hands it over, rather than handing over the command encoder.**
+ * A definition holding the encoder could open a compute pass while a render pass was open, which
+ * WebGPU forbids and which reports itself at `submit` rather than at the call that caused it —
+ * the failure shape the 2026-08-14 rule is about, where the result is no picture from a frame
+ * that recorded correctly. Handing over the pass keeps that invariant in one place instead of in
+ * every contributor.
+ *
+ * A definition that needs an encoder of its own for a readback still has one: it holds `device`
+ * from `init`, and a `copyBufferToBuffer` submitted afterwards sees this dispatch's result,
+ * because submission order is execution order.
+ */
+export type ComputeContext = { readonly backend: 'webgpu'; readonly pass: GPUComputePassEncoder };
+
+export interface ComputeDefinition {
+  /** For diagnostics, and for the label the backend gives the encoder and the pass. */
+  readonly label: string;
+  /** Build pipelines and buffers. Called once, when the definition is registered. */
+  init?(device: ComputeDevice): void;
+  /**
+   * Set a pipeline, set bind groups, and call `dispatchWorkgroups`.
+   *
+   * **The workgroup count is yours and does not cross the surface**, exactly as a contributed
+   * pass issues its own draw calls. The count comes from data the definition owns — a light
+   * count, a cluster count — so a renderer-side `(x, y, z)` would be one fact in two places, and
+   * the renderer's copy would be the one nobody updated.
+   *
+   * **Allocates nothing.** This is a per-frame path and the house rule about them binds a
+   * contributor exactly as it binds the renderer.
+   */
+  dispatch(ctx: ComputeContext): void;
+  /** Release what `init` built. Called on `unregisterCompute` and when the renderer is disposed. */
+  dispose?(device: ComputeDevice): void;
+}
+
+/**
+ * A registered definition, as the caller holds it.
+ *
+ * A slot and a generation packed into one number, for the reason `PassHandle` explains: a handle
+ * kept past `unregisterCompute` answers nothing rather than answering to whoever took the slot.
+ */
+export type ComputeHandle = number;
+
+export type ComputeRegistry = HandleRegistry<ComputeDefinition>;
+
+export function createComputeRegistry(): ComputeRegistry {
+  return createHandleRegistry<ComputeDefinition>();
+}
+
+/** The definition a handle names, or `undefined` if it names one that has been released. */
+export function computeAt(
+  registry: ComputeRegistry,
+  handle: ComputeHandle,
+): ComputeDefinition | undefined {
+  return definitionAt(registry, handle);
+}

package/src/render/contextLoss.ts

@@ -0,0 +1,50 @@
+/**
+ * Notice a lost drawing context, notice it coming back, and ask the browser for it.
+ *
+ * The engine owns the GL context, so it owns noticing both halves. A game reaching for
+ * `renderer.canvas.addEventListener('webglcontextlost')` would be the game reaching into
+ * the engine's internals.
+ *
+ * `preventDefault` is not politeness: it is the browser's signal that the page intends to
+ * restore rather than to die. Without it the context is gone for good and the player is
+ * looking at a black canvas that nothing will ever repaint.
+ *
+ * **The restore is a separate sink, and that is the point.** Routing it to `onLost` would
+ * report a fault at the moment the fault ended, which reads in a bug report as a device
+ * that lost its context twice. `NFD6QQ` is the report that proved the restore half was
+ * missing altogether: the promise `preventDefault` makes was made 29 s into a session on
+ * an Adreno 619, and nothing in either repository had ever been listening to keep it.
+ *
+ * Restoring is *not* the same as redrawing. Every resource the renderer holds is created
+ * in its constructor and `readonly` thereafter — the same reason a quality change is
+ * construction-time — so a listener that wants pixels again has to take the page through
+ * a reload. This function only makes the moment observable.
+ */
+/**
+ * Returns a detach function, which a renderer that can be torn down has to call.
+ *
+ * The listeners used to be anonymous and therefore unremovable. That is invisible in a
+ * game whose renderer lives as long as its page, and a leak in one that does not: a game
+ * embedded in a website is mounted and unmounted every time the player enters and leaves
+ * it, and each mount left a pair of listeners holding the previous renderer alive through
+ * their closures.
+ */
+export function attachContextLoss(
+  canvas: HTMLCanvasElement,
+  onLost: () => void,
+  onRestored: () => void,
+): () => void {
+  const lost = (event: Event): void => {
+    event.preventDefault();
+    onLost();
+  };
+  const restored = (): void => {
+    onRestored();
+  };
+  canvas.addEventListener('webglcontextlost', lost);
+  canvas.addEventListener('webglcontextrestored', restored);
+  return () => {
+    canvas.removeEventListener('webglcontextlost', lost);
+    canvas.removeEventListener('webglcontextrestored', restored);
+  };
+}

package/src/render/debugLines.ts

@@ -0,0 +1,411 @@
+import { createLineSegments } from './linePoints.ts';
+import type { LineSegments } from './linePoints.ts';
+import type { MeshData } from './mesh.ts';
+import type { ConvexShape } from '@driftengine/physics';
+import type { PhysicsWorld } from '@driftengine/physics';
+
+/**
+ * Debug geometry, as line segments the renderer already knows how to draw.
+ *
+ * **This is the generator and not a pass**, and that is the whole reason it is small: `drawLines`
+ * has shipped on both backends since the polyline batch landed, with a world-space width and a
+ * pixel floor so a distant line does not strobe. What was missing was anything that turns what you
+ * want to *see* — a mesh's normals, the colliders a body actually carries — into segments, so every
+ * consumer who wanted a normals key wrote the geometry themselves or, far more often, did not.
+ *
+ * **What its absence has cost, measured rather than supposed.** One consumer wrote geometry with
+ * downward normals four separate times: their roads, their ditch banks, their roof planes, and
+ * every building in their world lit inside out. Each was found by looking at a screenshot and
+ * wondering why tarmac was black at midday, because a flipped normal near a lamp is a dimmer
+ * surface rather than an absent one and only a directional light makes it plain. A key that draws
+ * normals turns each of those into a ten-second job.
+ *
+ * **Nothing here throws and nothing here allocates after construction.** A debug drawer that threw
+ * when it ran out of room would take the frame with it at exactly the moment somebody was trying to
+ * see what was wrong, which is the opposite of its job; so a segment past capacity is counted in
+ * `dropped` and discarded, and a consumer who cares reads that number and builds a bigger one.
+ */
+export class DebugLines {
+  readonly segments: LineSegments;
+  private overflow = 0;
+
+  constructor(capacity: number) {
+    if (!(capacity > 0)) throw new Error(`DebugLines: capacity must be positive, got ${capacity}`);
+    this.segments = createLineSegments(capacity);
+  }
+
+  /** Segments asked for since the last `clear` that there was no room for. */
+  get dropped(): number {
+    return this.overflow;
+  }
+
+  clear(): void {
+    this.segments.count = 0;
+    this.overflow = 0;
+  }
+
+  segment(ax: number, ay: number, az: number, bx: number, by: number, bz: number): void {
+    const at = this.segments.count;
+    if (at >= this.segments.capacity) {
+      this.overflow++;
+      return;
+    }
+    this.segments.from[at * 3] = ax;
+    this.segments.from[at * 3 + 1] = ay;
+    this.segments.from[at * 3 + 2] = az;
+    this.segments.to[at * 3] = bx;
+    this.segments.to[at * 3 + 1] = by;
+    this.segments.to[at * 3 + 2] = bz;
+    this.segments.count = at + 1;
+  }
+
+  /**
+   * A spike out of every vertex along its normal.
+   *
+   * `stride` skips vertices, because a mesh of a hundred thousand vertices is a hundred thousand
+   * segments and a screen with nothing legible on it. The default draws them all, which is right
+   * for the small piece of geometry somebody is actually staring at.
+   *
+   * **A mesh built from flat faces has four coincident normals per quad**, so what appears is one
+   * spike per corner rather than one per face, and that is the honest picture: the attribute is per
+   * vertex and this draws the attribute.
+   */
+  normals(mesh: MeshData, length = 0.25, stride = 1): void {
+    const count = mesh.positions.length / 3;
+    for (let v = 0; v < count; v += stride) {
+      const x = mesh.positions[v * 3] ?? 0;
+      const y = mesh.positions[v * 3 + 1] ?? 0;
+      const z = mesh.positions[v * 3 + 2] ?? 0;
+      this.segment(
+        x,
+        y,
+        z,
+        x + (mesh.normals[v * 3] ?? 0) * length,
+        y + (mesh.normals[v * 3 + 1] ?? 0) * length,
+        z + (mesh.normals[v * 3 + 2] ?? 0) * length,
+      );
+    }
+  }
+
+  /** The twelve edges of a world-axis box. */
+  box(cx: number, cy: number, cz: number, hx: number, hy: number, hz: number): void {
+    for (const [a, b] of BOX_EDGES) {
+      this.segment(
+        cx + hx * (a[0] ?? 0),
+        cy + hy * (a[1] ?? 0),
+        cz + hz * (a[2] ?? 0),
+        cx + hx * (b[0] ?? 0),
+        cy + hy * (b[1] ?? 0),
+        cz + hz * (b[2] ?? 0),
+      );
+    }
+  }
+
+  /** Three great circles, which is a sphere as far as an eye looking for one is concerned. */
+  sphere(cx: number, cy: number, cz: number, radius: number, points = 24): void {
+    this.circle(cx, cy, cz, radius, 1, 0, 0, 0, 0, 1, points);
+    this.circle(cx, cy, cz, radius, 1, 0, 0, 0, 1, 0, points);
+    this.circle(cx, cy, cz, radius, 0, 1, 0, 0, 0, 1, points);
+  }
+
+  /**
+   * A closed ring of `points` segments, in the plane the two unit vectors span.
+   *
+   * The basis is passed in rather than derived from an axis because every caller here already has
+   * one, and deriving a perpendicular from an axis has a degenerate case that a caller with a real
+   * basis does not need to think about.
+   */
+  circle(
+    cx: number,
+    cy: number,
+    cz: number,
+    radius: number,
+    ux: number,
+    uy: number,
+    uz: number,
+    vx: number,
+    vy: number,
+    vz: number,
+    points = 24,
+  ): void {
+    let px = cx + ux * radius;
+    let py = cy + uy * radius;
+    let pz = cz + uz * radius;
+    for (let i = 1; i <= points; i++) {
+      const angle = (i / points) * Math.PI * 2;
+      const c = Math.cos(angle) * radius;
+      const s = Math.sin(angle) * radius;
+      const nx = cx + ux * c + vx * s;
+      const ny = cy + uy * c + vy * s;
+      const nz = cz + uz * c + vz * s;
+      this.segment(px, py, pz, nx, ny, nz);
+      px = nx;
+      py = ny;
+      pz = nz;
+    }
+  }
+
+  /**
+   * One collider, placed by a body's position and orientation.
+   *
+   * **Dispatched on what the shape *is* rather than on a stored kind**, which is the same
+   * discrimination the narrow phase makes: a `sideRadius` is a cylinder, a `triangles` is a mesh, a
+   * `radius` over one point is a sphere and over two is a capsule, and anything with faces is a
+   * polytope drawn along its own face loops. A shape that grows a new representation appears here
+   * as its polytope hull rather than as nothing, which is the failure worth having.
+   */
+  shape(
+    shape: ConvexShape,
+    px: number,
+    py: number,
+    pz: number,
+    qx = 0,
+    qy = 0,
+    qz = 0,
+    qw = 1,
+  ): void {
+    const points = shape.vertices.length / 3;
+    const at = (i: number, out: number[]): void => {
+      rotate(
+        shape.vertices[i * 3] ?? 0,
+        shape.vertices[i * 3 + 1] ?? 0,
+        shape.vertices[i * 3 + 2] ?? 0,
+        qx,
+        qy,
+        qz,
+        qw,
+        out,
+      );
+      out[0] = (out[0] ?? 0) + px;
+      out[1] = (out[1] ?? 0) + py;
+      out[2] = (out[2] ?? 0) + pz;
+    };
+
+    const mesh = shape.triangles;
+    if (mesh !== undefined) {
+      for (let t = 0; t < mesh.triangleCount; t++) {
+        for (let e = 0; e < 3; e++) {
+          const i = mesh.indices[t * 3 + e] ?? 0;
+          const j = mesh.indices[t * 3 + ((e + 1) % 3)] ?? 0;
+          /* Each interior edge belongs to two triangles; drawing it once is the same picture at
+             half the segments, which matters when the capacity is what stops the drawing. */
+          if (i > j) continue;
+          rotate(
+            mesh.positions[i * 3] ?? 0,
+            mesh.positions[i * 3 + 1] ?? 0,
+            mesh.positions[i * 3 + 2] ?? 0,
+            qx,
+            qy,
+            qz,
+            qw,
+            A,
+          );
+          rotate(
+            mesh.positions[j * 3] ?? 0,
+            mesh.positions[j * 3 + 1] ?? 0,
+            mesh.positions[j * 3 + 2] ?? 0,
+            qx,
+            qy,
+            qz,
+            qw,
+            B,
+          );
+          this.segment(
+            (A[0] ?? 0) + px,
+            (A[1] ?? 0) + py,
+            (A[2] ?? 0) + pz,
+            (B[0] ?? 0) + px,
+            (B[1] ?? 0) + py,
+            (B[2] ?? 0) + pz,
+          );
+        }
+      }
+      return;
+    }
+
+    if (points === 1) {
+      at(0, A);
+      this.sphere(A[0] ?? 0, A[1] ?? 0, A[2] ?? 0, shape.radius);
+      return;
+    }
+
+    if (points === 2 && (shape.radius > 0 || shape.sideRadius > 0)) {
+      at(0, A);
+      at(1, B);
+      const round = shape.sideRadius > 0 ? shape.sideRadius : shape.radius;
+      basis(A, B, U, V);
+      if (shape.sideRadius > 0) {
+        /* A cylinder: two flat caps and a straight side, with a sharp rim between them. */
+        this.circle(
+          A[0] ?? 0,
+          A[1] ?? 0,
+          A[2] ?? 0,
+          round,
+          U[0] ?? 0,
+          U[1] ?? 0,
+          U[2] ?? 0,
+          V[0] ?? 0,
+          V[1] ?? 0,
+          V[2] ?? 0,
+        );
+        this.circle(
+          B[0] ?? 0,
+          B[1] ?? 0,
+          B[2] ?? 0,
+          round,
+          U[0] ?? 0,
+          U[1] ?? 0,
+          U[2] ?? 0,
+          V[0] ?? 0,
+          V[1] ?? 0,
+          V[2] ?? 0,
+        );
+      } else {
+        /* A capsule: a ball at each end, which is what its rounding actually is. */
+        this.sphere(A[0] ?? 0, A[1] ?? 0, A[2] ?? 0, round);
+        this.sphere(B[0] ?? 0, B[1] ?? 0, B[2] ?? 0, round);
+      }
+      for (const [sx, sy] of SIDE_ANGLES) {
+        const ox = (U[0] ?? 0) * sx * round + (V[0] ?? 0) * sy * round;
+        const oy = (U[1] ?? 0) * sx * round + (V[1] ?? 0) * sy * round;
+        const oz = (U[2] ?? 0) * sx * round + (V[2] ?? 0) * sy * round;
+        this.segment(
+          (A[0] ?? 0) + ox,
+          (A[1] ?? 0) + oy,
+          (A[2] ?? 0) + oz,
+          (B[0] ?? 0) + ox,
+          (B[1] ?? 0) + oy,
+          (B[2] ?? 0) + oz,
+        );
+      }
+      return;
+    }
+
+    const faces = shape.faceVertexStart.length - 1;
+    for (let f = 0; f < faces; f++) {
+      const start = shape.faceVertexStart[f] ?? 0;
+      const end = shape.faceVertexStart[f + 1] ?? 0;
+      for (let k = start; k < end; k++) {
+        const i = shape.faceVertexIndices[k] ?? 0;
+        const j = shape.faceVertexIndices[k + 1 === end ? start : k + 1] ?? 0;
+        /* Every edge is in two face loops, once each way round. Keeping the ascending one draws it
+           exactly once. */
+        if (i > j) continue;
+        at(i, A);
+        at(j, B);
+        this.segment(A[0] ?? 0, A[1] ?? 0, A[2] ?? 0, B[0] ?? 0, B[1] ?? 0, B[2] ?? 0);
+      }
+    }
+  }
+
+  /**
+   * Every body's collider in a world, where it is this tick.
+   *
+   * The other half of the key the report asked for. Bodies with no shape are skipped rather than
+   * refused: a world may hold one for a frame while it is being built.
+   */
+  colliders(world: PhysicsWorld): void {
+    const bodies = world.bodies;
+    for (let i = 0; i < bodies.count; i++) {
+      const shape = bodies.shape[i];
+      if (shape === undefined) continue;
+      this.shape(
+        shape,
+        bodies.posX[i] ?? 0,
+        bodies.posY[i] ?? 0,
+        bodies.posZ[i] ?? 0,
+        bodies.rotX[i] ?? 0,
+        bodies.rotY[i] ?? 0,
+        bodies.rotZ[i] ?? 0,
+        bodies.rotW[i] ?? 1,
+      );
+    }
+  }
+}
+
+/** Scratch, at module scope because a debug frame draws thousands of these. */
+const A: number[] = [0, 0, 0];
+const B: number[] = [0, 0, 0];
+const U: number[] = [0, 0, 0];
+const V: number[] = [0, 0, 0];
+
+/** Where the four side lines of a capsule or cylinder sit around its axis. */
+const SIDE_ANGLES: readonly (readonly [number, number])[] = [
+  [1, 0],
+  [0, 1],
+  [-1, 0],
+  [0, -1],
+];
+
+const BOX_EDGES: readonly (readonly [readonly number[], readonly number[]])[] = (() => {
+  const corners: number[][] = [];
+  for (const x of [-1, 1])
+    for (const y of [-1, 1]) for (const z of [-1, 1]) corners.push([x, y, z]);
+  const edges: [number[], number[]][] = [];
+  for (let i = 0; i < corners.length; i++) {
+    for (let j = i + 1; j < corners.length; j++) {
+      const a = corners[i] as number[];
+      const b = corners[j] as number[];
+      let differing = 0;
+      for (let k = 0; k < 3; k++) if (a[k] !== b[k]) differing++;
+      if (differing === 1) edges.push([a, b]);
+    }
+  }
+  return edges;
+})();
+
+/** `q * v * q⁻¹`, the standard two-cross form, into `out`. */
+function rotate(
+  x: number,
+  y: number,
+  z: number,
+  qx: number,
+  qy: number,
+  qz: number,
+  qw: number,
+  out: number[],
+): void {
+  const tx = 2 * (qy * z - qz * y);
+  const ty = 2 * (qz * x - qx * z);
+  const tz = 2 * (qx * y - qy * x);
+  out[0] = x + qw * tx + (qy * tz - qz * ty);
+  out[1] = y + qw * ty + (qz * tx - qx * tz);
+  out[2] = z + qw * tz + (qx * ty - qy * tx);
+}
+
+/**
+ * Two unit vectors perpendicular to the segment `a → b`, and to each other.
+ *
+ * The perpendicular is taken against whichever world axis the segment points along least, which is
+ * what stops the cross product collapsing for an axis-aligned shape — and every capsule and
+ * cylinder anybody builds is axis-aligned, so the degenerate case is the common one rather than the
+ * exotic one.
+ */
+function basis(a: number[], b: number[], u: number[], v: number[]): void {
+  let ax = (b[0] ?? 0) - (a[0] ?? 0);
+  let ay = (b[1] ?? 0) - (a[1] ?? 0);
+  let az = (b[2] ?? 0) - (a[2] ?? 0);
+  const length = Math.hypot(ax, ay, az) || 1;
+  ax /= length;
+  ay /= length;
+  az /= length;
+  const absX = Math.abs(ax);
+  const absY = Math.abs(ay);
+  const absZ = Math.abs(az);
+  const px = absX <= absY && absX <= absZ ? 1 : 0;
+  const py = absY < absX && absY <= absZ ? 1 : 0;
+  const pz = px === 0 && py === 0 ? 1 : 0;
+  let ux = ay * pz - az * py;
+  let uy = az * px - ax * pz;
+  let uz = ax * py - ay * px;
+  const ulength = Math.hypot(ux, uy, uz) || 1;
+  ux /= ulength;
+  uy /= ulength;
+  uz /= ulength;
+  u[0] = ux;
+  u[1] = uy;
+  u[2] = uz;
+  v[0] = ay * uz - az * uy;
+  v[1] = az * ux - ax * uz;
+  v[2] = ax * uy - ay * ux;
+}