@tlockney/cdp-kernel 0.1.1 → 0.3.0

package/dist/kernel.js

@@ -10,8 +10,13 @@ import { randomUUID } from "node:crypto";
 import { decodeMessage, encodeMessage, PROTOCOL_VERSION, verify } from "./wire.js";
 import { PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
 import { Interrupted, Target } from "./target.js";
-import { CellSyntaxError, objectLiteralCandidate, transformCell } from "./transform.js";
+import { BunTarget } from "./bun-target.js";
+import { WorkerdTarget } from "./workerd-target.js";
+import { launchCelld } from "./celld-target.js";
+import { CellSyntaxError, objectLiteralCandidate } from "./transform.js";
+import { loadDenoProject } from "./deno-config.js";
 import { checkIsComplete, codePointToUtf16Index, exprAtCursor, utf16ToCodePointIndex } from "./text.js";
+import { VERSION } from "./package.js";
 export function parseConnectionInfo(json) {
     const raw = JSON.parse(json);
     if (typeof raw !== "object" || raw === null)
@@ -43,6 +48,10 @@ export class Kernel {
     #conn;
     #runtime;
     #denoCompat;
+    // A Deno target in a Deno project uses its config (#13).
+    #project;
+    #projectWarning = null;
+    #noticeShownFor = null;
     #session = randomUUID();
     #shell;
     #control;
@@ -54,11 +63,14 @@ export class Kernel {
     #parent = {};
     #allowStdin = false;
     #executing = false;
+    // Open comms, for comm_info_request: comm_id -> target_name (#9).
+    #comms = new Map();
     #shuttingDown = false;
     constructor(conn, runtime, options = {}) {
         this.#conn = conn;
         this.#runtime = runtime;
         this.#denoCompat = options.denoCompat ?? false;
+        this.#project = runtime === "deno" ? this.#loadProject(options.notebookDir ?? process.cwd()) : null;
         startHeartbeat(conn.hb_port, conn.ip);
         this.#shell = new RouterSocket(conn.shell_port, conn.ip);
         this.#control = new RouterSocket(conn.control_port, conn.ip);
@@ -75,11 +87,101 @@ export class Kernel {
     #log(text) {
         process.stderr.write(`[cdp-kernel] ${text}\n`);
     }
+    #loadProject(notebookDir) {
+        try {
+            return loadDenoProject(notebookDir);
+        }
+        catch (err) {
+            // A broken deno.json mustn't stop the kernel: run as in a plain
+            // directory and say why in the first cell.
+            const reason = err instanceof Error ? err.message : String(err);
+            this.#projectWarning = `${reason}; running without the project config`;
+            this.#log(this.#projectWarning);
+            return null;
+        }
+    }
+    #transformOptions() {
+        return this.#project?.transform ?? {};
+    }
+    // --- comms (#9) ------------------------------------------------------------
+    #trackComm(msgType, content) {
+        const commId = typeof content.comm_id === "string" ? content.comm_id : null;
+        if (commId === null)
+            return;
+        if (msgType === "comm_open" && typeof content.target_name === "string")
+            this.#comms.set(commId, content.target_name);
+        else if (msgType === "comm_close")
+            this.#comms.delete(commId);
+    }
+    #commInfo(content) {
+        const filter = typeof content.target_name === "string" ? content.target_name : null;
+        const comms = {};
+        for (const [commId, targetName] of this.#comms) {
+            if (filter === null || filter === targetName)
+                comms[commId] = { target_name: targetName };
+        }
+        return comms;
+    }
+    /** A frontend comm message. The busy/idle status around it is the caller's. */
+    async #handleComm(msg) {
+        const type = msg.header.msg_type;
+        const commId = String(msg.content.comm_id ?? "");
+        const target = await this.#ensureTarget();
+        // Kernel messages the handlers send are replies to this message.
+        this.#parent = msg.header;
+        this.#allowStdin = false;
+        this.#executing = true;
+        let handled = false;
+        try {
+            const result = await target.dispatchComm(type, msg.content, msg.metadata, msg.buffers);
+            if ("error" in result) {
+                const { name, message, stack } = result.error;
+                this.#publish("stream", { name: "stderr", text: `Error in ${type} handler: ${stack || `${name}: ${message}`}\n` });
+            }
+            else {
+                handled = result.handled;
+            }
+        }
+        catch (err) {
+            if (!(err instanceof Interrupted))
+                throw err;
+            this.#publish("stream", { name: "stderr", text: `${type} handler interrupted\n` });
+        }
+        finally {
+            this.#executing = false;
+        }
+        await target.flush().catch(() => { });
+        if (type === "comm_open") {
+            if (handled) {
+                this.#comms.set(commId, String(msg.content.target_name ?? ""));
+            }
+            else {
+                // An unknown target, or a handler that failed: the protocol asks the
+                // kernel to close the comm so the frontend doesn't wait on it.
+                this.#publish("comm_close", { comm_id: commId, data: {} });
+            }
+        }
+        else if (type === "comm_close") {
+            this.#comms.delete(commId);
+        }
+    }
     // --- target lifecycle -----------------------------------------------------
