numbl 0.4.7 → 0.4.9

package/dist-lib/numbl-core/executors/jit/hostHelpers.d.ts

@@ -23,5 +23,9 @@ import type { Runtime } from "../../runtime/runtime.js";
 export interface JitHostHelpers {
     write: (s: string) => void;
     plotDispatch: (name: string, args: unknown[]) => void;
+    /** One uniform double in [0, 1). Backed by numbl's process-global PRNG
+     *  (the same `rngRandom` the interpreter uses), so JIT'd and interpreted
+     *  `rand` draw from one shared, `rng(seed)`-controllable stream. */
+    rand: () => number;
 }
 export declare function buildHostHelpers(rt: Runtime): JitHostHelpers;

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

@@ -15,6 +15,15 @@ export interface WebOptions {
     keyName?: string;
     keyValue?: string;
 }
+/** Subset of MATLAB's fileattrib attribute struct. `Name` is the resolved
+ *  absolute path. */
+export interface FileAttribInfo {
+    Name: string;
+    directory: boolean;
+    UserRead: boolean;
+    UserWrite: boolean;
+    UserExecute: boolean;
+}
 export interface FileIOAdapter {
     /** Open a file, returns an integer file identifier (fid). */
     fopen(filename: string, permission: string): number;
@@ -58,6 +67,10 @@ export interface FileIOAdapter {
     rmdir?(dirPath: string, recursive: boolean): boolean;
     /** Move or rename a file or folder. If force is true, overwrites read-only files. Returns true on success. Optional. */
     movefile?(source: string, destination: string, force: boolean): boolean;
+    /** Copy a file or folder. If force is true, overwrites read-only files. Returns true on success. Optional. */
+    copyfile?(source: string, destination: string, force: boolean): boolean;
+    /** Resolve a file/dir to its absolute path and attributes, or null if it does not exist. Optional. */
+    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[];
     /** Return the temporary directory path. Optional. */

package/dist-lib/numbl-core/helpers/scanFormat.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared scanning core for sscanf/fscanf: apply a MATLAB format string
+ * cyclically to input text, collecting numeric results.
+ */
+export interface ScanResult {
+    results: number[];
+    /** Number of characters consumed from the input. */
+    consumed: number;
+    matchFailure: boolean;
+}
+export declare function scanFormat(str: string, fmt: string, maxCount: number): ScanResult;

package/dist-lib/numbl-core/jit/builtins/defs/logical/fieldnames.d.ts

@@ -2,8 +2,8 @@
  * `fieldnames(s)` — returns an N×1 cell of char-array field names
  * for a struct or class instance. Matches numbl's
  * `introspection.ts:fieldnamesApply` semantics, with the result's
- * cell-element type being `char` (matches MATLAB; numbl wraps as
- * string but mtoc2 follows MATLAB by emitting chars).
+ * cell-element type being `char` (matches MATLAB and the
+ * interpreter, which also emits chars).
  *
  * Interpreter-only for now; the AOT path would need to materialize
  * a heterogeneous-len cell of chars which is a different feature

package/dist-lib/numbl-core/jit/builtins/defs/math/rand.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const rand: Builtin;

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

@@ -0,0 +1,32 @@
+/**
+ * Diagnostic sink for the most recent JIT decline reason.
+ *
+ * When a JIT executor cannot compile a unit it catches the
+ * `UnsupportedConstruct` / `JitTypeError` thrown during lowering/codegen and
+ * declines (returns `null`), letting the dispatcher fall through to the
+ * interpreter. That message is normally lost. We stash the most recent one
+ * here so a failing `%!numbl:assert_jit` can report *why* the unit declined,
+ * not merely that it ran in the interpreter.
+ *
+ * This is a best-effort, process-global "last decline" — when an assert fires,
+ * the unit it guards declined immediately beforehand, so the most recent
+ * recorded reason is the relevant one. It is a diagnostic aid, not a precise
+ * per-unit binding.
+ *
+ * Leaf module: no imports, so it can be shared by the executors
+ * (`executors/jit/*`) and the interpreter (`interpreter/*`) without cycles.
+ */
+export interface JitDecline {
+    /** The thrown error's message (e.g. "unsupported builtin 'rand'"). */
+    message: string;
+    /** Error class name: "UnsupportedConstruct" | "JitTypeError". */
+    kind: string;
+    /** Which executor declined: "jit-top-level" | "jit-call" | "jit-loop". */
+    where: string;
+}
+/** Record a swallowed JIT decline reason (called from executor catch blocks). */
+export declare function recordJitDecline(d: JitDecline): void;
+/** The most recent recorded JIT decline, or null if none seen. */
+export declare function getLastJitDecline(): JitDecline | null;
+/** Forget the last decline (e.g. so an unrelated stale reason isn't reported). */
+export declare function clearJitDecline(): void;

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

@@ -13,6 +13,19 @@
  */
 import type { WorkspaceFile, NativeBridge } from "./workspace/index.js";
 import type { IBuiltin } from "./interpreter/builtins/types.js";
+/**
+ * Per-WASM-instance registry that exposes numbl function handles to WASM as
+ * integer ids. A `.numbl.js` apply registers a JS thunk (closing over a
+ * handle + `callHandle`) with `add()`, passes the returned id into a WASM
+ * export, and removes it once the export returns. Inside WASM the handle is
+ * invoked by calling the host-provided `env.numbl_cb_d(id, x)` import.
+ */
+export interface WasmCallbackRegistry {
+    /** Register a callback thunk; returns its integer id. */
+    add(fn: (...args: number[]) => number): number;
+    /** Drop a previously registered callback. */
+    remove(id: number): void;
+}
 /** A loaded JS user function ready for registration in the workspace. */
 export interface LoadedJsUserFunction {
     name: string;

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

@@ -2,7 +2,7 @@
  * RuntimeValue constructor helpers (the RTV namespace).
  */
 import { ItemType } from "../lowering/itemTypes.js";
-import { type RuntimeNumber, RuntimeTensor, type RuntimeString, RuntimeChar, type RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeClassInstance, RuntimeClassInstanceArray, RuntimeComplexNumber, RuntimeDummyHandle, RuntimeGraphicsHandle, RuntimeStructArray, RuntimeSparseMatrix, RuntimeDictionary, type RuntimeValue } from "./types.js";
+import { type RuntimeNumber, RuntimeTensor, type RuntimeString, RuntimeChar, type RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeClassInstance, RuntimeClassInstanceArray, RuntimeComplexNumber, RuntimeDummyHandle, RuntimeGraphicsHandle, RuntimeStructArray, RuntimeSparseMatrix, RuntimeDictionary, RuntimeStringArray, type RuntimeValue } from "./types.js";
 export declare const RTV: {
     num(value: number): RuntimeNumber;
     tensor(data: Float64Array | number[], shape: number[], imag?: Float64Array | number[]): RuntimeTensor;
@@ -17,6 +17,8 @@ export declare const RTV: {
     /** Create a matrix from row-major data */
     matrix(rows: number, cols: number, data: number[] | Float64Array, imag?: number[] | Float64Array): RuntimeTensor;
     string(value: string): RuntimeString;
+    /** String array (does NOT collapse 1x1 — use stringArrayValue for that). */
+    stringArray(data: string[], shape: [number, number]): RuntimeStringArray;
     char(value: string): RuntimeChar;
     logical(value: boolean): RuntimeLogical;
     cell(data: RuntimeValue[], shape: number[]): RuntimeCell;

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

@@ -18,6 +18,9 @@ export declare function charToNumericTensor(c: RuntimeChar): RuntimeTensor;
 /** Inverse of charToNumericTensor: read a numeric tensor's column-major
  *  data into a row-major char value, rounding codes to integers. */
 export declare function numericTensorToChar(t: RuntimeTensor): RuntimeChar;
+/** Resolve one subscript against a dimension of extent `extent` to 0-based
+ *  positions. Handles colon, scalars, numeric vectors, and logical masks. */
+export declare function stringArraySubscript(idx: RuntimeValue, extent: number): number[];
 /** Index into a value: v(i1, i2, ...) */
 export declare function indexIntoRTValue(base: RuntimeValue, indices: RuntimeValue[]): RuntimeValue;
 /** Store into indexed position: base(indices) = rhs — uses copy-on-write for shared data */

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

@@ -78,6 +78,7 @@ export declare class Runtime {
         col(data: number[], imag?: number[]): RuntimeTensor;
         matrix(rows: number, cols: number, data: number[] | Float64Array, imag?: number[] | Float64Array): RuntimeTensor;
         string(value: string): RuntimeString;
+        stringArray(data: string[], shape: [number, number]): import("../runtime/types.js").RuntimeStringArray;
         char(value: string): RuntimeChar;
         logical(value: boolean): RuntimeLogical;
         cell(data: RuntimeValue[], shape: number[]): RuntimeCell;

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

@@ -1,6 +1,6 @@
 import { Refcounted, type RefcountRuntime } from "./refcount.js";
 export declare const USE_FLOAT32: boolean;
-export type RuntimeValue = number | boolean | string | RuntimeTensor | RuntimeChar | RuntimeCell | RuntimeStruct | RuntimeFunction | RuntimeClassInstance | RuntimeComplexNumber | RuntimeDummyHandle | RuntimeGraphicsHandle | RuntimeStructArray | RuntimeClassInstanceArray | RuntimeSparseMatrix | RuntimeDictionary;
+export type RuntimeValue = number | boolean | string | RuntimeTensor | RuntimeChar | RuntimeCell | RuntimeStruct | RuntimeFunction | RuntimeClassInstance | RuntimeComplexNumber | RuntimeDummyHandle | RuntimeGraphicsHandle | RuntimeStructArray | RuntimeClassInstanceArray | RuntimeSparseMatrix | RuntimeDictionary | RuntimeStringArray;
 export type RuntimeNumber = number;
 export type RuntimeLogical = boolean;
 export type RuntimeString = string;
@@ -20,6 +20,7 @@ export declare const isRuntimeStructArray: (value: RuntimeValue) => value is Run
 export declare const isRuntimeClassInstanceArray: (value: RuntimeValue) => value is RuntimeClassInstanceArray;
 export declare const isRuntimeSparseMatrix: (value: RuntimeValue) => value is RuntimeSparseMatrix;
 export declare const isRuntimeDictionary: (value: RuntimeValue) => value is RuntimeDictionary;
+export declare const isRuntimeStringArray: (value: RuntimeValue) => value is RuntimeStringArray;
 export declare const kstr: (value: RuntimeValue) => string;
 export declare class RuntimeTensor extends Refcounted {
     readonly kind: "tensor";
@@ -40,6 +41,19 @@ export declare class RuntimeChar extends Refcounted {
     shape: number[] | undefined;
     constructor(value: string, shape?: number[]);
 }
+export declare class RuntimeStringArray extends Refcounted {
+    readonly kind: "string_array";
+    /** Elements in column-major order (plain JS strings). */
+    data: string[];
+    /** 2-D shape [rows, cols]; data.length === rows*cols. A 1x1 string is
+     *  normally represented as a primitive JS string, not a 1x1 array —
+     *  use stringArrayValue() to build results so scalars collapse. */
+    shape: [number, number];
+    constructor(data: string[], shape: [number, number]);
+}
+/** Build a string-array result, collapsing 1x1 to the primitive string
+ *  representation used for string scalars throughout the runtime. */
+export declare function stringArrayValue(data: string[], shape: [number, number]): RuntimeValue;
 export declare class RuntimeCell extends Refcounted {
     readonly kind: "cell";
     data: RuntimeValue[];

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

@@ -14,3 +14,6 @@ export declare function colMajorIndex(row: number, col: number, rows: number): n
 export declare function ind2sub(shape: number[], idx: number): number[];
 /** Convert subscripts to linear index (column-major) */
 export declare function sub2ind(shape: number[], subs: number[]): number;
+/** MATLAB num2str/string(double) default formatting: integers exact,
+ *  otherwise 5 significant digits (%.5g with MATLAB exponent padding). */
+export declare function matlabNumToString(n: number): string;

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.7";
+export declare const NUMBL_VERSION = "0.4.9";

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

@@ -0,0 +1,60 @@
+/**
+ * Browser implementation of FileIOAdapter using an in-memory VirtualFileSystem.
+ * Mirrors NodeFileIOAdapter patterns from cli-fileio.ts.
+ */
+import type { FileIOAdapter, WebOptions, FileAttribInfo } from "../numbl-core/fileIOAdapter.js";
+import type { WorkspaceFile } from "../numbl-core/workspace/index.js";
+import { VirtualFileSystem, type VfsChanges } from "./VirtualFileSystem.js";
+export declare class BrowserFileIOAdapter implements FileIOAdapter {
+    private vfs;
+    private nextFid;
+    private openFiles;
+    constructor(vfs: VirtualFileSystem);
+    fopen(filename: string, permission: string): number;
+    fclose(fidOrAll: number | "all"): number;
+    fgetl(fid: number): string | number;
+    fgets(fid: number): string | number;
+    fileread(filename: string): string;
+    feof(fid: number): number;
+    ferror(fid: number): string;
+    fwrite(fid: number, text: string): void;
+    freadBytes(fid: number, count: number): Uint8Array;
+    fwriteBytes(fid: number, data: Uint8Array): number;
+    fseek(fid: number, offset: number, origin: number): number;
+    ftell(fid: number): number;
+    scanDirectory(dirPath: string): WorkspaceFile[];
+    resolvePath(dirPath: string): string;
+    existsPath(path: string): "file" | "dir" | null;
+    mkdir(dirPath: string): boolean;
+    tempdir(): string;
+    userpath(): string;
+    deleteFile(pattern: string): void;
+    rmdir(dirPath: string, recursive: boolean): boolean;
+    movefile(source: string, destination: string): boolean;
+    copyfile(source: string, destination: string): boolean;
+    fileattrib(path: string): FileAttribInfo | null;
+    listDir(dirPath: string): {
+        name: string;
+        folder: string;
+        bytes: number;
+        isdir: boolean;
+        mtimeMs: number;
+    }[];
+    websave(url: string, filename: string, options?: WebOptions): void;
+    webread(url: string, options?: WebOptions): string;
+    unzip(zipfilename: string, outputfolder: string): string[];
+    /** Get the VFS changes for syncing back to the main thread. */
+    getChanges(): VfsChanges;
+    private getEntry;
+    private flushEntry;
+    private writeBytes;
+    /**
+     * `entry.pos` stays the logical (consumed) byte position: the text buffer
+     * holds the bytes starting at `entry.pos`, and consuming a line advances
+     * `entry.pos` by its byte length. This keeps fgetl/fgets coherent with
+     * freadBytes/fseek/ftell (and fscanf, which mixes the two).
+     */
+    private readLine;
+    private listDirGlob;
+    private listDirRecursive;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Browser implementation of SystemAdapter using in-memory state.
+ *
+ * The current working directory is delegated to the VFS so that
+ * `cd` (system cwd) and relative-path resolution inside the VFS stay
+ * in sync. Without this, project files written at "folder1/foo.m"
+ * would land under VFS.cwd ("/project") while `cd folder1` would
+ * resolve against the system adapter's own root, producing "/folder1"
+ * — a directory that contains nothing.
+ */
+import type { SystemAdapter } from "../numbl-core/systemAdapter.js";
+import type { VirtualFileSystem } from "./VirtualFileSystem.js";
+export declare class BrowserSystemAdapter implements SystemAdapter {
+    private vars;
+    private vfs;
+    private fallbackCwd;
+    constructor(vfs?: VirtualFileSystem);
+    /** Attach (or replace) the VFS used as the cwd source of truth. */
+    setVfs(vfs: VirtualFileSystem): void;
+    getEnv(name: string): string | undefined;
+    getAllEnv(): Record<string, string>;
+    setEnv(name: string, value: string): void;
+    cwd(): string;
+    chdir(dir: string): void;
+    platform(): string;
+    arch(): string;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * In-memory virtual file system for browser execution.
+ * Pure TypeScript — no browser or Node.js APIs.
+ * All file content stored as Uint8Array internally.
+ */
+export interface VFSFile {
+    content: Uint8Array;
+    mtimeMs: number;
+}
+export interface VfsChanges {
+    created: {
+        path: string;
+        content: Uint8Array;
+    }[];
+    modified: {
+        path: string;
+        content: Uint8Array;
+    }[];
+    deleted: string[];
+}
+export declare class VirtualFileSystem {
+    private files;
+    private directories;
+    private cwd;
+    private createdFiles;
+    private modifiedFiles;
+    private deletedFiles;
+    /** Clear change tracking. Call after populating the VFS with initial files. */
+    clearChangeTracking(): void;
+    /** Normalize a path to absolute form. */
+    normalizePath(p: string): string;
+    getCwd(): string;
+    setCwd(dir: string): void;
+    readFile(path: string): Uint8Array;
+    writeFile(path: string, content: Uint8Array): void;
+    deleteFile(path: string): boolean;
+    exists(path: string): "file" | "dir" | null;
+    fileSize(path: string): number;
+    mkdir(dirPath: string): boolean;
+    /** Move/rename a file or directory tree. Returns true on success. */
+    movefile(source: string, destination: string): boolean;
+    /** Copy a file or directory tree (source is left in place). True on success. */
+    copyfile(source: string, destination: string): boolean;
+    /** Resolve a path to its (normalized) absolute path + attributes, or null. */
+    fileattrib(path: string): {
+        Name: string;
+        directory: boolean;
+        UserRead: boolean;
+        UserWrite: boolean;
+        UserExecute: boolean;
+    } | null;
+    rmdir(dirPath: string, recursive: boolean): boolean;
+    /** List entries in a directory. */
+    listDir(dirPath: string): {
+        name: string;
+        folder: string;
+        bytes: number;
+        isdir: boolean;
+        mtimeMs: number;
+    }[];
+    /** List all file paths in the VFS. */
+    allFiles(): string[];
+    /** Get the changes since the VFS was created. */
+    getChanges(): VfsChanges;
+    private ensureParentDirs;
+}