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

package/src/__tests__/bounds2.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest';
+import * as box2 from '../box2';
+import * as circle2 from '../circle2';
+import * as ray2 from '../ray2';
+import * as vec2 from '../vec2';
+
+function expectBox(
+  box: box2.Box2Like,
+  minX: number,
+  minY: number,
+  maxX: number,
+  maxY: number,
+): void {
+  expect(box[0]).toBe(minX);
+  expect(box[1]).toBe(minY);
+  expect(box[2]).toBe(maxX);
+  expect(box[3]).toBe(maxY);
+}
+
+describe('box2', () => {
+  it('builds center/half-size and point-cloud bounds', () => {
+    const out = box2.create();
+    expect(box2.fromCenter(out, [2, -1], [3, 4])).toBe(out);
+    expectBox(out, -1, -5, 5, 3);
+
+    box2.fromPoints(out, [
+      [-2, 4],
+      [5, 0],
+      [1, -3],
+    ]);
+    expectBox(out, -2, -3, 5, 4);
+  });
+
+  it('supports closest point, containment, merge, grow, and shrink', () => {
+    const box = box2.create(-2, -1, 2, 3);
+    const point = vec2.create();
+    box2.closestPoint(point, box, [5, -4]);
+    expect(point).toEqual(new Float32Array([2, -1]));
+    expect(box2.containsPoint(box, [2, 3])).toBe(true);
+    expect(box2.containsBox(box, box2.create(-1, 0, 1, 2))).toBe(true);
+
+    const merged = box2.create();
+    box2.merge(merged, box, box2.create(0, -4, 5, 1));
+    expectBox(merged, -2, -4, 5, 3);
+    box2.grow(merged, box, [1, 2]);
+    expectBox(merged, -3, -3, 3, 5);
+    box2.shrink(merged, box, [1, 1]);
+    expectBox(merged, -1, 0, 1, 2);
+  });
+
+  it('intersects boxes and circles at the boundary', () => {
+    const box = box2.create(-1, -1, 1, 1);
+    expect(box2.intersectsBox(box, box2.create(1, 0, 2, 1))).toBe(true);
+    expect(box2.intersectsBox(box, box2.create(1.01, 0, 2, 1))).toBe(false);
+    expect(box2.intersectsCircle(box, circle2.create(2, 0, 1))).toBe(true);
+    expect(box2.intersectsCircle(box, circle2.create(2.01, 0, 1))).toBe(false);
+    expect(box2.intersectsCircle(box, Float32Array.of(0, 0, -1))).toBe(false);
+  });
+});
+
+describe('circle2', () => {
+  it('builds an enclosing circle from points and converts to an AABB', () => {
+    const circle = circle2.create();
+    circle2.fromPoints(circle, [
+      [-2, 0],
+      [2, 0],
+      [0, 1],
+    ]);
+    expect(circle[0]).toBe(0);
+    expect(circle[1]).toBe(0.5);
+    expect(circle[2]).toBeCloseTo(2.06155, 4);
+
+    const box = box2.create();
+    circle2.toBox(box, circle);
+    const radius = circle[2] as number;
+    expectBox(box, -radius, 0.5 - radius, radius, 0.5 + radius);
+  });
+
+  it('handles closest point, intersections, and merge', () => {
+    const circle = circle2.create(0, 0, 2);
+    const point = vec2.create();
+    circle2.closestPoint(point, circle, [4, 0]);
+    expect(point).toEqual(new Float32Array([2, 0]));
+    expect(circle2.containsPoint(circle, [2, 0])).toBe(true);
+    expect(circle2.intersectsCircle(circle, circle2.create(3, 0, 1))).toBe(true);
+    expect(circle2.intersectsCircle(circle, circle2.create(3.01, 0, 1))).toBe(false);
+    expect(circle2.intersectsBox(circle, box2.create(-1, -1, 1, 1))).toBe(true);
+    circle2.closestPoint(point, Float32Array.of(0, 0, -1), [4, 0]);
+    expect(point).toEqual(new Float32Array([0, 0]));
+
+    const merged = circle2.create();
+    circle2.merge(merged, circle, circle2.create(5, 0, 1));
+    expect(merged[0]).toBe(2);
+    expect(merged[1]).toBe(0);
+    expect(merged[2]).toBe(4);
+  });
+});
+
+describe('ray2', () => {
+  it('intersects AABBs from outside, from inside, and with parallel axes', () => {
+    const ray = ray2.create(undefined, [-5, 0], [2, 0], 20);
+    const box = box2.create(-1, -1, 1, 1);
+    expect(ray2.rayAabbIntersects(ray, box)).toEqual({ hit: true, t: 4 });
+    expect(ray2.rayAabbIntersects(ray2.create(undefined, [0, 0], [1, 0], 0), box)).toEqual({
+      hit: true,
+      t: 0,
+    });
+    expect(ray2.rayAabbIntersects(ray2.create(undefined, [-5, 2], [1, 0], 20), box).hit).toBe(
+      false,
+    );
+    expect(ray2.rayAabbIntersects(ray2.create(undefined, [0, 0], [0, 1], 20), box)).toEqual({
+      hit: true,
+      t: 0,
+    });
+  });
+
+  it('intersects circles and respects the finite maximum distance', () => {
+    const hit = ray2.rayCircleIntersects(
+      ray2.create(undefined, [-5, 0], [2, 0], 20),
+      circle2.create(0, 0, 1),
+    );
+    expect(hit.hit).toBe(true);
+    expect(hit.t).toBeCloseTo(4, 6);
+    expect(
+      ray2.rayCircleIntersects(ray2.create(undefined, [-5, 0], [1, 0], 3), circle2.create(0, 0, 1))
+        .hit,
+    ).toBe(false);
+    expect(
+      ray2.rayCircleIntersects(ray2.create(undefined, [0, 0], [1, 0], 0), circle2.create(0, 0, 1)),
+    ).toEqual({ hit: true, t: 0 });
+  });
+
+  it('sweeps AABBs and circles through matching target volumes', () => {
+    const ray = ray2.create(undefined, [0, 0], [0, 2], 20);
+    const movingBox = box2.create(-1, -1, 1, 1);
+    const targetBox = box2.create(-1, 4, 1, 6);
+    expect(ray2.aabbCastIntersects(ray, movingBox, targetBox)).toEqual({ hit: true, t: 3 });
+
+    const movingCircle = circle2.create(0, 0, 1);
+    const targetCircle = circle2.create(0, 5, 1);
+    const circleHit = ray2.circleCastIntersects(ray, movingCircle, targetCircle);
+    expect(circleHit.hit).toBe(true);
+    expect(circleHit.t).toBeCloseTo(3, 6);
+    expect(ray2.circleCastIntersects(ray, movingCircle, circle2.create(3.1, 5, 1)).hit).toBe(false);
+  });
+});