+    #launchTarget() {
+        if (this.#runtime === "bun")
+            return BunTarget.launch(this.#targetEvents());
+        if (this.#runtime === "workerd")
+            return WorkerdTarget.launch(this.#targetEvents());
+        if (this.#runtime === "celld")
+            return launchCelld(this.#targetEvents());
+        return Target.launch(this.#runtime, this.#targetEvents(), {
+            denoCompat: this.#denoCompat,
+            denoConfig: this.#project?.configPath,
+        });
+    }
     #ensureTarget() {
         if (this.#target)
             return Promise.resolve(this.#target);
-        this.#targetStarting ??= Target.launch(this.#runtime, this.#targetEvents(), { denoCompat: this.#denoCompat }).then((target) => {
+        this.#targetStarting ??= this.#launchTarget().then((target) => {
             this.#target = target;
             this.#targetStarting = null;
             return target;
@@ -93,16 +195,18 @@ export class Kernel {
         return {
             stream: (name, text) => this.#publish("stream", { name, text }),
             message: (msg) => void this.#onTargetMessage(msg),
-            exit: (code) => {
+            exit: (code, note) => {
                 this.#target = null;
                 if (!this.#shuttingDown) {
-                    this.#publish("stream", { name: "stderr", text: `\n[cdp-kernel] ${this.#runtime} exited (${code}); restarting on next cell\n` });
+                    const text = note ?? `[cdp-kernel] ${this.#runtime} exited (${code}); restarting on next cell`;
+                    this.#publish("stream", { name: "stderr", text: `\n${text}\n` });
                 }
             },
         };
     }
     async #onTargetMessage(msg) {
         if (msg.kind === "iopub") {
+            this.#trackComm(msg.msg_type, msg.content);
             this.#publish(msg.msg_type, msg.content, {
                 metadata: msg.metadata,
                 buffers: msg.buffers.map((b) => new Uint8Array(Buffer.from(b, "base64"))),
@@ -156,7 +260,7 @@ export class Kernel {
             status: "ok",
             protocol_version: PROTOCOL_VERSION,
             implementation: "cdp-kernel",
-            implementation_version: "0.1.0",
+            implementation_version: VERSION,
             language_info: {
                 name: "typescript",
                 version: "5",
@@ -166,7 +270,7 @@ export class Kernel {
                 codemirror_mode: "typescript",
                 nbconvert_exporter: "script",
             },
-            banner: `cdp-kernel on ${this.#runtime} ${versions?.runtime ?? ""} (V8 ${versions?.v8 ?? "?"})`,
+            banner: `cdp-kernel on ${this.#runtime} ${versions?.runtime ?? ""} (${versions?.engine || "?"})`,
             help_links: [],
             debugger: false,
         };
@@ -218,11 +322,12 @@ export class Kernel {
                     this.#reply(this.#shell, peer, msg, "history_reply", { status: "ok", history: [] });
                     break;
                 case "comm_info_request":
-                    this.#reply(this.#shell, peer, msg, "comm_info_reply", { status: "ok", comms: {} });
+                    this.#reply(this.#shell, peer, msg, "comm_info_reply", { status: "ok", comms: this.#commInfo(msg.content) });
                     break;
                 case "comm_open":
-                    // No comm targets (widgets) yet: close it straight away, like Deno.
-                    this.#publish("comm_close", { comm_id: msg.content.comm_id ?? "", data: {} }, { parent: msg.header });
+                case "comm_msg":
+                case "comm_close":
+                    await this.#handleComm(msg);
                     break;
             }
         }
@@ -285,7 +390,7 @@ export class Kernel {
         const wrapped = objectLiteralCandidate(code);
         if (wrapped !== null) {
             try {
-                const result = await target.evaluate(transformCell(wrapped));
+                const result = await target.evaluate(target.transform(wrapped, this.#transformOptions()));
                 if (!result.exceptionDetails)
                     return result;
             }
@@ -294,7 +399,7 @@ export class Kernel {
                     throw err;
             }
         }
-        return target.evaluate(transformCell(code));
+        return target.evaluate(target.transform(code, this.#transformOptions()));
     }
     async #execute(msg, peer) {
         const parent = msg.header;
@@ -307,10 +412,20 @@ export class Kernel {
         this.#allowStdin = msg.content.allow_stdin === true;
         this.#status("busy", parent);
         this.#publish("execute_input", { code, execution_count: count });
+        if (this.#projectWarning !== null) {
+            // Shown once, in the first cell, where the user will see it.
+            this.#publish("stream", { name: "stderr", text: `[cdp-kernel] ${this.#projectWarning}\n` });
+            this.#projectWarning = null;
+        }
         let error = null;
         this.#executing = true;
         try {
             const target = await this.#ensureTarget();
+            if (target.notice !== undefined && this.#noticeShownFor !== target) {
+                // Once per target, in the first cell it runs.
+                this.#noticeShownFor = target;
+                this.#publish("stream", { name: "stderr", text: `${target.notice}\n` });
+            }
             const result = await this.#evaluateCell(target, code);
             if (result.exceptionDetails) {
                 const exception = result.exceptionDetails.exception;

package/dist/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // cdp-kernel CLI.
-//   cdp-kernel install [--runtime node|deno] [--deno-compat] [--name NAME] [--display NAME]
-//   cdp-kernel kernel --runtime node|deno [--deno-compat] --conn CONNECTION_FILE
+//   cdp-kernel install [--runtime node|deno|bun|workerd|celld] [--deno-compat] [--name NAME] [--display NAME]
+//   cdp-kernel kernel --runtime node|deno|bun|workerd|celld [--deno-compat] --conn CONNECTION_FILE
 //   cdp-kernel version
 //
 // --deno-compat (Node only) adds a `Deno` namespace for notebooks written for
@@ -14,7 +14,7 @@ import { parseArgs } from "node:util";
 import { Kernel, parseConnectionInfo } from "./kernel.js";
 import { hostRuntime, kernelArgv, moduleOrigin, VERSION } from "./package.js";
 function isRuntime(value) {
-    return value === "node" || value === "deno";
+    return value === "node" || value === "deno" || value === "bun" || value === "workerd" || value === "celld";
 }
 function kernelsDir() {
     if (process.env.JUPYTER_DATA_DIR)
@@ -59,7 +59,7 @@ const { positionals, values } = parseArgs({
 });
 const runtime = values.runtime;
 if (!isRuntime(runtime)) {
-    console.error(`unknown runtime ${runtime}; expected node or deno`);
+    console.error(`unknown runtime ${runtime}; expected node, deno, bun, workerd or celld`);
     process.exit(2);
 }
 // Deno targets have the real namespace; the shim is for Node.
@@ -83,6 +83,6 @@ switch (positionals[0]) {
         console.log(VERSION);
         break;
     default:
-        console.error("usage: cdp-kernel install [--runtime node|deno] [--deno-compat] | kernel --runtime node|deno --conn FILE | version");
+        console.error("usage: cdp-kernel install [--runtime node|deno|bun|workerd|celld] [--deno-compat] | kernel --runtime node|deno|bun|workerd|celld --conn FILE | version");
         process.exit(2);
 }

package/dist/package.d.ts

@@ -1,6 +1,6 @@
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export declare const VERSION = "0.1.1";
-export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "display.mjs", "node-hooks.mjs", "deno-compat.mjs"];
+export declare const VERSION = "0.3.0";
+export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "bun-channel.mjs", "evaluator.mjs", "workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "node-hooks.mjs", "deno-compat.mjs", "node-modules-resolve.mjs"];
 export type HostRuntime = "node" | "deno";
 export declare function hostRuntime(): HostRuntime;
 /** Where the CLI module was loaded from. */
@@ -20,10 +20,18 @@ export declare function moduleOrigin(moduleUrl: string): Origin;
 export declare function kernelArgv(host: HostRuntime, execPath: string, origin: Origin, args: string[]): string[];
 export declare function cacheRoot(): string;
 export type FetchText = (url: string) => Promise<string>;
+/** True when a file: URL points inside a node_modules directory (an npm install). */
+export declare function isInsideNodeModules(url: string): boolean;
 /**
  * A local directory holding runtime/*.mjs. `baseUrl` is the runtime/
  * directory's URL relative to the calling module. A file: URL is used in
- * place; anything else is copied once into a cache keyed by version and
- * URL.
+ * place unless `copy` is set; anything else is copied once into a cache
+ * keyed by version and URL.
+ *
+ * `copy` exists for Deno targets of an npm install: Deno resolves imports
+ * made by a module under node_modules as npm-package imports, without the
+ * notebook project's import map, so the bootstrap must load from outside it.
  */
-export declare function runtimeDir(baseUrl: string, cache?: string, get?: FetchText): Promise<string>;
+export declare function runtimeDir(baseUrl: string, cache?: string, get?: FetchText, { copy }?: {
+    copy?: boolean;
+}): Promise<string>;

package/dist/package.js

@@ -8,14 +8,25 @@
 //     import its bootstrap from an https URL, so a JSR install copies those
 //     files into a local cache first.
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export const VERSION = "0.1.1";
-export const RUNTIME_FILES = ["bootstrap.mjs", "display.mjs", "node-hooks.mjs", "deno-compat.mjs"];
+export const VERSION = "0.3.0";
+export const RUNTIME_FILES = [
+    "bootstrap.mjs",
+    "bun-channel.mjs",
+    "evaluator.mjs",
+    "workerd-worker.mjs",
+    "display.mjs",
+    "comm.mjs",
+    "widget.mjs",
+    "node-hooks.mjs",
+    "deno-compat.mjs",
+    "node-modules-resolve.mjs",
+];
 export function hostRuntime() {
     return process.versions.deno === undefined ? "node" : "deno";
 }
@@ -57,15 +68,29 @@ async function fetchText(url) {
         throw new Error(`fetching ${url}: ${res.status} ${res.statusText}`);
     return await res.text();
 }
+/** True when a file: URL points inside a node_modules directory (an npm install). */
+export function isInsideNodeModules(url) {
+    return url.startsWith("file:") && fileURLToPath(url).split(sep).includes("node_modules");
+}
+function readLocal(url) {
+    return Promise.resolve(readFileSync(fileURLToPath(url), "utf8"));
+}
 /**
  * A local directory holding runtime/*.mjs. `baseUrl` is the runtime/
  * directory's URL relative to the calling module. A file: URL is used in
- * place; anything else is copied once into a cache keyed by version and
- * URL.
+ * place unless `copy` is set; anything else is copied once into a cache
+ * keyed by version and URL.
+ *
+ * `copy` exists for Deno targets of an npm install: Deno resolves imports
+ * made by a module under node_modules as npm-package imports, without the
+ * notebook project's import map, so the bootstrap must load from outside it.
  */
-export async function runtimeDir(baseUrl, cache = cacheRoot(), get = fetchText) {
-    if (baseUrl.startsWith("file:"))
+export async function runtimeDir(baseUrl, cache = cacheRoot(), get = fetchText, { copy = false } = {}) {
+    const local = baseUrl.startsWith("file:");
+    if (local && !copy)
         return fileURLToPath(baseUrl);
+    if (local)
+        get = readLocal;
     const key = createHash("sha256").update(baseUrl).digest("hex").slice(0, 12);
     const dir = join(cache, "runtime", `${VERSION}-${key}`);
     if (RUNTIME_FILES.every((name) => existsSync(join(dir, name))))

package/dist/target.d.ts

@@ -1,7 +1,53 @@
 import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
-export type RuntimeName = "node" | "deno";
+import { type CellTransformOptions, transformCell } from "./transform.ts";
+/** Targets driven over CDP. */
+export type CdpRuntime = "node" | "deno";
+/** Bun and workerd have their own backends: src/bun-target.ts, src/workerd-target.ts. */
+export type RuntimeName = CdpRuntime | "bun" | "workerd" | "celld";
+/** What the kernel needs from a target runtime. */
+export interface KernelTarget {
+    readonly runtime: RuntimeName;
+    readonly versions: {
+        runtime: string;
+        engine: string;
+    };
+    /** Shown once, in the first cell: e.g. which project's bindings loaded. */
+    readonly notice?: string;
+    /** Turns a cell into the script evaluate() takes. */
+    transform(code: string, options: CellTransformOptions): string;
+    /** Runs a transformed cell. Rejects with Interrupted after interrupt(). */
+    evaluate(script: string): Promise<EvaluateResult>;
+    interrupt(): Promise<void>;
+    /** Resolves once all output and messages sent so far have been delivered. */
+    flush(): Promise<void>;
+    broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
+    dispatchComm(msgType: string, content: CdpParams, metadata: CdpParams, buffers: Uint8Array[]): Promise<{
+        handled: boolean;
+    } | {
+        error: {
+            name: string;
+            message: string;
+            stack: string;
+        };
+    }>;
+    describeError(exception: RemoteObject): Promise<{
+        name: string;
+        message: string;
+        stack: string;
+    }>;
+    propertyNames(expression: string): Promise<string[]>;
+    lexicalNames(): Promise<string[]>;
+    replyInput(value: string | null): void;
+    kill(): void;
+}
+export interface LaunchOptions {
+    /** Runtime binary; defaults to `deno`, or `node` (this one when hosted by Node). */
+    executable?: string;
+    /** A Deno target's project config (deno.json), passed as --config. */
+    denoConfig?: string;
+}
 /** `bootstrap` is the local path of runtime/bootstrap.mjs (see runtimeDir). */
-export declare function launchCommand(runtime: RuntimeName, bootstrap: string, executable?: string): {
+export declare function launchCommand(runtime: CdpRuntime, bootstrap: string, { executable, denoConfig }?: LaunchOptions): {
     cmd: string;
     args: string[];
 };
@@ -19,6 +65,7 @@ export type TargetMessage = {
     password: boolean;
     barrier: number;
 };
+export declare function isTargetMessage(value: unknown): value is TargetMessage;
 /**
  * Splits one output pipe into text and barrier markers, and releases them
  * in order. A gated marker (one that announces a binding message) pauses
@@ -36,26 +83,36 @@ export declare class PipeDemux {
     /** Release everything (the process died). */
     close(): void;
 }
+/** Promises keyed by barrier number, resolvable before or after first use. */
+export declare class Gates {
+    #private;
+    wait(n: number): Promise<void>;
+    open(n: number): void;
+    openAll(): void;
+}
 export interface TargetEvents {
     stream(name: "stdout" | "stderr", text: string): void;
     message(msg: TargetMessage): void;
-    exit(code: number | null): void;
+    /** `note` says why, when the target was stopped on purpose. */
+    exit(code: number | null, note?: string): void;
 }
 export declare class Interrupted extends Error {
     name: string;
 }
-export declare class Target {
+export declare class Target implements KernelTarget {
     #private;
-    readonly runtime: RuntimeName;
+    readonly runtime: CdpRuntime;
+    readonly transform: typeof transformCell;
     readonly versions: {
         runtime: string;
-        v8: string;
+        engine: string;
     };
     private constructor();
-    static launch(runtime: RuntimeName, events: TargetEvents, options?: {
+    static launch(runtime: CdpRuntime, events: TargetEvents, options?: {
         cwd?: string;
         executable?: string;
         denoCompat?: boolean;
+        denoConfig?: string;
     }): Promise<Target>;
     /** Resolves once all output and messages sent so far have been delivered. */
     flush(): Promise<void>;
@@ -72,6 +129,20 @@ export declare class Target {
     callFunctionOn(functionDeclaration: string, args: CdpParams[]): Promise<CdpParams>;
     /** The broadcastResult step of Deno's execute flow (jupyter/mod.rs). */
     broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
+    /**
+     * Hands a frontend comm message to the target's comms. Resolves to
+     * whether a comm or registered target took it, or to the error a handler
+     * threw. Rejects with Interrupted after interrupt().
+     */
+    dispatchComm(msgType: string, content: CdpParams, metadata: CdpParams, buffers: Uint8Array[]): Promise<{
+        handled: boolean;
+    } | {
+        error: {
+            name: string;
+            message: string;
+            stack: string;
+        };
+    }>;
     describeError(exception: RemoteObject): Promise<{
         name: string;
         message: string;

package/dist/target.js

@@ -1,12 +1,13 @@
 // A target runtime driven over CDP: the stand-in for Deno's REPL isolate and
 // the ops in cli/ops/jupyter.rs. Any runtime whose --inspect speaks CDP and
 // can load runtime/bootstrap.mjs works; Node and Deno are wired up here.
+import { Buffer } from "node:buffer";
 import process from "node:process";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
 import { asEvaluateResult, CdpAbandoned, CdpSession } from "./cdp.js";
-import { SHIM } from "./transform.js";
-import { hostRuntime, runtimeDir } from "./package.js";
+import { SHIM, transformCell } from "./transform.js";
+import { hostRuntime, isInsideNodeModules, runtimeDir } from "./package.js";
 const BINDING = "__cdpk_send";
 const MARKER_RE = /\x1b\[cdpk:(\d+)(m?)\]\x1b/;
 const MAX_MARKER_LEN = 24;
@@ -15,8 +16,12 @@ const MAX_MARKER_LEN = 24;
 // sends to the server log rather than the notebook).
 const INSPECTOR_CHATTER = /^(?:\x1b\[[0-9;]*m)*(Debugger listening on |Debugger attached\.|For help, see: |Visit chrome:\/\/inspect|Waiting for the debugger to disconnect|Download(?:\x1b\[[0-9;]*m)* https?:\/\/).*\n/gm;
 /** `bootstrap` is the local path of runtime/bootstrap.mjs (see runtimeDir). */
-export function launchCommand(runtime, bootstrap, executable) {
-    const inspect = "--inspect=127.0.0.1:0";
+export function launchCommand(runtime, bootstrap, { executable, denoConfig } = {}) {
+    // The CDP WebSocket has no authentication, so its URL must stay private:
+    // by default the inspector lists it at /json/list for any local process
+    // to read. Publishing it only on stderr, which only this host reads,
+    // leaves a random id nobody else can learn (#22).
+    const inspect = ["--inspect=127.0.0.1:0", "--inspect-publish-uid=stderr"];
     if (runtime === "deno") {
         // Deno discovers config from the main module's location, which would
         // put npm: imports in BYONM mode against this package's own
@@ -25,14 +30,18 @@ export function launchCommand(runtime, bootstrap, executable) {
         // into this package.
         return {
             cmd: executable ?? "deno",
-            args: ["run", "--allow-all", "--node-modules-dir=none", "--no-lock", inspect, bootstrap],
+            // In a project, its config (import map, nodeModulesDir, ...) applies
+            // instead; --no-lock still keeps the kernel out of the project's lock.
+            args: denoConfig === undefined
+                ? ["run", "--allow-all", "--node-modules-dir=none", "--no-lock", ...inspect, bootstrap]
+                : ["run", "--allow-all", "--config", denoConfig, "--no-lock", ...inspect, bootstrap],
         };
     }
     // Under a Deno host, process.execPath is deno; find node on PATH instead.
     const node = hostRuntime() === "node" ? process.execPath : "node";
-    return { cmd: executable ?? node, args: [inspect, bootstrap] };
+    return { cmd: executable ?? node, args: [...inspect, bootstrap] };
 }
-function isTargetMessage(value) {
+export function isTargetMessage(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const kind = value.kind;
@@ -131,7 +140,7 @@ export class PipeDemux {
     }
 }
 /** Promises keyed by barrier number, resolvable before or after first use. */
-class Gates {
+export class Gates {
     #map = new Map();
     #entry(n) {
         let entry = this.#map.get(n);
@@ -160,6 +169,7 @@ export class Interrupted extends Error {
 }
 export class Target {
     runtime;
+    transform = transformCell;
     #child;
     #shell;
     #control;
@@ -182,11 +192,20 @@ export class Target {
         this.versions = versions;
     }
     static async launch(runtime, events, options = {}) {
-        const bootstrap = join(await runtimeDir(new URL("../runtime/", import.meta.url).href), "bootstrap.mjs");
-        const { cmd, args } = launchCommand(runtime, bootstrap, options.executable);
+        const runtimeUrl = new URL("../runtime/", import.meta.url).href;
+        // A Deno target ignores the project's import map for imports made from
+        // under node_modules, so an npm install's runtime files are copied out.
+        const copy = runtime === "deno" && isInsideNodeModules(runtimeUrl);
+        const bootstrap = join(await runtimeDir(runtimeUrl, undefined, undefined, { copy }), "bootstrap.mjs");
+        const { cmd, args } = launchCommand(runtime, bootstrap, {
+            executable: options.executable,
+            denoConfig: options.denoConfig,
+        });
         const env = { ...process.env, FORCE_COLOR: "1" };
         if (options.denoCompat)
             env.CDPK_DENO_COMPAT = "1";
+        if (runtime === "deno" && options.denoConfig !== undefined)
+            env.CDPK_DENO_PROJECT = "1";
         delete env.NO_COLOR;
         const child = spawn(cmd, args, { cwd: options.cwd, stdio: ["pipe", "pipe", "pipe"], env });
         child.stdout.setEncoding("utf8");
@@ -235,7 +254,7 @@ export class Target {
         await shell.send("Runtime.enable");
         await shell.send("Runtime.addBinding", { name: BINDING });
         const contextId = await contextReady;
-        const target = new Target(runtime, child, shell, control, stdout, stderr, gates, contextId, { runtime: "", v8: "" });
+        const target = new Target(runtime, child, shell, control, stdout, stderr, gates, contextId, { runtime: "", engine: "" });
         shell.on("Runtime.bindingCalled", (params) => {
             if (params.name !== BINDING || typeof params.payload !== "string")
                 return;
@@ -250,7 +269,7 @@ export class Target {
                 break;
             await new Promise((r) => setTimeout(r, 25));
         }
-        const versions = await target.#evaluateRaw(`JSON.stringify(typeof Deno !== "undefined" ? { runtime: Deno.version.deno, v8: Deno.version.v8 } : { runtime: process.versions.node, v8: process.versions.v8 })`);
+        const versions = await target.#evaluateRaw(`JSON.stringify(typeof Deno !== "undefined" ? { runtime: Deno.version.deno, engine: "V8 " + Deno.version.v8 } : { runtime: process.versions.node, engine: "V8 " + process.versions.v8 })`);
         Object.assign(target.versions, JSON.parse(String(versions.result.value)));
         return target;
     }
@@ -320,6 +339,42 @@ export class Target {
             arg,
         ]);
     }
+    /**
+     * Hands a frontend comm message to the target's comms. Resolves to
+     * whether a comm or registered target took it, or to the error a handler
+     * threw. Rejects with Interrupted after interrupt().
+     */
+    async dispatchComm(msgType, content, metadata, buffers) {
+        this.#interrupted = false;
+        let res;
+        try {
+            res = await this.#shell.send("Runtime.callFunctionOn", {
+                functionDeclaration: `function (t, c, m, b) { return globalThis.${SHIM}.commDispatch(t, c, m, b); }`,
+                arguments: [
+                    { value: msgType },
+                    { value: content },
+                    { value: metadata },
+                    { value: buffers.map((b) => Buffer.from(b).toString("base64")) },
+                ],
+                executionContextId: this.#contextId,
+                awaitPromise: true,
+                returnByValue: true,
+            });
+        }
+        catch (err) {
+            if (err instanceof CdpAbandoned || this.#interrupted)
+                throw new Interrupted("Comm handler interrupted");
+            throw err;
+        }
+        const details = res.exceptionDetails;
+        if (details) {
+            const error = details.exception
+                ? await this.describeError(details.exception)
+                : { name: "Error", message: details.text, stack: "" };
+            return { error };
+        }
+        return { handled: res.result?.value === true };
+    }
     async describeError(exception) {
         const arg = exception.objectId ? { objectId: exception.objectId } : { value: exception.value };
         const res = await this.callFunctionOn(`function (e) { return globalThis.${SHIM}.describeError(e); }`, [arg]);