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

package/dist/vec2.d.ts

@@ -0,0 +1,76 @@
+import type { Vec2, Vec2Like } from './types';
+/** Create a Vec2 (zero vector by default). */
+export declare function create(x?: number, y?: number): Vec2;
+/** Allocate a new Vec2 copy. Difference from copy: clone allocates, copy writes into an existing out. */
+export declare function clone(a: Vec2Like): Vec2;
+/** out = a. Returns out. aliasing-safe (copy(v, v) is a no-op). */
+export declare function copy(out: Vec2, a: Vec2Like): Vec2;
+/** Write the components and return out. */
+export declare function set(out: Vec2, x: number, y: number): Vec2;
+/**
+ * Approximate equality: every component differs by ≤ epsilon. NaN inputs always return false (matches IEEE 754).
+ */
+export declare function equals(a: Vec2Like, b: Vec2Like, epsilon?: number): boolean;
+/** out = a + b. aliasing-safe. */
+export declare function add(out: Vec2, a: Vec2Like, b: Vec2Like): Vec2;
+/** out = a - b. aliasing-safe. */
+export declare function sub(out: Vec2, a: Vec2Like, b: Vec2Like): Vec2;
+/** out = a * s. */
+export declare function scale(out: Vec2, a: Vec2Like, s: number): Vec2;
+/** out = -a. The `0 - x` form avoids -0 (test toBe(0) uses Object.is and distinguishes ±0). */
+export declare function negate(out: Vec2, a: Vec2Like): Vec2;
+/** Dot product a · b. */
+export declare function dot(a: Vec2Like, b: Vec2Like): number;
+/** Squared length |a|² (avoids sqrt overhead; useful on hot paths comparing distances). */
+export declare function lengthSq(a: Vec2Like): number;
+/** Euclidean length |a|. */
+export declare function length(a: Vec2Like): number;
+/** Distance between two points |a - b|. */
+export declare function distance(a: Vec2Like, b: Vec2Like): number;
+/**
+ * out = a / |a| (unit-length).
+ *
+ * @degrade Zero vector (|a|² < EPS_NORMALIZE) silently falls back to the zero vector;
+ * no NaN, no throw (gl-matrix style, AC-06 / D-P12).
+ * @degrade NaN inputs → NaN outputs: when a component is NaN, lenSq=NaN; the `lenSq < EPS`
+ * branch is false → goes through 1/sqrt(NaN)=NaN → output is all NaN (IEEE-754 NaN propagation;
+ * still does not throw).
+ *
+ * @example
+ * ```ts
+ * vec2.normalize(out, [3, 4]);     // → (0.6, 0.8)
+ * vec2.normalize(out, [0, 0]);     // → (0, 0) zero vector falls back (no NaN; AC-06 no throw)
+ * vec2.normalize(out, [NaN, 1]);   // → (NaN, NaN) IEEE-754 propagation
+ * ```
+ */
+export declare function normalize(out: Vec2, a: Vec2Like): Vec2;
+/** out = lerp(a, b, t). t is not clamped (extrapolation semantics matches glam / wgpu-matrix). aliasing-safe. */
+export declare function lerp(out: Vec2, a: Vec2Like, b: Vec2Like, t: number): Vec2;
+/**
+ * out = frame-rate-INDEPENDENT exponential smoothing of `current` toward `target`:
+ * `lerp(current, target, 1 − exp(−decayRate · dt))`. Semantics match Bevy
+ * `StableInterpolate::smooth_nudge` / three.js `MathUtils.damp` (1st-order decay, NOT Unity
+ * `SmoothDamp`'s 2nd-order spring). `dt=0` → out=current; large `decayRate·dt` → out≈target.
+ * Frame-rate independent by construction (one `dt` step = two composed `dt/2` steps). aliasing-safe.
+ * See vec3.smoothDamp for the full contract. */
+export declare function smoothDamp(out: Vec2, current: Vec2Like, target: Vec2Like, decayRate: number, dt: number): Vec2;
+/**
+ * out = Catmull-Rom spline point on the segment between `p1` and `p2`, with `p0` / `p3` the
+ * neighbor control points setting the endpoint tangents (tension 0.5 — the Bevy
+ * `CubicCardinalSpline::new_catmull_rom` / three.js default). Interpolates the control points
+ * (`t=0` → `p1`, `t=1` → `p2`). See vec3.catmullRom for the full contract + whole-polyline
+ * sampling. aliasing-safe. */
+export declare function catmullRom(out: Vec2, p0: Vec2Like, p1: Vec2Like, p2: Vec2Like, p3: Vec2Like, t: number): Vec2;
+/** Component-wise min. */
+export declare function min(out: Vec2, a: Vec2Like, b: Vec2Like): Vec2;
+/** Component-wise max. */
+export declare function max(out: Vec2, a: Vec2Like, b: Vec2Like): Vec2;
+/**
+ * out = perp(a) — 2D counter-clockwise 90° rotation: (x, y) → (-y, x).
+ *
+ * Derives from cross(a, b) reducing to a scalar determinant in 2D; this API serves hot paths
+ * (collision / normals).
+ * aliasing-safe: reads a's components into locals before writing out.
+ */
+export declare function perp(out: Vec2, a: Vec2Like): Vec2;
+//# sourceMappingURL=vec2.d.ts.map

