numbl 0.4.3 → 0.4.4

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

@@ -19,6 +19,20 @@
  * detect captures against the handle's own recorded definition
  * environment, so the test reflects what the handle actually closed
  * over, not a syntactic guess.
+ *
+ * A second constraint applies at the relocation site. A body name that
+ * is NOT a variable in the def env resolves at definition time to a
+ * function (or is undefined). After relocation into the loop's synthetic
+ * scope, that same name may be bound as a variable (a loop input or
+ * assigned local). Re-lowering would then capture the loop variable
+ * instead of resolving the function/undefined the handle saw — silently
+ * turning `@(t) sq(t)` from a function call into an array index, or
+ * masking an undefined-variable error. So the caller passes the set of
+ * names that will be in scope at the relocation site, and we decline
+ * when a free body name collides with it. A name that is purely a
+ * function (never an env variable) is not in that set, so the common
+ * `@(t) sq(t)` case still inlines; only the genuine shadowing case
+ * declines (and falls back to the interpreter).
  */
 import type { Expr } from "../parser/index.js";
 /**
@@ -33,10 +47,12 @@ import type { Expr } from "../parser/index.js";
  *    shadow across files), AND
  *  - for an anonymous handle, it is capture-free: no name its body
  *    references (other than its own params) exists as a variable in the
- *    handle's recorded definition environment.
+ *    handle's recorded definition environment, AND no free body name
+ *    collides with `relocScopeNames` (the names that will be in scope
+ *    where the handle is inlined).
  *
  * Named (`@name`) handles are always capture-free. Anything the lowerer
  * ultimately can't compile (e.g. a builtin target) simply makes the
  * enclosing unit decline to the interpreter — still correct.
  */
-export declare function inlinableHandleExpr(val: unknown, compileFile: string): Expr | null;
+export declare function inlinableHandleExpr(val: unknown, compileFile: string, relocScopeNames?: ReadonlySet<string>): Expr | null;

package/dist-lib/numbl-core/executors/jit/valueAdapter.d.ts

@@ -22,20 +22,27 @@
  * have caused `propose()` to decline earlier.
  */
 import { type RuntimeValue } from "../../runtime/types.js";
-import type { JitType } from "../../jitTypes.js";
+import type { Type } from "../../jit/index.js";
 /** numbl RuntimeValue → mtoc2 emit-JS value shape. Owned-typed
  *  values (tensors) get their data buffer cloned so mtoc2's spec
  *  body can mutate freely without leaking the change back through
  *  numbl's caller-side env.
  *
- *  `targetType` is the JitType the spec was COMPILED for at this
- *  parameter. Type-widening can reuse a complex specialization for a
- *  later real/boolean scalar call (both keys collapse to
- *  `complex_or_number`); the complex-typed body reads `.re`/`.im`, so a
- *  bare JS number arriving there yields `undefined` → NaN. Box such a
- *  scalar into `{re, im:0}` to mirror the C adapter (valueAdapterC),
- *  which already boxes a real as a complex with `im=0`. */
-export declare function numblToJit(v: RuntimeValue, targetType?: JitType): unknown;
+ *  `paramType` is the compiler `Type` the spec was COMPILED for at this
+ *  parameter. It reconciles two value/type mismatches at the boundary,
+ *  both mirroring the C adapter (valueAdapterC):
+ *
+ *   1. **1×1 tensor → scalar param.** The compiler collapses a [1,1]
+ *      tensor type to a scalar `double`/`complex` (`!isMultiElement`),
+ *      so scalar codegen reads a bare number / `{re, im}`. A 1×1
+ *      `RuntimeTensor` value must therefore be unwrapped to its element;
+ *      otherwise the tensor OBJECT leaks into scalar arithmetic and
+ *      `a.data[i] + b` becomes `number + object = NaN`.
+ *   2. **real → complex-scalar param.** Type-widening can reuse a complex
+ *      specialization for a later real/boolean scalar call; the
+ *      complex-typed body reads `.re`/`.im`, so a bare number must be
+ *      boxed into `{re, im:0}`. */
+export declare function numblToJit(v: RuntimeValue, paramType?: Type): unknown;
 /** mtoc2 emit-JS return value → numbl RuntimeValue. */
 export declare function jitToNumbl(v: unknown): RuntimeValue;
 /** True if `e` is the grow-bail sentinel thrown by the emitted JS

package/dist-lib/numbl-core/jit/compileSpecC.d.ts

@@ -75,6 +75,13 @@ export interface CompileSpecCArgs {
     argTypes: Type[];
     /** Number of outputs the call site requests. Salts the spec key. */
     nargout: number;
