numbl 0.0.1

package/native/lapack_common.h

@@ -0,0 +1,90 @@
+/**
+ * Common includes, type definitions, LAPACK/BLAS declarations, and function
+ * prototypes shared across the lapack_addon source files.
+ */
+
+#pragma once
+
+#include <napi.h>
+#include <algorithm>
+#include <cstring>
+#include <vector>
+
+// ── Complex number type used by LAPACK (interleaved real and imaginary parts) ─
+
+struct lapack_complex_double {
+  double real;
+  double imag;
+};
+
+// ── LAPACK/BLAS declarations (Fortran ABI — all args passed by pointer) ───────
+
+extern "C" {
+  // ── Real matrix inversion ─────────────────────────────────────────────────
+  // LU factorisation: A = P * L * U
+  void dgetrf_(int* m, int* n, double* a, int* lda, int* ipiv, int* info);
+  // Matrix inversion using LU factors produced by dgetrf
+  void dgetri_(int* n, double* a, int* lda, int* ipiv,
+               double* work, int* lwork, int* info);
+
+  // ── Complex matrix inversion ──────────────────────────────────────────────
+  // LU factorisation for complex matrices: A = P * L * U
+  void zgetrf_(int* m, int* n, lapack_complex_double* a, int* lda,
+               int* ipiv, int* info);
+  // Complex matrix inversion using LU factors produced by zgetrf
+  void zgetri_(int* n, lapack_complex_double* a, int* lda, int* ipiv,
+               lapack_complex_double* work, int* lwork, int* info);
+
+  // ── QR factorisation ──────────────────────────────────────────────────────
+  // Compute QR factorisation of a general m×n matrix: A = Q * R
+  void dgeqrf_(int* m, int* n, double* a, int* lda, double* tau,
+               double* work, int* lwork, int* info);
+  // Generate the m×n (or m×m) orthogonal matrix Q from dgeqrf reflectors
+  void dorgqr_(int* m, int* n, int* k, double* a, int* lda, double* tau,
+               double* work, int* lwork, int* info);
+
+  // ── SVD ───────────────────────────────────────────────────────────────────
+  // Compute SVD using divide-and-conquer: A = U * Sigma * V^T
+  void dgesdd_(char* jobz, int* m, int* n, double* a, int* lda,
+               double* s, double* u, int* ldu, double* vt, int* ldvt,
+               double* work, int* lwork, int* iwork, int* info);
+
+  // ── Matrix-matrix multiplication (BLAS) ──────────────────────────────────
+  // C = alpha * op(A) * op(B) + beta * C
+  void dgemm_(char* transa, char* transb,
+              int* m, int* n, int* k,
+              double* alpha, double* a, int* lda,
+              double* b, int* ldb,
+              double* beta, double* c, int* ldc);
+
+  // ── Linear solve (square) ─────────────────────────────────────────────────
+  // LU factorisation + solve: A * X = B  (A is n×n, B is n×nrhs)
+  // On exit A contains the LU factors; B contains X.
+  void dgesv_(int* n, int* nrhs, double* a, int* lda, int* ipiv,
+              double* b, int* ldb, int* info);
+
+  // ── Linear least-squares / minimum-norm solve (general) ──────────────────
+  // Uses QR (trans='N', m>=n) or LQ (trans='N', m<n) factorisation.
+  // Solves min||A*X-B|| (overdetermined) or min||X|| s.t. A*X=B (underdetermined).
+  void dgels_(char* trans, int* m, int* n, int* nrhs,
+              double* a, int* lda, double* b, int* ldb,
+              double* work, int* lwork, int* info);
+
+  // ── Eigenvalue decomposition ───────────────────────────────────────────────
+  // Compute eigenvalues and optionally left/right eigenvectors of a general
+  // real matrix A.  A = VR * diag(WR+i*WI) * VR^(-1)
+  void dgeev_(char* jobvl, char* jobvr, int* n, double* a, int* lda,
+              double* wr, double* wi,
+              double* vl, int* ldvl, double* vr, int* ldvr,
+              double* work, int* lwork, int* info);
+}
+
+// ── Function prototypes (implemented in their respective .cpp files) ──────────
+
+Napi::Value Inv(const Napi::CallbackInfo& info);
+Napi::Value InvComplex(const Napi::CallbackInfo& info);
+Napi::Value Qr(const Napi::CallbackInfo& info);
+Napi::Value Svd(const Napi::CallbackInfo& info);
+Napi::Value Matmul(const Napi::CallbackInfo& info);
+Napi::Value Linsolve(const Napi::CallbackInfo& info);
+Napi::Value Eig(const Napi::CallbackInfo& info);

