@tlockney/cdp-kernel 0.6.0 → 0.7.1

package/dist/traceback.js

@@ -0,0 +1,200 @@
+// Structured tracebacks (#322): an error's stack as frames a frontend can
+// render, link to cells and fold, alongside the classic `traceback` lines.
+// The payload follows nteract's application/vnd.nteract.traceback+json
+// (runtimed/runt, docs/adr/traceback-output-protocol.md): ename, evalue,
+// frames with a source window and a `library` flag, and a plain `text`
+// rendering. Building it must never cost the user their traceback: callers
+// fall back to the classic lines if it throws.
+//
+// Cells run under a //# sourceURL naming them (cellName), so a frame in a
+// cell, including one in a function an earlier cell defined, says which
+// cell. Its line goes through the cell's source map, as for the debugger
+// (src/sourcemap.ts), so it is the line the user wrote, not the line of the
+// stripped JavaScript. Only lines are mapped: a cell frame has no column.
+//
+// Nothing here imports Node; reading other files' source is the caller's.
+import { murmur2 } from "./murmur2.js";
+export const TRACEBACK_MIME = "application/vnd.nteract.traceback+json";
+/** Lines of source shown around a frame's line. */
+const CONTEXT_BEFORE = 2;
+const CONTEXT_AFTER = 2;
+/** Longer stacks keep their first and last frames. */
+const HEAD_FRAMES = 20;
+const TAIL_FRAMES = 10;
+/** The //# sourceURL a cell's script runs under while not debugging. */
+export function cellName(code) {
+    return `$cdpk$cell-${murmur2(code, 0).toString(36)}.ts`;
+}
+// V8: "    at fn (file:1:2)", "    at file:1:2", "    at async fn (file:1:2)",
+// "    at new Promise (<anonymous>)".
+const V8_FRAME = /^\s*at (?:(.*?) \((.*?)(?::(\d+):(\d+))?\)|(.*?)(?::(\d+):(\d+))?)$/;
+// JavaScriptCore and SpiderMonkey: "fn@file:1:2", "@file:1:2", "fn@[native code]".
+const AT_FRAME = /^([^\s@]*)@(.+?)(?::(\d+):(\d+))?$/;
+/** One line of a stack as a frame, or null for a line that isn't one (the message). */
+export function parseFrame(text) {
+    const v8 = /^\s*at /.test(text) ? V8_FRAME.exec(text) : null;
+    if (v8) {
+        const named = v8[2] !== undefined;
+        const line = named ? v8[3] : v8[6];
+        const column = named ? v8[4] : v8[7];
+        return {
+            name: named ? v8[1] : "",
+            file: named ? v8[2] : v8[5],
+            line: line === undefined ? null : Number(line),
+            column: column === undefined ? null : Number(column),
+        };
+    }
+    const at = !/^\s/.test(text) && text.includes("@") ? AT_FRAME.exec(text) : null;
+    if (at) {
+        return {
+            name: at[1],
+            file: at[2],
+            line: at[3] === undefined ? null : Number(at[3]),
+            column: at[4] === undefined ? null : Number(at[4]),
+        };
+    }
+    return null;
+}
+/**
+ * Frames from packages, runtimes and the kernel itself, which a frontend
+ * can dim or fold: a hint, not a boundary.
+ */
+export function isLibraryFile(file, kernelFiles = []) {
+    if (["", "<anonymous>", "native", "[native code]", "unknown"].includes(file))
+        return true;
+    if (/^(?:node|ext|deno|bun|jsr|npm|internal):/.test(file))
+        return true;
+    if (/^https?:\/\/(?:jsr\.io|esm\.sh|cdn\.jsdelivr\.net|unpkg\.com|deno\.land)\//.test(file))
+        return true;
+    const path = file.replaceAll("\\", "/");
+    if (path.includes("/node_modules/") || path.includes("/npm/registry.npmjs.org/"))
+        return true;
+    return kernelFiles.some((prefix) => path.startsWith(prefix));
+}
+function window(source, line) {
+    const all = source.split("\n");
+    if (all.length > 1 && all[all.length - 1] === "")
+        all.pop();
+    const out = [];
+    for (let n = Math.max(1, line - CONTEXT_BEFORE); n <= Math.min(all.length, line + CONTEXT_AFTER); n++) {
+        const entry = { lineno: n, source: all[n - 1].replace(/\r$/, "") };
+        if (n === line)
+            entry.highlight = true;
+        out.push(entry);
+    }
+    return out;
+}
+/** How a cell frame's location reads in the classic traceback. */
+function cellLabel(cell) {
+    return cell.executionCount === null ? "cell" : `In[${cell.executionCount}]`;
+}
+/**
+ * `stack` is the error's stack as the target describes it (src/target.ts's
+ * describeError), message lines included. `callFrames`, from CDP, name the
+ * scripts of frames the stack shows as "<anonymous>": Deno formats stacks
+ * itself and doesn't use a script's //# sourceURL.
+ */
+export function buildTraceback(error, sources, execution) {
+    const raw = error.stack || `${error.ename}: ${error.evalue}`;
+    const lines = [];
+    const frames = [];
+    const callFrames = error.callFrames ?? [];
+    let next = 0;
+    for (const text of raw.split("\n")) {
+        const parsed = parseFrame(text);
+        if (parsed === null) {
+            lines.push(text);
+            continue;
+        }
+        let file = parsed.file;
+        if (parsed.line !== null) {
+            // CDP lists only frames with a position, in the same order.
+            const at = callFrames.findIndex((frame, i) => i >= next && frame.lineNumber + 1 === parsed.line && frame.columnNumber + 1 === parsed.column);
+            if (at !== -1) {
+                next = at + 1;
+                if (file === "<anonymous>" && callFrames[at].url)
+                    file = callFrames[at].url;
+            }
+        }
+        const cell = sources.cell(file);
+        if (cell !== undefined && parsed.line !== null) {
+            // Script lines are 1-based; the map's are 0-based.
+            const lineno = cell.lines ? cell.lines.toOriginal(parsed.line - 1) + 1 : parsed.line;
+            const frame = {
+                filename: cellLabel(cell),
+                lineno,
+                name: parsed.name,
+                library: false,
+                lines: window(cell.code, lineno),
+            };
+            if (cell.executionCount !== null)
+                frame.execution_count = cell.executionCount;
+            if (cell.cellId !== null)
+                frame.cell_id = cell.cellId;
+            frame.source_ref = {
+                kind: "notebook_execution",
+                ...(cell.executionCount !== null ? { execution_count: cell.executionCount } : {}),
+                ...(cell.cellId !== null ? { cell_id: cell.cellId } : {}),
+            };
+            frames.push(frame);
+            const location = `${cellLabel(cell)}:${lineno}`;
+            lines.push(rewriteLocation(text, parsed, location));
+            continue;
+        }
+        lines.push(text);
+        const library = isLibraryFile(file, sources.kernelFiles);
+        const frame = {
+            filename: file,
+            lineno: parsed.line ?? 0,
+            name: parsed.name,
+            library,
+            lines: [],
+        };
+        if (parsed.column !== null)
+            frame.colno = parsed.column;
+        if (!library && parsed.line !== null) {
+            const source = sources.readFile?.(file);
+            if (source !== undefined)
+                frame.lines = window(source, parsed.line);
+        }
+        frames.push(frame);
+    }
+    // What ran the cell (the kernel's evaluator, the runtime's own frames)
+    // comes after the cell's last frame and is never the user's.
+    const lastCell = frames.findLastIndex((frame) => frame.source_ref !== undefined);
+    let end = frames.length;
+    while (end > lastCell + 1 && lastCell !== -1 && frames[end - 1].library)
+        end--;
+    const kept = clip(frames.slice(0, end));
+    const payload = {
+        ename: error.ename,
+        evalue: error.evalue,
+        language: "typescript",
+        frames: kept,
+        syntax: null,
+        text: lines.join("\n"),
+        raw_text: raw,
+    };
+    if (execution.executionCount !== null || execution.cellId !== null) {
+        payload.execution = {
+            ...(execution.executionCount !== null ? { execution_count: execution.executionCount } : {}),
+            ...(execution.cellId !== null ? { cell_id: execution.cellId } : {}),
+        };
+    }
+    return { lines, payload };
+}
+function rewriteLocation(text, frame, location) {
+    const original = `${frame.file}:${frame.line}${frame.column === null ? "" : `:${frame.column}`}`;
+    const at = text.lastIndexOf(original);
+    return at === -1 ? text : text.slice(0, at) + location + text.slice(at + original.length);
+}
+function clip(frames) {
+    if (frames.length <= HEAD_FRAMES + TAIL_FRAMES)
+        return frames;
+    const omitted = frames.length - HEAD_FRAMES - TAIL_FRAMES;
+    return [
+        ...frames.slice(0, HEAD_FRAMES),
+        { filename: "", lineno: 0, name: `… ${omitted} frames omitted …`, library: true, lines: [] },
+        ...frames.slice(-TAIL_FRAMES),
+    ];
+}

package/dist/transform.d.ts

@@ -1,5 +1,6 @@
 import { LineMap } from "./sourcemap.ts";
 export declare const SHIM = "__cdpk";
+export declare const YIELD = "await __cdpk.tick();\n";
 /**
  * Each replMode cell also ends by yielding one macrotask, so the script
  * settles with no other microtasks queued ahead of the inspector's

package/dist/transform.js

@@ -23,7 +23,14 @@ export const SHIM = "__cdpk";
 // which is what lets a Runtime.terminateExecution from the control session
 // interrupt a busy loop. (Within that dispatch the inspector processes no
 // other messages, so an interrupt would never be seen.)
-const PRELUDE = `'use strict'; await ${SHIM}.tick();\n`;
+//
+// An expression that throws before its first await rejects the replMode
+// result promise at once, inside that dispatch, and a GC before the
+// inspector's then-callback runs fails the evaluate with "Promise was
+// collected" (#329). Yielding first moves the throw into a task, where
+// SETTLE's reasoning applies. The debug console uses YIELD for this.
+export const YIELD = `await ${SHIM}.tick();\n`;
+const PRELUDE = `'use strict'; ${YIELD}`;
 /**
  * Each replMode cell also ends by yielding one macrotask, so the script
  * settles with no other microtasks queued ahead of the inspector's

package/dist/wire.d.ts

@@ -1,35 +1,15 @@
+import { type Header, type JsonObject, type KernelMessage } from "./message.ts";
+export { makeHeader, PROTOCOL_VERSION } from "./message.ts";
+export type { Header, JsonObject, ReceivedHeader } from "./message.ts";
 export declare const DELIMITER: Uint8Array<ArrayBuffer>;
-export declare const PROTOCOL_VERSION = "5.3";
-export type JsonObject = {
-    [key: string]: unknown;
-};
-export interface Header extends JsonObject {
-    msg_id: string;
-    session: string;
-    date: string;
-    username: string;
-    msg_type: string;
-    version: string;
-}
-/** A header as received: the fields the kernel relies on, plus whatever else came. */
-export interface ReceivedHeader extends JsonObject {
-    msg_id: string;
-    msg_type: string;
-}
-export interface Message {
+export interface Message extends KernelMessage {
     identities: Uint8Array[];
     sig: string;
     /** Raw bytes of header, parent_header, metadata, content as received. */
     signedParts: Uint8Array[];
-    header: ReceivedHeader;
-    parentHeader: JsonObject;
-    metadata: JsonObject;
-    content: JsonObject;
-    buffers: Uint8Array[];
 }
 export declare function sign(key: string, parts: Uint8Array[]): string;
 export declare function verify(key: string, parts: Uint8Array[], sig: string): boolean;
-export declare function makeHeader(session: string, msgType: string): Header;
 export interface EncodeOptions {
     /** Defaults to a fresh header; pass one to know its msg_id. */
     header?: Header;

package/dist/wire.js

@@ -4,11 +4,12 @@
 // Copyright 2018-2026 the Deno authors, MIT license. The structure is kept;
 // WebCrypto's async HMAC is replaced with node:crypto's synchronous one.
 import { Buffer } from "node:buffer";
-import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { makeHeader } from "./message.js";
+export { makeHeader, PROTOCOL_VERSION } from "./message.js";
 const ENC = new TextEncoder();
 const DEC = new TextDecoder();
 export const DELIMITER = ENC.encode("<IDS|MSG>");
-export const PROTOCOL_VERSION = "5.3";
 export function sign(key, parts) {
     if (key.length === 0)
         return "";
@@ -29,16 +30,6 @@ export function verify(key, parts, sig) {
     const actual = Buffer.from(sig, "hex");
     return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
-export function makeHeader(session, msgType) {
-    return {
-        msg_id: randomUUID(),
-        session,
-        date: new Date().toISOString(),
-        username: "kernel",
-        msg_type: msgType,
-        version: PROTOCOL_VERSION,
-    };
-}
 export function encodeMessage(session, key, msgType, content, options = {}) {
     const parts = [
         options.header ?? makeHeader(session, msgType),

package/dist/workerd-target.d.ts

@@ -89,12 +89,16 @@ export declare class WorkerdTarget implements KernelTarget {
     static launch(events: TargetEvents, options?: {
         cwd?: string;
         executable?: string;
+        startTimeoutMs?: number;
     }): Promise<WorkerdTarget>;
     /**
      * A target over a started host's session. `notice` (a project that
      * failed to load) is replaced by the bindings when the host has a project.
      */
-    static open(host: WorkerHost, cwd: string, events: TargetEvents, runtime: WorkersRuntime, notice?: string): Promise<WorkerdTarget>;
+    static open(host: WorkerHost, cwd: string, events: TargetEvents, runtime: WorkersRuntime, options?: {
+        notice?: string;
+        startTimeoutMs?: number;
+    }): Promise<WorkerdTarget>;
     evaluate(script: string): Promise<EvaluateResult>;
     /**
      * A cell that's waiting on something leaves the driver free: it answers a
@@ -115,6 +119,7 @@ export declare class WorkerdTarget implements KernelTarget {
             stack: string;
         };
     }>;
+    format(value: RemoteObject): Promise<CdpParams>;
     describeError(exception: RemoteObject): Promise<{
         name: string;
         message: string;

package/dist/workerd-target.js

@@ -18,7 +18,7 @@ import { Buffer } from "node:buffer";
 import process from "node:process";
 import { execFileSync, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { copyFileSync, existsSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, rmSync, writeFileSync } from "node:fs";
 import { builtinModules } from "node:module";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -28,7 +28,8 @@ import { asEvaluateResult } from "./cdp.js";
 import { transformCellForEval } from "./transform.js";
 import { runtimeDir } from "./package.js";
 import { killOnExit } from "./children.js";
-import { Interrupted, isTargetMessage } from "./target.js";
+import { Interrupted, isTargetMessage, parseBundle, parseJson } from "./target.js";
+import { withStartTimeout } from "./target-api.js";
 import { connectUnixWebSocket } from "./ws-client.js";
 import { findWranglerConfig, startMiniflare } from "./workers-project.js";
 import { ensureInstalledAsync, findLockFile, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
@@ -188,8 +189,30 @@ function isWorkerdIn(pid, dir) {
     try {
         if (process.platform === "linux")
             return readlinkSync(`/proc/${pid}/cwd`) === dir;
-        const args = execFileSync("ps", ["-o", "args=", "-p", String(pid)], { encoding: "utf8" });
-        return /workerd/.test(args) && args.includes("config.capnp");
+        // No cwd to compare elsewhere: the process must at least be ours and
+        // look like a workerd (#335).
+        const [uid, ...args] = execFileSync("ps", ["-o", "uid=,args=", "-p", String(pid)], { encoding: "utf8" }).trim().split(/\s+/);
+        const command = args.join(" ");
+        return Number(uid) === process.getuid?.() && /workerd/.test(command) && command.includes("config.capnp");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `dir` is a directory mkdtemp made for this user: not a symlink,
+ * owned by us, and closed to everyone else. Anyone can create entries in
+ * tmpdir(), so nothing in a directory that fails this is trusted (#335).
+ * Windows has no uids; its tmpdir() is per-user.
+ */
+function isOwnPrivateDir(dir) {
+    try {
+        const stat = lstatSync(dir);
+        if (!stat.isDirectory())
+            return false;
+        if (process.getuid === undefined)
+            return true;
+        return stat.uid === process.getuid() && (stat.mode & 0o077) === 0;
     }
     catch {
         return false;
@@ -210,12 +233,14 @@ export function sweepStaleWorkerdDirs(root = tmpdir()) {
     }
     for (const name of names) {
         const dir = join(root, name);
+        if (!isOwnPrivateDir(dir))
+            continue;
         let owner;
         try {
             owner = JSON.parse(readFileSync(join(dir, OWNER_FILE), "utf8"));
         }
         catch {
-            continue; // Another user's, from before owner files, or being set up.
+            continue; // From before owner files, or being set up.
         }
         if (typeof owner.host !== "number" || pidAlive(owner.host))
             continue;
@@ -227,7 +252,12 @@ export function sweepStaleWorkerdDirs(root = tmpdir()) {
                 // Gone already.
             }
         }
-        rmSync(dir, { recursive: true, force: true });
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // Cleanup is best effort; it must not stop this kernel starting.
+        }
     }
 }
 /** The driver on a workerd of its own, behind a Unix socket. */
@@ -295,7 +325,7 @@ export class RawWorkerd {
             }
         })();
         try {
-            const host = new RawWorkerd(child, await Promise.race([ready, exited]), compatibilityDate);
+            const host = new RawWorkerd(child, await withStartTimeout(Promise.race([ready, exited]), "workerd"), compatibilityDate);
             starting = false;
             early = "";
             return host;
@@ -360,7 +390,7 @@ export class WorkerdTarget {
         let notice;
         if (project !== null) {
             try {
-                host = await startMiniflare(project, cwd);
+                host = await startMiniflare(project, cwd, options.startTimeoutMs);
             }
             catch (err) {
                 // Like a broken deno.json (#13): say why in the first cell, and run
@@ -370,16 +400,18 @@ export class WorkerdTarget {
             }
         }
         host ??= await RawWorkerd.start(cwd, options.executable);
-        return await WorkerdTarget.open(host, cwd, events, "workerd", notice);
+        return await WorkerdTarget.open(host, cwd, events, "workerd", { notice, startTimeoutMs: options.startTimeoutMs });
     }
     /**
      * A target over a started host's session. `notice` (a project that
      * failed to load) is replaced by the bindings when the host has a project.
      */
-    static async open(host, cwd, events, runtime, notice) {
+    static async open(host, cwd, events, runtime, options = {}) {
         const target = new WorkerdTarget(host, cwd, events, runtime);
+        let notice = options.notice;
         try {
-            const { v8, bindings, worker } = await target.#request("info");
+            // A driver that never answers is stopped (#336).
+            const { v8, bindings, worker } = await withStartTimeout(target.#request("info"), `the ${runtime} driver`, options.startTimeoutMs);
             if (typeof v8 === "string" && v8)
                 target.versions.engine = `V8 ${v8}`;
             if (host.project !== undefined) {
@@ -396,7 +428,15 @@ export class WorkerdTarget {
         return target;
     }
     #receive(text) {
-        const msg = JSON.parse(text);
+        const msg = parseJson(text);
+        if (msg === undefined) {
+            // The driver only sends JSON; a frame that isn't means the session is
+            // broken, which ends the target rather than the kernel (#337).
+            this.#stopNote = `[cdp-kernel] ${this.runtime} sent a message that isn't JSON, so it was stopped; ` +
+                "it restarts on the next cell, without the earlier cells' state";
+            this.kill();
+            return;
+        }
         if (isRecord(msg) && msg.kind === "stream") {
             this.#events.stream(msg.name === "stderr" ? "stderr" : "stdout", String(msg.text));
         }
@@ -519,6 +559,10 @@ export class WorkerdTarget {
         }
         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: "" };

package/dist/workers-project.d.ts

@@ -24,4 +24,4 @@ export declare function bundleProject(main: string, define?: {
     [name: string]: string;
 }): Promise<string>;
 /** Starts the driver on the project's Miniflare with its bindings. */
-export declare function startMiniflare(configPath: string, cwd: string): Promise<WorkerHost>;
+export declare function startMiniflare(configPath: string, cwd: string, startTimeoutMs?: number): Promise<WorkerHost>;

package/dist/workers-project.js

@@ -17,6 +17,7 @@ import { dirname, join } from "node:path";
 import { build } from "esbuild";
 import { childPids, reap } from "./children.js";
 import { runtimeDir } from "./package.js";
+import { withStartTimeout } from "./target-api.js";
 import { cellMeta, WORKER_MODULES } from "./workerd-target.js";
 export const WRANGLER_CONFIGS = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
 /** The nearest wrangler config at or above `cwd`, or null. */
@@ -157,7 +158,7 @@ class MiniflareHost {
     }
 }
 /** Starts the driver on the project's Miniflare with its bindings. */
-export async function startMiniflare(configPath, cwd) {
+export async function startMiniflare(configPath, cwd, startTimeoutMs) {
     const { wrangler, miniflare, version } = loadTooling(configPath);
     const projectDir = dirname(configPath);
     const { workerOptions, main, define } = wrangler.unstable_getMiniflareWorkerOptions(configPath);
@@ -190,10 +191,10 @@ export async function startMiniflare(configPath, cwd) {
     const before = new Set(childPids(process.pid, "workerd"));
     const mf = new miniflare.Miniflare(v5 && miniflare.convertV4MiniflareOptions ? miniflare.convertV4MiniflareOptions(options) : options);
     try {
-        await mf.ready;
         // Miniflare listens on a loopback TCP port; the token is what keeps
         // other local processes from the driver.
-        const res = await mf.dispatchFetch("http://cdpk/", { headers: { Upgrade: "websocket", "x-cdpk-token": token } });
+        const connect = mf.ready.then(() => mf.dispatchFetch("http://cdpk/", { headers: { Upgrade: "websocket", "x-cdpk-token": token } }));
+        const res = await withStartTimeout(connect, "Miniflare", startTimeoutMs);
         if (res.status !== 101 || res.webSocket === null)
             throw new Error(`the driver answered ${res.status}: ${await res.text()}`);
         const workerd = childPids(process.pid, "workerd").filter((pid) => !before.has(pid));

package/dist/zmq-channels.d.ts

@@ -0,0 +1,14 @@
+import type { ConnectionInfo } from "./kernel.ts";
+import type { ChannelName, KernelChannels, Received } from "./kernel-core.ts";
+import type { OutgoingMessage } from "./message.ts";
+export declare class ZmqChannels implements KernelChannels {
+    #private;
+    readonly ready: Promise<unknown>;
+    constructor(conn: ConnectionInfo, log: (text: string) => void);
+    recv(channel: ChannelName): Promise<Received | null>;
+    shellQueued(): number;
+    reply(channel: ChannelName, peer: string, msg: OutgoingMessage): void;
+    publish(msg: OutgoingMessage): void;
+    stdinPeers(): number;
+    sendStdin(msg: OutgoingMessage): void;
+}

package/dist/zmq-channels.js

@@ -0,0 +1,59 @@
+// KernelChannels over ZeroMQ: the connection file's five ports, with
+// messages framed and signed as src/wire.ts does it.
+import { decodeMessage, encodeMessage, verify } from "./wire.js";
+import { listening, PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
+export class ZmqChannels {
+    ready;
+    #key;
+    #log;
+    #routers;
+    #iopub;
+    constructor(conn, log) {
+        this.#key = conn.key;
+        this.#log = log;
+        const heartbeat = startHeartbeat(conn.hb_port, conn.ip);
+        this.#routers = {
+            shell: new RouterSocket(conn.shell_port, conn.ip),
+            control: new RouterSocket(conn.control_port, conn.ip),
+            stdin: new RouterSocket(conn.stdin_port, conn.ip),
+        };
+        this.#iopub = new PubSocket(conn.iopub_port, conn.ip);
+        // Settles once all five ports are bound (#257).
+        this.ready = Promise.all([heartbeat, ...Object.values(this.#routers).map((r) => r.server), this.#iopub.server].map(listening));
+    }
+    async recv(channel) {
+        const { peer, frames } = await this.#routers[channel].recv();
+        try {
+            const msg = decodeMessage(frames);
+            // Unsigned or forged messages are dropped, as in Deno.
+            return verify(this.#key, msg.signedParts, msg.sig) ? { peer, msg } : null;
+        }
+        catch (err) {
+            this.#log(`error handling message: ${err instanceof Error ? err.stack : err}`);
+            return null;
+        }
+    }
+    shellQueued() {
+        return this.#routers.shell.incoming.size;
+    }
+    #encode(msg) {
+        return encodeMessage(msg.header.session, this.#key, msg.header.msg_type, msg.content, {
+            header: msg.header,
+            parentHeader: msg.parentHeader,
+            metadata: msg.metadata,
+            buffers: msg.buffers,
+        });
+    }
+    reply(channel, peer, msg) {
+        this.#routers[channel].send(peer, this.#encode(msg));
+    }
+    publish(msg) {
+        this.#iopub.send(this.#encode(msg));
+    }
+    stdinPeers() {
+        return this.#routers.stdin.peers.size;
+    }
+    sendStdin(msg) {
+        this.#routers.stdin.sendAll(this.#encode(msg));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on Node, Deno, Bun, workerd and celld",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
@@ -34,6 +34,11 @@
       "types": "./dist/globals.d.ts",
       "default": "./dist/globals.js"
     },
+    "./browser": {
+      "types": "./dist/browser/mod.d.ts",
+      "default": "./dist/browser/kernel.js"
+    },
+    "./browser/worker": "./dist/browser/worker.js",
     "./globals/deno-compat": {
       "types": "./dist/globals-deno-compat.d.ts",
       "default": "./dist/globals-deno-compat.js"
@@ -49,11 +54,12 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/build-browser.mjs dist/browser",
     "check": "tsc -p tsconfig.json",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:notebooks": "node docs/.vitepress/run-notebooks.ts",
+    "docs:debugger": "uv run --with jupyterlab --with playwright --with nbformat python test/debugger_screenshot.py",
     "docs:widgets": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/widget_screenshots.py",
     "install:node": "node src/main.ts install --runtime node",
     "install:deno": "node src/main.ts install --runtime deno",
@@ -76,6 +82,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.19.2",
+    "medium-zoom": "^1.1.0",
     "vitepress": "^1.6.4",
     "workerd": "1.20261015.1",
     "wrangler": "4.151.0"

package/runtime/bootstrap.mjs

@@ -215,6 +215,8 @@ globalThis.__cdpk = {
   inspectPath: (path, detail) => inspectPath(path, { inspect: inspectPlain, detail }),
   resolvePath,
   broadcastResult: jupyter.broadcastResult,
+  // execute_request's user_expressions (#340).
+  formatJson: async (value) => JSON.stringify(await jupyter.namespace.format(value)),
   // The debugger's rich variable viewer (#18), synchronously: it runs while
   // the target is paused. A value whose $display is async shows as text.
   richBundle(value) {