numbl 0.4.8 → 0.4.9

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

@@ -0,0 +1,482 @@
+/**
+ * LAPACK bridge — a module-level singleton that holds a reference to the
+ * native addon when running under Node.js.
+ *
+ * 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(...) ... }
+ */
+/**
+ * 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 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).
+     * @param n     Matrix dimension.
+     * @returns     Inverted matrix as a allocFloat64Array in column-major order.
+     * @throws      Error if the matrix is singular.
+     */
+    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.
+     * @param dataRe  Real parts in column-major Float64Array of length n*n (not modified).
+     * @param dataIm  Imaginary parts in column-major Float64Array of length n*n (not modified).
+     * @param n       Matrix dimension.
+     * @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): {
+        re: Float64Array;
+        im: Float64Array;
+    };
+    /**
+     * QR decomposition of an m×n real matrix stored in column-major order.
+     * Uses LAPACK dgeqrf (QR factorisation) + dorgqr (generate Q).
+     * @param data   Column-major Float64Array of length m*n (not modified).
+     * @param m      Number of rows.
+     * @param n      Number of columns.
+     * @param econ   true → economy/thin QR (Q: m×k, R: k×n); false → full QR (Q: m×m, R: m×n). k = min(m,n).
+     * @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): {
+        Q: Float64Array;
+        R: Float64Array;
+    };
+    /**
+     * Column-pivoted QR decomposition: A*P = Q*R via dgeqp3 + dorgqr.
+     * @param data   Column-major Float64Array of length m*n (not modified).
+     * @param m      Number of rows.
+     * @param n      Number of columns.
+     * @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): {
+        Q: Float64Array;
+        R: Float64Array;
+        jpvt: Int32Array;
+    };
+    /**
+     * 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): {
+        QRe: Float64Array;
+        QIm: Float64Array;
+        RRe: Float64Array;
+        RIm: Float64Array;
+        jpvt: Int32Array;
+    };
+    /**
+     * QR decomposition of an m×n complex matrix stored in column-major order.
+     * Uses LAPACK zgeqrf (QR factorisation) + zungqr (generate Q).
+     * @param dataRe  Real parts — column-major Float64Array of length m*n (not modified).
+     * @param dataIm  Imaginary parts — column-major Float64Array of length m*n (not modified).
+     * @param m       Number of rows.
+     * @param n       Number of columns.
+     * @param econ    true → economy/thin QR; false → full QR.
+     * @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): {
+        QRe?: Float64Array;
+        QIm?: Float64Array;
+        RRe: Float64Array;
+        RIm: Float64Array;
+    };
+    /**
+     * SVD (Singular Value Decomposition) of an m×n real matrix stored in column-major order.
+     * Uses LAPACK dgesdd (divide-and-conquer SVD).
+     * @param data      Column-major Float64Array of length m*n (not modified).
+     * @param m         Number of rows.
+     * @param n         Number of columns.
+     * @param econ      true → economy SVD (U: m×k, S: k, V: n×k); false → full SVD (U: m×m, S: min(m,n), V: n×n). k = min(m,n).
+     * @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): {
+        U?: Float64Array;
+        S: Float64Array;
+        V?: Float64Array;
+    };
+    /**
+     * SVD (Singular Value Decomposition) of an m×n complex matrix stored in column-major order.
+     * Uses LAPACK zgesdd (complex divide-and-conquer SVD).
+     * @param dataRe    Real parts — column-major Float64Array of length m*n (not modified).
+     * @param dataIm    Imaginary parts — column-major Float64Array of length m*n (not modified).
+     * @param m         Number of rows.
+     * @param n         Number of columns.
+     * @param econ      true → economy SVD; false → full SVD.
+     * @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): {
+        S: Float64Array;
+        URe?: Float64Array;
+        UIm?: Float64Array;
+        VRe?: Float64Array;
+        VIm?: Float64Array;
+    };
+    /**
+     * Real matrix-matrix multiplication using BLAS dgemm.
+     * Computes C = A * B in column-major order.
+     * @param A  Column-major Float64Array of length m*k  (A is m×k, not modified).
+     * @param m  Number of rows in A and C.
+     * @param k  Number of columns in A and rows in B.
+     * @param B  Column-major Float64Array of length k*n  (B is k×n, not modified).
+     * @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;
+    /**
+     * Complex matrix-matrix multiplication using BLAS zgemm.
+     * Computes C = A * B in column-major order.
+     * @param ARe  Real parts of A, column-major Float64Array of length m*k.
+     * @param AIm  Imaginary parts of A, column-major Float64Array of length m*k.
+     * @param m    Number of rows in A and C.
+     * @param k    Number of columns in A and rows in B.
+     * @param BRe  Real parts of B, column-major Float64Array of length k*n.
+     * @param BIm  Imaginary parts of B, column-major Float64Array of length k*n.
+     * @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): {
+        re: Float64Array;
+        im?: Float64Array;
+    };
+    /**
+     * Solve a linear system A * X = B.
+     * If A is square (m === n), uses LU factorization (dgesv / dgetrf+solve).
+     * If A is non-square, uses QR / LQ factorization (dgels / dgeqrf+solve):
+     *   overdetermined (m > n): least-squares solution minimising ||A*X - B||₂
+     *   underdetermined (m < n): minimum-norm solution minimising ||X||₂
+     * @param A     Column-major Float64Array of length m*n  (A is m×n, not modified).
+     * @param m     Number of rows in A and B.
+     * @param n     Number of columns in A; also the number of rows in the result X.
+     * @param B     Column-major Float64Array of length m*nrhs  (B is m×nrhs, not modified).
+     * @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;
+    /**
+     * Solve a complex linear system A * X = B.
+     * Input/output are column-major Float64Arrays for real and imaginary parts.
+     * If A is square (m === n), uses LU factorization (zgesv).
+     * If A is non-square, uses QR / LQ factorization (zgels):
+     *   overdetermined (m > n): least-squares solution minimising ||A*X - B||₂
+     *   underdetermined (m < n): minimum-norm solution minimising ||X||₂
+     * @param ARe   Real parts of A — column-major Float64Array of length m*n (not modified).
+     * @param AIm   Imaginary parts of A — column-major Float64Array of length m*n (not modified).
+     * @param m     Number of rows in A and B.
+     * @param n     Number of columns in A; also the number of rows in the result X.
+     * @param BRe   Real parts of B — column-major Float64Array of length m*nrhs (not modified).
+     * @param BIm   Imaginary parts of B — column-major Float64Array of length m*nrhs (not modified).
+     * @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): {
+        re: Float64Array;
+        im: Float64Array;
+    };
+    /**
+     * Eigenvalue decomposition of an n×n real matrix stored in column-major order.
+     * Uses LAPACK dgeev.
+     * @param data       Column-major Float64Array of length n*n (not modified).
+     * @param n          Matrix dimension.
+     * @param computeVL  true → compute left eigenvectors.
+     * @param computeVR  true → compute right eigenvectors.
+     * @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): {
+        wr: Float64Array;
+        wi: Float64Array;
+        VL?: Float64Array;
+        VR?: Float64Array;
+    };
+    /**
+     * Eigenvalue decomposition of an n×n complex matrix stored in column-major order.
+     * Uses LAPACK zgeev.
+     * @param dataRe     Real parts — column-major Float64Array of length n*n (not modified).
+     * @param dataIm     Imaginary parts — column-major Float64Array of length n*n (not modified).
+     * @param n          Matrix dimension.
+     * @param computeVL  true → compute left eigenvectors.
+     * @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): {
+        wRe: Float64Array;
+        wIm: Float64Array;
+        VLRe?: Float64Array;
+        VLIm?: Float64Array;
+        VRRe?: Float64Array;
+        VRIm?: Float64Array;
+    };
+    /**
+     * LU factorization of an m×n real matrix with partial pivoting (dgetrf).
+     * @param data   Column-major Float64Array of length m*n (not modified).
+     * @param m      Number of rows.
+     * @param n      Number of columns.
+     * @returns      Object with:
+     *   - 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: Float64Array;
+        ipiv: Int32Array;
+    };
+    /**
+     * LU factorization of an m×n complex matrix with partial pivoting (zgetrf).
+     * @param dataRe  Real parts — column-major Float64Array of length m*n (not modified).
+     * @param dataIm  Imaginary parts — column-major Float64Array of length m*n (not modified).
+     * @param m       Number of rows.
+     * @param n       Number of columns.
+     * @returns       Object with:
+     *   - 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): {
+        LURe: Float64Array;
+        LUIm: Float64Array;
+        ipiv: Int32Array;
+    };
+    /**
+     * Cholesky factorization of an n×n real symmetric positive definite matrix.
+     * Uses LAPACK dpotrf.
+     * @param data   Column-major Float64Array of length n*n (not modified).
+     * @param n      Matrix dimension.
+     * @param upper  true → compute upper triangular R (A = R'*R);
+     *               false → compute lower triangular L (A = L*L').
+     * @returns      Object with:
+     *   - 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): {
+        R: Float64Array;
+        info: number;
+    };
+    /**
+     * Cholesky factorization of an n×n complex Hermitian positive definite matrix.
+     * Uses LAPACK zpotrf.
+     * @param dataRe  Real parts — column-major Float64Array of length n*n (not modified).
+     * @param dataIm  Imaginary parts — column-major Float64Array of length n*n (not modified).
+     * @param n       Matrix dimension.
+     * @param upper   true → compute upper triangular R (A = R'*R);
+     *                false → compute lower triangular L (A = L*L').
+     * @returns       Object with:
+     *   - 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): {
+        RRe: Float64Array;
+        RIm: Float64Array;
+        info: number;
+    };
+    /**
+     * QZ factorization (generalized Schur decomposition) of an n×n real matrix pair.
+     * Uses LAPACK dgges (and dtgevc for eigenvectors).
+     * @param dataA           Column-major Float64Array of length n*n (not modified).
+     * @param dataB           Column-major Float64Array of length n*n (not modified).
+     * @param n               Matrix dimension.
+     * @param computeEigvecs  true → also compute generalized eigenvectors via dtgevc.
+     * @returns  Object with:
+     *   - AA: n×n Float64Array, upper quasi-triangular Schur form of A.
+     *   - BB: n×n Float64Array, upper triangular Schur form of B.
+     *   - Q: n×n Float64Array, left orthogonal factor (Q*A*Z = AA).
+     *   - Z: n×n Float64Array, right orthogonal factor.
+     *   - alphar, alphai, beta: Float64Array(n), generalized eigenvalue components.
+     *   - 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): {
+        AA: Float64Array;
+        BB: Float64Array;
+        Q: Float64Array;
+        Z: Float64Array;
+        alphar: Float64Array;
+        alphai: Float64Array;
+        beta: Float64Array;
+        V?: Float64Array;
+        W?: Float64Array;
+    };
+    /**
+     * 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): {
+        AARe: Float64Array;
+        AAIm: Float64Array;
+        BBRe: Float64Array;
+        BBIm: Float64Array;
+        QRe: Float64Array;
+        QIm: Float64Array;
+        ZRe: Float64Array;
+        ZIm: Float64Array;
+        alphaRe: Float64Array;
+        alphaIm: Float64Array;
+        betaRe: Float64Array;
+        betaIm: Float64Array;
+        VRe?: Float64Array;
+        VIm?: Float64Array;
+        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.
+     * @param A       Column-major Float64Array of length n*n (not modified).
+     * @param n       System dimension.
+     * @param b       Right-hand side Float64Array of length n.
+     * @param restart Inner iterations per restart cycle (use n for no restart).
+     * @param tol     Convergence tolerance on relative preconditioned residual.
+     * @param maxit   Maximum number of outer iterations.
+     * @param M1      Preconditioner factor 1 (n×n column-major), or null.
+     * @param M2      Preconditioner factor 2 (n×n column-major), or null.
+     * @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): {
+        x: Float64Array;
+        flag: number;
+        relres: number;
+        iter: Int32Array;
+        resvec: Float64Array;
+    };
+    /**
+     * 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): {
+        xRe: Float64Array;
+        xIm: Float64Array;
+        flag: number;
+        relres: number;
+        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;
+    /** Real scalar-tensor binary elemwise. */
+    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;
+    /** 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;
+    /** Real unary elemwise: out[i] = OP(a[i]). op codes per OpUnary. */
+    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;
+    /** Complex absolute value (real-valued output). aIm may be null. */
+    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;
+    /** Real scalar-tensor comparison. */
+    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;
+    /** Complex scalar-tensor comparison. */
+    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;
+    /** 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Dump op-code enum values as a stable string (drift detection). */
+    tensorOpDumpCodes?(): string;
+}
+export declare function setLapackBridge(bridge: LapackBridge): void;
+export declare function getLapackBridge(): LapackBridge | null;

