@forgeax/engine-math 0.0.0-dev.8d955ade1c79

package/src/box2.ts

@@ -0,0 +1,168 @@
+// box2.ts — 2D axis-aligned bounding box namespace (P12 / bounding_2d).
+//
+// Storage layout: Float32Array length 4 [minX, minY, maxX, maxY]. The surface
+// mirrors box3 so an AI can transfer broad-phase code between dimensions without
+// learning a second object model.
+
+import type { Circle2Like } from './circle2';
+import type { Vec2, Vec2Like } from './types';
+
+/** 2D AABB storage: [minX, minY, maxX, maxY]. */
+export type Box2 = Float32Array & { readonly __box2: void };
+
+/** Readable 2D AABB input. */
+export type Box2Like = ArrayLike<number>;
+
+/** Create a 2D AABB. The default is the inverted-infinity empty box. */
+export function create(
+  minX = Number.POSITIVE_INFINITY,
+  minY = Number.POSITIVE_INFINITY,
+  maxX = Number.NEGATIVE_INFINITY,
+  maxY = Number.NEGATIVE_INFINITY,
+): Box2 {
+  return Float32Array.of(minX, minY, maxX, maxY) as Box2;
+}
+
+/** Create an AABB from its center and non-negative half-size. */
+export function fromCenter(out: Box2, center: Vec2Like, halfSize: Vec2Like): Box2 {
+  const cx = center[0] as number;
+  const cy = center[1] as number;
+  const hx = Math.abs(halfSize[0] as number);
+  const hy = Math.abs(halfSize[1] as number);
+  out[0] = cx - hx;
+  out[1] = cy - hy;
+  out[2] = cx + hx;
+  out[3] = cy + hy;
+  return out;
+}
+
+/** Build the tightest AABB containing the given points. */
+export function fromPoints(out: Box2, points: readonly Vec2Like[]): Box2 {
+  out[0] = Number.POSITIVE_INFINITY;
+  out[1] = Number.POSITIVE_INFINITY;
+  out[2] = Number.NEGATIVE_INFINITY;
+  out[3] = Number.NEGATIVE_INFINITY;
+  for (let i = 0; i < points.length; i++) {
+    const point = points[i] as Vec2Like;
+    const x = point[0] as number;
+    const y = point[1] as number;
+    if (x < (out[0] as number)) out[0] = x;
+    if (y < (out[1] as number)) out[1] = y;
+    if (x > (out[2] as number)) out[2] = x;
+    if (y > (out[3] as number)) out[3] = y;
+  }
+  return out;
+}
+
+/** Write the box center to out. Empty boxes produce non-finite values. */
+export function center(out: Vec2, box: Box2Like): Vec2 {
+  out[0] = ((box[0] as number) + (box[2] as number)) * 0.5;
+  out[1] = ((box[1] as number) + (box[3] as number)) * 0.5;
+  return out;
+}
+
+/** Write the box half-size to out. */
+export function halfSize(out: Vec2, box: Box2Like): Vec2 {
+  out[0] = ((box[2] as number) - (box[0] as number)) * 0.5;
+  out[1] = ((box[3] as number) - (box[1] as number)) * 0.5;
+  return out;
+}
+
+/** Write the closest point in the box to point. */
+export function closestPoint(out: Vec2, box: Box2Like, point: Vec2Like): Vec2 {
+  const x = point[0] as number;
+  const y = point[1] as number;
+  const minX = box[0] as number;
+  const minY = box[1] as number;
+  const maxX = box[2] as number;
+  const maxY = box[3] as number;
+  out[0] = x < minX ? minX : x > maxX ? maxX : x;
+  out[1] = y < minY ? minY : y > maxY ? maxY : y;
+  return out;
+}
+
+/** True when point is inside the box, including its boundary. */
+export function containsPoint(box: Box2Like, point: Vec2Like): boolean {
+  const x = point[0] as number;
+  const y = point[1] as number;
+  return (
+    x >= (box[0] as number) &&
+    x <= (box[2] as number) &&
+    y >= (box[1] as number) &&
+    y <= (box[3] as number)
+  );
+}
+
+/** True when the box completely contains other, including touching edges. */
+export function containsBox(box: Box2Like, other: Box2Like): boolean {
+  return (
+    (other[0] as number) >= (box[0] as number) &&
+    (other[1] as number) >= (box[1] as number) &&
+    (other[2] as number) <= (box[2] as number) &&
+    (other[3] as number) <= (box[3] as number)
+  );
+}
+
+/** True when two boxes overlap, including touching edges. */
+export function intersectsBox(a: Box2Like, b: Box2Like): boolean {
+  return (
+    (a[2] as number) >= (b[0] as number) &&
+    (a[0] as number) <= (b[2] as number) &&
+    (a[3] as number) >= (b[1] as number) &&
+    (a[1] as number) <= (b[3] as number)
+  );
+}
+
+/** True when a box and a circle overlap, including tangent contact. */
+export function intersectsCircle(box: Box2Like, circle: Circle2Like): boolean {
+  const cx = circle[0] as number;
+  const cy = circle[1] as number;
+  const radius = circle[2] as number;
+  if (radius < 0) return false;
+  const closestX =
+    cx < (box[0] as number)
+      ? (box[0] as number)
+      : cx > (box[2] as number)
+        ? (box[2] as number)
+        : cx;
+  const closestY =
+    cy < (box[1] as number)
+      ? (box[1] as number)
+      : cy > (box[3] as number)
+        ? (box[3] as number)
+        : cy;
+  const dx = cx - closestX;
+  const dy = cy - closestY;
+  return dx * dx + dy * dy <= radius * radius;
+}
+
+/** Return the smallest box containing a and b. */
+export function merge(out: Box2, a: Box2Like, b: Box2Like): Box2 {
+  out[0] = Math.min(a[0] as number, b[0] as number);
+  out[1] = Math.min(a[1] as number, b[1] as number);
+  out[2] = Math.max(a[2] as number, b[2] as number);
+  out[3] = Math.max(a[3] as number, b[3] as number);
+  return out;
+}
+
+/** Grow the box by a non-negative amount on each side. */
+export function grow(out: Box2, box: Box2Like, amount: Vec2Like): Box2 {
+  const x = Math.abs(amount[0] as number);
+  const y = Math.abs(amount[1] as number);
+  out[0] = (box[0] as number) - x;
+  out[1] = (box[1] as number) - y;
+  out[2] = (box[2] as number) + x;
+  out[3] = (box[3] as number) + y;
+  return out;
+}
+
+/** Shrink the box by a non-negative amount on each side. */
+export function shrink(out: Box2, box: Box2Like, amount: Vec2Like): Box2 {
+  const x = Math.abs(amount[0] as number);
+  const y = Math.abs(amount[1] as number);
+  out[0] = (box[0] as number) + x;
+  out[1] = (box[1] as number) + y;
+  out[2] = (box[2] as number) - x;
+  out[3] = (box[3] as number) - y;
+  return out;
+}

