numbl 0.4.7 → 0.4.8

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/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/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.8";

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

@@ -0,0 +1,54 @@
+/**
+ * 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;
+    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;
+}