numbl 0.4.8 → 0.4.10

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

@@ -0,0 +1,21 @@
+/**
+ * numbl/browser — managed in-browser sessions.
+ *
+ * Usage:
+ *   import { createNumblSession } from "numbl/browser";
+ *   const session = await createNumblSession({
+ *     files: [{ path: "main.m", content: "mip load --install chebfun;\n..." }],
+ *     mainFile: "main.m",
+ *     onOutput: console.log,
+ *   });
+ *   session.dispatchHtmlEvent(compId, "eventName", payload);
+ *
+ * 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).
+ */
+export { createNumblSession, type NumblSession, type NumblSessionOptions, } from "./session.js";
+export type { BootFile, UihtmlComponent } from "./protocol.js";

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

@@ -0,0 +1,10 @@
+export declare const MIP_SYSTEM_PREFIX = "/system/mip/packages/gh/mip-org/core/mip/";
+/** Directory that must be on the search path for `mip` to resolve. */
+export declare const MIP_SEARCH_PATH: string;
+/** Present iff mip core is installed in the VFS. */
+export declare const MIP_MARKER_PATH: string;
+export interface MipCoreFile {
+    path: string;
+    content: Uint8Array;
+}
+export declare function fetchMipCoreFiles(): Promise<MipCoreFile[]>;

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

@@ -0,0 +1,69 @@
+/** Messages between the NumblSession host and its worker. */
+export interface BootFile {
+    path: string;
+    content: string | Uint8Array;
+}
+export interface BootMessage {
+    type: "boot";
+    files: BootFile[];
+    mainFile: string;
+    mip: boolean;
+    persistSystem: boolean;
+    systemInactivityMs: number;
+    optimization: "0" | "1";
+    maxIterations: number;
+    displayResults: boolean;
+}
+export type ToWorker = BootMessage | {
+    type: "writeFile";
+    path: string;
+    content: string | Uint8Array;
+} | {
+    type: "readFile";
+    id: number;
+    path: string;
+} | {
+    type: "dispatch";
+    id: number;
+    compId: string;
+    name: string;
+    data: unknown;
+};
+export interface UihtmlComponent {
+    compId: string;
+    dataJson: string;
+}
+export type FromWorker = {
+    type: "progress";
+    message: string;
+} | {
+    type: "output";
+    text: string;
+} | {
+    type: "uihtml";
+    compId: string;
+    dataJson: string;
+} | {
+    type: "ready";
+    hasUihtmlSession: boolean;
+    components: UihtmlComponent[];
+} | {
+    type: "bootError";
+    message: string;
+} | {
+    type: "htmlSourceEvent";
+    compId: string;
+    name: string;
+    dataJson: string;
+} | {
+    type: "dispatchResult";
+    id: number;
+    ok: boolean;
+    message?: string;
+} | {
+    type: "readFileResult";
+    id: number;
+    ok: boolean;
+    content?: Uint8Array;
+    message?: string;
+};

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

@@ -0,0 +1,60 @@
+import type { BootFile, 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;
+    /**
+     * Bootstrap the mip package manager (fetched from its GitHub release)
+     * so the script can `mip load --install <pkg>`. Default true.
+     */
+    mip?: boolean;
+    /**
+     * Persist the /system directory (mip core + installed packages) in
+     * IndexedDB so later page loads skip the downloads. Default true.
+     */
+    persistSystem?: boolean;
+    /**
+     * Wipe the persisted /system directory after this much inactivity, so a
+     * stale mip core / package set refreshes eventually. Default 24 h.
+     */
+    systemInactivityMs?: number;
+    optimization?: "0" | "1";
+    maxIterations?: number;
+    displayResults?: boolean;
+    /** Console output from the script (fprintf/disp/mip logs). */
+    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;
+    /** Script -> host events (MATLAB `sendEventToHTMLSource`). */
+    onHtmlSourceEvent?: (compId: string, name: string, dataJson: string) => void;
+}
+export interface NumblSession {
+    /** uihtml components the run created, in creation order. */
+    readonly uihtmlComponents: readonly UihtmlComponent[];
+    /** True if the run left a live uihtml session (events can be dispatched). */
+    readonly hasUihtmlSession: boolean;
+    /** Write a file into the session VFS (visible to later dispatched events). */
+    writeFile(path: string, content: string | Uint8Array): void;
+    /**
+     * Read a file from the session VFS (e.g. results the script wrote).
+     * Relative paths resolve under /project/. Rejects if the file is missing.
+     */
+    readFile(path: string): Promise<Uint8Array>;
+    /**
+     * Fire the script's HTMLEventReceivedFcn (host -> MATLAB). Resolves when
+     * the callback returns; rejects if it errors (the session stays usable).
+     */
+    dispatchHtmlEvent(compId: string, name: string, data: unknown): Promise<void>;
+    /** 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).
+ */
+export declare function createNumblSession(options: NumblSessionOptions): Promise<NumblSession>;

package/dist-browser/browser/system-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Dependency-free IndexedDB store for the session's /system directory (mip
+ * core plus packages installed at runtime by `mip load --install`), so
+ * installs persist across page loads. Mirrors the IDE's __system__ project
+ * (db/operations.ts) but is usable from a worker with no Dexie/React.
+ *
+ * Staleness policy matches the IDE's: the whole store is wiped after a
+ * period of inactivity, and mip core is re-fetched on demand — packages are
+ * never individually invalidated.
+ */
+import type { VfsChanges } from "../vfs/VirtualFileSystem.js";
+export interface StoredFile {
+    path: string;
+    content: Uint8Array;
+}
+export declare class SystemStore {
+    private dbPromise;
+    constructor(dbName?: string);
+    /**
+     * Load the stored /system files, first wiping the store if it has been
+     * inactive longer than `inactivityMs`. Marks activity either way.
+     */
+    loadValid(inactivityMs: number): Promise<StoredFile[]>;
+    /** Persist the /system subset of a run's VFS changes. */
+    applyChanges(changes: VfsChanges): Promise<void>;
+    markActivity(): Promise<void>;
+    clear(): Promise<void>;
+    private getMeta;
+    private setMeta;
+}

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

@@ -0,0 +1 @@
+export {};