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

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

@@ -0,0 +1,256 @@
+// mat4.property.test.ts — fast-check property tests (M5 / T-031, AC-11)
+//
+// Category coverage (4 cases / 3 categories):
+//   - associativity ×1: (A·B)·C ≈ A·(B·C), numRuns:50 (single chained mul ~100ms)
+//   - identity ×2: I·M ≈ M, M·I ≈ M
+//   - invertibility ×1: M·M⁻¹ ≈ I (restricted to invertibleMat4Arb, TRS composition guards against singular)
+//
+// numRuns: default 100; chained-mul cases drop to 50 (D-P5 / wiki §7.3).
+// EPS: mat4 single mul 1e-4 (EPS_MAT4_MUL); triple chained mul 1e-3 (EPS_MAT4_MUL3).
+//
+// Related: requirements §AC-11; plan-strategy D-P5; wiki/fast-check-property-test §5.1-§5.3.
+
+import { fc, test } from '@fast-check/vitest';
+import { describe, expect } from 'vitest';
+import * as mat4 from '../mat4';
+import type { Vec3 } from '../types';
+import {
+  EPS_F32,
+  EPS_MAT4_MUL,
+  EPS_MAT4_MUL3,
+  invertibleMat4Arb,
+  mat4Arb,
+  unitVec3Arb,
+  vec3Arb,
+} from './_arbs';
+
+// 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,
+);
+// chained-mul cases drop to 1/2 numRuns, ~100ms × 50 = within 5s (vitest test timeout default)
+const NUM_RUNS_TRIPLE = Math.max(10, Math.floor(NUM_RUNS / 2));
+
+function mat4ApproxEq(a: Float32Array, b: Float32Array, eps: number): boolean {
+  for (let i = 0; i < 16; i++) {
+    const ai = a[i] as number;
+    const bi = b[i] as number;
+    const scale = Math.max(1, Math.abs(ai), Math.abs(bi));
+    if (Math.abs(ai - bi) >= eps * scale) return false;
+  }
+  return true;
+}
+
+describe('mat4 property: associativity', () => {
+  test.prop(
+    { A: mat4Arb(), B: mat4Arb(), C: mat4Arb() },
+    { numRuns: NUM_RUNS_TRIPLE, interruptAfterTimeLimit: 5000 },
+  )('(A·B)·C ≈ A·(B·C)', ({ A, B, C }) => {
+    const ab = mat4.create();
+    mat4.multiply(ab, A, B);
+    const left = mat4.create();
+    mat4.multiply(left, ab, C);
+
+    const bc = mat4.create();
+    mat4.multiply(bc, B, C);
+    const right = mat4.create();
+    mat4.multiply(right, A, bc);
+
+    return mat4ApproxEq(left, right, EPS_MAT4_MUL3);
+  });
+});
+
+describe('mat4 property: identity', () => {
+  test.prop({ M: mat4Arb() }, { numRuns: NUM_RUNS })('I · M ≈ M', ({ M }) => {
+    const I = mat4.create();
+    mat4.identity(I);
+    const out = mat4.create();
+    mat4.multiply(out, I, M);
+    return mat4ApproxEq(out, M, EPS_MAT4_MUL);
+  });
+
+  test.prop({ M: mat4Arb() }, { numRuns: NUM_RUNS })('M · I ≈ M', ({ M }) => {
+    const I = mat4.create();
+    mat4.identity(I);
+    const out = mat4.create();
+    mat4.multiply(out, M, I);
+    return mat4ApproxEq(out, M, EPS_MAT4_MUL);
+  });
+});
+
+describe('mat4 property: invertibility', () => {
+  test.prop({ M: invertibleMat4Arb() }, { numRuns: NUM_RUNS })(
+    'M · invert(M) ≈ I (restricted to invertible TRS compositions)',
+    ({ M }) => {
+      const inv = mat4.create();
+      mat4.invert(inv, M);
+      const I = mat4.create();
+      mat4.multiply(I, M, inv);
+      const expected = mat4.create();
+      mat4.identity(expected);
+      // EPS slightly relaxed: TRS scale range [1e-2, 10] × invert error amplification
+      return mat4ApproxEq(I, expected, 1e-2);
+    },
+  );
+});
+
+// M1 / t4 — mat4 transform 3-function property +6
+//
+// 6 cases / 2 per function:
+//   - transformVec3: (1) chained composition transformVec3(B*A, v) ≈ transformVec3(B, transformVec3(A, v))
+//                    (2) identity unit transformVec3(I, v) ≈ v
+//   - transformPoint: (1) equivalent to transformVec3 on an affine m
+//                    (2) translation independently testable: transformPoint(T, origin) = t
+//   - transformDirection: (1) orthogonal matrices preserve unit length
+//                        (2) equivalent to transformVec3 on a pure-rotation m
+//
+// numRuns: 100 default; EPS aligned with wiki §4.4 recommendation table; interruptAfterTimeLimit:5000.
+//
+// Related: requirements §3.3 property +8 mandate (mat4 contributes 6 cases) + §6 AC-11 ≥ 20;
+//          research Finding 5 template table + plan-strategy §4.2 + §4.3 key test points table row 5.
+
+function vec3ApproxEq(a: Float32Array, b: Float32Array, eps: number): boolean {
+  for (let i = 0; i < 3; i++) {
+    const ai = a[i] as number;
+    const bi = b[i] as number;
+    if (!Number.isFinite(ai) || !Number.isFinite(bi)) return false;
+    const scale = Math.max(1, Math.abs(ai), Math.abs(bi));
+    if (Math.abs(ai - bi) >= eps * scale) return false;
+  }
+  return true;
+}
+
+describe('mat4.transformVec3 property (t4)', () => {
+  test.prop({ v: vec3Arb() }, { numRuns: NUM_RUNS })(
+    'identity unit: transformVec3(I, v) ≈ v',
+    ({ v }) => {
+      const I = mat4.identity(mat4.create());
+      const out = new Float32Array(3) as Vec3;
+      mat4.transformVec3(out, I, v);
+      return vec3ApproxEq(out, v, EPS_F32);
+    },
+  );
+
+  test.prop(
+    { A: invertibleMat4Arb(), B: invertibleMat4Arb(), v: vec3Arb() },
+    { numRuns: NUM_RUNS, interruptAfterTimeLimit: 5000 },
+  )(
+    'chained composition: transformVec3(B*A, v) ≈ transformVec3(B, transformVec3(A, v))',
+    ({ A, B, v }) => {
+      const BA = mat4.create();
+      mat4.multiply(BA, B, A);
+      const left = new Float32Array(3) as Vec3;
+      mat4.transformVec3(left, BA, v);
+      const tmp = new Float32Array(3) as Vec3;
+      mat4.transformVec3(tmp, A, v);
+      const right = new Float32Array(3) as Vec3;
+      mat4.transformVec3(right, B, tmp);
+      return vec3ApproxEq(left, right, EPS_MAT4_MUL);
+    },
+  );
+});
+
+describe('mat4.transformPoint property (t4)', () => {
+  test.prop({ M: invertibleMat4Arb(), v: vec3Arb() }, { numRuns: NUM_RUNS })(
+    'equivalent to transformVec3 on an affine m (alias)',
+    ({ M, v }) => {
+      const a = new Float32Array(3) as Vec3;
+      const b = new Float32Array(3) as Vec3;
+      mat4.transformVec3(a, M, v);
+      mat4.transformPoint(b, M, v);
+      return vec3ApproxEq(a, b, EPS_F32);
+    },
+  );
+
+  test.prop({ t: vec3Arb() }, { numRuns: NUM_RUNS })(
+    'translation independently testable: transformPoint(T(t), origin) = t',
+    ({ t }) => {
+      const T = mat4.fromTranslation(mat4.create(), t);
+      const origin = Float32Array.of(0, 0, 0);
+      const out = new Float32Array(3) as Vec3;
+      mat4.transformPoint(out, T, origin);
+      return vec3ApproxEq(out, t, EPS_F32);
+    },
+  );
+});
+
+describe('mat4.transformDirection property (t4)', () => {
+  test.prop({ axis: unitVec3Arb(), dir: unitVec3Arb() }, { numRuns: NUM_RUNS })(
+    'orthogonal matrices preserve unit length: |transformDirection(R, dir)| ≈ 1',
+    ({ axis, dir }) => {
+      const R = mat4.fromRotation(mat4.create(), axis, 0.7);
+      const out = new Float32Array(3) as Vec3;
+      mat4.transformDirection(out, R, dir);
+      const len = Math.hypot(out[0] as number, out[1] as number, out[2] as number);
+      return Math.abs(len - 1) < EPS_F32 * 10;
+    },
+  );
+
+  test.prop({ axis: unitVec3Arb(), dir: unitVec3Arb() }, { numRuns: NUM_RUNS })(
+    'equivalent to transformVec3 on a pure-rotation m (normalize does not affect unit length)',
+    ({ axis, dir }) => {
+      const R = mat4.fromRotation(mat4.create(), axis, 0.5);
+      const a = new Float32Array(3) as Vec3;
+      const b = new Float32Array(3) as Vec3;
+      mat4.transformVec3(a, R, dir);
+      mat4.transformDirection(b, R, dir);
+      return vec3ApproxEq(a, b, EPS_F32 * 10);
+    },
+  );
+});
+
+// G-4 — projectPoint duality with unproject (roadmap 2026-06-15 game-demo-engine-gaps)
+//
+// Two cases:
+//   (1) intent-revealing alias: projectPoint(out, v, VP) ≡ transformVec3(out, VP, v)
+//       — sanity check the wrapper does not introduce divergence vs the underlying op
+//   (2) round-trip on a realistic view-projection (lookAt + perspective):
+//       unproject(projectPoint(v, VP), invVP) ≈ v for v inside the frustum.
+//       Restricted to in-frustum points — extreme invertibleMat4Arb matrices amplify
+//       f32 error past any reasonable epsilon, and HUD anchoring only ever cares about
+//       points the camera can actually see.
+describe('mat4.projectPoint property (G-4 dual of unproject)', () => {
+  test.prop({ VP: invertibleMat4Arb(), v: vec3Arb() }, { numRuns: NUM_RUNS })(
+    'projectPoint(out, v, VP) ≡ transformVec3(out, VP, v)',
+    ({ VP, v }) => {
+      const a = new Float32Array(3) as Vec3;
+      const b = new Float32Array(3) as Vec3;
+      mat4.projectPoint(a, v, VP);
+      mat4.transformVec3(b, VP, v);
+      return vec3ApproxEq(a, b, EPS_F32);
+    },
+  );
+
+  test.prop(
+    {
+      // sample world points roughly inside the frustum the VP below describes.
+      v: fc
+        .tuple(
+          fc.float({ min: -2, max: 2, noNaN: true }),
+          fc.float({ min: -2, max: 2, noNaN: true }),
+          fc.float({ min: -8, max: -2, noNaN: true }),
+        )
+        .map(([x, y, z]) => Float32Array.of(x, y, z) as Vec3),
+    },
+    { numRuns: NUM_RUNS },
+  )('round-trip on a realistic view-projection: unproject(projectPoint(v, VP)) ≈ v', ({ v }) => {
+    const view = mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]);
+    const proj = mat4.perspective(mat4.create(), Math.PI / 3, 16 / 9, 0.1, 100);
+    const VP = mat4.create();
+    mat4.multiply(VP, proj, view);
+    const invVP = mat4.create();
+    mat4.invert(invVP, VP);
+
+    const ndc = new Float32Array(3) as Vec3;
+    mat4.projectPoint(ndc, v, VP);
+    const back = new Float32Array(3) as Vec3;
+    mat4.unproject(back, ndc, invVP);
+    // round-trip across two w-divides + invert; relax to EPS_MAT4_MUL3 (1e-3).
+    return vec3ApproxEq(back, v, EPS_MAT4_MUL3);
+  });
+});
+
+void fc;
+void expect;

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