package/src/box3.ts

@@ -0,0 +1,372 @@
+// box3.ts — axis-aligned bounding box namespace (M3 / w7).
+//
+// 5-function surface (plan-tasks.json w7): create / expandByPoint / containsPoint / intersectsBox / fromPoints.
+//
+// Storage layout: Float32Array length 6 [minX, minY, minZ, maxX, maxY, maxZ].
+// Default state is "empty box" using the standard inverted-infinity convention
+// (min = +Infinity, max = -Infinity) so `expandByPoint` on any finite point
+// collapses to a zero-volume box containing exactly that point; this mirrors
+// three.js Box3.makeEmpty + glam/wgpu-matrix conventions (research knowledge-base
+// gl-matrix-overview §degenerate-anchor equivalent for AABB).
+//
+// Design locks:
+//   - branded `Box3` Float32Array local to this module; cast funneled through `create`
+//   - pure-function / out-param style consistent with vec3 / mat4;
+//   - `expandByPoint` / `fromPoints` write to `out` in place and return it (aliasing-safe);
+//   - `containsPoint` / `intersectsBox` are boundary-inclusive (standard AABB semantics).
+//
+// Related: requirements §AC-16 (Box3 / Sphere pure functions);
+//          plan-strategy M3 range + D-P5 procedural geometry (Box3 backs future frustum culling);
+//          plan-tasks.json w7 acceptanceCheck.
+
+import type { Mat4Like, Vec3Like } from './types';
+
+/**
+ * Box3 storage: Float32Array length 6 [minX, minY, minZ, maxX, maxY, maxZ].
+ * Local brand (not part of the seven-piece SSOT because bounding volumes are
+ * neither linear-algebra primitives nor ECS POD carriers; types.ts SSOT is
+ * reserved for vec/mat/quat/color).
+ */
+export type Box3 = Float32Array & { readonly __box3: void };
+
+/**
+ * Box3 readable input: ArrayLike<number> of length 6 (ordering identical to Box3).
+ */
+export type Box3Like = ArrayLike<number>;
+
+/**
+ * Create a Box3. Defaults to the "empty" box (min=+Inf, max=-Inf) so the first
+ * `expandByPoint` call collapses to a zero-volume box at the input point.
+ */
+export function create(
+  minX: number = Number.POSITIVE_INFINITY,
+  minY: number = Number.POSITIVE_INFINITY,
+  minZ: number = Number.POSITIVE_INFINITY,
+  maxX: number = Number.NEGATIVE_INFINITY,
+  maxY: number = Number.NEGATIVE_INFINITY,
+  maxZ: number = Number.NEGATIVE_INFINITY,
+): Box3 {
+  return Float32Array.of(minX, minY, minZ, maxX, maxY, maxZ) as Box3;
+}
+
+/**
+ * out ∪= point: grow min / max so `point` lies inside (boundary inclusive). Returns out.
+ * Works correctly from the default empty box (inverted-infinity) — the first call
+ * collapses both min and max to `point`.
+ */
+export function expandByPoint(out: Box3, point: Vec3Like): Box3 {
+  const px = point[0] as number;
+  const py = point[1] as number;
+  const pz = point[2] as number;
+  if (px < (out[0] as number)) out[0] = px;
+  if (py < (out[1] as number)) out[1] = py;
+  if (pz < (out[2] as number)) out[2] = pz;
+  if (px > (out[3] as number)) out[3] = px;
+  if (py > (out[4] as number)) out[4] = py;
+  if (pz > (out[5] as number)) out[5] = pz;
+  return out;
+}
+
+/**
+ * True when `point` is inside `box` (boundary inclusive). An empty box
+ * (min > max on any axis) contains no points.
+ */
+export function containsPoint(box: Box3Like, point: Vec3Like): boolean {
+  const px = point[0] as number;
+  const py = point[1] as number;
+  const pz = point[2] as number;
+  return (
+    px >= (box[0] as number) &&
+    px <= (box[3] as number) &&
+    py >= (box[1] as number) &&
+    py <= (box[4] as number) &&
+    pz >= (box[2] as number) &&
+    pz <= (box[5] as number)
+  );
+}
+
+/**
+ * True when `a` and `b` overlap on every axis (boundary inclusive — touching
+ * faces intersect). Two empty boxes do not intersect.
+ */
+export function intersectsBox(a: Box3Like, b: Box3Like): boolean {
+  return (
+    (a[3] as number) >= (b[0] as number) &&
+    (a[0] as number) <= (b[3] as number) &&
+    (a[4] as number) >= (b[1] as number) &&
+    (a[1] as number) <= (b[4] as number) &&
+    (a[5] as number) >= (b[2] as number) &&
+    (a[2] as number) <= (b[5] as number)
+  );
+}
+
+/**
+ * Build the tightest AABB enclosing `points`. Writes to `out` in place and
+ * returns it. Empty `points` leaves `out` as the inverted-infinity empty box.
+ */
+export function fromPoints(out: Box3, points: readonly Vec3Like[]): Box3 {
+  out[0] = Number.POSITIVE_INFINITY;
+  out[1] = Number.POSITIVE_INFINITY;
+  out[2] = Number.POSITIVE_INFINITY;
+  out[3] = Number.NEGATIVE_INFINITY;
+  out[4] = Number.NEGATIVE_INFINITY;
+  out[5] = Number.NEGATIVE_INFINITY;
+  for (let i = 0; i < points.length; i++) {
+    const p = points[i] as Vec3Like;
+    const px = p[0] as number;
+    const py = p[1] as number;
+    const pz = p[2] as number;
+    if (px < (out[0] as number)) out[0] = px;
+    if (py < (out[1] as number)) out[1] = py;
+    if (pz < (out[2] as number)) out[2] = pz;
+    if (px > (out[3] as number)) out[3] = px;
+    if (py > (out[4] as number)) out[4] = py;
+    if (pz > (out[5] as number)) out[5] = pz;
+  }
+  return out;
+}
+
+/**
+ * Build the tightest AABB enclosing flattened xyz `positions` (tight-packed,
+ * 3 floats per vertex). Writes to `out` in place and returns it.
+ *
+ * `positions` must have at least 3 elements to produce a non-empty box.
+ * Fewer than 3 elements leaves `out` as the inverted-infinity empty box
+ * (identical to `create()` default).
+ *
+ * Trailing elements beyond the last complete triplet are read verbatim
+ * (undefined → NaN), matching the legacy `aabbFromPositions` behaviour
+ * this function replaces.
+ *
+ * Related: `fromPoints` for `Vec3Like[]` input.
+ */
+export function fromPositions(out: Box3, positions: ArrayLike<number>): Box3 {
+  out[0] = Number.POSITIVE_INFINITY;
+  out[1] = Number.POSITIVE_INFINITY;
+  out[2] = Number.POSITIVE_INFINITY;
+  out[3] = Number.NEGATIVE_INFINITY;
+  out[4] = Number.NEGATIVE_INFINITY;
+  out[5] = Number.NEGATIVE_INFINITY;
+  if (positions.length < 3) return out;
+  let minX = positions[0] as number;
+  let minY = positions[1] as number;
+  let minZ = positions[2] as number;
+  let maxX = minX;
+  let maxY = minY;
+  let maxZ = minZ;
+  for (let i = 3; i < positions.length; i += 3) {
+    const x = positions[i] as number;
+    const y = positions[i + 1] as number;
+    const z = positions[i + 2] as number;
+    if (x < minX) minX = x;
+    if (y < minY) minY = y;
+    if (z < minZ) minZ = z;
+    if (x > maxX) maxX = x;
+    if (y > maxY) maxY = y;
+    if (z > maxZ) maxZ = z;
+  }
+  out[0] = minX;
+  out[1] = minY;
+  out[2] = minZ;
+  out[3] = maxX;
+  out[4] = maxY;
+  out[5] = maxZ;
+  return out;
+}
+
+/**
+ * Transform an AABB by a 4x4 matrix using the conservative 8-corner method.
+ *
+ * Each of the 8 corners (all min/max combinations) is transformed by `m` as a
+ * homogeneous point (w=1), then a new AABB is computed that tightly encloses
+ * all 8 transformed points. This is always conservative — the output AABB is
+ * guaranteed to contain the true transformed volume (no false culling).
+ *
+ * Returns `out`. Aliasing-safe: `box` and `out` may be the same reference.
+ *
+ * @example
+ * ```ts
+ * import { box3, mat4 } from '@forgeax/engine-math';
+ * const box = box3.create(-1, -1, -1, 1, 1, 1);
+ * const xform = mat4.create();
+ * mat4.fromTranslation(xform, [5, 0, 0]);
+ * box3.transformBox3(box, box, xform);
+ * ```
+ */
+export function transformBox3(out: Box3, box: Box3Like, m: Mat4Like): Box3 {
+  const bx = box[0] as number;
+  const by = box[1] as number;
+  const bz = box[2] as number;
+  const bX = box[3] as number;
+  const bY = box[4] as number;
+  const bZ = box[5] as number;
+
+  const m00 = m[0] as number;
+  const m01 = m[1] as number;
+  const m02 = m[2] as number;
+  const m03 = m[3] as number;
+  const m10 = m[4] as number;
+  const m11 = m[5] as number;
+  const m12 = m[6] as number;
+  const m13 = m[7] as number;
+  const m20 = m[8] as number;
+  const m21 = m[9] as number;
+  const m22 = m[10] as number;
+  const m23 = m[11] as number;
+  const m30 = m[12] as number;
+  const m31 = m[13] as number;
+  const m32 = m[14] as number;
+  const m33 = m[15] as number;
+
+  // Corner 0: (bx, by, bz)
+  let x = m00 * bx + m10 * by + m20 * bz + m30;
+  let y = m01 * bx + m11 * by + m21 * bz + m31;
+  let z = m02 * bx + m12 * by + m22 * bz + m32;
+  let w = m03 * bx + m13 * by + m23 * bz + m33;
+  if (w !== 0) {
+    const iw = 1 / w;
+    x *= iw;
+    y *= iw;
+    z *= iw;
+  }
+  let minX = x,
+    maxX = x,
+    minY = y,
+    maxY = y,
+    minZ = z,
+    maxZ = z;
+
+  // Corner 1: (bX, by, bz)
+  x = m00 * bX + m10 * by + m20 * bz + m30;
+  y = m01 * bX + m11 * by + m21 * bz + m31;
+  z = m02 * bX + m12 * by + m22 * bz + m32;
+  w = m03 * bX + m13 * by + m23 * bz + m33;
+  if (w !== 0) {
+    const iw = 1 / w;
+    x *= iw;
+    y *= iw;
+    z *= iw;
+  }
+  if (x < minX) minX = x;
+  if (x > maxX) maxX = x;
+  if (y < minY) minY = y;
+  if (y > maxY) maxY = y;
+  if (z < minZ) minZ = z;
+  if (z > maxZ) maxZ = z;
+
+  // Corner 2: (bx, bY, bz)
+  x = m00 * bx + m10 * bY + m20 * bz + m30;
+  y = m01 * bx + m11 * bY + m21 * bz + m31;
+  z = m02 * bx + m12 * bY + m22 * bz + m32;
+  w = m03 * bx + m13 * bY + m23 * bz + m33;
+  if (w !== 0) {
+    const iw = 1 / w;
+    x *= iw;
+    y *= iw;
+    z *= iw;
+  }
+  if (x < minX) minX = x;
+  if (x > maxX) maxX = x;
+  if (y < minY) minY = y;
+  if (y > maxY) maxY = y;
+  if (z < minZ) minZ = z;
+  if (z > maxZ) maxZ = z;
+
+  // Corner 3: (bX, bY, bz)
+  x = m00 * bX + m10 * bY + m20 * bz + m30;
+  y = m01 * bX + m11 * bY + m21 * bz + m31;
+  z = m02 * bX + m12 * bY + m22 * bz + m32;
+  w = m03 * bX + m13 * bY + m23 * bz + m33;
+  if (w !== 0) {
+    const iw = 1 / w;
+    x *= iw;
+    y *= iw;
+    z *= iw;
+  }
+  if (x < minX) minX = x;
+  if (x > maxX) maxX = x;
+  if (y < minY) minY = y;
+  if (y > maxY) maxY = y;
+  if (z < minZ) minZ = z;
+  if (z > maxZ) maxZ = z;
+
+  // Corner 4: (bx, by, bZ)
+  x = m00 * bx + m10 * by + m20 * bZ + m30;
+  y = m01 * bx + m11 * by + m21 * bZ + m31;
+  z = m02 * bx + m12 * by + m22 * bZ + m32;
+  w = m03 * bx + m13 * by + m23 * bZ + m33;
+  if (w !== 0) {
+    const iw = 1 / w;
+    x *= iw;
+    y *= iw;
+    z *= iw;
+  }
+  if (x < minX) minX = x;
+  if (x > maxX) maxX = x;
+  if (y < minY) minY = y;
+  if (y > maxY) maxY = y;
+  if (z < minZ) minZ = z;
+  if (z > maxZ) maxZ = z;
+
+  // Corner 5: (bX, by, bZ)
+  x = m00 * bX + m10 * by + m20 * bZ + m30;
+  y = m01 * bX + m11 * by + m21 * bZ + m31;
+  z = m02 * bX + m12 * by + m22 * bZ + m32;
+  w = m03 * bX + m13 * by + m23 * bZ + m33;
+  if (w !== 0) {
+    const iw = 1 / w;
+    x *= iw;
+    y *= iw;
+    z *= iw;
+  }
+  if (x < minX) minX = x;
+  if (x > maxX) maxX = x;
+  if (y < minY) minY = y;
+  if (y > maxY) maxY = y;
+  if (z < minZ) minZ = z;
+  if (z > maxZ) maxZ = z;
+
+  // Corner 6: (bx, bY, bZ)
+  x = m00 * bx + m10 * bY + m20 * bZ + m30;
+  y = m01 * bx + m11 * bY + m21 * bZ + m31;
+  z = m02 * bx + m12 * bY + m22 * bZ + m32;
+  w = m03 * bx + m13 * bY + m23 * bZ + m33;
+  if (w !== 0) {
+    const iw = 1 / w;
+    x *= iw;
+    y *= iw;
+    z *= iw;
+  }
+  if (x < minX) minX = x;
+  if (x > maxX) maxX = x;
+  if (y < minY) minY = y;
+  if (y > maxY) maxY = y;
+  if (z < minZ) minZ = z;
+  if (z > maxZ) maxZ = z;
+
+  // Corner 7: (bX, bY, bZ)
+  x = m00 * bX + m10 * bY + m20 * bZ + m30;
+  y = m01 * bX + m11 * bY + m21 * bZ + m31;
+  z = m02 * bX + m12 * bY + m22 * bZ + m32;
+  w = m03 * bX + m13 * bY + m23 * bZ + m33;
+  if (w !== 0) {
+    const iw = 1 / w;
+    x *= iw;
+    y *= iw;
+    z *= iw;
+  }
+  if (x < minX) minX = x;
+  if (x > maxX) maxX = x;
+  if (y < minY) minY = y;
+  if (y > maxY) maxY = y;
+  if (z < minZ) minZ = z;
+  if (z > maxZ) maxZ = z;
+
+  out[0] = minX;
+  out[1] = minY;
+  out[2] = minZ;
+  out[3] = maxX;
+  out[4] = maxY;
+  out[5] = maxZ;
+  return out;
+}

