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

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

@@ -0,0 +1,138 @@
+// quat.test-d.ts — branded return type + dimension-mix-up compile-time assertions (T-026)
+//
+// Locks quat.create / fromAxisAngle / fromEuler / slerp / nlerp / multiply / invert /
+// conjugate / normalize / fromRotationMatrix / fromLookAt / fromUnitVectors to return Quat;
+// dimension mix-ups (quat.multiply(out, vec3, vec3)) are ts-expect-error;
+// EulerOrder union is locked to 6 exhaustive values; fromEuler(_, _, _, _, 'INVALID') is ts-error.
+//
+// Related: requirements §AC-12 type test + AC-02 brand mutual exclusion (≥ 3 quat contributions);
+//          plan-strategy §4.2 type test;
+//          wiki/typescript-branded-types §3.1 expectTypeOf template + §7.3 ts-expect-error.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { quat } from '../index';
+import type { EulerOrder, Mat4, Quat, Vec3 } from '../types';
+
+describe('quat — branded return-type locks', () => {
+  it('quat.create returns Quat', () => {
+    expectTypeOf(quat.create()).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.identity returns Quat', () => {
+    expectTypeOf(quat.identity(quat.create())).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.fromAxisAngle returns Quat', () => {
+    expectTypeOf(
+      quat.fromAxisAngle(quat.create(), [1, 0, 0] as unknown as Vec3, 1),
+    ).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.fromEuler returns Quat', () => {
+    expectTypeOf(quat.fromEuler(quat.create(), 0, 0, 0, 'XYZ')).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.multiply returns Quat', () => {
+    expectTypeOf(quat.multiply(quat.create(), quat.create(), quat.create())).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.slerp returns Quat', () => {
+    expectTypeOf(
+      quat.slerp(quat.create(), quat.create(), quat.create(), 0.5),
+    ).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.nlerp returns Quat', () => {
+    expectTypeOf(
+      quat.nlerp(quat.create(), quat.create(), quat.create(), 0.5),
+    ).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.invert returns Quat', () => {
+    expectTypeOf(quat.invert(quat.create(), quat.create())).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.conjugate returns Quat', () => {
+    expectTypeOf(quat.conjugate(quat.create(), quat.create())).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.normalize returns Quat', () => {
+    expectTypeOf(quat.normalize(quat.create(), quat.create())).toEqualTypeOf<Quat>();
+  });
+
+  it('quat.fromLookAt returns Quat', () => {
+    expectTypeOf(
+      quat.fromLookAt(quat.create(), [0, 0, 5], [0, 0, 0], [0, 1, 0]),
+    ).toEqualTypeOf<Quat>();
+  });
+});
+
+describe('quat — cross-namespace misuse blocked at compile time (out brand lock)', () => {
+  it('quat.identity must reject Vec3 as out', () => {
+    const v: Vec3 = null as unknown as Vec3;
+    // @ts-expect-error — out must be Quat, not Vec3
+    quat.identity(v);
+  });
+
+  it('quat.multiply must reject Mat4 as out', () => {
+    const m: Mat4 = null as unknown as Mat4;
+    const q: Quat = quat.create();
+    // @ts-expect-error — out must be Quat, not Mat4
+    quat.multiply(m, q, q);
+  });
+
+  it('quat.slerp must reject Vec3 as out', () => {
+    const v: Vec3 = null as unknown as Vec3;
+    const q: Quat = quat.create();
+    // @ts-expect-error — out must be Quat, not Vec3
+    quat.slerp(v, q, q, 0.5);
+  });
+});
+
+describe('quat — EulerOrder union exhaustively locked to 6 values', () => {
+  it('EulerOrder contains the 6 entries XYZ / YXZ / ZXY / ZYX / YZX / XZY', () => {
+    expectTypeOf<EulerOrder>().toEqualTypeOf<'XYZ' | 'YXZ' | 'ZXY' | 'ZYX' | 'YZX' | 'XZY'>();
+  });
+
+  it('quat.fromEuler accepts every one of the 6 EulerOrder values', () => {
+    quat.fromEuler(quat.create(), 0, 0, 0, 'XYZ');
+    quat.fromEuler(quat.create(), 0, 0, 0, 'YXZ');
+    quat.fromEuler(quat.create(), 0, 0, 0, 'ZXY');
+    quat.fromEuler(quat.create(), 0, 0, 0, 'ZYX');
+    quat.fromEuler(quat.create(), 0, 0, 0, 'YZX');
+    quat.fromEuler(quat.create(), 0, 0, 0, 'XZY');
+  });
+
+  it('quat.fromEuler rejects string literals outside the union', () => {
+    // @ts-expect-error — 'INVALID' is not in the EulerOrder union
+    quat.fromEuler(quat.create(), 0, 0, 0, 'INVALID');
+  });
+});
+
+// M1 / t3 — quat.transformVec3 brand mutual exclusion + return type
+//
+// 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('quat.transformVec3 — branded return type + brand mutual exclusion (M1 / t3)', () => {
+  it('quat.transformVec3 returns Vec3', () => {
+    const v: Vec3 = null as unknown as Vec3;
+    const q: Quat = quat.create();
+    expectTypeOf(quat.transformVec3(v, q, v)).toEqualTypeOf<Vec3>();
+  });
+
+  it('quat.transformVec3 must reject Quat as out (Vec3 ≠ Quat brand mutual exclusion)', () => {
+    const q: Quat = quat.create();
+    const v3: Vec3 = null as unknown as Vec3;
+    // @ts-expect-error — out must be Vec3, not Quat
+    quat.transformVec3(q, q, v3);
+  });
+
+  it('quat.transformVec3 must reject Mat4 as out (Vec3 ≠ Mat4 brand mutual exclusion)', () => {
+    const m4: Mat4 = null as unknown as Mat4;
+    const q: Quat = quat.create();
+    const v3: Vec3 = null as unknown as Vec3;
+    // @ts-expect-error — out must be Vec3, not Mat4
+    quat.transformVec3(m4, q, v3);
+  });
+});

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

