@tlockney/cdp-kernel 0.1.0 → 0.2.0

package/README.md

@@ -11,7 +11,10 @@ own Jupyter integration tests on both targets, and it's packaged for npm and
 JSR as `@tlockney/cdp-kernel`, but it hasn't seen much real use yet. The
 feasibility study behind it covers the design,
 the other options considered (workerd, Bun, rusty_v8, FFI), and the
-evidence: [`docs/life-after-deno-jupyter.html`](docs/life-after-deno-jupyter.html).
+evidence: [read it online](https://claude.ai/artifact/S66TnTmhCzPy2EW7jbeeue)
+(also in the repo as
+[`docs/life-after-deno-jupyter.html`](docs/life-after-deno-jupyter.html)). It
+was written before packaging, so it calls the project a spike.
 The scripts that produced its runtime findings are in [`probes/`](probes/).
 
 ## Why this shape
@@ -64,6 +67,14 @@ The kernelspec pins the release it was installed from
 runtime modules are copied into `~/.cache/cdp-kernel/runtime/`. A Node
 target needs `node` on `PATH`.
 
+Deno 2.9+ refuses package versions less than 24 hours old by default
+([minimum dependency age](https://docs.deno.com/go/minimum-dependency-age)).
+In a release's first day, the install command fails with "blocked by the
+minimum dependency age policy". Wait out the day, or install an earlier
+release. Passing `--min-dep-age=0` gets the install through, but the
+kernelspec doesn't carry the flag, so the kernel still won't launch until
+the release is a day old.
+
 **From a checkout**, for working on the kernel itself:
 
 ```sh
@@ -93,12 +104,103 @@ In a cell:
   or `jsr:@scope/pkg@range`.
   - On Node, `npm:` and `jsr:` install on first use into
     `~/.cache/cdp-kernel/npm`.
-  - On Deno they use Deno's global cache. The target runs with
-    `--node-modules-dir=none --no-lock`, so a project-local `node_modules`
-    isn't used.
+  - On Deno they use Deno's global cache, unless the notebook is in a Deno
+    project (below).
+- **Deno projects.** If a `deno.json` or `deno.jsonc` sits in the notebook's
+  directory or above it, a Deno target uses it, as `deno jupyter` does:
+  - its import map (`"@/": "./lib/"` aliases, mapped packages);
+  - its `nodeModulesDir` setting, with `package.json` dependencies from the
+    project's `node_modules`;
+  - its JSX and decorator `compilerOptions`: `jsx` (`react-jsx`,
+    `react-jsxdev`, `precompile`, `react`), `jsxImportSource`,
+    `jsxFactory`, `jsxFragmentFactory`, `experimentalDecorators`.
+
+  The import map wins over `node_modules`, as in Deno. The kernel never
+  writes to the project's lockfile. A `deno.json` that doesn't parse is
+  reported in the first cell's output, and the kernel runs as in a plain
+  directory. Outside a project, the target runs with
+  `--node-modules-dir=none --no-lock`.
 - `prompt()` and `confirm()` work over the stdin channel. Interrupt keeps
   state.
 
+## Editor types
+
+Cells run untyped, as in `deno jupyter`. Notebook code your editor
+type-checks can declare the globals.
+
+**Node notebooks.** The npm package ships the declarations. Add it as a dev
+dependency, then reference it once from a cell or a `.d.ts` in the project:
+
+```ts
+/// <reference types="@tlockney/cdp-kernel/globals" />
+await jupyter.display(jupyter.md`typed`);
+const name: string | null = prompt("Name?", "", { password: false });
+```
+
+That declares `jupyter`, `prompt` and `confirm`. With the `cdp-node-deno`
+kernel, use `@tlockney/cdp-kernel/globals/deno-compat` instead: it adds the
+`Deno` namespace the compatibility shim implements. A custom display is a
+class with a `[jupyter.$display]()` method returning a MIME bundle.
+`jupyter.$display` is `Symbol.for("Jupyter.display")` at runtime, but only
+`jupyter.$display` carries the precise type.
+
+**Deno notebooks.** Use `Deno.jupyter`, which Deno already types and which a
+Deno target provides. The JSR package doesn't ship these globals, because
+JSR doesn't allow packages to augment global types.
+
+## Widgets and comms
+
+`deno jupyter` has no comms. Here they're supported in both directions, so
+anywidget-style widgets work in frontends with the `anywidget` extension:
+JupyterLab, Notebook 7 and VS Code. Install it with
+`pip install anywidget`; that's the frontend half, no Python kernel needed.
+
+```ts
+const counter = jupyter.widget({
+  esm: `export default {
+    render({ model, el }) {
+      const btn = document.createElement("button");
+      const update = () => { btn.textContent = \`count is \${model.get("count")}\`; };
+      btn.onclick = () => { model.set("count", model.get("count") + 1); model.save_changes(); };
+      model.on("change:count", update);
+      update();
+      el.append(btn);
+    },
+  };`,
+  state: { count: 0 },
+});
+counter.on("change:count", (value) => console.log("clicked to", value));
+counter; // display it
+```
+
+The model API:
+
+- `get(key)`, and `set(key, value)` or `set({ ... })`, which syncs to every
+  view.
+- `on("change:key" | "change" | "msg:custom", listener)` and `off(...)`.
+- `send(content, buffers)` for custom messages.
+- `close()`.
+
+`Uint8Array`, `ArrayBuffer` and `DataView` values in the state travel as
+binary buffers. JupyterLab restores widget state after a page reload over
+the `jupyter.widget.control` comm.
+
+The comm layer underneath is available directly, for other comm-based
+protocols:
+
+```ts
+const comm = jupyter.comm.open("my.target", { hello: 1 });
+comm.onMsg(({ data, buffers }) => console.log(data, buffers.length));
+comm.send({ ping: true });
+jupyter.comm.registerTarget("echo", (comm) => comm.onMsg((m) => comm.send(m.data)));
+```
+
+Comm handlers run like cells. Their output goes to the notebook as replies
+to the message that triggered them, an exception is shown on stderr, and
+interrupt stops a stuck handler. Messages are processed one at a time with
+cell executions, as in ipykernel, so a widget event that arrives during a
+long cell waits for the cell to finish.
+
 ## How the tricky parts work
 
 | Problem | Approach |
@@ -115,6 +217,7 @@ In a cell:
 npm run check  # tsc --strict over src/ and test/
 npm test       # unit tests (node:test)
 npm run e2e    # conformance suite via jupyter_client/libzmq, on node, deno, node-deno
+npm run test:lab   # an anywidget counter in real JupyterLab, headless Chromium (node, deno)
 uv run --with nbclient --with nbformat python examples/run_notebook.py   # Deno-style notebook on deno + node-deno
 ```
 
@@ -137,15 +240,22 @@ The `publish` workflow then:
 1. Checks that the tag matches the version.
 2. Runs the type check, the unit tests, and the e2e suite against the packed
    npm tarball and against a Deno host.
-3. Publishes to JSR (`deno publish`, authenticated by GitHub OIDC).
+3. Publishes to JSR (`deno publish`).
 4. Publishes to npm (`npm publish`).
 
-Neither registry lets a version be republished, so a failed half needs a new
-patch version.
+Both registries authenticate the workflow through GitHub OIDC, so no tokens
+are stored:
+- **npm:** a trusted publisher for `tlockney/cdp-kernel` + `publish.yml`.
+- **JSR:** the package is linked to this repo in its JSR settings.
+
+Neither registry lets a version be republished. Each job skips a version
+its registry already has, so re-running a release only fills in the half
+that failed.
 
 ## Known gaps
 
-- No comms, so no ipywidgets. Deno has none either.
+- Widgets are anywidget-style (`jupyter.widget`). The classic ipywidgets
+  controls (sliders, dropdowns) are Python classes, so they're not available.
 - No `inspect_request` content and no history. Deno has neither.
 - No debugger.
 - `npm:` on Node:

package/dist/deno-config.d.ts

@@ -0,0 +1,20 @@
+import type { CellTransformOptions, JsxOptions } from "./transform.ts";
+export type { CellTransformOptions, JsxOptions };
+/** Deno looks for these, in this order, in each directory. */
+export declare const DENO_CONFIG_NAMES: readonly ["deno.json", "deno.jsonc"];
+/** The nearest deno.json(c) at or above `startDir`, as Deno resolves it. */
+export declare function findDenoConfig(startDir: string): string | null;
+/**
+ * Parses JSON with comments and trailing commas (deno.jsonc). Comments and
+ * trailing commas are removed outside strings, then the rest goes to
+ * JSON.parse, so errors are JSON.parse's SyntaxErrors.
+ */
+export declare function parseJsonc(text: string): unknown;
+/** Maps a deno.json's compilerOptions onto the cell transformer's options. */
+export declare function transformOptionsFromConfig(config: unknown): CellTransformOptions;
+export interface DenoProject {
+    configPath: string;
+    transform: CellTransformOptions;
+}
+/** The Deno project a notebook directory belongs to, if any. */
+export declare function loadDenoProject(notebookDir: string): DenoProject | null;

package/dist/deno-config.js

@@ -0,0 +1,130 @@
+// A notebook's Deno project config, for Deno targets.
+//
+// `deno jupyter` honours the project's deno.json: its import map,
+// nodeModulesDir and JSX/decorator compilerOptions. Here those come from two
+// places: the target runtime gets `--config <path>` (import map, npm
+// resolution), and the host's cell transformer gets the compiler options,
+// because cells are transpiled by esbuild in the host, not by Deno.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Deno looks for these, in this order, in each directory. */
+export const DENO_CONFIG_NAMES = ["deno.json", "deno.jsonc"];
+/** The nearest deno.json(c) at or above `startDir`, as Deno resolves it. */
+export function findDenoConfig(startDir) {
+    for (let dir = startDir;; dir = dirname(dir)) {
+        for (const name of DENO_CONFIG_NAMES) {
+            const candidate = join(dir, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+/**
+ * Parses JSON with comments and trailing commas (deno.jsonc). Comments and
+ * trailing commas are removed outside strings, then the rest goes to
+ * JSON.parse, so errors are JSON.parse's SyntaxErrors.
+ */
+export function parseJsonc(text) {
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"') {
+            const start = i++;
+            while (i < text.length && text[i] !== '"')
+                i += text[i] === "\\" ? 2 : 1;
+            out += text.slice(start, ++i);
+        }
+        else if (ch === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+        }
+        else if (ch === "/" && text[i + 1] === "*") {
+            const end = text.indexOf("*/", i + 2);
+            i = end === -1 ? text.length : end + 2;
+        }
+        else {
+            out += ch;
+            i++;
+        }
+    }
+    return JSON.parse(stripTrailingCommas(out));
+}
+/** Drops commas that only whitespace separates from a closing } or ]. */
+function stripTrailingCommas(json) {
+    // Walks strings intact for the same reason as above: a string can
+    // legitimately contain ",}".
+    let out = "";
+    for (let i = 0; i < json.length; i++) {
+        const ch = json[i];
+        if (ch === '"') {
+            const start = i++;
+            while (i < json.length && json[i] !== '"')
+                i += json[i] === "\\" ? 2 : 1;
+            out += json.slice(start, i + 1);
+            continue;
+        }
+        if (ch === ",") {
+            let j = i + 1;
+            while (j < json.length && /\s/.test(json[j]))
+                j++;
+            if (json[j] === "}" || json[j] === "]")
+                continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+function stringField(obj, key) {
+    const value = obj[key];
+    return typeof value === "string" ? value : undefined;
+}
+/** Maps a deno.json's compilerOptions onto the cell transformer's options. */
+export function transformOptionsFromConfig(config) {
+    if (typeof config !== "object" || config === null)
+        return {};
+    const compilerOptions = config.compilerOptions;
+    if (typeof compilerOptions !== "object" || compilerOptions === null)
+        return {};
+    const opts = compilerOptions;
+    const result = {};
+    const jsx = stringField(opts, "jsx");
+    if (jsx === "react-jsx" || jsx === "react-jsxdev" || jsx === "precompile") {
+        // precompile is Deno's server-side optimisation of the automatic
+        // runtime; for a notebook cell the automatic runtime is equivalent.
+        const importSource = stringField(opts, "jsxImportSource");
+        result.jsx = { mode: "automatic", development: jsx === "react-jsxdev" };
+        if (importSource !== undefined)
+            result.jsx.importSource = importSource;
+    }
+    else if (jsx === "react") {
+        const factory = stringField(opts, "jsxFactory");
+        const fragment = stringField(opts, "jsxFragmentFactory");
+        const classic = { mode: "classic" };
+        if (factory !== undefined)
+            classic.factory = factory;
+        if (fragment !== undefined)
+            classic.fragment = fragment;
+        result.jsx = classic;
+    }
+    if (opts.experimentalDecorators === true)
+        result.experimentalDecorators = true;
+    return result;
+}
+/** The Deno project a notebook directory belongs to, if any. */
+export function loadDenoProject(notebookDir) {
+    const configPath = findDenoConfig(notebookDir);
+    if (configPath === null)
+        return null;
+    let config;
+    try {
+        config = parseJsonc(readFileSync(configPath, "utf8"));
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`cannot read Deno config ${configPath}: ${reason}`);
+    }
+    return { configPath, transform: transformOptionsFromConfig(config) };
+}

package/dist/globals-deno-compat.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ambient `Deno` namespace for Node notebooks run with `--deno-compat`
+ * (kernelspec `cdp-node-deno`), on top of the `jupyter` globals.
+ *
+ * Opt-in and separate from `./globals` because on a real Deno target, or
+ * with Deno's own types loaded, `Deno` is already declared.
+ *
+ * @module
+ */
+import type { DenoShim } from "../runtime/deno-compat.mjs";
+import type { JupyterNamespace } from "./globals.ts";
+export type { DenoShim };
+declare global {
+    /**
+     * The subset of Deno's namespace the compatibility shim implements on Node.
+     * APIs outside it (`Deno.serve`, `Deno.Command`, ...) are absent at runtime.
+     */
+    var Deno: Omit<DenoShim, "jupyter"> & {
+        jupyter: JupyterNamespace;
+    };
+}

package/dist/globals-deno-compat.js

@@ -0,0 +1,10 @@
+/**
+ * Ambient `Deno` namespace for Node notebooks run with `--deno-compat`
+ * (kernelspec `cdp-node-deno`), on top of the `jupyter` globals.
+ *
+ * Opt-in and separate from `./globals` because on a real Deno target, or
+ * with Deno's own types loaded, `Deno` is already declared.
+ *
+ * @module
+ */
+export {};

package/dist/globals.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Ambient types for notebook cells run by cdp-kernel: the `jupyter` display
+ * namespace and the stdin-backed `prompt`/`confirm`.
+ *
+ * Load it once per project, for example
+ * `/// <reference types="@tlockney/cdp-kernel/globals" />` (npm) or
+ * `import type {} from "jsr:@tlockney/cdp-kernel/globals";` (Deno).
+ *
+ * A custom display is a class with a `[jupyter.$display]()` method returning
+ * a media bundle. At runtime that key is `Symbol.for("Jupyter.display")`, but
+ * only `jupyter.$display` carries the precise type.
+ *
+ * @module
+ */
+import type { Displayable, DisplayOptions, JupyterNamespace, MediaBundle } from "../runtime/display.mjs";
+export type { Displayable, DisplayOptions, JupyterNamespace, MediaBundle };
+/** Options for the notebook's `prompt()`. */
+export interface PromptOptions {
+    /** Ask the frontend to hide what is typed. */
+    password?: boolean;
+}
+declare global {
+    /**
+     * The notebook display API: `display`, `md`/`html`/`svg` templates,
+     * `image`, `format`, `broadcast`. The same object as `Deno.jupyter` in
+     * `deno jupyter`.
+     */
+    var jupyter: JupyterNamespace;
+    /**
+     * Ask the frontend for a line of input over the Jupyter stdin channel.
+     * Returns `null` when the frontend didn't allow input for this cell.
+     */
+    function prompt(message?: string, defaultValue?: string, options?: PromptOptions): string | null;
+    /** Ask a yes/no question over the Jupyter stdin channel. */
+    function confirm(message?: string): boolean;
+}

package/dist/globals.js

@@ -0,0 +1,15 @@
+/**
+ * Ambient types for notebook cells run by cdp-kernel: the `jupyter` display
+ * namespace and the stdin-backed `prompt`/`confirm`.
+ *
+ * Load it once per project, for example
+ * `/// <reference types="@tlockney/cdp-kernel/globals" />` (npm) or
+ * `import type {} from "jsr:@tlockney/cdp-kernel/globals";` (Deno).
+ *
+ * A custom display is a class with a `[jupyter.$display]()` method returning
+ * a media bundle. At runtime that key is `Symbol.for("Jupyter.display")`, but
+ * only `jupyter.$display` carries the precise type.
+ *
+ * @module
+ */
+export {};

package/dist/kernel.d.ts

@@ -14,7 +14,8 @@ export declare function parseConnectionInfo(json: string): ConnectionInfo;
 export declare class Kernel {
     #private;
     constructor(conn: ConnectionInfo, runtime: RuntimeName, options?: {
-        denoCompat?: boolean;
+        denoCompat?: boolean; /** Defaults to the process cwd, which Jupyter sets. */
+        notebookDir?: string;
     });
     run(): Promise<void>;
 }

package/dist/kernel.js

@@ -11,7 +11,9 @@ import { decodeMessage, encodeMessage, PROTOCOL_VERSION, verify } from "./wire.j
 import { PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
 import { Interrupted, Target } from "./target.js";
 import { CellSyntaxError, objectLiteralCandidate, transformCell } 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 +45,9 @@ export class Kernel {
     #conn;
     #runtime;
     #denoCompat;
+    // A Deno target in a Deno project uses its config (#13).
+    #project;
+    #projectWarning = null;
     #session = randomUUID();
     #shell;
     #control;
@@ -54,11 +59,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 +83,92 @@ 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 -----------------------------------------------------
     #ensureTarget() {
         if (this.#target)
             return Promise.resolve(this.#target);
-        this.#targetStarting ??= Target.launch(this.#runtime, this.#targetEvents(), { denoCompat: this.#denoCompat }).then((target) => {
+        this.#targetStarting ??= Target.launch(this.#runtime, this.#targetEvents(), {
+            denoCompat: this.#denoCompat,
+            denoConfig: this.#project?.configPath,
+        }).then((target) => {
             this.#target = target;
             this.#targetStarting = null;
             return target;
@@ -103,6 +192,7 @@ export class Kernel {
     }
     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 +246,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",
@@ -218,11 +308,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 +376,7 @@ export class Kernel {
         const wrapped = objectLiteralCandidate(code);
         if (wrapped !== null) {
             try {
-                const result = await target.evaluate(transformCell(wrapped));
+                const result = await target.evaluate(transformCell(wrapped, this.#transformOptions()));
                 if (!result.exceptionDetails)
                     return result;
             }
@@ -294,7 +385,7 @@ export class Kernel {
                     throw err;
             }
         }
-        return target.evaluate(transformCell(code));
+        return target.evaluate(transformCell(code, this.#transformOptions()));
     }
     async #execute(msg, peer) {
         const parent = msg.header;
@@ -307,6 +398,11 @@ 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 {

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.0";
-export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "display.mjs", "node-hooks.mjs", "deno-compat.mjs"];
+export declare const VERSION = "0.2.0";
+export declare const RUNTIME_FILES: readonly ["bootstrap.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>;