numbl 0.4.4 → 0.4.5

package/README.md

@@ -1,6 +1,6 @@
 # Numbl
 
-A MATLAB-compatible numerical computing environment with 400+ built-in functions. Runs in your browser or on the command line.
+A numerical computing environment compatible with MATLAB syntax, featuring 400+ built-in functions. Runs in your browser or on the command line.
 
 [![numbl REPL](docs/repl-preview.svg)](https://numbl.org/embed-repl)
 
@@ -61,3 +61,7 @@ Jeremy Magland and Dan Fortunato, Center for Computational Mathematics, Flatiron
 ## License
 
 Apache 2.0
+
+## Disclaimer
+
+numbl is not affiliated with, endorsed by, or supported by MathWorks, Inc. MATLAB is a registered trademark of MathWorks, Inc.

package/dist-cli/cli.js

@@ -347,8 +347,33 @@ Expected directory: ${distDir}`
   const sseClients = [];
   let messageId = 0;
   const pendingMessages = [];
+  let uihtmlHandler;
   const server = createServer((req, res) => {
     const url2 = new URL(req.url ?? "/", `http://localhost`);
+    if (req.method === "POST" && url2.pathname === "/uihtml-event") {
+      const chunks = [];
+      let size2 = 0;
+      let aborted = false;
+      req.on("data", (chunk) => {
+        size2 += chunk.length;
+        if (size2 > 5e6) {
+          aborted = true;
+          req.destroy();
+        } else {
+          chunks.push(chunk);
+        }
+      });
+      req.on("end", () => {
+        if (aborted) return;
+        try {
+          uihtmlHandler?.(JSON.parse(Buffer.concat(chunks).toString("utf-8")));
+        } catch {
+        }
+        res.writeHead(204);
+        res.end();
+      });
+      return;
+    }
     if (url2.pathname === "/events") {
       res.writeHead(200, {
         "Content-Type": "text/event-stream",
@@ -411,12 +436,7 @@ Expected directory: ${distDir}`
   };
   process.on("SIGINT", onExit);
   process.on("SIGTERM", onExit);
-  function sendInstructions(instructions) {
-    messageId++;
-    const payload = `id: ${messageId}
-data: ${JSON.stringify(instructions)}
-
-`;
+  function broadcast(payload) {
     if (sseClients.length === 0) {
       pendingMessages.push(payload);
     } else {
@@ -425,22 +445,41 @@ data: ${JSON.stringify(instructions)}
       }
     }
   }
+  function sendInstructions(instructions) {
+    messageId++;
+    broadcast(`id: ${messageId}
+data: ${JSON.stringify(instructions)}
+
+`);
+  }
+  function sendUihtmlEvent(compId, name, dataJson) {
+    messageId++;
+    const data = JSON.stringify({ compId, name, dataJson });
+    broadcast(`id: ${messageId}
+event: uihtml
+data: ${data}
+
+`);
+  }
+  function setUihtmlEventHandler(fn) {
+    uihtmlHandler = fn;
+  }
   function scriptDone() {
     messageId++;
-    const payload = `id: ${messageId}
+    broadcast(`id: ${messageId}
 event: done
 data: {}
 
-`;
-    if (sseClients.length === 0) {
-      pendingMessages.push(payload);
-    } else {
-      for (const client of sseClients) {
-        client.write(payload);
-      }
-    }
+`);
   }
-  return { sendInstructions, scriptDone, port, closed };
+  return {
+    sendInstructions,
+    sendUihtmlEvent,
+    setUihtmlEventHandler,
+    scriptDone,
+    port,
+    closed
+  };
 }
 function openBrowser(url) {
   const platform = process.platform;
@@ -465,12 +504,34 @@ function createPlotHandler(disabled, plotOpts) {
     return {
       onDrawnow: void 0,
       flushAndWait: async () => {
+      },
+      sendUihtmlEvent: () => {
+      },
+      setUihtmlSession: () => {
       }
     };
   }
   let plotServer = null;
   let serverStarting = null;
   const pendingBatches = [];
+  let session = null;
+  const wireServer = (ps) => {
+    ps.setUihtmlEventHandler((e) => {
+      if (!session) return;
+      const eventType = e.kind === "dataChanged" ? "DataChanged" : "HTMLEventReceived";
+      try {
+        session.dispatchEvent(e.compId, eventType, {
+          name: e.name,
+          data: e.data
+        });
+      } catch (err) {
+        process.stderr.write(
+          `Error in uihtml callback: ${err instanceof Error ? err.message : String(err)}
+`
+        );
+      }
+    });
+  };
   const onDrawnow = (instructions) => {
     if (plotServer) {
       plotServer.sendInstructions(instructions);
@@ -479,6 +540,7 @@ function createPlotHandler(disabled, plotOpts) {
       if (!serverStarting) {
         serverStarting = startPlotServer(plotOpts).then((ps) => {
           plotServer = ps;
+          wireServer(ps);
           for (const batch of pendingBatches) {
             ps.sendInstructions(batch);
           }
@@ -500,7 +562,13 @@ function createPlotHandler(disabled, plotOpts) {
       await plotServer.closed;
     }
   };
-  return { onDrawnow, flushAndWait };
+  const sendUihtmlEvent = (compId, name, dataJson) => {
+    plotServer?.sendUihtmlEvent(compId, name, dataJson);
+  };
+  const setUihtmlSession = (s) => {
+    session = s;
+  };
+  return { onDrawnow, flushAndWait, sendUihtmlEvent, setUihtmlSession };
 }
 
 // src/numbl-core/runtime/refcount.ts
@@ -34494,7 +34562,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;
     }
@@ -38386,6 +38462,10 @@ var SPECIAL_BUILTIN_NAMES = [
   "stream2",
   "ishold",
   "figure",
+  "drawuihtml",
+  "registeruihtmlcallback",
+  "sendEventToHTMLSource",
+  "uigridlayout",
   "subplot",
   "tiledlayout",
   "nexttile",
@@ -39735,15 +39815,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) => {
@@ -41159,6 +41292,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": {
@@ -41599,6 +41745,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;
     }
@@ -41617,9 +41764,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.
@@ -41752,6 +41914,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) {
@@ -41897,6 +42068,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;
@@ -54476,6 +54663,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];
@@ -58942,7 +59272,7 @@ function getSourceLine(getSource, file, line) {
 }
 
 // src/numbl-core/version.ts
-var NUMBL_VERSION = "0.4.4";
+var NUMBL_VERSION = "0.4.5";
 
 // src/cli-repl.ts
 import { createInterface } from "readline";
@@ -64361,6 +64691,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"
   }
 ];
 
@@ -92326,6 +92660,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__";
@@ -92777,6 +93169,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,
@@ -94717,9 +95121,7 @@ ${code2}
       process.exit(0);
     } else if (opts.verbose) {
       const log3 = (msg) => console.error(`[verbose] ${msg}`);
-      const { onDrawnow, flushAndWait } = createPlotHandler(
-        !opts.plot || opts.stream
-      );
+      const plot = createPlotHandler(!opts.plot || opts.stream);
       const result = executeCode(
         code,
         {
@@ -94728,7 +95130,8 @@ ${code2}
           onOutput: (text) => {
             process.stdout.write(text);
           },
-          onDrawnow,
+          onDrawnow: plot.onDrawnow,
+          onHtmlSourceEvent: plot.sendUihtmlEvent,
           log: log3,
           onJitCompile,
           onJitBail,
@@ -94744,13 +95147,11 @@ ${code2}
       );
       writeProfileIfNeeded(result);
       finalizeDumps();
-      await flushAndWait(result.plotInstructions);
+      plot.setUihtmlSession(result.uihtmlSession ?? null);
+      await plot.flushAndWait(result.plotInstructions);
     } else {
       const asyncPlotOpts = opts.plotPort !== void 0 ? { port: opts.plotPort, host: "0.0.0.0" } : void 0;
-      const { onDrawnow, flushAndWait } = createPlotHandler(
-        !opts.plot,
-        asyncPlotOpts
-      );
+      const plot = createPlotHandler(!opts.plot, asyncPlotOpts);
       const result = executeCode(
         code,
         {
@@ -94759,7 +95160,8 @@ ${code2}
           onOutput: (text) => {
             process.stdout.write(text);
           },
-          onDrawnow,
+          onDrawnow: plot.onDrawnow,
+          onHtmlSourceEvent: plot.sendUihtmlEvent,
           onJitCompile,
           onJitBail,
           fileIO,
@@ -94774,7 +95176,8 @@ ${code2}
       );
       writeProfileIfNeeded(result);
       finalizeDumps();
-      await flushAndWait(result.plotInstructions);
+      plot.setUihtmlSession(result.uihtmlSession ?? null);
+      await plot.flushAndWait(result.plotInstructions);
     }
     process.exit(0);
   } catch (error) {

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

@@ -62,6 +62,15 @@ export type FigureState = {
     axes: {
         [index: number]: AxesState;
     };
+    /** When set, this figure is an HTML UI component (MATLAB `uihtml`): the
+     *  `html` string is rendered in an iframe instead of the axes/trace canvas.
+     *  Takes precedence over `axes`. `data` is the JSON-encoded `Data` property
+     *  (from `jsonencode`), pushed into the page's `htmlComponent`. */
+    uihtml?: {
+        id: string;
+        html: string;
+        data?: string;
+    };
 };
 export type FiguresState = {
     currentHandle: number;