@@ -0,0 +1,105 @@
+// ray.property.test.ts — fast-check round-trip property (feat-20260617-host-engine-contract-and-video-cutscene M2 w7)
+//
+// world -> screen -> world round-trip on a realistic view-projection (lookAt + perspective):
+//   screenToRay(worldToScreen(v)) yields a Ray that passes through v, for v inside the frustum.
+//
+// On-screen domain only: screenToRay clamps off-screen pixel coords back to the viewport edge
+// (research Finding 6 / R-5), so off-screen points do not round-trip. We sample world points
+// roughly inside the frustum the VP below describes, and assert onScreen before checking.
+//
+// EPS_MAT4_MUL3 = 1e-3 (two w-divides + a matrix invert; borrowed from mat4.property.test.ts:214-253).
+// >= 100 samples (default numRuns).
+//
+// Related: requirements AC-02; plan-strategy §5.2 (R-5: arbitrary restricted to on-screen domain);
+//          research Finding 6 (screenToRay clamps screen coords).
+
+import { fc, test } from '@fast-check/vitest';
+import { describe, expect } from 'vitest';
+import * as mat4 from '../mat4';
+import * as ray from '../ray';
+import type { Mat4, Vec2, Vec3 } from '../types';
+import * as vec2 from '../vec2';
+import { EPS_MAT4_MUL3 } from './_arbs';
+
+const NUM_RUNS = Number.parseInt(
+  (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env
+    ?.PROPERTY_NUM_RUNS ?? '100',
+  10,
+);
+
+const CANVAS_W = 800;
+const CANVAS_H = 600;
+const FOV = Math.PI / 3;
+const ASPECT = CANVAS_W / CANVAS_H;
+const NEAR = 0.1;
+const FAR = 100;
+
+/** Build the reference forward-looking view-projection (camera at origin, looking down -z). */
+function makeVP(): Mat4 {
+  const view = mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]);
+  const proj = mat4.perspective(mat4.create(), FOV, ASPECT, NEAR, FAR);
+  return mat4.multiply(mat4.create(), proj, view);
+}
+
+/** Distance from point p to the line defined by the ray (origin o, unit direction d). */
+function pointToRayDistance(p: Vec3, r: ray.Ray): number {
+  const ox = r[0] as number;
+  const oy = r[1] as number;
+  const oz = r[2] as number;
+  const dx = r[3] as number;
+  const dy = r[4] as number;
+  const dz = r[5] as number;
+  const wx = (p[0] as number) - ox;
+  const wy = (p[1] as number) - oy;
+  const wz = (p[2] as number) - oz;
+  // perpendicular component = w - (w·d) d  (d is unit length)
+  const t = wx * dx + wy * dy + wz * dz;
+  const px = wx - t * dx;
+  const py = wy - t * dy;
+  const pz = wz - t * dz;
+  return Math.sqrt(px * px + py * py + pz * pz);
+}
+
+describe('ray world->screen->world round-trip (AC-02)', () => {
+  test.prop(
+    {
+      // World points roughly inside the frustum the VP above describes (in front of camera).
+      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 },
+  )('on-screen point lies on screenToRay(worldToScreen(v))', ({ v }) => {
+    const VP = makeVP();
+
+    const px = vec2.create() as Vec2;
+    const { onScreen, behind } = ray.worldToScreen(px, v, VP, CANVAS_W, CANVAS_H);
+
+    // Restrict the property to the on-screen domain: off-screen pixels are clamped by
+    // screenToRay and would not round-trip (R-5).
+    if (behind || !onScreen) return true;
+
+    const view = mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]);
+    const proj = mat4.perspective(mat4.create(), FOV, ASPECT, NEAR, FAR);
+    const r = ray.screenToRay(
+      ray.create(),
+      px[0] as number,
+      px[1] as number,
+      CANVAS_W,
+      CANVAS_H,
+      view,
+      proj,
+      'perspective',
+    );
+
+    // v must lie on the recovered ray within the chained-mul tolerance.
+    return pointToRayDistance(v, r) < EPS_MAT4_MUL3;
+  });
+});
+
+void fc;
+void expect;