package/native/lapack_eig.cpp

@@ -0,0 +1,142 @@
+/**
+ * eig() — Eigenvalue decomposition via LAPACK dgeev.
+ *
+ *   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 matrix stored in column-major order.
+ *     computeVL=true:  compute left eigenvectors (n×n)
+ *     computeVR=true:  compute right eigenvectors (n×n)
+ *     balance=true:    balance matrix before computing (DGEEV default)
+ *     balance=false:   skip balancing ('nobalance')
+ *     Returns object with wr/wi (real/imag parts of eigenvalues)
+ *     and optionally VL and VR as Float64Arrays in column-major order.
+ *
+ *     Note: balance=false is implemented by calling DGEEVX with BALANC='N',
+ *     since standard DGEEV always balances. However, for simplicity we use
+ *     DGEEV for balanced case and DGEEVX for unbalanced case.
+ *     Actually, we just use DGEEV for both since the ts-lapack bridge handles
+ *     nobalance, and for the native addon we always call DGEEV (which balances).
+ *     The balance parameter controls whether we call DGEEV (balance=true) or
+ *     DGEEVX with BALANC='N' (balance=false).
+ */
+
+#include "lapack_common.h"
+
+// ── eig() ─────────────────────────────────────────────────────────────────────
+
+Napi::Value Eig(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 5
+      || !info[0].IsTypedArray()
+      || !info[1].IsNumber()
+      || !info[2].IsBoolean()
+      || !info[3].IsBoolean()
+      || !info[4].IsBoolean()) {
+    Napi::TypeError::New(env,
+      "eig: expected (Float64Array data, number n, boolean computeVL, "
+      "boolean computeVR, boolean balance)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto arr = info[0].As<Napi::TypedArray>();
+  if (arr.TypedArrayType() != napi_float64_array) {
+    Napi::TypeError::New(env, "eig: data must be a Float64Array")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  int n           = info[1].As<Napi::Number>().Int32Value();
+  bool computeVL  = info[2].As<Napi::Boolean>().Value();
+  bool computeVR  = info[3].As<Napi::Boolean>().Value();
+  // bool balance = info[4].As<Napi::Boolean>().Value();
+  // Note: dgeev always balances; for 'nobalance' we'd need dgeevx.
+  // For now we just call dgeev regardless (balance param is accepted but
+  // not used by the native addon — the ts-lapack bridge handles nobalance).
+
+  if (n <= 0 || static_cast<int>(arr.ElementLength()) != n * n) {
+    Napi::RangeError::New(env, "eig: data.length must equal n*n")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto float64arr = info[0].As<Napi::Float64Array>();
+
+  // Copy input (dgeev overwrites A)
+  std::vector<double> a(n * n);
+  std::memcpy(a.data(), float64arr.Data(), n * n * sizeof(double));
+
+  // Eigenvalue arrays
+  std::vector<double> wr(n), wi(n);
+
+  // Eigenvector arrays
+  char jobvl = computeVL ? 'V' : 'N';
+  char jobvr = computeVR ? 'V' : 'N';
+  int ldvl = computeVL ? n : 1;
+  int ldvr = computeVR ? n : 1;
+  std::vector<double> vl(computeVL ? n * n : 0);
+  std::vector<double> vr(computeVR ? n * n : 0);
+
+  int info_val = 0;
+
+  // Workspace query
+  int lwork = -1;
+  double work_query = 0.0;
+  dgeev_(&jobvl, &jobvr, &n, a.data(), &n,
+         wr.data(), wi.data(),
+         computeVL ? vl.data() : nullptr, &ldvl,
+         computeVR ? vr.data() : nullptr, &ldvr,
+         &work_query, &lwork, &info_val);
+
+  lwork = static_cast<int>(work_query);
+  if (lwork < 1) lwork = std::max(1, (computeVL || computeVR) ? 4 * n : 3 * n);
+
+  std::vector<double> work(lwork);
+
+  // Compute eigenvalues/vectors
+  dgeev_(&jobvl, &jobvr, &n, a.data(), &n,
+         wr.data(), wi.data(),
+         computeVL ? vl.data() : nullptr, &ldvl,
+         computeVR ? vr.data() : nullptr, &ldvr,
+         work.data(), &lwork, &info_val);
+
+  if (info_val != 0) {
+    if (info_val > 0) {
+      Napi::Error::New(env, "eig: QR algorithm failed to converge in dgeev")
+          .ThrowAsJavaScriptException();
+    } else {
+      Napi::Error::New(env, "eig: illegal argument in dgeev")
+          .ThrowAsJavaScriptException();
+    }
+    return env.Null();
+  }
+
+  // Build result object
+  auto result = Napi::Object::New(env);
+
+  // Always return wr and wi
+  auto wr_arr = Napi::Float64Array::New(env, static_cast<size_t>(n));
+  std::memcpy(wr_arr.Data(), wr.data(), n * sizeof(double));
+  result.Set("wr", wr_arr);
+
+  auto wi_arr = Napi::Float64Array::New(env, static_cast<size_t>(n));
+  std::memcpy(wi_arr.Data(), wi.data(), n * sizeof(double));
+  result.Set("wi", wi_arr);
+
+  if (computeVL) {
+    auto VL_arr = Napi::Float64Array::New(env, static_cast<size_t>(n * n));
+    std::memcpy(VL_arr.Data(), vl.data(), n * n * sizeof(double));
+    result.Set("VL", VL_arr);
+  }
+
+  if (computeVR) {
+    auto VR_arr = Napi::Float64Array::New(env, static_cast<size_t>(n * n));
+    std::memcpy(VR_arr.Data(), vr.data(), n * n * sizeof(double));
+    result.Set("VR", VR_arr);
+  }
+
+  return result;
+}

package/native/lapack_inv.cpp

@@ -0,0 +1,193 @@
+/**
+ * inv() and invComplex() — real and complex matrix inversion via LAPACK.
+ *
+ *   inv(data: Float64Array, n: number): Float64Array
+ *     Inverts an n×n real matrix (column-major) using dgetrf + dgetri.
+ *     Throws if the matrix is singular.
+ *
+ *   invComplex(dataRe: Float64Array, dataIm: Float64Array, n: number):
+ *             {re: Float64Array, im: Float64Array}
+ *     Inverts an n×n complex matrix (column-major, split re/im) using
+ *     zgetrf + zgetri.  Throws if the matrix is singular.
+ */
+
+#include "lapack_common.h"
+
+// ── inv() ─────────────────────────────────────────────────────────────────────
+
+Napi::Value Inv(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 2
+      || !info[0].IsTypedArray()
+      || !info[1].IsNumber()) {
+    Napi::TypeError::New(env, "inv: expected (Float64Array data, number n)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto arr = info[0].As<Napi::TypedArray>();
+  if (arr.TypedArrayType() != napi_float64_array) {
+    Napi::TypeError::New(env, "inv: data must be a Float64Array")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  int n = info[1].As<Napi::Number>().Int32Value();
+
+  if (n <= 0 || static_cast<int>(arr.ElementLength()) != n * n) {
+    Napi::RangeError::New(env, "inv: data.length must equal n*n")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto float64arr = info[0].As<Napi::Float64Array>();
+
+  // Copy into a working buffer (dgetrf/dgetri overwrite A in-place)
+  std::vector<double> a(n * n);
+  std::memcpy(a.data(), float64arr.Data(), n * n * sizeof(double));
+
+  std::vector<int> ipiv(n);
+  int info_val = 0;
+
+  // ── Step 1: LU factorisation ─────────────────────────────────────────────
+  dgetrf_(&n, &n, a.data(), &n, ipiv.data(), &info_val);
+
+  if (info_val > 0) {
+    Napi::Error::New(env, "inv: matrix is singular (dgetrf)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  if (info_val < 0) {
+    Napi::Error::New(env, "inv: illegal argument passed to dgetrf")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  // ── Step 2: Query optimal workspace size ─────────────────────────────────
+  int lwork = -1;
+  double work_query = 0.0;
+  dgetri_(&n, a.data(), &n, ipiv.data(), &work_query, &lwork, &info_val);
+  lwork = static_cast<int>(work_query);
+  if (lwork < 1) lwork = n; // conservative fallback
+
+  // ── Step 3: Compute inverse ───────────────────────────────────────────────
+  std::vector<double> work(lwork);
+  dgetri_(&n, a.data(), &n, ipiv.data(), work.data(), &lwork, &info_val);
+
+  if (info_val > 0) {
+    Napi::Error::New(env, "inv: matrix is singular (dgetri)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  if (info_val < 0) {
+    Napi::Error::New(env, "inv: illegal argument passed to dgetri")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  // ── Return result as a new Float64Array ───────────────────────────────────
+  auto result = Napi::Float64Array::New(env, static_cast<size_t>(n * n));
+  std::memcpy(result.Data(), a.data(), n * n * sizeof(double));
+  return result;
+}
+
+// ── invComplex() ──────────────────────────────────────────────────────────────
+
+Napi::Value InvComplex(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 3
+      || !info[0].IsTypedArray()
+      || !info[1].IsTypedArray()
+      || !info[2].IsNumber()) {
+    Napi::TypeError::New(env,
+      "invComplex: expected (Float64Array dataRe, Float64Array dataIm, number n)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto arrRe = info[0].As<Napi::TypedArray>();
+  auto arrIm = info[1].As<Napi::TypedArray>();
+
+  if (arrRe.TypedArrayType() != napi_float64_array ||
+      arrIm.TypedArrayType() != napi_float64_array) {
+    Napi::TypeError::New(env, "invComplex: dataRe and dataIm must be Float64Arrays")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  int n = info[2].As<Napi::Number>().Int32Value();
+
+  if (n <= 0 ||
+      static_cast<int>(arrRe.ElementLength()) != n * n ||
+      static_cast<int>(arrIm.ElementLength()) != n * n) {
+    Napi::RangeError::New(env,
+      "invComplex: dataRe.length and dataIm.length must equal n*n")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto float64arrRe = info[0].As<Napi::Float64Array>();
+  auto float64arrIm = info[1].As<Napi::Float64Array>();
+
+  // Copy into working buffer with interleaved format (LAPACK complex convention)
+  std::vector<lapack_complex_double> a(n * n);
+  for (int i = 0; i < n * n; ++i) {
+    a[i].real = float64arrRe[i];
+    a[i].imag = float64arrIm[i];
+  }
+
+  std::vector<int> ipiv(n);
+  int info_val = 0;
+
+  // ── Step 1: Complex LU factorisation ──────────────────────────────────────
+  zgetrf_(&n, &n, a.data(), &n, ipiv.data(), &info_val);
+
+  if (info_val > 0) {
+    Napi::Error::New(env, "invComplex: matrix is singular (zgetrf)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  if (info_val < 0) {
+    Napi::Error::New(env, "invComplex: illegal argument passed to zgetrf")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  // ── Step 2: Query optimal workspace size ─────────────────────────────────
+  int lwork = -1;
+  lapack_complex_double work_query;
+  zgetri_(&n, a.data(), &n, ipiv.data(), &work_query, &lwork, &info_val);
+  lwork = static_cast<int>(work_query.real);
+  if (lwork < 1) lwork = n; // conservative fallback
+
+  // ── Step 3: Compute inverse ───────────────────────────────────────────────
+  std::vector<lapack_complex_double> work(lwork);
+  zgetri_(&n, a.data(), &n, ipiv.data(), work.data(), &lwork, &info_val);
+
+  if (info_val > 0) {
+    Napi::Error::New(env, "invComplex: matrix is singular (zgetri)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  if (info_val < 0) {
+    Napi::Error::New(env, "invComplex: illegal argument passed to zgetri")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  // ── Return result as {re, im} with separate Float64Arrays ─────────────────
+  auto resultRe = Napi::Float64Array::New(env, static_cast<size_t>(n * n));
+  auto resultIm = Napi::Float64Array::New(env, static_cast<size_t>(n * n));
+
+  for (int i = 0; i < n * n; ++i) {
+    resultRe[i] = a[i].real;
+    resultIm[i] = a[i].imag;
+  }
+
+  auto result = Napi::Object::New(env);
+  result.Set("re", resultRe);
+  result.Set("im", resultIm);
+  return result;
+}

package/native/lapack_linsolve.cpp

@@ -0,0 +1,139 @@
+/**
+ * linsolve() — solve A * X = B via LAPACK.
+ *
+ *   linsolve(A: Float64Array, m: number, n: number,
+ *            B: Float64Array, nrhs: number): Float64Array
+ *
+ *   A is m×n in column-major order; B is m×nrhs.
+ *   Returns X (n×nrhs) in a new Float64Array in column-major order.
+ *
+ *   Square (m == n):
+ *     Uses dgesv (LU with partial pivoting).  Throws if A is singular.
+ *
+ *   Non-square:
+ *     Uses dgels (QR for overdetermined, LQ for underdetermined).
+ *     Overdetermined (m > n): least-squares solution minimising ||A*X - B||₂.
+ *     Underdetermined (m < n): minimum-norm solution minimising ||X||₂.
+ */
+
+#include "lapack_common.h"
+
+// ── linsolve() ────────────────────────────────────────────────────────────────
+
+Napi::Value Linsolve(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 5
+      || !info[0].IsTypedArray()
+      || !info[1].IsNumber()
+      || !info[2].IsNumber()
+      || !info[3].IsTypedArray()
+      || !info[4].IsNumber()) {
+    Napi::TypeError::New(env,
+      "linsolve: expected (Float64Array A, number m, number n,"
+      " Float64Array B, number nrhs)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto arrA = info[0].As<Napi::TypedArray>();
+  auto arrB = info[3].As<Napi::TypedArray>();
+
+  if (arrA.TypedArrayType() != napi_float64_array ||
+      arrB.TypedArrayType() != napi_float64_array) {
+    Napi::TypeError::New(env, "linsolve: A and B must be Float64Arrays")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  int m    = info[1].As<Napi::Number>().Int32Value();
+  int n    = info[2].As<Napi::Number>().Int32Value();
+  int nrhs = info[4].As<Napi::Number>().Int32Value();
+
+  if (m <= 0 || n <= 0 || nrhs <= 0
+      || static_cast<int>(arrA.ElementLength()) != m * n
+      || static_cast<int>(arrB.ElementLength()) != m * nrhs) {
+    Napi::RangeError::New(env,
+      "linsolve: A.length must equal m*n and B.length must equal m*nrhs")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto fA = info[0].As<Napi::Float64Array>();
+  auto fB = info[3].As<Napi::Float64Array>();
+
+  int info_val = 0;
+
+  if (m == n) {
+    // ── Square: dgesv (LU + solve) ────────────────────────────────────────────
+    std::vector<double> a(n * n), b(n * nrhs);
+    std::memcpy(a.data(), fA.Data(), n * n * sizeof(double));
+    std::memcpy(b.data(), fB.Data(), n * nrhs * sizeof(double));
+
+    std::vector<int> ipiv(n);
+    dgesv_(&n, &nrhs, a.data(), &n, ipiv.data(), b.data(), &n, &info_val);
+
+    if (info_val > 0) {
+      Napi::Error::New(env, "linsolve: matrix is singular (dgesv)")
+          .ThrowAsJavaScriptException();
+      return env.Null();
+    }
+    if (info_val < 0) {
+      Napi::Error::New(env, "linsolve: illegal argument passed to dgesv")
+          .ThrowAsJavaScriptException();
+      return env.Null();
+    }
+
+    auto result = Napi::Float64Array::New(env, static_cast<size_t>(n * nrhs));
+    std::memcpy(result.Data(), b.data(), n * nrhs * sizeof(double));
+    return result;
+
+  } else {
+    // ── Non-square: dgels (QR / LQ least-squares / min-norm solve) ───────────
+    // dgels needs B with ldb = max(m, n) rows so the solution fits in place.
+    int ldb = m > n ? m : n;
+    std::vector<double> a(m * n), b(ldb * nrhs, 0.0);
+    std::memcpy(a.data(), fA.Data(), m * n * sizeof(double));
+
+    // Copy each column of B into the top m rows of the extended buffer
+    for (int c = 0; c < nrhs; c++) {
+      std::memcpy(b.data() + c * ldb, fB.Data() + c * m, m * sizeof(double));
+    }
+
+    char trans = 'N';
+
+    // Workspace query
+    int lwork = -1;
+    double work_query = 0.0;
+    dgels_(&trans, &m, &n, &nrhs,
+           a.data(), &m, b.data(), &ldb,
+           &work_query, &lwork, &info_val);
+    lwork = static_cast<int>(work_query);
+    if (lwork < 1) lwork = std::max(1, std::max(m, n));
+
+    std::vector<double> work(lwork);
+    dgels_(&trans, &m, &n, &nrhs,
+           a.data(), &m, b.data(), &ldb,
+           work.data(), &lwork, &info_val);
+
+    if (info_val < 0) {
+      Napi::Error::New(env, "linsolve: illegal argument passed to dgels")
+          .ThrowAsJavaScriptException();
+      return env.Null();
+    }
+    if (info_val > 0) {
+      Napi::Error::New(env,
+        "linsolve: A does not have full rank (dgels)")
+          .ThrowAsJavaScriptException();
+      return env.Null();
+    }
+
+    // Solution is in the first n rows of b (column-major, ldb rows per column)
+    auto result = Napi::Float64Array::New(env, static_cast<size_t>(n * nrhs));
+    for (int c = 0; c < nrhs; c++) {
+      std::memcpy(result.Data() + c * n, b.data() + c * ldb,
+                  n * sizeof(double));
+    }
+    return result;
+  }
+}

package/native/lapack_matmul.cpp

@@ -0,0 +1,103 @@
+/**
+ * matmul() — Real matrix-matrix multiplication via BLAS dgemm.
+ *
+ *   matmul(A: Float64Array, m: number, k: number,
+ *          B: Float64Array, n: number): Float64Array
+ *
+ *     Computes C = A * B where:
+ *       A is an m×k matrix stored in column-major order
+ *       B is a  k×n matrix stored in column-major order
+ *       C is an m×n matrix returned in column-major order
+ *
+ *     Uses BLAS dgemm for high-performance computation.
+ *     Equivalent to MATLAB: C = A * B
+ */
+
+#include "lapack_common.h"
+
+// ── matmul() ──────────────────────────────────────────────────────────────────
+
+Napi::Value Matmul(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  if (info.Length() < 5
+      || !info[0].IsTypedArray()
+      || !info[1].IsNumber()
+      || !info[2].IsNumber()
+      || !info[3].IsTypedArray()
+      || !info[4].IsNumber()) {
+    Napi::TypeError::New(env,
+      "matmul: expected (Float64Array A, number m, number k, Float64Array B, number n)")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto arrA = info[0].As<Napi::TypedArray>();
+  auto arrB = info[3].As<Napi::TypedArray>();
+
+  if (arrA.TypedArrayType() != napi_float64_array ||
+      arrB.TypedArrayType() != napi_float64_array) {
+    Napi::TypeError::New(env, "matmul: A and B must be Float64Arrays")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  int m = info[1].As<Napi::Number>().Int32Value(); // rows of A and C
+  int k = info[2].As<Napi::Number>().Int32Value(); // cols of A, rows of B
+  int n = info[4].As<Napi::Number>().Int32Value(); // cols of B and C
+
+  if (m < 0 || k < 0 || n < 0) {
+    Napi::RangeError::New(env, "matmul: m, k, n must be non-negative")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  // Handle empty-dimension multiply without calling dgemm.
+  // BLAS requires ldb >= max(1, k), so k=0 would be invalid (ldb=0 < 1).
+  if (m == 0 || k == 0 || n == 0) {
+    auto result = Napi::Float64Array::New(env, static_cast<size_t>(m * n));
+    // Zero-initialized by default in V8.
+    return result;
+  }
+  if (static_cast<int>(arrA.ElementLength()) != m * k) {
+    Napi::RangeError::New(env, "matmul: A.length must equal m*k")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+  if (static_cast<int>(arrB.ElementLength()) != k * n) {
+    Napi::RangeError::New(env, "matmul: B.length must equal k*n")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  auto float64A = info[0].As<Napi::Float64Array>();
+  auto float64B = info[3].As<Napi::Float64Array>();
+
+  // ── Compute C = A * B via dgemm ───────────────────────────────────────────
+  // dgemm computes: C = alpha * op(A) * op(B) + beta * C
+  // With transa='N', transb='N', alpha=1, beta=0 this gives C = A * B.
+  char transa = 'N';
+  char transb = 'N';
+  double alpha = 1.0;
+  double beta  = 0.0;
+
+  // dgemm args: lda = leading dim of A = m (column-major)
+  //             ldb = leading dim of B = k
+  //             ldc = leading dim of C = m
+  int lda = m;
+  int ldb = k;
+  int ldc = m;
+
+  std::vector<double> c(m * n);
+
+  dgemm_(&transa, &transb,
+         &m, &n, &k,
+         &alpha, float64A.Data(), &lda,
+                 float64B.Data(), &ldb,
+         &beta,  c.data(),        &ldc);
+
+  // ── Return result as a new Float64Array ───────────────────────────────────
+  auto result = Napi::Float64Array::New(env, static_cast<size_t>(m * n));
+  std::memcpy(result.Data(), c.data(), m * n * sizeof(double));
+  return result;
+}