@tlockney/cdp-kernel 0.1.0 → 0.2.0

package/dist/package.js

@@ -8,14 +8,22 @@
 //     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.0";
-export const RUNTIME_FILES = ["bootstrap.mjs", "display.mjs", "node-hooks.mjs", "deno-compat.mjs"];
+export const VERSION = "0.2.0";
+export const RUNTIME_FILES = [
+    "bootstrap.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 +65,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,13 @@
 import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
 export type RuntimeName = "node" | "deno";
+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: RuntimeName, bootstrap: string, { executable, denoConfig }?: LaunchOptions): {
     cmd: string;
     args: string[];
 };
@@ -56,6 +62,7 @@ export declare class Target {
         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 +79,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 { 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,12 +30,16 @@ 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) {
     if (typeof value !== "object" || value === null)
@@ -182,11 +191,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");
@@ -320,6 +338,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]);

package/dist/transform.d.ts

@@ -2,9 +2,27 @@ export declare const SHIM = "__cdpk";
 export declare class CellSyntaxError extends Error {
     name: string;
 }
+export type JsxOptions = {
+    mode: "automatic";
+    importSource?: string;
+    development: boolean;
+} | {
+    mode: "classic";
+    factory?: string;
+    fragment?: string;
+};
+/**
+ * Compiler options for cells, e.g. from a Deno project's compilerOptions
+ * (see src/deno-config.ts). Without any, JSX compiles to classic
+ * React.createElement calls, Deno's own default.
+ */
+export interface CellTransformOptions {
+    jsx?: JsxOptions;
+    experimentalDecorators?: boolean;
+}
 /** Rewrites module-only syntax in plain JavaScript into script syntax. */
 export declare function rewriteModuleSyntax(js: string): string;
-export declare function transformCell(code: string): string;
+export declare function transformCell(code: string, options?: CellTransformOptions): string;
 /**
  * Deno treats a cell like `{ "a": 1 }` as an object literal rather than a
  * block, as browser consoles do. Returns the wrapped form to try first, or

package/dist/transform.js

@@ -27,7 +27,17 @@ const PRELUDE = `'use strict'; await ${SHIM}.tick();\n`;
 export class CellSyntaxError extends Error {
     name = "SyntaxError";
 }
-function stripTypes(code) {
+function jsxSettings(jsx) {
+    if (jsx?.mode === "automatic") {
+        return { jsx: "automatic", jsxImportSource: jsx.importSource, jsxDev: jsx.development };
+    }
+    return { jsx: "transform", jsxFactory: jsx?.factory, jsxFragment: jsx?.fragment };
+}
+function stripTypes(code, options) {
+    const compilerOptions = {
+        verbatimModuleSyntax: true,
+        ...(options.experimentalDecorators ? { experimentalDecorators: true } : {}),
+    };
     // Like Deno: prefer TSX, fall back to TS for `<T>x` assertions.
     let firstError;
     for (const loader of ["tsx", "ts"]) {
@@ -35,8 +45,8 @@ function stripTypes(code) {
             return transformSync(code, {
                 loader,
                 target: "esnext",
-                jsx: "transform",
-                tsconfigRaw: { compilerOptions: { verbatimModuleSyntax: true } },
+                ...jsxSettings(options.jsx),
+                tsconfigRaw: { compilerOptions },
                 logLevel: "silent",
             }).code;
         }
@@ -132,8 +142,8 @@ export function rewriteModuleSyntax(js) {
         out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
     return out;
 }
-export function transformCell(code) {
-    return PRELUDE + rewriteModuleSyntax(stripTypes(code));
+export function transformCell(code, options = {}) {
+    return PRELUDE + rewriteModuleSyntax(stripTypes(code, options));
 }
 /**
  * Deno treats a cell like `{ "a": 1 }` as an object literal rather than a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.1.0",
+  "version": "0.2.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>",
@@ -20,6 +20,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": [
@@ -38,7 +46,8 @@
     "install:node-deno": "node src/main.ts install --runtime node --deno-compat",
     "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",

package/runtime/bootstrap.mjs

@@ -8,13 +8,18 @@
 // Plain JavaScript on purpose: the same file must load unmodified in Node
 // and in Deno.
 
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJupyter } from "./display.mjs";
 
 const isDeno = typeof globalThis.Deno?.version?.deno === "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);
 
@@ -79,20 +84,51 @@ if (!isDeno) {
   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);
+  }
+}
+
 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) : 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 ?? "" });

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;

package/runtime/display.mjs

@@ -1,3 +1,4 @@
+// @ts-self-types="./display.d.mts"
 // The Jupyter display API that Deno exposes as `Deno.jupyter`, made
 // runtime-neutral. Runs inside the target runtime (Node or Deno).
 //
@@ -10,7 +11,11 @@
 //   Deno.readFileSync               -> host.readFile
 //   op_jupyter_broadcast            -> host.send
 // WebGPU texture/buffer display depends on Deno's wgpu bindings and is
-// omitted.
+// omitted. Comms and widgets (jupyter.comm, jupyter.widget) are additions
+// Deno doesn't have; see comm.mjs and widget.mjs.
+
+import { createComms } from "./comm.mjs";
+import { createWidgetFactory } from "./widget.mjs";
 
 export const $display = Symbol.for("Jupyter.display");
 
@@ -219,6 +224,8 @@ export function createJupyter(host) {
     return answer === "" ? defaultValue : answer;
   }
 
+  const comms = createComms((msgType, content, metadata, buffers) => host.send(msgType, content, metadata, buffers));
+
   return {
     namespace: {
       broadcast,
@@ -229,9 +236,12 @@ export function createJupyter(host) {
       svg: taggedTemplate("image/svg+xml"),
       image,
       $display,
+      comm: comms.api,
+      widget: createWidgetFactory(comms.api, $display),
     },
     broadcastResult,
     confirm,
     prompt,
+    commDispatch: comms.dispatch,
   };
 }

package/runtime/node-modules-resolve.d.mts

@@ -0,0 +1,8 @@
+/** True for "pkg", "@scope/pkg", "pkg/sub"; false for paths, URLs and aliases like "@/x". */
+export function isBareSpecifier(specifier: string): boolean;
+
+/**
+ * An absolute file URL for a bare package import, resolved from the
+ * node_modules at or above `fromDir`, or null when none has the package.
+ */
+export function resolveFromNodeModules(specifier: string, fromDir: string): string | null;