@@ -0,0 +1,130 @@
+// mat4.test-d.ts — branded return type + dimension-mix-up compile-time assertions (T-018)
+//
+// Locks multiply / invert / transpose to return Mat4; dimension mix-ups
+// (mat4.multiply(out, vec3, vec3)) are ts-expect-error; lookAt's Vec3 inputs are also type-locked.
+//
+// Related: requirements §AC-12 type test + AC-02 brand mutual exclusion;
+//          research §Finding 7.3 dimension-mix-up call → ts-error template.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { mat4 } from '../index';
+import type { Mat3, Mat4, Quat, Vec3, Vec4 } from '../types';
+
+describe('mat4 — branded return-type locks', () => {
+  it('mat4.create returns Mat4', () => {
+    expectTypeOf(mat4.create()).toEqualTypeOf<Mat4>();
+  });
+
+  it('mat4.identity returns Mat4', () => {
+    expectTypeOf(mat4.identity(mat4.create())).toEqualTypeOf<Mat4>();
+  });
+
+  it('mat4.multiply returns Mat4', () => {
+    expectTypeOf(mat4.multiply(mat4.create(), mat4.create(), mat4.create())).toEqualTypeOf<Mat4>();
+  });
+
+  it('mat4.transpose returns Mat4', () => {
+    expectTypeOf(mat4.transpose(mat4.create(), mat4.create())).toEqualTypeOf<Mat4>();
+  });
+
+  it('mat4.invert returns Mat4 (does not return null, AC-08 cross-vendor rewrite)', () => {
+    expectTypeOf(mat4.invert(mat4.create(), mat4.create())).toEqualTypeOf<Mat4>();
+  });
+
+  it('mat4.perspective returns Mat4', () => {
+    expectTypeOf(mat4.perspective(mat4.create(), 1, 1, 0.1, 100)).toEqualTypeOf<Mat4>();
+  });
+
+  it('mat4.perspectiveReverseZ returns Mat4', () => {
+    expectTypeOf(mat4.perspectiveReverseZ(mat4.create(), 1, 1, 0.1, 100)).toEqualTypeOf<Mat4>();
+  });
+});
+
+describe('mat4 — cross-namespace misuse blocked at compile time (out brand lock)', () => {
+  it('mat4.identity must reject Mat3 as out', () => {
+    const m3: Mat3 = null as unknown as Mat3;
+    // @ts-expect-error — out must be Mat4, not Mat3
+    mat4.identity(m3);
+  });
+
+  it('mat4.multiply must reject Vec3 as out', () => {
+    const v3: Vec3 = null as unknown as Vec3;
+    const m4: Mat4 = mat4.create();
+    // @ts-expect-error — out must be Mat4, not Vec3
+    mat4.multiply(v3, m4, m4);
+  });
+
+  it('mat4.invert must reject Mat3 as out', () => {
+    const m3: Mat3 = null as unknown as Mat3;
+    const m4: Mat4 = mat4.create();
+    // @ts-expect-error — out must be Mat4, not Mat3
+    mat4.invert(m3, m4);
+  });
+});
+
+// M1 / t3 — mat4 transform 3-function brand mutual exclusion + return type + alias type consistency
+//
+// Related: requirements §6 AC-15 + §10.1 brand-safety row;
+//          research Finding 4 table: brand type mismatch → compile-time TS error;
+//          plan-strategy §4.3 key test points table row 6 + §7.1 brand safety.
+describe('mat4 transform 3 functions — branded return type + brand mutual exclusion (M1 / t3)', () => {
+  it('mat4.transformVec3 returns Vec3', () => {
+    const v: Vec3 = null as unknown as Vec3;
+    const m: Mat4 = mat4.create();
+    expectTypeOf(mat4.transformVec3(v, m, v)).toEqualTypeOf<Vec3>();
+  });
+
+  it('mat4.transformPoint returns Vec3', () => {
+    const v: Vec3 = null as unknown as Vec3;
+    const m: Mat4 = mat4.create();
+    expectTypeOf(mat4.transformPoint(v, m, v)).toEqualTypeOf<Vec3>();
+  });
+
+  it('mat4.transformDirection returns Vec3', () => {
+    const v: Vec3 = null as unknown as Vec3;
+    const m: Mat4 = mat4.create();
+    expectTypeOf(mat4.transformDirection(v, m, v)).toEqualTypeOf<Vec3>();
+  });
+
+  it('transformPoint shares the same type signature as transformVec3 (alias form, S-1)', () => {
+    expectTypeOf(mat4.transformPoint).toEqualTypeOf<typeof mat4.transformVec3>();
+  });
+
+  it('mat4.transformVec3 must reject Vec4 as out (Vec3 ≠ Vec4 brand mutual exclusion)', () => {
+    const v4: Vec4 = null as unknown as Vec4;
+    const m: Mat4 = mat4.create();
+    const v3: Vec3 = null as unknown as Vec3;
+    // @ts-expect-error — out must be Vec3, not Vec4
+    mat4.transformVec3(v4, m, v3);
+  });
+
+  it('mat4.transformPoint must reject Quat as out (Vec3 ≠ Quat brand mutual exclusion)', () => {
+    const q: Quat = null as unknown as Quat;
+    const m: Mat4 = mat4.create();
+    const v3: Vec3 = null as unknown as Vec3;
+    // @ts-expect-error — out must be Vec3, not Quat
+    mat4.transformPoint(q, m, v3);
+  });
+
+  it('mat4.transformDirection must reject Mat4 as out (Vec3 ≠ Mat4 brand mutual exclusion)', () => {
+    const m4: Mat4 = mat4.create();
+    const v3: Vec3 = null as unknown as Vec3;
+    // @ts-expect-error — out must be Vec3, not Mat4
+    mat4.transformDirection(m4, m4, v3);
+  });
+
+  // G-4 (roadmap 2026-06-15 game-demo-engine-gaps) — projectPoint dual of unproject
+  it('mat4.projectPoint returns Vec3', () => {
+    const v: Vec3 = null as unknown as Vec3;
+    const m: Mat4 = mat4.create();
+    expectTypeOf(mat4.projectPoint(v, v, m)).toEqualTypeOf<Vec3>();
+  });
+
+  it('mat4.projectPoint must reject Quat as out (Vec3 ≠ Quat brand mutual exclusion)', () => {
+    const q: Quat = null as unknown as Quat;
+    const m: Mat4 = mat4.create();
+    const v3: Vec3 = null as unknown as Vec3;
+    // @ts-expect-error — out must be Vec3, not Quat
+    mat4.projectPoint(q, v3, m);
+  });
+});