package/dist/vec2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec2.d.ts","sourceRoot":"","sources":["../src/vec2.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE9C,8CAA8C;AAC9C,wBAAgB,MAAM,CAAC,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,IAAI,CAEzC;AAED,yGAAyG;AACzG,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAEvC;AAED,mEAAmE;AACnE,wBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAIjD;AAED,2CAA2C;AAC3C,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAIzD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,SAAO,GAAG,OAAO,CAOxE;AAED,kCAAkC;AAClC,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAQ7D;AAED,kCAAkC;AAClC,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAQ7D;AAED,mBAAmB;AACnB,wBAAgB,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAI7D;AAED,+FAA+F;AAC/F,wBAAgB,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAInD;AAED,yBAAyB;AACzB,wBAAgB,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAEpD;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAI5C;AAED,4BAA4B;AAC5B,wBAAgB,MAAM,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAI1C;AAED,2CAA2C;AAC3C,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAIzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAatD;AAED,iHAAiH;AACjH,wBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAQzE;AAED;;;;;;gDAMgD;AAChD,wBAAgB,UAAU,CACxB,GAAG,EAAE,IAAI,EACT,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,GACT,IAAI,CAEN;AAED;;;;;8BAK8B;AAC9B,wBAAgB,UAAU,CACxB,GAAG,EAAE,IAAI,EACT,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,QAAQ,EACZ,CAAC,EAAE,MAAM,GACR,IAAI,CAMN;AAED,0BAA0B;AAC1B,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAI7D;AAED,0BAA0B;AAC1B,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAMjD"}

package/dist/vec3.d.ts

