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

package/src/__tests__/vec-catmull-rom.test.ts

@@ -0,0 +1,125 @@
+// vec-catmull-rom.test.ts — value tests for vec2/vec3.catmullRom (solo round 20260713-203432)
+//
+// Regression guard for the friction that motivated the sampler: a smooth curve through
+// control points (Bevy CubicCardinalSpline::new_catmull_rom, three.js CatmullRomCurve3)
+// forced hand-rolling the cubic coefficient matrix (tension, basis, control-point
+// windowing — all easy to get wrong). catmullRom folds the Catmull-Rom (tension 0.5)
+// position basis. These tests pin:
+//   1. endpoint interpolation: t=0 → p1, t=1 → p2 (the defining Catmull-Rom property),
+//   2. matches the explicit coefficient formula per component,
+//   3. collinear equally-spaced control points → linear interpolation (straight stays straight),
+//   4. midpoint value for a known symmetric control set,
+//   5. aliasing-safe (out === an input point),
+//   6. vec2 + vec3 symmetric.
+
+import { describe, expect, it } from 'vitest';
+import type { Vec2Like, Vec3Like } from '../types';
+import * as vec2 from '../vec2';
+import * as vec3 from '../vec3';
+
+// Reference scalar Catmull-Rom (tension 0.5) for cross-checking.
+function crScalar(a: number, b: number, c: number, d: number, t: number): number {
+  const c0 = b;
+  const c1 = 0.5 * (c - a);
+  const c2 = a - 2.5 * b + 2 * c - 0.5 * d;
+  const c3 = -0.5 * a + 1.5 * b - 1.5 * c + 0.5 * d;
+  return c0 + c1 * t + c2 * t * t + c3 * t * t * t;
+}
+
+describe('vec3.catmullRom — endpoint interpolation', () => {
+  it('t=0 → p1, t=1 → p2 (passes through the control points)', () => {
+    const p0: Vec3Like = [0, 0, 0];
+    const p1: Vec3Like = [1, 2, 3];
+    const p2: Vec3Like = [4, 0, -1];
+    const p3: Vec3Like = [5, 5, 5];
+    const out = vec3.create();
+
+    vec3.catmullRom(out, p0, p1, p2, p3, 0);
+    expect(out[0]).toBeCloseTo(1, 6);
+    expect(out[1]).toBeCloseTo(2, 6);
+    expect(out[2]).toBeCloseTo(3, 6);
+
+    vec3.catmullRom(out, p0, p1, p2, p3, 1);
+    expect(out[0]).toBeCloseTo(4, 6);
+    expect(out[1]).toBeCloseTo(0, 6);
+    expect(out[2]).toBeCloseTo(-1, 6);
+  });
+
+  it('matches the explicit coefficient formula per component at several t', () => {
+    const p0: Vec3Like = [-1, 2, 0.5];
+    const p1: Vec3Like = [3, -2, 1];
+    const p2: Vec3Like = [5, 3, -4];
+    const p3: Vec3Like = [9, 8, 2];
+    const out = vec3.create();
+    for (const t of [0.1, 0.25, 0.5, 0.75, 0.9]) {
+      vec3.catmullRom(out, p0, p1, p2, p3, t);
+      expect(out[0]).toBeCloseTo(crScalar(-1, 3, 5, 9, t), 5);
+      expect(out[1]).toBeCloseTo(crScalar(2, -2, 3, 8, t), 5);
+      expect(out[2]).toBeCloseTo(crScalar(0.5, 1, -4, 2, t), 5);
+    }
+  });
+});
+
+describe('vec3.catmullRom — geometric properties', () => {
+  it('collinear equally-spaced control points reduce to linear interpolation', () => {
+    // Points on a straight line, equally spaced → the Catmull-Rom segment between p1,p2
+    // is exactly the straight segment (a well-known Catmull-Rom property).
+    const p0: Vec3Like = [0, 0, 0];
+    const p1: Vec3Like = [1, 1, 1];
+    const p2: Vec3Like = [2, 2, 2];
+    const p3: Vec3Like = [3, 3, 3];
+    const out = vec3.create();
+    for (const t of [0, 0.2, 0.5, 0.8, 1]) {
+      vec3.catmullRom(out, p0, p1, p2, p3, t);
+      const expected = 1 + t; // linear from p1=(1,1,1) to p2=(2,2,2)
+      expect(out[0]).toBeCloseTo(expected, 5);
+      expect(out[1]).toBeCloseTo(expected, 5);
+      expect(out[2]).toBeCloseTo(expected, 5);
+    }
+  });
+
+  it('midpoint of a symmetric control set is the known Catmull-Rom value', () => {
+    // Symmetric 1D control points 0,0,1,1 → midpoint t=0.5 value is 0.5 by symmetry.
+    const out = vec3.create();
+    vec3.catmullRom(out, [0, 0, 0], [0, 0, 0], [1, 1, 1], [1, 1, 1], 0.5);
+    expect(out[0]).toBeCloseTo(0.5, 6);
+    expect(out[1]).toBeCloseTo(0.5, 6);
+    expect(out[2]).toBeCloseTo(0.5, 6);
+  });
+});
+
+describe('vec3.catmullRom — aliasing-safe', () => {
+  it('out === p1 gives the correct result', () => {
+    const p1 = vec3.create();
+    vec3.set(p1, 1, 2, 3);
+    vec3.catmullRom(p1, [0, 0, 0], p1, [4, 0, -1], [5, 5, 5], 0.5);
+    const ex0 = crScalar(0, 1, 4, 5, 0.5);
+    const ex1 = crScalar(0, 2, 0, 5, 0.5);
+    const ex2 = crScalar(0, 3, -1, 5, 0.5);
+    expect(p1[0]).toBeCloseTo(ex0, 6);
+    expect(p1[1]).toBeCloseTo(ex1, 6);
+    expect(p1[2]).toBeCloseTo(ex2, 6);
+  });
+});
+
+describe('vec2.catmullRom — symmetric surface', () => {
+  it('endpoint interpolation + formula match', () => {
+    const p0: Vec2Like = [-1, 2];
+    const p1: Vec2Like = [3, -2];
+    const p2: Vec2Like = [5, 3];
+    const p3: Vec2Like = [9, 8];
+    const out = vec2.create();
+
+    vec2.catmullRom(out, p0, p1, p2, p3, 0);
+    expect(out[0]).toBeCloseTo(3, 6);
+    expect(out[1]).toBeCloseTo(-2, 6);
+
+    vec2.catmullRom(out, p0, p1, p2, p3, 1);
+    expect(out[0]).toBeCloseTo(5, 6);
+    expect(out[1]).toBeCloseTo(3, 6);
+
+    vec2.catmullRom(out, p0, p1, p2, p3, 0.35);
+    expect(out[0]).toBeCloseTo(crScalar(-1, 3, 5, 9, 0.35), 5);
+    expect(out[1]).toBeCloseTo(crScalar(2, -2, 3, 8, 0.35), 5);
+  });
+});

