numbl 0.4.11 → 0.4.13

package/dist-lib/numbl-core/fileIOAdapter.d.ts

@@ -73,6 +73,10 @@ export interface FileIOAdapter {
     fileattrib?(path: string): FileAttribInfo | null;
     /** Extract a ZIP file to an output folder. Returns list of extracted file paths. Optional. */
     unzip?(zipfilename: string, outputfolder: string): string[];
+    /** Create a ZIP file from files/folders (paths resolved relative to
+     *  rootDir; folders are added recursively; simple globs in the last
+     *  path component are expanded). Returns the entry names written. Optional. */
+    zip?(zipfilename: string, filenames: string[], rootDir: string): string[];
     /** Return the temporary directory path. Optional. */
     tempdir?(): string;
     /** Return the numbl user/config directory path. Optional. */

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

@@ -29,7 +29,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.

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

@@ -0,0 +1,114 @@
+/**
+ * Optional WASM linear-algebra accelerator bridge.
+ *
+ * numbl can offload heavy LAPACK/BLAS kernels to an externally-hosted
+ * WebAssembly module (e.g. libFLAME/BLIS compiled to wasm, served from
+ * GitHub Pages). This is the *platform-agnostic core*: it operates on an
+ * already-instantiated wasm `exports` object, so it has no `fetch` /
+ * `WebAssembly.instantiate` dependency and runs identically under Node and
+ * the browser. The browser worker owns the fetch + instantiate step and
+ * hands the exports here (see the browser loader); Node bundling can reuse
+ * the same functions later.
+ *
+ * Two seams are installed from one instantiated module (see
+ * `installWasmLapackBridge`):
+ *   1. `setLapackBridge()` — covers the *interpreter* path (opt 0), which
+ *      already resolves per-op via `getEffectiveBridge` and falls back to
+ *      ts-lapack for any op the bridge omits.
+ *   2. `globalThis.$matmulAccel` — the hook the JS-JIT matmul runtime
+ *      snippet consults (opt 1, the browser IDE default), which otherwise
+ *      runs a naive JS triple-loop that never touches the bridge.
+ *
+ * Trust model: numbl instantiates only the module's *wasm* (never remote
+ * JS) with a numbl-controlled import object, and does all marshaling here,
+ * so the accelerator is sandboxed — it cannot reach the DOM or network.
+ *
+ * v1 exposes real f64 `matmul` only. The ABI and manifest are versioned so
+ * more ops (svd/qr/lu/…) can be added without breaking older endpoints.
+ */
+import { type LapackBridge } from "./lapack-bridge.js";
+/** Bumped when the wasm ABI (export names / signatures) changes
+ *  incompatibly. An endpoint manifest must advertise the same major. */
+export declare const ACCELERATOR_ABI = 1;
+/** Below this many multiply-adds (`m*n*k`) the JS loop beats the cost of
+ *  marshaling into and out of the wasm heap, so the accelerator declines
+ *  and the caller uses its own loop. Tuned conservatively; small matmuls
+ *  dominate typical MATLAB code and should never pay the copy tax. */
+export declare const WASM_MATMUL_MIN_WORK = 100000;
+/** Manifest served alongside the wasm (`numbl-bridge.json`). Describes
+ *  which ops/precisions the endpoint provides so numbl can negotiate
+ *  capabilities and fall back per-op for anything absent. */
+export interface AcceleratorManifest {
+    /** Wasm ABI major version. Must equal `ACCELERATOR_ABI` to load. */
+    abi: number;
+    /** Human-readable endpoint name (for diagnostics). */
+    name?: string;
+    /** Whether the module uses wasm threads (SharedArrayBuffer). v1: false. */
+    threads?: boolean;
+    /** Advertised operations. Only `matmul` is understood in v1. */
+    ops: {
+        matmul?: {
+            precision: string[];
+            complex?: boolean;
+        };
+    };
+    /** Wasm binary filename, resolved relative to the manifest URL. */
+    wasm: string;
+}
+/** The subset of a wasm module's exports the v1 ABI requires. A conforming
+ *  module exports its linear `memory`, a bump/allocator pair, and the
+ *  column-major real gemm. All pointers are byte offsets into `memory`. */
+export interface WasmLapackExports {
+    memory: WebAssembly.Memory;
+    numbl_malloc(nbytes: number): number;
+    numbl_free(ptr: number): void;
+    /** C(m×n) = A(m×k) · B(k×n), all column-major f64, in `memory`. */
+    numbl_matmul_f64_colmajor(aPtr: number, bPtr: number, cPtr: number, m: number, k: number, n: number): void;
+}
+/** Signature shared by `LapackBridge.matmul` and the `$matmulAccel` hook. */
+export type MatmulFn = (a: Float64Array, m: number, k: number, b: Float64Array, n: number) => Float64Array;
+/**
+ * Validate a fetched manifest. Returns the typed manifest or throws with a
+ * specific reason (so the loader can log and fall back to ts-lapack).
+ */
+export declare function validateManifest(raw: unknown): AcceleratorManifest;
+/**
+ * Build a real-f64 matmul closure over an instantiated wasm module. Copies
+ * the (column-major) inputs into the wasm heap, runs the kernel, and copies
+ * the result out into a fresh `Float64Array`.
+ *
+ * Memory-growth safe: heap views are constructed *after* every `malloc`
+ * (which may grow and detach `memory.buffer`) and the result view is taken
+ * *after* the kernel call.
+ */
+export declare function makeWasmMatmul(exports: WasmLapackExports): MatmulFn;
+/**
+ * Assemble a (partial) `LapackBridge` from an instantiated module, exposing
+ * only the ops the manifest advertises. Ops the bridge omits resolve to
+ * ts-lapack via `getEffectiveBridge`.
+ */
+export declare function buildLapackBridgeFromWasm(exports: WasmLapackExports, manifest: AcceleratorManifest): LapackBridge;
+/**
+ * Install/remove the JS-JIT matmul accelerator hook (`globalThis.$matmulAccel`)
+ * that `mtoc2_tensor_mtimes_real` consults. Pass `null` to uninstall.
+ */
+export declare function setMatmulAccelerator(fn: ((a: Float64Array, m: number, k: number, b: Float64Array, n: number) => Float64Array | null | undefined) | null): void;
+/** Current matmul accelerator hook, or undefined if none is installed. */
+export declare function getMatmulAccelerator(): ((a: Float64Array, m: number, k: number, b: Float64Array, n: number) => Float64Array | null | undefined) | undefined;
+/**
+ * Install both seams from one instantiated module:
+ *  - registers a partial `LapackBridge` (interpreter / opt 0), and
+ *  - installs the `$matmulAccel` hook (JS-JIT / opt 1) when the module
+ *    provides matmul.
+ *
+ * The `$matmulAccel` wrapper is best-effort: it declines (returns `null`)
+ * for small matmuls and on any error, so the JS loop remains the fallback.
+ * The interpreter-path `bridge.matmul` is NOT wrapped — it propagates
+ * errors like any other bridge (matching native-addon semantics).
+ */
+/** Remove both seams (e.g. when the user disables the accelerator). Leaves
+ *  the interpreter and JS-JIT on ts-lapack / the JS loop. */
+export declare function uninstallWasmLapackBridge(): void;
+export declare function installWasmLapackBridge(exports: WasmLapackExports, manifest: AcceleratorManifest): {
+    matmul: boolean;
+};

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

@@ -0,0 +1,34 @@
+/**
+ * Browser/worker loader for the optional WASM linear-algebra accelerator.
+ *
+ * Mirrors `qhull-browser.ts`: fetch the endpoint's manifest, fetch and
+ * instantiate its wasm, and install it via `installWasmLapackBridge`. numbl
+ * instantiates the wasm itself (no remote JS is executed) with a
+ * numbl-controlled import object, so the accelerator is sandboxed.
+ *
+ * Best-effort: any failure resolves to `false` (nothing installed → the
+ * interpreter/JIT keep using ts-lapack / the JS loop). Idempotent per URL —
+ * a repeat call for the same URL returns the in-flight/settled promise.
+ *
+ * `fetchImpl` / `instantiate` / `cache` are injectable so the whole
+ * orchestration is unit-testable without a wasm toolchain.
+ */
+/** Persistent byte cache (e.g. IndexedDB) for wasm binaries, keyed by URL.
+ *  Optional; failures must be non-fatal. */
+export interface WasmByteCache {
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, bytes: Uint8Array): Promise<void>;
+}
+export interface LoadWasmLapackDeps {
+    fetchImpl?: typeof fetch;
+    /** Instantiate wasm bytes; defaults to `WebAssembly.instantiate`. */
+    instantiate?: (bytes: BufferSource, imports: WebAssembly.Imports) => Promise<WebAssembly.Instance>;
+    cache?: WasmByteCache;
+}
+/**
+ * Ensure the accelerator for `url` is loaded and installed. Pass `null` (or
+ * empty) to uninstall. Returns a promise for whether matmul got installed.
+ */
+export declare function ensureWasmLapackBridge(url: string | null, deps?: LoadWasmLapackDeps): Promise<boolean>;
+/** Test-only: reset the module-level idempotency cache. */
+export declare function _resetWasmLapackLoaderForTests(): void;