package/dist-browser/numbl-core/native/qhull-browser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser/worker loader for the qhull WASM Delaunay backend.
+ *
+ * The CLI installs the backend in cli.ts (reading the `.wasm` from disk). In
+ * the browser there is no filesystem, so we let Vite emit the `.wasm` as an
+ * asset (`?url`), fetch its bytes, and pass them to the emscripten module as
+ * `wasmBinary` — this avoids relying on the glue locating the binary next to
+ * itself at runtime.
+ *
+ * `ensureQhullBackend()` is idempotent and best-effort: on any failure it
+ * resolves anyway (so it never crashes the worker), but then no backend is
+ * installed and a later `delaunay`/`delaunayn` call throws (see geometry.ts).
+ */
+/** Load and install the qhull backend (once). Safe to await before every run. */
+export declare function ensureQhullBackend(): Promise<void>;

package/dist-browser/numbl-core/native/qhull-node.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Node loader for the qhull WASM Delaunay backend.
+ *
+ * In Node the emscripten module reads its `.wasm` from disk on its own, so no
+ * asset wiring is needed (unlike the browser; see qhull-browser.ts). This is
+ * used by the CLI, the vitest setup, and is re-exported from the library entry
+ * (lib.ts) so programmatic consumers can install the backend before calling
+ * `delaunay` / `delaunayn`.
+ *
+ * Idempotent: the first call starts loading and caches the promise.
+ */
+/** Load the qhull WASM module and install it as the Delaunay backend (once). */
+export declare function loadQhullNodeBackend(): Promise<void>;

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