@@ -0,0 +1,82 @@
+import type { Vec3, Vec3Like } from './types';
+export type { Vec3, Vec3Like };
+/** Create a Vec3 (zero vector by default). */
+export declare function create(x?: number, y?: number, z?: number): Vec3;
+/** Allocate a new Vec3 copy. */
+export declare function clone(a: Vec3Like): Vec3;
+/** out = a. aliasing-safe (copy(v, v) is a no-op). */
+export declare function copy(out: Vec3, a: Vec3Like): Vec3;
+/** Write the components and return out. */
+export declare function set(out: Vec3, x: number, y: number, z: number): Vec3;
+/**
+ * Approximate equality: every component differs by ≤ epsilon. NaN inputs always return false (IEEE 754).
+ */
+export declare function equals(a: Vec3Like, b: Vec3Like, epsilon?: number): boolean;
+/** out = a + b. aliasing-safe. */
+export declare function add(out: Vec3, a: Vec3Like, b: Vec3Like): Vec3;
+/** out = a - b. aliasing-safe. */
+export declare function sub(out: Vec3, a: Vec3Like, b: Vec3Like): Vec3;
+/** out = a * s. */
+export declare function scale(out: Vec3, a: Vec3Like, s: number): Vec3;
+/** out = -a. */
+export declare function negate(out: Vec3, a: Vec3Like): Vec3;
+/** Dot product a · b. */
+export declare function dot(a: Vec3Like, b: Vec3Like): number;
+/** out = a × b (cross product). aliasing-safe (reads all 6 components into locals first). */
+export declare function cross(out: Vec3, a: Vec3Like, b: Vec3Like): Vec3;
+/** Squared length |a|² (avoids sqrt overhead). */
+export declare function lengthSq(a: Vec3Like): number;
+/** Euclidean length |a|. */
+export declare function length(a: Vec3Like): number;
+/** Distance between two points |a - b|. */
+export declare function distance(a: Vec3Like, b: Vec3Like): number;
+/** Squared distance between two points |a - b|² (avoids sqrt overhead). */
+export declare function distanceSq(a: Vec3Like, b: Vec3Like): number;
+/**
+ * out = a / |a| (unit-length).
+ *
+ * @degrade Zero vector (|a|² < EPS_NORMALIZE) silently falls back to the zero vector;
+ * no NaN, no throw (gl-matrix style, AC-06 / D-P12).
+ * @degrade NaN inputs → NaN outputs: when a component is NaN, lenSq=NaN; the `lenSq < EPS`
+ * branch is false → goes through 1/sqrt(NaN)=NaN → output is all NaN (IEEE-754 NaN propagation;
+ * still does not throw).
+ *
+ * @example
+ * ```ts
+ * vec3.normalize(out, [3, 0, 4]);     // → (0.6, 0, 0.8)
+ * vec3.normalize(out, [0, 0, 0]);     // → (0, 0, 0) zero vector falls back (AC-06 no throw)
+ * vec3.normalize(out, [NaN, 1, 0]);   // → (NaN, NaN, NaN) IEEE-754 propagation
+ * ```
+ */
+export declare function normalize(out: Vec3, a: Vec3Like): Vec3;
+/** out = lerp(a, b, t). t is not clamped (extrapolation semantics). aliasing-safe. */
+export declare function lerp(out: Vec3, a: Vec3Like, b: Vec3Like, t: number): Vec3;
+/**
+ * out = frame-rate-INDEPENDENT exponential smoothing of `current` toward `target`:
+ * `lerp(current, target, 1 − exp(−decayRate · dt))`. Semantics match Bevy
+ * `StableInterpolate::smooth_nudge` / three.js `MathUtils.damp` — NOT Unity `Vector3.SmoothDamp`
+ * (which is a 2nd-order critically-damped spring needing a velocity ref; this is 1st-order decay).
+ *
+ * `decayRate` is the exponential decay constant (1/s), meant to stay fixed while `dt` is per-frame;
+ * a good anchor is `decayRate = ln(2)/halfLife`. `dt=0` → out=current (no move); large `decayRate·dt`
+ * → out≈target; `decayRate=0` → out=current. Frame-rate independent by construction: one step of `dt`
+ * equals two composed steps of `dt/2` — unlike the naive `lerp(current, target, rate·dt)`, which
+ * behaves differently per frame rate and overshoots when `rate·dt > 1`. aliasing-safe.
+ */
+export declare function smoothDamp(out: Vec3, current: Vec3Like, target: Vec3Like, decayRate: number, dt: number): Vec3;
+/**
+ * out = Catmull-Rom spline point on the segment between `p1` and `p2`, with `p0` / `p3` the
+ * neighbor control points setting the endpoint tangents (tension 0.5 — the Bevy
+ * `CubicCardinalSpline::new_catmull_rom` / three.js `CatmullRomCurve3` default). Interpolates
+ * the control points: `t=0` → `p1`, `t=1` → `p2`. Unlike `lerp` (a straight segment), this is
+ * the smooth cubic through the points — use it for camera paths, animation ease paths, or
+ * procedural curve geometry. To sample a whole polyline, loop the segments with a sliding
+ * 4-point window `[pts[i-1], pts[i], pts[i+1], pts[i+2]]` (clamp/duplicate ends). `t` is not
+ * clamped (extrapolation follows the same cubic). aliasing-safe.
+ */
+export declare function catmullRom(out: Vec3, p0: Vec3Like, p1: Vec3Like, p2: Vec3Like, p3: Vec3Like, t: number): Vec3;
+/** Component-wise min. */
+export declare function min(out: Vec3, a: Vec3Like, b: Vec3Like): Vec3;
+/** Component-wise max. */
+export declare function max(out: Vec3, a: Vec3Like, b: Vec3Like): Vec3;
+//# sourceMappingURL=vec3.d.ts.map

