@tlockney/cdp-kernel 0.7.0 → 0.7.2

package/README.md

@@ -5,7 +5,9 @@ into Deno 2.9.6 (`deno jupyter`), that runs notebooks on several JavaScript runt
 host runs on Node or Deno; the code you type runs in a separate **target**
 runtime: Node or Deno over the Chrome DevTools Protocol, or Bun, workerd and
 celld, which evaluate cells in-process. In principle, anything else whose
-inspector speaks CDP works too.
+inspector speaks CDP works too. The kernel can also run inside a web page,
+with cells in a Web Worker and no server
+([The browser](https://cdp-kernel.org/docs/integration-browser), experimental).
 
 **Website:** <https://cdp-kernel.org/> ·
 **Docs:** [cdp-kernel.org/docs](https://cdp-kernel.org/docs/)
@@ -33,7 +35,7 @@ runtime versions and frontends are supported, and what may change before
 - Deno projects (`deno.json` import maps, JSX settings) and Workers
   projects (`wrangler` bindings in `env`).
 - JupyterLab's visual debugger on Node and Deno targets.
-- anywidget-style widgets and Jupyter comms.
+- [anywidget](https://github.com/manzt/anywidget)-style widgets and Jupyter comms.
 - `prompt()` and `confirm()`, interrupt that keeps state, Shift-Tab
   inspection, completion and history.
 

package/dist/browser/kernel.js

@@ -28401,6 +28401,17 @@ function makeHeader(session, msgType) {
 }
 
 // src/target-api.ts
+function parseBundle(text) {
+  const bundle = typeof text === "string" ? parseJson(text) : void 0;
+  return typeof bundle === "object" && bundle !== null && !Array.isArray(bundle) ? bundle : {};
+}
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
 function isTargetMessage(value) {
   if (typeof value !== "object" || value === null) return false;
   const kind = value.kind;
@@ -28746,6 +28757,7 @@ function clip(frames) {
 }
 
 // src/kernel-core.ts
+var TYPESCRIPT_VERSION = "6";
 function fromBase64(text) {
   return Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
 }
@@ -28814,6 +28826,8 @@ var KernelCore = class {
   #input = null;
   /** An interrupt is waiting on the target. */
   #interrupting = false;
+  /** Ends the cell waiting for the target to start, while one is (#336). */
+  #interruptStart = null;
   /** The shell message being handled, and since when. */
   #handling = null;
   // Open comms, for comm_info_request: comm_id -> target_name (#9).
@@ -28932,6 +28946,21 @@ var KernelCore = class {
     });
     return this.#targetStarting;
   }
+  /**
+   * The target for a cell. An interrupt while it starts ends the cell; the
+   * start goes on, bounded by the target's own deadline, for the next one (#336).
+   */
+  async #targetForCell() {
+    if (this.#target) return this.#target;
+    const interrupted = new Promise((_, reject) => {
+      this.#interruptStart = () => reject(new Interrupted("Execution interrupted"));
+    });
+    try {
+      return await Promise.race([this.#ensureTarget(), interrupted]);
+    } finally {
+      this.#interruptStart = null;
+    }
+  }
   #targetEvents() {
     return {
       stream: (name, text) => this.#publish("stream", { name, text }),
@@ -28974,6 +29003,10 @@ ${text}
       input2.settle({ value: null, interrupted: true });
       return;
     }
+    if (this.#interruptStart !== null) {
+      this.#interruptStart();
+      return;
+    }
     if (!this.#target || !this.#executing) return;
     this.#interrupting = true;
     try {
@@ -29029,7 +29062,7 @@ ${text}
       implementation_version: this.#host.version,
       language_info: {
         name: "typescript",
-        version: "5",
+        version: this.#host.languageVersion ?? TYPESCRIPT_VERSION,
         mimetype: "text/x.typescript",
         file_extension: ".ts",
         pygments_lexer: "typescript",
@@ -29042,7 +29075,8 @@ ${text}
       debugger: this.#debugger !== null,
       // What current ipykernel advertises; JupyterLab itself goes by the
       // kernelspec's metadata.debugger.
-      supported_features: this.#debugger !== null ? ["debugger"] : []
+      supported_features: this.#debugger !== null ? ["debugger"] : [],
+      ...this.#host.capabilities ? { capabilities: this.#host.capabilities } : {}
     };
   }
   // --- control channel ------------------------------------------------------
@@ -29281,6 +29315,39 @@ ${withoutSignature(runtime)}`;
     }
     return target.evaluate(transform2(code));
   }
+  /** execute_request's user_expressions, each as its value's MIME bundle or the error it threw (#340). */
+  async #userExpressions(target, expressions) {
+    const results = {};
+    if (typeof expressions !== "object" || expressions === null) return results;
+    for (const [name, expression] of Object.entries(expressions)) {
+      results[name] = await this.#userExpression(target, String(expression));
+    }
+    return results;
+  }
+  async #userExpression(target, expression) {
+    try {
+      const source = `(
+${expression}
+)`;
+      const result = await target.evaluate(`${target.transform(source, this.#transformOptions())}
+//# sourceURL=$cdpk$user-expression.ts`);
+      if (result.exceptionDetails) {
+        const exception = result.exceptionDetails.exception;
+        const described = exception ? await target.describeError(exception) : { name: "Error", message: result.exceptionDetails.text, stack: "" };
+        return {
+          status: "error",
+          ename: described.name || "Error",
+          evalue: described.message,
+          traceback: (described.stack || `${described.name}: ${described.message}`).split("\n")
+        };
+      }
+      return { status: "ok", data: await target.format(result.result), metadata: {} };
+    } catch (err) {
+      const ename = err instanceof CellSyntaxError ? "SyntaxError" : err instanceof Interrupted ? "Interrupted" : "Error";
+      const evalue = err instanceof Error ? err.message : String(err);
+      return { status: "error", ename, evalue, traceback: [`${ename}: ${evalue}`] };
+    }
+  }
   async #execute(msg, peer) {
     const parent = msg.header;
     if (this.#aborting) {
@@ -29306,10 +29373,11 @@ ${withoutSignature(runtime)}`;
       this.#projectWarning = null;
     }
     let error = null;
+    let userExpressions = {};
     let structured = null;
     this.#executing = true;
     try {
-      const target = await this.#ensureTarget();
+      const target = await this.#targetForCell();
       if (target.notice !== void 0 && this.#noticeShownFor !== target) {
         this.#noticeShownFor = target;
         this.#publish("stream", { name: "stderr", text: `${target.notice}
@@ -29334,6 +29402,7 @@ ${withoutSignature(runtime)}`;
       } else if (!silent && result.result.type !== "undefined") {
         await target.broadcastResult(count, result.result);
       }
+      if (!result.exceptionDetails) userExpressions = await this.#userExpressions(target, msg.content.user_expressions);
       await target.flush();
     } catch (err) {
       if (err instanceof CellSyntaxError) {
@@ -29362,7 +29431,7 @@ ${withoutSignature(runtime)}`;
         status: "ok",
         execution_count: count,
         payload: [],
-        user_expressions: {}
+        user_expressions: userExpressions
       });
     }
     this.#status("idle", parent);
@@ -29370,7 +29439,7 @@ ${withoutSignature(runtime)}`;
 };
 
 // stub:package
-var VERSION = "0.7.0";
+var VERSION = "0.7.2";
 
 // src/browser/channels.ts
 var PEER = "page";
@@ -29485,13 +29554,17 @@ var BrowserTarget = class _BrowserTarget {
   #pending = /* @__PURE__ */ new Map();
   /** Requests that interrupt() abandons when the driver can still answer. */
   #interruptible = /* @__PURE__ */ new Set();
+  /** Host requests in flight, by the Worker's id (#384). */
+  #hostCalls = /* @__PURE__ */ 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));
     worker.addEventListener("error", (event) => {
       this.#events.stream("stderr", `[cdp-kernel] browser Worker error: ${event.message ?? "unknown"}
@@ -29500,10 +29573,10 @@ var BrowserTarget = class _BrowserTarget {
     });
   }
   static async launch(events, options) {
-    const target = new _BrowserTarget(options.createWorker(), events);
+    const target = new _BrowserTarget(options.createWorker(), events, options.host);
     const base2 = options.base ?? globalThis.location?.href ?? "file:///";
     try {
-      const { userAgent } = await target.#request("info", { base: base2, cdn: options.cdn });
+      const { userAgent } = await target.#request("info", { base: base2, cdn: options.cdn, preload: options.preload ?? [] });
       if (typeof userAgent === "string") target.versions.runtime = browserName(userAgent);
       target.versions.engine = engineName(typeof userAgent === "string" ? userAgent : "");
     } catch (err) {
@@ -29515,6 +29588,8 @@ var BrowserTarget = class _BrowserTarget {
   #receive(msg) {
     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);
     } else if (isRecord(msg) && msg.kind === "reply") {
@@ -29527,10 +29602,52 @@ var BrowserTarget = class _BrowserTarget {
       else 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;
+      this.#hostCalls.delete(id);
+      try {
+        this.#worker.postMessage({ op: "host", id, ...reply });
+      } catch (err) {
+        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) })
+    );
+  }
+  /** Aborts each host request in flight and rejects it in the Worker. */
+  #cancelHostCalls() {
+    const calls = [...this.#hostCalls];
+    this.#hostCalls.clear();
+    for (const [id, controller] of calls) {
+      controller.abort();
+      this.#worker.postMessage({ op: "host", id, error: { name: "AbortError", message: "interrupted" } });
+    }
+  }
+  /** 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();
     this.#events.exit(code, this.#stopNote);
     for (const pending of this.#pending.values()) pending.reject(new Abandoned("the browser Worker stopped"));
     this.#pending.clear();
@@ -29558,9 +29675,10 @@ var BrowserTarget = class _BrowserTarget {
   }
   /**
    * A cell that's waiting on something leaves the Worker free: it answers a
-   * ping, and the cell is abandoned with its state intact. A busy cell
-   * can't be reached, so the Worker is terminated, and a new one starts on
-   * the next cell.
+   * ping, and the cell is abandoned with its state intact; host requests
+   * in flight are cancelled on the page, and reject in the Worker with an
+   * AbortError (#388). A busy cell can't be reached, so the Worker is
+   * terminated, and a new one starts on the next cell.
    */
   async interrupt() {
     this.#interrupted = true;
@@ -29575,6 +29693,7 @@ var BrowserTarget = class _BrowserTarget {
         this.#pending.delete(id);
         this.#interruptible.delete(id);
       }
+      this.#cancelHostCalls();
       return;
     }
     this.#stopNote = RESTART_NOTE;
@@ -29596,6 +29715,10 @@ var BrowserTarget = 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 === void 0) return { name: "Error", message: exception.description ?? "", stack: "" };
     const { value } = await this.#request("describe", { handle: exception.objectId });
@@ -29621,6 +29744,17 @@ var BrowserTarget = 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 === void 0 ? {} : { code }
+    };
+  }
+  return { name: "Error", message: String(err) };
+}
 function toBase64(bytes2) {
   let binary = "";
   for (let i = 0; i < bytes2.length; i += 32768) binary += String.fromCharCode(...bytes2.subarray(i, i + 32768));
@@ -29651,12 +29785,14 @@ 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()
   });
@@ -29664,7 +29800,8 @@ function startBrowserKernel(options) {
   return {
     send: (channel, msg) => channels.deliver(channel, msg),
     onMessage: (listener) => channels.onMessage(listener),
-    closed: closedPromise
+    closed: closedPromise,
+    notifyHost: (event, value) => target?.notifyHost(event, value)
   };
 }
 export {