+    /** True when the entry `funcDecl` is a synthetic wrapper (loop or
+     *  top-level body), whose declared outputs may include the loop variable
+     *  and other loop-body locals that are legitimately unassigned on a
+     *  zero-iteration run. Suppresses the output-definite-assignment check on
+     *  the entry spec (callees are still fully checked). Defaults to false
+     *  (a real user-function entry, e.g. the call executor). */
+    entrySynthetic?: boolean;
 }
 export interface CompileSpecCResult {
     /** Mangled spec name. Same as `signature.cName`. */

package/dist-lib/numbl-core/jit/lowering/definiteAssign.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Conservative definite-assignment check for the C backend.
+ *
+ * The C-JIT predeclares every function local at the top of the emitted
+ * function with a default value (`double x = 0.0;`, an empty owned struct,
+ * …). C has no "unassigned" sentinel, so a variable that is assigned ONLY
+ * on a path that doesn't run — e.g. inside a `for` loop with an empty range,
+ * or one arm of an `if` with no matching `else` — leaks its default value
+ * when read afterwards. The interpreter and JS-JIT instead leave the binding
+ * absent: the interpreter raises "Undefined function or variable", and the
+ * JS-JIT returns `undefined` which fails to marshal back and bails to the
+ * interpreter. So at `--opt 2` a use-before-assign silently returns 0 while
+ * `--opt 0/1` (correctly) raise.
+ *
+ * Rather than model MATLAB's binding-absent semantics in C, we DECLINE: if a
+ * variable that is assigned somewhere in the function may be read before it
+ * is definitely assigned, throw `UnsupportedConstruct`. The C-JIT executor
+ * catches that and falls back to the JS-JIT / interpreter, which handle the
+ * case correctly. Declining is always safe — it can only cost a fallback,
+ * never correctness — so the analysis is deliberately conservative:
+ *
+ *   - On the READ side it may under-approximate (a missed read kind just
+ *     means we don't catch that particular use-before-assign — still safe).
+ *   - On the ASSIGNMENT side it must not under-approximate, or we'd flag a
+ *     valid program; the `assert_jit c` integration tests guard against
+ *     over-declining real code.
+ */
+import type { IRFunc } from "./ir.js";
+/**
+ * Throw `UnsupportedConstruct` if `fn` may read a local variable before it
+ * is definitely assigned. Parameters are assigned on entry.
+ *
+ * `checkOutputs` additionally rejects a function whose declared output may
+ * be returned before assignment (MATLAB's "Output argument not assigned").
+ * Enable it only for REAL user functions: a synthetic loop/top-level wrapper
+ * lists the loop variable (and other loop-body locals) as pseudo-outputs
+ * that are legitimately unassigned when the loop runs zero times, so the
+ * check would over-decline every loop.
+ */
+export declare function assertDefiniteAssignment(fn: IRFunc, opts?: {
+    checkOutputs: boolean;
+}): void;

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

@@ -9,67 +9,68 @@ export declare enum Token {
     Else = 7,
     ElseIf = 8,
     For = 9,
-    While = 10,
-    Break = 11,
-    Continue = 12,
-    Return = 13,
-    End = 14,
-    ClassDef = 15,
-    Properties = 16,
-    Methods = 17,
-    Events = 18,
-    Enumeration = 19,
-    Arguments = 20,
-    Import = 21,
-    Switch = 22,
-    Case = 23,
-    Otherwise = 24,
-    Try = 25,
-    Catch = 26,
-    Global = 27,
-    Persistent = 28,
-    True = 29,
-    False = 30,
-    Plus = 31,
-    Minus = 32,
-    Star = 33,
-    Slash = 34,
-    Backslash = 35,
-    Caret = 36,
-    And = 37,
-    Or = 38,
-    Tilde = 39,
-    At = 40,
-    Question = 41,
-    Less = 42,
-    Greater = 43,
-    Dot = 44,
-    Colon = 45,
-    Comma = 46,
-    Assign = 47,
-    Semicolon = 48,
-    LParen = 49,
-    RParen = 50,
-    LBracket = 51,
-    RBracket = 52,
-    LBrace = 53,
-    RBrace = 54,
-    DotStar = 55,
-    DotSlash = 56,
-    DotBackslash = 57,
-    DotCaret = 58,
-    AndAnd = 59,
-    OrOr = 60,
-    Equal = 61,
-    NotEqual = 62,
-    LessEqual = 63,
-    GreaterEqual = 64,
-    Transpose = 65,
-    Ellipsis = 66,
-    Newline = 67,
-    Section = 68,
-    Error = 69,
-    Directive = 70
+    ParFor = 10,
+    While = 11,
+    Break = 12,
+    Continue = 13,
+    Return = 14,
+    End = 15,
+    ClassDef = 16,
+    Properties = 17,
+    Methods = 18,
+    Events = 19,
+    Enumeration = 20,
+    Arguments = 21,
+    Import = 22,
+    Switch = 23,
+    Case = 24,
+    Otherwise = 25,
+    Try = 26,
+    Catch = 27,
+    Global = 28,
+    Persistent = 29,
+    True = 30,
+    False = 31,
+    Plus = 32,
+    Minus = 33,
+    Star = 34,
+    Slash = 35,
+    Backslash = 36,
+    Caret = 37,
+    And = 38,
+    Or = 39,
+    Tilde = 40,
+    At = 41,
+    Question = 42,
+    Less = 43,
+    Greater = 44,
+    Dot = 45,
+    Colon = 46,
+    Comma = 47,
+    Assign = 48,
+    Semicolon = 49,
+    LParen = 50,
+    RParen = 51,
+    LBracket = 52,
+    RBracket = 53,
+    LBrace = 54,
+    RBrace = 55,
+    DotStar = 56,
+    DotSlash = 57,
+    DotBackslash = 58,
+    DotCaret = 59,
+    AndAnd = 60,
+    OrOr = 61,
+    Equal = 62,
+    NotEqual = 63,
+    LessEqual = 64,
+    GreaterEqual = 65,
+    Transpose = 66,
+    Ellipsis = 67,
+    Newline = 68,
+    Section = 69,
+    Error = 70,
+    Directive = 71
 }
 export interface SpannedToken {
     token: Token;

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

@@ -0,0 +1,32 @@
+/**
+ * Pure-TypeScript complex non-symmetric eigensolver — a zgeev-equivalent for
+ * the ts-lapack bridge (browser path, no native LAPACK addon).
+ *
+ * Ported from the netlib LAPACK reference (zgeev → zgehd2 / zunghr → zlahqr →
+ * ztrevc). Simplifications relative to zgeev, valid for the well-scaled inputs
+ * numbl produces (the acceptance bar is residual-based, A*V≈V*D / W^H*A≈D*W^H,
+ * not bit-matching MKL):
+ *   - No balancing (zgebal/zgebak) — ILO=1, IHI=N.
+ *   - No norm scaling (zlascl).
+ *   - Eigenvector back-substitution uses plain triangular solves with the
+ *     ztrevc SMIN diagonal regularization, instead of the overflow-safe zlatrs.
+ *
+ * Eigenvectors are normalized to unit Euclidean norm with the largest-magnitude
+ * component made real (the documented zgeev convention).
+ *
+ * All matrices are column-major with leading dimension n, split into parallel
+ * real/imag Float64Arrays — matching the bridge's eigComplex I/O shape.
+ */
+/**
+ * Complex eigendecomposition (zgeev-equivalent). Matches the LapackBridge
+ * eigComplex contract: column-major real/imag inputs, returns eigenvalues and
+ * (optionally) left/right eigenvectors.
+ */
+export declare function eigComplexTs(dataRe: Float64Array, dataIm: Float64Array, n: number, computeVL: boolean, computeVR: boolean): {
+    wRe: Float64Array;
+    wIm: Float64Array;
+    VLRe?: Float64Array;
+    VLIm?: Float64Array;
+    VRRe?: Float64Array;
+    VRIm?: Float64Array;
+};

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

@@ -5,8 +5,9 @@
  * plot(X1,Y1,LineSpec1,...), and Name-Value pairs like 'Color','r','LineWidth',2.
  */
 import { type RuntimeValue } from "./types.js";
-export type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace, } from "../../graphics/types.js";
-import type { PlotTrace, Plot3Trace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace } from "../../graphics/types.js";
+export type { PlotTrace, Plot3Trace, PatchTrace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace, } from "../../graphics/types.js";
+import type { PlotTrace, Plot3Trace, PatchTrace, SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, BarTrace, Bar3Trace, ErrorBarTrace, BoxTrace, PieTrace, HeatmapTrace, QuiverTrace, Quiver3Trace } from "../../graphics/types.js";
+export declare function resolveColor(v: RuntimeValue | string): [number, number, number] | undefined;
 export interface ParsedLineSpec {
     color?: string;
     lineStyle?: string;
@@ -24,6 +25,58 @@ export declare function parsePlotArgs(args: RuntimeValue[]): PlotTrace[];
  *   plot3(..., Name, Value)
  */
 export declare function parsePlot3Args(args: RuntimeValue[]): Plot3Trace[];
+/** Result of parsing line() arguments: a set of 2-D or 3-D traces. */
+export type ParsedLine = {
+    kind: "2d";
+    traces: PlotTrace[];
+} | {
+    kind: "3d";
+    traces: Plot3Trace[];
+};
+/**
+ * Parse line() arguments.
+ *
+ * Supported forms:
+ *   line                                  — line from (0,0) to (1,1)
+ *   line(x, y)                            — 2-D line(s)
+ *   line(x, y, z)                         — 3-D line(s)
+ *   line(___, Name, Value)               — Color/LineStyle/LineWidth/Marker/...
+ *   line('XData', x, 'YData', y, ...)    — low-level form (black line)
+ *   line(ax, ___)                        — leading axes handle (ignored)
+ *
+ * Like plot/plot3, vector inputs make a single line and matrix inputs make one
+ * line per column.
+ */
+export declare function parseLineArgs(args: RuntimeValue[]): ParsedLine;
+/** Apply a single patch property (lower-cased key) to the trace. Shared by the
+ *  Name-Value, struct, and `set`/handle paths. */
+export declare function applyPatchProp(trace: PatchTrace, key: string, val: RuntimeValue): void;
+/**
+ * Parse patch() arguments into a canonical PatchTrace.
+ *
+ * Supported forms:
+ *   patch(X, Y, C)                              — 2-D polygons, color C
+ *   patch(X, Y, Z, C)                           — 3-D polygons
+ *   patch('XData', X, 'YData', Y[, 'ZData', Z]) — coords as name-value
+ *   patch('Faces', F, 'Vertices', V)            — faces/vertices model
+ *   patch(S)                                    — struct of patch properties
+ *   patch(___, Name, Value)                     — patch properties
+ *   patch(ax, ___)                              — leading axes handle (ignored)
+ */
+export declare function parsePatchArgs(args: RuntimeValue[]): PatchTrace;
+/**
+ * Parse fill() arguments into one patch trace per (X,Y,C) group. fill is the
+ * 2-D coordinate form of patch repeated over groups, so it reuses the patch
+ * vertex/color/property helpers — the only fill-specific logic is splitting
+ * the argument list into X,Y,C triplets.
+ *
+ * Supported forms:
+ *   fill(X, Y, C)
+ *   fill(X1, Y1, C1, ..., Xn, Yn, Cn)
+ *   fill(___, Name, Value)
+ *   fill(ax, ___)
+ */
+export declare function parseFillArgs(args: RuntimeValue[]): PatchTrace[];
 /**
  * Parse surf() arguments.
  *

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

@@ -32,6 +32,9 @@ export declare class Runtime {
     plotInstructions: PlotInstruction[];
     variableValues: Record<string, RuntimeValue>;
     holdState: boolean;
+    /** Monotonic id source for graphics handles whose trace can be live-updated
+     *  via `set` / `update_trace` (e.g. lines returned by `line`). */
+    graphicsIdCounter: number;
     tiledLayoutState: {
         rows: number;
         cols: number;

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

@@ -47,6 +47,9 @@ export declare function plotInstr(plotInstructions: PlotInstruction[], instr: {
 } | {
     type: "set_grid";
     value: unknown;
+} | {
+    type: "set_box";
+    value: unknown;
 } | {
     type: "set_zlabel";
     text: unknown;
@@ -68,6 +71,9 @@ export declare function plotInstr(plotInstructions: PlotInstruction[], instr: {
 export declare function viewCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function plotCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function plot3Call(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function lineCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function patchCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function fillCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function surfCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function surfaceCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function imagescCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;

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

@@ -3,5 +3,9 @@
  */
 import { type RuntimeValue } from "./types.js";
 import { type RefcountRuntime } from "./refcount.js";
+export declare function applyHandleProperty(trace: Record<string, unknown>, traceType: string, field: string, value: RuntimeValue): {
+    key: string;
+    value: unknown;
+};
 export declare function getRTValueField(base: RuntimeValue, field: string): RuntimeValue;
 export declare function setRTValueField(base: RuntimeValue, field: string, value: RuntimeValue, rt?: RefcountRuntime): 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.4.3";
+export declare const NUMBL_VERSION = "0.4.4";