package/src/__tests__/vec-smooth-damp.test.ts

@@ -0,0 +1,167 @@
+// vec-smooth-damp.test.ts — value tests for vec2/vec3/vec4.smoothDamp (solo round 20260713-183918)
+//
+// Regression guard for the friction that motivated the helpers: smoothly moving one entity toward
+// another (Bevy `Vec3::smooth_nudge`, three.js `MathUtils.damp`) required either a missing primitive
+// or the frame-rate-DEPENDENT hand-write `vec3.lerp(out, p, target, rate * dt)` — smooth at 60 fps,
+// snappy at 30 fps, overshooting when `rate * dt > 1`. smoothDamp folds the exponential decay
+// `lerp(current, target, 1 − exp(−decayRate · dt))`. These tests pin:
+//   1. dt = 0 → out = current (no move),
+//   2. large decayRate·dt → out ≈ target (converges),
+//   3. FRAME-RATE INDEPENDENCE WITNESS: one step of dt ≈ two composed steps of dt/2 (the property
+//      the naive lerp(rate·dt) violates — proven side-by-side that the naive form drifts),
+//   4. monotone convergence: distance to target strictly shrinks each step (decay>0, dt>0),
+//   5. aliasing-safe: out === current and out === target both give the right answer,
+//   6. exact per-component formula current + (target−current)·(1−exp(−decay·dt)),
+//   7. all three of vec2 / vec3 / vec4 present + symmetric.
+
+import { describe, expect, it } from 'vitest';
+import type { Vec2Like, Vec3Like, Vec4Like } from '../types';
+import * as vec2 from '../vec2';
+import * as vec3 from '../vec3';
+import * as vec4 from '../vec4';
+
+function dist3(a: Vec3Like, b: Vec3Like): number {
+  const dx = (a[0] as number) - (b[0] as number);
+  const dy = (a[1] as number) - (b[1] as number);
+  const dz = (a[2] as number) - (b[2] as number);
+  return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+
+describe('vec3.smoothDamp — core contract', () => {
+  it('dt = 0 → out = current (no move)', () => {
+    const out = vec3.create();
+    vec3.smoothDamp(out, [1, 2, 3], [10, 20, 30], 5, 0);
+    expect(out[0]).toBeCloseTo(1, 5);
+    expect(out[1]).toBeCloseTo(2, 5);
+    expect(out[2]).toBeCloseTo(3, 5);
+  });
+
+  it('decayRate = 0 → out = current (no effect, matches Bevy)', () => {
+    const out = vec3.create();
+    vec3.smoothDamp(out, [1, 2, 3], [10, 20, 30], 0, 1 / 60);
+    expect(out[0]).toBeCloseTo(1, 5);
+    expect(out[1]).toBeCloseTo(2, 5);
+    expect(out[2]).toBeCloseTo(3, 5);
+  });
+
+  it('large decayRate·dt → out ≈ target (snaps)', () => {
+    const out = vec3.create();
+    vec3.smoothDamp(out, [0, 0, 0], [7, -4, 2], 1000, 1);
+    expect(out[0]).toBeCloseTo(7, 5);
+    expect(out[1]).toBeCloseTo(-4, 5);
+    expect(out[2]).toBeCloseTo(2, 5);
+  });
+
+  it('exact per-component formula current + (target−current)·(1−exp(−decay·dt))', () => {
+    const current: Vec3Like = [1, 2, 3];
+    const target: Vec3Like = [5, 5, 5];
+    const decay = 3;
+    const dt = 1 / 60;
+    const f = 1 - Math.exp(-decay * dt);
+    const out = vec3.create();
+    vec3.smoothDamp(out, current, target, decay, dt);
+    expect(out[0]).toBeCloseTo(1 + (5 - 1) * f, 6);
+    expect(out[1]).toBeCloseTo(2 + (5 - 2) * f, 6);
+    expect(out[2]).toBeCloseTo(3 + (5 - 3) * f, 6);
+  });
+
+  it('monotone convergence: distance to target strictly shrinks each step', () => {
+    const target: Vec3Like = [10, 10, 10];
+    const p = vec3.create();
+    vec3.set(p, 0, 0, 0);
+    let prev = dist3(p, target);
+    for (let i = 0; i < 120; i++) {
+      vec3.smoothDamp(p, p, target, 4, 1 / 60);
+      const d = dist3(p, target);
+      expect(d).toBeLessThan(prev);
+      prev = d;
+    }
+    // after 2 s of decay=4 the remaining distance is tiny (exp(−8) ≈ 3.4e-4 of the original)
+    expect(prev).toBeLessThan(0.01);
+  });
+});
+
+describe('vec3.smoothDamp — frame-rate independence WITNESS', () => {
+  it('one step of dt ≈ two composed steps of dt/2 (smoothDamp holds; naive lerp drifts)', () => {
+    const current: Vec3Like = [0, 0, 0];
+    const target: Vec3Like = [10, 0, 0];
+    const decay = 6;
+    const dt = 1 / 30;
+
+    // Frame-rate-INDEPENDENT: smoothDamp with one full dt.
+    const big = vec3.create();
+    vec3.smoothDamp(big, current, target, decay, dt);
+
+    // ...vs two half-dt smoothDamp steps composed. Exponential decay composes exactly:
+    // exp(−k·(dt/2))·exp(−k·(dt/2)) = exp(−k·dt).
+    const small = vec3.create();
+    vec3.copy(small, current);
+    vec3.smoothDamp(small, small, target, decay, dt / 2);
+    vec3.smoothDamp(small, small, target, decay, dt / 2);
+
+    expect(small[0]).toBeCloseTo(big[0] as number, 5);
+    expect(small[1]).toBeCloseTo(big[1] as number, 5);
+    expect(small[2]).toBeCloseTo(big[2] as number, 5);
+
+    // Contrast: the naive frame-rate-DEPENDENT lerp(current, target, rate·dt) does NOT compose —
+    // this is exactly the footgun smoothDamp folds. Prove the drift is real, not negligible.
+    const naiveBig = vec3.create();
+    vec3.lerp(naiveBig, current, target, decay * dt);
+    const naiveSmall = vec3.create();
+    vec3.copy(naiveSmall, current);
+    vec3.lerp(naiveSmall, naiveSmall, target, decay * (dt / 2));
+    vec3.lerp(naiveSmall, naiveSmall, target, decay * (dt / 2));
+    const naiveDrift = Math.abs((naiveBig[0] as number) - (naiveSmall[0] as number));
+    expect(naiveDrift).toBeGreaterThan(0.1); // meaningfully different — the bug smoothDamp removes
+  });
+});
+
+describe('vec3.smoothDamp — aliasing-safe', () => {
+  it('out === current gives the correct result', () => {
+    const p = vec3.create();
+    vec3.set(p, 1, 2, 3);
+    vec3.smoothDamp(p, p, [5, 5, 5], 3, 1 / 60);
+    const f = 1 - Math.exp(-3 / 60);
+    expect(p[0]).toBeCloseTo(1 + (5 - 1) * f, 6);
+    expect(p[1]).toBeCloseTo(2 + (5 - 2) * f, 6);
+    expect(p[2]).toBeCloseTo(3 + (5 - 3) * f, 6);
+  });
+
+  it('out === target gives the correct result', () => {
+    const t = vec3.create();
+    vec3.set(t, 5, 5, 5);
+    vec3.smoothDamp(t, [1, 2, 3], t, 3, 1 / 60);
+    const f = 1 - Math.exp(-3 / 60);
+    expect(t[0]).toBeCloseTo(1 + (5 - 1) * f, 6);
+    expect(t[1]).toBeCloseTo(2 + (5 - 2) * f, 6);
+    expect(t[2]).toBeCloseTo(3 + (5 - 3) * f, 6);
+  });
+});
+
+describe('vec2 / vec4 smoothDamp — symmetric surface', () => {
+  it('vec2.smoothDamp matches the per-component formula', () => {
+    const out = vec2.create();
+    const current: Vec2Like = [1, 2];
+    const target: Vec2Like = [9, -3];
+    const decay = 2.5;
+    const dt = 1 / 60;
+    const f = 1 - Math.exp(-decay * dt);
+    vec2.smoothDamp(out, current, target, decay, dt);
+    expect(out[0]).toBeCloseTo(1 + (9 - 1) * f, 6);
+    expect(out[1]).toBeCloseTo(2 + (-3 - 2) * f, 6);
+  });
+
+  it('vec4.smoothDamp matches the per-component formula', () => {
+    const out = vec4.create();
+    const current: Vec4Like = [1, 2, 3, 4];
+    const target: Vec4Like = [9, -3, 0, 8];
+    const decay = 2.5;
+    const dt = 1 / 60;
+    const f = 1 - Math.exp(-decay * dt);
+    vec4.smoothDamp(out, current, target, decay, dt);
+    expect(out[0]).toBeCloseTo(1 + (9 - 1) * f, 6);
+    expect(out[1]).toBeCloseTo(2 + (-3 - 2) * f, 6);
+    expect(out[2]).toBeCloseTo(3 + (0 - 3) * f, 6);
+    expect(out[3]).toBeCloseTo(4 + (8 - 4) * f, 6);
+  });
+});

package/src/__tests__/vec2.test-d.ts

@@ -0,0 +1,59 @@
+// vec2.test-d.ts — branded return type + dimension mutual-exclusion compile-time assertions (T-012)
+//
+// Locks add / sub / scale / normalize / lerp / perp etc. to return Vec2;
+// vec2.add(out=Vec3, ...) is a ts-error verifying dimension mutual exclusion
+// (an AC-02 brand-mutex contribution).
+//
+// Related: requirements §AC-12 type test + AC-02 brand mutual exclusion;
+//          wiki/typescript-branded-types §3.1 expectTypeOf template + §7.3 ts-expect-error.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { vec2 } from '../index';
+import type { Vec2, Vec3 } from '../types';
+
+describe('vec2 — branded return-type locks', () => {
+  it('vec2.create returns Vec2', () => {
+    expectTypeOf(vec2.create()).toEqualTypeOf<Vec2>();
+  });
+
+  it('vec2.add returns Vec2', () => {
+    expectTypeOf(vec2.add(vec2.create(), vec2.create(), vec2.create())).toEqualTypeOf<Vec2>();
+  });
+
+  it('vec2.sub returns Vec2', () => {
+    expectTypeOf(vec2.sub(vec2.create(), vec2.create(), vec2.create())).toEqualTypeOf<Vec2>();
+  });
+
+  it('vec2.scale returns Vec2', () => {
+    expectTypeOf(vec2.scale(vec2.create(), vec2.create(), 1)).toEqualTypeOf<Vec2>();
+  });
+
+  it('vec2.normalize returns Vec2', () => {
+    expectTypeOf(vec2.normalize(vec2.create(), vec2.create())).toEqualTypeOf<Vec2>();
+  });
+
+  it('vec2.lerp returns Vec2', () => {
+    expectTypeOf(vec2.lerp(vec2.create(), vec2.create(), vec2.create(), 0.5)).toEqualTypeOf<Vec2>();
+  });
+
+  it('vec2.perp returns Vec2', () => {
+    expectTypeOf(vec2.perp(vec2.create(), vec2.create())).toEqualTypeOf<Vec2>();
+  });
+
+  it('vec2.dot returns number', () => {
+    expectTypeOf(vec2.dot(vec2.create(), vec2.create())).toEqualTypeOf<number>();
+  });
+
+  it('vec2.length returns number', () => {
+    expectTypeOf(vec2.length(vec2.create())).toEqualTypeOf<number>();
+  });
+});
+
+describe('vec2 — cross-namespace misuse blocked at compile time', () => {
+  it('vec2.add must reject Vec3 as out', () => {
+    const v3: Vec3 = null as unknown as Vec3;
+    const v2: Vec2 = vec2.create();
+    // @ts-expect-error — out must be Vec2, not Vec3
+    vec2.add(v3, v2, v2);
+  });
+});

package/src/__tests__/vec3.property.test.ts

@@ -0,0 +1,72 @@
+// vec3.property.test.ts — fast-check property tests (M5 / T-031, AC-11)
+//
+// Category coverage:
+//   - normalize idempotence ×2: |n(v)|≈1, n(n(v))≈n(v)
+//   - identity ×1: v + 0 ≈ v (vec3.add identity)
+//
+// Total cases: 3. numRuns defaults to 100 (D-P5); the PROPERTY_NUM_RUNS env can override to 1000 (nightly).
+// Degenerate input: normalize takes nonZeroVec3Arb (the zero vector is already mapper-repaired to [1,0,0]
+// to avoid ε comparisons hitting NaN).
+//
+// Related: requirements §AC-11; plan-strategy D-P5; wiki/fast-check-property-test §5.4.
+
+import { fc, test } from '@fast-check/vitest';
+import { describe, expect } from 'vitest';
+import * as vec3 from '../vec3';
+import { EPS_F32, nonZeroVec3Arb, vec3Arb } from './_arbs';
+
+// numRuns defaults to 100; nightly overrides to 1000 via env (D-P5).
+// process.env is read via globalThis to avoid pulling in the @types/node devDep (AC-16 / D-P13).
+const NUM_RUNS = Number.parseInt(
+  (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+    ?.PROPERTY_NUM_RUNS ?? '100',
+  10,
+);
+
+describe('vec3 property: normalize idempotence', () => {
+  test.prop({ v: nonZeroVec3Arb() }, { numRuns: NUM_RUNS })(
+    '|normalize(v)| ≈ 1 (v non-zero)',
+    ({ v }) => {
+      const out = vec3.create();
+      vec3.normalize(out, v);
+      const len = Math.hypot(out[0] as number, out[1] as number, out[2] as number);
+      // one sqrt + one div, wiki §4.4 recommends 1e-5
+      return Math.abs(len - 1) < EPS_F32;
+    },
+  );
+
+  test.prop({ v: nonZeroVec3Arb() }, { numRuns: NUM_RUNS })(
+    'normalize(normalize(v)) ≈ normalize(v) (idempotent)',
+    ({ v }) => {
+      const n1 = vec3.create();
+      vec3.normalize(n1, v);
+      const n2 = vec3.create();
+      vec3.normalize(n2, n1);
+      // accumulated error of two normalizations stays within 1e-6
+      return (
+        Math.abs((n1[0] as number) - (n2[0] as number)) < 1e-6 &&
+        Math.abs((n1[1] as number) - (n2[1] as number)) < 1e-6 &&
+        Math.abs((n1[2] as number) - (n2[2] as number)) < 1e-6
+      );
+    },
+  );
+});
+
+describe('vec3 property: identity', () => {
+  test.prop({ v: vec3Arb() }, { numRuns: NUM_RUNS })('v + 0 ≈ v (additive identity)', ({ v }) => {
+    const zero = vec3.create();
+    const out = vec3.create();
+    vec3.add(out, v, zero);
+    // adding 0 is strictly equal (no float rounding), but keep ε to guard the -0 / +0 corner
+    return (
+      Math.abs((out[0] as number) - (v[0] as number)) < EPS_F32 &&
+      Math.abs((out[1] as number) - (v[1] as number)) < EPS_F32 &&
+      Math.abs((out[2] as number) - (v[2] as number)) < EPS_F32
+    );
+  });
+});
+
+// avoid unused import warning when fc is not directly referenced in body
+void fc;
+// explicitly import expect to silence typecheck complaints under some vitest configs
+void expect;

package/src/__tests__/vec3.test-d.ts

@@ -0,0 +1,65 @@
+// vec3.test-d.ts — branded return type + dimension mutual-exclusion compile-time assertions (T-012)
+//
+// Locks add / sub / scale / normalize / cross / lerp to return Vec3;
+// vec3.add(out=Vec2, ...) is a ts-error; vec3.cross(out, vec2, vec2) is also a ts-error.
+//
+// Related: requirements §AC-12 type test + AC-02 brand mutual exclusion;
+//          wiki/typescript-branded-types §3.1 expectTypeOf template + §7.3 ts-expect-error.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { vec3 } from '../index';
+import type { Vec2, Vec3, Vec4 } from '../types';
+
+describe('vec3 — branded return-type locks', () => {
+  it('vec3.create returns Vec3', () => {
+    expectTypeOf(vec3.create()).toEqualTypeOf<Vec3>();
+  });
+
+  it('vec3.add returns Vec3', () => {
+    expectTypeOf(vec3.add(vec3.create(), vec3.create(), vec3.create())).toEqualTypeOf<Vec3>();
+  });
+
+  it('vec3.sub returns Vec3', () => {
+    expectTypeOf(vec3.sub(vec3.create(), vec3.create(), vec3.create())).toEqualTypeOf<Vec3>();
+  });
+
+  it('vec3.scale returns Vec3', () => {
+    expectTypeOf(vec3.scale(vec3.create(), vec3.create(), 1)).toEqualTypeOf<Vec3>();
+  });
+
+  it('vec3.normalize returns Vec3', () => {
+    expectTypeOf(vec3.normalize(vec3.create(), vec3.create())).toEqualTypeOf<Vec3>();
+  });
+
+  it('vec3.cross returns Vec3', () => {
+    expectTypeOf(vec3.cross(vec3.create(), vec3.create(), vec3.create())).toEqualTypeOf<Vec3>();
+  });
+
+  it('vec3.lerp returns Vec3', () => {
+    expectTypeOf(vec3.lerp(vec3.create(), vec3.create(), vec3.create(), 0.5)).toEqualTypeOf<Vec3>();
+  });
+
+  it('vec3.dot returns number', () => {
+    expectTypeOf(vec3.dot(vec3.create(), vec3.create())).toEqualTypeOf<number>();
+  });
+
+  it('vec3.length returns number', () => {
+    expectTypeOf(vec3.length(vec3.create())).toEqualTypeOf<number>();
+  });
+});
+
+describe('vec3 — cross-namespace misuse blocked at compile time', () => {
+  it('vec3.add must reject Vec2 as out', () => {
+    const v2: Vec2 = null as unknown as Vec2;
+    const v3: Vec3 = vec3.create();
+    // @ts-expect-error — out must be Vec3, not Vec2
+    vec3.add(v2, v3, v3);
+  });
+
+  it('vec3.cross must reject Vec4 as out', () => {
+    const v4: Vec4 = null as unknown as Vec4;
+    const v3: Vec3 = vec3.create();
+    // @ts-expect-error — out must be Vec3, not Vec4
+    vec3.cross(v4, v3, v3);
+  });
+});

package/src/__tests__/vec4.test-d.ts

@@ -0,0 +1,61 @@
+// vec4.test-d.ts — branded return type + dimension mutual-exclusion compile-time assertions (T-012)
+//
+// Locks add / sub / scale / normalize / lerp to return Vec4; vec4.add(out=Vec3, ...) is a ts-error.
+// Vec4 ≠ Quat: contributes to the same-length=4 brand mutual-exclusion check.
+//
+// Related: requirements §AC-12 type test + AC-02 brand mutual exclusion;
+//          wiki/typescript-branded-types §3.1 expectTypeOf template + §7.3 ts-expect-error.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { vec4 } from '../index';
+import type { Quat, Vec3, Vec4 } from '../types';
+
+describe('vec4 — branded return-type locks', () => {
+  it('vec4.create returns Vec4', () => {
+    expectTypeOf(vec4.create()).toEqualTypeOf<Vec4>();
+  });
+
+  it('vec4.add returns Vec4', () => {
+    expectTypeOf(vec4.add(vec4.create(), vec4.create(), vec4.create())).toEqualTypeOf<Vec4>();
+  });
+
+  it('vec4.sub returns Vec4', () => {
+    expectTypeOf(vec4.sub(vec4.create(), vec4.create(), vec4.create())).toEqualTypeOf<Vec4>();
+  });
+
+  it('vec4.scale returns Vec4', () => {
+    expectTypeOf(vec4.scale(vec4.create(), vec4.create(), 1)).toEqualTypeOf<Vec4>();
+  });
+
+  it('vec4.normalize returns Vec4', () => {
+    expectTypeOf(vec4.normalize(vec4.create(), vec4.create())).toEqualTypeOf<Vec4>();
+  });
+
+  it('vec4.lerp returns Vec4', () => {
+    expectTypeOf(vec4.lerp(vec4.create(), vec4.create(), vec4.create(), 0.5)).toEqualTypeOf<Vec4>();
+  });
+
+  it('vec4.dot returns number', () => {
+    expectTypeOf(vec4.dot(vec4.create(), vec4.create())).toEqualTypeOf<number>();
+  });
+
+  it('vec4.length returns number', () => {
+    expectTypeOf(vec4.length(vec4.create())).toEqualTypeOf<number>();
+  });
+});
+
+describe('vec4 — cross-namespace misuse blocked at compile time', () => {
+  it('vec4.add must reject Vec3 as out', () => {
+    const v3: Vec3 = null as unknown as Vec3;
+    const v4: Vec4 = vec4.create();
+    // @ts-expect-error — out must be Vec4, not Vec3
+    vec4.add(v3, v4, v4);
+  });
+
+  it('Vec4 ≠ Quat (same length=4 brand mutual exclusion) — out must be Vec4', () => {
+    const q: Quat = null as unknown as Quat;
+    // @ts-expect-error — out must be Vec4; Quat is rejected (Vec4Like inputs allow ArrayLike,
+    // but the out type is strictly brand-locked, so Quat as out triggers a ts-error).
+    vec4.add(q, vec4.create(), vec4.create());
+  });
+});

package/src/_internal/epsilon.ts

@@ -0,0 +1,29 @@
+// _internal/epsilon.ts — EPS constant family SSOT (D-P14)
+//
+// Centralizes all numeric tolerances; prevents scattered hard-coded constants.
+// Not exported through src/index.ts (D-P13 _internal does not leave the package);
+// indirectly covered by the vec/mat/quat tests that consume it.
+//
+// Rationale:
+//   - EPS_NORMALIZE: lengths below this are treated as zero vectors; normalize falls back to a zero
+//     vector. 1e-12 follows the consensus of glam-rs and wgpu-matrix, avoiding single-precision
+//     Float32 noise misjudgments.
+//   - EPS_DET: threshold for declaring a determinant singular. 1e-8 leaves safe headroom over the
+//     single-precision ULP near 1.0 (~1.19e-7) (research §Finding 4.2 ε-tolerance table).
+//   - EPS_QUAT_PARALLEL: near-collinear input check for fromUnitVectors / slerp (D-P18).
+//   - EPS_SLERP_DOT_LIMIT: slerp falls back to nlerp when |dot| ≥ 1-EPS, avoiding acos blowup (D-P6).
+//
+// Related: plan-strategy D-P14 EPS constants centralized; research §Finding 3 glam epsilon choice +
+//          §Finding 4.2 ε-tolerance table.
+
+/** Vector lengths below this value are treated as zero (normalize fall-back). */
+export const EPS_NORMALIZE = 1e-12;
+
+/** Matrix determinants below this value are treated as singular (invert falls back to identity, D-P1). */
+export const EPS_DET = 1e-8;
+
+/** Threshold for treating two unit vectors as nearly collinear / opposite (fromUnitVectors / slerp inputs). */
+export const EPS_QUAT_PARALLEL = 1e-6;
+
+/** In quat.slerp, |dot| above this value is treated as endpoint coincidence; falls back to nlerp (D-P6). */
+export const EPS_SLERP_DOT_LIMIT = 1e-6;

package/src/_internal/scalar.ts

@@ -0,0 +1,90 @@
+// _internal/scalar.ts — scalar helper SSOT (D-P13 not exported from package)
+//
+// Provides the scalar-layer building blocks reused across the vec/mat/quat namespaces;
+// avoids duplicate implementations.
+// Not exported through src/index.ts; indirectly covered by the public API tests of the dim files
+// (plan-strategy §4.1 exemption).
+//
+// Related: plan-strategy §1.1 file layering (_internal/scalar.ts) + D-P13 _internal not exported;
+//          requirements §duplicate-code elimination strategy D mixed.
+
+/**
+ * Scalar linear interpolation. t is not clamped (extrapolation semantics preserved,
+ * matches glam Vec3.lerp / wgpu-matrix).
+ */
+export function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+/** Squared length of a four-component numeric value. */
+export function lengthSq4(a: ArrayLike<number>): number {
+  const x = a[0] as number;
+  const y = a[1] as number;
+  const z = a[2] as number;
+  const w = a[3] as number;
+  return x * x + y * y + z * z + w * w;
+}
+
+/** Normalize a four-component numeric value into a typed-array output. */
+export function normalize4(out: Float32Array, a: ArrayLike<number>, epsilon: number): void {
+  const lenSq = lengthSq4(a);
+  if (lenSq < epsilon) {
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = 0;
+    out[3] = 0;
+    return;
+  }
+  const inv = 1 / Math.sqrt(lenSq);
+  out[0] = (a[0] as number) * inv;
+  out[1] = (a[1] as number) * inv;
+  out[2] = (a[2] as number) * inv;
+  out[3] = (a[3] as number) * inv;
+}
+
+/**
+ * Exponential-decay smoothing factor for frame-rate-INDEPENDENT damping:
+ * `1 − exp(−decayRate · dt)`. The single value the vec `smoothDamp` helpers interpolate by.
+ *
+ * SSOT for the smooth-nudge semantics (Bevy `StableInterpolate::smooth_nudge`,
+ * three.js `MathUtils.damp`): the returned factor composes multiplicatively over dt —
+ * `exp(−k·(a+b)) = exp(−k·a)·exp(−k·b)` — so one step of dt equals two steps of dt/2, the
+ * property a naive `rate·dt` factor violates. `dt=0` → 0 (no move); `decayRate·dt → ∞` → 1
+ * (snap to target); `decayRate=0` → 0 (no effect). NaN propagates via Math.exp.
+ */
+export function smoothDecayFactor(decayRate: number, dt: number): number {
+  return 1 - Math.exp(-decayRate * dt);
+}
+
+/**
+ * Scalar Catmull-Rom spline value on the segment between `b` and `c`, with `a` / `d` the
+ * neighbor control points that set the endpoint tangents. Tension 0.5 (the Catmull-Rom
+ * special case of a Cardinal spline, and the Bevy default). SSOT for the vec `catmullRom`
+ * helpers — the coefficient matrix lives here once (Bevy `CubicCardinalSpline::char_matrix`
+ * with s=0.5):
+ *   c0 = b
+ *   c1 = 0.5 (c − a)
+ *   c2 = a − 2.5 b + 2 c − 0.5 d
+ *   c3 = −0.5 a + 1.5 b − 1.5 c + 0.5 d
+ *   value = c0 + c1 t + c2 t² + c3 t³
+ * Interpolates the control points: t=0 → b, t=1 → c. `t` is not clamped (extrapolation
+ * beyond the segment follows the same cubic, matching `lerp`'s unclamped semantics).
+ */
+export function catmullRomScalar(a: number, b: number, c: number, d: number, t: number): number {
+  const c0 = b;
+  const c1 = 0.5 * (c - a);
+  const c2 = a - 2.5 * b + 2 * c - 0.5 * d;
+  const c3 = -0.5 * a + 1.5 * b - 1.5 * c + 0.5 * d;
+  const t2 = t * t;
+  const t3 = t2 * t;
+  return c0 + c1 * t + c2 * t2 + c3 * t3;
+}
+
+/**
+ * Numeric clamp into the closed interval [min, max]. Returns NaN when v is NaN (NaN propagation).
+ */
+export function clamp(v: number, min: number, max: number): number {
+  if (v < min) return min;
+  if (v > max) return max;
+  return v;
+}