package/src/__tests__/box3.test.ts

@@ -0,0 +1,277 @@
+// box3.test.ts — box3.fromPositions TDD RED spec (m1-1)
+//
+// RED phase: box3.fromPositions is not yet implemented (M2).
+// All tests assert the numerical semantics that fromPositions must fulfill.
+//
+// Coverage: multi-point tight enclosure, single point (min==max), empty input
+// (inverted-infinity default), degenerate plane (zero-thickness axis),
+// out-param return-reference, migration equivalence with geometry
+// aabbFromPositions (fixed expected values), non-3-multiple trailing
+// behaviour.
+//
+// Related: requirements AC-06/AC-07; plan-strategy D-1/D-2/D-5;
+//          plan-tasks.json m1-1 acceptanceCheck.
+
+import { describe, expect, it } from 'vitest';
+import * as box3 from '../box3';
+
+// ============================================================
+// Helpers
+// ============================================================
+
+/** Assert a Box3 has [minX, minY, minZ, maxX, maxY, maxZ] exactly. */
+function expectBox3(
+  actual: Float32Array,
+  minX: number,
+  minY: number,
+  minZ: number,
+  maxX: number,
+  maxY: number,
+  maxZ: number,
+): void {
+  expect(actual[0]).toBe(minX);
+  expect(actual[1]).toBe(minY);
+  expect(actual[2]).toBe(minZ);
+  expect(actual[3]).toBe(maxX);
+  expect(actual[4]).toBe(maxY);
+  expect(actual[5]).toBe(maxZ);
+}
+
+/** Assert min == max on every axis (single-point or degenerate). */
+function expectBox3Point(actual: Float32Array, x: number, y: number, z: number): void {
+  expectBox3(actual, x, y, z, x, y, z);
+}
+
+// ============================================================
+// Multi-point tight enclosure
+// ============================================================
+
+describe('box3.fromPositions — multi-point', () => {
+  it('3 points: min/max across all xyz components', () => {
+    const positions = [1, 10, 100, -5, 0, 50, 3, 20, 0];
+    // Points: (1,10,100), (-5,0,50), (3,20,0)
+    const out = box3.create();
+    const result = box3.fromPositions(out, positions);
+    expect(result).toBe(out); // out-param returns same reference
+    expectBox3(out, -5, 0, 0, 3, 20, 100);
+  });
+
+  it('5 points with negative coords: correct min/max envelope', () => {
+    const positions = [-1, -2, -3, 4, 5, 6, -7, 8, -9, 0, 0, 0, 10, -10, 1];
+    // Points: (-1,-2,-3), (4,5,6), (-7,8,-9), (0,0,0), (10,-10,1)
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, -7, -10, -9, 10, 8, 6);
+  });
+});
+
+// ============================================================
+// Single point (min == max on every axis)
+// ============================================================
+
+describe('box3.fromPositions — single point', () => {
+  it('one point: min == max on all axes', () => {
+    const out = box3.create();
+    box3.fromPositions(out, [7, 8, 9]);
+    expectBox3Point(out, 7, 8, 9);
+  });
+
+  it('origin point', () => {
+    const out = box3.create();
+    box3.fromPositions(out, [0, 0, 0]);
+    expectBox3Point(out, 0, 0, 0);
+  });
+});
+
+// ============================================================
+// Empty / insufficient input → inverted-infinity empty box
+// ============================================================
+
+describe('box3.fromPositions — empty input', () => {
+  it('0 vertices → inverted-infinity empty box (box3.create() default)', () => {
+    const out = box3.create();
+    box3.fromPositions(out, []);
+    expectBox3(
+      out,
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+    );
+  });
+
+  it('1 element (incomplete point) → inverted-infinity empty box', () => {
+    const out = box3.create();
+    box3.fromPositions(out, [42]);
+    expectBox3(
+      out,
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+    );
+  });
+
+  it('2 elements (incomplete point) → inverted-infinity empty box', () => {
+    const out = box3.create();
+    box3.fromPositions(out, [1, 2]);
+    expectBox3(
+      out,
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+    );
+  });
+
+  it('inverted-empty box is not pickable per pick.ts convention (min > max)', () => {
+    const out = box3.create();
+    box3.fromPositions(out, []);
+    // pick.ts checks: localAabb[0] > localAabb[3] → skip
+    // inverted-infinity: +Inf > -Inf → true → correctly skipped
+    expect(out[0] as number).toBeGreaterThan(out[3] as number);
+  });
+});
+
+// ============================================================
+// Degenerate plane (one axis zero thickness)
+// ============================================================
+
+describe('box3.fromPositions — degenerate plane', () => {
+  it('all z=0 → minZ == maxZ == 0 (zero-thickness on Z axis)', () => {
+    const positions = [1, 2, 0, 3, 4, 0, 5, 1, 0, 0, 6, 0];
+    // Points: (1,2,0), (3,4,0), (5,1,0), (0,6,0)
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, 0, 1, 0, 5, 6, 0);
+    expect(out[2]).toBe(out[5]); // minZ == maxZ == 0
+  });
+
+  it('all x=0 → minX == maxX == 0 (zero-thickness on X axis)', () => {
+    const positions = [0, 1, 2, 0, 3, 4, 0, 5, 6];
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, 0, 1, 2, 0, 5, 6);
+    expect(out[0]).toBe(out[3]); // minX == maxX == 0
+  });
+
+  it('two points same z → degenerate XY plane strip', () => {
+    const positions = [-2, 0, 5, 3, 0, 5];
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, -2, 0, 5, 3, 0, 5);
+    expect(out[1]).toBe(out[4]); // minY == maxY == 0
+    expect(out[2]).toBe(out[5]); // minZ == maxZ == 5
+  });
+});
+
+// ============================================================
+// Migration equivalence: fixed expected values matching
+// geometry aabbFromPositions output for the same inputs
+// (no dynamic dependency on geometry package — values are
+// hand-computed from the algorithm in box.ts:162-191)
+// ============================================================
+
+describe('box3.fromPositions — aabbFromPositions equivalence', () => {
+  it('matches aabbFromPositions: 3-point general case', () => {
+    // geometry aabbFromPositions would output [1, 1, 0, 4, 8, 6]
+    // for positions [1,2,3, 4,1,6, 2,8,0]
+    const positions = [1, 2, 3, 4, 1, 6, 2, 8, 0];
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, 1, 1, 0, 4, 8, 6);
+  });
+
+  it('matches aabbFromPositions: 6-point all-positive', () => {
+    // Positions: (10,20,30), (5,100,5), (1,1,1), (50,25,0), (30,30,30), (0,0,99)
+    // min: (0,0,0), max: (50,100,99)
+    const positions = [10, 20, 30, 5, 100, 5, 1, 1, 1, 50, 25, 0, 30, 30, 30, 0, 0, 99];
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, 0, 0, 0, 50, 100, 99);
+  });
+
+  it('matches aabbFromPositions: negative-and-positive mix', () => {
+    // Positions: (-5,-10,-15), (3,7,-2)
+    // min: (-5,-10,-15), max: (3,7,-2)
+    const positions = [-5, -10, -15, 3, 7, -2];
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, -5, -10, -15, 3, 7, -2);
+  });
+
+  it('matches aabbFromPositions: single point case', () => {
+    // aabbFromPositions seeds from positions[0..2] and never enters the loop
+    const positions = [42, 17, 99];
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3Point(out, 42, 17, 99);
+  });
+
+  it('matches aabbFromPositions: empty input → inverted-infinity', () => {
+    // aabbFromPositions with Float32Array(0): returns inverted-infinity
+    const out = box3.create();
+    box3.fromPositions(out, []);
+    expectBox3(
+      out,
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+    );
+  });
+});
+
+// ============================================================
+// Non-3-multiple trailing: behaviour matches aabbFromPositions
+// (plan-strategy S5.3: trailing elements of an incomplete last point behave identically to old implementation)
+// ============================================================
+
+describe('box3.fromPositions — non-3-multiple trailing', () => {
+  it('5 elements (last point has 2 values): matches aabbFromPositions', () => {
+    // aabbFromPositions: seeds from positions[0..2]=(1,2,3), then i=3:
+    // x=4, y=5, z=positions[5]=undefined → NaN; NaN<3 and NaN>3 both false
+    // → minZ/maxZ stay at 3 (unchanged from seed).
+    const positions = [1, 2, 3, 4, 5];
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, 1, 2, 3, 4, 5, 3);
+  });
+
+  it('4 elements (last point has 1 value): matches aabbFromPositions', () => {
+    // Seeds from (1,2,3), i=3: x=4, y=positions[4]=undefined,
+    // z=positions[5]=undefined → NaN comparisons all false → y,z unchanged.
+    const positions = [1, 2, 3, 4];
+    const out = box3.create();
+    box3.fromPositions(out, positions);
+    expectBox3(out, 1, 2, 3, 4, 2, 3);
+  });
+});
+
+// ============================================================
+// Out-param identity
+// ============================================================
+
+describe('box3.fromPositions — out-param contract', () => {
+  it('returns the same Box3 reference passed as out', () => {
+    const out = box3.create();
+    const result = box3.fromPositions(out, [1, 2, 3]);
+    expect(result).toBe(out);
+  });
+
+  it('writes to pre-existing non-default out, overwriting previous state', () => {
+    const out = box3.create(100, 100, 100, 200, 200, 200);
+    box3.fromPositions(out, [5, 5, 5, -5, -5, -5]);
+    expectBox3(out, -5, -5, -5, 5, 5, 5);
+  });
+});
+
+void expect;

