numbl 0.3.0 → 0.4.0

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

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ */
+export type SignCategory = "positive" | "nonneg" | "nonpositive" | "negative";
+export type JitType = {
+    kind: "number";
+    exact?: number;
+    sign?: SignCategory;
+    isInteger?: boolean;
+} | {
+    kind: "boolean";
+    value?: boolean;
+} | {
+    kind: "complex_or_number";
+    pureImaginary?: boolean;
+} | {
+    kind: "tensor";
+    isComplex: boolean;
+    shape?: number[];
+    ndim?: number;
+    isLogical?: boolean;
+    nonneg?: boolean;
+} | {
+    kind: "string";
+    value?: string;
+} | {
+    kind: "char";
+    value?: string;
+} | {
+    kind: "struct";
+    fields?: Record<string, JitType>;
+} | {
+    /**
+     * A 1-D homogeneous array of structs (matlab struct array form
+     * `T.nodes(i)`). `elemFields` records the per-element field types
+     * unified across all elements. `length` is optional and carries
+     * the statically-known element count when available.
+     */
+    kind: "struct_array";
+    elemFields?: Record<string, JitType>;
+    length?: number;
+} | {
+    kind: "class_instance";
+    className: string;
+    isHandleClass?: boolean;
+    fields?: Record<string, JitType>;
+} | {
+    kind: "sparse_matrix";
+    isComplex: boolean;
+    m?: number;
+    n?: number;
+} | {
+    kind: "cell";
+    shape?: number[];
+    /** Per-index element types (1-based), tracked when literal-index
+     *  writes happen with a known type. Reads with a literal index in
+     *  the map return the tracked type instead of `unknown`, which
+     *  unblocks chunkerfunc's `[out{1:3}] = fcurve(ts); r = out{1}; …`
+     *  pattern. Sparse — missing keys mean "unknown". */
+    elements?: Record<number, JitType>;
+} | {
+    kind: "dictionary";
+} | {
+    kind: "function_handle";
+} | {
+    kind: "unknown";
+};
+export declare function signFromNumber(v: number): SignCategory | undefined;
+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;
+/** 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;
+export declare function isNumericScalarType(t: JitType): boolean;
+export declare function isTensorType(t: JitType): boolean;
+export declare function isComplexType(t: JitType): boolean;
+/** True when the type guarantees an integer value at runtime (safe for |0). */
+export declare function isKnownInteger(t: JitType): boolean;
+/** Types that support arithmetic binary operations in the JIT. */
+export declare function isArithmeticType(t: JitType): boolean;
+export declare function shapeAfterReduction(shape: number[], dim?: number): {
+    scalar: true;
+} | {
+    scalar: false;
+    shape: number[];
+};

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>
@@ -21,12 +21,20 @@ export interface LoadedJsUserFunction {
 }
 /** Returns true if the file is a numbl JS user function file (`*.numbl.js`). */
 export declare function isNumblJsFile(fileName: string): boolean;
+/** Returns true if the file is an mtoc2-only user function file (`*.mtoc2.js`).
+ *  Numbl recognizes the extension for workspace discovery + function-name
+ *  resolution, but never executes the body — mtoc2's loader does that. */
+export declare function isMtoc2JsFile(fileName: string): boolean;
+/** Derive a function name from a `.mtoc2.js` workspace file path.
+ *    "myadd.mtoc2.js"            → "myadd"
+ *    "/path/to/myadd.mtoc2.js"   → "myadd" */
+export declare function funcNameFromMtoc2JsFile(fileName: string): string;
 /**
  * Load .numbl.js user function files and return them as LoadedJsUserFunction
  * 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/lowering/loweringContext.d.ts

@@ -23,6 +23,13 @@ interface WorkspaceRegistry {
         fileName: string;
         builtin: IBuiltin;
     }>;
+    /** mtoc2-only user functions (.mtoc2.js): functionName → { fileName, source }.
+     *  Numbl never executes these — the source text is stored for mtoc2's loader
+     *  to consume. Numbl's interpreter rejects calls to them with a clear error. */
+    mtoc2UserFunctionsByName: Map<string, {
+        fileName: string;
+        source: string;
+    }>;
     /** Per-workspace-file lowering contexts (created on demand) */
     fileContexts: Map<string, LoweringContext>;
     /** Workspace classes: qualifiedName → ClassInfo */
