numbl 0.3.3 → 0.4.1

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

@@ -1,7 +1,12 @@
 /**
- * JIT type system and IR node definitions.
+ * JIT type system.
+ *
+ * Used by the executor classification phase and by the JIT type
+ * adapter to map numbl runtime values onto JIT specializations.
+ * The IR node definitions that previously lived alongside this file
+ * (`JitExpr` / `JitStmt` / `JitCacheEntry`) belonged to the legacy
+ * in-tree JS-JIT / C-JIT pipeline and were deleted with it.
  */
-import type { BinaryOperation, UnaryOperation } from "./parser/types.js";
 export type SignCategory = "positive" | "nonneg" | "nonpositive" | "negative";
 export type JitType = {
     kind: "number";
@@ -71,9 +76,6 @@ export declare function isNonneg(t: JitType): boolean;
 export declare function flipSign(s?: SignCategory): SignCategory | undefined;
 export declare function unifySign(a?: SignCategory, b?: SignCategory): SignCategory | undefined;
 export declare function jitTypeKey(t: JitType): string;
-export declare function computeJitCacheKey(nargout: number, argTypes: JitType[]): string;
-/** Compute a unique JS function name for a JIT'd specialization. */
-export declare function computeJitFnName(identity: string, funcName: string): string;
 /** Widen/unify two types at control-flow join points. */
 export declare function unifyJitTypes(a: JitType, b: JitType): JitType;
 export declare function isScalarType(t: JitType): boolean;
@@ -90,319 +92,3 @@ export declare function shapeAfterReduction(shape: number[], dim?: number): {
     scalar: false;
     shape: number[];
 };
-export type JitExpr = {
-    tag: "NumberLiteral";
-    value: number;
-    jitType: JitType;
-} | {
-    tag: "ImagLiteral";
-    jitType: JitType;
-} | {
-    tag: "Var";
-    name: string;
-    jitType: JitType;
-} | {
-    tag: "Binary";
-    op: BinaryOperation;
-    left: JitExpr;
-    right: JitExpr;
-    jitType: JitType;
-} | {
-    tag: "Unary";
-    op: UnaryOperation;
-    operand: JitExpr;
-    jitType: JitType;
-} | {
-    tag: "StringLiteral";
-    value: string;
-    isChar: boolean;
-    jitType: JitType;
-} | {
-    tag: "Call";
-    name: string;
-    args: JitExpr[];
-    jitType: JitType;
-} | {
-    tag: "UserCall";
-    jitName: string;
-    name: string;
-    args: JitExpr[];
-    jitType: JitType;
-} | {
-    tag: "Index";
-    base: JitExpr;
-    indices: JitExpr[];
-    jitType: JitType;
-} | {
-    /**
-     * Range slice read on a real tensor: `src(a:b)` producing a fresh
-     * column-vector tensor of length `b - a + 1`. Stage 21 — unblocks
-     * chunkie's chunk_nearparam Newton loop which splits a Legendre
-     * expansion vector via `r0 = all0(1:dim)`.
-     *
-     * Codegen emits `$h.subarrayCopy1r(srcData, srcLen, start, end)`
-     * using the hoisted data/length aliases. Per-iter allocation is
-     * unavoidable without a range-alias extension to stage 5; small
-     * slices are cheap in V8 young-gen.
-     */
-    tag: "RangeSliceRead";
-    baseName: string;
-    start: JitExpr;
-    /** `null` when the range endpoint is the `end` keyword — codegen
-     *  substitutes the hoisted `.data.length` alias. */
-    end: JitExpr | null;
-    /** True when the source is a statically-known row vector
-     *  (shape `[1, n]`); the slice then preserves row orientation.
-     *  Otherwise the slice is a column vector (MATLAB semantics). */
-    isRow: boolean;
-    jitType: JitType;
-} | {
-    tag: "TensorLiteral";
-    rows: JitExpr[][];
-    nRows: number;
-    nCols: number;
-    jitType: JitType;
-} | {
-    /**
-     * Vertical concat growth: `[base; value]` where `base` is a real
-     * column-vector (or empty) tensor and `value` is a numeric scalar.
-     * Lowered from the chunkie grow-a-list pattern `it = [it; i]`.
-     * Codegens to `$h.vconcatGrow1r(base, value)` which allocates a
-     * fresh `(k+1, 1)` tensor and copies.
-     */
-    tag: "VConcatGrow";
-    base: JitExpr;
-    value: JitExpr;
-    jitType: JitType;
-} | {
-    /**
-     * Scalar read of a struct field: `s.f` where `s` has a struct type
-     * with a statically-known scalar field `f`. Lowered from `Member`
-     * exprs with an `Ident` base. The codegen hoists each unique
-     * `(baseName, fieldName)` pair to a local alias at function entry
-     * so per-iter reads are bare local loads (no `Map.get` per use).
-     * Mirrors the chunkie `opts.rho`, `chnkr.k`, `chnkr.nch` pattern.
-     */
-    tag: "MemberRead";
-    baseName: string;
-    fieldName: string;
-    jitType: JitType;
-} | {
-    /**
-     * Chained struct array member read: `T.nodes(i).leaf` where
-     * `T.nodes` is a struct array whose elements all share a field
-     * `leaf`. Lowered from the parser shape
-     * `Member(MethodCall(Ident(T), "nodes", [i]), "leaf")`.
-     *
-     * Codegen hoists `var $T_nodes_elements = T.fields.get("nodes").elements`
-     * at function entry (one alias per unique (structVarName,
-     * structArrayFieldName) pair) and emits
-     * `$T_nodes_elements[Math.round(i) - 1].fields.get("leaf")` per use.
-     *
-     * `leafFieldJitType` records the result type: either a scalar
-     * numeric type (number/boolean/complex_or_number) or a real tensor.
-     * Tensor-valued leaves work because the existing per-Assign hoist
-     * refresh picks up the newly-read tensor when the result flows
-     * into `chld = T.nodes(i).chld` and the callers then use
-     * `chld(k)` through the hoisted alias path.
-     */
-    tag: "StructArrayMemberRead";
-    structVarName: string;
-    structArrayFieldName: string;
-    indexExpr: JitExpr;
-    leafFieldName: string;
-    jitType: JitType;
-} | {
-    /**
-     * Indirect call through a function handle variable: `f(a, b)` where
-     * `f` has JitType `function_handle`. The codegen emits
-     * `$h.callFuncHandle($rt, f, arg1, arg2, ...)` which invokes the
-     * handle via its `jsFn` closure (or falls back to `rt.dispatch`).
-     * The `returnType` is determined at lowering time by probing the
-     * function handle's runtime value.
-     */
-    tag: "FuncHandleCall";
-    name: string;
-    args: JitExpr[];
-    jitType: JitType;
-} | {
-    /**
-     * User function call that bailed recursive lowering (stage 24 —
-     * soft-bail). Instead of bailing the containing loop, emit a
-     * runtime dispatch through the interpreter. Return type is
-     * determined at JIT compile time by probing (actually calling
-     * the function once with representative args). The helper
-     * `callUserFunc` verifies the actual return type on every call
-     * and throws `JitFuncHandleBailError` on mismatch so the loop
-     * runner can invalidate the cache entry and fall back to
-     * interpretation.
-     *
-     * Use case: `oneintp(...)` / `lege.exev(...)` in chunkie's adap
-     * inner loop — the callee body has tensor arithmetic the JIT
-     * can't inline, but the outer loop (scalar stack + col-slice
-     * writes + scalar compares) is a perfect JIT fit.
-     */
-    tag: "UserDispatchCall";
-    name: string;
-    args: JitExpr[];
-    jitType: JitType;
-};
-export type JitStmt = {
-    tag: "Assign";
-    name: string;
-    expr: JitExpr;
-} | {
-    tag: "AssignIndex";
-    /** Name of the tensor variable being written to (must be an Ident-based lvalue). */
-    baseName: string;
-    /** Scalar index expressions (1..3). */
-    indices: JitExpr[];
-    /** RHS scalar value to store. */
-    value: JitExpr;
-    /** Type of the base tensor (for codegen to choose the right helper). */
-    baseType: JitType;
-} | {
-    /**
-     * Range-slice write of the form `dst(a:b) = src(c:d)` or
-     * `dst(a:b) = src` (whole-tensor source). Both `dst` and `src` must
-     * be real tensors, and the LHS must use exactly one (linear) range
-     * index. Used by the loop JIT for the chunkie grow-and-copy pattern.
-     *
-     * When `srcStart` and `srcEnd` are both `null`, the source is used
-     * in its entirety — codegen substitutes `1` and `srcLen` (the
-     * source's hoisted length alias). This is stage 9's whole-tensor
-     * RHS form: `isp(1:nn) = itemp` where `itemp` is a plain Var.
-     */
-    tag: "AssignIndexRange";
-    baseName: string;
-    baseType: JitType;
-    dstStart: JitExpr;
-    dstEnd: JitExpr;
-    srcBaseName: string;
-    srcType: JitType;
-    srcStart: JitExpr | null;
-    srcEnd: JitExpr | null;
-} | {
-    /**
-     * Multi-dim column slice write `dst(:, j) = src` where both `dst`
-     * and `src` are real tensors. LHS must be `Index(Ident(dst),
-     * [Colon, scalar_j])` with `dst` having statically 2-D shape.
-     * RHS must be a plain Ident referencing a real-tensor var whose
-     * total element count matches `dst.shape[0]` at runtime.
-     *
-     * Used by the loop JIT for chunkie's adapgausskerneval column
-     * stack write: `vals(:, jj+1) = v2`. Also covers
-     * chunkerinterior's `rss(:, jj) = rval(:, k)` after a slice
-     * alias binds the RHS.
-     */
-    tag: "AssignIndexCol";
-    baseName: string;
-    baseType: JitType;
-    colIndex: JitExpr;
-    srcBaseName: string;
-    srcType: JitType;
-} | {
-    /**
-     * Page-slice write `dst(:, :, k) = rhs` where `dst` is a 3-D tensor
-     * and `rhs` is a 2-D tensor. Real-base + complex-rhs upgrades the
-     * base to complex in place.  Drives chunkie helm2d.green's
-     * `grad(:,:,k) = ...` / `hess(:,:,k) = ...` assignments.
-     */
-    tag: "AssignIndexPage3d";
-    baseName: string;
-    /** Base tensor type AFTER the write (may be complex even if the
-     *  initializer was real — the lowerer promotes in ctx.env). */
-    baseType: JitType;
-    /** Page index (1-based). */
-    pageIndex: JitExpr;
-    /** 2-D tensor RHS. */
-    value: JitExpr;
-} | {
-    /**
-     * Struct field assign lvalue `s.f = v`. When `needsPromote` is
-     * true, the base is (re)initialized as a fresh empty struct
-     * before the field is set — mirrors MATLAB's
-     * `s = []; s.f = v` idiom that promotes the empty matrix to a
-     * struct on first field write. `valueType` is the JIT type of
-     * `value` so stage 12 can hoist subsequent reads through a
-     * typed alias.
-     */
-    tag: "AssignMember";
-    baseName: string;
-    fieldName: string;
-    value: JitExpr;
-    needsPromote: boolean;
-} | {
-    tag: "If";
-    cond: JitExpr;
-    thenBody: JitStmt[];
-    elseifBlocks: {
-        cond: JitExpr;
-        body: JitStmt[];
-    }[];
-    elseBody: JitStmt[] | null;
-} | {
-    tag: "For";
-    varName: string;
-    start: JitExpr;
-    step: JitExpr | null;
-    end: JitExpr;
-    body: JitStmt[];
-} | {
-    tag: "While";
-    cond: JitExpr;
-    body: JitStmt[];
-} | {
-    tag: "Break";
-} | {
-    tag: "Continue";
-} | {
-    tag: "Return";
-} | {
-    tag: "ExprStmt";
-    expr: JitExpr;
-} | {
-    tag: "MultiAssign";
-    names: (string | null)[];
-    callName: string;
-    args: JitExpr[];
-    outputTypes: JitType[];
-    /** Dispatch shape:
-     *  - "ibuiltin" (default) — IBuiltin called via $h.ibcall.
-     *  - "func_handle" — `callName` is a function-handle var name; the
-     *    JIT loads the handle and calls jsFn with the requested nargout.
-     *  - "user" — `callName` is a user-fn name dispatched through the
-     *    interpreter (no specialized JIT artifact for the callee yet).
-     */
-    kind?: "ibuiltin" | "func_handle" | "user";
-} | {
-    /**
-     * Call a synthetic specialization (installed as a forwarder on $h)
-     * and write back multiple outputs into outer-scope vars. Only
-     * produced by the hybrid-loop pass in hybrid.ts, which
-     * replaces a For/While JitStmt with this call form when the
-     * extracted loop specialization compiled to native C.
-     *
-     * Semantics (0 / 1 / N outputs):
-     *   nargout==0 → emit `$h.callUser(...)` as a stmt (no writeback)
-     *   nargout==1 → emit `out = $h.callUser(...)`
-     *   nargout>=2 → emit `var $r = $h.callUser(...); out0=$r[0]; ...`
-     */
-    tag: "UserCallWriteback";
-    outputs: string[];
-    jitName: string;
-    name: string;
-    args: JitExpr[];
-    outputTypes: JitType[];
-} | {
-    tag: "SetLoc";
-    line: number;
-} | {
-    /** C-JIT assertion: if this JitStmt survives to JS codegen at --opt 2,
-     *  emit a runtime throw. The C-JIT codegen elides it. */
-    tag: "AssertCJit";
-};
-export interface JitCacheEntry {
-    fn: (...args: unknown[]) => unknown;
-    source: string;
-}

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

@@ -2,7 +2,7 @@
  * Loader for .numbl.js user functions.
  *
  * Evaluates .numbl.js files that define IBuiltins via
- *   register({ resolve, jitEmit? }).
+ *   register({ resolve }).
  * Supports optional WASM and native shared library bindings via directives:
  *   // wasm: <name>
  *   // native: <name>
@@ -34,7 +34,7 @@ export declare function funcNameFromMtoc2JsFile(fileName: string): string;
  * records. Each loaded record carries the function name, source file name,
  * and the IBuiltin object built from the file's `register()` call.
  *
- * Each .numbl.js file calls register({ resolve, jitEmit? }) to define an
+ * Each .numbl.js file calls register({ resolve }) to define an
  * IBuiltin. resolve(argTypes, nargout) returns { outputTypes, apply } or null.
  *
  * A .numbl.js file can specify bindings via directives at the top of the file:

package/dist-lib/numbl-core/parser/ClassParser.d.ts

@@ -8,6 +8,9 @@ export declare class ClassParser extends FunctionParser {
     parseClassDef(): Stmt;
     private parseNameBlock;
     private parsePropertiesNamesBlock;
+    /** Consume a balanced `open ... close` run (handling nesting). Assumes the
+     *  next token is `open`; no-op otherwise. */
+    private skipBalanced;
     private parseOptionalAttrList;
     /**
      * Parse a single method signature.

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

@@ -8,6 +8,6 @@ export { valuesAreEqual } from "./compare.js";
 export { displayValue } 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, } from "./indexing.js";
+export { COLON_INDEX, indexIntoRTValue as mIndex, storeIntoRTValueIndex as mIndexStore, charToNumericTensor, numericTensorToChar, } from "./indexing.js";
 export { getRTValueField as mGetField, setRTValueField as mSetField, } from "./struct-access.js";
 export { makeRangeTensor as mRange, horzcat, vertcat, } from "./tensor-construction.js";

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

@@ -1,13 +1,23 @@
 /**
  * Indexing, struct field access, range creation, and tensor concatenation.
  */
-import { type RuntimeValue } from "./types.js";
+import { type RuntimeValue, RuntimeTensor, RuntimeChar } from "./types.js";
 import { type RefcountRuntime } from "./refcount.js";
 /** Runtime surface needed by index-store mutations. The full Runtime
  *  class satisfies this structurally. */
 type StoreRuntime = RefcountRuntime;
 /** Sentinel marker for colon (:) indexing — means "all indices in this dimension" */
 export declare const COLON_INDEX: RuntimeValue;
+/** Convert a char value to a numeric (column-major) tensor of its code
+ *  points. A RuntimeChar stores its `value` row-major (each of `shape[0]`
+ *  rows is `shape[1]` chars, concatenated), so we transpose into the
+ *  tensor's column-major layout. Used so indexed assignment into / from a
+ *  char array runs on the numeric tensor machinery (MATLAB treats char as
+ *  numeric for indexed assignment). */
+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;
 /** 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/plotUtils.d.ts

@@ -5,8 +5,8 @@
  * plot(X1,Y1,LineSpec1,...), and Name-Value pairs like 'Color','r','LineWidth',2.
  */
 import { type RuntimeValue } from "./types.js";
-export type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, } from "../../graphics/types.js";
-import type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace } from "../../graphics/types.js";
+export type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace, } from "../../graphics/types.js";
+import type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace } from "../../graphics/types.js";
 export interface ParsedLineSpec {
     color?: string;
     lineStyle?: string;
@@ -75,6 +75,20 @@ export declare function parseImagescArgs(args: RuntimeValue[]): ImagescTrace;
  *   contour(..., Name, Value)
  */
 export declare function parseContourArgs(args: RuntimeValue[], filled: boolean): ContourTrace;
+/** Result of computing contour geometry: the MATLAB contour matrix `C`
+ *  (column-major `2 × n` data) plus the level list actually used. */
+export interface ContourMatrix {
+    /** Column-major `2 × n` data for a `RTV.tensor(data, [2, n])`. */
+    data: number[];
+    n: number;
+    levelList: number[];
+}
+/** Compute the MATLAB contour matrix for a parsed contour trace via marching
+ *  squares. Each marching-squares segment is emitted as its own two-vertex
+ *  contour line (header `[level; 2]` followed by the two `[x; y]` vertices) —
+ *  a valid contour matrix whose geometry matches MATLAB's connected polylines
+ *  segment-for-segment. */
+export declare function computeContourMatrix(trace: ContourTrace): ContourMatrix;
 /**
  * Parse mesh() arguments — same as surf but with different default rendering.
  */
@@ -237,3 +251,15 @@ export declare function parseHeatmapArgs(args: RuntimeValue[]): HeatmapTrace;
  * vectors, X and Y are expanded to a meshgrid.
  */
 export declare function parseQuiverArgs(args: RuntimeValue[]): QuiverTrace[];
+/**
+ * Parse quiver3() arguments.
+ *
+ * Supported forms:
+ *   quiver3(Z, U, V, W)
+ *   quiver3(X, Y, Z, U, V, W)
+ *   quiver3(..., scale)         — scale: nonnegative number or 'off'
+ *   quiver3(..., LineSpec)
+ *   quiver3(..., LineSpec, 'filled')
+ *   quiver3(..., Name, Value)   — Color, LineStyle, LineWidth, ShowArrowHead, …
+ */
+export declare function parseQuiver3Args(args: RuntimeValue[]): Quiver3Trace;

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

@@ -23,6 +23,12 @@ export declare class Runtime {
     private options;
     private initialVariableValues?;
     outputLines: string[];
+    /** Stack of in-progress output-capture buffers. While non-empty,
+     *  `output()` appends to the top buffer instead of emitting, so a
+     *  speculative JIT attempt's side effects can be committed on success
+     *  or discarded on bail (preventing duplicated output when the
+     *  interpreter re-runs the same code). */
+    private outputCaptureStack;
     plotInstructions: PlotInstruction[];
     variableValues: Record<string, RuntimeValue>;
     holdState: boolean;
@@ -104,7 +110,6 @@ export declare class Runtime {
     system?: SystemAdapter;
     builtins: Record<string, (nargout: number, args: unknown[]) => unknown>;
     customBuiltins: Record<string, (nargout: number, args: unknown[]) => unknown>;
-    jitHelpers: Record<string, any> | null;
     compileSpecialized: ((name: string, argTypes: ItemType[], callSite: CallSite) => ((...args: any[]) => any) | null) | null;
     evalLocalCallback: ((code: string, initialVars: Record<string, RuntimeValue>, onOutput: (text: string) => void, fileName?: string) => {
         returnValue: unknown;
@@ -158,6 +163,16 @@ export declare class Runtime {
     getJitCompileTimeMs(): number;
     getDispatchUnknownCounts(): Record<string, number>;
     output(text: string): void;
+    /** Begin buffering output for a speculative execution attempt.
+     *  Pair with exactly one `commitOutputCapture()` or
+     *  `discardOutputCapture()`. */
+    beginOutputCapture(): void;
+    /** Emit the buffered output (to the parent capture frame if nested,
+     *  else to the real sink) — call when the attempt succeeded. */
+    commitOutputCapture(): void;
+    /** Drop the buffered output — call when the attempt bailed, so a
+     *  subsequent re-run is the only thing that emits. */
+    discardOutputCapture(): void;
     error(message: string): RuntimeError;
     annotateError(e: unknown): void;
     wrapError(e: unknown): RuntimeStruct;

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

@@ -33,6 +33,9 @@ export declare function plotInstr(plotInstructions: PlotInstruction[], instr: {
     type: "close_all";
 } | {
     type: "clf";
+} | {
+    type: "cla";
+    reset: boolean;
 } | {
     type: "set_subplot";
     rows: unknown;
@@ -66,6 +69,7 @@ export declare function viewCall(plotInstructions: PlotInstruction[], args: Runt
 export declare function plotCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function plot3Call(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function surfCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function surfaceCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function imagescCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function pcolorCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function contourCall(plotInstructions: PlotInstruction[], args: RuntimeValue[], filled: boolean): void;
@@ -101,6 +105,7 @@ export declare function piechartCall(plotInstructions: PlotInstruction[], args:
 export declare function donutchartCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function heatmapCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function quiverCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function quiver3Call(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function legendCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function drawnow(plotInstructions: PlotInstruction[], options: ExecOptions): void;
 export declare function pause(seconds: unknown): void;

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

@@ -84,6 +84,19 @@ export declare class RuntimeFunction extends Refcounted {
         vars: Map<string, RuntimeValue>;
         parent?: unknown;
     } | undefined;
+    /** The defining AST of this handle — an `AnonFunc` (`@(p) body`) or
+     *  `FuncHandle` (`@name`) parser Expr. Lets the JIT recover the
+     *  handle's source so a capture-free handle that crosses a
+     *  compile boundary (a loop input / call arg) can be inlined as an
+     *  in-scope handle constant. Typed loosely (parser Expr) to avoid a
+     *  runtime→parser layering dependency; consumers cast. Undefined for
+     *  handles created by paths that don't set it (e.g. builtins). */
+    handleAst: unknown;
+    /** Source file the handle was defined in. The inliner only reuses a
+     *  handle's AST when this matches the file being compiled, so a
+     *  named-handle target (`@foo`) resolves to the same `foo` it did at
+     *  definition (file-local functions can shadow across files). */
+    handleDefFile: string | undefined;
     constructor(name: string, impl: "builtin" | "user", captures: RuntimeValue[], jsFn?: (...args: unknown[]) => unknown, jsFnExpectsNargout?: boolean, nargin?: number);
     protected _destroy(rt: RefcountRuntime): void;
 }
@@ -103,13 +116,16 @@ export declare class RuntimeClassInstance extends Refcounted {
     bindField(rt: RefcountRuntime, name: string, value: RuntimeValue): void;
     protected _destroy(rt: RefcountRuntime): void;
 }
-/** A 1-D array of class instances that all share the same class.
- *  Created by default horzcat/vertcat when the class doesn't overload them. */
+/** An array of class instances that all share the same class. Created by
+ *  default horzcat/vertcat when the class doesn't overload them. `elements`
+ *  are stored in column-major order; `shape` is the 2-D `[rows, cols]` size
+ *  (defaults to a `1×N` row vector when omitted). */
 export declare class RuntimeClassInstanceArray extends Refcounted {
     readonly kind: "class_instance_array";
     className: string;
     elements: RuntimeClassInstance[];
-    constructor(className: string, elements: RuntimeClassInstance[]);
+    shape: [number, number];
+    constructor(className: string, elements: RuntimeClassInstance[], shape?: [number, number]);
     protected _destroy(rt: RefcountRuntime): void;
 }
 export declare class RuntimeComplexNumber extends Refcounted {

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

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

@@ -10,7 +10,15 @@ export interface WorkspaceFile {
  * Bridge for loading native shared libraries (.so/.dll/.dylib).
  * Implemented outside numbl-core (e.g. via koffi in the CLI) since
  * native FFI is not available in browser environments.
+ *
+ * `koffi`, when present, exposes the root koffi module so the
+ * C-JIT executors can call its struct / alloc / encode / decode
+ * helpers. Browser deployments leave `koffi` undefined; the
+ * C-JIT executors decline (numbl falls back to JS-JIT).
  */
 export interface NativeBridge {
     load(libraryPath: string): unknown;
+    /** koffi root module — `require("koffi")`'s exports. Only the
+     *  C-JIT path consumes it. Optional so non-Node hosts can omit. */
+    koffi?: unknown;
 }