@tlockney/cdp-kernel 0.1.1 → 0.3.0

package/dist/ws-client.d.ts

@@ -0,0 +1,32 @@
+import { Buffer } from "node:buffer";
+export declare const OP_CONTINUATION = 0;
+export declare const OP_TEXT = 1;
+export declare const OP_CLOSE = 8;
+export declare const OP_PING = 9;
+export declare const OP_PONG = 10;
+export interface Frame {
+    fin: boolean;
+    opcode: number;
+    payload: Buffer;
+}
+/** One frame; clients must mask what they send. */
+export declare function encodeFrame(opcode: number, payload: Buffer, mask?: Buffer | null): Buffer;
+/** Splits a byte stream into frames, holding back a partial one. */
+export declare class FrameDecoder {
+    #private;
+    push(chunk: Buffer): Frame[];
+}
+export declare function acceptKey(key: string): string;
+export interface WsChannel {
+    send(text: string): void;
+    onMessage(listener: (text: string) => void): void;
+    onClose(listener: () => void): void;
+    close(): void;
+}
+/** Opens a WebSocket over the Unix socket at `socketPath`. */
+export declare function connectUnixWebSocket(socketPath: string, { path, headers }?: {
+    path?: string;
+    headers?: {
+        [name: string]: string;
+    };
+}): Promise<WsChannel>;

package/dist/ws-client.js