package/dist/vec3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec3.d.ts","sourceRoot":"","sources":["../src/vec3.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE9C,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAE/B,8CAA8C;AAC9C,wBAAgB,MAAM,CAAC,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,IAAI,CAEhD;AAED,gCAAgC;AAChC,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAEvC;AAED,sDAAsD;AACtD,wBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAKjD;AAED,2CAA2C;AAC3C,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAKpE;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,SAAO,GAAG,OAAO,CAoBxE;AAED,kCAAkC;AAClC,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAW7D;AAED,kCAAkC;AAClC,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAW7D;AAED,mBAAmB;AACnB,wBAAgB,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAK7D;AAED,gBAAgB;AAChB,wBAAgB,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAKnD;AAED,yBAAyB;AACzB,wBAAgB,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAMpD;AAED,6FAA6F;AAC7F,wBAAgB,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAW/D;AAED,kDAAkD;AAClD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAK5C;AAED,4BAA4B;AAC5B,wBAAgB,MAAM,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAK1C;AAED,2CAA2C;AAC3C,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAKzD;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAK3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAgBtD;AAED,sFAAsF;AACtF,wBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAWzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,IAAI,EACT,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,GACT,IAAI,CAEN;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,IAAI,EACT,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,QAAQ,EACZ,EAAE,EAAE,QAAQ,EACZ,CAAC,EAAE,MAAM,GACR,IAAI,CAQN;AAED,0BAA0B;AAC1B,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAK7D;AAED,0BAA0B;AAC1B,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAK7D"}

package/dist/vec4.d.ts

@@ -0,0 +1,61 @@
+import type { Vec4, Vec4Like } from './types';
+/** Create a Vec4 (zero vector by default). */
+export declare function create(x?: number, y?: number, z?: number, w?: number): Vec4;
+/** Allocate a new Vec4 copy. */
+export declare function clone(a: Vec4Like): Vec4;
+/** out = a. aliasing-safe (copy(v, v) is a no-op). */
+export declare function copy(out: Vec4, a: Vec4Like): Vec4;
+/** Write the components and return out. */
+export declare function set(out: Vec4, x: number, y: number, z: number, w: number): Vec4;
+/**
+ * Approximate equality: every component differs by ≤ epsilon. NaN inputs always return false (IEEE 754).
+ */
+export declare function equals(a: Vec4Like, b: Vec4Like, epsilon?: number): boolean;
+/** out = a + b. aliasing-safe. */
+export declare function add(out: Vec4, a: Vec4Like, b: Vec4Like): Vec4;
+/** out = a - b. aliasing-safe. */
+export declare function sub(out: Vec4, a: Vec4Like, b: Vec4Like): Vec4;
+/** out = a * s. */
+export declare function scale(out: Vec4, a: Vec4Like, s: number): Vec4;
+/** out = -a. The `0 - x` form avoids -0. */
+export declare function negate(out: Vec4, a: Vec4Like): Vec4;
+/** Dot product a · b (4 components). */
+export declare function dot(a: Vec4Like, b: Vec4Like): number;
+/** Squared length |a|² (avoids sqrt overhead). */
+export declare function lengthSq(a: Vec4Like): number;
+/** Euclidean length |a|. */
+export declare function length(a: Vec4Like): number;
+/** Distance between two points |a - b|. */
+export declare function distance(a: Vec4Like, b: Vec4Like): number;
+/**
+ * out = a / |a| (unit-length).
+ *
+ * @degrade Zero vector (|a|² < EPS_NORMALIZE) silently falls back to the zero vector;
+ * no NaN, no throw (gl-matrix style, AC-06 / D-P12).
+ * @degrade NaN inputs → NaN outputs: when a component is NaN, lenSq=NaN; the `lenSq < EPS`
+ * branch is false → goes through 1/sqrt(NaN)=NaN → output is all NaN (IEEE-754 NaN propagation;
+ * still does not throw).
+ *
+ * @example
+ * ```ts
+ * vec4.normalize(out, [1, 2, 2, 0]);    // → (1/3, 2/3, 2/3, 0)
+ * vec4.normalize(out, [0, 0, 0, 0]);    // → (0, 0, 0, 0) zero vector falls back (AC-06 no throw)
+ * vec4.normalize(out, [NaN, 1, 0, 0]);  // → all NaN, IEEE-754 propagation
+ * ```
+ */
+export declare function normalize(out: Vec4, a: Vec4Like): Vec4;
+/** out = lerp(a, b, t). t is not clamped (extrapolation semantics). aliasing-safe. */
+export declare function lerp(out: Vec4, a: Vec4Like, b: Vec4Like, t: number): Vec4;
+/**
+ * out = frame-rate-INDEPENDENT exponential smoothing of `current` toward `target`:
+ * `lerp(current, target, 1 − exp(−decayRate · dt))`. Semantics match Bevy
+ * `StableInterpolate::smooth_nudge` / three.js `MathUtils.damp` (1st-order decay, NOT Unity
+ * `SmoothDamp`'s 2nd-order spring). `dt=0` → out=current; large `decayRate·dt` → out≈target.
+ * Frame-rate independent by construction (one `dt` step = two composed `dt/2` steps). aliasing-safe.
+ * See vec3.smoothDamp for the full contract. */
+export declare function smoothDamp(out: Vec4, current: Vec4Like, target: Vec4Like, decayRate: number, dt: number): Vec4;
+/** Component-wise min. */
+export declare function min(out: Vec4, a: Vec4Like, b: Vec4Like): Vec4;
+/** Component-wise max. */
+export declare function max(out: Vec4, a: Vec4Like, b: Vec4Like): Vec4;
+//# sourceMappingURL=vec4.d.ts.map