package/dist-lib/numbl-core/runtime/datetime-format.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Formatter for datetime `Format` patterns — the Unicode-LDML-style tokens
+ * MATLAB uses (e.g. "yyyy-MM-dd'T'HH:mm:ss'Z'").
+ *
+ * Supported tokens: y/u (year), M (month; MMM abbreviated name, MMMM full
+ * name), d (day of month), H (hour 0–23), h (hour 1–12), m (minute),
+ * s (second), S (fractional-second digits), a (AM/PM). Text between single
+ * quotes is emitted literally; '' is an escaped single quote.
+ */
+export declare function formatDatetimePattern(pattern: string, year: number, month: number, day: number, hour: number, minute: number, second: number): string;

package/dist-lib/numbl-core/runtime/display.d.ts

@@ -1,6 +1,10 @@
 /**
  * Value display/formatting.
  */
-import { type RuntimeValue } from "./types.js";
+import { type RuntimeClassInstance, type RuntimeValue } from "./types.js";
 /** Format a value for display */
 export declare function displayValue(v: RuntimeValue): string;
+/** Format a datetime or duration instance for display / char conversion.
+ *  Returns null when the instance lacks the expected fields (or is some
+ *  other class), letting the generic class-instance display run. */
+export declare function formatDatetimeOrDuration(v: RuntimeClassInstance): string | null;

