numbl 0.3.0 → 0.3.3

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;
+}

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

@@ -11,6 +11,7 @@
  * runtimeDispatch.ts, and helper types/utilities in runtimeHelpers.ts.
  */
 import { type RuntimeValue, type RuntimeLogical, type RuntimeTensor, type RuntimeStruct, type RuntimeString, type RuntimeFunction, RuntimeError, type CallFrame } from "../runtime/index.js";
+import { RefScope } from "./refcount.js";
 import { RuntimeChar, RuntimeCell, type RuntimeComplexNumber, type RuntimeClassInstance } from "../runtime/types.js";
 import { type ItemType } from "../lowering/itemTypes.js";
 import type { PlotInstruction } from "../../graphics/types.js";
@@ -25,6 +26,12 @@ export declare class Runtime {
     plotInstructions: PlotInstruction[];
     variableValues: Record<string, RuntimeValue>;
     holdState: boolean;
+    tiledLayoutState: {
+        rows: number;
+        cols: number;
+        mode: "fixed" | "flow" | "vertical" | "horizontal";
+        count: number;
+    } | null;
     private cancelFlag;
     $line: number;
     $file: string | null;
@@ -37,12 +44,12 @@ export declare class Runtime {
     END: symbol;
     RTV: {
         num(value: number): import("../runtime/types.js").RuntimeNumber;
-        tensor(data: import("../runtime/types.js").FloatXArrayType | number[], shape: number[], imag?: import("../runtime/types.js").FloatXArrayType | number[]): RuntimeTensor;
-        tensorRaw(data: import("../runtime/types.js").FloatXArrayType, shape: number[]): RuntimeTensor;
+        tensor(data: Float64Array | number[], shape: number[], imag?: Float64Array | number[]): RuntimeTensor;
+        tensorRaw(data: Float64Array, shape: number[]): RuntimeTensor;
         scalar(value: number): import("../runtime/types.js").RuntimeNumber;
         row(data: number[], imag?: number[]): RuntimeTensor;
         col(data: number[], imag?: number[]): RuntimeTensor;
-        matrix(rows: number, cols: number, data: number[] | import("../runtime/types.js").FloatXArrayType, imag?: number[] | import("../runtime/types.js").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;
@@ -60,8 +67,19 @@ export declare class Runtime {
             value: RuntimeValue;
         }>, keyType?: string, valueType?: string): import("../runtime/types.js").RuntimeDictionary;
     };
-    private persistentStore;
+    persistentStore: Map<string, Map<string, RuntimeValue>>;
     $g: Record<string, RuntimeValue>;
+    /** Active per-statement transient scope. New refcounted values are
+     *  auto-adopted into this scope (rc 0→1) on construction so they
+     *  survive long enough to be bound somewhere; on scope drain at end
+     *  of statement, anything still held only by the scope is decref'd
+     *  to 0 and destroyed. Null when no statement is in flight. */
+    currentScope: RefScope | null;
+    /** When true, `decref` on a zero count throws (loud at the
+     *  underflow site rather than silently leaking). On by default — the
+     *  refcount-driven COW system relies on accurate refcounts to make
+     *  correct mutate-vs-copy decisions. */
+    strictRefcount: boolean;
     activeAccessors: Set<string>;
     resolveClassMethod: ((className: string, methodName: string) => ((...args: any[]) => any) | null) | null;
     getClassParent: ((className: string) => string | null) | null;
@@ -112,6 +130,10 @@ export declare class Runtime {
     constructor(options: ExecOptions, initialVariableValues?: Record<string, RuntimeValue> | undefined);
     /** Throw CancellationError if the cancel flag has been set. */
     checkCancel(): void;
+    /** Run `fn` with a fresh `RefScope` as `this.currentScope`. On return,
+     *  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;
     private initBuiltins;
     profileEnter(key: string): void;
     profileLeave(): void;
@@ -146,7 +168,6 @@ export declare class Runtime {
     lg(v: boolean): RuntimeLogical;
     /** Scalar power that returns complex for negative base with fractional exponent */
     pow(a: number, b: number): number | RuntimeComplexNumber;
-    share(v: unknown): RuntimeValue;
     get displayResults(): boolean;
     displayResult(v: unknown): void;
     displayAssign(name: string, v: unknown): void;
@@ -270,68 +291,8 @@ export declare class Runtime {
     memberChainAssign(base: unknown, names: string[], rhs: unknown): unknown;
     narginchk(actualNargin: unknown, minArgs: unknown, maxArgs: unknown): void;
     nargoutchk(actualNargout: unknown, minArgs: unknown, maxArgs: unknown): void;
-    plot_instr(instr: {
-        type: "set_figure_handle";
-        handle: unknown;
-    } | {
-        type: "plot";
-        x: unknown;
-        y: unknown;
-    } | {
-        type: "set_hold";
-        value: unknown;
-    } | {
-        type: "close";
-    } | {
-        type: "close_all";
-    } | {
-        type: "clf";
-    } | {
-        type: "set_subplot";
-        rows: unknown;
-        cols: unknown;
-        index: unknown;
-    } | {
-        type: "set_sgtitle";
-        text: unknown;
-    } | {
-        type: "set_grid";
-        value: unknown;
-    }): void;
+    /** Read the hold state, for `ishold()` queries. */
     ishold(): RuntimeValue;
-    plot_call(args: RuntimeValue[]): void;
-    plot3_call(args: RuntimeValue[]): void;
-    surf_call(args: RuntimeValue[]): void;
-    scatter_call(args: RuntimeValue[]): void;
-    imagesc_call(args: RuntimeValue[]): void;
-    pcolor_call(args: RuntimeValue[]): void;
-    contour_call(args: RuntimeValue[], filled: boolean): void;
-    mesh_call(args: RuntimeValue[]): void;
-    bar_call(args: RuntimeValue[]): void;
-    barh_call(args: RuntimeValue[]): void;
-    bar3_call(args: RuntimeValue[]): void;
-    bar3h_call(args: RuntimeValue[]): void;
-    stairs_call(args: RuntimeValue[]): void;
-    errorbar_call(args: RuntimeValue[]): void;
-    semilogx_call(args: RuntimeValue[]): void;
-    semilogy_call(args: RuntimeValue[]): void;
-    loglog_call(args: RuntimeValue[]): void;
-    area_call(args: RuntimeValue[]): void;
-    fplot_call(args: RuntimeValue[]): void;
-    fplot3_call(args: RuntimeValue[]): void;
-    scatter3_call(args: RuntimeValue[]): void;
-    histogram_call(args: RuntimeValue[]): void;
-    histogram2_call(args: RuntimeValue[]): void;
-    boxchart_call(args: RuntimeValue[]): void;
-    swarmchart_call(args: RuntimeValue[]): void;
-    swarmchart3_call(args: RuntimeValue[]): void;
-    piechart_call(args: RuntimeValue[]): void;
-    donutchart_call(args: RuntimeValue[]): void;
-    heatmap_call(args: RuntimeValue[]): void;
-    streamline_call(args: RuntimeValue[]): RuntimeValue;
-    stream2_call(args: RuntimeValue[]): RuntimeValue;
-    view_call(args: RuntimeValue[]): void;
-    legend_call(args: RuntimeValue[]): void;
     drawnow(): void;
     pause(seconds: unknown): void;
     readInput(prompt: string): string;

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

@@ -4,12 +4,12 @@
  * Standalone functions that take the Runtime instance as the first parameter.
  * Handles function/class dispatch, arrayfun/cellfun/bsxfun, and subsref/subsasgn.
  */
-import { type RuntimeValue, type RuntimeLogical, type RuntimeFunction } from "../runtime/index.js";
+import { type RuntimeValue, type RuntimeLogical, RuntimeFunction } from "../runtime/index.js";
 import type { Runtime } from "./runtime.js";
 export declare function getFuncHandle(name: string): RuntimeFunction;
 export declare function makeUserFuncHandle(jsFn: (...args: unknown[]) => unknown, nargin?: number): RuntimeFunction;
 export declare function isa(rt: Runtime, value: unknown, classNameArg: unknown): RuntimeLogical;
-export declare function callSuperConstructor(target: unknown, superInstance: unknown): RuntimeValue;
+export declare function callSuperConstructor(target: unknown, superInstance: unknown, rt?: Runtime): RuntimeValue;
 export declare function createClassInstance(_rt: Runtime, className: string, propertyNames: string[], defaults?: Record<string, unknown>, isHandleClass?: boolean): RuntimeValue;
 export declare function dispatch(rt: Runtime, name: string, nargout: number, args: unknown[], targetClassName?: string): unknown;
 /** Direct builtin call — skips local/workspace/registry lookup. */

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

@@ -20,9 +20,9 @@ export declare function indexStore(rt: Runtime, base: unknown, indices: unknown[
 /**
  * Cell-indexed assignment (curly braces).
  */
-export declare function indexCellStore(base: unknown, indices: unknown[], rhs: unknown): unknown;
+export declare function indexCellStore(base: unknown, indices: unknown[], rhs: unknown, rt?: import("./refcount.js").RefcountRuntime): unknown;
 /**
  * Multi-output assignment to cell elements: [c{idx}] = func()
  * Distributes individual results to individual cell positions.
  */
-export declare function multiOutputCellAssign(base: unknown, indices: unknown, results: unknown[]): unknown;
+export declare function multiOutputCellAssign(base: unknown, indices: unknown, results: unknown[], rt?: import("./refcount.js").RefcountRuntime): unknown;

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

@@ -7,7 +7,7 @@ export declare function getMember(rt: Runtime, base: unknown, name: string): unk
 export declare function getMemberDynamic(base: unknown, nameExpr: unknown): RuntimeValue;
 export declare function getMemberOrEmpty(base: unknown, name: string): RuntimeValue;
 export declare function setMemberReturn(rt: Runtime, base: unknown, name: string, rhs: unknown): unknown;
-export declare function setMemberDynamicReturn(base: unknown, nameExpr: unknown, rhs: unknown): RuntimeValue;
+export declare function setMemberDynamicReturn(rt: Runtime, base: unknown, nameExpr: unknown, rhs: unknown): RuntimeValue;
 /**
  * Call a user-defined subsref method on a class instance.
  * Constructs S = struct('type', '.', 'subs', name) for each name in the chain.

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

@@ -100,6 +100,7 @@ export declare function swarmchart3Call(plotInstructions: PlotInstruction[], arg
 export declare function piechartCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 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 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/struct-access.d.ts

@@ -2,5 +2,6 @@
  * Struct and class instance field access.
  */
 import { type RuntimeValue } from "./types.js";
+import { type RefcountRuntime } from "./refcount.js";
 export declare function getRTValueField(base: RuntimeValue, field: string): RuntimeValue;
-export declare function setRTValueField(base: RuntimeValue, field: string, value: RuntimeValue): RuntimeValue;
+export declare function setRTValueField(base: RuntimeValue, field: string, value: RuntimeValue, rt?: RefcountRuntime): RuntimeValue;

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

@@ -1,6 +1,5 @@
+import { Refcounted, type RefcountRuntime } from "./refcount.js";
 export declare const USE_FLOAT32: boolean;
-export declare const FloatXArray: Float32ArrayConstructor | Float64ArrayConstructor;
-export type FloatXArrayType = Float32Array | Float64Array;
 export type RuntimeValue = number | boolean | string | RuntimeTensor | RuntimeChar | RuntimeCell | RuntimeStruct | RuntimeFunction | RuntimeClassInstance | RuntimeComplexNumber | RuntimeDummyHandle | RuntimeGraphicsHandle | RuntimeStructArray | RuntimeClassInstanceArray | RuntimeSparseMatrix | RuntimeDictionary;
 export type RuntimeNumber = number;
 export type RuntimeLogical = boolean;
@@ -22,104 +21,147 @@ export declare const isRuntimeClassInstanceArray: (value: RuntimeValue) => value
 export declare const isRuntimeSparseMatrix: (value: RuntimeValue) => value is RuntimeSparseMatrix;
 export declare const isRuntimeDictionary: (value: RuntimeValue) => value is RuntimeDictionary;
 export declare const kstr: (value: RuntimeValue) => string;
-export type RuntimeTensor = {
-    kind: "tensor";
-    data: FloatXArrayType;
-    imag?: FloatXArrayType;
+export declare class RuntimeTensor extends Refcounted {
+    readonly kind: "tensor";
+    data: Float64Array;
+    imag: Float64Array | undefined;
     shape: number[];
-    /** When true, this tensor represents a logical (boolean) array from comparisons/logical ops. */
-    _isLogical?: boolean;
-    /** Reference count for copy-on-write. When > 1, data is shared and must be copied before mutation. */
-    _rc: number;
-};
-export type RuntimeChar = {
-    kind: "char";
+    /** When true, this tensor represents a logical (boolean) array from
+     *  comparisons/logical ops. */
+    _isLogical: boolean | undefined;
+    constructor(data: Float64Array, shape: number[], imag?: Float64Array, _isLogical?: boolean);
+}
+export declare class RuntimeChar extends Refcounted {
+    readonly kind: "char";
     value: string;
-    /** Optional shape for multi-row char arrays. If absent, shape is [1, value.length].
-     *  For multi-row arrays, value contains all rows concatenated (each row is shape[1] chars). */
-    shape?: number[];
-};
-export type RuntimeCell = {
-    kind: "cell";
+    /** Optional shape for multi-row char arrays. If absent, shape is
+     *  [1, value.length]. For multi-row arrays, value contains all rows
+     *  concatenated (each row is shape[1] chars). */
+    shape: number[] | undefined;
+    constructor(value: string, shape?: number[]);
+}
+export declare class RuntimeCell extends Refcounted {
+    readonly kind: "cell";
     data: RuntimeValue[];
     shape: number[];
-    /** Reference count for copy-on-write. When > 1, data is shared and must be copied before mutation. */
-    _rc: number;
-};
-export type RuntimeStruct = {
-    kind: "struct";
+    constructor(data: RuntimeValue[], shape: number[]);
+    /** Replace element at idx, decref-old / incref-new. Caller resizes the
+     *  shape if necessary; this method does not touch shape. */
+    bindElement(rt: RefcountRuntime, idx: number, value: RuntimeValue): void;
+    protected _destroy(rt: RefcountRuntime): void;
+}
+export declare class RuntimeStruct extends Refcounted {
+    readonly kind: "struct";
     fields: Map<string, RuntimeValue>;
-};
-export type RuntimeFunction = {
-    kind: "function";
+    constructor(fields: Map<string, RuntimeValue>);
+    /** Set/replace a field value, decref-old / incref-new. */
+    bindField(rt: RefcountRuntime, name: string, value: RuntimeValue): void;
+    protected _destroy(rt: RefcountRuntime): void;
+}
+export declare class RuntimeFunction extends Refcounted {
+    readonly kind: "function";
     name: string;
     /** For closures: captured variables */
     captures: RuntimeValue[];
     /** The underlying callable — either a builtin or user-defined function name */
     impl: "builtin" | "user";
     /** For anonymous functions and user function handles: the underlying JS closure */
-    jsFn?: (...args: unknown[]) => unknown;
+    jsFn: ((...args: unknown[]) => unknown) | undefined;
     /** When true, jsFn expects nargout as its first argument */
-    jsFnExpectsNargout?: boolean;
+    jsFnExpectsNargout: boolean | undefined;
     /** Number of input parameters (for nargin(handle)) */
-    nargin?: number;
-};
-export type RuntimeClassInstance = {
-    kind: "class_instance";
+    nargin: number | undefined;
+    /** Cleanup hook fired by `_destroy`. Anonymous functions use this to
+     *  decref values held in their captured environment snapshot, since
+     *  those refs live in the JS closure (not in `captures`). */
+    releaseExtra: ((rt: RefcountRuntime) => void) | undefined;
+    /** For anonymous-function snapshots: the captured environment, made
+     *  visible to the alias sweep so a tensor stored both here and in
+     *  the parent env triggers copy-on-write on parent-side mutations.
+     *  (Only the structural shape `{ vars, parent }` is needed; typed
+     *  loosely to avoid a runtime↔interpreter circular import.) */
+    capturedEnv: {
+        vars: Map<string, RuntimeValue>;
+        parent?: unknown;
+    } | undefined;
+    constructor(name: string, impl: "builtin" | "user", captures: RuntimeValue[], jsFn?: (...args: unknown[]) => unknown, jsFnExpectsNargout?: boolean, nargin?: number);
+    protected _destroy(rt: RefcountRuntime): void;
+}
+export declare class RuntimeClassInstance extends Refcounted {
+    readonly kind: "class_instance";
     className: string;
     fields: Map<string, RuntimeValue>;
     /** True if this class inherits from handle (reference semantics). */
     isHandleClass: boolean;
     /** For classes that inherit from built-in types (e.g. classdef Foo < double),
      *  stores the underlying built-in data. */
-    _builtinData?: RuntimeValue;
-};
+    _builtinData: RuntimeValue | undefined;
+    constructor(className: string, fields: Map<string, RuntimeValue>, isHandleClass: boolean, _builtinData?: RuntimeValue);
+    /** Set/replace a field value (handle-class in-place mutation), with
+     *  proper decref-old / incref-new bookkeeping. Used for handle-class
+     *  field assigns; value-class field assigns construct a new instance. */
+    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. */
-export type RuntimeClassInstanceArray = {
-    kind: "class_instance_array";
+export declare class RuntimeClassInstanceArray extends Refcounted {
+    readonly kind: "class_instance_array";
     className: string;
     elements: RuntimeClassInstance[];
-};
-export type RuntimeComplexNumber = {
-    kind: "complex_number";
+    constructor(className: string, elements: RuntimeClassInstance[]);
+    protected _destroy(rt: RefcountRuntime): void;
+}
+export declare class RuntimeComplexNumber extends Refcounted {
+    readonly kind: "complex_number";
     re: number;
     im: number;
-};
-export type RuntimeDummyHandle = {
-    kind: "dummy_handle";
-};
+    constructor(re: number, im: number);
+}
+export declare class RuntimeDummyHandle extends Refcounted {
+    readonly kind: "dummy_handle";
+    constructor();
+}
 /** Handle to a graphics object (e.g. surface returned by pcolor) with a mutable trace reference. */
-export type RuntimeGraphicsHandle = {
-    kind: "graphics_handle";
+export declare class RuntimeGraphicsHandle extends Refcounted {
+    readonly kind: "graphics_handle";
     _trace: Record<string, unknown>;
     _traceType: string;
-};
-/** A 1-D array of structs that all share the same field names. **/
-export type RuntimeStructArray = {
-    kind: "struct_array";
+    constructor(_trace: Record<string, unknown>, _traceType: string);
+}
+/** A 1-D array of structs that all share the same field names. */
+export declare class RuntimeStructArray extends Refcounted {
+    readonly kind: "struct_array";
     fieldNames: string[];
     elements: RuntimeStruct[];
-};
-/** Sparse matrix in CSC (Compressed Sparse Column) format, matching MATLAB's internal representation. */
-export type RuntimeSparseMatrix = {
-    kind: "sparse_matrix";
+    constructor(fieldNames: string[], elements: RuntimeStruct[]);
+    protected _destroy(rt: RefcountRuntime): void;
+}
+/** Sparse matrix in CSC (Compressed Sparse Column) format, matching MATLAB's
+ *  internal representation. */
+export declare class RuntimeSparseMatrix extends Refcounted {
+    readonly kind: "sparse_matrix";
     m: number;
     n: number;
     ir: Int32Array;
     jc: Int32Array;
     pr: Float64Array;
-    pi?: Float64Array;
-    _rc: number;
-};
+    pi: Float64Array | undefined;
+    constructor(m: number, n: number, ir: Int32Array, jc: Int32Array, pr: Float64Array, pi?: Float64Array);
+}
 /** Dictionary mapping unique keys to values (MATLAB R2022b+). */
-export type RuntimeDictionary = {
-    kind: "dictionary";
+export declare class RuntimeDictionary extends Refcounted {
+    readonly kind: "dictionary";
     /** Entries keyed by a hash string of the RuntimeValue key, preserving insertion order. */
     entries: Map<string, {
         key: RuntimeValue;
         value: RuntimeValue;
     }>;
-    keyType?: string;
-    valueType?: string;
-};
+    keyType: string | undefined;
+    valueType: string | undefined;
+    constructor(entries?: Map<string, {
+        key: RuntimeValue;
+        value: RuntimeValue;
+    }>, keyType?: string, valueType?: string);
+    protected _destroy(rt: RefcountRuntime): void;
+}

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

@@ -1,7 +1,7 @@
 /**
- * Tensor shape/indexing utilities and copy-on-write helpers.
+ * Tensor shape/indexing utilities.
  */
-import { type RuntimeValue, type RuntimeTensor } from "./types.js";
+import { type RuntimeTensor } from "./types.js";
 /** Get 2D size (rows, cols) from shape, padding with 1s as needed.
  *  For N-D tensors (N>2), trailing dimensions are collapsed into cols,
  *  matching MATLAB's behavior when fewer subscripts than dimensions. */
@@ -14,9 +14,3 @@ 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;
-/**
- * Share an RuntimeValue for assignment (COW): increments refcount on tensors/cells
- * so that mIndexStore knows to copy before mutating.
- * Returns a new wrapper object that shares the same underlying data.
- */
-export declare function shareRuntimeValue(v: RuntimeValue): RuntimeValue;

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