package/src/__tests__/easing.test.ts

@@ -0,0 +1,109 @@
+// easing.test.ts — value tests for the easing namespace (solo round 20260713-233409)
+//
+// Regression guard for the friction that motivated the namespace: forgeax's math had no
+// easing functions, so non-linear motion forced hand-rolling curves + the [0,1] clamp.
+// These tests pin the polynomial curves and the ElasticInOut endpoint contract:
+//   1. endpoints f(0)=0, f(1)=1,
+//   2. input clamp: t<0 → 0, t>1 → 1 (saturate, not extrapolate),
+//   3. symmetric midpoint f(0.5)=0.5,
+//   4. exact polynomial match at sampled t,
+//   5. monotonic non-decreasing on [0,1],
+//   6. S-shape: below the diagonal early (f(0.25)<0.25), above it late (f(0.75)>0.75).
+
+import { describe, expect, it } from 'vitest';
+import { easing } from '../index';
+
+const { cubicInOut, elasticInOut, smoothstep, smootherstep } = easing;
+
+describe('easing.cubicInOut', () => {
+  it('matches Bevy cubic in/out and clamps input', () => {
+    expect(cubicInOut(-1)).toBe(0);
+    expect(cubicInOut(0)).toBe(0);
+    expect(cubicInOut(0.25)).toBeCloseTo(0.0625, 12);
+    expect(cubicInOut(0.5)).toBeCloseTo(0.5, 12);
+    expect(cubicInOut(0.75)).toBeCloseTo(0.9375, 12);
+    expect(cubicInOut(1)).toBe(1);
+    expect(cubicInOut(2)).toBe(1);
+  });
+});
+
+describe('easing.smoothstep', () => {
+  it('endpoints: f(0)=0, f(1)=1', () => {
+    expect(smoothstep(0)).toBeCloseTo(0, 12);
+    expect(smoothstep(1)).toBeCloseTo(1, 12);
+  });
+
+  it('clamps input to [0,1] (saturate, not extrapolate)', () => {
+    expect(smoothstep(-2)).toBe(0);
+    expect(smoothstep(5)).toBe(1);
+  });
+
+  it('symmetric midpoint f(0.5)=0.5', () => {
+    expect(smoothstep(0.5)).toBeCloseTo(0.5, 12);
+  });
+
+  it('matches 3t² − 2t³ at sampled t', () => {
+    for (const t of [0.1, 0.25, 0.4, 0.6, 0.75, 0.9]) {
+      expect(smoothstep(t)).toBeCloseTo(t * t * (3 - 2 * t), 12);
+    }
+  });
+
+  it('monotonic non-decreasing on [0,1]', () => {
+    let prev = -1;
+    for (let i = 0; i <= 20; i++) {
+      const v = smoothstep(i / 20);
+      expect(v).toBeGreaterThanOrEqual(prev);
+      prev = v;
+    }
+  });
+
+  it('S-shape: slow-in below diagonal early, slow-out above late', () => {
+    expect(smoothstep(0.25)).toBeLessThan(0.25);
+    expect(smoothstep(0.75)).toBeGreaterThan(0.75);
+  });
+});
+
+describe('easing.smootherstep', () => {
+  it('endpoints: f(0)=0, f(1)=1', () => {
+    expect(smootherstep(0)).toBeCloseTo(0, 12);
+    expect(smootherstep(1)).toBeCloseTo(1, 12);
+  });
+
+  it('clamps input to [0,1]', () => {
+    expect(smootherstep(-1)).toBe(0);
+    expect(smootherstep(2)).toBe(1);
+  });
+
+  it('symmetric midpoint f(0.5)=0.5', () => {
+    expect(smootherstep(0.5)).toBeCloseTo(0.5, 12);
+  });
+
+  it('matches 6t⁵ − 15t⁴ + 10t³ at sampled t', () => {
+    for (const t of [0.1, 0.25, 0.4, 0.6, 0.75, 0.9]) {
+      expect(smootherstep(t)).toBeCloseTo(6 * t ** 5 - 15 * t ** 4 + 10 * t ** 3, 12);
+    }
+  });
+
+  it('S-shape: even flatter endpoints than smoothstep near 0', () => {
+    // smootherstep has a flatter start (zero 2nd derivative), so at a small t it eases
+    // in LESS than smoothstep (stays closer to 0 longer).
+    expect(smootherstep(0.15)).toBeLessThan(smoothstep(0.15));
+    expect(smootherstep(0.25)).toBeLessThan(0.25);
+    expect(smootherstep(0.75)).toBeGreaterThan(0.75);
+  });
+});
+
+describe('easing.elasticInOut', () => {
+  it('clamps and preserves exact endpoints', () => {
+    expect(elasticInOut(-1)).toBe(0);
+    expect(elasticInOut(0)).toBe(0);
+    expect(elasticInOut(0.5)).toBeCloseTo(0.5, 12);
+    expect(elasticInOut(1)).toBe(1);
+    expect(elasticInOut(2)).toBe(1);
+  });
+
+  it('has the expected overshoot on both halves', () => {
+    expect(elasticInOut(0.35)).toBeLessThan(0);
+    expect(elasticInOut(0.65)).toBeGreaterThan(1);
+  });
+});

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

