numbl 0.4.7 → 0.4.9

package/dist-browser/numbl-core/interpreter/builtins/logical.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Logical builtins: or, and, not.
+ *
+ * Functional forms of `|`, `&`, and `~`. Mirror the corresponding operator
+ * implementations in runtimeOperators.ts so `or(a, b)` behaves the same as
+ * `a | b`, etc. (`xor` is registered separately in reductions.ts and uses a
+ * broadcast-aware implementation.)
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/math.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Unary math builtins: trig, hyperbolic, exp/log, rounding, abs, sqrt, sign.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/misc.d.ts

@@ -0,0 +1,7 @@
+import type { RuntimeValue } from "../../runtime/types.js";
+/** Clear all appdata — called at the start of each executeCode to isolate
+ *  runs. Decrefs every stored value so the previous run's containers can
+ *  hit rc=0 cleanly; if the previous runtime is gone (test harness), we
+ *  just drop the JS references and let GC reclaim them. */
+export declare function resetAppdataStore(): void;
+export declare function convertJsonValue(val: unknown): RuntimeValue;

package/dist-browser/numbl-core/interpreter/builtins/numerical.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Numerical builtins for the interpreter system:
+ * conv, deconv, polyval, polyfit, trapz, cumtrapz, gradient,
+ * interp1, roots, poly, cov, corrcoef, accumarray.
+ *
+ * These are thin wrappers that delegate to the legacy implementations
+ * (which are already well-tested) while registering as IBuiltins for
+ * proper JIT type inference.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/predicates.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Predicate builtins: isnan, isinf, isfinite, isreal.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/prng.d.ts

@@ -0,0 +1,4 @@
+/**
+ * PRNG builtins: rand, randn, randi, randperm, rng.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/reductions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Interpreter IBuiltins for reduction operations:
+ * sum, prod, mean, std, var, median, mode, any, all,
+ * cumsum, cumprod, cummax, cummin, diff.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/set-operations.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Set and search builtins for the interpreter: find, sort, setdiff, ismember.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/sparse.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Sparse matrix builtins: sparse, speye, spdiags, spconvert.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/special-math.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Special math builtins: airy, ellipj, legendre, besselj, bessely, besseli, besselk.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/string-extras.d.ts

@@ -0,0 +1,5 @@
+/**
+ * String builtins that return cell arrays or have complex output modes:
+ * strsplit, strjoin, regexp, regexpi, regexprep, symvar.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/strings.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Interpreter IBuiltins for string/char operations.
+ *
+ * Functions that involve cell arrays (strsplit, strjoin, symvar, regexp/regexpi)
+ * or the parser (symvar) are left to legacy builtins since JitType has no cell kind.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/time-system.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Time and system builtins: tic, toc, clock, etime, warning, computer, version,
+ * ismac, ispc, isunix.
+ */
+export declare function getTicTime(): number;
+export declare function setTicTime(ms: number): void;