package/dist/vec4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vec4.d.ts","sourceRoot":"","sources":["../src/vec4.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE9C,8CAA8C;AAC9C,wBAAgB,MAAM,CAAC,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,IAAI,CAEvD;AAED,gCAAgC;AAChC,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAEvC;AAED,sDAAsD;AACtD,wBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAMjD;AAED,2CAA2C;AAC3C,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAM/E;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,SAAO,GAAG,OAAO,CA2BxE;AAED,kCAAkC;AAClC,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAc7D;AAED,kCAAkC;AAClC,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAc7D;AAED,mBAAmB;AACnB,wBAAgB,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAM7D;AAED,4CAA4C;AAC5C,wBAAgB,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAMnD;AAED,wCAAwC;AACxC,wBAAgB,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAOpD;AAED,kDAAkD;AAClD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAE5C;AAED,4BAA4B;AAC5B,wBAAgB,MAAM,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAE1C;AAED,2CAA2C;AAC3C,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAMzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAGtD;AAED,sFAAsF;AACtF,wBAAgB,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAczE;AAED;;;;;;gDAMgD;AAChD,wBAAgB,UAAU,CACxB,GAAG,EAAE,IAAI,EACT,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,GACT,IAAI,CAEN;AAED,0BAA0B;AAC1B,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAM7D;AAED,0BAA0B;AAC1B,wBAAgB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAM7D"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@forgeax/engine-math",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Pure-function SoA-friendly Vec/Mat/Quat math utilities for forgeax-engine.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library package, no runtime canvas; fps reported by hello-triangle / hello-cube apps"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "pure math micro-benchmarks rarely regress; removed from CI to save 15s runner-minutes"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; smoke gate covered by hello-triangle / hello-cube apps"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; spike artefacts archived in feat-20260511-naga-rhi-wgpu-merge M5 (PR #34 + git history)"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "bench": "vitest bench --run",
+    "bench:json": "FORGEAX_BENCH=fast vitest bench --run --outputJson bench-result.json",
+    "lint:brand-cast": "node scripts/lint-brand-cast.mjs",
+    "lint:brand-runtime": "node scripts/lint-brand-runtime.mjs"
+  }
+}

package/src/__tests__/_arbs.ts