@@ -0,0 +1,63 @@
+// euler.test-d.ts — branded return type + EulerOrder union compile-time assertions (T-026)
+//
+// Locks the return types of euler.create / set / clone / toQuat / fromQuat / fromRotationMatrix;
+// EulerOrder union has 6 exhaustive members; euler.fromQuat(q, 'INVALID') is ts-error.
+//
+// Related: requirements §AC-12 type test; plan-strategy §4.2 type test;
+//          wiki/typescript-branded-types §3.1 expectTypeOf template.
+
+import { describe, expectTypeOf, it } from 'vitest';
+import { euler, quat } from '../index';
+import type { Euler, EulerOrder, Mat3, Quat } from '../types';
+
+describe('euler — return-type locks', () => {
+  it('euler.create returns Euler', () => {
+    expectTypeOf(euler.create()).toEqualTypeOf<Euler>();
+  });
+
+  it('euler.clone returns Euler', () => {
+    expectTypeOf(euler.clone(euler.create())).toEqualTypeOf<Euler>();
+  });
+
+  it('euler.set returns Euler', () => {
+    expectTypeOf(euler.set(euler.create(), 0, 0, 0, 'XYZ')).toEqualTypeOf<Euler>();
+  });
+
+  it('euler.toQuat returns Quat', () => {
+    expectTypeOf(euler.toQuat(quat.create(), euler.create())).toEqualTypeOf<Quat>();
+  });
+
+  it('euler.fromQuat returns Euler', () => {
+    expectTypeOf(euler.fromQuat(euler.create(), quat.create(), 'XYZ')).toEqualTypeOf<Euler>();
+  });
+
+  it('euler.fromRotationMatrix returns Euler', () => {
+    const m: Mat3 = null as unknown as Mat3;
+    expectTypeOf(euler.fromRotationMatrix(euler.create(), m, 'XYZ')).toEqualTypeOf<Euler>();
+  });
+});
+
+describe('euler — EulerOrder union lock + invalid-order rejection', () => {
+  it('EulerOrder union exhaustive over 6 members', () => {
+    expectTypeOf<EulerOrder>().toEqualTypeOf<'XYZ' | 'YXZ' | 'ZXY' | 'ZYX' | 'YZX' | 'XZY'>();
+  });
+
+  it('euler.set accepts every one of the 6 EulerOrder values', () => {
+    euler.set(euler.create(), 0, 0, 0, 'XYZ');
+    euler.set(euler.create(), 0, 0, 0, 'YXZ');
+    euler.set(euler.create(), 0, 0, 0, 'ZXY');
+    euler.set(euler.create(), 0, 0, 0, 'ZYX');
+    euler.set(euler.create(), 0, 0, 0, 'YZX');
+    euler.set(euler.create(), 0, 0, 0, 'XZY');
+  });
+
+  it('euler.fromQuat rejects the INVALID literal', () => {
+    // @ts-expect-error — 'INVALID' is not in the EulerOrder union
+    euler.fromQuat(euler.create(), quat.create(), 'INVALID');
+  });
+
+  it('euler.set rejects the INVALID literal', () => {
+    // @ts-expect-error — 'INVALID' is not in the EulerOrder union
+    euler.set(euler.create(), 0, 0, 0, 'INVALID');
+  });
+});

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