@@ -0,0 +1,166 @@
+// A minimal WebSocket client (RFC 6455) over a Unix socket, for the workerd
+// target's session with its driver Worker (#26). The WebSocket that Node
+// and Deno provide can't connect to a Unix socket, and a TCP listener would
+// be reachable by every local process. Text messages only: that's all the
+// session carries.
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes } from "node:crypto";
+import { connect } from "node:net";
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+export const OP_CONTINUATION = 0x0;
+export const OP_TEXT = 0x1;
+export const OP_CLOSE = 0x8;
+export const OP_PING = 0x9;
+export const OP_PONG = 0xa;
+/** One frame; clients must mask what they send. */
+export function encodeFrame(opcode, payload, mask = randomBytes(4)) {
+    const len = payload.length;
+    const head = len < 126 ? 2 : len < 0x10000 ? 4 : 10;
+    const out = Buffer.alloc(head + (mask ? 4 : 0) + len);
+    out[0] = 0x80 | opcode;
+    const maskBit = mask ? 0x80 : 0;
+    if (len < 126) {
+        out[1] = maskBit | len;
+    }
+    else if (len < 0x10000) {
+        out[1] = maskBit | 126;
+        out.writeUInt16BE(len, 2);
+    }
+    else {
+        out[1] = maskBit | 127;
+        out.writeBigUInt64BE(BigInt(len), 2);
+    }
+    if (mask) {
+        mask.copy(out, head);
+        for (let i = 0; i < len; i++)
+            out[head + 4 + i] = payload[i] ^ mask[i & 3];
+    }
+    else {
+        payload.copy(out, head);
+    }
+    return out;
+}
+/** Splits a byte stream into frames, holding back a partial one. */
+export class FrameDecoder {
+    #buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        const frames = [];
+        for (;;) {
+            const b = this.#buffer;
+            if (b.length < 2)
+                break;
+            const masked = (b[1] & 0x80) !== 0;
+            let len = b[1] & 0x7f;
+            let offset = 2;
+            if (len === 126) {
+                if (b.length < 4)
+                    break;
+                len = b.readUInt16BE(2);
+                offset = 4;
+            }
+            else if (len === 127) {
+                if (b.length < 10)
+                    break;
+                len = Number(b.readBigUInt64BE(2));
+                offset = 10;
+            }
+            const maskAt = offset;
+            if (masked)
+                offset += 4;
+            if (b.length < offset + len)
+                break;
+            const payload = Buffer.from(b.subarray(offset, offset + len));
+            if (masked)
+                for (let i = 0; i < len; i++)
+                    payload[i] ^= b[maskAt + (i & 3)];
+            frames.push({ fin: (b[0] & 0x80) !== 0, opcode: b[0] & 0x0f, payload });
+            this.#buffer = b.subarray(offset + len);
+        }
+        return frames;
+    }
+}
+export function acceptKey(key) {
+    return createHash("sha1").update(key + GUID).digest("base64");
+}
+/** Opens a WebSocket over the Unix socket at `socketPath`. */
+export function connectUnixWebSocket(socketPath, { path = "/", headers = {} } = {}) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({ path: socketPath });
+        const key = randomBytes(16).toString("base64");
+        const messageListeners = [];
+        const closeListeners = [];
+        let open = false;
+        let closed = false;
+        let head = Buffer.alloc(0);
+        const decoder = new FrameDecoder();
+        let parts = [];
+        const finish = () => {
+            if (closed)
+                return;
+            closed = true;
+            if (!open)
+                reject(new Error("the WebSocket closed before it opened"));
+            for (const listener of closeListeners)
+                listener();
+        };
+        const write = (opcode, payload) => {
+            if (!closed)
+                socket.write(encodeFrame(opcode, payload));
+        };
+        const channel = {
+            send: (text) => write(OP_TEXT, Buffer.from(text)),
+            onMessage: (listener) => void messageListeners.push(listener),
+            onClose: (listener) => void closeListeners.push(listener),
+            close() {
+                write(OP_CLOSE, Buffer.alloc(0));
+                socket.end();
+            },
+        };
+        const onFrames = (frames) => {
+            for (const frame of frames) {
+                if (frame.opcode === OP_TEXT || frame.opcode === OP_CONTINUATION) {
+                    parts.push(frame.payload);
+                    if (frame.fin) {
+                        const text = Buffer.concat(parts).toString("utf8");
+                        parts = [];
+                        for (const listener of messageListeners)
+                            listener(text);
+                    }
+                }
+                else if (frame.opcode === OP_PING) {
+                    write(OP_PONG, frame.payload);
+                }
+                else if (frame.opcode === OP_CLOSE) {
+                    socket.end();
+                }
+            }
+        };
+        socket.on("data", (chunk) => {
+            if (open)
+                return onFrames(decoder.push(chunk));
+            head = Buffer.concat([head, chunk]);
+            const end = head.indexOf("\r\n\r\n");
+            if (end === -1)
+                return;
+            const response = head.subarray(0, end).toString("latin1");
+            const accept = /^sec-websocket-accept:\s*(\S+)/im.exec(response)?.[1];
+            if (!/^HTTP\/1\.1 101 /.test(response) || accept !== acceptKey(key)) {
+                socket.destroy();
+                reject(new Error(`the WebSocket handshake failed: ${response.split("\r\n")[0]}`));
+                return;
+            }
+            open = true;
+            resolve(channel);
+            onFrames(decoder.push(head.subarray(end + 4)));
+        });
+        socket.on("error", (err) => {
+            if (!open)
+                reject(err);
+        });
+        socket.on("close", finish);
+        const extra = Object.entries(headers).map(([name, value]) => `${name}: ${value}\r\n`).join("");
+        socket.write(`GET ${path} HTTP/1.1\r\nHost: cdpk\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n` +
+            `Sec-WebSocket-Key: ${key}\r\nSec-WebSocket-Version: 13\r\n${extra}\r\n`);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on any V8 runtime over the Chrome DevTools Protocol",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
@@ -8,7 +8,16 @@
     "type": "git",
     "url": "git+https://github.com/tlockney/cdp-kernel.git"
   },
-  "keywords": ["jupyter", "kernel", "typescript", "notebook", "deno", "node", "cdp", "devtools-protocol"],
+  "keywords": [
+    "jupyter",
+    "kernel",
+    "typescript",
+    "notebook",
+    "deno",
+    "node",
+    "cdp",
+    "devtools-protocol"
+  ],
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -20,6 +29,14 @@
     ".": {
       "types": "./dist/mod.d.ts",
       "default": "./dist/mod.js"
+    },
+    "./globals": {
+      "types": "./dist/globals.d.ts",
+      "default": "./dist/globals.js"
+    },
+    "./globals/deno-compat": {
+      "types": "./dist/globals-deno-compat.d.ts",
+      "default": "./dist/globals-deno-compat.js"
     }
   },
   "files": [
@@ -36,9 +53,13 @@
     "install:node": "node src/main.ts install --runtime node",
     "install:deno": "node src/main.ts install --runtime deno",
     "install:node-deno": "node src/main.ts install --runtime node --deno-compat",
+    "install:bun": "node src/main.ts install --runtime bun",
+    "install:workerd": "node src/main.ts install --runtime workerd",
+    "install:celld": "node src/main.ts install --runtime celld",
     "prepack": "npm run build",
     "test": "node --test test/*.test.ts",
-    "e2e": "uv run --with nbclient --with nbformat --with jupyter_client python test/e2e.py"
+    "e2e": "uv run --with nbclient --with nbformat --with jupyter_client python test/e2e.py",
+    "test:lab": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/lab_widgets.py"
   },
   "dependencies": {
     "acorn": "^8.15.0",
@@ -47,6 +68,8 @@
   },
   "devDependencies": {
     "@types/node": "^24.19.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "workerd": "1.20261015.1",
+    "wrangler": "4.151.0"
   }
 }

