@danielsimonjr/mathts-matrix 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import * as _danielsimonjr_mathts_parallel from '@danielsimonjr/mathts-parallel';
 import { ComputePool, ComputePoolConfig } from '@danielsimonjr/mathts-parallel';
 import * as typed_function from 'typed-function';
 
@@ -192,167 +191,165 @@ declare abstract class Matrix<T = number> {
 declare function isMatrix<T = number>(value: unknown): value is Matrix<T>;
 
 /**
- * Sparse Matrix Implementation (CSR Format)
- *
- * Compressed Sparse Row (CSR) format sparse matrix for efficient storage
- * and operations on matrices with many zero elements.
+ * Dense Matrix Implementation
  *
- * CSR stores:
- * - values: Non-zero values in row-major order
- * - colIndices: Column index for each non-zero value
- * - rowPointers: Index into values/colIndices where each row starts
+ * Row-major dense matrix backed by Float64Array for efficient storage
+ * and operations. Supports views (slices without copying) where possible.
  *
  * @packageDocumentation
  */
 
 /**
- * Sparse matrix using Compressed Sparse Row (CSR) format
+ * Dense matrix implementation using Float64Array
  *
- * Efficient for:
- * - Row slicing and iteration
- * - Sparse matrix-vector multiplication
- * - Matrices with many zeros (typically < 10% non-zero)
+ * Data is stored in row-major order for cache-friendly row access.
+ * All operations return new matrices (immutable API).
  */
-declare class SparseMatrix extends Matrix<number> {
-    readonly type: "SparseMatrix";
+declare class DenseMatrix extends Matrix<number> {
+    readonly type: "DenseMatrix";
     readonly rows: number;
     readonly cols: number;
     /**
-     * Non-zero values in row-major order
+     * Internal data storage (row-major Float64Array)
      */
-    private readonly _data;
+    private readonly data;
     /**
-     * Column indices for each non-zero value
+     * Whether this matrix is a view into another matrix's data
      */
-    private readonly _colIndices;
+    private readonly isView;
     /**
-     * Row pointers: rowPointers[i] = index of first non-zero in row i
-     * rowPointers[rows] = total number of non-zeros (nnz)
+     * Offset into data array (for views)
      */
-    private readonly _rowPointers;
+    private readonly offset;
     /**
-     * Create a sparse matrix from CSR components
+     * Stride between rows (for views)
+     */
+    private readonly rowStride;
+    /**
+     * Create a new DenseMatrix
      *
      * @param rows - Number of rows
      * @param cols - Number of columns
-     * @param values - Non-zero values
-     * @param colIndices - Column index for each value
-     * @param rowPointers - Row start indices
+     * @param data - Optional initial data (row-major order)
      */
-    constructor(rows: number, cols: number, values: Float64Array | number[], colIndices: Int32Array | number[], rowPointers: Int32Array | number[]);
+    constructor(rows: number, cols: number, data?: Float64Array | number[] | number[][], viewConfig?: {
+        isView: boolean;
+        offset: number;
+        rowStride: number;
+    });
     /**
-     * Create a sparse matrix from a dense matrix
-     *
-     * @param dense - Dense matrix to convert
-     * @param dropTolerance - Values below this threshold are treated as zero
+     * Create a matrix from a nested array
      */
-    static fromDense(dense: DenseMatrix, dropTolerance?: number): SparseMatrix;
+    static fromArray(arr: number[][]): DenseMatrix;
     /**
-     * Create a sparse matrix from coordinate (COO) format
-     *
-     * @param rows - Number of rows
-     * @param cols - Number of columns
-     * @param entries - Array of {row, col, value} entries
+     * Create a matrix from a flat array with specified dimensions
      */
-    static fromCOO(rows: number, cols: number, entries: Array<{
-        row: number;
-        col: number;
-        value: number;
-    }>): SparseMatrix;
+    static fromFlat(rows: number, cols: number, data: number[]): DenseMatrix;
     /**
-     * Create a zero sparse matrix
+     * Create a zero matrix
      */
-    static zeros(rows: number, cols: number): SparseMatrix;
+    static zeros(rows: number, cols: number): DenseMatrix;
     /**
-     * Create a sparse identity matrix
+     * Create a matrix filled with ones
      */
-    static identity(n: number): SparseMatrix;
+    static ones(rows: number, cols: number): DenseMatrix;
     /**
-     * Create a sparse diagonal matrix
+     * Create an identity matrix
      */
-    static diag(values: number[]): SparseMatrix;
+    static identity(n: number): DenseMatrix;
     /**
-     * Number of non-zero elements
+     * Create a diagonal matrix from values
      */
-    get nnz(): number;
+    static diag(values: number[]): DenseMatrix;
     /**
-     * Sparsity: fraction of zero elements
+     * Create a matrix filled with a constant value
      */
-    get sparsity(): number;
+    static fill(rows: number, cols: number, value: number): DenseMatrix;
     /**
-     * Density: fraction of non-zero elements
+     * Create a matrix with random values in [0, 1)
      */
-    get density(): number;
+    static random(rows: number, cols: number): DenseMatrix;
     /**
-     * Get element at (row, col) - O(log(nnz_in_row)) for sorted columns
+     * Get element at (row, col)
+     * O(1) access time
      */
     get(row: number, col: number): number;
     /**
-     * Set element at (row, col) - returns new matrix (immutable)
+     * Set element at (row, col) - returns new matrix
      */
-    set(row: number, col: number, value: number): SparseMatrix;
+    set(row: number, col: number, value: number): DenseMatrix;
     /**
-     * Get a row as a sparse 1×n matrix
+     * Get the raw Float64Array data (copy if view, reference otherwise)
      */
-    row(index: number): SparseMatrix;
+    private toFlatFloat64Array;
     /**
-     * Get a column as a sparse m×1 matrix
+     * Get a row as a 1×n matrix (view, no copy)
      */
-    column(index: number): SparseMatrix;
+    row(index: number): DenseMatrix;
+    /**
+     * Get a column as an m×1 matrix (copy, since data is row-major)
+     */
+    column(index: number): DenseMatrix;
     /**
      * Get a submatrix
      */
-    slice(spec: SliceSpec): SparseMatrix;
+    slice(spec: SliceSpec): DenseMatrix;
     /**
      * Get the diagonal elements
      */
-    diagonal(k?: number): SparseMatrix;
+    diagonal(k?: number): DenseMatrix;
     /**
-     * Sparse matrix addition
+     * Matrix addition
      */
-    add(other: Matrix<number>): SparseMatrix;
-    private addSparse;
+    add(other: Matrix<number>): DenseMatrix;
     /**
-     * Sparse matrix subtraction
+     * Matrix subtraction
      */
-    subtract(other: Matrix<number>): SparseMatrix;
+    subtract(other: Matrix<number>): DenseMatrix;
     /**
      * Element-wise multiplication (Hadamard product)
      */
-    multiplyElementwise(other: Matrix<number>): SparseMatrix;
+    multiplyElementwise(other: Matrix<number>): DenseMatrix;
     /**
-     * Sparse matrix multiplication
+     * Matrix multiplication
      */
-    multiply(other: Matrix<number>): SparseMatrix;
-    private multiplySparse;
+    multiply(other: Matrix<number>): DenseMatrix;
     /**
      * Scalar multiplication
      */
-    scale(scalar: number): SparseMatrix;
+    scale(scalar: number): DenseMatrix;
     /**
-     * Sparse matrix transpose
+     * Matrix transpose
      */
-    transpose(): SparseMatrix;
+    transpose(): DenseMatrix;
     /**
      * Negate all elements
      */
-    negate(): SparseMatrix;
+    negate(): DenseMatrix;
     /**
      * Sum of all elements
      */
     sum(): number;
     /**
-     * Frobenius norm
+     * Mean of all elements
+     */
+    mean(): number;
+    /**
+     * Minimum element
+     */
+    min(): number;
+    /**
+     * Maximum element
+     */
+    max(): number;
+    /**
+     * Frobenius norm (sqrt of sum of squared elements)
      */
     norm(): number;
     /**
      * Trace (sum of diagonal elements)
      */
     trace(): number;
-    /**
-     * Convert to dense matrix
-     */
-    toDense(): DenseMatrix;
     /**
      * Convert to nested array
      */
@@ -361,209 +358,213 @@ declare class SparseMatrix extends Matrix<number> {
      * Convert to flat array (row-major)
      */
     toFlatArray(): number[];
+    /**
+     * Get the underlying Float64Array (copy)
+     */
+    toFloat64Array(): Float64Array;
     /**
      * Clone the matrix
      */
-    clone(): SparseMatrix;
+    clone(): DenseMatrix;
     /**
-     * Get the CSR components
+     * Convert to sparse matrix (CSR format)
+     *
+     * This is a synchronous conversion that creates a SparseMatrix
+     * containing only the non-zero elements of this matrix.
+     *
+     * @param dropTolerance - Values below this threshold are treated as zero
+     * @returns SparseMatrix representation (typed as the `Matrix` base — the
+     *   `SparseMatrix` subtype is loaded lazily to avoid an import cycle)
      */
-    getCSR(): {
-        values: Float64Array;
-        colIndices: Int32Array;
-        rowPointers: Int32Array;
-    };
+    toSparse(dropTolerance?: number): Matrix;
     /**
-     * Iterate over non-zero entries
+     * Iterate over entries with indices
      */
     entries(): IterableIterator<MatrixEntry<number>>;
     /**
-     * Iterate over non-zero values
+     * Iterate over values (row-major)
      */
     values(): IterableIterator<number>;
     /**
-     * Iterate over all values (including zeros, row-major)
-     */
-    allValues(): IterableIterator<number>;
-    /**
-     * Support for...of iteration (iterates over non-zero values)
+     * Support for...of iteration (iterates over values)
      */
     [Symbol.iterator](): IterableIterator<number>;
     /**
-     * Apply a function to each non-zero element
+     * Apply a function to each element
      */
-    mapNonZeros(fn: (value: number, row: number, col: number) => number): SparseMatrix;
+    map(fn: (value: number, row: number, col: number) => number): DenseMatrix;
     /**
-     * Apply a function to each element (including zeros)
-     * Warning: This may create a dense result
+     * Apply a function to each element (no return, for side effects)
      */
-    map(fn: (value: number, row: number, col: number) => number): SparseMatrix;
+    forEach(fn: (value: number, row: number, col: number) => void): void;
 }
 /**
- * Type guard for SparseMatrix
+ * Type guard for DenseMatrix
  */
-declare function isSparseMatrix(value: unknown): value is SparseMatrix;
+declare function isDenseMatrix(value: unknown): value is DenseMatrix;
 
 /**
- * Dense Matrix Implementation
+ * Sparse Matrix Implementation (CSR Format)
  *
- * Row-major dense matrix backed by Float64Array for efficient storage
- * and operations. Supports views (slices without copying) where possible.
+ * Compressed Sparse Row (CSR) format sparse matrix for efficient storage
+ * and operations on matrices with many zero elements.
+ *
+ * CSR stores:
+ * - values: Non-zero values in row-major order
+ * - colIndices: Column index for each non-zero value
+ * - rowPointers: Index into values/colIndices where each row starts
  *
  * @packageDocumentation
  */
 
 /**
- * Dense matrix implementation using Float64Array
+ * Sparse matrix using Compressed Sparse Row (CSR) format
  *
- * Data is stored in row-major order for cache-friendly row access.
- * All operations return new matrices (immutable API).
+ * Efficient for:
+ * - Row slicing and iteration
+ * - Sparse matrix-vector multiplication
+ * - Matrices with many zeros (typically < 10% non-zero)
  */
-declare class DenseMatrix extends Matrix<number> {
-    readonly type: "DenseMatrix";
+declare class SparseMatrix extends Matrix<number> {
+    readonly type: "SparseMatrix";
     readonly rows: number;
     readonly cols: number;
     /**
-     * Internal data storage (row-major Float64Array)
-     */
-    private readonly data;
-    /**
-     * Whether this matrix is a view into another matrix's data
+     * Non-zero values in row-major order
      */
-    private readonly isView;
+    private readonly _data;
     /**
-     * Offset into data array (for views)
+     * Column indices for each non-zero value
      */
-    private readonly offset;
+    private readonly _colIndices;
     /**
-     * Stride between rows (for views)
+     * Row pointers: rowPointers[i] = index of first non-zero in row i
+     * rowPointers[rows] = total number of non-zeros (nnz)
      */
-    private readonly rowStride;
+    private readonly _rowPointers;
     /**
-     * Create a new DenseMatrix
+     * Create a sparse matrix from CSR components
      *
      * @param rows - Number of rows
      * @param cols - Number of columns
-     * @param data - Optional initial data (row-major order)
+     * @param values - Non-zero values
+     * @param colIndices - Column index for each value
+     * @param rowPointers - Row start indices
      */
-    constructor(rows: number, cols: number, data?: Float64Array | number[] | number[][], viewConfig?: {
-        isView: boolean;
-        offset: number;
-        rowStride: number;
-    });
+    constructor(rows: number, cols: number, values: Float64Array | number[], colIndices: Int32Array | number[], rowPointers: Int32Array | number[]);
     /**
-     * Create a matrix from a nested array
+     * Create a sparse matrix from a dense matrix
+     *
+     * @param dense - Dense matrix to convert
+     * @param dropTolerance - Values below this threshold are treated as zero
      */
-    static fromArray(arr: number[][]): DenseMatrix;
+    static fromDense(dense: DenseMatrix, dropTolerance?: number): SparseMatrix;
     /**
-     * Create a matrix from a flat array with specified dimensions
+     * Create a sparse matrix from coordinate (COO) format
+     *
+     * @param rows - Number of rows
+     * @param cols - Number of columns
+     * @param entries - Array of {row, col, value} entries
      */
-    static fromFlat(rows: number, cols: number, data: number[]): DenseMatrix;
+    static fromCOO(rows: number, cols: number, entries: Array<{
+        row: number;
+        col: number;
+        value: number;
+    }>): SparseMatrix;
     /**
-     * Create a zero matrix
+     * Create a zero sparse matrix
      */
-    static zeros(rows: number, cols: number): DenseMatrix;
+    static zeros(rows: number, cols: number): SparseMatrix;
     /**
-     * Create a matrix filled with ones
+     * Create a sparse identity matrix
      */
-    static ones(rows: number, cols: number): DenseMatrix;
+    static identity(n: number): SparseMatrix;
     /**
-     * Create an identity matrix
+     * Create a sparse diagonal matrix
      */
-    static identity(n: number): DenseMatrix;
+    static diag(values: number[]): SparseMatrix;
     /**
-     * Create a diagonal matrix from values
+     * Number of non-zero elements
      */
-    static diag(values: number[]): DenseMatrix;
+    get nnz(): number;
     /**
-     * Create a matrix filled with a constant value
+     * Sparsity: fraction of zero elements
      */
-    static fill(rows: number, cols: number, value: number): DenseMatrix;
+    get sparsity(): number;
     /**
-     * Create a matrix with random values in [0, 1)
+     * Density: fraction of non-zero elements
      */
-    static random(rows: number, cols: number): DenseMatrix;
+    get density(): number;
     /**
-     * Get element at (row, col)
-     * O(1) access time
+     * Get element at (row, col) - O(log(nnz_in_row)) for sorted columns
      */
     get(row: number, col: number): number;
     /**
-     * Set element at (row, col) - returns new matrix
-     */
-    set(row: number, col: number, value: number): DenseMatrix;
-    /**
-     * Get the raw Float64Array data (copy if view, reference otherwise)
+     * Set element at (row, col) - returns new matrix (immutable)
      */
-    private toFlatFloat64Array;
+    set(row: number, col: number, value: number): SparseMatrix;
     /**
-     * Get a row as a 1×n matrix (view, no copy)
+     * Get a row as a sparse 1×n matrix
      */
-    row(index: number): DenseMatrix;
+    row(index: number): SparseMatrix;
     /**
-     * Get a column as an m×1 matrix (copy, since data is row-major)
+     * Get a column as a sparse m×1 matrix
      */
-    column(index: number): DenseMatrix;
+    column(index: number): SparseMatrix;
     /**
      * Get a submatrix
      */
-    slice(spec: SliceSpec): DenseMatrix;
+    slice(spec: SliceSpec): SparseMatrix;
     /**
      * Get the diagonal elements
      */
-    diagonal(k?: number): DenseMatrix;
+    diagonal(k?: number): SparseMatrix;
     /**
-     * Matrix addition
+     * Sparse matrix addition
      */
-    add(other: Matrix<number>): DenseMatrix;
+    add(other: Matrix<number>): SparseMatrix;
+    private addSparse;
     /**
-     * Matrix subtraction
+     * Sparse matrix subtraction
      */
-    subtract(other: Matrix<number>): DenseMatrix;
+    subtract(other: Matrix<number>): SparseMatrix;
     /**
      * Element-wise multiplication (Hadamard product)
      */
-    multiplyElementwise(other: Matrix<number>): DenseMatrix;
+    multiplyElementwise(other: Matrix<number>): SparseMatrix;
     /**
-     * Matrix multiplication
+     * Sparse matrix multiplication
      */
-    multiply(other: Matrix<number>): DenseMatrix;
+    multiply(other: Matrix<number>): SparseMatrix;
+    private multiplySparse;
     /**
      * Scalar multiplication
      */
-    scale(scalar: number): DenseMatrix;
+    scale(scalar: number): SparseMatrix;
     /**
-     * Matrix transpose
+     * Sparse matrix transpose
      */
-    transpose(): DenseMatrix;
+    transpose(): SparseMatrix;
     /**
      * Negate all elements
      */
-    negate(): DenseMatrix;
+    negate(): SparseMatrix;
     /**
      * Sum of all elements
      */
     sum(): number;
     /**
-     * Mean of all elements
-     */
-    mean(): number;
-    /**
-     * Minimum element
-     */
-    min(): number;
-    /**
-     * Maximum element
-     */
-    max(): number;
-    /**
-     * Frobenius norm (sqrt of sum of squared elements)
+     * Frobenius norm
      */
     norm(): number;
     /**
      * Trace (sum of diagonal elements)
      */
     trace(): number;
+    /**
+     * Convert to dense matrix
+     */
+    toDense(): DenseMatrix;
     /**
      * Convert to nested array
      */
@@ -572,49 +573,48 @@ declare class DenseMatrix extends Matrix<number> {
      * Convert to flat array (row-major)
      */
     toFlatArray(): number[];
-    /**
-     * Get the underlying Float64Array (copy)
-     */
-    toFloat64Array(): Float64Array;
     /**
      * Clone the matrix
      */
-    clone(): DenseMatrix;
+    clone(): SparseMatrix;
     /**
-     * Convert to sparse matrix (CSR format)
-     *
-     * This is a synchronous conversion that creates a SparseMatrix
-     * containing only the non-zero elements of this matrix.
-     *
-     * @param dropTolerance - Values below this threshold are treated as zero
-     * @returns SparseMatrix representation
+     * Get the CSR components
      */
-    toSparse(dropTolerance?: number): SparseMatrix;
+    getCSR(): {
+        values: Float64Array;
+        colIndices: Int32Array;
+        rowPointers: Int32Array;
+    };
     /**
-     * Iterate over entries with indices
+     * Iterate over non-zero entries
      */
     entries(): IterableIterator<MatrixEntry<number>>;
     /**
-     * Iterate over values (row-major)
+     * Iterate over non-zero values
      */
     values(): IterableIterator<number>;
     /**
-     * Support for...of iteration (iterates over values)
+     * Iterate over all values (including zeros, row-major)
+     */
+    allValues(): IterableIterator<number>;
+    /**
+     * Support for...of iteration (iterates over non-zero values)
      */
     [Symbol.iterator](): IterableIterator<number>;
     /**
-     * Apply a function to each element
+     * Apply a function to each non-zero element
      */
-    map(fn: (value: number, row: number, col: number) => number): DenseMatrix;
+    mapNonZeros(fn: (value: number, row: number, col: number) => number): SparseMatrix;
     /**
-     * Apply a function to each element (no return, for side effects)
+     * Apply a function to each element (including zeros)
+     * Warning: This may create a dense result
      */
-    forEach(fn: (value: number, row: number, col: number) => void): void;
+    map(fn: (value: number, row: number, col: number) => number): SparseMatrix;
 }
 /**
- * Type guard for DenseMatrix
+ * Type guard for SparseMatrix
  */
-declare function isDenseMatrix(value: unknown): value is DenseMatrix;
+declare function isSparseMatrix(value: unknown): value is SparseMatrix;
 
 /**
  * Matrix Backend Interface
@@ -629,7 +629,7 @@ declare function isDenseMatrix(value: unknown): value is DenseMatrix;
 /**
  * Backend type identifier
  */
-type BackendType = 'js' | 'wasm' | 'gpu' | 'parallel';
+type BackendType = 'js' | 'wasm' | 'rust-wasm' | 'gpu' | 'parallel';
 /**
  * Backend selection hints
  */
@@ -854,6 +854,96 @@ declare class JSBackend implements MatrixBackend {
  */
 declare const jsBackend: JSBackend;
 
+/**
+ * Stub type declarations for workerpool.
+ * The actual workerpool package ships raw .ts sources without pre-built .d.ts files.
+ * This stub prevents TypeScript from diving into the raw source during type-checking.
+ */
+declare module 'workerpool' {
+  export interface ExecOptions<T = unknown> {
+    on?: (payload: unknown) => void;
+    transfer?: Transferable[];
+    metadata?: T;
+  }
+
+  export interface PoolStats {
+    totalWorkers: number;
+    busyWorkers: number;
+    idleWorkers: number;
+    pendingTasks: number;
+    activeTasks: number;
+  }
+
+  export interface PoolOptions {
+    minWorkers?: number | 'max';
+    maxWorkers?: number;
+    maxQueueSize?: number;
+    workerType?: 'auto' | 'web' | 'process' | 'thread';
+    queueStrategy?: 'fifo' | 'lifo';
+    script?: string;
+    workerTerminateTimeout?: number;
+    forkArgs?: string[];
+    forkOpts?: Record<string, unknown>;
+    workerOpts?: Record<string, unknown>;
+    workerThreadOpts?: Record<string, unknown>;
+    emitStdStreams?: boolean;
+    onCreateWorker?: (arg: Record<string, unknown>) => Record<string, unknown> | void;
+    onTerminateWorker?: (arg: Record<string, unknown>) => void;
+    debugPortStart?: number;
+  }
+
+  export interface WorkerpoolPromise<T, E = unknown> extends Promise<T> {
+    readonly resolved: boolean;
+    readonly rejected: boolean;
+    readonly pending: boolean;
+    cancel(): this;
+    timeout(delay: number): this;
+  }
+
+  export type WorkerProxy<T extends Record<string, (...args: unknown[]) => unknown>> = {
+    [K in keyof T]: (...args: Parameters<T[K]>) => WorkerpoolPromise<ReturnType<T[K]>>;
+  };
+
+  export class Pool {
+    constructor(script?: string | PoolOptions, options?: PoolOptions);
+    exec<T>(
+      method: string | ((...args: unknown[]) => T),
+      params?: unknown[],
+      options?: ExecOptions
+    ): WorkerpoolPromise<T>;
+    proxy<T extends Record<string, (...args: unknown[]) => unknown>>(): Promise<WorkerProxy<T>>;
+    stats(): PoolStats;
+    terminate(force?: boolean, timeout?: number): Promise<void>;
+  }
+
+  export interface TransferDescriptor<T = unknown> {
+    message: T;
+    transfer: Transferable[];
+  }
+
+  export class Transfer<T = unknown> {
+    message: T;
+    transfer: Transferable[];
+    constructor(message: T, transfer: Transferable[]);
+  }
+
+  export class CancellationError extends Error {}
+  export class TimeoutError extends Error {}
+  export class TerminateError extends Error {}
+
+  export function pool(script?: string | PoolOptions, options?: PoolOptions): Pool;
+
+  export function worker(
+    methods?: Record<string, (...args: unknown[]) => unknown>,
+    options?: {
+      onTerminate?: (code: number | undefined) => void | PromiseLike<void>;
+      abortListenerTimeout?: number;
+    }
+  ): void;
+
+  export function workerEmit(payload: unknown): void;
+}
+
 /**
  * Configuration for ParallelBackend
  */
@@ -960,7 +1050,7 @@ declare class ParallelBackend {
     /**
      * Get pool statistics
      */
-    getStats(): _danielsimonjr_mathts_parallel.PoolStats;
+    getStats(): undefined;
     private checkDimensionsMatch;
     private checkMultiplyDimensions;
 }
@@ -1032,10 +1122,50 @@ declare function clearFeatureCache(): void;
 declare function getCachedFeatures(): WasmFeatures | null;
 
 /**
- * WASM Matrix Backend
- *
- * Implements MatrixBackend using WebAssembly for accelerated operations.
- * Falls back to JSBackend when WASM is unavailable or for small matrices.
+ * WASM Matrix Backend (AssemblyScript)
+ *
+ * Implements MatrixBackend using the AssemblyScript-compiled WebAssembly
+ * module (`lib/wasm/mathts-as.wasm`, ~42 KB). Falls back to JSBackend when
+ * the WASM module is unavailable or for small matrices.
+ *
+ * ABI:
+ *   The AS module exports a managed runtime (`__new` / `__pin` / `__unpin` /
+ *   `__collect`) and its matrix/array functions accept managed `Float64Array`
+ *   *header* pointers — NOT raw flat-memory pointers. A typed-array header is
+ *   a 12-byte block at some offset that stores (buffer, buffer, byteLength).
+ *
+ *   To call e.g. `matrix_add(a, b, result)` from JS, we have to:
+ *     1. `__new(byteLength, 1)` — allocate the data buffer (id=1 = ArrayBuffer)
+ *     2. `__pin(buffer)`         — pin so it survives GC while building header
+ *     3. `__new(12, 5)`          — allocate the Float64Array header (id=5)
+ *     4. Write [buffer, buffer, byteLength] into the header
+ *     5. Copy caller data into the buffer
+ *     6. `__unpin(buffer)`       — the header now owns the buffer reference
+ *
+ *   The Rust artifact has no managed runtime and uses a completely different
+ *   ABI (camelCase exports, flat-memory raw pointers); for that backend, use
+ *   `RustWASMBackend` (from `./RustWASMBackend.ts`).
+ *
+ * Naming map (Rust ↔ AssemblyScript) — for cross-backend reference:
+ *
+ *   Op                  Rust (camelCase, flat ptrs)        AS (snake_case, header refs)
+ *   ------------------  ---------------------------------  -------------------------------
+ *   add                 add(aPtr,bPtr,n,resPtr)            matrix_add(a,b,result)
+ *   subtract            subtract(aPtr,bPtr,n,resPtr)       matrix_sub(a,b,result)
+ *   multiplyElementwise simdMulF64(aPtr,bPtr,resPtr,n)     matrix_mul_elementwise(a,b,result)
+ *   divideElementwise   (none)                              matrix_div_elementwise(a,b,result)
+ *   scale               simdScaleF64(aPtr,s,resPtr,n)      matrix_scale(a,scalar,result)
+ *   abs                 simdAbsF64(aPtr,resPtr,n)          array_abs(a,result)
+ *   negate              simdScaleF64(aPtr,-1,resPtr,n)     matrix_neg(a,result)
+ *   multiply            multiplyDense(a,r,c,b,r,c,res)     matrix_multiply(a,aRows,aCols,b,bCols,result)
+ *   transpose           transpose(a,r,c,res)               matrix_transpose(a,rows,cols,result)
+ *   sum                 simdSumF64(aPtr,n)                 array_sum(a)
+ *   norm                simdNormF64(aPtr,n)                array_norm(a)
+ *   dot                 dotProduct(aPtr,bPtr,n)            array_dot(a,b)
+ *
+ *   AssemblyScript has no LU / QR / Cholesky / inverse / determinant exports,
+ *   so those operations fall back to the JS implementation. The Rust backend
+ *   has them — route those calls through `RustWASMBackend` if you need WASM.
  *
  * @packageDocumentation
  */
@@ -1046,16 +1176,18 @@ declare function getCachedFeatures(): WasmFeatures | null;
 interface WASMBackendConfig {
     /** Minimum elements to use WASM (default: 100) */
     minElements?: number;
-    /** Path to WASM file */
+    /** Path to WASM file (defaults to the AS artifact, `lib/wasm/mathts-as.wasm`) */
     wasmPath?: string;
-    /** Enable SIMD optimizations when available */
+    /** Enable SIMD code paths if the AS module exposes them (currently a no-op
+     * — AS export surface does not include `simd*` ops; kept for API stability). */
     useSIMD?: boolean;
 }
 /**
- * WASM Backend for matrix operations
+ * WASM Backend for matrix operations (AssemblyScript path).
  *
- * Uses WebAssembly for accelerated matrix operations with SIMD support.
- * Automatically falls back to JavaScript for small matrices or when WASM unavailable.
+ * For the Rust path use `RustWASMBackend`. Both implement `MatrixBackend`
+ * and report different `type` discriminants ('wasm' vs 'rust-wasm') so that
+ * `BackendManager` can route operations to the correct one.
  */
 declare class WASMBackend implements MatrixBackend {
     readonly type: BackendType;
@@ -1063,23 +1195,27 @@ declare class WASMBackend implements MatrixBackend {
     private wasmModule;
     private features;
     private initPromise;
+    /** Pooled allocations — see `AsAllocCache` for rationale. */
+    private allocCache;
     constructor(config?: WASMBackendConfig);
-    /**
-     * Check if WASM is available in the current environment
-     */
     isAvailable(): boolean;
-    /**
-     * Initialize the WASM backend
-     */
     initialize(): Promise<void>;
     private doInitialize;
     /**
-     * Check if operation should use WASM
+     * Resolve the path to the AssemblyScript artifact (`lib/wasm/mathts-as.wasm`).
+     *
+     * On Windows, `URL.pathname` returns "/C:/foo/bar.wasm" which fs.readFile
+     * interprets as drive-relative ("C:\C:\foo\..."). `fileURLToPath` does the
+     * platform-correct conversion.
      */
-    private shouldUseWasm;
+    private resolveAsWasmPath;
     /**
-     * Get detected WASM features
+     * Compile + instantiate the AssemblyScript WASM artifact. Each
+     * WASMBackend instance owns its own instance — this is intentional so
+     * tests and the Rust backend can coexist in the same process.
      */
+    private loadAsModule;
+    private shouldUseWasm;
     getFeatures(): WasmFeatures | null;
     add(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
     subtract(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
@@ -1094,40 +1230,24 @@ declare class WASMBackend implements MatrixBackend {
     sumAxis(a: DenseMatrix, axis: 0 | 1): DenseMatrix;
     norm(a: DenseMatrix): number;
     dot(a: DenseMatrix, b: DenseMatrix): number;
-    /**
-     * LU Decomposition using WASM
-     */
     luDecomposition(a: DenseMatrix): Promise<{
         lu: DenseMatrix;
         perm: Int32Array;
         singular: boolean;
     }>;
     private luDecompositionJS;
-    /**
-     * QR Decomposition using WASM
-     */
     qrDecomposition(a: DenseMatrix): Promise<{
         q: DenseMatrix;
         r: DenseMatrix;
     }>;
     private qrDecompositionJS;
-    /**
-     * Matrix inversion using LU decomposition
-     */
     inverse(a: DenseMatrix): Promise<{
         inverse: DenseMatrix;
         singular: boolean;
     }>;
     private inverseJS;
-    /**
-     * Compute matrix determinant using LU decomposition
-     */
     determinantWasm(a: DenseMatrix): Promise<number>;
     private determinantJS;
-    /**
-     * Cholesky Decomposition using WASM
-     * For symmetric positive-definite matrices: A = L * L^T
-     */
     choleskyDecomposition(a: DenseMatrix): Promise<{
         l: DenseMatrix;
         positiveDefinite: boolean;
@@ -1143,11 +1263,11 @@ declare class WASMBackend implements MatrixBackend {
     getConfig(): Required<WASMBackendConfig>;
 }
 /**
- * Global WASM backend instance
+ * Global WASM backend instance (AssemblyScript path)
  */
 declare const wasmBackend: WASMBackend;
 /**
- * Create a WASM backend with custom configuration
+ * Create a WASM backend (AssemblyScript path) with custom configuration
  */
 declare function createWASMBackend(config?: WASMBackendConfig): WASMBackend;
 
@@ -1893,170 +2013,489 @@ declare class GPUBackend {
      */
     add(a: Float32Array, b: Float32Array, rows: number, cols: number): Promise<Float32Array>;
     /**
-     * Multiply two matrices
+     * Multiply two matrices
+     */
+    matmul(a: Float32Array, b: Float32Array, M: number, K: number, N: number): Promise<Float32Array>;
+    /**
+     * Transpose a matrix
+     */
+    transpose(a: Float32Array, rows: number, cols: number): Promise<Float32Array>;
+    /**
+     * Scale a matrix by a scalar
+     */
+    scale(a: Float32Array, scalar: number): Promise<Float32Array>;
+    /**
+     * Get backend statistics
+     */
+    getStats(): {
+        status: GPUBackendStatus;
+        capabilities: GPUCapabilities | null;
+        bufferPool: {
+            totalBuffers: number;
+            inUseBuffers: number;
+            cachedBuffers: number;
+        } | null;
+        shaders: {
+            cachedShaders: number;
+            cachedPipelines: number;
+        } | null;
+    };
+    /**
+     * Destroy the backend
+     */
+    destroy(): void;
+}
+/**
+ * Get the global GPU backend
+ */
+declare function getGlobalGPUBackend(): GPUBackend;
+/**
+ * Initialize the global GPU backend
+ */
+declare function initializeGlobalGPUBackend(options?: GPUBackendOptions): Promise<boolean>;
+/**
+ * Destroy the global GPU backend
+ */
+declare function destroyGlobalGPUBackend(): void;
+
+/**
+ * GPU Matrix Backend Adapter
+ *
+ * Adapts GPUBackend to implement the MatrixBackend interface,
+ * enabling seamless integration with the backend selection system.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Configuration for GPU Matrix Backend
+ */
+interface GPUMatrixBackendConfig {
+    /** Minimum elements to use GPU (default: 65536 = 256x256) */
+    minElements?: number;
+    /** Use global GPU backend instance */
+    useGlobalBackend?: boolean;
+    /** GPU backend options */
+    gpuOptions?: GPUBackendOptions;
+    /** Fall back to JS on GPU errors */
+    fallbackOnError?: boolean;
+}
+/**
+ * GPU Matrix Backend
+ *
+ * Implements MatrixBackend interface using WebGPU compute shaders.
+ * Provides significant acceleration for large matrices.
+ *
+ * @example
+ * ```typescript
+ * const gpu = new GPUMatrixBackend();
+ * await gpu.initialize();
+ *
+ * const result = gpu.multiply(matrixA, matrixB);
+ * ```
+ */
+declare class GPUMatrixBackend implements MatrixBackend {
+    readonly type: BackendType;
+    private config;
+    private backend;
+    private capabilities;
+    private initPromise;
+    private _available;
+    constructor(config?: GPUMatrixBackendConfig);
+    /**
+     * Check if GPU is available in the current environment
+     */
+    isAvailable(): boolean;
+    /**
+     * Initialize the GPU backend
+     */
+    initialize(): Promise<void>;
+    private doInitialize;
+    /**
+     * Check if operation should use GPU
+     */
+    private shouldUseGPU;
+    /**
+     * Execute GPU operation with fallback
+     */
+    private executeWithFallback;
+    /**
+     * Get GPU capabilities
+     */
+    getCapabilities(): GPUCapabilities | null;
+    /**
+     * Get backend statistics
+     */
+    getStats(): ReturnType<GPUBackend['getStats']> | null;
+    add(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Async add operation using GPU
+     */
+    addAsync(a: DenseMatrix, b: DenseMatrix): Promise<DenseMatrix>;
+    subtract(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    multiplyElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    divideElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    scale(a: DenseMatrix, scalar: number): DenseMatrix;
+    /**
+     * Async scale operation using GPU
+     */
+    scaleAsync(a: DenseMatrix, scalar: number): Promise<DenseMatrix>;
+    abs(a: DenseMatrix): DenseMatrix;
+    negate(a: DenseMatrix): DenseMatrix;
+    multiply(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    /**
+     * Async matrix multiplication using GPU
+     */
+    multiplyAsync(a: DenseMatrix, b: DenseMatrix): Promise<DenseMatrix>;
+    transpose(a: DenseMatrix): DenseMatrix;
+    /**
+     * Async transpose using GPU
+     */
+    transposeAsync(a: DenseMatrix): Promise<DenseMatrix>;
+    sum(a: DenseMatrix): number;
+    sumAxis(a: DenseMatrix, axis: 0 | 1): DenseMatrix;
+    norm(a: DenseMatrix): number;
+    dot(a: DenseMatrix, b: DenseMatrix): number;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<GPUMatrixBackendConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<GPUMatrixBackendConfig>;
+    /**
+     * Destroy the backend
+     */
+    destroy(): void;
+}
+/**
+ * Global GPU matrix backend instance
+ */
+declare const gpuMatrixBackend: GPUMatrixBackend;
+/**
+ * Create a GPU matrix backend with custom configuration
+ */
+declare function createGPUMatrixBackend(config?: GPUMatrixBackendConfig): GPUMatrixBackend;
+
+/**
+ * Rust WASM Matrix Backend
+ *
+ * Implements MatrixBackend using the Rust-compiled WebAssembly module (648 KB).
+ * Designed for heavy operations: large matrix multiply (faer), FFT (rustfft),
+ * eigendecomposition, sparse algebra, and SIMD-accelerated array operations.
+ *
+ * This backend sits alongside the existing WASMBackend (AssemblyScript) and
+ * is selected by BackendManager for large matrices and heavy operations.
+ *
+ * Memory model:
+ *   Uses a bump allocator on the JS side to write data into WASM linear
+ *   memory. The allocator is reset between operations (batch-free pattern).
+ *   This avoids the overhead of per-allocation malloc/free calls.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Rust WASM Backend configuration
+ */
+interface RustWASMBackendConfig {
+    /** Minimum elements to use Rust WASM (default: 1000) */
+    minElements?: number;
+    /** Path to the Rust WASM binary */
+    wasmPath?: string;
+}
+/**
+ * Rust WASM Backend for matrix operations.
+ *
+ * Uses the Rust WASM module for heavy computation, with automatic
+ * fallback to JSBackend when the module is unavailable or for small matrices.
+ *
+ * The backend registers as type 'wasm' so it can serve as a drop-in
+ * replacement or complement to the AssemblyScript WASMBackend. When both
+ * are needed, use BackendManager's operation-specific routing.
+ */
+declare class RustWASMBackend implements MatrixBackend {
+    /**
+     * Backend type identifier.
+     * Uses 'rust-wasm' to distinguish from the AssemblyScript WASMBackend.
+     */
+    readonly type: BackendType;
+    private config;
+    private exports;
+    private initPromise;
+    constructor(config?: RustWASMBackendConfig);
+    /**
+     * Check if WebAssembly is available in the current environment.
+     */
+    isAvailable(): boolean;
+    /**
+     * Initialize the Rust WASM backend.
+     * Loads the WASM binary and caches the exports.
+     */
+    initialize(): Promise<void>;
+    private doInitialize;
+    /**
+     * Whether to use Rust WASM for this operation size.
+     */
+    private shouldUseRustWasm;
+    /**
+     * Whether the Rust WASM module is loaded and ready.
+     */
+    get isRustLoaded(): boolean;
+    add(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    subtract(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    multiplyElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    divideElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    scale(a: DenseMatrix, scalar: number): DenseMatrix;
+    abs(a: DenseMatrix): DenseMatrix;
+    negate(a: DenseMatrix): DenseMatrix;
+    multiply(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    transpose(a: DenseMatrix): DenseMatrix;
+    sum(a: DenseMatrix): number;
+    sumAxis(a: DenseMatrix, axis: 0 | 1): DenseMatrix;
+    norm(a: DenseMatrix): number;
+    dot(a: DenseMatrix, b: DenseMatrix): number;
+    /**
+     * LU Decomposition using Rust WASM.
+     */
+    luDecomposition(a: DenseMatrix): Promise<{
+        lu: DenseMatrix;
+        perm: Int32Array;
+        singular: boolean;
+    }>;
+    /**
+     * Eigenvalue decomposition for symmetric matrices using Rust WASM.
      */
-    matmul(a: Float32Array, b: Float32Array, M: number, K: number, N: number): Promise<Float32Array>;
+    eigsSymmetric(a: DenseMatrix, precision?: number): Promise<{
+        eigenvalues: Float64Array;
+        eigenvectors: DenseMatrix;
+        iterations: number;
+    }>;
     /**
-     * Transpose a matrix
+     * Matrix inversion using Rust WASM.
      */
-    transpose(a: Float32Array, rows: number, cols: number): Promise<Float32Array>;
+    inverse(a: DenseMatrix): Promise<{
+        inverse: DenseMatrix;
+        singular: boolean;
+    }>;
     /**
-     * Scale a matrix by a scalar
+     * FFT using Rust WASM (rustfft).
+     * Data is interleaved complex: [re0, im0, re1, im1, ...].
      */
-    scale(a: Float32Array, scalar: number): Promise<Float32Array>;
+    fft(data: Float64Array, n: number, inverse?: boolean): Float64Array;
     /**
-     * Get backend statistics
+     * Update configuration.
      */
-    getStats(): {
-        status: GPUBackendStatus;
-        capabilities: GPUCapabilities | null;
-        bufferPool: {
-            totalBuffers: number;
-            inUseBuffers: number;
-            cachedBuffers: number;
-        } | null;
-        shaders: {
-            cachedShaders: number;
-            cachedPipelines: number;
-        } | null;
-    };
+    updateConfig(config: Partial<RustWASMBackendConfig>): void;
     /**
-     * Destroy the backend
+     * Get current configuration.
      */
-    destroy(): void;
+    getConfig(): Required<RustWASMBackendConfig>;
 }
 /**
- * Get the global GPU backend
- */
-declare function getGlobalGPUBackend(): GPUBackend;
-/**
- * Initialize the global GPU backend
+ * Global Rust WASM backend instance
  */
-declare function initializeGlobalGPUBackend(options?: GPUBackendOptions): Promise<boolean>;
+declare const rustWasmBackend: RustWASMBackend;
 /**
- * Destroy the global GPU backend
+ * Create a Rust WASM backend with custom configuration
  */
-declare function destroyGlobalGPUBackend(): void;
+declare function createRustWASMBackend(config?: RustWASMBackendConfig): RustWASMBackend;
 
 /**
- * GPU Matrix Backend Adapter
+ * Rust WASM Loader
  *
- * Adapts GPUBackend to implement the MatrixBackend interface,
- * enabling seamless integration with the backend selection system.
+ * Loads and manages the Rust-compiled WebAssembly module (648 KB).
+ * The Rust WASM provides heavy computation: matrix multiply (faer),
+ * FFT (rustfft), eigendecomposition, sparse algebra, statistics (statrs),
+ * and SIMD-accelerated array operations.
+ *
+ * Memory model:
+ *   The Rust WASM uses `#[no_mangle] extern "C"` raw exports with
+ *   a linear memory model. Unlike the AssemblyScript WASM, there is
+ *   no managed GC heap (`__new`/`__pin`/`__unpin`/`__collect`).
+ *   Instead, JavaScript writes data directly into WASM linear memory
+ *   at computed offsets and passes those offsets as pointers.
  *
  * @packageDocumentation
  */
-
 /**
- * Configuration for GPU Matrix Backend
+ * Typed interface for Rust WASM exports.
+ *
+ * This is a subset of the full export surface, covering the operations
+ * most useful for the matrix backend. The full module has 150+ exports
+ * across algebra, arithmetic, signal, statistics, etc.
+ */
+interface RustWasmExports {
+    memory: WebAssembly.Memory;
+    multiplyDense: (aPtr: number, aRows: number, aCols: number, bPtr: number, bRows: number, bCols: number, resultPtr: number) => void;
+    multiplyDenseSIMD: (aPtr: number, aRows: number, aCols: number, bPtr: number, bRows: number, bCols: number, resultPtr: number) => void;
+    multiplyVector: (aPtr: number, aRows: number, aCols: number, xPtr: number, resultPtr: number) => void;
+    transpose: (dataPtr: number, rows: number, cols: number, resultPtr: number) => void;
+    /** Thin SVD: writes U (m*k), S (k), V (n*k); k = min(m,n). */
+    svd: (aPtr: number, m: number, n: number, uPtr: number, sPtr: number, vPtr: number, workPtr: number) => number;
+    /** Singular values only: writes S (k); k = min(m,n). */
+    singularValues: (aPtr: number, m: number, n: number, sPtr: number, workPtr: number) => number;
+    /** Scratch length (in f64s) required by `svd`. */
+    svdWorkSize: (m: number, n: number) => number;
+    /** Scratch length (in f64s) required by `singularValues`. */
+    singularValuesWorkSize: (m: number, n: number) => number;
+    simdAddF64: (aPtr: number, bPtr: number, resultPtr: number, length: number) => void;
+    simdSubF64: (aPtr: number, bPtr: number, resultPtr: number, length: number) => void;
+    simdMulF64: (aPtr: number, bPtr: number, resultPtr: number, length: number) => void;
+    simdScaleF64: (aPtr: number, scalar: number, resultPtr: number, length: number) => void;
+    simdAbsF64: (aPtr: number, resultPtr: number, length: number) => void;
+    simdDotF64: (aPtr: number, bPtr: number, length: number) => number;
+    simdSumF64: (aPtr: number, length: number) => number;
+    simdNormF64: (aPtr: number, length: number) => number;
+    simdMatMulF64: (aPtr: number, bPtr: number, cPtr: number, m: number, k: number, n: number) => void;
+    simdMinF64: (aPtr: number, length: number) => number;
+    simdMaxF64: (aPtr: number, length: number) => number;
+    simdMeanF64: (aPtr: number, length: number) => number;
+    simdVarianceF64: (aPtr: number, length: number, ddof: number) => number;
+    simdStdF64: (aPtr: number, length: number, ddof: number) => number;
+    luDecomposition: (aPtr: number, n: number, permPtr: number) => number;
+    qrDecomposition: (aPtr: number, m: number, n: number, qPtr: number) => void;
+    choleskyDecomposition: (aPtr: number, n: number, lPtr: number) => number;
+    eigsSymmetric: (matrixPtr: number, n: number, precision: number, eigenvaluesPtr: number, eigenvectorsPtr: number, workPtr: number) => number;
+    laInv: (aPtr: number, n: number, resultPtr: number, workPtr: number) => number;
+    laDet: (aPtr: number, n: number, workPtr: number) => number;
+    laSolve: (aPtr: number, bPtr: number, n: number, resultPtr: number, workPtr: number) => number;
+    fft: (dataPtr: number, n: number, inverse: number) => void;
+    fft2d: (dataPtr: number, rows: number, cols: number, inverse: number) => void;
+    convolve: (signalPtr: number, n: number, kernelPtr: number, m: number, resultPtr: number) => void;
+    rfft: (dataPtr: number, n: number, resultPtr: number) => void;
+    statsMean: (aPtr: number, n: number) => number;
+    statsMedian: (aPtr: number, n: number) => number;
+    statsVariance: (aPtr: number, n: number, ddof: number) => number;
+    statsStd: (aPtr: number, n: number, ddof: number) => number;
+    statsSum: (aPtr: number, n: number) => number;
+    statsMin: (aPtr: number, n: number) => number;
+    statsMax: (aPtr: number, n: number) => number;
+    rust_mat_mul_2x2: (aPtr: number, bPtr: number, outPtr: number) => void;
+    rust_fft_4: (inPtr: number, outPtr: number) => void;
+    rust_gamma: (x: number, outPtr: number) => void;
+    [key: string]: unknown;
+}
+/**
+ * Loading metrics for performance monitoring
  */
-interface GPUMatrixBackendConfig {
-    /** Minimum elements to use GPU (default: 65536 = 256x256) */
-    minElements?: number;
-    /** Use global GPU backend instance */
-    useGlobalBackend?: boolean;
-    /** GPU backend options */
-    gpuOptions?: GPUBackendOptions;
-    /** Fall back to JS on GPU errors */
-    fallbackOnError?: boolean;
+interface RustLoadingMetrics {
+    loadMs: number;
+    compileMs: number;
+    instantiateMs: number;
+    totalMs: number;
+    binarySize: number;
 }
 /**
- * GPU Matrix Backend
- *
- * Implements MatrixBackend interface using WebGPU compute shaders.
- * Provides significant acceleration for large matrices.
- *
- * @example
- * ```typescript
- * const gpu = new GPUMatrixBackend();
- * await gpu.initialize();
+ * Loader for the Rust-compiled WASM module.
  *
- * const result = gpu.multiply(matrixA, matrixB);
- * ```
+ * Singleton pattern with lazy loading. The WASM binary is loaded
+ * on first use and cached for subsequent calls.
  */
-declare class GPUMatrixBackend implements MatrixBackend {
-    readonly type: BackendType;
-    private config;
-    private backend;
-    private capabilities;
-    private initPromise;
-    private _available;
-    constructor(config?: GPUMatrixBackendConfig);
+declare class RustWasmLoader {
+    private static instance;
+    private wasmInstance;
+    private wasmMemory;
+    private allocator;
+    private _isLoaded;
+    private loading;
+    private lastMetrics;
+    private constructor();
+    static getInstance(): RustWasmLoader;
+    get isLoaded(): boolean;
     /**
-     * Check if GPU is available in the current environment
+     * Load the Rust WASM module.
+     * Returns true on success, false if the binary is not available.
+     * Safe to call multiple times (idempotent).
      */
-    isAvailable(): boolean;
+    load(wasmPath?: string): Promise<boolean>;
+    private doLoad;
     /**
-     * Initialize the GPU backend
+     * Resolve the WASM binary path.
+     * Checks several locations relative to the project root.
      */
-    initialize(): Promise<void>;
-    private doInitialize;
+    private findWasmPath;
+    private getImports;
     /**
-     * Check if operation should use GPU
+     * Get the typed exports from the WASM instance.
      */
-    private shouldUseGPU;
+    getExports(): RustWasmExports | null;
     /**
-     * Execute GPU operation with fallback
+     * Get WASM linear memory.
      */
-    private executeWithFallback;
+    getMemory(): WebAssembly.Memory | null;
     /**
-     * Get GPU capabilities
+     * Get loading metrics.
      */
-    getCapabilities(): GPUCapabilities | null;
+    getLoadingMetrics(): RustLoadingMetrics | null;
     /**
-     * Get backend statistics
+     * Write a Float64Array into WASM memory and return the pointer.
      */
-    getStats(): ReturnType<GPUBackend['getStats']> | null;
-    add(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    writeF64(data: Float64Array | number[]): number;
     /**
-     * Async add operation using GPU
+     * Allocate an empty Float64Array in WASM memory (for output buffers).
+     * Returns the pointer.
      */
-    addAsync(a: DenseMatrix, b: DenseMatrix): Promise<DenseMatrix>;
-    subtract(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
-    multiplyElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
-    divideElementwise(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
-    scale(a: DenseMatrix, scalar: number): DenseMatrix;
+    allocF64(length: number): number;
     /**
-     * Async scale operation using GPU
+     * Write an Int32Array into WASM memory and return the pointer.
      */
-    scaleAsync(a: DenseMatrix, scalar: number): Promise<DenseMatrix>;
-    abs(a: DenseMatrix): DenseMatrix;
-    negate(a: DenseMatrix): DenseMatrix;
-    multiply(a: DenseMatrix, b: DenseMatrix): DenseMatrix;
+    writeI32(data: Int32Array | number[]): number;
     /**
-     * Async matrix multiplication using GPU
+     * Allocate an empty Int32Array in WASM memory.
      */
-    multiplyAsync(a: DenseMatrix, b: DenseMatrix): Promise<DenseMatrix>;
-    transpose(a: DenseMatrix): DenseMatrix;
+    allocI32(length: number): number;
     /**
-     * Async transpose using GPU
+     * Read a Float64Array from WASM memory.
+     * Note: the returned array is a *copy* (safe after memory reset).
      */
-    transposeAsync(a: DenseMatrix): Promise<DenseMatrix>;
-    sum(a: DenseMatrix): number;
-    sumAxis(a: DenseMatrix, axis: 0 | 1): DenseMatrix;
-    norm(a: DenseMatrix): number;
-    dot(a: DenseMatrix, b: DenseMatrix): number;
+    readF64(ptr: number, length: number): Float64Array;
     /**
-     * Update configuration
+     * Read an Int32Array from WASM memory.
      */
-    updateConfig(config: Partial<GPUMatrixBackendConfig>): void;
+    readI32(ptr: number, length: number): Int32Array;
     /**
-     * Get current configuration
+     * Reset the bump allocator. Call between independent operations
+     * to reclaim temporary memory.
      */
-    getConfig(): Required<GPUMatrixBackendConfig>;
+    resetAllocator(): void;
     /**
-     * Destroy the backend
+     * Reset the loader (for testing).
      */
-    destroy(): void;
+    reset(): void;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
 }
 /**
- * Global GPU matrix backend instance
+ * Global Rust WASM loader instance
  */
-declare const gpuMatrixBackend: GPUMatrixBackend;
+declare const rustWasmLoader: RustWasmLoader;
 /**
- * Create a GPU matrix backend with custom configuration
+ * Initialize the Rust WASM module (call once at startup).
+ * Returns true if loaded successfully, false if not available.
  */
-declare function createGPUMatrixBackend(config?: GPUMatrixBackendConfig): GPUMatrixBackend;
+declare function initRustWasm(wasmPath?: string): Promise<boolean>;
+
+/**
+ * MathTS Matrix Configuration
+ *
+ * Centralized configuration for matrix operations, backend selection,
+ * and performance tuning.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Operation type hints for backend selection.
+ *
+ * Defined here rather than in `BackendManager.ts` so that `config.ts` (the
+ * lower-level module) owns it — `BackendManager` already imports `config`, so
+ * sourcing the type the other way round closed an import cycle.
+ */
+type OperationType = 'add' | 'subtract' | 'multiply' | 'multiplyElementwise' | 'transpose' | 'scale' | 'decomposition' | 'solve' | 'fft' | 'eig' | 'svd';
 
 /**
  * Backend Manager
@@ -2068,10 +2507,6 @@ declare function createGPUMatrixBackend(config?: GPUMatrixBackendConfig): GPUMat
  * @packageDocumentation
  */
 
-/**
- * Operation type hints for backend selection
- */
-type OperationType = 'add' | 'subtract' | 'multiply' | 'multiplyElementwise' | 'transpose' | 'scale' | 'decomposition' | 'solve';
 /**
  * Extended backend hints with operation-specific thresholds
  */
@@ -2080,11 +2515,16 @@ interface ExtendedBackendHints extends BackendHints {
     operationThresholds?: Partial<Record<OperationType, {
         wasm?: number;
         gpu?: number;
+        rustWasm?: number;
     }>>;
     /** Enable automatic SIMD detection for WASM */
     autoSIMD?: boolean;
     /** Fallback to JS on backend failure */
     fallbackOnError?: boolean;
+    /** Minimum elements to use Rust WASM backend (default: 1000) */
+    rustWasmThreshold?: number;
+    /** Operations that always prefer Rust WASM regardless of size */
+    rustWasmPreferredOps?: OperationType[];
 }
 /**
  * Default extended hints
@@ -2122,7 +2562,15 @@ declare class BackendManager {
      */
     getHints(): Required<ExtendedBackendHints>;
     /**
-     * Get the best backend for a given operation and matrix size
+     * Get the best backend for a given operation and matrix size.
+     *
+     * Selection priority:
+     *   1. Preferred backend (if explicitly set)
+     *   2. Heavy operations (fft, eig, svd, decomposition) -> Rust WASM (if loaded)
+     *   3. Elements > gpuThreshold -> GPU (if available)
+     *   4. Elements > rustWasmThreshold -> Rust WASM (if loaded)
+     *   5. Elements > wasmThreshold -> AS WASM (if loaded)
+     *   6. JS fallback
      */
     selectBackend(elementCount: number, operation?: OperationType): MatrixBackend;
     /**
@@ -2350,7 +2798,7 @@ declare function singularValues(matrix: number[][] | Float64Array, options?: Omi
 /**
  * Compute the pseudoinverse (Moore-Penrose inverse) using SVD
  */
-declare function pinv(matrix: number[][], options?: SVDOptions): number[][];
+declare function pinv$1(matrix: number[][], options?: SVDOptions): number[][];
 /**
  * Low-rank approximation using SVD
  * Keeps only the top r singular values
@@ -2425,32 +2873,380 @@ declare function spectralRadiusWasm(matrix: number[][], options?: {
 }): Promise<number>;
 
 /**
- * WASM-accelerated Singular Value Decomposition
+ * WASM-accelerated Singular Value Decomposition.
  *
- * Provides SVD computation with optional WASM acceleration.
- * The Rust WASM crate currently exposes eigenvalue operations but not
- * a direct SVD implementation. For symmetric matrices, SVD can be
- * derived from eigendecomposition (singular values = |eigenvalues|).
+ * Routes through the Rust WASM crate's direct one-sided Jacobi SVD
+ * (`svd` export) for any real `m x n` matrix, and falls back to the
+ * synchronous JavaScript Golub-Reinsch {@link svd} when the WASM module is
+ * unavailable.
  *
- * Strategy:
- *   - Symmetric matrices: WASM eig -> derive SVD
- *   - General matrices: JS Golub-Reinsch bidiagonalization (svd.ts)
+ * Unlike the synchronous {@link svd} (which returns the *full* `m x m` /
+ * `n x n` factors), `svdWasm` always returns the **thin / economy** form —
+ * `U` is `m x k`, `V` is `n x k`, `k = min(m, n)` — on both the WASM and the
+ * fallback path, so callers get a stable result shape.
  *
  * @packageDocumentation
  */
 
 /**
- * WASM-accelerated SVD.
- *
- * For symmetric matrices, uses WASM eigendecomposition to derive SVD.
- * For general matrices, falls back to the JavaScript Golub-Reinsch algorithm.
+ * WASM-accelerated thin SVD. Always safe to call — falls back to the
+ * synchronous JS SVD when the Rust WASM module is not available.
  *
- * @param matrix - Input matrix (m x n) as 2D array
- * @param options - SVD computation options
- * @returns SVD decomposition { U, S, V, rank }
+ * @param matrix - Input matrix (m x n) as a row-major 2D array
+ * @param options - SVD options; `rankTolerance` controls the rank estimate
+ * @returns thin SVD `{ U (m x k), S (k), V (n x k), rank }`
  */
 declare function svdWasm(matrix: number[][], options?: SVDOptions): Promise<SVDResult>;
 
+/**
+ * Moore-Penrose Pseudoinverse (DenseMatrix primitive)
+ *
+ * Computes the pseudoinverse A⁺ of a DenseMatrix A via full SVD with
+ * rcond·max(S) singular-value thresholding.
+ *
+ * Algorithm:
+ *   1. Full SVD:   A = U · diag(S) · Vᵀ   (A is m×n)
+ *      U: m×m orthogonal, V: n×n orthogonal, S: min(m,n) values (descending).
+ *   2. Threshold:  s_inv_i = 1/s_i  if  s_i > rcond·max(S),  else 0.
+ *   3. Build:      A⁺ = V · diag(s_inv) · Uᵀ   (shape: n×m).
+ *
+ * Satisfies all four Moore-Penrose identities within numerical precision:
+ *   A · A⁺ · A  = A
+ *   A⁺ · A · A⁺ = A⁺
+ *   (A · A⁺)ᵀ   = A · A⁺
+ *   (A⁺ · A)ᵀ   = A⁺ · A
+ */
+
+interface PinvOptions {
+    /**
+     * Relative condition threshold for singular-value truncation.
+     * A singular value s_i is treated as zero when s_i ≤ rcond · max(S).
+     * Default: 1e-10.
+     */
+    rcond?: number;
+}
+/**
+ * Compute the Moore-Penrose pseudoinverse of a DenseMatrix.
+ *
+ * @param A    - Input matrix (m × n).
+ * @param opts - Optional rcond threshold (default 1e-10).
+ * @returns    A⁺, the pseudoinverse of A (n × m).
+ */
+declare function pinv(A: DenseMatrix, opts?: PinvOptions): DenseMatrix;
+
+/**
+ * QR Decomposition (DenseMatrix primitive)
+ *
+ * Classical Gram-Schmidt with re-orthogonalisation. Adequate for the
+ * well-conditioned matrices that arise in the tensor wrappers + the
+ * `randomTensor` orthogonal-distribution code path. For pathological
+ * matrices the Householder QR implemented in `WASMBackend.qrDecompositionJS`
+ * is preferable, but Gram-Schmidt suffices for the current call sites.
+ *
+ * Two modes:
+ *   - 'reduced' (thin QR): Q is (m × k), R is (k × n), k = min(m, n).
+ *   - 'full'             : Q is (m × m), R is (m × n).
+ *
+ * In 'reduced' mode A = Q · R reconstructs A to within `1e-12`.
+ * Q's columns are orthonormal (Qᵀ · Q = I_k); R is upper-triangular.
+ */
+
+interface QRResult {
+    /** Orthonormal Q factor. Reduced: (m × k); full: (m × m). */
+    Q: DenseMatrix;
+    /** Upper-triangular R factor. Reduced: (k × n); full: (m × n). */
+    R: DenseMatrix;
+}
+interface QROptions {
+    /** 'reduced' (default, thin QR) or 'full'. */
+    mode?: 'reduced' | 'full';
+}
+/**
+ * Compute the QR decomposition of `A` such that `A = Q · R`.
+ *
+ * @param A    - Input matrix (m × n, m ≥ 0, n ≥ 0).
+ * @param opts - Optional mode selector (`'reduced'` thin QR or `'full'` square Q).
+ */
+declare function qr(A: DenseMatrix, opts?: QROptions): QRResult;
+
+/**
+ * LU Decomposition (DenseMatrix primitive)
+ *
+ * Doolittle's algorithm with partial (row) pivoting. Factorises a square
+ * matrix A into P · A = L · U where:
+ *   - L is unit lower-triangular (1s on the diagonal).
+ *   - U is upper-triangular.
+ *   - P is returned as a row-permutation array: P[i] is the original-row
+ *     index now at position i after pivoting.
+ *
+ * Usage:
+ *   const { L, U, P } = lu(A);
+ *   // P[i] gives the original row moved to position i, so P · A = L · U.
+ */
+
+interface LUResult {
+    /** Unit lower-triangular factor L. */
+    L: DenseMatrix;
+    /** Upper-triangular factor U. */
+    U: DenseMatrix;
+    /** Row permutation array of length n. P[i] is the original-row index now at position i. */
+    P: number[];
+}
+/**
+ * Perform LU decomposition with partial pivoting on a square `DenseMatrix`.
+ *
+ * Implements Doolittle's algorithm in compact form: the working array stores
+ * L below the diagonal (unit diagonal implicit) and U on and above it.
+ *
+ * @throws {Error} if `A` is not square.
+ * @throws {Error} if `A` is singular (zero pivot encountered).
+ */
+declare function lu(A: DenseMatrix): LUResult;
+
+/**
+ * Cholesky Decomposition (DenseMatrix primitive)
+ *
+ * Right-looking algorithm. Factorises a symmetric positive-definite (SPD)
+ * matrix A into A = L · Lᵀ where L is lower-triangular.
+ *
+ * Usage:
+ *   const { L } = cholesky(A);
+ *   // A ≈ L · L^T  (to floating-point precision)
+ */
+
+interface CholeskyResult {
+    /** Lower-triangular Cholesky factor L such that A = L · Lᵀ. */
+    L: DenseMatrix;
+}
+/**
+ * Compute the Cholesky decomposition of the symmetric positive-definite
+ * `DenseMatrix` A such that A = L · Lᵀ.
+ *
+ * @throws {Error} if `A` is not square.
+ * @throws {Error} if `A` is not positive definite (non-positive diagonal pivot).
+ */
+declare function cholesky(A: DenseMatrix): CholeskyResult;
+
+/**
+ * Matrix Exponential — Scaling-and-Squaring with Padé-13 Approximant
+ *
+ * Implements Algorithm 10.20 from:
+ *   Higham, N. J. (2005). "The scaling and squaring method for the matrix
+ *   exponential revisited." SIAM J. Matrix Anal. Appl., 26(4), 1179–1193.
+ *
+ * Algorithm:
+ *   1. Compute s = max(0, ceil(log2(||A||_1 / θ_13))) where θ_13 ≈ 5.372.
+ *   2. Scale: B = A / 2^s.
+ *   3. Compute the [13/13] Padé approximant R(B) = (U + V)^{-1} * (-U + V).
+ *   4. Square s times: expm(A) = R(B)^(2^s).
+ *
+ * Works for any real square DenseMatrix. For large ||A||, uses scaling to
+ * stay within the Padé approximant's accuracy radius.
+ */
+
+interface ExpmOptions {
+    /**
+     * When true, return the result as a DenseMatrix.
+     * When false (default), work directly on the internal number[][] and
+     * return as DenseMatrix anyway — this option is reserved for future use.
+     */
+    _reserved?: never;
+}
+/**
+ * Compute the matrix exponential of a square DenseMatrix.
+ *
+ * Uses the Padé-13 scaling-and-squaring algorithm (Higham 2005).
+ * Accurate to near machine precision for general real matrices.
+ *
+ * @param A - Square DenseMatrix (n × n).
+ * @returns expm(A) as a DenseMatrix (n × n).
+ * @throws Error if A is not square.
+ *
+ * @example
+ * // expm(0) = I
+ * matrixExpm(DenseMatrix.zeros(3, 3)) // => identity 3×3
+ *
+ * @example
+ * // expm(t*I) = e^t * I
+ * const tI = DenseMatrix.fromArray([[2,0],[0,2]]);
+ * matrixExpm(tI) // => [[e^2, 0], [0, e^2]]
+ */
+declare function matrixExpm(A: DenseMatrix): DenseMatrix;
+
+/**
+ * Matrix Logarithm — Schur-Padé inverse scaling-and-squaring (Slices 5.9a + 6.1)
+ *
+ * Implements the Schur-Padé algorithm based on:
+ *   Higham (2008) "Functions of Matrices: Theory and Computation," Chapter 11
+ *   (Algorithm 11.10).
+ *
+ * Algorithm (general Schur-based path, Slice 6.1):
+ *   1. Schur decompose: A = Q · T · Q^T.
+ *   2. Repeatedly take matrix square roots of T (Björck recurrence on upper-
+ *      triangular matrices) until ||T^{1/2^k} - I||_1 < 0.25.
+ *   3. Evaluate log(I + X) via 16-point Gauss-Legendre quadrature.
+ *   4. Scale back by 2^k; rotate by Q: logm(A) = Q · (2^k · log(T^{1/2^k})) · Q^T.
+ *
+ * For the eig-based fallback (diagonalisable matrices with positive real
+ * eigenvalues): logm(A) = V · diag(log(λ)) · V^{-1}.
+ */
+
+interface LogmOptions {
+    /**
+     * Tolerance for the "near-identity" test.
+     * Default: 0.25 (||M - I||_1 < tol triggers Padé path).
+     */
+    nearIdentityTol?: number;
+}
+/**
+ * Compute the principal matrix logarithm of a square DenseMatrix.
+ *
+ * Algorithm (Slice 5.9a — inverse scaling-and-squaring + Padé quadrature):
+ *   1. Repeatedly take matrix square roots until ||M - I||_1 < nearIdentityTol.
+ *   2. Evaluate log(I + X) = X * ∫₀¹ (I + tX)^{-1} dt via 7-pt Gauss-Legendre.
+ *   3. Scale back: logm(A) = 2^k * log(A^{1/2^k}).
+ *
+ * Falls back to eigendecomposition if the square-root sequence diverges
+ * (i.e., if the matrix has no non-positive eigenvalues and is diagonalisable).
+ *
+ * Limitations (deferred to Slice 5.9b):
+ *   - Matrices with non-positive real eigenvalues: principal log is undefined.
+ *   - Matrices with complex eigenvalues: throws.
+ *   - Non-diagonalisable (defective) matrices: eig-fallback also throws.
+ *   - Full Schur-based inverse-scaling-and-squaring for general non-normal
+ *     matrices.
+ *
+ * @param A - Square DenseMatrix with positive real eigenvalues.
+ * @returns logm(A) as a DenseMatrix.
+ * @throws Error for matrices with non-positive or complex eigenvalues.
+ *
+ * @example
+ * // logm(I) = 0
+ * matrixLogm(DenseMatrix.eye(3)) // => zero matrix
+ *
+ * @example
+ * // Round-trip: expm(logm(A)) ≈ A
+ * const A = DenseMatrix.fromArray([[4, 1], [0, 9]]);
+ * const logA = matrixLogm(A);
+ * // expm(logA) ≈ A  (to machine precision for diagonalisable A)
+ */
+declare function matrixLogm(A: DenseMatrix, opts?: LogmOptions): DenseMatrix;
+
+/**
+ * Matrix Square Root — Hybrid approach (Slices 5.9a + 6.1)
+ *
+ * Computes the principal square root of a square matrix.
+ *
+ * Algorithm selection:
+ *   1. For symmetric positive semi-definite matrices: symmetric eigendecomposition
+ *      with Gram-Schmidt re-orthogonalisation (handles repeated eigenvalues).
+ *   2. For general matrices: Björck-Hammarling Schur-based algorithm
+ *      (Higham 2008, Algorithm 6.3):
+ *        a. Schur decompose: A = Q · T · Q^T.
+ *        b. Compute upper-triangular U with U^2 = T via back-substitution.
+ *        c. Rotate back: sqrtm(A) = Q · U · Q^T.
+ *      Falls back to Newton iteration for diagonalisable matrices when the
+ *      Schur path is unsuitable (e.g. negative eigenvalues in 1×1 blocks).
+ *
+ * References:
+ *   - Higham (2008) "Functions of Matrices" §6 (Algorithm 6.3).
+ *   - Björck & Hammarling (1983) "A Schur method for the square root of a matrix."
+ */
+
+interface SqrtmOptions {
+    /**
+     * Force the symmetric-eigendecomposition path even for non-SPD matrices.
+     * By default, symmetry is auto-detected.
+     */
+    assumeSymmetric?: boolean;
+}
+/**
+ * Compute the principal square root of a square DenseMatrix.
+ *
+ * For symmetric positive semi-definite A:
+ *   Uses symmetric eigendecomposition with Gram-Schmidt re-orthogonalisation.
+ *
+ * For general diagonalisable A with non-negative eigenvalues:
+ *   Uses Newton iteration Y_{k+1} = (Y_k + A * Y_k^{-1}) / 2, falling back
+ *   to the eig-based formula if Newton fails to converge.
+ *
+ * Slice 5.9a limitations:
+ *   - Matrices with negative real eigenvalues: throws.
+ *   - Matrices with complex eigenvalues: throws.
+ *   - Non-diagonalisable (defective) matrices: Newton may fail + eig fallback
+ *     may also fail. Full Schur-based Björck-Hammarling deferred to Slice 5.9b.
+ *
+ * @param A    - Square DenseMatrix (n × n).
+ * @param opts - Optional flags.
+ * @returns sqrtm(A), the principal square root.
+ * @throws Error for matrices with negative or complex eigenvalues.
+ *
+ * @example
+ * // sqrtm(I) = I
+ * matrixSqrtm(DenseMatrix.eye(3))  // => identity 3×3
+ *
+ * @example
+ * // sqrtm(4*I) = 2*I
+ * const A = DenseMatrix.fromArray([[4,0],[0,4]]);
+ * matrixSqrtm(A)  // => [[2,0],[0,2]]
+ *
+ * @example
+ * // Round-trip: sqrtm(A)^2 ≈ A
+ * const S = DenseMatrix.fromArray([[4,2],[2,3]]);
+ * const R = matrixSqrtm(S);
+ * // R * R ≈ S  (to machine precision for SPD matrices)
+ */
+declare function matrixSqrtm(A: DenseMatrix, opts?: SqrtmOptions): DenseMatrix;
+
+/**
+ * Schur Decomposition — Francis QR with double shifts (Slice 6.1)
+ *
+ * Computes the real Schur decomposition A = Q · T · Q^T where:
+ *   - Q is orthogonal (Q^T · Q = I)
+ *   - T is quasi-upper-triangular (real Schur form): diagonal blocks are
+ *     1×1 (real eigenvalue) or 2×2 (complex-conjugate eigenvalue pair)
+ *
+ * Algorithm: Householder reduction to upper Hessenberg form followed by
+ * Francis double-shift implicit QR iteration (Golub & Van Loan §7.5).
+ *
+ * References:
+ *   Golub & Van Loan (2013) "Matrix Computations," 4th ed., §7.5.
+ *   Higham (2008) "Functions of Matrices: Theory and Computation," §1.
+ */
+
+interface SchurResult {
+    /** Orthogonal factor Q (Q^T · Q = I, Q · Q^T = I). */
+    Q: DenseMatrix;
+    /** Quasi-upper-triangular Schur form T (real Schur form). */
+    T: DenseMatrix;
+}
+interface SchurOptions {
+    /** Maximum QR iterations (default: 1000). */
+    maxIterations?: number;
+    /** Deflation tolerance (default: 1e-12). */
+    tolerance?: number;
+}
+/**
+ * Compute the real Schur decomposition of a square matrix:
+ *   A = Q · T · Q^T
+ *
+ * T is quasi-upper-triangular (real Schur form): 1×1 diagonal blocks for
+ * real eigenvalues and 2×2 blocks for complex-conjugate pairs. Q is
+ * orthogonal.
+ *
+ * For matrices with all real eigenvalues, T is upper triangular with
+ * eigenvalues on the diagonal. For matrices with complex-conjugate eigenvalue
+ * pairs, the corresponding 2×2 diagonal block has the form
+ *   [[a, b], [-b, a]]  (approximately)
+ * and the complex pair is  a ± bi.
+ *
+ * @param A - Square DenseMatrix (n × n, real entries).
+ * @param opts - Optional algorithm parameters.
+ * @returns { Q, T } satisfying Q · T · Q^T ≈ A.
+ * @throws Error if A is not square.
+ */
+declare function matrixSchur(A: DenseMatrix, opts?: SchurOptions): SchurResult;
+
 /**
  * Typed Matrix Operations
  *
@@ -2834,4 +3630,4 @@ declare function initializeParallelMatrix(): Promise<void>;
  */
 declare function terminateParallelMatrix(): Promise<void>;
 
-export { BUILTIN_SHADERS, type BackendHints, BackendManager, BackendRegistry, type BackendType, BatchExecutor, BufferPool, DEFAULT_BACKEND_HINTS, DEFAULT_EXTENDED_HINTS, DenseMatrix, type EigOptions, type EigResult, type ExtendedBackendHints, GPUBackend, type GPUBackendOptions, type GPUBackendStatus, type GPUCapabilities, GPUContext, type GPUContextOptions, GPUMatrixBackend, type GPUMatrixBackendConfig, JSBackend, Matrix, type MatrixBackend, type MatrixDimensions, type MatrixEntry, type MatrixIndex, type MatrixType, type OperationType, ParallelBackend, type ParallelBackendConfig, type SVDOptions, type SVDResult, ShaderManager, type SliceSpec, SparseMatrix, type SyncConfig, SyncManager, type SyncStrategy, WASMBackend, type WASMBackendConfig, type WasmFeatures, abs, add, backendManager, backendRegistry, clearFeatureCache, column, cond, createBackendManager, createGPUMatrixBackend, createParallelBackend, createSyncManager, createWASMBackend, destroyGlobalGPU, destroyGlobalGPUBackend, detectGPUCapabilities, detectWasmFeatures, diag, diagonal, divide, dotMultiply, eig, eigWasm, eigvals, eigvalsWasm, exp, getCachedFeatures, getGlobalGPUBackend, getGlobalGPUContext, getRecommendedWorkgroupSize, gpuMatrixBackend, hasWebGPU, identity, initializeGlobalGPUBackend, initializeParallelMatrix, isAtomicsAvailable, isDenseMatrix, isMatrix, isSharedMemoryAvailable, isSparseMatrix, isWasmAvailable, jsBackend, log, lowRankApprox, matrix, max, mean, min, multiply, norm, norm2, normFro, ones, parallelBackend, parallelDiag, parallelDotMultiply, parallelIdentity, parallelMatrix, parallelMatrixAbs, parallelMatrixAdd, parallelMatrixColumn, parallelMatrixCos, parallelMatrixDiagonal, parallelMatrixDistance, parallelMatrixDivide, parallelMatrixDot, parallelMatrixExp, parallelMatrixHistogram, parallelMatrixLog, parallelMatrixMatvec, parallelMatrixMax, parallelMatrixMean, parallelMatrixMin, parallelMatrixMultiply, parallelMatrixNorm, parallelMatrixOperations, parallelMatrixOuter, parallelMatrixRow, parallelMatrixSin, parallelMatrixSize, parallelMatrixSqrt, parallelMatrixSquare, parallelMatrixStd, parallelMatrixSubset, parallelMatrixSubtract, parallelMatrixSum, parallelMatrixTan, parallelMatrixTrace, parallelMatrixTranspose, parallelMatrixVariance, parallelOnes, parallelRandom, parallelUnaryMinus, parallelZeros, pinv, pow, powerIteration, random, row, singularValues, size, spectralRadiusWasm, sqrt, square, subset, subtract, sum, svd, svdWasm, terminateParallelMatrix, trace, transpose, typedMatrixOperations, unaryMinus, wasmBackend, zeros };
+export { BUILTIN_SHADERS, type BackendHints, BackendManager, BackendRegistry, type BackendType, BatchExecutor, BufferPool, type CholeskyResult, DEFAULT_BACKEND_HINTS, DEFAULT_EXTENDED_HINTS, DenseMatrix, type EigOptions, type EigResult, type ExpmOptions, type ExtendedBackendHints, GPUBackend, type GPUBackendOptions, type GPUBackendStatus, type GPUCapabilities, GPUContext, type GPUContextOptions, GPUMatrixBackend, type GPUMatrixBackendConfig, JSBackend, type LUResult, type LogmOptions, Matrix, type MatrixBackend, type MatrixDimensions, type MatrixEntry, type MatrixIndex, type MatrixType, type OperationType, ParallelBackend, type ParallelBackendConfig, type PinvOptions, type QROptions, type QRResult, type RustLoadingMetrics, RustWASMBackend, type RustWASMBackendConfig, type RustWasmExports, RustWasmLoader, type SVDOptions, type SVDResult, type SchurOptions, type SchurResult, ShaderManager, type SliceSpec, SparseMatrix, type SqrtmOptions, type SyncConfig, SyncManager, type SyncStrategy, WASMBackend, type WASMBackendConfig, type WasmFeatures, abs, add, backendManager, backendRegistry, cholesky, clearFeatureCache, column, cond, createBackendManager, createGPUMatrixBackend, createParallelBackend, createRustWASMBackend, createSyncManager, createWASMBackend, destroyGlobalGPU, destroyGlobalGPUBackend, detectGPUCapabilities, detectWasmFeatures, diag, diagonal, divide, dotMultiply, eig, eigWasm, eigvals, eigvalsWasm, exp, getCachedFeatures, getGlobalGPUBackend, getGlobalGPUContext, getRecommendedWorkgroupSize, gpuMatrixBackend, hasWebGPU, identity, initRustWasm, initializeGlobalGPUBackend, initializeParallelMatrix, isAtomicsAvailable, isDenseMatrix, isMatrix, isSharedMemoryAvailable, isSparseMatrix, isWasmAvailable, jsBackend, log, lowRankApprox, lu, matrix, matrixExpm, matrixLogm, pinv as matrixPinv, matrixSchur, matrixSqrtm, max, mean, min, multiply, norm, norm2, normFro, ones, parallelBackend, parallelDiag, parallelDotMultiply, parallelIdentity, parallelMatrix, parallelMatrixAbs, parallelMatrixAdd, parallelMatrixColumn, parallelMatrixCos, parallelMatrixDiagonal, parallelMatrixDistance, parallelMatrixDivide, parallelMatrixDot, parallelMatrixExp, parallelMatrixHistogram, parallelMatrixLog, parallelMatrixMatvec, parallelMatrixMax, parallelMatrixMean, parallelMatrixMin, parallelMatrixMultiply, parallelMatrixNorm, parallelMatrixOperations, parallelMatrixOuter, parallelMatrixRow, parallelMatrixSin, parallelMatrixSize, parallelMatrixSqrt, parallelMatrixSquare, parallelMatrixStd, parallelMatrixSubset, parallelMatrixSubtract, parallelMatrixSum, parallelMatrixTan, parallelMatrixTrace, parallelMatrixTranspose, parallelMatrixVariance, parallelOnes, parallelRandom, parallelUnaryMinus, parallelZeros, pinv$1 as pinv, pow, powerIteration, qr, random, row, rustWasmBackend, rustWasmLoader, singularValues, size, spectralRadiusWasm, sqrt, square, subset, subtract, sum, svd, svdWasm, terminateParallelMatrix, trace, transpose, typedMatrixOperations, unaryMinus, wasmBackend, zeros };