numbl 0.4.19 → 0.4.22

package/dist-browser/numbl-core/lowering/loweringContext.d.ts

@@ -22,13 +22,7 @@ interface WorkspaceRegistry {
     jsUserFunctionsByName: Map<string, {
         fileName: string;
         builtin: IBuiltin;
-    }>;
-    /** mtoc2-only user functions (.mtoc2.js): functionName → { fileName, source }.
-     *  Numbl never executes these — the source text is stored for mtoc2's loader
-     *  to consume. Numbl's interpreter rejects calls to them with a clear error. */
-    mtoc2UserFunctionsByName: Map<string, {
-        fileName: string;
-        source: string;
+        help?: string;
     }>;
     /** Per-workspace-file lowering contexts (created on demand) */
     fileContexts: Map<string, LoweringContext>;
@@ -75,10 +69,6 @@ export interface FunctionIndex {
     workspaceFunctions: Set<string>;
     /** JS user functions (resolved at workspace-function priority, not builtin) */
     jsUserFunctions: Set<string>;
-    /** mtoc2-only user functions (.mtoc2.js). Resolved at workspace-function
-     *  priority, like jsUserFunctions. Numbl's interpreter rejects calls to
-     *  these; mtoc2 routes them through its own loader. */
-    mtoc2UserFunctions: Set<string>;
     /** Workspace classes (classdef files) */
     workspaceClasses: Set<string>;
     /** Local subfunctions per workspace file: primaryFuncName → Set<subfuncName> */
@@ -152,10 +142,7 @@ export declare class LoweringContext {
      * Also handles @ClassName class folders.
      *
      * `.m` files register as workspace functions / classes / private functions
-     * (the regular MATLAB-style discovery). `.mtoc2.js` files register as
-     * mtoc2-only user functions: numbl tracks the name so resolution sees
-     * them, but the body stays unparsed — mtoc2's loader evaluates them.
-     * `.mtoc2.js` files in `@ClassName/` are not yet supported.
+     * (the regular MATLAB-style discovery).
      */
     registerWorkspaceFiles(files: WorkspaceFile[]): void;
     isWorkspaceFunction(name: string): boolean;
@@ -165,14 +152,7 @@ export declare class LoweringContext {
      * Register a JS user function (.numbl.js) in the workspace registry.
      * Uses first-wins semantics so search-path priority is honored.
      */
-    registerJsUserFunction(funcName: string, fileName: string, builtin: IBuiltin): void;
-    /**
-     * Register an mtoc2-only user function (.mtoc2.js) in the workspace
-     * registry. Numbl stores the source text verbatim; mtoc2's loader
-     * evaluates it. Uses first-wins semantics so search-path priority is
-     * honored — same as `.numbl.js`.
-     */
-    registerMtoc2UserFunction(funcName: string, fileName: string, source: string): void;
+    registerJsUserFunction(funcName: string, fileName: string, builtin: IBuiltin, help?: string): void;
     /**
      * Get the effective directory for this context's file, used for
      * private function resolution. If the file is inside a private/ folder,
@@ -209,6 +189,18 @@ export declare class LoweringContext {
     isLocalClass(name: string): boolean;
     isClass(name: string): boolean;
     getClassInfo(name: string): ClassInfo | null;
+    /** Ancestors of a class in method-resolution order: depth-first, left to
+     *  right through each `<` list, each name once. Built-in bases such as
+     *  `handle` are included even though they have no ClassInfo; a built-in
+     *  handle mixin (e.g. `matlab.mixin.Copyable`) is followed by `handle`. */
+    superclassNames(info: ClassInfo): string[];
+    /** `superclassNames` by class name; empty for an unknown class. */
+    classAncestors(className: string): string[];
+    /** A class followed by its ancestors that have class definitions, in
+     *  method-resolution order. */
+    classLineage(info: ClassInfo): ClassInfo[];
+    /** True if the class derives from a handle base class. */
+    isHandleClass(info: ClassInfo): boolean;
     /** Check if a class (or any ancestor) has a given method. */
     classHasMethod(className: string, methodName: string): boolean;
     /** Check if a class (or any ancestor) has a given static method. */

package/dist-browser/numbl-core/native/lapack-bridge.d.ts

@@ -1,27 +1,22 @@
 /**
- * LAPACK bridge — a module-level singleton that holds a reference to the
- * native addon when running under Node.js.
+ * LAPACK bridge: one interface for the dense linear algebra and tensor-op
+ * kernels, satisfied both by the native addon and by the pure-TypeScript
+ * implementation (ts-lapack-bridge.ts).
  *
- * In the browser the bridge is never set (stays null) and callers fall back
- * to pure-JavaScript implementations.
- *
- * Usage (CLI startup):
- *   import { setLapackBridge } from './numbl-core/native/lapack-bridge.js';
- *   setLapackBridge(require('<path-to-addon>'));
- *
- * Usage (builtin):
- *   import { getLapackBridge } from '../native/lapack-bridge.js';
- *   const bridge = getLapackBridge();
- *   if (bridge) { ... use bridge.inv(...) ... }
+ * `getLapackBridge()` always returns a complete bridge: each entry comes from
+ * the bridge installed with `setLapackBridge` (the native addon under Node,
+ * optionally a wasm accelerator in the browser) when it provides it, and from
+ * the TypeScript implementation otherwise. Call sites therefore use
+ * `getLapackBridge().X(...)` with no availability checks. Operations the
+ * TypeScript side cannot do are listed in `TS_UNSUPPORTED` in
+ * ts-lapack-bridge.ts and throw a clear error there.
  */
 /**
  * Expected native addon version. Bump this whenever the C++ addon API changes
  * (must match ADDON_VERSION in numbl_addon.cpp).
  */
-export declare const NATIVE_ADDON_EXPECTED_VERSION = 8;
+export declare const NATIVE_ADDON_EXPECTED_VERSION = 10;
 export interface LapackBridge {
-    /** Returns the native addon's version number. */
-    addonVersion?(): number;
     /**
      * Invert an n×n real matrix stored in column-major order (MATLAB/LAPACK convention).
      * @param data  Column-major Float64Array of length n*n (not modified).
@@ -29,7 +24,7 @@ export interface LapackBridge {
      * @returns     Inverted matrix as a allocFloat64Array in column-major order.
      * @throws      Error if the matrix is singular.
      */
-    inv?(data: Float64Array, n: number): Float64Array;
+    inv(data: Float64Array, n: number): Float64Array;
     /**
      * Invert an n×n complex matrix stored in column-major order (MATLAB/LAPACK convention).
      * Complex matrices are stored with separate real and imaginary parts.
@@ -39,7 +34,7 @@ export interface LapackBridge {
      * @returns       Object with {re, im} - inverted matrix parts as Float64Arrays in column-major order.
      * @throws        Error if the matrix is singular.
      */
-    invComplex?(dataRe: Float64Array, dataIm: Float64Array, n: number): {
+    invComplex(dataRe: Float64Array, dataIm: Float64Array, n: number): {
         re: Float64Array;
         im: Float64Array;
     };
@@ -53,7 +48,7 @@ export interface LapackBridge {
      * @param wantQ  false → skip dorgqr; Q will be absent from the returned object.
      * @returns      Object with R (always present) and Q (present only when wantQ=true).
      */
-    qr?(data: Float64Array, m: number, n: number, econ: boolean, wantQ: boolean): {
+    qr(data: Float64Array, m: number, n: number, econ: boolean, wantQ: boolean): {
         Q: Float64Array;
         R: Float64Array;
     };
@@ -65,7 +60,7 @@ export interface LapackBridge {
      * @param econ   true → economy/thin QR; false → full QR.
      * @returns      Object with Q, R, and jpvt (1-based permutation vector as Int32Array).
      */
-    qrPivot?(data: Float64Array, m: number, n: number, econ: boolean): {
+    qrPivot(data: Float64Array, m: number, n: number, econ: boolean): {
         Q: Float64Array;
         R: Float64Array;
         jpvt: Int32Array;
@@ -73,7 +68,7 @@ export interface LapackBridge {
     /**
      * Column-pivoted QR decomposition of an m×n complex matrix: A*P = Q*R via zgeqp3 + zungqr.
      */
-    qrPivotComplex?(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number, econ: boolean): {
+    qrPivotComplex(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number, econ: boolean): {
         QRe: Float64Array;
         QIm: Float64Array;
         RRe: Float64Array;
@@ -91,7 +86,7 @@ export interface LapackBridge {
      * @param wantQ   false → skip zungqr; Q properties will be absent from the returned object.
      * @returns       Object with RRe, RIm (always present) and QRe, QIm (present only when wantQ=true).
      */
-    qrComplex?(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number, econ: boolean, wantQ: boolean): {
+    qrComplex(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number, econ: boolean, wantQ: boolean): {
         QRe?: Float64Array;
         QIm?: Float64Array;
         RRe: Float64Array;
@@ -107,7 +102,7 @@ export interface LapackBridge {
      * @param computeUV true → compute U and V; false → compute S only.
      * @returns         Object with S (always present as vector of singular values) and optionally U and V.
      */
-    svd?(data: Float64Array, m: number, n: number, econ: boolean, computeUV: boolean): {
+    svd(data: Float64Array, m: number, n: number, econ: boolean, computeUV: boolean): {
         U?: Float64Array;
         S: Float64Array;
         V?: Float64Array;
@@ -123,7 +118,7 @@ export interface LapackBridge {
      * @param computeUV true → compute U and V; false → compute S only.
      * @returns         Object with S (real singular values) and optionally URe, UIm, VRe, VIm.
      */
-    svdComplex?(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number, econ: boolean, computeUV: boolean): {
+    svdComplex(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number, econ: boolean, computeUV: boolean): {
         S: Float64Array;
         URe?: Float64Array;
         UIm?: Float64Array;
@@ -140,7 +135,7 @@ export interface LapackBridge {
      * @param n  Number of columns in B and C.
      * @returns  C = A*B as a allocFloat64Array of length m*n in column-major order.
      */
-    matmul?(A: Float64Array, m: number, k: number, B: Float64Array, n: number): Float64Array;
+    matmul(A: Float64Array, m: number, k: number, B: Float64Array, n: number): Float64Array;
     /**
      * Complex matrix-matrix multiplication using BLAS zgemm.
      * Computes C = A * B in column-major order.
@@ -153,7 +148,7 @@ export interface LapackBridge {
      * @param n    Number of columns in B and C.
      * @returns    Object with {re, im?} — complex result as Float64Arrays.
      */
-    matmulComplex?(ARe: Float64Array, AIm: Float64Array, m: number, k: number, BRe: Float64Array, BIm: Float64Array, n: number): {
+    matmulComplex(ARe: Float64Array, AIm: Float64Array, m: number, k: number, BRe: Float64Array, BIm: Float64Array, n: number): {
         re: Float64Array;
         im?: Float64Array;
     };
@@ -170,7 +165,7 @@ export interface LapackBridge {
      * @param nrhs  Number of right-hand sides (columns of B and X).
      * @returns     X as a allocFloat64Array of length n*nrhs in column-major order.
      */
-    linsolve?(A: Float64Array, m: number, n: number, B: Float64Array, nrhs: number): Float64Array;
+    linsolve(A: Float64Array, m: number, n: number, B: Float64Array, nrhs: number): Float64Array;
     /**
      * Solve a complex linear system A * X = B.
      * Input/output are column-major Float64Arrays for real and imaginary parts.
@@ -187,7 +182,7 @@ export interface LapackBridge {
      * @param nrhs  Number of right-hand sides (columns of B and X).
      * @returns     Object with {re, im} — X as Float64Arrays of length n*nrhs in column-major order.
      */
-    linsolveComplex?(ARe: Float64Array, AIm: Float64Array, m: number, n: number, BRe: Float64Array, BIm: Float64Array, nrhs: number): {
+    linsolveComplex(ARe: Float64Array, AIm: Float64Array, m: number, n: number, BRe: Float64Array, BIm: Float64Array, nrhs: number): {
         re: Float64Array;
         im: Float64Array;
     };
@@ -201,12 +196,40 @@ export interface LapackBridge {
      * @param balance    true → balance matrix before computing (default); false → no balancing.
      * @returns          Object with wr/wi (real/imag parts of eigenvalues) and optionally VL/VR.
      */
-    eig?(data: Float64Array, n: number, computeVL: boolean, computeVR: boolean, balance: boolean): {
+    eig(data: Float64Array, n: number, computeVL: boolean, computeVR: boolean, balance: boolean): {
         wr: Float64Array;
         wi: Float64Array;
         VL?: Float64Array;
         VR?: Float64Array;
     };
+    /**
+     * Eigenvalue decomposition of an n×n real *symmetric* matrix stored in
+     * column-major order. Uses LAPACK dsyev (only the lower triangle is read).
+     * Unlike `eig`, the eigenvalues are real and returned in ascending order and
+     * the eigenvectors are orthonormal, including across repeated eigenvalues.
+     * @param data      Column-major Float64Array of length n*n (not modified).
+     * @param n         Matrix dimension.
+     * @param computeV  true → also compute the orthonormal eigenvectors.
+     * @returns         Object with w (ascending eigenvalues) and optionally V.
+     */
+    eigSym(data: Float64Array, n: number, computeV: boolean): {
+        w: Float64Array;
+        V?: Float64Array;
+    };
+    /**
+     * Eigenvalue decomposition of an n×n complex *Hermitian* matrix stored in
+     * column-major order. Uses LAPACK zheev (only the lower triangle is read).
+     * @param dataRe    Real parts — column-major Float64Array of length n*n.
+     * @param dataIm    Imaginary parts — column-major Float64Array of length n*n.
+     * @param n         Matrix dimension.
+     * @param computeV  true → also compute the unitary eigenvector basis.
+     * @returns         Object with w (real, ascending) and optionally VRe/VIm.
+     */
+    eigHerm(dataRe: Float64Array, dataIm: Float64Array, n: number, computeV: boolean): {
+        w: Float64Array;
+        VRe?: Float64Array;
+        VIm?: Float64Array;
+    };
     /**
      * Eigenvalue decomposition of an n×n complex matrix stored in column-major order.
      * Uses LAPACK zgeev.
@@ -217,7 +240,7 @@ export interface LapackBridge {
      * @param computeVR  true → compute right eigenvectors.
      * @returns          Object with wRe/wIm (real/imag parts of eigenvalues) and optionally VLRe/VLIm/VRRe/VRIm.
      */
-    eigComplex?(dataRe: Float64Array, dataIm: Float64Array, n: number, computeVL: boolean, computeVR: boolean): {
+    eigComplex(dataRe: Float64Array, dataIm: Float64Array, n: number, computeVL: boolean, computeVR: boolean): {
         wRe: Float64Array;
         wIm: Float64Array;
         VLRe?: Float64Array;
@@ -234,7 +257,7 @@ export interface LapackBridge {
      *   - LU: m×n Float64Array with L (unit lower) and U (upper) packed together.
      *   - ipiv: Int32Array of length min(m,n), 1-based pivot indices from dgetrf.
      */
-    lu?(data: Float64Array, m: number, n: number): {
+    lu(data: Float64Array, m: number, n: number): {
         LU: Float64Array;
         ipiv: Int32Array;
     };
@@ -248,7 +271,7 @@ export interface LapackBridge {
      *   - LURe, LUIm: m×n Float64Arrays with L (unit lower) and U (upper) packed together.
      *   - ipiv: Int32Array of length min(m,n), 1-based pivot indices from zgetrf.
      */
-    luComplex?(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number): {
+    luComplex(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number): {
         LURe: Float64Array;
         LUIm: Float64Array;
         ipiv: Int32Array;
@@ -264,7 +287,7 @@ export interface LapackBridge {
      *   - R: n×n Float64Array with the triangular factor (opposite triangle zeroed).
      *   - info: 0 if successful, >0 if not positive definite (index of failing pivot).
      */
-    chol?(data: Float64Array, n: number, upper: boolean): {
+    chol(data: Float64Array, n: number, upper: boolean): {
         R: Float64Array;
         info: number;
     };
@@ -280,7 +303,7 @@ export interface LapackBridge {
      *   - RRe, RIm: n×n Float64Arrays with the triangular factor.
      *   - info: 0 if successful, >0 if not positive definite.
      */
-    cholComplex?(dataRe: Float64Array, dataIm: Float64Array, n: number, upper: boolean): {
+    cholComplex(dataRe: Float64Array, dataIm: Float64Array, n: number, upper: boolean): {
         RRe: Float64Array;
         RIm: Float64Array;
         info: number;
@@ -301,7 +324,7 @@ export interface LapackBridge {
      *   - V?: n×n Float64Array, right generalized eigenvectors (packed, like dgeev format).
      *   - W?: n×n Float64Array, left generalized eigenvectors (packed, like dgeev format).
      */
-    qz?(dataA: Float64Array, dataB: Float64Array, n: number, computeEigvecs: boolean): {
+    qz(dataA: Float64Array, dataB: Float64Array, n: number, computeEigvecs: boolean): {
         AA: Float64Array;
         BB: Float64Array;
         Q: Float64Array;
@@ -316,48 +339,7 @@ export interface LapackBridge {
      * Complex QZ factorization (generalized Schur decomposition) of an n×n complex matrix pair.
      * Uses LAPACK zgges (and ztgevc for eigenvectors).
      */
-    /**
-     * Forward/inverse 1D FFT on real input via FFTW.
-     * Does NOT normalize for inverse — caller handles 1/n scaling.
-     * @param re      Real input data as Float64Array of length n.
-     * @param n       Transform length.
-     * @param inverse true for inverse FFT, false for forward.
-     * @returns       { re, im } Float64Arrays of length n.
-     */
-    fft1d?(re: Float64Array, n: number, inverse: boolean): {
-        re: Float64Array;
-        im: Float64Array;
-    };
-    /**
-     * Forward/inverse 1D FFT on complex input via FFTW.
-     * Does NOT normalize for inverse — caller handles 1/n scaling.
-     * @param re      Real part of input as Float64Array of length n.
-     * @param im      Imaginary part of input as Float64Array of length n.
-     * @param n       Transform length.
-     * @param inverse true for inverse FFT, false for forward.
-     * @returns       { re, im } Float64Arrays of length n.
-     */
-    fft1dComplex?(re: Float64Array, im: Float64Array, n: number, inverse: boolean): {
-        re: Float64Array;
-        im: Float64Array;
-    };
-    /**
-     * Batch FFT along a single dimension of a column-major tensor via FFTW.
-     * Transforms ALL fibers in one FFTW call using the guru split interface.
-     * Does NOT normalize for inverse — caller handles 1/n scaling.
-     * @param re      Real part of input tensor (column-major flat array).
-     * @param im      Imaginary part, or null for real input.
-     * @param shape   Tensor dimensions as a JS array of numbers.
-     * @param dim     0-based dimension to transform along.
-     * @param n       FFT length (may differ from shape[dim] for pad/truncate).
-     * @param inverse true for inverse FFT, false for forward.
-     * @returns       { re, im } Float64Arrays for the output tensor.
-     */
-    fftAlongDim?(re: Float64Array, im: Float64Array | null, shape: number[], dim: number, n: number, inverse: boolean): {
-        re: Float64Array;
-        im: Float64Array;
-    };
-    qzComplex?(dataARe: Float64Array, dataAIm: Float64Array, dataBRe: Float64Array, dataBIm: Float64Array, n: number, computeEigvecs: boolean): {
+    qzComplex(dataARe: Float64Array, dataAIm: Float64Array, dataBRe: Float64Array, dataBIm: Float64Array, n: number, computeEigvecs: boolean): {
         AARe: Float64Array;
         AAIm: Float64Array;
         BBRe: Float64Array;
@@ -375,26 +357,6 @@ export interface LapackBridge {
         WRe?: Float64Array;
         WIm?: Float64Array;
     };
-    /**
-     * Bulk fill normal random values using Marsaglia polar + xoshiro128**.
-     * State is mutated in-place. Spare is passed in/out to preserve pair caching.
-     */
-    fillRandn?(state: Uint32Array, n: number, spare: number, hasSpare: boolean): {
-        data: Float64Array;
-        spare: number;
-        hasSpare: boolean;
-    };
-    /**
-     * Unary element-wise math on a real Float64Array.
-     * op: 0=exp, 1=log, 2=log2, 3=log10, 4=sqrt, 5=abs, 6=floor, 7=ceil,
-     *     8=round, 9=trunc, 10=sin, 11=cos, 12=tan, 13=asin, 14=acos, 15=atan,
-     *     16=sinh, 17=cosh, 18=tanh, 19=sign
-     */
-    unaryElemwise?(arr: Float64Array, op: number): Float64Array;
-    /** Element-wise binary op on real Float64Arrays. op: 0=add, 1=sub, 2=mul, 3=div */
-    elemwise?(a: Float64Array, b: Float64Array, op: number): Float64Array;
-    /** Scalar-tensor element-wise op. scalarOnLeft: true → scalar op arr[i], false → arr[i] op scalar */
-    elemwiseScalar?(scalar: number, arr: Float64Array, op: number, scalarOnLeft: boolean): Float64Array;
     /**
      * Restarted GMRES solver for A*x = b (real, dense matrices only).
      * Uses BLAS dgemv for matvec and LAPACK dgetrf+dgetrs for preconditioner.
@@ -409,7 +371,7 @@ export interface LapackBridge {
      * @param x0      Initial guess (length n), or null for zeros.
      * @returns       Object with x, flag, relres, iter (Int32Array[2]), resvec.
      */
-    gmres?(A: Float64Array, n: number, b: Float64Array, restart: number, tol: number, maxit: number, M1: Float64Array | null, M2: Float64Array | null, x0: Float64Array | null): {
+    gmres(A: Float64Array, n: number, b: Float64Array, restart: number, tol: number, maxit: number, M1: Float64Array | null, M2: Float64Array | null, x0: Float64Array | null): {
         x: Float64Array;
         flag: number;
         relres: number;
@@ -419,7 +381,7 @@ export interface LapackBridge {
     /**
      * Complex restarted GMRES solver for A*x = b (split real/imag dense matrices).
      */
-    gmresComplex?(ARe: Float64Array, AIm: Float64Array, n: number, bRe: Float64Array, bIm: Float64Array, restart: number, tol: number, maxit: number, M1Re: Float64Array | null, M1Im: Float64Array | null, M2Re: Float64Array | null, M2Im: Float64Array | null, x0Re: Float64Array | null, x0Im: Float64Array | null): {
+    gmresComplex(ARe: Float64Array, AIm: Float64Array, n: number, bRe: Float64Array, bIm: Float64Array, restart: number, tol: number, maxit: number, M1Re: Float64Array | null, M1Im: Float64Array | null, M2Re: Float64Array | null, M2Im: Float64Array | null, x0Re: Float64Array | null, x0Im: Float64Array | null): {
         xRe: Float64Array;
         xIm: Float64Array;
         flag: number;
@@ -427,56 +389,103 @@ export interface LapackBridge {
         iter: Int32Array;
         resvec: Float64Array;
     };
-    /** Element-wise binary op on complex Float64Arrays. op: 0=add, 1=sub, 2=mul, 3=div */
-    elemwiseComplex?(aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, op: number): {
-        re: Float64Array;
-        im?: Float64Array;
-    };
-    /** Complex-scalar * (real or complex) tensor element-wise op.
-     * op: 0=add, 1=sub, 2=mul, 3=div.
-     * Pass null for arrIm to treat the tensor as purely real. */
-    elemwiseComplexScalar?(scalarRe: number, scalarIm: number, arrRe: Float64Array, arrIm: Float64Array | null, op: number, scalarOnLeft: boolean): {
-        re: Float64Array;
-        im?: Float64Array;
-    };
     /** Real binary elemwise: out[i] = a[i] OP b[i]. op codes per OpRealBin. */
-    tensorOpRealBinary?(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    tensorOpRealBinary(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
     /** Real scalar-tensor binary elemwise. */
-    tensorOpRealScalarBinary?(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    tensorOpRealScalarBinary(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
     /** Complex binary elemwise (split storage). aIm/bIm may be null. */
-    tensorOpComplexBinary?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    tensorOpComplexBinary(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
     /** Complex scalar-tensor binary elemwise. arrIm may be null. */
-    tensorOpComplexScalarBinary?(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;
+    tensorOpComplexScalarBinary(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;
     /** Real unary elemwise: out[i] = OP(a[i]). op codes per OpUnary. */
-    tensorOpRealUnary?(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    tensorOpRealUnary(op: number, n: number, a: Float64Array, out: Float64Array): void;
     /** Complex unary elemwise (split storage). aIm may be null. ABS unsupported. */
-    tensorOpComplexUnary?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    tensorOpComplexUnary(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
     /** Complex absolute value (real-valued output). aIm may be null. */
-    tensorOpComplexAbs?(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;
+    tensorOpComplexAbs(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;
     /** Real comparison: out[i] = (a[i] OP b[i]) ? 1 : 0. */
-    tensorOpRealComparison?(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    tensorOpRealComparison(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
     /** Real scalar-tensor comparison. */
-    tensorOpRealScalarComparison?(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    tensorOpRealScalarComparison(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
     /** Complex comparison. EQ/NE use both parts; LT/LE/GT/GE use real parts. */
-    tensorOpComplexComparison?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+    tensorOpComplexComparison(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
     /** Complex scalar-tensor comparison. */
-    tensorOpComplexScalarComparison?(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;
+    tensorOpComplexScalarComparison(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;
     /** Flat real reduction (output is a 1-element Float64Array). */
-    tensorOpRealFlatReduce?(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    tensorOpRealFlatReduce(op: number, n: number, a: Float64Array, out: Float64Array): void;
     /** Flat complex reduction.  outIm may be null for ANY/ALL. */
-    tensorOpComplexFlatReduce?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;
+    tensorOpComplexFlatReduce(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;
     /**
      * Real Bessel tensor op: out[i] = besselX(nu, z[i]).
      * op codes per OpBessel. scale: 0 unscaled, 1 scaled.
      */
-    tensorOpBesselReal?(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+    tensorOpBesselReal(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
     /**
      * Hankel function tensor op (complex output, real input).
      * kKind: 1 → J + i*Y; 2 → J - i*Y.
      */
-    tensorOpBesselH?(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;
+    tensorOpBesselH(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;
+    /** Returns the native addon's version number. */
+    addonVersion?(): number;
     /** Dump op-code enum values as a stable string (drift detection). */
     tensorOpDumpCodes?(): string;
+    /**
+     * Forward/inverse 1D FFT on real input via FFTW.
+     * Does NOT normalize for inverse — caller handles 1/n scaling.
+     * @param re      Real input data as Float64Array of length n.
+     * @param n       Transform length.
+     * @param inverse true for inverse FFT, false for forward.
+     * @returns       { re, im } Float64Arrays of length n.
+     */
+    fft1d?(re: Float64Array, n: number, inverse: boolean): {
+        re: Float64Array;
+        im: Float64Array;
+    };
+    /**
+     * Forward/inverse 1D FFT on complex input via FFTW.
+     * Does NOT normalize for inverse — caller handles 1/n scaling.
+     * @param re      Real part of input as Float64Array of length n.
+     * @param im      Imaginary part of input as Float64Array of length n.
+     * @param n       Transform length.
+     * @param inverse true for inverse FFT, false for forward.
+     * @returns       { re, im } Float64Arrays of length n.
+     */
+    fft1dComplex?(re: Float64Array, im: Float64Array, n: number, inverse: boolean): {
+        re: Float64Array;
+        im: Float64Array;
+    };
+    /**
+     * Batch FFT along a single dimension of a column-major tensor via FFTW.
+     * Transforms ALL fibers in one FFTW call using the guru split interface.
+     * Does NOT normalize for inverse — caller handles 1/n scaling.
+     * @param re      Real part of input tensor (column-major flat array).
+     * @param im      Imaginary part, or null for real input.
+     * @param shape   Tensor dimensions as a JS array of numbers.
+     * @param dim     0-based dimension to transform along.
+     * @param n       FFT length (may differ from shape[dim] for pad/truncate).
+     * @param inverse true for inverse FFT, false for forward.
+     * @returns       { re, im } Float64Arrays for the output tensor.
+     */
+    fftAlongDim?(re: Float64Array, im: Float64Array | null, shape: number[], dim: number, n: number, inverse: boolean): {
+        re: Float64Array;
+        im: Float64Array;
+    };
+    /**
+     * Bulk fill normal random values using Marsaglia polar + xoshiro128**.
+     * State is mutated in-place. Spare is passed in/out to preserve pair caching.
+     */
+    fillRandn?(state: Uint32Array, n: number, spare: number, hasSpare: boolean): {
+        data: Float64Array;
+        spare: number;
+        hasSpare: boolean;
+    };
 }
-export declare function setLapackBridge(bridge: LapackBridge): void;
-export declare function getLapackBridge(): LapackBridge | null;
+/** Set (or clear) the sink for the one-time "bridge in use" diagnostic. */
+export declare function setBridgeLog(log: ((message: string) => void) | null): void;
+/**
+ * Install an accelerated bridge (native addon, wasm module, test stub), or
+ * clear it with null. Entries it omits fall back to TypeScript.
+ */
+export declare function setLapackBridge(bridge: Partial<LapackBridge> | null): void;
+/** The complete bridge: installed entries over the TypeScript ones. */
+export declare function getLapackBridge(): LapackBridge;

package/dist-browser/numbl-core/native/ts-lapack-bridge.d.ts

@@ -1,9 +1,8 @@
 /**
- * Pure-TypeScript LAPACK bridge — implements the LapackBridge interface using
- * the ts-lapack translations of LAPACK Fortran routines.
- *
- * This is always available (no native addon required) and is used as the
- * fallback when the native C++ addon is not loaded (e.g. in the browser).
+ * Pure-TypeScript LAPACK bridge: implements the LapackBridge interface with
+ * the ts-lapack translations of LAPACK Fortran routines and the ops-layer
+ * tensor kernels. getLapackBridge() uses it for every entry the installed
+ * (native) bridge does not provide, e.g. everything in the browser.
  */
 import type { LapackBridge } from "./lapack-bridge.js";
 export declare function getTsLapackBridge(): LapackBridge;

package/dist-browser/numbl-core/native/ts-lapack-complex.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Complex scalar helpers and ZLARFG shared by the ts-lapack complex
+ * routines (eig, Hermitian eig, QR). Split real/imag storage throughout.
+ */
+export declare const EPS = 2.220446049250313e-16;
+export declare const SAFMIN = 2.2250738585072014e-308;
+/** |Re| + |Im| (LAPACK CABS1). */
+export declare function cabs1(re: number, im: number): number;
+/** Fortran SIGN(mag, s): |mag| with the sign of s. */
+export declare function fsign(mag: number, s: number): number;
+/** Robust complex divide (a/b) via Smith's algorithm (ZLADIV). */
+export declare function cdiv(ar: number, ai: number, br: number, bi: number): [number, number];
+/** sqrt(x^2 + y^2 + z^2) without spurious over/underflow (DLAPY3). */
+export declare function dlapy3(x: number, y: number, z: number): number;
+/** DZNRM2 over x(off), x(off+incx), ... (n elements). */
+export declare function dznrm2(n: number, re: Float64Array, im: Float64Array, off: number, incx: number): number;
+/**
+ * ZLARFG: generate a complex elementary reflector H = I - tau*v*v^H with
+ * H^H * [alpha; x] = [beta; 0] and beta real. On entry re/im[off] = alpha and
+ * X is re/im[off + i*incx], i = 1..n-1; on exit re/im[off] = beta and the X
+ * part holds v(2:). Returns tau.
+ */
+export declare function zlarfg(n: number, re: Float64Array, im: Float64Array, off: number, incx: number): [number, number];

package/dist-browser/numbl-core/native/ts-lapack-eig-hermitian.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure-TypeScript Hermitian eigensolver — a zheev-equivalent for the ts-lapack
+ * bridge (browser path, no native LAPACK addon).
+ *
+ * Ported from the netlib LAPACK reference (zheev → zhetd2 / zungtr → zsteqr).
+ * One structural deviation: zsteqr accumulates the QL/QR rotations directly
+ * into the complex matrix Q, whereas here DSTEQR is run with COMPZ = 'I' to
+ * get the real orthogonal eigenvector matrix S of the tridiagonal, and the
+ * back-transformation V = Q * S is done as one complex-times-real matrix
+ * product afterwards. Both are O(n^3); this way the tridiagonal QL/QR lives in
+ * exactly one place (src/ts-lapack/src/SRC/dsteqr.ts) instead of two.
+ *
+ * Because zlarfg produces a real beta, the tridiagonal form is real symmetric,
+ * so DSTEQR applies unchanged.
+ *
+ * Eigenvalues come back real and in ascending order; eigenvectors form a
+ * unitary basis (V^H * V = I), matching dsyev/zheev and MATLAB.
+ *
+ * All matrices are column-major with leading dimension n, split into parallel
+ * real/imag Float64Arrays — matching the bridge's eigHerm I/O shape.
+ */
+/**
+ * ZHEEV-equivalent. `dataRe`/`dataIm` hold the full n×n Hermitian matrix in
+ * column-major order (only the lower triangle is read); they are not modified.
+ *
+ * Returns the eigenvalues in ascending order, plus a unitary eigenvector basis
+ * when `computeV` is set.
+ */
+export declare function eigHermTs(dataRe: Float64Array, dataIm: Float64Array, n: number, computeV: boolean): {
+    w: Float64Array;
+    VRe?: Float64Array;
+    VIm?: Float64Array;
+};

package/dist-browser/numbl-core/native/ts-lapack-qr-lu.d.ts

@@ -0,0 +1,37 @@
+/**
+ * QR and LU entry points of the ts-lapack bridge that are not plain calls
+ * into src/ts-lapack: real column-pivoted QR, and complex QR (zgeqr2/zung2r),
+ * column-pivoted QR (zlaqp2) and LU (zgetf2).
+ *
+ * The complex routines are unblocked translations that follow the LAPACK
+ * conventions (zlarfg: real diagonal of R with beta = -sign(Re(alpha))*norm;
+ * izamax pivoting by |re|+|im|) so results agree with MATLAB up to rounding.
+ */
+/**
+ * Real column-pivoted QR, A*P = Q*R (dgeqp3 + dorgqr equivalent): Householder
+ * with greedy pivoting on downdated squared column norms. jpvt is 1-based.
+ */
+export declare function qrPivotTs(data: Float64Array, m: number, n: number, econ: boolean): {
+    Q: Float64Array;
+    R: Float64Array;
+    jpvt: Int32Array;
+};
+export declare function qrComplexTs(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number, econ: boolean, wantQ: boolean): {
+    QRe?: Float64Array;
+    QIm?: Float64Array;
+    RRe: Float64Array;
+    RIm: Float64Array;
+};
+export declare function qrPivotComplexTs(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number, econ: boolean): {
+    QRe: Float64Array;
+    QIm: Float64Array;
+    RRe: Float64Array;
+    RIm: Float64Array;
+    jpvt: Int32Array;
+};
+/** zgetf2: LU with partial pivoting, L unit lower and U packed in place. */
+export declare function luComplexTs(dataRe: Float64Array, dataIm: Float64Array, m: number, n: number): {
+    LURe: Float64Array;
+    LUIm: Float64Array;
+    ipiv: Int32Array;
+};