package/runtime/bootstrap.mjs

@@ -4,17 +4,25 @@
 // then drives it over CDP. Everything the host needs from inside the
 // runtime lives on globalThis.__cdpk; output to the host goes through the
 // `__cdpk_send` CDP binding (Runtime.addBinding) plus plain stdout/stderr.
+// Bun is launched as `bun runtime/bootstrap.mjs` and driven over a pipe
+// instead; see bun-channel.mjs.
 //
-// Plain JavaScript on purpose: the same file must load unmodified in Node
-// and in Deno.
+// Plain JavaScript on purpose: the same file must load unmodified in Node,
+// Deno and Bun.
 
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJupyter } from "./display.mjs";
 
 const isDeno = typeof globalThis.Deno?.version?.deno === "string";
+const isBun = typeof globalThis.Bun?.version === "string";
 const ENC = new TextEncoder();
 
 const cwd = isDeno ? Deno.cwd() : process.cwd();
-const cwdUrl = new URL(`file://${cwd.endsWith("/") ? cwd : cwd + "/"}`);
+// pathToFileURL, not string concatenation: a directory name containing
+// "#", "?" or "%" would otherwise cut the path short or turn into a query,
+// breaking relative imports and import.meta (#22). It also handles Windows
+// drive letters.
+const cwdUrl = pathToFileURL(cwd.endsWith("/") ? cwd : cwd + "/");
 // Stand-in referrer for cell code, like Deno's ./$deno$jupyter_repl.mts.
 const replUrl = new URL("$cdpk$repl.mjs", cwdUrl);
 
@@ -72,27 +80,82 @@ function resolveRelative(specifier) {
   return /^\.{0,2}\//.test(specifier) ? new URL(specifier, replUrl).href : specifier;
 }
 
