Module: Core Math

/** 3-component vector (position, direction, color) */
export interface Vec3 {
    x: number;
    y: number;
    z: number;
}

/** 4-component vector (homogeneous coords, quaternion, tangent) */
export interface Vec4 {
    x: number;
    y: number;
    z: number;
    w: number;
}

/** RGB color */
export interface Color3 {
    r: number;
    g: number;
    b: number;
}

/** RGBA color */
export interface Color4 {
    r: number;
    g: number;
    b: number;
    a: number;
}

/** 4x4 column-major matrix (16 elements). Opaque-by-convention: the
 *  underlying storage is `Float32Array` (default) or `Float64Array`
 *  (after an HPM engine is created — see `36-high-precision-matrix.md`).
 *  Layout matches WebGPU/WGSL mat4x4<f32> memory order. */
export interface Mat4 {
    readonly __brand: "Mat4";
    readonly length: 16;
    readonly [index: number]: number;
}

/** @internal Writable backing for Mat4 used by kernels and the GPU packer.
 *  Raw typed-array union (no brand). Not re-exported from the public root API. */
export type Mat4Storage = Float32Array | Float64Array;

/** Quaternion rotation */
export interface Quat {
    x: number;
    y: number;
    z: number;
    w: number;
}

// --- Constructors ---
export function vec3(x: number, y: number, z: number): Vec3;

export const Vec3Up: Readonly<Vec3>; // { x: 0, y: 1, z: 0 }

// --- Arithmetic (all return new objects — no mutation) ---
export function addVec3(a: Vec3, b: Vec3): Vec3;
export function subtractVec3(a: Vec3, b: Vec3): Vec3;
export function scaleVec3(v: Vec3, s: number): Vec3;
export function dotVec3(a: Vec3, b: Vec3): number;
export function crossVec3(a: Vec3, b: Vec3): Vec3;
export function lengthVec3(v: Vec3): number;
export function normalizeVec3(v: Vec3): Vec3;
export function normalizeVec3TupleOrUp(x: number, y: number, z: number, epsilon?: number): Vec3Tuple;
export function negateVec3(v: Vec3): Vec3;
export function lerpVec3(a: Vec3, b: Vec3, t: number): Vec3;

/** Write Vec3 into a Float32Array at the given element offset (for uniform buffers). */
export function writeVec3(out: Float32Array, offset: number, v: Vec3): void;

/** Create a new identity Mat4. */
export function createIdentityMat4(): Mat4;

/** Multiply two Mat4: out = a * b (column-major). */
export function multiplyMat4(a: Mat4, b: Mat4): Mat4;

/** LookAt matrix (left-handed). */
export function createLookAtMat4LH(eye: Vec3, target: Vec3, up: Vec3): Mat4;

/** Camera-to-world matrix for an eye looking at `target` — the inverse of `createLookAtMat4LH`,
 *  written in place. Used by every camera factory for its local world matrix. */
export function writeLookAtWorldMat4LHIntoBuffer(out: Mat4Storage, eye: Vec3, target: Vec3, up: Vec3): void;

/** Perspective projection (left-handed, zero-to-one depth). */
export function createPerspectiveMat4LH(fov: number, aspect: number, near: number, far: number): Mat4;

/** Compute inverse of a Mat4. Returns null if singular. */
export function invertMat4(m: Mat4): Mat4 | null;

/** Create a scaling matrix. */
export function createScalingMat4(x: number, y: number, z: number): Mat4;

/** Create a translation matrix. */
export function createTranslationMat4(x: number, y: number, z: number): Mat4;

/** Create a rotation matrix from a quaternion. */
export function createMat4FromQuat(qx: number, qy: number, qz: number, qw: number): Mat4;

/** Write a rotation matrix from a quaternion into an existing matrix buffer. */
export function writeMat4FromQuatIntoBuffer<T extends Float32Array | Float64Array>(out: T, qx: number, qy: number, qz: number, qw: number): T;

/** Compose TRS (translation * rotation * scale) into a single Mat4. */
export function composeMat4(tx: number, ty: number, tz: number, qx: number, qy: number, qz: number, qw: number, sx: number, sy: number, sz: number): Mat4;

/** Decompose a column-major affine Mat4 into translation/rotation(quaternion)/scale.
 *  Shared by setParent(), the gizmo/Gaussian-splat rotation extraction, and the Havok
 *  compound-shape path. **Behaviour change:** earlier versions always returned a
 *  non-negative scale and silently dropped the reflection of a mirrored matrix;
 *  `scale.y` is now negative for one, so callers assuming non-negative components
 *  must take `Math.abs` themselves. Mirrored matrices are preserved by folding the
 *  reflection onto a negative Y scale, matching Babylon.js `Matrix.decompose` —
 *  lossless, but canonical rather than sign-faithful (a negative X scale comes back
 *  as negative Y + a different rotation). Assumes a shear-free TRS matrix; a
 *  degenerate axis (scale below 1e-8) yields a finite but meaningless rotation
 *  rather than an error. */