package/dist-browser/numbl-core/interpreter/builtins/type-constructors.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Type constructor builtins: double, logical, complex, cell, struct, full,
+ * isfield, deal, func2str.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * IBuiltin interface, registry, and shared helpers for interpreter builtins.
+ */
+import type { RuntimeValue } from "../../runtime/types.js";
+import { RuntimeTensor, RuntimeComplexNumber } from "../../runtime/types.js";
+import { type JitType } from "../../jitTypes.js";
+export interface IBuiltinResolution {
+    outputTypes: JitType[];
+    apply: (args: RuntimeValue[], nargout: number) => RuntimeValue | RuntimeValue[];
+}
+export interface BuiltinHelp {
+    signatures: string[];
+    description: string;
+}
+export interface IBuiltin {
+    name: string;
+    help?: BuiltinHelp;
+    /** Given input JIT types + nargout, return output types and a specialized apply, or null. */
+    resolve: (argTypes: JitType[], nargout: number) => IBuiltinResolution | null;
+}
+export declare function getIBuiltin(name: string): IBuiltin | undefined;
+export declare function registerIBuiltin(b: IBuiltin): void;
+/** Register a dynamic IBuiltin (e.g. .js user functions), replacing any
+ *  existing entry with the same name without error. */
+export declare function registerDynamicIBuiltin(b: IBuiltin): void;
+export declare function unregisterIBuiltin(name: string): void;
+export declare function getAllIBuiltinNames(): string[];
+export declare function getIBuiltinHelp(name: string): BuiltinHelp | undefined;
+export declare function registerBuiltinHelp(name: string, help: BuiltinHelp): void;
+/** Probe an IBuiltin to determine its nargin (number of input args).
+ *  Tries resolve with 1, 2, 3 number-type args to find the accepted count. */
+export declare function getIBuiltinNargin(name: string): number | undefined;
+export declare function inferJitType(value: unknown): JitType;
+export declare function mkc(re: number, im: number): number | RuntimeComplexNumber;
+export declare function makeTensor(data: Float64Array, imag: Float64Array | undefined, shape: number[]): RuntimeTensor;
+/** Type rule requiring two scalar numbers */
+export declare function binaryNumberOnly(argTypes: JitType[]): JitType[] | null;
+export declare function applyUnaryElemwise(v: RuntimeValue, realFn: (x: number) => number, complexFn: (re: number, im: number) => {
+    re: number;
+    im: number;
+}, name: string): RuntimeValue;
+/** Apply a binary scalar function */
+export declare function applyBinaryScalar(args: RuntimeValue[], fn: (a: number, b: number) => number, name: string): RuntimeValue;
+/** Apply a binary element-wise function supporting scalars, tensors, and broadcast. */
+export declare function applyBinaryElemwise(args: RuntimeValue[], fn: (a: number, b: number) => number, name: string): RuntimeValue;
+/** Match a binary function accepting number/boolean/tensor args (no complex). */
+export declare function binaryElemwiseMatch(argTypes: JitType[]): JitType[] | null;
+/** A single case in a builtin's dispatch table. Bundles type-level matching
+ *  with runtime implementation so the two paths cannot diverge. */
+export interface BuiltinCase {
+    /** Return output types if this case handles the given arg types, or null. */
+    match: (argTypes: JitType[], nargout: number) => JitType[] | null;
+    /** Runtime implementation — only called when match succeeded. */
+    apply: (args: RuntimeValue[], nargout: number) => RuntimeValue | RuntimeValue[];
+}
+/** Register an IBuiltin from a list of cases. The first matching case wins. */
+export declare function defineBuiltin(opts: {
+    name: string;
+    help?: BuiltinHelp;
+    cases: BuiltinCase[];
+}): void;
+type NumberJitType = Extract<JitType, {
+    kind: "number";
+}>;
+type BooleanJitType = Extract<JitType, {
+    kind: "boolean";
+}>;
+type ComplexJitType = Extract<JitType, {
+    kind: "complex_or_number";
+}>;
+type TensorJitType = Extract<JitType, {
+    kind: "tensor";
+}>;
+interface UnaryElemwiseSpec {
+    numberType?: (a: NumberJitType) => JitType | null;
+    booleanType?: (a: BooleanJitType) => JitType | null;
+    complexType?: (a: ComplexJitType) => JitType | null;
+    tensorType?: (a: TensorJitType) => JitType | null;
+    realFn: (x: number) => number;
+    complexFn: (re: number, im: number) => {
+        re: number;
+        im: number;
+    };
+    /** Use applyUnaryElemwiseMaybeComplex instead of applyUnaryElemwise */
+    maybeComplex?: boolean;
+    /** Opcode for the native unaryElemwise dispatch (see unary_elemwise.cpp).
+     * Used by the maybeComplex path so that e.g. sqrt/log can run in native C
+     * on the common all-in-domain case, then fall back for NaN entries only. */
+    nativeOpCode?: number;
+}
+/** Generate cases for a unary element-wise builtin. Each accepted kind gets
+ *  its own case that bundles the type rule with the corresponding apply. */
+export declare function unaryElemwiseCases(spec: UnaryElemwiseSpec, name: string): BuiltinCase[];
+/** Shorthand: build cases where all kinds return always-real output. */
+export declare function unaryRealResultCases(realFn: (x: number) => number, complexFn: (re: number, im: number) => number, name: string): BuiltinCase[];
+/** Build cases for numeric predicates (isnan, isinf, isfinite) that return logical. */
+export declare function predicateCases(scalarTest: (x: number) => boolean, complexTest: (re: number, im: number) => boolean, tensorTest: (x: number) => boolean, tensorComplexTest: (re: number, im: number) => boolean, name: string): BuiltinCase[];
+export {};

