numbl 0.4.4 → 0.4.6

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

@@ -10,6 +10,8 @@ import type { FileIOAdapter } from "./fileIOAdapter.js";
 import type { SystemAdapter } from "./systemAdapter.js";
 import type { WorkspaceFile } from "../numbl-core/workspace/index.js";
 import type { NativeBridge } from "./workspace/index.js";
+import { type UihtmlSession } from "./runtime/uihtmlSession.js";
+export type { UihtmlSession } from "./runtime/uihtmlSession.js";
 export interface ExecOptions {
     onOutput?: (text: string) => void;
     onDrawnow?: (plotInstructions: PlotInstruction[]) => void;
@@ -48,6 +50,10 @@ export interface ExecOptions {
     implicitCwdPath?: string | null;
     /** SharedArrayBuffer for cooperative cancellation. Int32[0] != 0 means cancelled. */
     cancelSAB?: SharedArrayBuffer;
+    /** Hook for `sendEventToHTMLSource(src,name,data)` — pushes an event from a
+     *  uihtml callback back to the component's page (MATLAB → JS). `dataJson` is
+     *  the data already `jsonencode`d. The host forwards it to the iframe. */
+    onHtmlSourceEvent?: (compId: string, name: string, dataJson: string) => void;
 }
 export interface BuiltinProfileEntry {
     totalTimeMs: number;
@@ -94,5 +100,9 @@ export interface ExecResult {
     workspaceFiles?: WorkspaceFile[];
     /** Final implicit cwd path (for REPL persistence across commands). */
     implicitCwdPath?: string | null;
+    /** Present when the run left `uihtml` reverse-channel callbacks registered.
+     *  The host retains this to dispatch later iframe events into the still-live
+     *  interpreter (see UihtmlSession). Absent for normal runs (no overhead). */
+    uihtmlSession?: UihtmlSession;
 }
 export declare function executeCode(source: string, options?: ExecOptions, workspaceFiles?: WorkspaceFile[], mainFileName?: string, searchPaths?: string[], nativeBridge?: NativeBridge): ExecResult;

package/dist-lib/numbl-core/executors/plugins.d.ts

@@ -10,6 +10,15 @@
  * registered executor.
  */
 import type { Registry } from "./registry.js";
+import type { Executor } from "./types.js";
+/** The three C-JIT executors, registered at Node bootstrap. */
+export interface CJitExecutors {
+    topLevel: Executor;
+    loop: Executor;
+    call: Executor;
+}
+/** Register the C-JIT executors. Called once at Node bootstrap. */
+export declare function registerCJitExecutors(execs: CJitExecutors): void;
 /** Optimization mode label.
  *
  *   - `"0"` — pure AST interpreter, no executors registered.

package/dist-lib/numbl-core/helpers/marching-cubes-tables.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Marching-cubes lookup tables (Paul Bourke / Lorensen-Cline).
+ *
+ * Vendored verbatim from mikolalysenko/isosurface (MIT). Generated from
+ * lib/marchingcubes.js; do not edit by hand.
+ */
+export declare const edgeTable: Uint32Array<ArrayBuffer>;
+export declare const triTable: number[][];
+export declare const cubeVerts: number[][];
+export declare const edgeIndex: number[][];

package/dist-lib/numbl-core/helpers/marching-cubes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Marching cubes over a regular scalar grid, plus the MATLAB `isosurface`
+ * argument parsing. Backs the `isosurface` builtin.
+ *
+ * The 256-case lookup tables are vendored in `marching-cubes-tables.ts`
+ * (MIT, mikolalysenko/isosurface — Paul Bourke's classic table). The loop
+ * here adds the two things that library lacks for our use:
+ *   - vertices interpolated from arbitrary X/Y/Z coordinate arrays (so it is
+ *     correct for ndgrid, meshgrid, vector, and implicit grids), and
+ *   - cross-cell vertex sharing (keyed by grid-edge identity), which MATLAB
+ *     produces by default and which downstream code (e.g. triangle adjacency)
+ *     relies on.
+ */
+import type { RuntimeValue } from "../runtime/types.js";
+export interface IsoMesh {
+    /** Physical vertex coordinates, one `[x, y, z]` per vertex. */
+    vertices: number[][];
+    /** Triangles as 0-based vertex-index triples. */
+    faces: number[][];
+    /** Per-vertex scalar color data (present only when a colors array is given). */
+    colors?: number[];
+}
+type ScalarFn = (i: number, j: number, k: number) => number;
+type CoordFn = (i: number, j: number, k: number) => [number, number, number];
+/**
+ * Extract the isosurface of `getVal` at `iso` over an `m×n×p` grid.
+ * `getCoord` maps a grid corner to its physical position; `getColor` (if
+ * given) supplies a scalar field interpolated onto the surface vertices.
+ */
+export declare function marchingCubes(dims: [number, number, number], getVal: ScalarFn, getCoord: CoordFn, iso: number, opts?: {
+    share?: boolean;
+    getColor?: ScalarFn;
+}): IsoMesh;
+/**
+ * Parse `isosurface(...)` arguments and compute the mesh.
+ *
+ * Forms (by numeric-argument count, after stripping 'verbose'/'noshare'):
+ *   1: isosurface(V)               4: isosurface(X,Y,Z,V)
+ *   2: isosurface(V,iso)           5: isosurface(X,Y,Z,V,iso)
+ *   3: isosurface(V,iso,colors)    6: isosurface(X,Y,Z,V,iso,colors)
+ *
+ * When the isovalue is omitted it is chosen automatically (see autoIsovalue) —
+ * an approximation that does not match MATLAB's exact histogram heuristic.
+ */
+export declare function isosurfaceFromArgs(args: RuntimeValue[]): IsoMesh;
+export {};

package/dist-lib/numbl-core/interpreter/builtins/array-construction.d.ts

@@ -1,4 +1,10 @@
 /**
  * Array construction builtins: zeros, ones, nan/NaN, eye, linspace, logspace.
  */
-export {};
+import type { RuntimeValue } from "../../runtime/types.js";
+import type { JitType } from "../../jitTypes.js";
+/** Drop a trailing class-name spec from the JIT arg types (used in `match`
+ *  so the size cases still apply when a class string is present). */
+export declare function stripClassNameTypes(argTypes: JitType[]): JitType[];
+/** Drop a trailing class-name spec from the runtime args (used in `apply`). */
+export declare function stripClassNameArgs(args: RuntimeValue[]): RuntimeValue[];

package/dist-lib/numbl-core/interpreter/builtins/geometry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Interpreter IBuiltins for computational geometry functions: delaunay,
+ * delaunayn, inpolygon.
+ *
+ * delaunay/delaunayn are backed by the qhull WASM module, installed as the
+ * Delaunay backend at startup (see geometry-bridge.ts and the qhull-node /
+ * qhull-browser loaders). The backend must be installed before these builtins
+ * run; otherwise they throw.
+ */
+export {};

package/dist-lib/numbl-core/interpreter/builtins/index.d.ts

@@ -28,6 +28,7 @@ import "./time-system.js";
 import "./datetime.js";
 import "./sparse.js";
 import "./special-math.js";
+import "./geometry.js";
 import "./misc.js";
 import "./dictionary.js";
 import "./help-text.js";

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

@@ -119,6 +119,7 @@ export declare class Interpreter {
     evalBinary: (expr: Extract<Expr, {
         type: "Binary";
     }>) => unknown;
+    evalCondition: (expr: Expr) => unknown;
     evalUnary: (expr: Extract<Expr, {
         type: "Unary";
     }>) => unknown;

package/dist-lib/numbl-core/interpreter/interpreterExec.d.ts

@@ -20,6 +20,17 @@ export declare function evalArgs(this: Interpreter, argExprs: Expr[]): unknown[]
 export declare function evalBinary(this: Interpreter, expr: Extract<Expr, {
     type: "Binary";
 }>): unknown;
+/**
+ * Evaluate an `if`/`while`/`elseif` condition.
+ *
+ * MATLAB short-circuits the element-wise `&` and `|` operators when they
+ * appear at the top of a conditional expression and the left operand is
+ * scalar — e.g. `if nargin<4 | isempty(x)` must NOT evaluate `isempty(x)`
+ * when `nargin<4` (otherwise `x` may be undefined). Outside this context
+ * `&`/`|` evaluate both operands element-wise, so the special handling
+ * lives here rather than in `evalBinary`.
+ */
+export declare function evalCondition(this: Interpreter, expr: Expr): unknown;
 export declare function evalUnary(this: Interpreter, expr: Extract<Expr, {
     type: "Unary";
 }>): unknown;

package/dist-lib/numbl-core/jit/builtins/runtime/snippets.c.gen.d.ts

@@ -0,0 +1,4 @@
+/** C snippet bodies, keyed by basename (e.g. `disp_double.h`).
+ *  C-JIT only (`--opt 2`, Node). Registered at bootstrap via
+ *  `setCSnippets` so the browser bundle never pulls it in. */
+export declare const C_SNIPPETS: Record<string, string>;

package/dist-lib/numbl-core/jit/builtins/runtime/snippets.gen.d.ts

@@ -72,8 +72,6 @@ export * from "./tensor_ops/tensor_var.js";
 export * from "./tensor_ops/tensor_zeros_nd.js";
 export * from "./tensor_ops/tensor_zeros_square.js";
 export * from "./text/strcmp.js";
-/** C snippet bodies, keyed by basename (e.g. `disp_double.h`). */
-export declare const C_SNIPPETS: Record<string, string>;
 /** JS snippet bodies (with `export` keywords stripped), keyed by
  *  basename (e.g. `disp_double.js`). Inlined into emitted JS. The
  *  functions may reference host hooks (`$write`, …) as free

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

@@ -14,6 +14,8 @@
  * pulls dependencies in first.
  */
 import type { Builtin } from "../builtins/registry.js";
+/** Register the C runtime-snippet table. Called once at Node bootstrap. */
+export declare function setCSnippets(snippets: Record<string, string>): void;
 /** Minimal Workspace shape consulted at emit time. Importing the
  *  concrete Workspace class would create a cycle (workspace ↔ codegen);
  *  the structural type below captures exactly what codegen needs. */

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

@@ -0,0 +1,29 @@
+/**
+ * Geometry bridge — a module-level singleton that holds the Delaunay
+ * triangulation backend.
+ *
+ * Startup (CLI, browser worker, test-runner) loads the qhull WASM module
+ * (exact, robust to cospherical/coplanar input) and installs it here. The
+ * builtins require it: if no backend is set, delaunay/delaunayn throw.
+ *
+ * Usage (startup):
+ *   import { setDelaunayBackend } from './numbl-core/native/geometry-bridge.js';
+ *   const qhull = await loadQhull();
+ *   setDelaunayBackend((points, dim) => qhull.delaunay(points, dim).facets);
+ *
+ * Usage (builtin):
+ *   import { getDelaunayBackend } from '../native/geometry-bridge.js';
+ *   const backend = getDelaunayBackend();
+ *   if (!backend) throw ...;
+ *   const cells = backend(points, dim);
+ */
+/**
+ * Compute a Delaunay triangulation of `points` (an array of dim-dimensional
+ * tuples). Returns an array of simplices, each a list of `dim+1` 0-based input
+ * point indices.
+ */
+export type DelaunayBackend = (points: number[][], dim: number) => number[][];
+/** Install (or clear, with null) the Delaunay backend. */
+export declare function setDelaunayBackend(fn: DelaunayBackend | null): void;
+/** Get the current Delaunay backend, or null if none is installed. */
+export declare function getDelaunayBackend(): DelaunayBackend | null;

package/dist-lib/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-lib/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-lib/numbl-core/runtime/plotBuiltinDispatch.d.ts

@@ -42,6 +42,12 @@ import type { PlotInstruction } from "../../graphics/types.js";
 export interface PlotDispatchState {
     holdState: boolean;
     tiledLayoutState: TiledLayoutState | null;
+    /** Current figure handle (0 = none created yet). */
+    currentFigureHandle?: number;
+    /** Highest figure handle allocated so far. `figure` with no argument
+     *  creates a NEW figure with handle `maxFigureHandle + 1` (MATLAB
+     *  semantics), rather than always reusing handle 1. */
+    maxFigureHandle?: number;
 }
 /** Active tiled-layout grid. `mode` controls how the grid grows: in
  *  `flow` (default), nexttile expands rows/cols to fit; `vertical` and

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

@@ -77,6 +77,24 @@ export declare function parsePatchArgs(args: RuntimeValue[]): PatchTrace;
  *   fill(ax, ___)
  */
 export declare function parseFillArgs(args: RuntimeValue[]): PatchTrace[];
+/**
+ * Parse trimesh() arguments into a canonical PatchTrace.
+ *
+ * trimesh draws a triangular mesh and (per the MATLAB docs) returns a patch
+ * object, so it maps onto the PatchTrace model: the connectivity matrix T
+ * supplies the faces (one triangle per row, 1-based vertex indices) and the
+ * x/y[/z] vectors supply the vertices.
+ *
+ * Supported forms:
+ *   trimesh(T, x, y)              — 2-D triangular mesh
+ *   trimesh(T, x, y, z)           — 3-D triangular mesh
+ *   trimesh(T, x, y, z, c)        — c is per-vertex color data
+ *   trimesh(TO)                   — triangulation object (struct exposing
+ *                                   ConnectivityList + Points)
+ *   trimesh(___, Name, Value)     — patch properties
+ *   trimesh(ax, ___)              — leading axes handle (ignored)
+ */
+export declare function parseTriMeshArgs(args: RuntimeValue[]): PatchTrace;
 /**
  * Parse surf() arguments.
  *

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

@@ -32,9 +32,27 @@ export declare class Runtime {
     plotInstructions: PlotInstruction[];
     variableValues: Record<string, RuntimeValue>;
     holdState: boolean;
+    /** Figure-handle tracking for MATLAB-style `figure` allocation: `figure`
+     *  with no argument creates a new figure (`maxFigureHandle + 1`). */
+    currentFigureHandle: number;
+    maxFigureHandle: number;
     /** Monotonic id source for graphics handles whose trace can be live-updated
      *  via `set` / `update_trace` (e.g. lines returned by `line`). */
     graphicsIdCounter: number;
+    /** Reverse channel for `uihtml` components (HTML → MATLAB). Maps a component
+     *  id (the `uihtml` instruction's `id`) to the callback handles registered
+     *  for it. When non-empty after a run, the host keeps this runtime alive so
+     *  iframe events can re-enter the interpreter and invoke these handles.
+     *  Handles are incref'd while stored (see registeruihtmlcallback). */
+    uihtmlCallbacks: Map<string, {
+        HTMLEventReceived?: RuntimeValue;
+        DataChanged?: RuntimeValue;
+    }>;
+    /** Hook invoked by `sendEventToHTMLSource(src, name, data)` to push an event
+     *  from MATLAB back to a uihtml component's page. `dataJson` is the data
+     *  already `jsonencode`d. Set from ExecOptions; the host forwards it to the
+     *  iframe. */
+    onHtmlSourceEvent?: (compId: string, name: string, dataJson: string) => void;
     tiledLayoutState: {
         rows: number;
         cols: number;
@@ -142,6 +160,10 @@ export declare class Runtime {
      *  every value adopted into the scope is decref'd. Used by `execStmt`
      *  to bound the lifetime of expression transients to one statement. */
     withScope<T>(fn: () => T): T;
+    /** Register the implicit default figure (handle 1) the first time a graphics
+     *  op runs without an explicit `figure`, so a later no-arg `figure` allocates
+     *  a new handle instead of reusing 1 (MATLAB semantics). */
+    ensureCurrentFigure(): void;
     private initBuiltins;
     profileEnter(key: string): void;
     profileLeave(): void;

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

@@ -73,6 +73,7 @@ export declare function plotCall(plotInstructions: PlotInstruction[], args: Runt
 export declare function plot3Call(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function lineCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function patchCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function trimeshCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function fillCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function surfCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function surfaceCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;

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

@@ -0,0 +1,40 @@
+/**
+ * uihtml reverse channel (HTML → MATLAB) for a finished run.
+ *
+ * When a script creates a `uihtml` component with a callback
+ * (HTMLEventReceivedFcn / DataChangedFcn), the run leaves entries in
+ * `rt.uihtmlCallbacks`. `executeCode` then builds a `UihtmlSession` and returns
+ * it so the host (the worker) can keep the interpreter alive and re-enter it
+ * when an event arrives from the iframe — mirroring MATLAB, where the script
+ * returns but its callbacks keep firing.
+ *
+ * Dispatch re-activates the run's own special-builtin closures (captured at
+ * end-of-run, NOT re-registered — re-registering would reset their counters)
+ * and pushes the runtime so `disp`, plotting, and `sendEventToHTMLSource`
+ * inside the callback reach this runtime. This mirrors executeCode's own
+ * save/restore of SPECIAL_BUILTIN_NAMES.
+ */
+import type { Runtime } from "./runtime.js";
+import type { PlotInstruction } from "../../graphics/types.js";
+import { type IBuiltin } from "../interpreter/builtins/types.js";
+export interface UihtmlSession {
+    /** True while at least one component still has a registered callback. */
+    hasCallbacks(): boolean;
+    /** Dispatch an event from a component's page into MATLAB. `eventType` is
+     *  "HTMLEventReceived" (JS `sendEventToMATLAB`) or "DataChanged" (JS set
+     *  `htmlComponent.Data`). `payload.data` is the structured-clone'd JS value.
+     *  New plot output is flushed via `onDrawnow`; outgoing
+     *  `sendEventToHTMLSource` calls go through `rt.onHtmlSourceEvent`. */
+    dispatchEvent(compId: string, eventType: "HTMLEventReceived" | "DataChanged", payload: {
+        name?: string;
+        data: unknown;
+    }): void;
+    /** Release the retained callback handles (and their refs). */
+    dispose(): void;
+}
+/**
+ * Build a session over a runtime that registered uihtml callbacks.
+ * `activeSpecials` is a snapshot of this runtime's special-builtin closures,
+ * captured at end-of-run while they are still installed globally.
+ */
+export declare function createUihtmlSession(rt: Runtime, activeSpecials: Map<string, IBuiltin>, onDrawnow?: (plotInstructions: PlotInstruction[]) => void): UihtmlSession;

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