@@ -0,0 +1,9 @@
+/**
+ * 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).
+ */
+import type { LapackBridge } from "./lapack-bridge.js";
+export declare function getTsLapackBridge(): LapackBridge;

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

@@ -0,0 +1,32 @@
+/**
+ * Pure-TypeScript complex non-symmetric eigensolver — a zgeev-equivalent for
+ * the ts-lapack bridge (browser path, no native LAPACK addon).
+ *
+ * Ported from the netlib LAPACK reference (zgeev → zgehd2 / zunghr → zlahqr →
+ * ztrevc). Simplifications relative to zgeev, valid for the well-scaled inputs
+ * numbl produces (the acceptance bar is residual-based, A*V≈V*D / W^H*A≈D*W^H,
+ * not bit-matching MKL):
+ *   - No balancing (zgebal/zgebak) — ILO=1, IHI=N.
+ *   - No norm scaling (zlascl).
+ *   - Eigenvector back-substitution uses plain triangular solves with the
+ *     ztrevc SMIN diagonal regularization, instead of the overflow-safe zlatrs.
+ *
+ * Eigenvectors are normalized to unit Euclidean norm with the largest-magnitude
+ * component made real (the documented zgeev convention).
+ *
+ * All matrices are column-major with leading dimension n, split into parallel
+ * real/imag Float64Arrays — matching the bridge's eigComplex I/O shape.
+ */
+/**
+ * Complex eigendecomposition (zgeev-equivalent). Matches the LapackBridge
+ * eigComplex contract: column-major real/imag inputs, returns eigenvalues and
+ * (optionally) left/right eigenvectors.
+ */
+export declare function eigComplexTs(dataRe: Float64Array, dataIm: Float64Array, n: number, computeVL: boolean, computeVR: boolean): {
+    wRe: Float64Array;
+    wIm: Float64Array;
+    VLRe?: Float64Array;
+    VLIm?: Float64Array;
+    VRRe?: Float64Array;
+    VRIm?: Float64Array;
+};