@@ -68,6 +75,10 @@ export interface FunctionIndex {
     workspaceFunctions: Set<string>;
     /** JS user functions (resolved at workspace-function priority, not builtin) */
     jsUserFunctions: Set<string>;
+    /** mtoc2-only user functions (.mtoc2.js). Resolved at workspace-function
+     *  priority, like jsUserFunctions. Numbl's interpreter rejects calls to
+     *  these; mtoc2 routes them through its own loader. */
+    mtoc2UserFunctions: Set<string>;
     /** Workspace classes (classdef files) */
     workspaceClasses: Set<string>;
     /** Local subfunctions per workspace file: primaryFuncName → Set<subfuncName> */
@@ -139,6 +150,12 @@ export declare class LoweringContext {
      * Register workspace files for on-demand resolution.
      * Extracts function names from filenames (top-level only, plus +pkg namespaces).
      * Also handles @ClassName class folders.
+     *
+     * `.m` files register as workspace functions / classes / private functions
+     * (the regular MATLAB-style discovery). `.mtoc2.js` files register as
+     * mtoc2-only user functions: numbl tracks the name so resolution sees
+     * them, but the body stays unparsed — mtoc2's loader evaluates them.
+     * `.mtoc2.js` files in `@ClassName/` are not yet supported.
      */
     registerWorkspaceFiles(files: WorkspaceFile[]): void;
     isWorkspaceFunction(name: string): boolean;
@@ -149,6 +166,13 @@ export declare class LoweringContext {
      * Uses first-wins semantics so search-path priority is honored.
      */
     registerJsUserFunction(funcName: string, fileName: string, builtin: IBuiltin): void;
+    /**
+     * Register an mtoc2-only user function (.mtoc2.js) in the workspace
+     * registry. Numbl stores the source text verbatim; mtoc2's loader
+     * evaluates it. Uses first-wins semantics so search-path priority is
+     * honored — same as `.numbl.js`.
+     */
+    registerMtoc2UserFunction(funcName: string, fileName: string, source: string): void;
     /**
      * Get the effective directory for this context's file, used for
      * private function resolution. If the file is inside a private/ folder,

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

@@ -26,7 +26,7 @@ export interface LapackBridge {
      * Invert an n×n real matrix stored in column-major order (MATLAB/LAPACK convention).
      * @param data  Column-major Float64Array of length n*n (not modified).
      * @param n     Matrix dimension.
-     * @returns     Inverted matrix as a new Float64Array in column-major order.
+     * @returns     Inverted matrix as a allocFloat64Array in column-major order.
      * @throws      Error if the matrix is singular.
      */
     inv(data: Float64Array, n: number): Float64Array;
@@ -138,7 +138,7 @@ export interface LapackBridge {
      * @param k  Number of columns in A and rows in B.
      * @param B  Column-major Float64Array of length k*n  (B is k×n, not modified).
      * @param n  Number of columns in B and C.
-     * @returns  C = A*B as a new Float64Array of length m*n in column-major order.
+     * @returns  C = A*B as a allocFloat64Array of length m*n in column-major order.
      */
     matmul?(A: Float64Array, m: number, k: number, B: Float64Array, n: number): Float64Array;
     /**
@@ -168,7 +168,7 @@ export interface LapackBridge {
      * @param n     Number of columns in A; also the number of rows in the result X.
      * @param B     Column-major Float64Array of length m*nrhs  (B is m×nrhs, not modified).
      * @param nrhs  Number of right-hand sides (columns of B and X).
-     * @returns     X as a new Float64Array of length n*nrhs in column-major order.
+     * @returns     X as a allocFloat64Array of length n*nrhs in column-major order.
      */
     linsolve?(A: Float64Array, m: number, n: number, B: Float64Array, nrhs: number): Float64Array;
     /**

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/parser/types.d.ts

@@ -316,6 +316,26 @@ export type Stmt = {
     directive: string;
     args: string[];
     span: Span;
+} | {
+    /** Synthetic stmt produced by an executor-registered AST
+     *  transformer (e.g. the C-JIT chain pass). Wraps a contiguous
+     *  run of original stmts so a specialized executor can claim
+     *  them as a unit; the interpreter falls back to executing
+     *  `subStmts` in order when the executor isn't registered or
+     *  declines.
+     *
+     *  Never produced by the parser. */
+    type: "Synth";
+    /** Identifies the executor that this synth node was built for
+     *  (e.g. `"c-jit-chain"`). The matching executor reads `data`. */
+    tag: string;
+    /** Original adjacent stmts, in source order. Used by the
+     *  interpreter fallback. */
+    subStmts: Stmt[];
+    /** Executor-specific pre-computed analysis. Opaque to the
+     *  interpreter. */
+    data: unknown;
+    span: Span;
 };
 export interface AbstractSyntaxTree {
     body: Stmt[];

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

@@ -1,23 +1,12 @@
-/**
- * Allocate an UNINITIALIZED typed array — skips the zero-fill that
- * `new Float64Array(n)` / `new FloatXArray(n)` perform by default.
- *
- * On Node, `Buffer.allocUnsafe` returns un-zeroed memory; wrapping it
- * in a TypedArray view costs ~10× less than the zero-fill for a 16 MB
- * buffer (~45 µs vs ~470 µs at N=2M doubles).
- *
- * SAFETY CONTRACT (very important):
- *   The caller MUST write every element before reading it.  Any element
- *   that is read before being written will contain arbitrary stale bytes
- *   from recently-freed memory.  If you cannot guarantee full coverage,
- *   use `new Float64Array(n)` / `new FloatXArray(n)` instead.
- *
- * In non-Node environments (browser, Deno without node-compat, …) where
- * `Buffer` is unavailable, we fall back to the zero-filling constructor
- * — still correct, just slower.
- */
-import { FloatXArray } from "./types.js";
-type FloatXInstance = InstanceType<typeof FloatXArray>;
-export declare function uninitFloat64(n: number): Float64Array<ArrayBuffer>;
-export declare function uninitFloatX(n: number): FloatXInstance;
-export {};
+/** Allocate a Float64Array. Thin wrapper around `new Float64Array(x)`
+ *  kept as a single allocation site so future strategies (pooling,
+ *  COW-aware allocation, etc.) can be reintroduced without touching
+ *  every callsite. */
+export declare function allocFloat64Array(x: number | number[] | Float64Array): Float64Array;
+/** No-op. Kept as a placeholder for future explicit-release strategies
+ *  (e.g. pool release, arena reset). With pure JS GC, scratch buffers
+ *  are reclaimed when the wrapper goes out of scope. */
+export declare function releaseFloat64Array(_buf: Float64Array): void;
+/** Pass-through. Kept as a placeholder for future scratch-arena
+ *  strategies. Today it just runs `fn` and returns its result. */
+export declare function withScratch<T>(fn: () => T): T;

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

@@ -1,13 +1,13 @@
 /**
- * RuntimeValue constructor helpers (the MV namespace).
+ * RuntimeValue constructor helpers (the RTV namespace).
  */
 import { ItemType } from "../lowering/itemTypes.js";
-import { type RuntimeNumber, type RuntimeTensor, type RuntimeString, type RuntimeChar, type RuntimeLogical, type RuntimeCell, type RuntimeStruct, type RuntimeFunction, type RuntimeClassInstance, type RuntimeComplexNumber, type RuntimeDummyHandle, type RuntimeGraphicsHandle, type RuntimeStructArray, type RuntimeSparseMatrix, type RuntimeDictionary, type RuntimeValue, type FloatXArrayType } from "./types.js";
+import { type RuntimeNumber, RuntimeTensor, type RuntimeString, RuntimeChar, type RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeClassInstance, RuntimeComplexNumber, RuntimeDummyHandle, RuntimeGraphicsHandle, RuntimeStructArray, RuntimeSparseMatrix, RuntimeDictionary, type RuntimeValue } from "./types.js";
 export declare const RTV: {
     num(value: number): RuntimeNumber;
-    tensor(data: FloatXArrayType | number[], shape: number[], imag?: FloatXArrayType | number[]): RuntimeTensor;
-    /** Fast tensor constructor — data must be FloatXArray, shape already normalized (no trailing singletons). */
-    tensorRaw(data: FloatXArrayType, shape: number[]): RuntimeTensor;
+    tensor(data: Float64Array | number[], shape: number[], imag?: Float64Array | number[]): RuntimeTensor;
+    /** Fast tensor constructor — data must be Float64Array, shape already normalized (no trailing singletons). */
+    tensorRaw(data: Float64Array, shape: number[]): RuntimeTensor;
     /** Create a scalar tensor (1x1) */
     scalar(value: number): RuntimeNumber;
     /** Create a row vector [1 x n] */
@@ -15,7 +15,7 @@ export declare const RTV: {
     /** Create a column vector [n x 1] */
     col(data: number[], imag?: number[]): RuntimeTensor;
     /** Create a matrix from row-major data */
-    matrix(rows: number, cols: number, data: number[] | FloatXArrayType, imag?: number[] | FloatXArrayType): RuntimeTensor;
+    matrix(rows: number, cols: number, data: number[] | Float64Array, imag?: number[] | Float64Array): RuntimeTensor;
     string(value: string): RuntimeString;
     char(value: string): RuntimeChar;
     logical(value: boolean): RuntimeLogical;

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

@@ -0,0 +1,33 @@
+/**
+ * Refcount-driven copy-on-write helpers.
+ *
+ * The lvalue write path uses these to make sure the chain from the env
+ * root to the leaf is uniquely owned before mutation: at each level, if
+ * the container is shared (`isShared`), it's cloned and the clone is
+ * rebound in the parent. After the chain is unique, in-place mutation
+ * at the leaf is observable only to the LHS variable.
+ */
+import { type RuntimeValue } from "./types.js";
+import { type RefcountRuntime } from "./refcount.js";
+/** Return a fresh wrapper that shadows `v`'s contents but has rc=0
+ *  (modulo scope adoption from the constructor). The new wrapper holds
+ *  its own copy of the underlying buffers (for tensors) or its own
+ *  fields/data array (for containers). Refs to child values are
+ *  shared with the original — child wrappers get incref'd by the new
+ *  container's constructor. Caller is responsible for binding the
+ *  fresh wrapper into the parent slot.
+ *
+ *  Returns the original value unchanged for kinds that don't need to
+ *  be copied (handle-class instances, primitives) — the caller can
+ *  `=== v` test if the copy was a no-op. */
+export declare function cowCopy(v: RuntimeValue): RuntimeValue;
+/** If `v` is shared (rc-driven), return a fresh non-shared copy;
+ *  otherwise return `v` unchanged. The new wrapper has refcount 0
+ *  (or 1 if the active scope adopts it via the constructor); the
+ *  caller must bind it into the parent slot to keep it alive.
+ *
+ *  Returns the original `v` for handle-class instances and primitives —
+ *  callers can `result === v` test to detect a no-op. */
+export declare function cowIfShared(v: RuntimeValue): RuntimeValue;
+export { isShared } from "./refcount.js";
+export type { RefcountRuntime };

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

@@ -1,12 +1,13 @@
-export type { RuntimeValue, RuntimeTensor, RuntimeString, RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeDictionary, } from "./types.js";
+export type { RuntimeValue, RuntimeString, RuntimeLogical } from "./types.js";
+export { RuntimeTensor, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeDictionary, } from "./types.js";
 export { RuntimeError, CancellationError, offsetToLine, offsetToColumn, } from "./error.js";
 export type { CallFrame } from "./error.js";
-export { tensorSize2D, numel, colMajorIndex, shareRuntimeValue, } from "./utils.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 { 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,10 +1,25 @@
 /**
  * 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 */
-export declare function storeIntoRTValueIndex(base: RuntimeValue, indices: RuntimeValue[], rhs: RuntimeValue, parenAssign?: boolean): RuntimeValue;
+export declare function storeIntoRTValueIndex(base: RuntimeValue, indices: RuntimeValue[], rhs: RuntimeValue, parenAssign?: boolean, rt?: StoreRuntime): RuntimeValue;
+export {};

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

@@ -0,0 +1,86 @@
+/**
+ * Plot builtin dispatch — the single source of truth for the
+ * `(name, args)` → `PlotInstruction[]` mapping that every plotting
+ * builtin performs.
+ *
+ * Historically this logic was scattered across two places:
+ *   - `runtime.ts` registered the data-bearing plot names
+ *     (`plot`, `surf`, `imagesc`, …) inside `initBuiltins`.
+ *   - `specialBuiltins.ts` registered the graphics ops (`figure`,
+ *     `title`, `xlabel`, `hold`, `subplot`, `clf`, …) inside
+ *     `registerSpecialBuiltins`.
+ *
+ * Both sites pushed onto `rt.plotInstructions` and (for `hold` /
+ * `tiledlayout` / `nexttile`) updated small flags on the Runtime.
+ * `dispatchPlotBuiltin` is the consolidation. The Runtime registers
+ * each name with a 1-line wrapper that calls this function and then
+ * returns the right `nargout`-handle value; the side-effect (the
+ * push) lives here.
+ *
+ * Out-of-scope names — kept registered separately because their
+ * semantics need the full Runtime context:
+ *   - `fplot` / `fplot3` — evaluate a user function-handle, need
+ *     the Runtime's executor.
+ *   - `drawnow` / `pause` — call the `ExecOptions` callbacks
+ *     (`onDrawnow`, `onPause`).
+ *   - `streamline` / `stream2` — return non-trivial values.
+ *   - `ishold` — reads `state.holdState`, but is a pure query (no
+ *     instructions pushed); the Runtime can call `state.holdState`
+ *     directly.
+ *
+ * Reusable from outside numbl: mtoc2 (the static-translation
+ * sibling project) imports this function to render plots in its
+ * browser IDE without reimplementing per-builtin logic.
+ */
+import type { RuntimeValue } from "./types.js";
+import type { PlotInstruction } from "../../graphics/types.js";
+/** State carried by graphics ops that need to remember things between
+ *  calls. `holdState` is read by `ishold()` so `hold on; if ishold ...`
+ *  works; `tiledLayoutState` lets `nexttile` know where to place the
+ *  next axes. The `Runtime` class implements this interface; mtoc2's
+ *  browser viewer keeps its own instance. */
+export interface PlotDispatchState {
+    holdState: boolean;
+    tiledLayoutState: TiledLayoutState | null;
+}
+/** Active tiled-layout grid. `mode` controls how the grid grows: in
+ *  `flow` (default), nexttile expands rows/cols to fit; `vertical` and
+ *  `horizontal` extend one axis; `fixed` uses the M/N from the
+ *  tiledlayout(M,N) call verbatim. */
+export interface TiledLayoutState {
+    rows: number;
+    cols: number;
+    mode: "fixed" | "flow" | "vertical" | "horizontal";
+    count: number;
+}
+/** Run a single plot-builtin call. Pushes onto `instructions` and
+ *  updates `state` to mirror what numbl's runtime did before this
+ *  refactor. Returns `true` iff `name` was a recognized plot builtin;
+ *  callers fall through to their own dispatch on `false`. */
+export declare function dispatchPlotBuiltin(name: string, args: RuntimeValue[], instructions: PlotInstruction[], state: PlotDispatchState): boolean;
+/** Names handled by `dispatchPlotBuiltin`. Useful for registering all
+ *  of them in a loop (numbl's `initBuiltins` / `registerSpecialBuiltins`
+ *  do that for the side-effect-only subset). Stays in sync with the
+ *  cases above by construction. */
+export declare const PLOT_DISPATCH_NAMES: ReadonlyArray<string>;
+/** Graphics-related names numbl exposes as no-op (or near-no-op)
+ *  stubs — they don't push plot instructions and don't render, but
+ *  numbl accepts them so MATLAB scripts compile and run. Sources:
+ *    - `interpreter/builtins/misc.ts` (`groot`, `gcf`, `gca`, `shg`,
+ *      `newplot`, `xlim`, `ylim`, `set`, `get`, `ishold`)
+ *    - `runtime/specialBuiltins.ts` (`drawnow`, `pause`)
+ *
+ *  These names belong here, alongside `PLOT_DISPATCH_NAMES`, because
+ *  downstream consumers (mtoc2's translator, syntax highlighters,
+ *  doc generators) want to know the full "plot-script surface area"
+ *  numbl tolerates — not just the renderable subset. Keeping the
+ *  union in one place is the whole point of consolidating dispatch
+ *  here. */
+export declare const PLOT_STUB_NAMES: ReadonlyArray<string>;
+/** The union of `PLOT_DISPATCH_NAMES` (renderable) and
+ *  `PLOT_STUB_NAMES` (recognized-but-no-render). Every name a plotting
+ *  script might invoke that numbl tolerates. Mtoc2 imports this to
+ *  drive its own builtin registration so the two repos stay in
+ *  lockstep — when numbl gains a new plot builtin, mtoc2 picks it up
+ *  at the next `tsc` / `vite build` with no mtoc2-side edit. */
+export declare const PLOT_ALL_NAMES: ReadonlyArray<string>;

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, } from "../../graphics/types.js";
-import type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace } from "../../graphics/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 interface ParsedLineSpec {
     color?: string;
     lineStyle?: string;
@@ -222,3 +222,18 @@ export declare function parsePiechartArgs(args: RuntimeValue[], innerRadius: num
  *   heatmap(xvalues, yvalues, cdata) — with axis labels
  */
 export declare function parseHeatmapArgs(args: RuntimeValue[]): HeatmapTrace;
+/**
+ * Parse quiver() arguments.
+ *
+ * Supported forms:
+ *   quiver(U, V)
+ *   quiver(X, Y, U, V)
+ *   quiver(..., scale)        — scale: nonnegative number or 'off'
+ *   quiver(..., LineSpec)
+ *   quiver(..., LineSpec, 'filled')
+ *   quiver(..., Name, Value)  — Color, LineStyle, LineWidth, ShowArrowHead, etc.
+ *
+ * X, Y, U, V can be vectors or matrices. If U,V are matrices and X,Y are
+ * vectors, X and Y are expanded to a meshgrid.
+ */
+export declare function parseQuiverArgs(args: RuntimeValue[]): QuiverTrace[];

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

@@ -0,0 +1,85 @@
+/**
+ * Reference counting for RuntimeValue containers, used both for
+ * lifecycle (decref → _destroy chain) and for refcount-driven COW.
+ *
+ * Every container kind extends `Refcounted`. The count starts at 0
+ * (newly-constructed value, not yet bound to anything), is incremented
+ * when a slot (env binding, struct field, cell element, ...) takes
+ * ownership, and decremented when the slot releases ownership. When the
+ * count reaches 0, `_destroy` runs and decrefs every child value.
+ *
+ * COW uses `effectiveRc(v)` — the count minus the number of currently
+ * active per-statement scopes that hold the value. Scope adoption is
+ * a transient lifecycle artifact (it keeps the wrapper alive across an
+ * expression's evaluation); it isn't an ownership relationship that
+ * should force a copy.
+ *
+ * Strict mode (`rt.strictRefcount`) makes a decref of an already-zero
+ * count throw.
+ */
+export declare function pushCurrentRuntime(rt: RefcountRuntime): void;
+export declare function popCurrentRuntime(rt: RefcountRuntime): void;
+export declare function getCurrentRuntime(): RefcountRuntime | null;
+/** Minimal runtime surface used by the refcount API. The real `Runtime`
+ *  class satisfies this; using an interface here avoids a circular
+ *  import between refcount.ts ↔ runtime.ts ↔ types.ts. */
+export interface RefcountRuntime {
+    /** When true, decref of a zero count throws. */
+    strictRefcount?: boolean;
+    /** Per-statement transient scope. Constructors auto-adopt fresh
+     *  values here so an unbound expression result stays alive until end
+     *  of statement. Null when no statement is in flight. */
+    currentScope?: RefScope | null;
+}
+/** Base class for every refcounted runtime value. */
+export declare abstract class Refcounted {
+    /** Public so type guards can look for a `kind` discriminator without
+     *  walking the prototype. The string is set by every subclass. */
+    abstract readonly kind: string;
+    /** Reference count. Starts at 0; incremented when bound to a slot. */
+    _rc: number;
+    /** Subset of `_rc` contributed by active per-statement scopes. The
+     *  COW check uses `_rc - _scopeHolds` so transient scope holds don't
+     *  force unnecessary copies (a value freshly constructed during a
+     *  statement and passed to a function would otherwise look "shared"
+     *  to the callee). */
+    _scopeHolds: number;
+    constructor();
+    incref(): void;
+    decref(rt: RefcountRuntime): void;
+    /** Subclasses release child refs. Idempotent must NOT be assumed —
+     *  callers guarantee this fires exactly once. Default is a no-op for
+     *  kinds that have no child refs (RuntimeChar, RuntimeComplexNumber,
+     *  RuntimeDummyHandle, etc.). */
+    protected _destroy(_rt: RefcountRuntime): void;
+}
+/** True if the value is a container that participates in refcounting.
+ *  Primitives (number, boolean, string) return false. */
+export declare function isRefcountable(v: unknown): v is Refcounted;
+/** Increment refcount on a value if it's a container; primitives are noop. */
+export declare function incref(v: unknown): void;
+/** Decrement refcount on a value if it's a container; primitives are noop. */
+export declare function decref(rt: RefcountRuntime, v: unknown): void;
+/** True if `v` has more than one external (non-scope) holder — i.e. a
+ *  mutation through one slot would observably affect another holder.
+ *  Primitives return false; primitives can never be "shared" since
+ *  every slot stores a copy of the value. */
+export declare function isShared(v: unknown): boolean;
+/** Per-statement transients harness. Fresh values produced by constructors
+ *  and operators are adopted here at rc=1; on `drain`, every member is
+ *  decref'd. Anything bound to a slot during the statement gets an extra
+ *  incref from the slot, so it survives drain at slot count.
+ *
+ *  Each adopt also increments the value's `_scopeHolds`, which the COW
+ *  check (`isShared`) subtracts from `_rc` — the scope's hold is a
+ *  lifecycle artifact, not an ownership relationship that should force
+ *  a copy. */
+export declare class RefScope {
+    private members;
+    /** Take ownership of a fresh value: incref and remember for drain. */
+    adopt(v: unknown): void;
+    /** Release every adopted value. Called in `withScope`'s finally. */
+    drain(rt: RefcountRuntime): void;
+    /** Number of currently-adopted values (for assertions/tests). */
+    size(): number;
+}