numbl 0.4.13 → 0.4.15

package/README.md

@@ -50,10 +50,6 @@ Full documentation is available at **[numbl.org/docs](https://numbl.org/docs)**,
 
 The [Numbl extension for VS Code](https://marketplace.visualstudio.com/items?itemName=jmagland.numbl) provides inline error diagnostics and a built-in figure viewer.
 
-## Embedding
-
-Numbl scripts can be embedded in HTML and Markdown pages. See the [numbl-embed-example](https://magland.github.io/numbl-embed-example/) for usage and a [live demo](https://magland.github.io/numbl-embed-example/example1).
-
 ## Authors
 
 Jeremy Magland and Dan Fortunato, Center for Computational Mathematics, Flatiron Institute.

package/dist-browser/browser/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * numbl/browser — managed in-browser sessions.
  *
- * Usage:
+ * Run-a-script usage:
  *   import { createNumblSession } from "numbl/browser";
  *   const session = await createNumblSession({
  *     files: [{ path: "main.m", content: "mip load --install chebfun;\n..." }],
@@ -10,12 +10,21 @@
  *   });
  *   session.dispatchHtmlEvent(compId, "eventName", payload);
  *
+ * REPL usage (persistent workspace across calls):
+ *   const session = await createNumblSession({ onOutput: console.log });
+ *   await session.execute("x = linspace(0, 2*pi, 100);");
+ *   const { plotInstructions } = await session.execute("plot(x, sin(x))");
+ *   // render plotInstructions with figuresReducer/FigureView from numbl/graphics
+ *
  * The session runs in a worker numbl manages (inlined at build time — no
  * bundler worker support needed), with mip bootstrapped from its GitHub
  * release and installed packages persisted in IndexedDB across page loads.
  *
- * Not available in sessions: delaunay/convhull (qhull WASM is not loaded)
- * and non-uihtml figures (plot instructions other than uihtml are ignored).
+ * Figures are not rendered by the session itself: plot instructions are
+ * returned/surfaced for the host to render (numbl/graphics provides a React
+ * renderer). Not available in sessions: delaunay/convhull (qhull WASM is not
+ * loaded).
  */
 export { createNumblSession, type NumblSession, type NumblSessionOptions, } from "./session.js";
-export type { BootFile, UihtmlComponent } from "./protocol.js";
+export type { BootFile, ExecuteResult, UihtmlComponent } from "./protocol.js";
+export type { PlotInstruction } from "../graphics/types.js";

package/dist-browser/browser/protocol.d.ts

@@ -1,4 +1,5 @@
 /** Messages between the NumblSession host and its worker. */
+import type { PlotInstruction } from "../graphics/types.js";
 export interface BootFile {
     path: string;
     content: string | Uint8Array;
@@ -6,13 +7,22 @@ export interface BootFile {
 export interface BootMessage {
     type: "boot";
     files: BootFile[];
-    mainFile: string;
+    /** Script to run at boot. When omitted, the session boots idle and code is
+     *  run incrementally via `execute`. */
+    mainFile?: string;
     mip: boolean;
     persistSystem: boolean;
     systemInactivityMs: number;
     optimization: "0" | "1";
     maxIterations: number;
     displayResults: boolean;
+    /**
+     * Shared cancellation flag (Int32[0] != 0 ⇒ cancel the running code). The
+     * worker keeps this reference and passes it to every executeCode call, so
+     * the host can interrupt a runaway run cooperatively. Only present when the
+     * page is cross-origin isolated (SharedArrayBuffer available).
+     */
+    cancelSAB?: SharedArrayBuffer;
 }
 export type ToWorker = BootMessage | {
     type: "writeFile";
@@ -22,6 +32,10 @@ export type ToWorker = BootMessage | {
     type: "readFile";
     id: number;
     path: string;
+} | {
+    type: "execute";
+    id: number;
+    code: string;
 } | {
     type: "dispatch";
     id: number;
@@ -31,8 +45,26 @@ export type ToWorker = BootMessage | {
 };
 export interface UihtmlComponent {
     compId: string;
+    /** The component's HTML markup (render with buildUihtmlSrcDoc). */
+    html: string;
+    /** The component's Data, JSON-encoded. */
     dataJson: string;
 }
+export interface ExecuteResult {
+    ok: boolean;
+    /** Concatenated console output (also streamed live via onOutput). */
+    output: string;
+    /** Every plot instruction the execution produced, uihtml included. */
+    plotInstructions: PlotInstruction[];
+    /** Formatted error message when `ok` is false. */
+    error?: string;
+    /**
+     * True when the run ended because it was interrupted via
+     * `NumblSession.interrupt()` (rather than finishing or erroring). The
+     * workspace is left at its pre-run state, so variables survive the abort.
+     */
+    aborted?: boolean;
+}
 export type FromWorker = {
     type: "progress";
     message: string;
@@ -42,6 +74,7 @@ export type FromWorker = {
 } | {
     type: "uihtml";
     compId: string;
+    html: string;
     dataJson: string;
 } | {
     type: "ready";
@@ -55,6 +88,10 @@ export type FromWorker = {
     compId: string;
     name: string;
     dataJson: string;
+} | {
+    type: "executeResult";
+    id: number;
+    result: ExecuteResult;
 } | {
     type: "dispatchResult";
     id: number;

package/dist-browser/browser/session.d.ts

@@ -1,9 +1,10 @@
-import type { BootFile, UihtmlComponent } from "./protocol.js";
+import type { BootFile, ExecuteResult, UihtmlComponent } from "./protocol.js";
 export interface NumblSessionOptions {
-    /** Project files. Relative paths land under /project/. */
-    files: BootFile[];
-    /** The script to run, as one of the paths in `files`. */
-    mainFile: string;
+    /** Project files. Relative paths land under /project/. Default none. */
+    files?: BootFile[];
+    /** The script to run at boot, as one of the paths in `files`. When omitted
+     *  the session boots idle; run code incrementally with `execute`. */
+    mainFile?: string;
     /**
      * Bootstrap the mip package manager (fetched from its GitHub release)
      * so the script can `mip load --install <pkg>`. Default true.
@@ -26,8 +27,8 @@ export interface NumblSessionOptions {
     onOutput?: (text: string) => void;
     /** Boot progress (package downloads, engine start). */
     onProgress?: (message: string) => void;
-    /** A uihtml component was created/updated (its Data JSON-encoded). */
-    onUihtml?: (compId: string, dataJson: string) => void;
+    /** A uihtml component was created/updated (Data JSON-encoded + markup). */
+    onUihtml?: (compId: string, dataJson: string, html: string) => void;
     /** Script -> host events (MATLAB `sendEventToHTMLSource`). */
     onHtmlSourceEvent?: (compId: string, name: string, dataJson: string) => void;
 }
@@ -36,6 +37,14 @@ export interface NumblSession {
     readonly uihtmlComponents: readonly UihtmlComponent[];
     /** True if the run left a live uihtml session (events can be dispatched). */
     readonly hasUihtmlSession: boolean;
+    /**
+     * Execute code against the session's persistent workspace (REPL semantics:
+     * variables persist across calls, expression results are auto-displayed).
+     * Resolves with the run's output and plot instructions; a numbl error
+     * resolves with `ok: false` and a formatted `error` (the promise rejects
+     * only on session-level failures). Calls run sequentially in the worker.
+     */
+    execute(code: string): Promise<ExecuteResult>;
     /** Write a file into the session VFS (visible to later dispatched events). */
     writeFile(path: string, content: string | Uint8Array): void;
     /**
@@ -48,13 +57,28 @@ export interface NumblSession {
      * the callback returns; rejects if it errors (the session stays usable).
      */
     dispatchHtmlEvent(compId: string, name: string, data: unknown): Promise<void>;
+    /**
+     * Cooperatively interrupt the currently running `execute` (or boot script):
+     * sets a shared cancel flag the worker polls at loop iterations and function
+     * calls, so it throws and the pending `execute` resolves with
+     * `aborted: true`. The worker and the persistent workspace survive — only
+     * the running command is abandoned. No-op when `canInterrupt` is false.
+     */
+    interrupt(): void;
+    /**
+     * Whether `interrupt()` can actually stop a run. True only when the page is
+     * cross-origin isolated (SharedArrayBuffer available). When false, a runaway
+     * run can only be stopped by disposing the session.
+     */
+    readonly canInterrupt: boolean;
     /** Terminate the worker. The session is unusable afterwards. */
     dispose(): void;
 }
 /**
  * Boot a numbl session in a dedicated worker: restore the persisted /system
- * directory, bootstrap mip, run `mainFile`, and keep the uihtml session live.
- * Resolves once the main script has finished (including any
- * `mip load --install` downloads it performs).
+ * directory, bootstrap mip, run `mainFile` when given, and keep the uihtml
+ * session live. Resolves once boot (and the main script, if any) has
+ * finished, including any `mip load --install` downloads it performs.
+ * Without a `mainFile` the session boots idle — run code with `execute`.
  */
 export declare function createNumblSession(options: NumblSessionOptions): Promise<NumblSession>;