export function decomposeMat4(m: Mat4): { translation: Vec3; rotation: Quat; scale: Vec3 };

/** Unit quaternion from the rotation part of a column-major Mat4 (Babylon.js
 *  `Quaternion.FromRotationMatrix`). The upper-left 3×3 must be a pure rotation. */
export function createQuatFromRotationMat4(matrix: Mat4): Quat;

/** Unit quaternion orienting local +Z onto `forward` and +Y onto `up`, right-handed
 *  (`right = up × forward`); Babylon.js `Quaternion.FromLookDirectionRH`. Inputs are
 *  orthonormalized, so non-unit / slightly non-orthogonal vectors still give a pure rotation. */
export function createQuatFromLookDirectionRH(forward: Vec3, up: Vec3): Quat;

export function linearToSrgbByte(v: number): number;
export function srgbByteToLinear(b: number): number;
export function packedSrgbToLinearRgba(packed: number, alpha?: number): readonly [number, number, number, number];

Index:  [0]  [4]  [8]  [12]
        [1]  [5]  [9]  [13]
        [2]  [6]  [10] [14]
        [3]  [7]  [11] [15]

Column:  0    1    2    3

Logical matrix:
  | m[0]  m[4]  m[8]   m[12] |
  | m[1]  m[5]  m[9]   m[13] |
  | m[2]  m[6]  m[10]  m[14] |
  | m[3]  m[7]  m[11]  m[15] |

export interface Mat4 {
    readonly __brand: "Mat4";
    readonly length: 16;
    readonly [index: number]: number;
}

for col in 0..3:
  for row in 0..3:
    out[col*4+row] = a[row]*b[col*4] + a[4+row]*b[col*4+1] + a[8+row]*b[col*4+2] + a[12+row]*b[col*4+3]

zAxis = normalize(target - eye)     // forward (into screen in LH)
xAxis = normalize(cross(up, zAxis)) // right
yAxis = cross(zAxis, xAxis)         // true up

out = | xAxis.x  xAxis.y  xAxis.z  -dot(xAxis, eye) |
      | yAxis.x  yAxis.y  yAxis.z  -dot(yAxis, eye) |
      | zAxis.x  zAxis.y  zAxis.z  -dot(zAxis, eye) |
      | 0        0        0         1                |

out[0]=xAxis.x  out[4]=xAxis.y  out[8]=xAxis.z   out[12]=-dot(xAxis,eye)
out[1]=yAxis.x  out[5]=yAxis.y  out[9]=yAxis.z   out[13]=-dot(yAxis,eye)
out[2]=zAxis.x  out[6]=zAxis.y  out[10]=zAxis.z  out[14]=-dot(zAxis,eye)
out[3]=0        out[7]=0        out[11]=0         out[15]=1

out[0]=xAxis.x  out[4]=yAxis.x  out[8]=zAxis.x   out[12]=eye.x
out[1]=xAxis.y  out[5]=yAxis.y  out[9]=zAxis.y   out[13]=eye.y
out[2]=xAxis.z  out[6]=yAxis.z  out[10]=zAxis.z  out[14]=eye.z
out[3]=0        out[7]=0        out[11]=0        out[15]=1

tan = 1 / Math.tan(fov * 0.5)
range = far - near

out[0]  = tan / aspect
out[5]  = tan
out[10] = far / range
out[11] = 1                    // LH: w_clip = +z_eye
out[14] = -(far * near) / range
out[15] = 0

det = b00*b11 - b01*b10 + b02*b09 + b03*b08 - b04*b07 + b05*b06

out = diag(x, y, z, 1) → out[0]=x, out[5]=y, out[10]=z, out[15]=1

out = identity with out[12]=x, out[13]=y, out[14]=z

xx=qx*qx  yy=qy*qy  zz=qz*qz
xy=qx*qy  xz=qx*qz  yz=qy*qz
wx=qw*qx  wy=qw*qy  wz=qw*qz

out[0]  = 1 - 2*(yy+zz)    out[4]  = 2*(xy-wz)       out[8]  = 2*(xz+wy)
out[1]  = 2*(xy+wz)         out[5]  = 1 - 2*(xx+zz)   out[9]  = 2*(yz-wx)
out[2]  = 2*(xz-wy)         out[6]  = 2*(yz+wx)        out[10] = 1 - 2*(xx+yy)
out[15] = 1

result[0..2]  = rotCol0 * sx    // column 0 (X axis)
result[4..6]  = rotCol1 * sy    // column 1 (Y axis)
result[8..10] = rotCol2 * sz    // column 2 (Z axis)
result[12..14] = (tx, ty, tz)   // column 3 (translation)
result[15] = 1