package/dist-browser/numbl-core/interpreter/builtins/utility.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Utility builtins for JIT: isequal, assert, error, abs.
+ */
+export {};

package/dist-browser/numbl-core/interpreter/builtins/validation.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Validation builtins: mustBe* family.
+ */
+export {};

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

@@ -0,0 +1,199 @@
+/**
+ * AST-walking interpreter for MATLAB code.
+ *
+ * Walks the parsed AST directly without lowering or codegen.
+ * All dispatch decisions are made at runtime using actual values.
+ *
+ * Reuses LoweringContext and FunctionIndex from the lowering pipeline
+ * for workspace registration, class extraction, and function resolution.
+ *
+ * The Interpreter class is defined here with all fields.
+ * Methods are split across:
+ *   - interpreterExec.ts   (statement + expression evaluation)
+ *   - interpreterFunctions.ts (function call, resolution, class methods)
+ */
+import type { AbstractSyntaxTree } from "../parser/types.js";
+import type { Runtime } from "../runtime/runtime.js";
+import type { RuntimeValue } from "../runtime/types.js";
+import type { LoweringContext, FunctionIndex } from "../lowering/loweringContext.js";
+import { type ResolvedTarget } from "../functionResolve.js";
+import { Environment, type FunctionDef, type ControlSignal } from "./types.js";
+import type { Stmt, Expr, LValue } from "../parser/types.js";
+import type { ClassInfo } from "../lowering/classInfo.js";
+export declare class Interpreter {
+    /** @internal */ env: Environment;
+    ans: RuntimeValue | undefined;
+    /** @internal */ ctx: LoweringContext;
+    /** @internal */ functionIndex: FunctionIndex;
+    /** @internal */ rt: Runtime;
+    /** @internal */ currentFile: string;
+    /** @internal */ currentClassName: string | undefined;
+    /** @internal */ currentMethodName: string | undefined;
+    /** @internal */ mainLocalFunctions: Map<string, FunctionDef>;
+    /** @internal The main script (workspace) environment — for evalin/assignin('workspace', ...) */
+    workspaceEnv: Environment | undefined;
+    /** @internal The caller's environment — for evalin/assignin('caller', ...) */
+    callerEnv: Environment | undefined;
+    /** @internal Call-site variable names for the next user-function call, set
+     *  by `evalFuncCall` and consumed by `callUserFunction` to support
+     *  `inputname`. One-shot: cleared as soon as it is consumed. */
+    pendingInputNames: string[] | undefined;
+    /** @internal Stack of [base, dimIndex, numIndices] for resolving `end` keyword in indexing. */
+    endContextStack: Array<{
+        base: unknown;
+        dimIndex: number;
+        numIndices: number;
+    }>;
+    /** @internal Number of enclosing `for` / `while` loop bodies the
+     *  interpreter is currently inside. Bumped on body entry, decremented
+     *  on exit. Read by the executor registry's `propose()` to gate JIT
+     *  attempts: when `loopDepth > 0`, the interpreter is iterating a
+     *  hot loop and per-call JIT lookup overhead / spec-cache thrashing
+     *  is a net loss. Once mtoc2 successfully JITs an outer call, the
+     *  nested loops execute inside the compiled artifact and the
+     *  interpreter never sees them, so this gate only fires on calls
+     *  that genuinely happen at the interpreter level inside a loop. */
+    loopDepth: number;
+    /** @internal Number of enclosing conditional blocks (`if` / `switch` /
+     *  `try`) whose bodies the interpreter is currently executing. Used by
+     *  the loop classifier: when a loop is dispatched with `condBlockDepth >
+     *  0` (or `loopDepth > 0`), its sibling list is a nested block, so the
+     *  post-loop liveness scan can't see reads after the enclosing block —
+     *  the classifier must then keep every loop-assigned name live-out. */
+    condBlockDepth: number;
+    /** @internal */
+    functionDefCache: Map<string, FunctionDef>;
+    /** @internal Pre-built line break tables for offset→line lookup per file. */
+    lineTableCache: Map<string, number[]>;
+    /** @internal file→source mapping for line number computation */
+    fileSources: Map<string, string>;
+    /** @internal Guard against infinite recursion in compileSpecialized */
+    compileInProgress: Set<string>;
+    /**
+     * Optimization mode:
+     *   "0" — pure AST interpreter, no JIT.
+     *   "1" — JS-JIT (default): top-level + call shapes get
+     *         type-specialized JS via the JIT's `compileSpec`.
+     *   "2" — C-JIT: scalar/tensor kernels via `compileSpecC` + koffi.
+     */
+    optimization: import("../executors/plugins.js").OptLevel;
+    /** Callback for JIT compilation logging. `lang` distinguishes the
+     *  emitted source: `"js"` for the JS-JIT backend, `"c"` for the
+     *  C-JIT backend (both can fire in a single `--opt 2` run). */
+    onJitCompile?: (description: string, code: string, lang: "js" | "c") => void;
+    /** Called when a JIT-compiled unit bails back to the interpreter at
+     *  RUNTIME (as opposed to declining at compile time). Today the sole
+     *  trigger is an indexed-store array growth that's only detectable at
+     *  runtime — the JIT can't model the grown shape, so it bails and the
+     *  interpreter re-runs the whole scope with full MATLAB semantics.
+     *  Surfaced as a warning (the CLI routes it to stderr); a compile-time
+     *  decline stays silent (it's the normal "not JIT-able" path). */
+    onJitBail?: (message: string) => void;
+    /** Bridge for loading native shared libraries. Undefined in browser
+     *  contexts. */
+    nativeBridge?: import("../workspace/types.js").NativeBridge;
+    /** Telemetry: invoked after a registered executor's `run()` succeeds.
+     *  Used to track which optimizers fire in a session. The kind is the
+     *  LoweredStmt kind the executor handled ("top-level", "loop", "call",
+     *  ...). Hot path — keep the callback cheap. */
+    onExecutorFired?: (name: string, kind: string) => void;
+    /** Verbose log sink (plumbed from ExecOptions.log). */
+    log?: (message: string) => void;
+    /** Executor registry. Holds the strategies (JS-JIT, C-kernel, ...)
+     *  the dispatcher selects among at runtime. The AST interpreter is
+     *  the dispatcher's hardcoded fallback (not a registered executor).
+     *  Mode-driven plugins (`--opt 1`, `--opt 2`, ...) register
+     *  executors during `executeCode` setup. See
+     *  docs/developer_reference/executors.md. */
+    readonly registry: import("../executors/registry.js").Registry;
+    constructor(rt: Runtime, ctx: LoweringContext, functionIndex: FunctionIndex, mainFileName: string, initialVariableValues?: Record<string, RuntimeValue>);
+    /** Clear all JIT and function resolution caches. Called after addpath/rmpath. */
+    clearAllCaches(): void;
+    /** Wire up runtime callbacks so dispatch() routes through the interpreter. */
+    installRuntimeCallbacks(): void;
+    /** Run a complete AST (main script). */
+    run(ast: AbstractSyntaxTree): void;
+    /** Get variable values for ExecResult. */
+    getVariableValues(): Record<string, RuntimeValue>;
+    execStmt: (stmt: Stmt) => ControlSignal | null;
+    execStmts: (stmts: Stmt[]) => ControlSignal | null;
+    execBlockStmts: (stmts: Stmt[]) => ControlSignal | null;
+    evalExpr: (expr: Expr) => unknown;
+    evalExprNargout: (expr: Expr, nargout: number) => unknown;
+    evalBinary: (expr: Extract<Expr, {
+        type: "Binary";
+    }>) => unknown;
+    evalCondition: (expr: Expr) => unknown;
+    evalUnary: (expr: Extract<Expr, {
+        type: "Unary";
+    }>) => unknown;
+    evalRange: (expr: Extract<Expr, {
+        type: "Range";
+    }>) => unknown;
+    evalFuncCall: (expr: Extract<Expr, {
+        type: "FuncCall";
+    }>, nargout: number) => unknown;
+    evalIndex: (expr: Extract<Expr, {
+        type: "Index";
+    }>) => unknown;
+    evalIndexCell: (expr: Extract<Expr, {
+        type: "IndexCell";
+    }>) => unknown;
+    evalIndicesWithEnd: (base: unknown, indexExprs: Expr[]) => unknown[];
+    evalArgs: (argExprs: Expr[]) => unknown[];
+    evalMember: (expr: Extract<Expr, {
+        type: "Member";
+    }>, nargout: number) => unknown;
+    tryExtractDottedName: (expr: Expr) => string | null;
+    evalAnonFunc: (expr: Extract<Expr, {
+        type: "AnonFunc";
+    }>) => RuntimeValue;
+    makeFuncHandle: (name: string) => RuntimeValue;
+    evalTensorLiteral: (expr: Extract<Expr, {
+        type: "Tensor";
+    }>) => unknown;
+    evalCellLiteral: (expr: Extract<Expr, {
+        type: "Cell";
+    }>) => unknown;
+    assignLValue: (lv: LValue, value: RuntimeValue) => void;
+    writeLValueBase: (base: Expr, value: RuntimeValue) => void;
+    evalLValueBase: (base: Expr, defaultVal: RuntimeValue) => unknown;
+    switchMatch: (switchVal: unknown, caseVal: unknown) => boolean;
+    isOutputExpr: (expr: Expr) => boolean;
+    callFunction: (name: string, args: unknown[], nargout: number) => unknown;
+    declaredNargin: (name: string) => number | undefined;
+    interpretTarget: (target: ResolvedTarget, args: unknown[], nargout: number) => unknown;
+    interpretLocalFunction: (target: Extract<ResolvedTarget, {
+        kind: "localFunction";
+    }>, args: unknown[], nargout: number) => unknown;
+    interpretWorkspaceFunction: (target: Extract<ResolvedTarget, {
+        kind: "workspaceFunction";
+    }>, args: unknown[], nargout: number) => unknown;
+    interpretJsUserFunction: (target: Extract<ResolvedTarget, {
+        kind: "jsUserFunction";
+    }>, args: unknown[], nargout: number) => unknown;
+    interpretClassMethod: (target: Extract<ResolvedTarget, {
+        kind: "classMethod";
+    }>, args: unknown[], nargout: number) => unknown;
+    interpretPrivateFunction: (target: Extract<ResolvedTarget, {
+        kind: "privateFunction";
+    }>, args: unknown[], nargout: number) => unknown;
+    instantiateClass: (className: string, args: unknown[], nargout: number) => unknown;
+    interpretConstructor: (classInfo: ClassInfo, args: unknown[], nargout: number) => unknown;
+    callUserFunction: (fn: FunctionDef, args: unknown[], nargout: number, narginOverride?: number) => unknown;
+    callNestedFunction: (fn: FunctionDef, parentEnv: Environment, args: unknown[], nargout: number) => unknown;
+    withFileContext: <T>(file: string, className: string | undefined, methodName: string | undefined, fn: () => T) => T;
+    getWorkspaceFileName: (funcName: string) => string;
+    getClassFileName: (className: string) => string;
+    findFunctionInWorkspaceFile: (wsName: string, funcName: string) => FunctionDef | null;
+    findFunctionInClassFile: (className: string, funcName: string, methodScope?: string) => FunctionDef | null;
+    findMethodInClass: (classInfo: ClassInfo, methodName: string) => FunctionDef | null;
+    findExternalMethod: (classInfo: ClassInfo, methodName: string) => FunctionDef | null;
+    collectClassProperties: (classInfo: ClassInfo) => {
+        propertyNames: string[];
+        propertyDefaults: Map<string, Expr>;
+    };
+    isHandleClass: (classInfo: ClassInfo) => boolean;
+    evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
+    processArgumentsBlocks: (fn: FunctionDef, args: unknown[]) => void;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Interpreter statement execution and expression evaluation methods.
+ * Augments the Interpreter class via prototype assignment.
+ */
+import type { Stmt, Expr, LValue } from "../parser/types.js";
+import type { RuntimeValue } from "../runtime/types.js";
+import { Environment, type ControlSignal } from "./types.js";
+import type { Interpreter } from "./interpreter.js";
+export declare function execStmt(this: Interpreter, stmt: Stmt): ControlSignal | null;
+export declare function execStmts(this: Interpreter, stmts: Stmt[]): ControlSignal | null;
+/** Execute a conditional-block body (`if` / `switch` / `try`), tracking
+ *  `condBlockDepth` so a loop dispatched inside knows its sibling list is
+ *  a nested block — the loop classifier then keeps every loop-assigned
+ *  name live-out (the post-loop liveness scan can't see reads after the
+ *  enclosing block). */
+export declare function execBlockStmts(this: Interpreter, stmts: Stmt[]): ControlSignal | null;
+export declare function evalExpr(this: Interpreter, expr: Expr): unknown;
+export declare function evalExprNargout(this: Interpreter, expr: Expr, nargout: number): unknown;
+/** Compute the call-site variable names for `inputname`, aligned to the
+ *  argument expressions. Entry i is the name of the variable passed as
+ *  argument i+1, or '' if that argument is not a plain workspace variable.
+ *
+ *  Per MATLAB: an argument that uses cell `{}` or dot `.` indexing produces
+ *  a comma-separated list, making the position of every following argument
+ *  dynamic — so that argument and all subsequent ones report ''. Plain
+ *  literals, expressions, and paren-indexing report '' only for themselves.
+ *
+ *  The returned array may be shorter than the flattened arg count (when an
+ *  argument expanded to a CSL); callers treat out-of-range indices as ''.
+ */
+export declare function computeInputNames(argExprs: Expr[], callerEnv: Environment): string[];
+export declare function evalArgs(this: Interpreter, argExprs: Expr[]): unknown[];
+export declare function evalBinary(this: Interpreter, expr: Extract<Expr, {
+    type: "Binary";
+}>): unknown;
+/**
+ * Evaluate an `if`/`while`/`elseif` condition.
+ *
+ * MATLAB short-circuits the element-wise `&` and `|` operators when they
+ * appear at the top of a conditional expression and the left operand is
+ * scalar — e.g. `if nargin<4 | isempty(x)` must NOT evaluate `isempty(x)`
+ * when `nargin<4` (otherwise `x` may be undefined). Outside this context
+ * `&`/`|` evaluate both operands element-wise, so the special handling
+ * lives here rather than in `evalBinary`.
+ */
+export declare function evalCondition(this: Interpreter, expr: Expr): unknown;
+export declare function evalUnary(this: Interpreter, expr: Extract<Expr, {
+    type: "Unary";
+}>): unknown;
+export declare function evalRange(this: Interpreter, expr: Extract<Expr, {
+    type: "Range";
+}>): unknown;
+export declare function evalFuncCall(this: Interpreter, expr: Extract<Expr, {
+    type: "FuncCall";
+}>, nargout: number): unknown;
+export declare function evalMember(this: Interpreter, expr: Extract<Expr, {
+    type: "Member";
+}>, nargout: number): unknown;
+export declare function tryExtractDottedName(this: Interpreter, expr: Expr): string | null;
+export declare function evalIndex(this: Interpreter, expr: Extract<Expr, {
+    type: "Index";
+}>): unknown;
+export declare function evalIndexCell(this: Interpreter, expr: Extract<Expr, {
+    type: "IndexCell";
+}>): unknown;
+export declare function evalIndicesWithEnd(this: Interpreter, base: unknown, indexExprs: Expr[]): unknown[];
+export declare function evalAnonFunc(this: Interpreter, expr: Extract<Expr, {
+    type: "AnonFunc";
+}>): RuntimeValue;
+export declare function makeFuncHandle(this: Interpreter, name: string): RuntimeValue;
+export declare function evalTensorLiteral(this: Interpreter, expr: Extract<Expr, {
+    type: "Tensor";
+}>): unknown;
+export declare function evalCellLiteral(this: Interpreter, expr: Extract<Expr, {
+    type: "Cell";
+}>): unknown;
+export declare function assignLValue(this: Interpreter, lv: LValue, value: RuntimeValue): void;
+export declare function writeLValueBase(this: Interpreter, base: Expr, value: RuntimeValue): void;
+export declare function evalLValueBase(this: Interpreter, base: Expr, defaultVal: RuntimeValue): unknown;
+export declare function switchMatch(this: Interpreter, switchVal: unknown, caseVal: unknown): boolean;
+export declare function isOutputExpr(this: Interpreter, expr: Expr): boolean;

package/dist-browser/numbl-core/interpreter/interpreterFunctions.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Interpreter function call, resolution, and class method methods.
+ * Augments the Interpreter class via prototype assignment.
+ */
+import type { Expr } from "../parser/types.js";
+import { type ResolvedTarget } from "../functionResolve.js";
+import type { ClassInfo } from "../lowering/classInfo.js";
+import { Environment, type FunctionDef } from "./types.js";
+import type { Interpreter } from "./interpreter.js";
+export declare function callFunction(this: Interpreter, name: string, args: unknown[], nargout: number): unknown;
+/** Declared input count of the user function a `@name` handle points to,
+ *  resolved the same way a call to `name` would resolve. Returns undefined
+ *  when the target is a builtin or otherwise has no resolvable user-function
+ *  AST (caller falls back to probing / 0). Used to populate
+ *  `nargin(@name)`. */
+export declare function declaredNargin(this: Interpreter, name: string): number | undefined;
+export declare function interpretTarget(this: Interpreter, target: ResolvedTarget, args: unknown[], nargout: number): unknown;
+export declare function interpretJsUserFunction(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "jsUserFunction";
+}>, args: unknown[], nargout: number): unknown;
+export declare function interpretLocalFunction(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "localFunction";
+}>, args: unknown[], nargout: number): unknown;
+export declare function interpretWorkspaceFunction(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "workspaceFunction";
+}>, args: unknown[], nargout: number): unknown;
+export declare function interpretClassMethod(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "classMethod";
+}>, args: unknown[], nargout: number): unknown;
+export declare function interpretPrivateFunction(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "privateFunction";
+}>, args: unknown[], nargout: number): unknown;
+export declare function instantiateClass(this: Interpreter, className: string, args: unknown[], nargout: number): unknown;
+export declare function interpretConstructor(this: Interpreter, classInfo: ClassInfo, args: unknown[], nargout: number): unknown;
+export declare function callUserFunction(this: Interpreter, fn: FunctionDef, args: unknown[], nargout: number, narginOverride?: number): unknown;
+export declare function callNestedFunction(this: Interpreter, fn: FunctionDef, parentEnv: Environment, args: unknown[], nargout: number): unknown;
+export declare function withFileContext<T>(this: Interpreter, file: string, className: string | undefined, methodName: string | undefined, fn: () => T): T;
+export declare function getWorkspaceFileName(this: Interpreter, funcName: string): string;
+export declare function getClassFileName(this: Interpreter, className: string): string;
+export declare function findFunctionInWorkspaceFile(this: Interpreter, wsName: string, funcName: string): FunctionDef | null;
+export declare function findFunctionInClassFile(this: Interpreter, className: string, funcName: string, methodScope?: string): FunctionDef | null;
+export declare function findMethodInClass(this: Interpreter, classInfo: ClassInfo, methodName: string): FunctionDef | null;
+export declare function findExternalMethod(this: Interpreter, classInfo: ClassInfo, methodName: string): FunctionDef | null;
+export declare function collectClassProperties(this: Interpreter, classInfo: ClassInfo): {
+    propertyNames: string[];
+    propertyDefaults: Map<string, Expr>;
+};
+export declare function isHandleClass(this: Interpreter, classInfo: ClassInfo): boolean;
+export declare function evalInLocalScope(this: Interpreter, codeArg: unknown, fileName?: string): unknown;
+/**
+ * Apply `arguments`-block defaults and build name-value struct parameters,
+ * binding the results into the *current* function environment.
+ *
+ * Must be called with `this.env` already set to the function scope and the
+ * caller-supplied positional arguments already bound to their parameters.
+ * Default expressions are evaluated in that scope so they can reference
+ * earlier arguments (e.g. `mergeIdx = surfaceop.defaultIdx(dom)`), matching
+ * MATLAB. Entries are matched to parameters by name via `fn.params`, which
+ * also handles the constructor case where the output variable is prepended
+ * to `params` (shifting argument positions by one).
+ */
+export declare function processArgumentsBlocks(this: Interpreter, fn: FunctionDef, args: unknown[]): void;