@@ -0,0 +1,47 @@
+// mat3.test-d.ts — branded return type + dimension-mix-up compile-time assertions (T-018)
+//
+// Locks multiply / invert / transpose to return Mat3; dimension mix-ups are 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 { mat3 } from '../index';
+import type { Mat3, Mat4, Vec3 } from '../types';
+
+describe('mat3 — branded return-type locks', () => {
+  it('mat3.create returns Mat3', () => {
+    expectTypeOf(mat3.create()).toEqualTypeOf<Mat3>();
+  });
+
+  it('mat3.identity returns Mat3', () => {
+    expectTypeOf(mat3.identity(mat3.create())).toEqualTypeOf<Mat3>();
+  });
+
+  it('mat3.multiply returns Mat3', () => {
+    expectTypeOf(mat3.multiply(mat3.create(), mat3.create(), mat3.create())).toEqualTypeOf<Mat3>();
+  });
+
+  it('mat3.transpose returns Mat3', () => {
+    expectTypeOf(mat3.transpose(mat3.create(), mat3.create())).toEqualTypeOf<Mat3>();
+  });
+
+  it('mat3.invert returns Mat3 (does not return null, D-P1)', () => {
+    expectTypeOf(mat3.invert(mat3.create(), mat3.create())).toEqualTypeOf<Mat3>();
+  });
+});
+
+describe('mat3 — cross-namespace misuse blocked at compile time', () => {
+  it('mat3.multiply must reject Mat4 as out', () => {
+    const m4: Mat4 = null as unknown as Mat4;
+    const m3: Mat3 = mat3.create();
+    // @ts-expect-error — out must be Mat3, not Mat4
+    mat3.multiply(m4, m3, m3);
+  });
+
+  it('mat3.identity must reject Vec3 as out', () => {
+    const v3: Vec3 = null as unknown as Vec3;
+    // @ts-expect-error — out must be Mat3, not Vec3
+    mat3.identity(v3);
+  });
+});