package/src/__tests__/mat4.test.ts

@@ -0,0 +1,162 @@
+// mat4.test.ts — mat4 unit tests (feat-20260617-host-engine-contract-and-video-cutscene M2 w4)
+//
+// Coverage: computeViewProj elementwise equals hand-computed mat4.perspective * mat4.lookAt
+// (EPS_MAT4_MUL3 = 1e-3), >= 3 param combos. Multiple fov/aspect/near/far and eye/target poses.
+// Test must NOT import any runtime type (zero-dep guard, plan-strategy §5.6).
+//
+// TDD: this file is committed RED (computeViewProj not yet implemented in mat4.ts);
+// w6 implementation greens these tests.
+//
+// Related: requirements AC-03; plan-strategy D-1; research Finding 4/5.
+
+import { describe, expect, it } from 'vitest';
+import * as mat4 from '../mat4';
+import type { Mat4 } from '../types';
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/** element-wise approximate equality with relative scaling */
+function mat4ApproxEq(a: Float32Array, b: Float32Array, eps: number): boolean {
+  for (let i = 0; i < 16; i++) {
+    const ai = a[i] as number;
+    const bi = b[i] as number;
+    const scale = Math.max(1, Math.abs(ai), Math.abs(bi));
+    if (Math.abs(ai - bi) >= eps * scale) return false;
+  }
+  return true;
+}
+
+const EPS_MAT4_MUL3 = 1e-3;
+
+/** Build VP via hand-composed lookAt + perspective + multiply (the reference). */
+function refVP(
+  out: Mat4,
+  eye: [number, number, number],
+  target: [number, number, number],
+  up: [number, number, number],
+  fov: number,
+  aspect: number,
+  near: number,
+  far: number,
+): Mat4 {
+  const view = mat4.lookAt(mat4.create(), eye, target, up);
+  const proj = mat4.perspective(mat4.create(), fov, aspect, near, far);
+  return mat4.multiply(out, proj, view);
+}
+
+// ============================================================
+// Param combo 1: default forward-looking camera
+// ============================================================
+
+describe('mat4.computeViewProj', () => {
+  it('combo 1: camera at origin, looking at -z → equals proj * lookAt', () => {
+    const eye: [number, number, number] = [0, 0, 0];
+    const target: [number, number, number] = [0, 0, -1];
+    const up: [number, number, number] = [0, 1, 0];
+    const fov = Math.PI / 3;
+    const aspect = 800 / 600;
+    const near = 0.1;
+    const far = 100;
+
+    const result = mat4.create();
+    mat4.computeViewProj(result, eye, target, up, fov, aspect, near, far);
+
+    const expected = mat4.create();
+    refVP(expected, eye, target, up, fov, aspect, near, far);
+
+    expect(mat4ApproxEq(result, expected, EPS_MAT4_MUL3)).toBe(true);
+  });
+
+  // ============================================================
+  // Param combo 2: elevated camera looking at world origin
+  // ============================================================
+
+  it('combo 2: elevated camera looking at origin → equals proj * lookAt', () => {
+    const eye: [number, number, number] = [0, 5, 10];
+    const target: [number, number, number] = [0, 0, 0];
+    const up: [number, number, number] = [0, 1, 0];
+    const fov = Math.PI / 4;
+    const aspect = 16 / 9;
+    const near = 0.1;
+    const far = 100;
+
+    const result = mat4.create();
+    mat4.computeViewProj(result, eye, target, up, fov, aspect, near, far);
+
+    const expected = mat4.create();
+    refVP(expected, eye, target, up, fov, aspect, near, far);
+
+    expect(mat4ApproxEq(result, expected, EPS_MAT4_MUL3)).toBe(true);
+  });
+
+  // ============================================================
+  // Param combo 3: off-axis camera with narrow FOV and large near/far
+  // ============================================================
+
+  it('combo 3: off-axis camera, narrow fov, large range → equals proj * lookAt', () => {
+    const eye: [number, number, number] = [10, 3, -20];
+    const target: [number, number, number] = [0, 0, 0];
+    const up: [number, number, number] = [0, 1, 0.5];
+    const fov = Math.PI / 6; // 30 deg — narrow
+    const aspect = 4 / 3;
+    const near = 1;
+    const far = 500;
+
+    const result = mat4.create();
+    mat4.computeViewProj(result, eye, target, up, fov, aspect, near, far);
+
+    const expected = mat4.create();
+    refVP(expected, eye, target, up, fov, aspect, near, far);
+
+    expect(mat4ApproxEq(result, expected, EPS_MAT4_MUL3)).toBe(true);
+  });
+
+  // ============================================================
+  // Param combo 4: infinite far plane
+  // ============================================================
+
+  it('combo 4: infinite far plane → equals proj * lookAt', () => {
+    const eye: [number, number, number] = [0, 0, 0];
+    const target: [number, number, number] = [0, 0, -1];
+    const up: [number, number, number] = [0, 1, 0];
+    const fov = Math.PI / 3;
+    const aspect = 800 / 600;
+    const near = 0.1;
+    const far = Number.POSITIVE_INFINITY;
+
+    const result = mat4.create();
+    mat4.computeViewProj(result, eye, target, up, fov, aspect, near, far);
+
+    const expected = mat4.create();
+    refVP(expected, eye, target, up, fov, aspect, near, far);
+
+    expect(mat4ApproxEq(result, expected, EPS_MAT4_MUL3)).toBe(true);
+  });
+
+  // ============================================================
+  // Param combo 5: close-to-identity view (eye almost on target → identity)
+  // ============================================================
+
+  it('combo 5: degenerate eye=target → lookAt returns identity, VP = proj * I = proj', () => {
+    const eye: [number, number, number] = [0, 0, 0];
+    const target: [number, number, number] = [0, 0, 0];
+    const up: [number, number, number] = [0, 1, 0];
+    const fov = Math.PI / 3;
+    const aspect = 800 / 600;
+    const near = 0.1;
+    const far = 100;
+
+    const result = mat4.create();
+    mat4.computeViewProj(result, eye, target, up, fov, aspect, near, far);
+
+    // When eye=target, lookAt returns identity → VP = proj * I = proj
+    const expected = mat4.create();
+    mat4.perspective(expected, fov, aspect, near, far);
+
+    expect(mat4ApproxEq(result, expected, EPS_MAT4_MUL3)).toBe(true);
+  });
+});
+
+void expect;