package/dist-lib/numbl-core/runtime/index.d.ts

@@ -5,7 +5,7 @@ export type { CallFrame } from "./error.js";
 export { tensorSize2D, numel, colMajorIndex } from "./utils.js";
 export { toNumber, toBool, toString } from "./convert.js";
 export { valuesAreEqual } from "./compare.js";
-export { displayValue } from "./display.js";
+export { displayValue, formatDatetimeOrDuration } from "./display.js";
 export { RTV } from "./constructors.js";
 export { mAdd, mSub, mMul, mElemMul, mDiv, mElemDiv, mPow, mElemPow, mNeg, mTranspose, mConjugateTranspose, mEqual, mNotEqual, mLess, mLessEqual, mGreater, mGreaterEqual, } from "../helpers/arithmetic.js";
 export { COLON_INDEX, indexIntoRTValue as mIndex, storeIntoRTValueIndex as mIndexStore, charToNumericTensor, numericTensorToChar, } from "./indexing.js";

package/dist-lib/numbl-core/version.d.ts

@@ -1,2 +1,2 @@
 /** Numbl version, used for JIT disk cache invalidation. */
-export declare const NUMBL_VERSION = "0.4.11";
+export declare const NUMBL_VERSION = "0.4.13";

package/dist-lib/vfs/BrowserFileIOAdapter.d.ts

@@ -43,6 +43,7 @@ export declare class BrowserFileIOAdapter implements FileIOAdapter {
     websave(url: string, filename: string, options?: WebOptions): void;
     webread(url: string, options?: WebOptions): string;
     unzip(zipfilename: string, outputfolder: string): string[];
+    zip(zipfilename: string, filenames: string[], rootDir: string): string[];
     /** Get the VFS changes for syncing back to the main thread. */
     getChanges(): VfsChanges;
     private getEntry;