package/dist-browser/numbl-core/interpreter/interpreterSpecialBuiltins.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Interpreter special builtins: functions that need access to interpreter
+ * context (env, callerEnv, etc.) and run before normal function resolution.
+ */
+import type { Environment } from "./types.js";
+import type { Runtime } from "../runtime/runtime.js";
+export interface InterpreterContext {
+    env: Environment;
+    setEnv: (env: Environment) => void;
+    callerEnv: Environment | undefined;
+    workspaceEnv: Environment | undefined;
+    evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
+    callFunction: (name: string, args: unknown[], nargout: number) => unknown;
+    rt: Runtime;
+    /** Optimization mode: "0" = no JIT, "1" = JS-JIT, "2" = C-JIT. */
+    optimization: import("../executors/plugins.js").OptLevel;
+    /** Resolve a workspace function or class name to its source file,
+     *  or undefined if no workspace file provides that name.
+     *  `kind` distinguishes a regular .m function from a .numbl.js
+     *  user function (treated as a MEX-equivalent) or a class file.
+     *  `source` is the raw .m source for "function"/"class" kinds, or empty
+     *  for "jsfunction" (where the implementation is JS, not .m text). */
+    lookupWorkspaceFile: (name: string) => {
+        path: string;
+        kind: "function" | "jsfunction" | "class";
+        source: string;
+    } | undefined;
+    /** Public (GetAccess public) property names of a class, including inherited
+     *  ones, in declaration order. Returns undefined if `className` is not a
+     *  known class. Backs `properties(obj)`. */
+    classPublicProperties: (className: string) => string[] | undefined;
+}
+export declare const FALL_THROUGH: unique symbol;
+export type InterpreterSpecialBuiltinHandler = (ctx: InterpreterContext, args: unknown[], nargout: number) => unknown | typeof FALL_THROUGH;
+export declare function getInterpreterSpecialBuiltin(name: string): InterpreterSpecialBuiltinHandler | undefined;