numbl 0.4.21 → 0.4.22

package/dist-lib/numbl-core/plotting/builtins.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Plot builtin registrations: data-bearing plot calls (plot, surf, contour,
+ * ...), graphics ops with figure/axes state (figure, hold, subplot, ...), and
+ * the ops that return handles or need the runtime's plot state. Names with no
+ * custom registration fall through to the generic loop at the end, which
+ * routes them to `dispatchPlotBuiltin`.
+ */
+export {};

package/dist-lib/numbl-core/plotting/colormaps.d.ts

@@ -0,0 +1,10 @@
+export type RGB = [number, number, number];
+/** An axes colormap: a named map, or custom N×3 `data` (which wins). */
+export interface ColormapSpec {
+    name?: string;
+    data?: number[][];
+}
+export declare const PARULA_ANCHORS: RGB[];
+/** Color at t ∈ [0, 1] (clamped; non-finite → 0) in the given colormap.
+ *  Unknown names fall back to parula. */
+export declare function colormapLookup(t: number, cm?: ColormapSpec): RGB;

package/dist-lib/numbl-core/{runtime/plotBuiltinDispatch.d.ts → plotting/dispatch.d.ts}

@@ -3,19 +3,10 @@
  * `(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.
+ * Registration lives in `builtins.ts`: each name gets a wrapper that
+ * calls this function and returns the right `nargout`-handle value; the
+ * side effect (the push onto `rt.plotInstructions`, plus the small
+ * hold / tiled-layout flags on the Runtime) lives here.
  *
  * Out-of-scope names — kept registered separately because their
  * semantics need the full Runtime context:
@@ -32,8 +23,8 @@
  * 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";
+import type { RuntimeValue } from "../runtime/types.js";
+import type { PlotInstruction } from "./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
@@ -64,17 +55,16 @@ export interface TiledLayoutState {
  *  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. */
+/** Names handled by `dispatchPlotBuiltin`. `builtins.ts` registers all
+ *  of them in a loop (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`)
+ *      `newplot`, `xlim`, `ylim`, `get`)
+ *    - `plotting/builtins.ts` (`drawnow`, `pause`, `ishold`, `set`)
  *
  *  These names belong here, alongside `PLOT_DISPATCH_NAMES`, because
  *  downstream consumers (mtoc2's translator, syntax highlighters,
@@ -85,8 +75,7 @@ export declare const PLOT_DISPATCH_NAMES: ReadonlyArray<string>;
 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. */
+ *  script might invoke that numbl tolerates. The JIT registers its plot
+ *  builtins from this list, so a new plot builtin needs no JIT-side
+ *  edit. */
 export declare const PLOT_ALL_NAMES: ReadonlyArray<string>;

package/dist-lib/numbl-core/plotting/imagescExtent.d.ts

@@ -0,0 +1,19 @@
+import type { ImagescTrace } from "./types.js";
+/**
+ * Pixel geometry of an imagesc trace. As in MATLAB, `x` and `y` hold the
+ * centers of the first and last columns/rows (XData/YData), so the image
+ * extends half a pixel beyond them; a single column or row is one unit wide.
+ * `dx`/`dy` may be negative (decreasing XData/YData).
+ */
+export declare function imagescExtent(t: ImagescTrace): {
+    dx: number;
+    dy: number;
+    x: [number, number];
+    y: [number, number];
+};
+/**
+ * Color limits for an imagesc trace: the axes' caxis/clim when set, else the
+ * finite data range. Values outside the limits clamp to the colormap ends.
+ * Returns null when there is no finite data and no caxis.
+ */
+export declare function imagescColorLimits(t: ImagescTrace, caxis?: [number, number]): [number, number] | null;

package/dist-lib/numbl-core/{runtime/runtimePlot.d.ts → plotting/instructions.d.ts}

@@ -1,10 +1,10 @@
 /**
- * Plot-related operations for the runtime.
+ * Plot instruction builders: one `*Call` per plotting builtin, each parsing
+ * its runtime arguments and pushing the resulting `PlotInstruction`s.
  */
 import { type RuntimeValue } from "../runtime/index.js";
-import type { PlotInstruction } from "../../graphics/types.js";
-import type { ExecOptions } from "../executeCode.js";
-import type { Runtime } from "./runtime.js";
+import type { PlotInstruction } from "./types.js";
+import type { Runtime } from "../runtime/runtime.js";
 export declare function plotInstr(plotInstructions: PlotInstruction[], instr: {
     type: "set_figure_handle";
     handle: unknown;
@@ -74,6 +74,7 @@ export declare function plot3Call(plotInstructions: PlotInstruction[], args: Run
 export declare function lineCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function patchCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function trimeshCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function trisurfCall(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;
@@ -114,16 +115,3 @@ export declare function heatmapCall(plotInstructions: PlotInstruction[], args: R
 export declare function quiverCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function quiver3Call(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function legendCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
-export declare function drawnow(plotInstructions: PlotInstruction[], options: ExecOptions): void;
-export declare function pause(seconds: unknown): void;
-/**
- * streamline(X,Y,U,V,startX,startY) — compute and plot 2D streamlines.
- * streamline(verts) — plot from pre-computed cell array of vertex matrices.
- * Returns a dummy graphics handle.
- */
-export declare function streamlineCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): RuntimeValue;
-/**
- * stream2(X,Y,U,V,startX,startY) — compute 2D streamline vertices.
- * Returns a cell array of Nx2 vertex matrices.
- */
-export declare function stream2Call(args: RuntimeValue[]): RuntimeValue;

package/dist-lib/numbl-core/plotting/parseArgsChart.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Argument parsers for statistical charts: bar, barh, bar3, histogram,
+ * histogram2, boxchart, swarmchart, and piechart/donutchart.
+ */
+import { type RuntimeValue } from "../runtime/types.js";
+import type { PlotTrace, Plot3Trace, BarTrace, Bar3Trace, BoxTrace, PieTrace } from "./types.js";
+/**
+ * Parse bar() arguments.
+ *
+ * Supported forms:
+ *   bar(Y)             — Y values with x = 1:length(Y)
+ *   bar(X, Y)          — explicit X positions
+ *   bar(..., width)     — relative bar width (scalar 0–1)
+ *   bar(..., color)     — single-char color spec
+ */
+export declare function parseBarArgs(args: RuntimeValue[]): BarTrace[];
+/**
+ * Parse barh() arguments — same forms as bar() but rendered horizontally.
+ *
+ * Supported forms:
+ *   barh(Y)             — Y values (bar lengths) with positions = 1:length(Y)
+ *   barh(X, Y)          — explicit positions X, bar lengths Y
+ *   barh(..., width)    — relative bar thickness (scalar 0–1)
+ *   barh(..., color)    — single-char color spec
+ */
+export declare function parseBarHArgs(args: RuntimeValue[]): BarTrace[];
+/**
+ * Parse bar3() / bar3h() arguments.
+ *
+ * Supported forms:
+ *   bar3(Z)             — Z values with y = 1:m, x = 1:n
+ *   bar3(Y, Z)          — explicit Y positions
+ *   bar3(..., width)    — relative bar width (scalar 0–1)
+ *   bar3(..., color)    — single-char color spec
+ */
+export declare function parseBar3Args(args: RuntimeValue[]): Bar3Trace;
+/**
+ * Parse histogram() arguments.
+ *
+ * Supported forms:
+ *   histogram(X)
+ *   histogram(X, nbins)
+ *   histogram(X, edges)
+ */
+export declare function parseHistogramArgs(args: RuntimeValue[]): BarTrace[];
+/**
+ * Parse histogram2() arguments.
+ *
+ * Supported forms:
+ *   histogram2(X, Y)
+ *   histogram2(X, Y, nbins)        — nbins is scalar or [nx, ny]
+ *   histogram2(X, Y, Xedges, Yedges)
+ */
+export declare function parseHistogram2Args(args: RuntimeValue[]): Bar3Trace;
+/**
+ * Parse boxchart() arguments.
+ *
+ * Supported forms:
+ *   boxchart(ydata)           — one box per column of ydata
+ *   boxchart(xgroupdata, ydata) — group ydata by unique values in xgroupdata
+ */
+export declare function parseBoxchartArgs(args: RuntimeValue[]): BoxTrace[];
+/**
+ * Parse swarmchart() arguments.
+ *
+ * Supported forms:
+ *   swarmchart(x, y)
+ *   swarmchart(x, y, sz)
+ *   swarmchart(x, y, sz, c)
+ *   swarmchart(..., 'filled')
+ *   swarmchart(..., markertype)
+ */
+export declare function parseSwarmchartArgs(args: RuntimeValue[]): PlotTrace[];
+/**
+ * Parse swarmchart3() arguments.
+ *
+ * Supported forms:
+ *   swarmchart3(x, y, z)
+ *   swarmchart3(x, y, z, sz)
+ *   swarmchart3(x, y, z, sz, c)
+ *   swarmchart3(..., 'filled')
+ *   swarmchart3(..., markertype)
+ */
+export declare function parseSwarmchart3Args(args: RuntimeValue[]): Plot3Trace[];
+/**
+ * Parse piechart() / donutchart() arguments.
+ *
+ * Supported forms:
+ *   piechart(data)
+ *   piechart(data, names)
+ *
+ * @param innerRadius 0 for pie, >0 for donut
+ */
+export declare function parsePiechartArgs(args: RuntimeValue[], innerRadius: number): PieTrace;

package/dist-lib/numbl-core/plotting/parseArgsCommon.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared helpers for plot argument parsing: color specs, LineSpec strings,
+ * Name-Value key detection, and conversion of runtime values to plain
+ * number arrays and grids.
+ */
+import { type RuntimeValue, type RuntimeTensor } from "../runtime/types.js";
+export declare const COLOR_SHORT: Record<string, [number, number, number]>;
+export declare function resolveColor(v: RuntimeValue | string): [number, number, number] | undefined;
+export interface ParsedLineSpec {
+    color?: string;
+    lineStyle?: string;
+    marker?: string;
+}
+export declare function parseLineSpec(s: string): ParsedLineSpec | null;
+export declare function isNameValueKey(v: RuntimeValue): string | null;
+export declare function isNumericArg(v: unknown): boolean;
+export declare function isStringArg(v: unknown): boolean;
+export declare function getStringValue(v: RuntimeValue): string;
+/** Convert runtime value to a flat number array */
+export declare function toNumberArray(v: RuntimeValue): number[];
+/** Extract column j from a column-major tensor with shape [m, n] */
+export declare function tensorColumn(tensor: RuntimeTensor, col: number): number[];
+/**
+ * Get the number of columns of a numeric value for matrix splitting.
+ * Only returns > 1 for true matrices (nRows > 1 && nCols > 1).
+ * Row vectors (1×N) and column vectors (N×1) return 1.
+ */
+export declare function numColumns(v: RuntimeValue): number;
+/** Generate 1-based index array [1, 2, ..., n] */
+export declare function oneBasedIndices(n: number): number[];
+/**
+ * Expand a numeric value into column-wise traces.
+ * For a vector (row or column), returns one array.
+ * For an m×n matrix (m>1, n>1), returns n arrays (one per column).
+ */
+export declare function expandColumns(v: RuntimeValue): number[][];
+/** A leading argument that should be skipped as an axes handle. numbl has no
+ *  real axes handles, so `line(ax, ___)` is accepted and the handle ignored. */
+export declare function isAxesHandleArg(v: RuntimeValue): boolean;
+export declare function getMatrixInfo(v: RuntimeValue): {
+    data: number[];
+    rows: number;
+    cols: number;
+};
+/** Generate meshgrid X and Y for a rows×cols grid: X = 1:cols, Y = 1:rows (column-major) */
+export declare function generateMeshgrid(rows: number, cols: number): {
+    x: number[];
+    y: number[];
+};
+/**
+ * Expand X and Y to match the grid dimensions of Z.
+ * Handles:
+ *   - X and Y as full m×n matrices (pass through)
+ *   - X as 1×n row vector, Y as m×1 column vector (meshgrid expansion)
+ *   - X as n-element vector, Y as m-element vector (meshgrid expansion)
+ */
+export declare function expandXY(xVal: RuntimeValue, yVal: RuntimeValue, rows: number, cols: number): {
+    x: number[];
+    y: number[];
+};
+/** Get string value if the value is a string/char, otherwise undefined */
+export declare function getStringValueIfString(v: RuntimeValue): string | undefined;
+/** Create a runtime tensor from a plain number array (for synthetic args). */
+export declare function tensorFromArray(arr: number[]): RuntimeValue;

package/dist-lib/numbl-core/plotting/parseArgsLine.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Argument parsers for line-like plots: plot, plot3, line, scatter, scatter3,
+ * stairs, errorbar, and area.
+ *
+ * Handles: plot(Y), plot(X,Y), plot(X1,Y1,...,Xn,Yn),
+ * plot(X1,Y1,LineSpec1,...), and Name-Value pairs like 'Color','r','LineWidth',2.
+ */
+import { type RuntimeValue } from "../runtime/types.js";
+import type { PlotTrace, Plot3Trace, ErrorBarTrace } from "./types.js";
+export declare function parsePlotArgs(args: RuntimeValue[]): PlotTrace[];
+/**
+ * Parse plot3() arguments.
+ *
+ * Supported forms:
+ *   plot3(X, Y, Z)
+ *   plot3(X, Y, Z, LineSpec)
+ *   plot3(X1,Y1,Z1,...,Xn,Yn,Zn)
+ *   plot3(X1,Y1,Z1,LineSpec1,...,Xn,Yn,Zn,LineSpecn)
+ *   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;
+/**
+ * Parse scatter() arguments.
+ *
+ * Supported forms:
+ *   scatter(X, Y)
+ *   scatter(X, Y, sz)
+ *   scatter(X, Y, sz, c)
+ *   scatter(X, Y, ..., 'filled')
+ *   scatter(X, Y, ..., mkr)
+ *   scatter(X, Y, ..., Name, Value)
+ */
+export declare function parseScatterArgs(args: RuntimeValue[]): PlotTrace[];
+/**
+ * Parse stairs() arguments — same forms as plot() but with staircase-transformed coordinates.
+ *
+ * Supported forms:
+ *   stairs(Y)
+ *   stairs(X, Y)
+ *   stairs(..., LineSpec)
+ *   stairs(..., Name, Value)
+ */
+export declare function parseStairsArgs(args: RuntimeValue[]): PlotTrace[];
+/**
+ * Parse errorbar() arguments.
+ *
+ * Supported forms:
+ *   errorbar(y, err)                    — symmetric vertical
+ *   errorbar(x, y, err)                 — symmetric vertical with explicit x
+ *   errorbar(x, y, neg, pos)            — asymmetric vertical
+ *   errorbar(x, y, yneg, ypos, xneg, xpos) — both axes
+ *   errorbar(..., LineSpec)
+ */
+export declare function parseErrorBarArgs(args: RuntimeValue[]): ErrorBarTrace[];
+/**
+ * Parse area() arguments.
+ *
+ * Supported forms:
+ *   area(Y)              — fill under Y with x = 1:length(Y)
+ *   area(X, Y)           — explicit X
+ *   area(..., basevalue)  — scalar baseline (default 0)
+ *   area(..., Name, Value)
+ *
+ * Returns { traces, baseValue }.
+ */
+export declare function parseAreaArgs(args: RuntimeValue[]): {
+    traces: PlotTrace[];
+    baseValue: number;
+};
+/**
+ * Parse scatter3() arguments.
+ *
+ * Supported forms:
+ *   scatter3(X, Y, Z)
+ *   scatter3(X, Y, Z, S)
+ *   scatter3(X, Y, Z, S, C)
+ *   scatter3(..., 'filled')
+ *   scatter3(..., markertype)
+ */
+export declare function parseScatter3Args(args: RuntimeValue[]): Plot3Trace[];

package/dist-lib/numbl-core/plotting/parseArgsPatch.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Argument parsers for patch-based plots: patch, fill, trimesh, and trisurf.
+ */
+import { type RuntimeValue } from "../runtime/types.js";
+import type { PatchTrace } from "./types.js";
+/** 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[];
+export declare function parseTriMeshArgs(args: RuntimeValue[]): PatchTrace;
+/** Parse trisurf() arguments. Same forms as trimesh, but (matching MATLAB)
+ *  the faces default to 'flat' coloring by the per-vertex z values (or c). */
+export declare function parseTriSurfArgs(args: RuntimeValue[]): PatchTrace;

package/dist-lib/numbl-core/plotting/parseArgsQuiver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Argument parsers for vector fields: quiver and quiver3.
+ */
+import { type RuntimeValue } from "../runtime/types.js";
+import type { QuiverTrace, Quiver3Trace } from "./types.js";
+/**
+ * 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[];
+/**
+ * Parse quiver3() arguments.
+ *
+ * Supported forms:
+ *   quiver3(Z, U, V, W)
+ *   quiver3(X, Y, Z, U, V, W)
+ *   quiver3(..., scale)         — scale: nonnegative number or 'off'
+ *   quiver3(..., LineSpec)
+ *   quiver3(..., LineSpec, 'filled')
+ *   quiver3(..., Name, Value)   — Color, LineStyle, LineWidth, ShowArrowHead, …
+ */
+export declare function parseQuiver3Args(args: RuntimeValue[]): Quiver3Trace;

package/dist-lib/numbl-core/plotting/parseArgsSurface.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Argument parsers for gridded data: surf, mesh, pcolor, imagesc, contour
+ * (including the MATLAB contour matrix), and heatmap.
+ */
+import { type RuntimeValue } from "../runtime/types.js";
+import type { SurfTrace, ImagescTrace, PcolorTrace, ContourTrace, HeatmapTrace } from "./types.js";
+/**
+ * Parse surf() arguments.
+ *
+ * Supported forms:
+ *   surf(Z)           — Z is m×n, X = 1:n, Y = 1:m
+ *   surf(Z, C)        — Z is m×n, C is m×n color data
+ *   surf(X, Y, Z)     — X, Y, Z are m×n matrices (or X is 1×n / Y is m×1)
+ *   surf(X, Y, Z, C)  — with explicit color data
+ *   surf(..., Name, Value) — name-value pairs
+ */
+export declare function parseSurfArgs(args: RuntimeValue[]): SurfTrace;
+/**
+ * Parse pcolor() arguments.
+ *
+ * Supported forms:
+ *   pcolor(C)         — C is m×n, X = 1:n, Y = 1:m
+ *   pcolor(X, Y, C)   — X, Y, C are m×n matrices (or X is 1×n / Y is m×1)
+ *   pcolor(..., Name, Value) — name-value pairs (EdgeColor, FaceAlpha)
+ */
+export declare function parsePcolorArgs(args: RuntimeValue[]): PcolorTrace;
+/**
+ * Parse imagesc() arguments.
+ *
+ * Supported forms:
+ *   imagesc(C)         — C is m×n matrix
+ *   imagesc(x, y, C)   — x and y are vectors defining axis limits
+ *   imagesc(..., clims) — clims = [low high] sets the axes' color limits
+ */
+export declare function parseImagescArgs(args: RuntimeValue[]): {
+    trace: ImagescTrace;
+    clims?: [number, number];
+};
+/**
+ * Parse contour()/contourf() arguments.
+ *
+ * Supported forms:
+ *   contour(Z)
+ *   contour(Z, N)
+ *   contour(X, Y, Z)
+ *   contour(X, Y, Z, N)
+ *   contour(..., Name, Value)
+ */
+export declare function parseContourArgs(args: RuntimeValue[], filled: boolean): ContourTrace;
+/** Result of computing contour geometry: the MATLAB contour matrix `C`
+ *  (column-major `2 × n` data) plus the level list actually used. */
+export interface ContourMatrix {
+    /** Column-major `2 × n` data for a `RTV.tensor(data, [2, n])`. */
+    data: number[];
+    n: number;
+    levelList: number[];
+}
+/** Compute the MATLAB contour matrix for a parsed contour trace via marching
+ *  squares. Each marching-squares segment is emitted as its own two-vertex
+ *  contour line (header `[level; 2]` followed by the two `[x; y]` vertices) —
+ *  a valid contour matrix whose geometry matches MATLAB's connected polylines
+ *  segment-for-segment. */
+export declare function computeContourMatrix(trace: ContourTrace): ContourMatrix;
+/**
+ * Parse mesh() arguments — same as surf but with different default rendering.
+ */
+export declare function parseMeshArgs(args: RuntimeValue[]): SurfTrace;
+/**
+ * Parse heatmap() arguments.
+ *
+ * Supported forms:
+ *   heatmap(cdata)                — matrix of values
+ *   heatmap(xvalues, yvalues, cdata) — with axis labels
+ */
+export declare function parseHeatmapArgs(args: RuntimeValue[]): HeatmapTrace;

package/dist-lib/numbl-core/plotting/streamline.d.ts

@@ -0,0 +1,16 @@
+/**
+ * streamline / stream2: trace 2-D streamlines through a gridded vector field.
+ */
+import type { RuntimeValue } from "../runtime/index.js";
+import type { PlotInstruction } from "./types.js";
+/**
+ * streamline(X,Y,U,V,startX,startY) — compute and plot 2D streamlines.
+ * streamline(verts) — plot from pre-computed cell array of vertex matrices.
+ * Returns a dummy graphics handle.
+ */
+export declare function streamlineCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): RuntimeValue;
+/**
+ * stream2(X,Y,U,V,startX,startY) — compute 2D streamline vertices.
+ * Returns a cell array of Nx2 vertex matrices.
+ */
+export declare function stream2Call(args: RuntimeValue[]): RuntimeValue;

package/dist-lib/{graphics → numbl-core/plotting}/types.d.ts

@@ -1,12 +1,12 @@
 /**
- * Shared graphics types used by both numbl-core and the rendering layer.
+ * Plot data types: the trace interfaces and `PlotInstruction`, the
+ * serializable contract between numbl-core (which emits instructions) and the
+ * renderer in src/graphics/ (which consumes them). The renderer imports these
+ * from here; numbl-core does not depend on src/graphics/.
  *
- * This file is the single source of truth for plot trace interfaces and
- * PlotInstruction.  numbl-core re-exports these types so that internal
- * runtime code can import them without reaching into src/graphics/.
- *
- * The numbl-vscode extension syncs this file (and the rest of src/graphics/)
- * via devel/sync-graphics.sh.
+ * The numbl-vscode extension syncs src/graphics/ via devel/sync-graphics.sh;
+ * it also needs the core modules the renderer imports (types, figuresReducer,
+ * axisLimits, imagescExtent, colormaps).
  */
 export interface PlotTrace {
     x: number[];
@@ -53,6 +53,8 @@ export interface PatchTrace {
     edgeColor?: [number, number, number] | "flat" | "interp" | "none";
     /** Face transparency in [0,1]. */
     faceAlpha?: number;
+    /** Edge transparency in [0,1]. */
+    edgeAlpha?: number;
     lineWidth?: number;
     lineStyle?: string;
     marker?: string;

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

@@ -21,13 +21,5 @@ import { type RefcountRuntime } from "./refcount.js";
  *  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/refcount.d.ts

@@ -53,9 +53,6 @@ export declare abstract class Refcounted {
      *  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. */

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

@@ -0,0 +1,15 @@
+/**
+ * Registration helpers for builtins that need the active Runtime. They are
+ * ordinary IBuiltins; each call gets the runtime from the current-runtime
+ * stack.
+ */
+import type { Runtime } from "./runtime.js";
+import type { RuntimeValue } from "./types.js";
+/** The runtime executing the current call. */
+export declare function currentRuntime(): Runtime;
+/** Register a builtin that accepts any args and gets the active runtime. */
+export declare function registerSpecial(name: string, fn: (nargout: number, args: RuntimeValue[], rt: Runtime) => unknown): void;
+/** Register a builtin with no outputs. The call site raises "Too many output
+ *  arguments." when nargout > 0, and `ans` is not set when called as a
+ *  statement. */
+export declare function registerSpecialVoid(name: string, fn: (args: RuntimeValue[], rt: Runtime) => void): void;