-if (!isDeno) {
+if (!isDeno && !isBun) {
   // Deno resolves npm:/jsr: natively; Node gets a resolve hook that adds
   // them and re-parents cell imports to the notebook's directory.
   const { installNodeResolveHooks } = await import("./node-hooks.mjs");
   installNodeResolveHooks({ shimUrl: import.meta.url, replUrl: replUrl.href });
 }
 
+// In a Deno project (#13), Deno's own resolution (import map, npm:, jsr:)
+// goes first, as in `deno jupyter`. A bare package it can't place, because
+// package.json dependencies resolve relative to *this* module rather than
+// the notebook, is retried from the project's node_modules.
+const inDenoProject = isDeno && Deno.env.get("CDPK_DENO_PROJECT") === "1";
+const { resolveFromNodeModules } = inDenoProject ? await import("./node-modules-resolve.mjs") : {};
+
+function isResolutionError(err, specifier) {
+  return err instanceof TypeError && err.message.includes(`"${specifier}"`);
+}
+
+async function denoImport(specifier, options) {
+  const resolved = resolveRelative(specifier);
+  try {
+    return await import(resolved, options);
+  } catch (err) {
+    const fromNodeModules = resolveFromNodeModules && isResolutionError(err, specifier)
+      ? resolveFromNodeModules(specifier, cwd)
+      : null;
+    if (fromNodeModules === null) throw err;
+    return await import(fromNodeModules, options);
+  }
+}
+
+// Bun has neither npm: nor jsr:, and would resolve a bare name from this
+// file's directory. npm:/jsr: install into a per-user cache as on Node
+// (with `bun add`); anything else bare resolves from the notebook's
+// directory, so its node_modules, or Bun's auto-install, supplies it.
+const packages = isBun ? await import("./node-hooks.mjs") : null;
+
+function bunResolve(specifier) {
+  let pkg = null;
+  if (specifier.startsWith("npm:")) pkg = packages.parsePackageSpecifier(specifier.slice(4));
+  else if (specifier.startsWith("jsr:")) pkg = packages.jsrToNpm(specifier.slice(4));
+  if (pkg) {
+    const { dir, alias } = packages.ensureInstalled(pkg, "bun");
+    return Bun.resolveSync(alias + pkg.subpath, dir);
+  }
+  // Relative, absolute, or a URL scheme such as node:, bun: or file:.
+  if (/^(?:\.{0,2}\/|[a-z][a-z0-9+.-]*:)/i.test(specifier)) return resolveRelative(specifier);
+  return Bun.resolveSync(specifier, cwd);
+}
+
 globalThis.__cdpk = {
   // Cell code awaits this first; see PRELUDE in src/transform.ts.
   tick: () => new Promise((resolve) => setTimeout(resolve, 0)),
   // Node: the resolve hook re-parents these imports. Deno would resolve
-  // relative paths against this file, so do it here.
-  import: (specifier, options) => import(isDeno ? resolveRelative(specifier) : specifier, options),
+  // relative paths against this file, so denoImport does it here.
+  import: (specifier, options) =>
+    isDeno
+      ? denoImport(specifier, options)
+      : isBun
+      ? import(bunResolve(specifier), options)
+      : import(specifier, options),
   meta: {
     url: replUrl.href,
     dirname: cwd,
-    filename: replUrl.pathname,
+    filename: fileURLToPath(replUrl),
     resolve: (specifier) => new URL(specifier, replUrl).href,
   },
   barrier,
   broadcastResult: jupyter.broadcastResult,
+  // Frontend comm messages (#9), from the host's shell channel. Handlers
+  // run after one macrotask, like cells, so interrupt can reach them.
+  async commDispatch(msgType, content, metadata, buffers64) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
+    return await jupyter.commDispatch(msgType, content, metadata, buffers);
+  },
   describeError(value) {
     if (value instanceof Error) {
       return JSON.stringify({ name: value.name, message: value.message, stack: value.stack ?? "" });
@@ -146,6 +209,14 @@ if (isDeno) {
 // Keep the event loop alive between cells.
 setInterval(() => {}, 1 << 30);
 
+if (isBun) {
+  const { startChannel } = await import("./bun-channel.mjs");
+  const { createHandler } = await import("./evaluator.mjs");
+  startChannel(createHandler(globalThis.__cdpk), {
+    versions: { runtime: Bun.version, engine: `JavaScriptCore (WebKit ${process.versions.webkit.slice(0, 12)})` },
+  });
+}
+
 async function platform() {
   if (isDeno) {
     const stdinBuf = new Uint8Array(1);

package/runtime/bun-channel.d.mts

@@ -0,0 +1,3 @@
+import type { Handler } from "./evaluator.mjs";
+
+export function startChannel(handle: Handler, ready: { [key: string]: unknown }, fd?: number): void;

package/runtime/bun-channel.mjs

@@ -0,0 +1,58 @@
+// The Bun target's side of the host connection (#7), in place of CDP.
+//
+// Bun's --inspect speaks the WebKit Inspector Protocol, which has no
+// replMode, Runtime.addBinding or Runtime.terminateExecution, so the host
+// doesn't drive Bun over an inspector. It sends requests as JSON lines over
+// fd 3, a pipe only the host holds (there is no port to discover), and the
+// cells are evaluated here, in-process, by evaluator.mjs. Replies, and the
+// iopub messages that the CDP binding carries for other targets, go back the
+// same way. stdout and stderr stay ordinary pipes, ordered against those
+// messages by bootstrap.mjs's barrier markers.
+
+import fs from "node:fs";
+
+const CHANNEL_FD = 3;
+
+/** Synchronous, like a CDP binding call, so output order is kept. */
+function writeAll(fd, text) {
+  const bytes = Buffer.from(text);
+  for (let offset = 0; offset < bytes.length;) {
+    try {
+      offset += fs.writeSync(fd, bytes, offset);
+    } catch (err) {
+      // The reader's side of the pipe is full; the fd may be non-blocking.
+      if (err.code !== "EAGAIN") throw err;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
+    }
+  }
+}
+
+/**
+ * Serves `handle` (see evaluator.mjs) over fd 3 and installs
+ * globalThis.__cdpk_send, the function bootstrap.mjs sends iopub messages
+ * through. `ready` is sent first, once the target can take requests.
+ */
+export function startChannel(handle, ready, fd = CHANNEL_FD) {
+  const send = (message) => writeAll(fd, JSON.stringify(message) + "\n");
+  Object.defineProperty(globalThis, "__cdpk_send", {
+    value: (payload) => writeAll(fd, payload + "\n"),
+    enumerable: false,
+  });
+
+  let buffer = "";
+  const input = fs.createReadStream(null, { fd, autoClose: false, encoding: "utf8" });
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    for (let nl = buffer.indexOf("\n"); nl !== -1; nl = buffer.indexOf("\n")) {
+      const request = JSON.parse(buffer.slice(0, nl));
+      buffer = buffer.slice(nl + 1);
+      handle(request).then(
+        (reply) => send({ kind: "reply", id: request.id, ...reply }),
+        (err) => send({ kind: "reply", id: request.id, failure: String(err?.stack ?? err) }),
+      );
+    }
+  });
+  // The host is gone; don't linger as an orphan.
+  input.on("end", () => process.exit(0));
+  send({ kind: "ready", ...ready });
+}

package/runtime/comm.d.mts

@@ -0,0 +1,46 @@
+/** A comm message as a handler receives it. */
+export interface CommMessage {
+  data: { [key: string]: unknown };
+  metadata: { [key: string]: unknown };
+  buffers: Uint8Array[];
+}
+
+export interface CommSendOptions {
+  metadata?: { [key: string]: unknown };
+  buffers?: Uint8Array[];
+}
+
+/** One end of a Jupyter comm channel. */
+export interface Comm {
+  readonly id: string;
+  readonly targetName: string;
+  readonly closed: boolean;
+  send(data?: { [key: string]: unknown }, options?: CommSendOptions): void;
+  close(data?: { [key: string]: unknown }, options?: CommSendOptions): void;
+  onMsg(handler: (msg: CommMessage) => void | Promise<void>): void;
+  onClose(handler: (msg: CommMessage) => void | Promise<void>): void;
+}
+
+/** `jupyter.comm`: open comms, and accept comms the frontend opens. */
+export interface CommApi {
+  open(targetName: string, data?: { [key: string]: unknown }, options?: CommSendOptions): Comm;
+  registerTarget(targetName: string, handler: (comm: Comm, msg: CommMessage) => void | Promise<void>): void;
+  unregisterTarget(targetName: string): void;
+}
+
+export interface Comms {
+  api: CommApi;
+  /** Routes a frontend comm message; resolves to whether a comm or target took it. */
+  dispatch(
+    msgType: string,
+    content: { [key: string]: unknown },
+    metadata: { [key: string]: unknown },
+    buffers: Uint8Array[],
+  ): Promise<boolean>;
+  list(): { commId: string; targetName: string }[];
+}
+
+export function createComms(
+  send: (msgType: string, content: object, metadata: object, buffers: Uint8Array[]) => void,
+  newId?: () => string,
+): Comms;

package/runtime/comm.mjs

@@ -0,0 +1,108 @@
+// @ts-self-types="./comm.d.mts"
+// Jupyter comms: bidirectional channels between kernel and frontend, the
+// transport ipywidgets and anywidget are built on (#9). Runs inside the
+// target runtime.
+//
+// Kernel-to-frontend messages (comm_open, comm_msg, comm_close) go out
+// through `send`, the same ordered path as display messages. Frontend
+// messages arrive from the host through `dispatch`, which returns whether
+// anything in the kernel handled them, so the host can answer an unknown
+// target's comm_open with a comm_close, as the protocol asks.
+
+class Comm {
+  #send;
+  #onClosed;
+  #msgHandlers = [];
+  #closeHandlers = [];
+  closed = false;
+
+  constructor(id, targetName, send, onClosed) {
+    this.id = id;
+    this.targetName = targetName;
+    this.#send = send;
+    this.#onClosed = onClosed;
+  }
+
+  send(data = {}, { metadata = {}, buffers = [] } = {}) {
+    if (this.closed) return;
+    this.#send("comm_msg", { comm_id: this.id, data }, metadata, buffers);
+  }
+
+  close(data = {}, { metadata = {}, buffers = [] } = {}) {
+    if (this.closed) return;
+    this.#send("comm_close", { comm_id: this.id, data }, metadata, buffers);
+    // close() is synchronous for callers; its close handlers run detached.
+    void this._closed({ data, metadata, buffers });
+  }
+
+  onMsg(handler) {
+    this.#msgHandlers.push(handler);
+  }
+
+  onClose(handler) {
+    this.#closeHandlers.push(handler);
+  }
+
+  async _receive(msg) {
+    for (const handler of this.#msgHandlers) await handler(msg);
+  }
+
+  async _closed(msg) {
+    if (this.closed) return;
+    this.closed = true;
+    this.#onClosed(this.id);
+    for (const handler of this.#closeHandlers) await handler(msg);
+  }
+}
+
+/**
+ * @param {(msgType: string, content: object, metadata: object, buffers: Uint8Array[]) => void} send
+ * @param {() => string} [newId]
+ */
+export function createComms(send, newId = () => crypto.randomUUID()) {
+  const comms = new Map(); // comm_id -> Comm
+  const targets = new Map(); // target_name -> handler
+  const forget = (id) => comms.delete(id);
+
+  function track(id, targetName) {
+    const comm = new Comm(id, targetName, send, forget);
+    comms.set(id, comm);
+    return comm;
+  }
+
+  const api = {
+    open(targetName, data = {}, { metadata = {}, buffers = [] } = {}) {
+      const comm = track(newId(), targetName);
+      send("comm_open", { comm_id: comm.id, target_name: targetName, data }, metadata, buffers);
+      return comm;
+    },
+    registerTarget(targetName, handler) {
+      targets.set(targetName, handler);
+    },
+    unregisterTarget(targetName) {
+      targets.delete(targetName);
+    },
+  };
+
+  async function dispatch(msgType, content, metadata, buffers) {
+    const msg = { data: content.data ?? {}, metadata: metadata ?? {}, buffers: buffers ?? [] };
+    if (msgType === "comm_open") {
+      const handler = targets.get(content.target_name);
+      if (!handler) return false;
+      await handler(track(content.comm_id, content.target_name), msg);
+      return true;
+    }
+    const comm = comms.get(content.comm_id);
+    if (!comm) return false;
+    if (msgType === "comm_msg") await comm._receive(msg);
+    else if (msgType === "comm_close") await comm._closed(msg);
+    else return false;
+    return true;
+  }
+
+  function list() {
+    return [...comms.values()].map((comm) => ({ commId: comm.id, targetName: comm.targetName }));
+  }
+
+  return { api, dispatch, list };
+}

package/runtime/deno-compat.mjs

@@ -1,3 +1,4 @@
+// @ts-self-types="./deno-compat.d.mts"
 // An opt-in `Deno` namespace for Node targets, so notebooks written for
 // `deno jupyter` keep working: Deno.jupyter plus the file, env and process
 // APIs notebooks commonly reach for, implemented on Node's.

package/runtime/display.d.mts

@@ -1,3 +1,8 @@
+import type { CommApi, Comms } from "./comm.d.mts";
+import type { Widget, WidgetOptions } from "./widget.d.mts";
+
+export type { CommApi, Widget, WidgetOptions };
+
 export const $display: unique symbol;
 
 export type MediaBundle = { [mediaType: string]: unknown };
@@ -33,6 +38,10 @@ export interface JupyterNamespace {
   svg(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
   image(obj: string | Uint8Array): Displayable;
   $display: typeof $display;
+  /** Jupyter comms: bidirectional channels to the frontend. */
+  comm: CommApi;
+  /** An anywidget-compatible widget; display the result to show it. */
+  widget(options: WidgetOptions): Widget;
 }
 
 export interface Jupyter {
@@ -40,6 +49,8 @@ export interface Jupyter {
   broadcastResult(executionCount: number, result: unknown): Promise<void>;
   confirm(message?: string): boolean;
   prompt(message?: string, defaultValue?: string, options?: { password?: boolean }): string | null;
+  /** Routes a frontend comm message into the kernel's comms. */
+  commDispatch: Comms["dispatch"];
 }
 
 export function escapeHTML(str: string): string;