package/dist-browser/numbl-core/ops/bessel.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure-TS implementation of Bessel tensor ops.
+ * Mirrors native/ops/bessel.c — fallback when the native addon is unavailable.
+ *
+ * Delegates the per-element math to src/numbl-core/helpers/bessel.ts so both
+ * the scalar interpreter path and the tensor path share the same algorithm.
+ */
+/**
+ * out[i] = bessel<OP>(nu, z[i]).  scale mirrors the behavior of numbl_bessel_real.
+ */
+export declare function tsBesselReal(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+/**
+ * Hankel function for real z:
+ *   kKind=1 → out[i] = J_nu(z[i]) + i * Y_nu(z[i])
+ *   kKind=2 → out[i] = J_nu(z[i]) - i * Y_nu(z[i])
+ * scaled=1 multiplies by exp(-i*z) (k=1) or exp(+i*z) (k=2).
+ */
+export declare function tsBesselH(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;

package/dist-browser/numbl-core/ops/comparison.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pure-TS implementation of comparison ops.
+ * Mirrors native/ops/comparison.c.
+ *
+ * Output is 0.0 / 1.0 stored in a Float64Array (numbl's logical-tensor
+ * convention — caller wraps the result with _isLogical = true).
+ */
+export declare function tsRealComparison(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+export declare function tsRealScalarComparison(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+export declare function tsComplexComparison(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+export declare function tsComplexScalarComparison(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;

package/dist-browser/numbl-core/ops/complexBinaryElemwise.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pure-TS implementation of complex binary element-wise ops, split storage.
+ * Mirrors native/ops/complex_binary_elemwise.c.
+ *
+ * Caller-allocated input/output buffers; never copies.
+ * aIm/bIm/arrIm may be null → treat as zero.
+ * outIm is always required (caller allocates even if result might be real).
+ */
+export declare function tsComplexBinaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+export declare function tsComplexScalarBinaryElemwise(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;

package/dist-browser/numbl-core/ops/complexUnaryElemwise.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure-TS implementation of complex unary element-wise ops, split storage.
+ * Mirrors native/ops/complex_unary_elemwise.c.
+ *
+ * ABS is intentionally unsupported (use tsComplexAbs — real-valued output).
+ */
+export declare function tsComplexUnaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+export declare function tsComplexAbs(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;

package/dist-browser/numbl-core/ops/dispatch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tensor-ops dispatcher: chooses native bridge or pure-TS fallback.
+ *
+ * All entry points have identical signatures across native and TS impls.
+ * Caller owns input AND output memory; functions never allocate output.
+ *
+ * Selection happens once on first use per category and is cached
+ * (the bridge identity is captured at module load via getLapackBridge()).
+ */
+export declare const tensorOps: {
+    realBinaryElemwise(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    realScalarBinaryElemwise(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    complexBinaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    complexScalarBinaryElemwise(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;
+    realUnaryElemwise(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    complexUnaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    complexAbs(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;
+    realComparison(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    realScalarComparison(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    complexComparison(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+    complexScalarComparison(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;
+    realFlatReduce(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    complexFlatReduce(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;
+    besselReal(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+    besselH(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;
+};

package/dist-browser/numbl-core/ops/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tensor-ops layer: pointer-based, op-code dispatched, native + TS parity.
+ *
+ * Every op has identical signatures across native (C) and TS implementations.
+ * Caller owns input AND output memory; ops never allocate output.
+ */
+export { tensorOps } from "./dispatch.js";
+export { OpRealBin, OpComplexBin, OpUnary, OpCmp, OpReduce, OpBessel, } from "./opCodes.js";