numbl 0.4.4 → 0.4.5

package/dist-lib/graphics/types.d.ts

@@ -261,6 +261,17 @@ export type AxisLimitSpec = [number | null, number | null] | "auto";
 export type PlotInstruction = {
     type: "set_figure_handle";
     handle: number;
+} | {
+    /** An HTML UI component (MATLAB `uihtml`): renders self-contained HTML
+     *  markup in an iframe, bypassing the axes/trace model. `html` is the
+     *  full HTMLSource string; `id` is a stable per-component key. `data`, when
+     *  present, is the `Data` property JSON-encoded (via `jsonencode`); the
+     *  renderer parses it and pushes it to the page's `htmlComponent` so the
+     *  `setup`/`"DataChanged"` bridge fires (MATLAB `h.Data` → JavaScript). */
+    type: "uihtml";
+    id: string;
+    html: string;
+    data?: string;
 } | {
     type: "plot";
     traces: PlotTrace[];

package/dist-lib/lib.js

@@ -44556,6 +44556,149 @@ for (const { name, min: min2, max: max2 } of INT_RANGES) {
     ]
   });
 }
+var TYPECAST_VIEWS = {
+  uint8: (b) => new Uint8Array(b),
+  int8: (b) => new Int8Array(b),
+  uint16: (b) => new Uint16Array(b),
+  int16: (b) => new Int16Array(b),
+  uint32: (b) => new Uint32Array(b),
+  int32: (b) => new Int32Array(b),
+  single: (b) => new Float32Array(b),
+  double: (b) => new Float64Array(b)
+};
+defineBuiltin({
+  name: "typecast",
+  help: {
+    signatures: ["B = typecast(X, CLASS)"],
+    description: "Reinterpret the raw bytes of numeric array X as CLASS (e.g. 'uint8', 'single', 'int32'). numbl stores all numerics as double, so X is treated as double-precision; this is mainly for serializing numeric data to bytes, e.g. typecast(double(x), 'uint8')."
+  },
+  cases: [
+    {
+      match: (argTypes) => {
+        if (argTypes.length !== 2) return null;
+        const a = argTypes[0];
+        if (a.kind === "number" || a.kind === "boolean" || a.kind === "tensor" || a.kind === "complex_or_number")
+          return [{ kind: "tensor", isComplex: false }];
+        return null;
+      },
+      apply: (args) => {
+        const X = args[0];
+        const cls = toString(args[1]).toLowerCase();
+        const makeView = TYPECAST_VIEWS[cls];
+        if (!makeView)
+          throw new RuntimeError(`typecast: unsupported class '${cls}'`);
+        let src;
+        if (isRuntimeNumber(X)) src = Float64Array.of(X);
+        else if (isRuntimeLogical(X)) src = Float64Array.of(X ? 1 : 0);
+        else if (isRuntimeTensor(X)) {
+          if (X.imag)
+            throw new RuntimeError("typecast: complex input not supported");
+          src = X.data;
+        } else {
+          throw new RuntimeError("typecast: X must be a numeric array");
+        }
+        const buffer = src.buffer.slice(
+          src.byteOffset,
+          src.byteOffset + src.byteLength
+        );
+        const view = makeView(buffer);
+        const out = allocFloat64Array(view.length);
+        for (let i = 0; i < view.length; i++) out[i] = view[i];
+        return RTV.tensor(out, [1, view.length]);
+      }
+    }
+  ]
+});
+function jsonEncodeNumber(x) {
+  return Number.isFinite(x) ? String(x) : "null";
+}
+function jsonEncodeTensor(v) {
+  if (v.imag && !imagAllZero(v.imag))
+    throw new RuntimeError("jsonencode: complex values are not supported");
+  const data = v.data;
+  const n = data.length;
+  const enc = v._isLogical ? (x) => x ? "true" : "false" : jsonEncodeNumber;
+  const shape = v.shape ?? [n];
+  if (n === 1 && shape.every((s) => s === 1)) return enc(data[0]);
+  if (n === 0) return "[]";
+  const nonSingleton = shape.filter((s) => s > 1).length;
+  if (shape.length <= 1 || nonSingleton <= 1) {
+    const parts2 = [];
+    for (let i = 0; i < n; i++) parts2.push(enc(data[i]));
+    return "[" + parts2.join(",") + "]";
+  }
+  if (shape.length === 2) {
+    const [m, cols] = shape;
+    const rows = [];
+    for (let i = 0; i < m; i++) {
+      const rowParts = [];
+      for (let j = 0; j < cols; j++) rowParts.push(enc(data[j * m + i]));
+      rows.push("[" + rowParts.join(",") + "]");
+    }
+    return "[" + rows.join(",") + "]";
+  }
+  const parts = [];
+  for (let i = 0; i < n; i++) parts.push(enc(data[i]));
+  return "[" + parts.join(",") + "]";
+}
+function jsonEncodeCell(v) {
+  if (v.data.length === 0) return "[]";
+  return "[" + v.data.map(jsonEncodeValue).join(",") + "]";
+}
+function jsonEncodeStruct(v) {
+  const parts = [];
+  for (const [key, val] of v.fields) {
+    parts.push(JSON.stringify(key) + ":" + jsonEncodeValue(val));
+  }
+  return "{" + parts.join(",") + "}";
+}
+function jsonEncodeValue(v) {
+  if (v === void 0 || v === null) return "null";
+  if (isRuntimeNumber(v)) return jsonEncodeNumber(v);
+  if (isRuntimeLogical(v)) return v ? "true" : "false";
+  if (isRuntimeString(v)) return JSON.stringify(v);
+  if (isRuntimeChar(v)) {
+    if (v.shape && v.shape.length === 2 && v.shape[0] > 1) {
+      const rows = v.shape[0];
+      const cols = v.shape[1];
+      const out = [];
+      for (let i = 0; i < rows; i++) {
+        let row = "";
+        for (let j = 0; j < cols; j++) row += v.value[j * rows + i] ?? "";
+        out.push(JSON.stringify(row));
+      }
+      return "[" + out.join(",") + "]";
+    }
+    return JSON.stringify(v.value);
+  }
+  if (isRuntimeComplexNumber(v)) {
+    if (v.im !== 0)
+      throw new RuntimeError("jsonencode: complex values are not supported");
+    return jsonEncodeNumber(v.re);
+  }
+  if (isRuntimeTensor(v)) return jsonEncodeTensor(v);
+  if (isRuntimeCell(v)) return jsonEncodeCell(v);
+  if (isRuntimeStruct(v)) return jsonEncodeStruct(v);
+  if (isRuntimeStructArray(v))
+    return "[" + v.elements.map(jsonEncodeStruct).join(",") + "]";
+  throw new RuntimeError("jsonencode: unsupported value type");
+}
+defineBuiltin({
+  name: "jsonencode",
+  help: {
+    signatures: ["txt = jsonencode(V)"],
+    description: "Encode value V (struct, cell, char/string, logical, or numeric array) as a JSON-formatted char row vector."
+  },
+  cases: [
+    {
+      match: (argTypes) => {
+        if (argTypes.length < 1) return null;
+        return [{ kind: "char" }];
+      },
+      apply: (args) => RTV.char(jsonEncodeValue(args[0]))
+    }
+  ]
+});
 function idivideMode(args) {
   if (args.length < 3) return "fix";
   const m = args[2];
@@ -51289,7 +51432,15 @@ function dispatchPlotBuiltin(name, args, instructions, state) {
       return true;
     // ── Graphics ops: figure / labels / hold / layout ──────────────
     case "figure": {
-      const handle = args.length > 0 ? args[0] : 1;
+      let handle;
+      if (args.length > 0) {
+        handle = toNumber(args[0]);
+        state.maxFigureHandle = Math.max(state.maxFigureHandle ?? 0, handle);
+      } else {
+        handle = (state.maxFigureHandle ?? 0) + 1;
+        state.maxFigureHandle = handle;
+      }
+      state.currentFigureHandle = handle;
       plotInstr(instructions, { type: "set_figure_handle", handle });
       return true;
     }
@@ -52236,6 +52387,10 @@ var SPECIAL_BUILTIN_NAMES = [
   "stream2",
   "ishold",
   "figure",
+  "drawuihtml",
+  "registeruihtmlcallback",
+  "sendEventToHTMLSource",
+  "uigridlayout",
   "subplot",
   "tiledlayout",
   "nexttile",
@@ -53585,15 +53740,68 @@ function registerSpecialBuiltins(rt) {
     return rt.ishold();
   });
   registerSpecial("figure", (nargout, args) => {
-    const handle = args.length > 0 ? args[0] : 1;
     dispatchPlotBuiltin(
       "figure",
       args.map(ensureRuntimeValue),
       rt.plotInstructions,
       rt
     );
-    return nargout >= 1 ? RTV.num(toNumber(ensureRuntimeValue(handle))) : void 0;
+    return nargout >= 1 ? RTV.num(rt.currentFigureHandle) : void 0;
+  });
+  let uihtmlSeq = 0;
+  registerSpecial("drawuihtml", (nargout, args) => {
+    const html = args.length > 0 ? toString(ensureRuntimeValue(args[0])) : "";
+    const data = args.length > 1 ? toString(ensureRuntimeValue(args[1])) : void 0;
+    uihtmlSeq += 1;
+    const id = "uh" + uihtmlSeq;
+    rt.plotInstructions.push({
+      type: "uihtml",
+      id,
+      html,
+      ...data !== void 0 ? { data } : {}
+    });
+    return nargout >= 1 ? RTV.char(id) : void 0;
+  });
+  registerSpecial("registeruihtmlcallback", (_nargout, args) => {
+    if (args.length < 3) return void 0;
+    const compId = toString(ensureRuntimeValue(args[0]));
+    const eventType = toString(ensureRuntimeValue(args[1]));
+    const fcn = ensureRuntimeValue(args[2]);
+    if (eventType !== "HTMLEventReceived" && eventType !== "DataChanged") {
+      return void 0;
+    }
+    if (!isRuntimeFunction(fcn)) return void 0;
+    const entry = rt.uihtmlCallbacks.get(compId) ?? {};
+    const prev = entry[eventType];
+    if (prev) decref(rt, prev);
+    incref(fcn);
+    entry[eventType] = fcn;
+    rt.uihtmlCallbacks.set(compId, entry);
+    return void 0;
+  });
+  registerSpecial("sendEventToHTMLSource", (_nargout, args) => {
+    if (args.length < 2) {
+      throw new RuntimeError("sendEventToHTMLSource requires src and name");
+    }
+    const src = ensureRuntimeValue(args[0]);
+    if (!isRuntimeStruct(src) || !src.fields.has("ComponentId")) {
+      throw new RuntimeError(
+        "sendEventToHTMLSource: src must be the component passed to the callback"
+      );
+    }
+    const compId = toString(src.fields.get("ComponentId"));
+    const name = toString(ensureRuntimeValue(args[1]));
+    const dataArg = args.length > 2 ? ensureRuntimeValue(args[2]) : RTV.num(0);
+    const dataJson = toString(
+      ensureRuntimeValue(rt.dispatch("jsonencode", 1, [dataArg]))
+    );
+    rt.onHtmlSourceEvent?.(compId, name, dataJson);
+    return void 0;
   });
+  registerSpecial(
+    "uigridlayout",
+    (nargout) => nargout >= 1 ? RTV.num(0) : void 0
+  );
   const PLOT_RETURNS_ZERO = ["subplot", "tiledlayout", "nexttile", "legend"];
   for (const name of PLOT_RETURNS_ZERO) {
     registerSpecial(name, (nargout, args) => {
@@ -56434,6 +56642,19 @@ var figuresReducer = (state, action) => {
   switch (action.type) {
     case "set_figure_handle":
       return { ...state, currentHandle: action.handle };
+    case "uihtml": {
+      const fig = ensureFig(state);
+      return {
+        ...state,
+        figs: {
+          ...state.figs,
+          [state.currentHandle]: {
+            ...fig,
+            uihtml: { id: action.id, html: action.html, data: action.data }
+          }
+        }
+      };
+    }
     case "set_hold":
       return updateAxes(state, { holdOn: action.value });
     case "plot": {
@@ -56874,6 +57095,7 @@ var Runtime = class _Runtime {
     this.profilingEnabled = !!options.profile;
     this.fileIO = options.fileIO;
     this.system = options.system;
+    this.onHtmlSourceEvent = options.onHtmlSourceEvent;
     if (options.initialHoldState) {
       this.holdState = options.initialHoldState;
     }
@@ -56892,9 +57114,24 @@ var Runtime = class _Runtime {
   plotInstructions = [];
   variableValues = {};
   holdState = false;
+  /** Figure-handle tracking for MATLAB-style `figure` allocation: `figure`
+   *  with no argument creates a new figure (`maxFigureHandle + 1`). */
+  currentFigureHandle = 0;
+  maxFigureHandle = 0;
   /** Monotonic id source for graphics handles whose trace can be live-updated
    *  via `set` / `update_trace` (e.g. lines returned by `line`). */
   graphicsIdCounter = 1;
+  /** Reverse channel for `uihtml` components (HTML → MATLAB). Maps a component
+   *  id (the `uihtml` instruction's `id`) to the callback handles registered
+   *  for it. When non-empty after a run, the host keeps this runtime alive so
+   *  iframe events can re-enter the interpreter and invoke these handles.
+   *  Handles are incref'd while stored (see registeruihtmlcallback). */
+  uihtmlCallbacks = /* @__PURE__ */ new Map();
+  /** Hook invoked by `sendEventToHTMLSource(src, name, data)` to push an event
+   *  from MATLAB back to a uihtml component's page. `dataJson` is the data
+   *  already `jsonencode`d. Set from ExecOptions; the host forwards it to the
+   *  iframe. */
+  onHtmlSourceEvent;
   // tiledlayout/nexttile state. Reset by tiledlayout, advanced by nexttile.
   // mode: "fixed" uses the rows/cols verbatim; "flow"/"vertical"/"horizontal"
   // grow the grid as tiles are added.
@@ -57027,6 +57264,15 @@ var Runtime = class _Runtime {
     }
   }
   // ── Builtin initialization ──────────────────────────────────────────
+  /** Register the implicit default figure (handle 1) the first time a graphics
+   *  op runs without an explicit `figure`, so a later no-arg `figure` allocates
+   *  a new handle instead of reusing 1 (MATLAB semantics). */
+  ensureCurrentFigure() {
+    if (!this.currentFigureHandle) {
+      this.currentFigureHandle = 1;
+      this.maxFigureHandle = Math.max(this.maxFigureHandle, 1);
+    }
+  }
   initBuiltins() {
     registerSpecialBuiltins(this);
     for (const name of PLOT_DISPATCH_NAMES) {
@@ -57172,6 +57418,22 @@ var Runtime = class _Runtime {
     this.builtins["stream2"] = (_nargout, args) => {
       return stream2Call(args.map(ensureRuntimeValue));
     };
+    const NO_AUTO_FIGURE = /* @__PURE__ */ new Set(["figure", "close", "clf", "cla", "axis"]);
+    for (const name of [
+      ...PLOT_DISPATCH_NAMES,
+      "fplot",
+      "fplot3",
+      "streamline",
+      "stream2"
+    ]) {
+      if (NO_AUTO_FIGURE.has(name)) continue;
+      const orig = this.builtins[name];
+      if (!orig) continue;
+      this.builtins[name] = (n, a) => {
+        this.ensureCurrentFigure();
+        return orig(n, a);
+      };
+    }
   }
   profileEnter(key) {
     if (!this.profilingEnabled) return;
@@ -63616,6 +63878,10 @@ end
   {
     name: "isIllConditioned.m",
     source: "function result = isIllConditioned(dA)\n    result = dA.isIllCond;\nend\n"
+  },
+  {
+    name: "uihtml.m",
+    source: "classdef uihtml < handle\n    %UIHTML Create an HTML UI component (numbl subset).\n    %   H = UIHTML('HTMLSource', HTML) renders the self-contained HTML string\n    %   HTML in the figure pane. An optional leading parent argument (e.g. a\n    %   figure) is accepted and ignored. Supported name-value options:\n    %   HTMLSource, Data, Position.\n    %\n    %   H = UIHTML('HTMLSource', HTML, 'Data', X) also sends X into the page.\n    %   Mirroring MATLAB, X is encoded with jsonencode, parsed in the page with\n    %   JSON.parse, and set on the JavaScript `htmlComponent.Data` object,\n    %   firing any \"DataChanged\" listener registered in the page's\n    %   `function setup(htmlComponent)`. To update the data after construction,\n    %   set H.Data and call show(H) (numbl re-renders the component):\n    %\n    %       h = uihtml('HTMLSource', html, 'Data', struct('n', 1));\n    %       h.Data = struct('n', 2);\n    %       show(h);\n    %\n    %   numbl currently supports HTMLSource given as an HTML markup string (a\n    %   single self-contained document). HTML file paths and supporting files\n    %   are not yet supported.\n    %\n    %   The reverse channel (page -> MATLAB) is supported for the IDE:\n    %   HTMLEventReceivedFcn fires when JS calls\n    %   htmlComponent.sendEventToMATLAB(name,data); inside the callback use\n    %   sendEventToHTMLSource(src,name,data) to send back to the page.\n    %   DataChangedFcn fires when JS sets htmlComponent.Data. Register callbacks\n    %   at construction (name-value) since numbl renders at construction.\n    properties\n        HTMLSource = ''\n        Data = []\n        Position = [100 100 100 100]\n        HTMLEventReceivedFcn = []\n        DataChangedFcn = []\n    end\n    methods\n        function obj = uihtml(varargin)\n            args = varargin;\n            % Ignore an optional leading parent argument (anything that is not\n            % a name-value name string).\n            if numel(args) >= 1 && ~(ischar(args{1}) || isstring(args{1}))\n                args = args(2:end);\n            end\n            for i = 1:2:numel(args) - 1\n                name = args{i};\n                val = args{i + 1};\n                if strcmpi(name, 'HTMLSource')\n                    obj.HTMLSource = val;\n                elseif strcmpi(name, 'Data')\n                    obj.Data = val;\n                elseif strcmpi(name, 'Position')\n                    obj.Position = val;\n                elseif strcmpi(name, 'HTMLEventReceivedFcn')\n                    obj.HTMLEventReceivedFcn = val;\n                elseif strcmpi(name, 'DataChangedFcn')\n                    obj.DataChangedFcn = val;\n                end\n            end\n            render(obj);\n        end\n\n        function show(obj)\n            render(obj);\n        end\n\n        function render(obj)\n            if isempty(obj.HTMLSource)\n                return;\n            end\n            if isempty(obj.Data)\n                id = drawuihtml(obj.HTMLSource);\n            else\n                id = drawuihtml(obj.HTMLSource, jsonencode(obj.Data));\n            end\n            if ~isempty(obj.HTMLEventReceivedFcn)\n                registeruihtmlcallback(id, 'HTMLEventReceived', ...\n                                       obj.HTMLEventReceivedFcn);\n            end\n            if ~isempty(obj.DataChangedFcn)\n                registeruihtmlcallback(id, 'DataChanged', obj.DataChangedFcn);\n            end\n        end\n    end\nend\n"
   }
 ];
 
@@ -91570,6 +91836,64 @@ function registerExecutorsForOpt(registry3, opt) {
   }
 }
 
+// src/numbl-core/runtime/uihtmlSession.ts
+function createUihtmlSession(rt, activeSpecials, onDrawnow) {
+  function invokeHandle(fn, args) {
+    if (fn.jsFn) {
+      if (fn.jsFnExpectsNargout) fn.jsFn(0, ...args);
+      else fn.jsFn(...args);
+      return;
+    }
+    rt.dispatch(fn.name, 0, args);
+  }
+  function dispatchEvent(compId, eventType, payload) {
+    const entry = rt.uihtmlCallbacks.get(compId);
+    const fn = entry?.[eventType];
+    if (!fn || !isRuntimeFunction(fn)) return;
+    const saved = /* @__PURE__ */ new Map();
+    for (const name of SPECIAL_BUILTIN_NAMES) {
+      const ex = getIBuiltin(name);
+      if (ex) saved.set(name, ex);
+    }
+    for (const ib of activeSpecials.values()) registerDynamicIBuiltin(ib);
+    pushCurrentRuntime(rt);
+    const before = rt.plotInstructions.length;
+    try {
+      const src = RTV.struct({ ComponentId: RTV.char(compId) });
+      const dataRV = convertJsonValue(payload.data);
+      const event = eventType === "HTMLEventReceived" ? RTV.struct({
+        HTMLEventName: RTV.char(payload.name ?? ""),
+        HTMLEventData: dataRV,
+        Source: src,
+        EventName: RTV.char("HTMLEventReceived")
+      }) : RTV.struct({
+        Data: dataRV,
+        PreviousData: RTV.tensor(new Float64Array(0), [0, 0]),
+        Source: src,
+        EventName: RTV.char("DataChanged")
+      });
+      invokeHandle(fn, [src, event]);
+    } finally {
+      popCurrentRuntime(rt);
+      for (const ib of saved.values()) registerDynamicIBuiltin(ib);
+    }
+    const newInstrs = rt.plotInstructions.slice(before);
+    if (newInstrs.length && onDrawnow) onDrawnow(newInstrs);
+  }
+  function dispose() {
+    for (const entry of rt.uihtmlCallbacks.values()) {
+      if (entry.HTMLEventReceived) decref(rt, entry.HTMLEventReceived);
+      if (entry.DataChanged) decref(rt, entry.DataChanged);
+    }
+    rt.uihtmlCallbacks.clear();
+  }
+  return {
+    hasCallbacks: () => rt.uihtmlCallbacks.size > 0,
+    dispatchEvent,
+    dispose
+  };
+}
+
 // src/numbl-core/executeCode.ts
 globalThis.FloatXArray = Float64Array;
 var SHIM_SEARCH_PATH = "__numbl_shims__";
@@ -92021,6 +92345,18 @@ ${sections.join("\n\n")}` : `// No ${label} generated`;
       variableValues: interpreter.getVariableValues(),
       holdState: rt.holdState
     };
+    if (rt.uihtmlCallbacks.size > 0) {
+      const activeSpecials = /* @__PURE__ */ new Map();
+      for (const name of SPECIAL_BUILTIN_NAMES) {
+        const ex = getIBuiltin(name);
+        if (ex) activeSpecials.set(name, ex);
+      }
+      result.uihtmlSession = createUihtmlSession(
+        rt,
+        activeSpecials,
+        options.onDrawnow
+      );
+    }
     if (options.profile) {
       result.profileData = {
         executionTimeMs,

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

@@ -10,6 +10,8 @@ import type { FileIOAdapter } from "./fileIOAdapter.js";
 import type { SystemAdapter } from "./systemAdapter.js";
 import type { WorkspaceFile } from "../numbl-core/workspace/index.js";
 import type { NativeBridge } from "./workspace/index.js";
+import { type UihtmlSession } from "./runtime/uihtmlSession.js";
+export type { UihtmlSession } from "./runtime/uihtmlSession.js";
 export interface ExecOptions {
     onOutput?: (text: string) => void;
     onDrawnow?: (plotInstructions: PlotInstruction[]) => void;
@@ -48,6 +50,10 @@ export interface ExecOptions {
     implicitCwdPath?: string | null;
     /** SharedArrayBuffer for cooperative cancellation. Int32[0] != 0 means cancelled. */
     cancelSAB?: SharedArrayBuffer;
+    /** Hook for `sendEventToHTMLSource(src,name,data)` — pushes an event from a
+     *  uihtml callback back to the component's page (MATLAB → JS). `dataJson` is
+     *  the data already `jsonencode`d. The host forwards it to the iframe. */
+    onHtmlSourceEvent?: (compId: string, name: string, dataJson: string) => void;
 }
 export interface BuiltinProfileEntry {
     totalTimeMs: number;
@@ -94,5 +100,9 @@ export interface ExecResult {
     workspaceFiles?: WorkspaceFile[];
     /** Final implicit cwd path (for REPL persistence across commands). */
     implicitCwdPath?: string | null;
+    /** Present when the run left `uihtml` reverse-channel callbacks registered.
+     *  The host retains this to dispatch later iframe events into the still-live
+     *  interpreter (see UihtmlSession). Absent for normal runs (no overhead). */
+    uihtmlSession?: UihtmlSession;
 }
 export declare function executeCode(source: string, options?: ExecOptions, workspaceFiles?: WorkspaceFile[], mainFileName?: string, searchPaths?: string[], nativeBridge?: NativeBridge): ExecResult;

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

@@ -42,6 +42,12 @@ import type { PlotInstruction } from "../../graphics/types.js";
 export interface PlotDispatchState {
     holdState: boolean;
     tiledLayoutState: TiledLayoutState | null;
+    /** Current figure handle (0 = none created yet). */
+    currentFigureHandle?: number;
+    /** Highest figure handle allocated so far. `figure` with no argument
+     *  creates a NEW figure with handle `maxFigureHandle + 1` (MATLAB
+     *  semantics), rather than always reusing handle 1. */
+    maxFigureHandle?: number;
 }
 /** Active tiled-layout grid. `mode` controls how the grid grows: in
  *  `flow` (default), nexttile expands rows/cols to fit; `vertical` and

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

@@ -32,9 +32,27 @@ export declare class Runtime {
     plotInstructions: PlotInstruction[];
     variableValues: Record<string, RuntimeValue>;
     holdState: boolean;
+    /** Figure-handle tracking for MATLAB-style `figure` allocation: `figure`
+     *  with no argument creates a new figure (`maxFigureHandle + 1`). */
+    currentFigureHandle: number;
+    maxFigureHandle: number;
     /** Monotonic id source for graphics handles whose trace can be live-updated
      *  via `set` / `update_trace` (e.g. lines returned by `line`). */
     graphicsIdCounter: number;
+    /** Reverse channel for `uihtml` components (HTML → MATLAB). Maps a component
+     *  id (the `uihtml` instruction's `id`) to the callback handles registered
+     *  for it. When non-empty after a run, the host keeps this runtime alive so
+     *  iframe events can re-enter the interpreter and invoke these handles.
+     *  Handles are incref'd while stored (see registeruihtmlcallback). */
+    uihtmlCallbacks: Map<string, {
+        HTMLEventReceived?: RuntimeValue;
+        DataChanged?: RuntimeValue;
+    }>;
+    /** Hook invoked by `sendEventToHTMLSource(src, name, data)` to push an event
+     *  from MATLAB back to a uihtml component's page. `dataJson` is the data
+     *  already `jsonencode`d. Set from ExecOptions; the host forwards it to the
+     *  iframe. */
+    onHtmlSourceEvent?: (compId: string, name: string, dataJson: string) => void;
     tiledLayoutState: {
         rows: number;
         cols: number;
@@ -142,6 +160,10 @@ export declare class Runtime {
      *  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;
+    /** Register the implicit default figure (handle 1) the first time a graphics
+     *  op runs without an explicit `figure`, so a later no-arg `figure` allocates
+     *  a new handle instead of reusing 1 (MATLAB semantics). */
+    ensureCurrentFigure(): void;
     private initBuiltins;
     profileEnter(key: string): void;
     profileLeave(): void;

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

@@ -0,0 +1,40 @@
+/**
+ * uihtml reverse channel (HTML → MATLAB) for a finished run.
+ *
+ * When a script creates a `uihtml` component with a callback
+ * (HTMLEventReceivedFcn / DataChangedFcn), the run leaves entries in
+ * `rt.uihtmlCallbacks`. `executeCode` then builds a `UihtmlSession` and returns
+ * it so the host (the worker) can keep the interpreter alive and re-enter it
+ * when an event arrives from the iframe — mirroring MATLAB, where the script
+ * returns but its callbacks keep firing.
+ *
+ * Dispatch re-activates the run's own special-builtin closures (captured at
+ * end-of-run, NOT re-registered — re-registering would reset their counters)
+ * and pushes the runtime so `disp`, plotting, and `sendEventToHTMLSource`
+ * inside the callback reach this runtime. This mirrors executeCode's own
+ * save/restore of SPECIAL_BUILTIN_NAMES.
+ */
+import type { Runtime } from "./runtime.js";
+import type { PlotInstruction } from "../../graphics/types.js";
+import { type IBuiltin } from "../interpreter/builtins/types.js";
+export interface UihtmlSession {
+    /** True while at least one component still has a registered callback. */
+    hasCallbacks(): boolean;
+    /** Dispatch an event from a component's page into MATLAB. `eventType` is
+     *  "HTMLEventReceived" (JS `sendEventToMATLAB`) or "DataChanged" (JS set
+     *  `htmlComponent.Data`). `payload.data` is the structured-clone'd JS value.
+     *  New plot output is flushed via `onDrawnow`; outgoing
+     *  `sendEventToHTMLSource` calls go through `rt.onHtmlSourceEvent`. */
+    dispatchEvent(compId: string, eventType: "HTMLEventReceived" | "DataChanged", payload: {
+        name?: string;
+        data: unknown;
+    }): void;
+    /** Release the retained callback handles (and their refs). */
+    dispose(): void;
+}
+/**
+ * Build a session over a runtime that registered uihtml callbacks.
+ * `activeSpecials` is a snapshot of this runtime's special-builtin closures,
+ * captured at end-of-run while they are still installed globally.
+ */
+export declare function createUihtmlSession(rt: Runtime, activeSpecials: Map<string, IBuiltin>, onDrawnow?: (plotInstructions: PlotInstruction[]) => void): UihtmlSession;

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