@@ -0,0 +1,149 @@
+// _arbs.ts — fast-check arbitrary factories + ε-tolerance comparison helpers (M5 / T-031)
+//
+// Shared by the three property files vec3.property.test.ts / mat4.property.test.ts /
+// quat.property.test.ts. The leading underscore prevents vitest's default glob
+// `**/*.test.ts` from running this file as a test (source: wiki/fast-check-property-test §7.1).
+//
+// Design anchors:
+//   - safeFloat: noNaN + noDefaultInfinity, prevents NaN from making ε comparisons
+//     spuriously pass/fail (wiki §3.1 + §8 anti-pattern #1)
+//   - vec3Arb / vec4Arb: same shape as the Float32Array.of branded factories (packages/math/src/vec3.ts)
+//   - unitVec3Arb: spherical sampling, filter hit rate > 99% (len² > 1e-12 almost always)
+//   - unitQuatArb: 4D-sphere Marsaglia / generic normalization + filter, 4D unit Hopf
+//   - invertibleMat4Arb: composed from TRS rather than 16 random elements (wiki §3.3)
+//   - approxEq / vec3ApproxEq / mat4ApproxEq / quatApproxEq: ε-tolerance helpers,
+//     EPS chosen from wiki §4.4 recommendation table (annotated inline below)
+//
+// brand cast: this file lives under packages/math/src/__tests__/, which is inside
+// lint-brand-cast.mjs's allow-list (the packages/math/src/ prefix is OK).
+//
+// Related: requirements §AC-11 property ≥ 12 / ≥ 5 categories / ≤ 4 per category;
+//          plan-strategy D-P5 numRuns default 100;
+//          wiki/fast-check-property-test §3 / §4 / §5 / §7.
+
+import { fc } from '@fast-check/vitest';
+import * as mat4 from '../mat4';
+import type { Mat4, Quat, Vec3, Vec4 } from '../types';
+
+// ---------- ε constants (wiki §4.4 recommendation table) ----------
+
+/** Float32 single add/sub; ULP ≈ 1.19e-7, leaves an 8× margin. */
+export const EPS_F32 = 1e-5;
+
+/** Float32 mat4 × mat4: chained accumulation of 16 muls + 12 adds. */
+export const EPS_MAT4_MUL = 1e-4;
+
+/** Float32 mat4 × mat4 × mat4: associativity test accumulates 3 multiplications on each side. */
+export const EPS_MAT4_MUL3 = 1e-3;
+
+/** Quat slerp endpoint / single-step numeric path. */
+export const EPS_QUAT = 1e-5;
+
+// ---------- single-value generators ----------
+
+/** General 32-bit safe scalar: noNaN + noDefaultInfinity, lies in [-1e3, 1e3]. */
+export const safeFloat = (min = -1e3, max = 1e3): fc.Arbitrary<number> =>
+  fc.float({
+    noNaN: true,
+    noDefaultInfinity: true,
+    // fast-check 4.x: min/max must be 32-bit representable, otherwise it throws
+    min: Math.fround(min),
+    max: Math.fround(max),
+  });
+
+/** Safe scalar for matrix elements: [-10, 10], prevents mat4×mat4 element values from inflating ε. */
+export const matFloat = (): fc.Arbitrary<number> =>
+  fc.float({
+    noNaN: true,
+    noDefaultInfinity: true,
+    min: Math.fround(-10),
+    max: Math.fround(10),
+  });
+
+/** Scale component: keeps away from 0 to avoid singularities ([1e-2, 10] ∪ [-10, -1e-2]). */
+export const nonZeroScale = (): fc.Arbitrary<number> =>
+  fc.oneof(
+    fc.float({
+      noNaN: true,
+      noDefaultInfinity: true,
+      min: Math.fround(1e-2),
+      max: Math.fround(10),
+    }),
+    fc.float({
+      noNaN: true,
+      noDefaultInfinity: true,
+      min: Math.fround(-10),
+      max: Math.fround(-1e-2),
+    }),
+  );
+
+// ---------- Float32Array vectors ----------
+
+/** Generic vec3: three independent safeFloat components. */
+export const vec3Arb = (): fc.Arbitrary<Vec3> =>
+  fc
+    .tuple(safeFloat(), safeFloat(), safeFloat())
+    .map(([x, y, z]) => Float32Array.of(x, y, z) as Vec3);
+
+/** Generic vec4. */
+export const vec4Arb = (): fc.Arbitrary<Vec4> =>
+  fc
+    .tuple(safeFloat(), safeFloat(), safeFloat(), safeFloat())
+    .map(([x, y, z, w]) => Float32Array.of(x, y, z, w) as Vec4);
+
+/** Non-zero vec3 (len² > 1e-6 to avoid normalize fall-back). */
+export const nonZeroVec3Arb = (): fc.Arbitrary<Vec3> =>
+  vec3Arb().map((v) => {
+    const x = v[0] as number;
+    const y = v[1] as number;
+    const z = v[2] as number;
+    const len2 = x * x + y * y + z * z;
+    return len2 < 1e-6 ? (Float32Array.of(1, 0, 0) as Vec3) : v;
+  });
+
+/** Scale vector: each component nonZeroScale, used by TRS compose. */
+export const scaleVec3Arb = (): fc.Arbitrary<Vec3> =>
+  fc
+    .tuple(nonZeroScale(), nonZeroScale(), nonZeroScale())
+    .map(([x, y, z]) => Float32Array.of(x, y, z) as Vec3);
+
+/** Unit vec3: normalized non-zero vec3. */
+export const unitVec3Arb = (): fc.Arbitrary<Vec3> =>
+  nonZeroVec3Arb().map((v) => {
+    const x = v[0] as number;
+    const y = v[1] as number;
+    const z = v[2] as number;
+    const inv = 1 / Math.hypot(x, y, z);
+    return Float32Array.of(x * inv, y * inv, z * inv) as Vec3;
+  });
+
+// ---------- unit quaternion ----------
+
+/** Unit quaternion: 4D-sphere sampling (filter hit rate ≈ 1 since random 4D points have len² > 1e-12). */
+export const unitQuatArb = (): fc.Arbitrary<Quat> =>
+  fc
+    .tuple(safeFloat(-1, 1), safeFloat(-1, 1), safeFloat(-1, 1), safeFloat(-1, 1))
+    .map(([x, y, z, w]) => {
+      const len2 = x * x + y * y + z * z + w * w;
+      if (len2 < 1e-12) return Float32Array.of(0, 0, 0, 1) as Quat;
+      const inv = 1 / Math.sqrt(len2);
+      return Float32Array.of(x * inv, y * inv, z * inv, w * inv) as Quat;
+    });
+
+// ---------- Mat4 ----------
+
+/** Generic mat4: 16 independent elements ∈ [-10, 10], associativity / identity friendly. */
+export const mat4Arb = (): fc.Arbitrary<Mat4> =>
+  fc
+    .array(matFloat(), { minLength: 16, maxLength: 16 })
+    .map((arr) => Float32Array.from(arr) as Mat4);
+
+/**
+ * Invertible mat4: composed from TRS (translation × rotation × scale) so det ≠ 0 is guaranteed.
+ * Random 16 elements are almost always singular, invert returns identity → invertibility test always fails.
+ */
+export const invertibleMat4Arb = (): fc.Arbitrary<Mat4> =>
+  fc.tuple(vec3Arb(), unitQuatArb(), scaleVec3Arb()).map(([t, r, s]) => {
+    const out = mat4.create();
+    return mat4.compose(out, t, r, s);
+  });

