@tlockney/cdp-kernel 0.7.0 → 0.7.1

package/dist/browser/mod.d.ts

@@ -1,13 +1,16 @@
+import type { JsonObject } from "../message.ts";
 import type { TypeStripper, TypeStripperName } from "../transform.ts";
 import { type Channel, type JupyterMessage, type MessageListener } from "./channels.ts";
 import { type BrowserTargetOptions } from "./target.ts";
 export type { Channel, JupyterMessage, MessageListener } from "./channels.ts";
-export { BrowserTarget, type BrowserTargetOptions, type WorkerLike } from "./target.ts";
+export { BrowserTarget, type BrowserTargetOptions, type HostHandler, type HostRequest, type WorkerLike } from "./target.ts";
 export interface BrowserKernelOptions extends BrowserTargetOptions {
     /** What strips cells' types; sucrase by default, since esbuild's native binary can't run in a page. */
     typeStrip?: TypeStripperName | TypeStripper;
     /** Where the kernel's own log lines go; console.debug by default. */
     log?(text: string): void;
+    /** Returned as `capabilities` in kernel_info_reply: what this page offers cells (#384). */
+    capabilities?: JsonObject;
 }
 export interface BrowserKernel {
     /** A message from the frontend, on shell, control or stdin. */
@@ -16,5 +19,7 @@ export interface BrowserKernel {
     onMessage(listener: MessageListener): () => void;
     /** Settles once a shutdown_request has been answered. */
     readonly closed: Promise<void>;
+    /** An event for the Worker's `host.onEvent` listeners; dropped while no Worker runs (#384). */
+    notifyHost(event: string, value?: unknown): void;
 }
 export declare function startBrowserKernel(options: BrowserKernelOptions): BrowserKernel;

package/dist/browser/mod.js

@@ -20,12 +20,14 @@ export function startBrowserKernel(options) {
     const log = options.log ?? ((text) => console.debug(`[cdp-kernel] ${text}`));
     let closed;
     const closedPromise = new Promise((resolve) => (closed = resolve));
+    let target = null;
     const core = new KernelCore({
         runtime: "browser",
         version: VERSION,
         channels,
-        launchTarget: (events) => BrowserTarget.launch(events, options),
+        launchTarget: async (events) => (target = await BrowserTarget.launch(events, options)),
         typeStrip: options.typeStrip ?? "sucrase",
+        capabilities: options.capabilities,
         log,
         exit: () => closed(),
     });
@@ -34,5 +36,6 @@ export function startBrowserKernel(options) {
         send: (channel, msg) => channels.deliver(channel, msg),
         onMessage: (listener) => channels.onMessage(listener),
         closed: closedPromise,
+        notifyHost: (event, value) => target?.notifyHost(event, value),
     };
 }

package/dist/browser/target.d.ts

@@ -22,7 +22,27 @@ export interface BrowserTargetOptions {
     base?: string;
     /** Where npm:, jsr: and bare imports load from; esm.sh by default. */
     cdn?: string;
+    /**
+     * Modules the Worker imports before the first cell, each time it starts,
+     * resolved against `base`. A module's default export, if a function, is
+     * called with `{ host, jupyter }` (#384).
+     */
+    preload?: string[];
+    /** Answers the Worker's `host.request` calls; without it they reject (#384). */
+    host?: HostHandler;
+}
+/** A request a preload module made with `host.request(method, params)`. */
+export interface HostRequest {
+    method: string;
+    params: unknown;
 }
+/**
+ * Resolves with the value `host.request` resolves with in the Worker, or
+ * rejects, and the Worker's promise rejects with an Error carrying the
+ * thrown error's `name`, `message` and `code`. `signal` aborts when the
+ * Worker cancels the call or stops.
+ */
+export type HostHandler = (request: HostRequest, signal: AbortSignal) => unknown;
 export declare class BrowserTarget implements KernelTarget {
     #private;
     readonly runtime: "browser";
@@ -33,6 +53,8 @@ export declare class BrowserTarget implements KernelTarget {
     readonly transform: typeof transformCellForEval;
     private constructor();
     static launch(events: TargetEvents, options: BrowserTargetOptions): Promise<BrowserTarget>;
+    /** Sends `host.onEvent` listeners in the Worker an event (#384). */
+    notifyHost(event: string, value?: unknown): void;
     evaluate(script: string): Promise<EvaluateResult>;
     /**
      * A cell that's waiting on something leaves the Worker free: it answers a
@@ -53,6 +75,7 @@ export declare class BrowserTarget implements KernelTarget {
             stack: string;
         };
     }>;
+    format(value: RemoteObject): Promise<CdpParams>;
     describeError(exception: RemoteObject): Promise<{
         name: string;
         message: string;

package/dist/browser/target.js

@@ -5,7 +5,7 @@
 // follows. Cells are transformed as for Bun and workerd
 // (transformCellForEval).
 import { asEvaluateResult, isRecord } from "../cdp.js";
-import { Interrupted, isTargetMessage } from "../target-api.js";
+import { Interrupted, isTargetMessage, parseBundle } from "../target-api.js";
 import { transformCellForEval } from "../transform.js";
 /** See BunTarget: how long an interrupted cell has to show it isn't busy. */
 export const INTERRUPT_GRACE_MS = 500;
@@ -23,13 +23,17 @@ export class BrowserTarget {
     #pending = new Map();
     /** Requests that interrupt() abandons when the driver can still answer. */
     #interruptible = new Set();
+    /** Host requests in flight, by the Worker's id (#384). */
+    #hostCalls = new Map();
+    #host;
     #nextId = 0;
     #interrupted = false;
     #stopNote;
     #exited = false;
-    constructor(worker, events) {
+    constructor(worker, events, host) {
         this.#worker = worker;
         this.#events = events;
+        this.#host = host;
         worker.addEventListener("message", (event) => this.#receive(event.data));
         // A driver that failed to load: what's pending can't be answered.
         worker.addEventListener("error", (event) => {
@@ -38,10 +42,10 @@ export class BrowserTarget {
         });
     }
     static async launch(events, options) {
-        const target = new BrowserTarget(options.createWorker(), events);
+        const target = new BrowserTarget(options.createWorker(), events, options.host);
         const base = options.base ?? globalThis.location?.href ?? "file:///";
         try {
-            const { userAgent } = await target.#request("info", { base, cdn: options.cdn });
+            const { userAgent } = await target.#request("info", { base, cdn: options.cdn, preload: options.preload ?? [] });
             if (typeof userAgent === "string")
                 target.versions.runtime = browserName(userAgent);
             target.versions.engine = engineName(typeof userAgent === "string" ? userAgent : "");
@@ -56,6 +60,9 @@ export class BrowserTarget {
         if (isRecord(msg) && msg.kind === "stream") {
             this.#events.stream(msg.name === "stderr" ? "stderr" : "stdout", String(msg.text));
         }
+        else if (isRecord(msg) && msg.kind === "host") {
+            this.#hostRequest(msg);
+        }
         else if (isTargetMessage(msg)) {
             this.#events.message(msg);
         }
@@ -72,11 +79,47 @@ export class BrowserTarget {
                 pending.resolve(msg);
         }
     }
+    #hostRequest(msg) {
+        const id = Number(msg.id);
+        if (msg.cancel === true) {
+            this.#hostCalls.get(id)?.abort();
+            this.#hostCalls.delete(id);
+            return;
+        }
+        const controller = new AbortController();
+        this.#hostCalls.set(id, controller);
+        const answer = (reply) => {
+            if (this.#hostCalls.get(id) !== controller)
+                return; // cancelled, or the Worker stopped
+            this.#hostCalls.delete(id);
+            try {
+                this.#worker.postMessage({ op: "host", id, ...reply });
+            }
+            catch (err) {
+                // A result structured clone can't copy, such as a function.
+                this.#worker.postMessage({ op: "host", id, error: describeHostError(err) });
+            }
+        };
+        const host = this.#host;
+        new Promise((resolve) => {
+            if (!host)
+                throw new Error("this page offers no host requests");
+            resolve(host({ method: String(msg.method), params: msg.params }, controller.signal));
+        }).then((result) => answer({ result }), (err) => answer({ error: describeHostError(err) }));
+    }
+    /** Sends `host.onEvent` listeners in the Worker an event (#384). */
+    notifyHost(event, value) {
+        if (!this.#exited)
+            this.#worker.postMessage({ op: "host", event, value });
+    }
     #exit(code) {
         if (this.#exited)
             return;
         this.#exited = true;
         this.#worker.terminate();
+        for (const controller of this.#hostCalls.values())
+            controller.abort();
+        this.#hostCalls.clear();
         // Reported before the requests it cut off fail, so the note lands in
         // the interrupted cell's output.
         this.#events.exit(code, this.#stopNote);
@@ -150,6 +193,10 @@ export class BrowserTarget {
         }
         return { handled: reply.handled === true };
     }
+    async format(value) {
+        const reply = await this.#request("format", { handle: value.objectId });
+        return parseBundle(reply.value);
+    }
     async describeError(exception) {
         if (exception.objectId === undefined)
             return { name: "Error", message: exception.description ?? "", stack: "" };
@@ -175,6 +222,17 @@ export class BrowserTarget {
         this.#exit(null);
     }
 }
+function describeHostError(err) {
+    if (isRecord(err)) {
+        const { name, message, code } = err;
+        return {
+            name: typeof name === "string" ? name : "Error",
+            message: typeof message === "string" ? message : String(err),
+            ...(code === undefined ? {} : { code: code }),
+        };
+    }
+    return { name: "Error", message: String(err) };
+}
 function toBase64(bytes) {
     let binary = "";
     for (let i = 0; i < bytes.length; i += 0x8000)

package/dist/browser/worker.js

@@ -524,13 +524,13 @@ function hasDisplaySymbol(obj) {
 function isMediaBundle(obj) {
   return obj !== null && typeof obj === "object" && !Array.isArray(obj);
 }
-function createJupyter(host) {
+function createJupyter(host2) {
   async function format2(obj) {
     return await formatNow(obj);
   }
   function formatNow(obj) {
     if (hasDisplaySymbol(obj)) return obj[$display]();
-    if (typeof obj !== "object" || obj === null) return { "text/plain": host.inspect(obj) };
+    if (typeof obj !== "object" || obj === null) return { "text/plain": host2.inspect(obj) };
     if (isCanvasLike(obj)) {
       const [prefix, data] = obj.toDataURL().split(",");
       return { [prefix.split(":")[1].split(";")[0]]: data };
@@ -540,11 +540,11 @@ function createJupyter(host) {
       if (vega) return vega;
     }
     if (isDataFrameLike(obj)) return extractDataFrame(obj);
-    if (isJpg(obj)) return { "image/jpeg": host.base64(obj) };
-    if (isPng(obj)) return { "image/png": host.base64(obj) };
+    if (isJpg(obj)) return { "image/jpeg": host2.base64(obj) };
+    if (isPng(obj)) return { "image/png": host2.base64(obj) };
     if (isSVGElementLike(obj)) return { "image/svg+xml": obj.outerHTML };
     if (isHTMLElementLike(obj)) return { "text/html": obj.outerHTML };
-    return { "text/plain": host.inspect(obj) };
+    return { "text/plain": host2.inspect(obj) };
   }
   function taggedTemplate(mediatype) {
     return (strings, ...values) => {
@@ -555,18 +555,18 @@ function createJupyter(host) {
   function image(obj) {
     if (typeof obj === "string") {
       try {
-        obj = host.readFile(obj);
+        obj = host2.readFile(obj);
       } catch {
       }
     }
-    if (isJpg(obj)) return { [$display]: () => ({ "image/jpeg": host.base64(obj) }) };
-    if (isPng(obj)) return { [$display]: () => ({ "image/png": host.base64(obj) }) };
+    if (isJpg(obj)) return { [$display]: () => ({ "image/jpeg": host2.base64(obj) }) };
+    if (isPng(obj)) return { [$display]: () => ({ "image/png": host2.base64(obj) }) };
     throw new TypeError(
       "Object is not a valid image or a path to an image. `jupyter.image` supports displaying JPG or PNG images."
     );
   }
   function broadcast(msgType, content, { metadata = {}, buffers = [] } = {}) {
-    host.send(msgType, content, metadata, buffers);
+    host2.send(msgType, content, metadata, buffers);
   }
   async function display(obj, options = { raw: false, update: false }) {
     const bundle = options.raw && isMediaBundle(obj) ? obj : await format2(obj);
@@ -595,15 +595,15 @@ function createJupyter(host) {
     }
   }
   function confirm(message = "Confirm") {
-    const answer2 = host.input(`${message} [y/N] `, false);
+    const answer2 = host2.input(`${message} [y/N] `, false);
     return answer2 === "Y" || answer2 === "y";
   }
   function prompt(message = "Prompt", defaultValue = "", { password = false } = {}) {
     if (defaultValue != "") message += ` [${defaultValue}]`;
-    const answer2 = host.input(message, password);
+    const answer2 = host2.input(message, password);
     return answer2 === "" ? defaultValue : answer2;
   }
-  const comms = createComms((msgType, content, metadata, buffers) => host.send(msgType, content, metadata, buffers));
+  const comms = createComms((msgType, content, metadata, buffers) => host2.send(msgType, content, metadata, buffers));
   return {
     namespace: {
       broadcast,
@@ -665,6 +665,8 @@ function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
       case "broadcast":
         await shim.broadcastResult(request.count, take(request.handle));
         return {};
+      case "format":
+        return { value: await shim.formatJson(request.handle === void 0 ? void 0 : take(request.handle)) };
       case "describe":
         return { value: shim.describeError(take(request.handle)) };
       case "comm":
@@ -952,6 +954,71 @@ var jupyter = createJupyter({
   input: () => null
 });
 var cdn = DEFAULT_CDN;
+var hostCalls = /* @__PURE__ */ new Map();
+var hostListeners = /* @__PURE__ */ new Set();
+var nextHostId = 0;
+function hostError(error) {
+  const err = new Error(String(error?.message ?? "the host request failed"));
+  if (typeof error?.name === "string") err.name = error.name;
+  if (error?.code !== void 0) err.code = error.code;
+  return err;
+}
+var host = {
+  /** Resolves with the page's answer; aborting `signal` cancels the call on the page too. */
+  request(method, params, { signal, transfer } = {}) {
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    const id = ++nextHostId;
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        hostCalls.delete(id);
+        post({ kind: "host", id, cancel: true });
+        reject(signal.reason);
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      const done = () => signal?.removeEventListener("abort", onAbort);
+      try {
+        globalThis.postMessage({ kind: "host", id, method, params }, transfer ?? []);
+      } catch (err) {
+        done();
+        throw err;
+      }
+      hostCalls.set(id, { resolve, reject, done });
+    });
+  },
+  /** Calls `listener(event, value)` for each event the page sends; returns a function that stops it. */
+  onEvent(listener) {
+    hostListeners.add(listener);
+    return () => hostListeners.delete(listener);
+  }
+};
+function receiveHost(msg) {
+  if (msg.id === void 0) {
+    for (const listener of hostListeners) {
+      try {
+        listener(msg.event, msg.value);
+      } catch (err) {
+        reportUncaught("Uncaught", err);
+      }
+    }
+    return;
+  }
+  const call = hostCalls.get(msg.id);
+  if (!call) return;
+  hostCalls.delete(msg.id);
+  call.done();
+  if (msg.error !== void 0) call.reject(hostError(msg.error));
+  else call.resolve(msg.result);
+}
+async function preload(urls, base) {
+  for (const specifier of Array.isArray(urls) ? urls : []) {
+    try {
+      const mod = await import(new URL(specifier, base).href);
+      if (typeof mod.default === "function") await mod.default({ host, jupyter: jupyter.namespace });
+    } catch (err) {
+      reportUncaught(`Preloading ${specifier} failed`, err);
+    }
+  }
+}
 var handle = null;
 function install({ base, cdn: cdnBase }) {
   if (typeof cdnBase === "string") cdn = cdnBase.endsWith("/") ? cdnBase : cdnBase + "/";
@@ -965,6 +1032,8 @@ function install({ base, cdn: cdnBase }) {
     resolvePath,
     barrier: () => 0,
     broadcastResult: jupyter.broadcastResult,
+    // execute_request's user_expressions (#340).
+    formatJson: async (value) => JSON.stringify(await jupyter.namespace.format(value)),
     async commDispatch(msgType, content, metadata, buffers64) {
       const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
       return await jupyter.commDispatch(msgType, content, metadata, buffers);
@@ -985,6 +1054,7 @@ function install({ base, cdn: cdnBase }) {
 async function answer(req) {
   if (req.op === "info") {
     install(req);
+    await preload(req.preload, req.base);
     return { userAgent: globalThis.navigator?.userAgent ?? "" };
   }
   if (handle === null) throw new Error("the driver wasn't sent info first");
@@ -992,6 +1062,7 @@ async function answer(req) {
 }
 globalThis.addEventListener("message", (event) => {
   const req = event.data;
+  if (req?.op === "host") return receiveHost(req);
   answer(req).then(
     (reply) => post({ kind: "reply", id: req.id, ...reply }),
     (err) => post({ kind: "reply", id: req.id, failure: String(err?.stack ?? err) })