package/src/circle2.ts

@@ -0,0 +1,134 @@
+// circle2.ts — 2D bounding-circle namespace (P12 / bounding_2d).
+
+import * as box2 from './box2';
+import type { Vec2, Vec2Like } from './types';
+
+/** 2D bounding circle storage: Float32Array [centerX, centerY, radius]. */
+export type Circle2 = Float32Array & { readonly __circle2: void };
+
+/** Readable 2D bounding-circle input. */
+export type Circle2Like = ArrayLike<number>;
+
+/** Create a bounding circle. Negative radius is clamped to zero. */
+export function create(cx = 0, cy = 0, radius = 0): Circle2 {
+  return Float32Array.of(cx, cy, radius < 0 ? 0 : radius) as Circle2;
+}
+
+/** Build a circle centered at the point-cloud AABB center and enclosing all points. */
+export function fromPoints(out: Circle2, points: readonly Vec2Like[]): Circle2 {
+  if (points.length === 0) {
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = -1;
+    return out;
+  }
+  const bounds = box2.create();
+  box2.fromPoints(bounds, points);
+  const cx = ((bounds[0] as number) + (bounds[2] as number)) * 0.5;
+  const cy = ((bounds[1] as number) + (bounds[3] as number)) * 0.5;
+  let radiusSq = 0;
+  for (let i = 0; i < points.length; i++) {
+    const point = points[i] as Vec2Like;
+    const dx = (point[0] as number) - cx;
+    const dy = (point[1] as number) - cy;
+    const distanceSq = dx * dx + dy * dy;
+    if (distanceSq > radiusSq) radiusSq = distanceSq;
+  }
+  out[0] = cx;
+  out[1] = cy;
+  out[2] = Math.sqrt(radiusSq);
+  return out;
+}
+
+/** Build the smallest AABB containing the circle. */
+export function toBox(out: box2.Box2, circle: Circle2Like): box2.Box2 {
+  const cx = circle[0] as number;
+  const cy = circle[1] as number;
+  const radius = circle[2] as number;
+  out[0] = cx - radius;
+  out[1] = cy - radius;
+  out[2] = cx + radius;
+  out[3] = cy + radius;
+  return out;
+}
+
+/** Write the circle center to out. */
+export function center(out: Vec2, circle: Circle2Like): Vec2 {
+  out[0] = circle[0] as number;
+  out[1] = circle[1] as number;
+  return out;
+}
+
+/** Return the circle radius. */
+export function radius(circle: Circle2Like): number {
+  return circle[2] as number;
+}
+
+/** Write the closest point in the circle to point. */
+export function closestPoint(out: Vec2, circle: Circle2Like, point: Vec2Like): Vec2 {
+  const dx = (point[0] as number) - (circle[0] as number);
+  const dy = (point[1] as number) - (circle[1] as number);
+  const distanceSq = dx * dx + dy * dy;
+  const r = circle[2] as number;
+  if (r < 0) {
+    out[0] = circle[0] as number;
+    out[1] = circle[1] as number;
+    return out;
+  }
+  if (distanceSq <= r * r || distanceSq < 1e-12) {
+    out[0] = point[0] as number;
+    out[1] = point[1] as number;
+    return out;
+  }
+  const scale = r / Math.sqrt(distanceSq);
+  out[0] = (circle[0] as number) + dx * scale;
+  out[1] = (circle[1] as number) + dy * scale;
+  return out;
+}
+
+/** True when point is inside the circle, including its boundary. */
+export function containsPoint(circle: Circle2Like, point: Vec2Like): boolean {
+  const dx = (point[0] as number) - (circle[0] as number);
+  const dy = (point[1] as number) - (circle[1] as number);
+  const r = circle[2] as number;
+  return r >= 0 && dx * dx + dy * dy <= r * r;
+}
+
+/** True when two circles overlap, including tangent contact. */
+export function intersectsCircle(a: Circle2Like, b: Circle2Like): boolean {
+  const dx = (a[0] as number) - (b[0] as number);
+  const dy = (a[1] as number) - (b[1] as number);
+  const radius = (a[2] as number) + (b[2] as number);
+  return (a[2] as number) >= 0 && (b[2] as number) >= 0 && dx * dx + dy * dy <= radius * radius;
+}
+
+/** True when the circle overlaps the box, including tangent contact. */
+export function intersectsBox(circle: Circle2Like, box: box2.Box2Like): boolean {
+  return box2.intersectsCircle(box, circle);
+}
+
+/** Return the smallest circle containing both circles. */
+export function merge(out: Circle2, a: Circle2Like, b: Circle2Like): Circle2 {
+  const ax = a[0] as number;
+  const ay = a[1] as number;
+  const ar = a[2] as number;
+  const bx = b[0] as number;
+  const by = b[1] as number;
+  const br = b[2] as number;
+  const dx = bx - ax;
+  const dy = by - ay;
+  const distance = Math.sqrt(dx * dx + dy * dy);
+  if (ar >= distance + br) return createInto(out, ax, ay, ar);
+  if (br >= distance + ar) return createInto(out, bx, by, br);
+  if (distance < 1e-12) return createInto(out, ax, ay, Math.max(ar, br));
+  const nextRadius = (distance + ar + br) * 0.5;
+  const shift = (nextRadius - ar) / distance;
+  return createInto(out, ax + dx * shift, ay + dy * shift, nextRadius);
+}
+
+function createInto(out: Circle2, cx: number, cy: number, r: number): Circle2 {
+  out[0] = cx;
+  out[1] = cy;
+  out[2] = r;
+  return out;
+}