package/src/__tests__/noise.test.ts

@@ -0,0 +1,75 @@
+// noise.test.ts — value tests for the noise namespace (solo round 20260716-212942)
+//
+// Regression guard for the 1D Perlin noise function used by camera shake and procedural
+// effects. These tests pin:
+//   1. output in [-1, 1],
+//   2. perlin1d is deterministic (same input → same output),
+//   3. perlin1d is smooth (nearby inputs → nearby outputs, the defining noise property),
+//   4. offset channels like x, x+100, x+200 are independent (different values),
+//   5. integer lattice points return 0 (the gradient dot at distance 0).
+
+import { describe, expect, it } from 'vitest';
+import { noise } from '../index';
+
+const { perlin1d } = noise;
+
+describe('noise.perlin1d', () => {
+  it('returns values in [-1, 1]', () => {
+    for (let x = 0; x < 500; x += 0.137) {
+      const v = perlin1d(x);
+      expect(v).toBeGreaterThanOrEqual(-1);
+      expect(v).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('is deterministic', () => {
+    expect(perlin1d(3.14)).toBe(perlin1d(3.14));
+    expect(perlin1d(42)).toBe(perlin1d(42));
+    expect(perlin1d(0)).toBe(perlin1d(0));
+  });
+
+  it('is smooth: nearby inputs yield nearby outputs', () => {
+    for (let x = 1; x < 100; x += 0.7) {
+      const a = perlin1d(x);
+      const b = perlin1d(x + 0.001);
+      // The fade curve is smooth, so a tiny input change should produce a tiny output change.
+      expect(Math.abs(a - b)).toBeLessThan(0.05);
+    }
+  });
+
+  it('offset channels are independent (x, x+100, x+200)', () => {
+    // Use a non-integer input so the channels aren't all zero.
+    const a = perlin1d(50.5);
+    const b = perlin1d(150.5); // 50.5 + 100
+    const c = perlin1d(250.5); // 50.5 + 200
+    // They should not all be the same — the offset separates the channels.
+    const allSame = a === b && b === c;
+    expect(allSame).toBe(false);
+  });
+
+  it('integer lattice points return 0 (gradient dot at distance 0)', () => {
+    for (let x = 0; x < 256; x++) {
+      expect(perlin1d(x)).toBeCloseTo(0, 10);
+    }
+  });
+
+  it('integer lattice points return 0 at negative inputs too', () => {
+    expect(perlin1d(-1)).toBeCloseTo(0, 10);
+    expect(perlin1d(-42)).toBeCloseTo(0, 10);
+    expect(perlin1d(-256)).toBeCloseTo(0, 10);
+  });
+
+  it('symmetry: the same fractional offset from any integer gives the same absolute value', () => {
+    // perlin1d works on the fractional part relative to the floor — the integer part
+    // determines which hash bucket, so outputs differ between different integer segments.
+    // But the interpolation *pattern* is consistent: at the same fractional offset t, the
+    // output is somewhere between two lattice values that cross the segment.
+    // We just verify it's not NaN or out-of-range.
+    for (let x = -10; x < 10; x += 0.13) {
+      const v = perlin1d(x);
+      expect(Number.isNaN(v)).toBe(false);
+      expect(v).toBeGreaterThanOrEqual(-1);
+      expect(v).toBeLessThanOrEqual(1);
+    }
+  });
+});