package/src/__tests__/_fixtures.ts

@@ -0,0 +1,118 @@
+// _fixtures.ts — reversed-Z double-precision reference matrices + projection-correctness probe table (T-019, AC-05)
+//
+// Reference SSOT: `.forgeax-harness/knowledge-base/wiki/reversed-z-projection.md` §7.2 / §7.3 / §7.4.
+// Numbers are computed in IEEE-754 float64 (cross-checked against Python's `math` stdlib);
+// this library's Float32Array implementation matches within 1e-5 tolerance.
+//
+// Related: requirements §AC-05 reversed-Z fixture error ≤ 1e-5;
+//          research §Finding 6.2 double-precision reference fixture (copied verbatim);
+//          wiki/reversed-z-projection.md §7.2 finite + §7.3 infinite + §7.4 projection probes.
+
+/** AC-05 fixed input: fovy=π/4, aspect=16/9, near=0.1, far=100. */
+export const PERSPECTIVE_REVERSE_Z_FINITE_INPUT = {
+  fovy: Math.PI / 4,
+  aspect: 16 / 9,
+  near: 0.1,
+  far: 100,
+} as const;
+
+/**
+ * Finite reversed-Z expected matrix (column-major 16 elements, double-precision reference).
+ *
+ * Numeric derivation:
+ *   m[0]  = (1 / tan(π/8)) / (16/9)         = 1.357995128834866
+ *   m[5]  = 1 / tan(π/8)                    = 2.414213562373095
+ *   m[10] = near / (far - near) = 0.1 / 99.9 = 0.001001001001001001
+ *   m[11] = -1
+ *   m[14] = near * far / (far - near)        = 0.10010010010010009
+ *   m[15] = 0
+ */
+export const PERSPECTIVE_REVERSE_Z_FINITE_EXPECTED: ReadonlyArray<number> = Object.freeze([
+  1.357995128834866,
+  0,
+  0,
+  0, // col 0
+  0,
+  2.414213562373095,
+  0,
+  0, // col 1
+  0,
+  0,
+  0.001001001001001001,
+  -1, // col 2
+  0,
+  0,
+  0.10010010010010009,
+  0, // col 3
+]);
+
+/**
+ * Infinite reversed-Z expected matrix (fovy=π/4, aspect=16/9, near=0.1, far=Infinity).
+ *
+ * lim(f→∞) m[10] = 0; lim(f→∞) m[14] = near = 0.1.
+ */
+export const PERSPECTIVE_REVERSE_Z_INFINITE_EXPECTED: ReadonlyArray<number> = Object.freeze([
+  1.357995128834866,
+  0,
+  0,
+  0, // col 0
+  0,
+  2.414213562373095,
+  0,
+  0, // col 1
+  0,
+  0,
+  0,
+  -1, // col 2
+  0,
+  0,
+  0.1,
+  0, // col 3
+]);
+
+/**
+ * Projection-correctness check (reversed-Z finite, near=0.1, far=100):
+ * feed z_eye into mat4.perspectiveReverseZ and the table below should produce ndc_z.
+ *
+ * Derivation: p_clip = M @ [0, 0, z_eye, 1]^T; ndc_z = p_clip[2] / p_clip[3].
+ *
+ * From wiki §7.4 table (n=0.1, f=100):
+ *   z_eye=-0.1   (near) → ndc_z = 1.0
+ *   z_eye=-1.0          → ndc_z = 0.09909909909909909
+ *   z_eye=-10.0         → ndc_z = 0.009009009009009009
+ *   z_eye=-100.0 (far)  → ndc_z = 0.0
+ */
+export const REVERSE_Z_PROJECTION_PROBES_FINITE: ReadonlyArray<{ z_eye: number; ndc_z: number }> =
+  Object.freeze([
+    { z_eye: -0.1, ndc_z: 1.0 },
+    { z_eye: -1.0, ndc_z: 0.09909909909909909 },
+    { z_eye: -10.0, ndc_z: 0.009009009009009009 },
+    { z_eye: -100.0, ndc_z: 0.0 },
+  ]);
+
+/**
+ * Projection-correctness check (reversed-Z infinite, near=0.1, far=Infinity):
+ *
+ * From wiki §7.4 table: infinite-far yields ndc_z = -near / z_eye = n / |z_eye| for any z_eye < 0.
+ *   z_eye=-0.1   (near)              → ndc_z = 1.0
+ *   z_eye=-1.0                       → ndc_z = 0.1
+ *   z_eye=-10.0                      → ndc_z = 0.01
+ *   z_eye=-100.0                     → ndc_z = 0.001
+ *   z_eye=-10000.0 (far frustum out) → ndc_z = 1e-5
+ */
+export const REVERSE_Z_PROJECTION_PROBES_INFINITE: ReadonlyArray<{
+  z_eye: number;
+  ndc_z: number;
+}> = Object.freeze([
+  { z_eye: -0.1, ndc_z: 1.0 },
+  { z_eye: -1.0, ndc_z: 0.1 },
+  { z_eye: -10.0, ndc_z: 0.01 },
+  { z_eye: -100.0, ndc_z: 0.001 },
+  { z_eye: -10000.0, ndc_z: 1e-5 },
+]);
+
+/**
+ * AC-05 tolerance: vitest `toBeCloseTo(expected, decimals)` with 5 decimals → ≤ 0.5e-5;
+ * float32 arithmetic stays within this tolerance vs the float64 reference.
+ */
+export const REVERSE_Z_FIXTURE_TOLERANCE = 5;