@tlockney/cdp-kernel 0.8.0 → 0.10.0

package/dist/kernel-core.js

@@ -160,6 +160,9 @@ export class KernelCore {
         // Transforms are synchronous, so the stripper loads before any cell.
         if (typeof this.#typeStrip === "string")
             await loadTypeStripper(this.#typeStrip);
+        // No shell or control reply until every port is bound: a client that
+        // has kernel_info_reply goes on to the heartbeat port (#438).
+        await this.#channels.ready;
         await Promise.all([this.#readShell(), this.#runShell(this.#mainShell),
             this.#loop("control", (m, p) => this.#handleControl(m, p)),
             this.#loop("stdin", (m) => this.#handleStdin(m))]);
@@ -322,6 +325,14 @@ export class KernelCore {
                 // Its prompt, if any, died with it; a late reply is dropped.
                 this.#input = null;
                 void this.#debugger?.attachTarget(null);
+                // Its comms died with it: tell the frontends, so a widget or a
+                // Ganymede host comm isn't left waiting on a runtime that is gone,
+                // and the next runtime can open its own (#461).
+                if (!this.#shuttingDown) {
+                    for (const commId of this.#comms.keys())
+                        this.#publish("comm_close", { comm_id: commId, data: {} });
+                }
+                this.#comms.clear();
                 if (!this.#shuttingDown) {
                     const text = note ?? `[cdp-kernel] ${this.#runtime} exited (${code}); restarting on next cell`;
                     this.#publish("stream", { name: "stderr", text: `\n${text}\n` });

package/dist/package.d.ts

@@ -1,11 +1,11 @@
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.10.0";
 /**
  * The UTC day this version was released, set with VERSION. The publish
  * workflow refuses a tag unless it's today or yesterday, so it can't go
  * stale: see dependencyCutoff.
  */
-export declare const RELEASE_DATE = "2026-11-06";
+export declare const RELEASE_DATE = "2026-11-11";
 /**
  * Deno blocks packages less than 24 hours old (minimum dependency age), so
  * a kernelspec relaunching a release from JSR would fail on release day. It
@@ -14,7 +14,7 @@ export declare const RELEASE_DATE = "2026-11-06";
  * late in the day its tag was pushed), and nothing newer ever is.
  */
 export declare function dependencyCutoff(releaseDate?: string): string;
-export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "bun-channel.mjs", "evaluator.mjs", "introspect.mjs", "workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "node-hooks.mjs", "deno-compat.mjs", "node-modules-resolve.mjs"];
+export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "bun-channel.mjs", "evaluator.mjs", "introspect.mjs", "workerd-worker.mjs", "display.mjs", "comm.mjs", "host.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. */

package/dist/package.js

@@ -14,13 +14,13 @@ 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.8.0";
+export const VERSION = "0.10.0";
 /**
  * The UTC day this version was released, set with VERSION. The publish
  * workflow refuses a tag unless it's today or yesterday, so it can't go
  * stale: see dependencyCutoff.
  */
-export const RELEASE_DATE = "2026-11-06";
+export const RELEASE_DATE = "2026-11-11";
 /**
  * Deno blocks packages less than 24 hours old (minimum dependency age), so
  * a kernelspec relaunching a release from JSR would fail on release day. It
@@ -43,6 +43,7 @@ export const RUNTIME_FILES = [
     "workerd-worker.mjs",
     "display.mjs",
     "comm.mjs",
+    "host.mjs",
     "widget.mjs",
     "node-hooks.mjs",
     "deno-compat.mjs",

package/dist/transform.d.ts

@@ -51,7 +51,16 @@ export declare function isTypeStripperName(value: unknown): value is TypeStrippe
  * imported (#238).
  */
 export declare function loadTypeStripper(name: TypeStripperName): Promise<TypeStripper>;
-/** Rewrites module-only syntax in plain JavaScript into script syntax. */
+/**
+ * Rewrites module-only syntax in plain JavaScript into script syntax.
+ *
+ * Top-level `const` becomes `let`, as do import bindings (#444). Under
+ * replMode a later evaluation may redeclare a top-level name only with the
+ * same kind of declaration: `const a` then `let a`, or `const a` then
+ * `import { a }`, fails with "already been declared" until a restart. With
+ * one kind, cells can be re-run and edited freely; the cost is that
+ * assigning to a top-level `const` from another cell doesn't throw.
+ */
 export declare function rewriteModuleSyntax(js: string): string;
 export declare function transformCell(code: string, options?: CellTransformOptions): string;
 /**

package/dist/transform.js

@@ -113,7 +113,9 @@ function rewriteImport(code, node, index) {
             return `${local} = ${ns}`;
         return `${local} = ${ns}[${JSON.stringify(importedName(spec))}]`;
     });
-    return `var ${ns} = ${load}; var ${bindings.join(", ")};`;
+    // `let`, like top-level `const` (see toLet): replMode lets a later
+    // cell redeclare a name only with the same kind of declaration.
+    return `var ${ns} = ${load}; let ${bindings.join(", ")};`;
 }
 function parseCell(js) {
     try {
@@ -128,10 +130,26 @@ function parseCell(js) {
         throw new CellSyntaxError(err instanceof Error ? err.message : String(err));
     }
 }
-/** Rewrites module-only syntax in plain JavaScript into script syntax. */
+/**
+ * Rewrites module-only syntax in plain JavaScript into script syntax.
+ *
+ * Top-level `const` becomes `let`, as do import bindings (#444). Under
+ * replMode a later evaluation may redeclare a top-level name only with the
+ * same kind of declaration: `const a` then `let a`, or `const a` then
+ * `import { a }`, fails with "already been declared" until a restart. With
+ * one kind, cells can be re-run and edited freely; the cost is that
+ * assigning to a top-level `const` from another cell doesn't throw.
+ */
 export function rewriteModuleSyntax(js) {
     const program = parseCell(js);
     const edits = [];
+    for (const statement of program.body) {
+        const decl = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+        if (decl?.type === "VariableDeclaration" && decl.kind === "const") {
+            // Padded to `const`'s length, so columns stay where the debugger expects them.
+            edits.push({ start: decl.start, end: decl.start + "const".length, text: "let  " });
+        }
+    }
     let importIndex = 0;
     full(program, (node) => {
         switch (node.type) {

package/dist/workerd-target.js

@@ -35,7 +35,7 @@ import { connectUnixWebSocket } from "./ws-client.js";
 import { findWranglerConfig, startMiniflare } from "./workers-project.js";
 import { ensureInstalledAsync, findLockFile, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
 /** The driver Worker's modules; the first is its main module. */
-export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "evaluator.mjs", "introspect.mjs"];
+export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "host.mjs", "widget.mjs", "evaluator.mjs", "introspect.mjs"];
 /** See BunTarget: how long an interrupted cell has to show it isn't busy. */
 export const INTERRUPT_GRACE_MS = 500;
 export function restartNote(runtime) {
@@ -71,6 +71,7 @@ const driver :Workerd.Worker = (
     (name = "UNSAFE", unsafeEval = void),
     (name = "TOKEN", fromEnvironment = "CDPK_TOKEN"),
     (name = "META", fromEnvironment = "CDPK_META"),
+    (name = "CDPK_PARAMS", fromEnvironment = "CDPK_PARAMS"),
   ],
 );
 `;
@@ -332,7 +333,10 @@ export class RawWorkerd {
             copyFileSync(join(source, name), join(dir, name));
         writeFileSync(join(dir, "config.capnp"), workerdConfig({ socket, compatibilityDate }));
         const token = randomBytes(32).toString("hex");
-        const env = { ...process.env, CDPK_TOKEN: token, CDPK_META: JSON.stringify(cellMeta(cwd)) };
+        const env = { ...process.env, CDPK_TOKEN: token, CDPK_META: JSON.stringify(cellMeta(cwd)),
+            // jupyter.params (#456); always set, so the binding exists.
+            CDPK_PARAMS: process.env.GANYMEDE_PARAMS ?? "",
+        };
         // --experimental: the UnsafeEval binding.
         const child = spawn(workerd, ["serve", "config.capnp", "--experimental"], { cwd: dir, stdio: ["ignore", "pipe", "pipe"], env });
         child.once("exit", () => rmSync(dir, { recursive: true, force: true }));

package/dist/workers-project.js

@@ -185,7 +185,7 @@ export async function startMiniflare(configPath, cwd, startTimeoutMs) {
         unsafeEvalBinding: "UNSAFE",
         compatibilityDate: date,
         compatibilityFlags: compatibilityFlagsFor(workerOptions.compatibilityFlags ?? []),
-        bindings: { ...workerOptions.bindings, TOKEN: token, META: JSON.stringify(cellMeta(cwd)) },
+        bindings: { ...workerOptions.bindings, TOKEN: token, META: JSON.stringify(cellMeta(cwd)), CDPK_PARAMS: process.env.GANYMEDE_PARAMS ?? "" },
         // Miniflare 5 renamed Miniflare 4's defaultPersistRoot.
         ...(v5 ? { resourcePersistencePath: state } : { defaultPersistRoot: state }),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on Node, Deno, Bun, workerd and celld",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
@@ -77,11 +77,11 @@
   "dependencies": {
     "acorn": "^8.15.0",
     "acorn-walk": "^8.3.4",
-    "esbuild": "^0.25.10",
+    "esbuild": "^0.28.2",
     "typescript": "^6.0.3"
   },
   "devDependencies": {
-    "@types/node": "^24.19.2",
+    "@types/node": "^26.6.6",
     "medium-zoom": "^1.1.0",
     "vitepress": "^1.6.4",
     "workerd": "1.20261015.1",

package/runtime/bootstrap.mjs

@@ -83,6 +83,8 @@ function send(payload) {
 
 const jupyter = createJupyter({
   inspect: (value) => inspect(value),
+  // jupyter.params (#456): the kernel's environment reaches the target.
+  params: () => (isDeno ? Deno.env.get("GANYMEDE_PARAMS") : process.env.GANYMEDE_PARAMS),
   base64,
   readFile,
   send(msgType, content, metadata, buffers) {

package/runtime/browser-worker.mjs

@@ -65,7 +65,10 @@ const jupyter = createJupyter({
   // A synchronous prompt would need SharedArrayBuffer and Atomics.wait, so
   // a cross-origin isolated page; until then, as with no stdin.
   input: () => null,
+  // jupyter.params (#456): the target's `params` option, sent with info.
+  params: () => paramsText,
 });
+let paramsText;
 
 // --- Modules ----------------------------------------------------------------
 let cdn = DEFAULT_CDN;
@@ -150,7 +153,8 @@ async function preload(urls, base) {
 // --- The shim cells and the evaluator use -----------------------------------
 let handle = null;
 
-function install({ base, cdn: cdnBase }) {
+function install({ base, cdn: cdnBase, params }) {
+  if (typeof params === "string") paramsText = params;
   if (typeof cdnBase === "string") cdn = cdnBase.endsWith("/") ? cdnBase : cdnBase + "/";
   const url = new URL("$cdpk$repl.mjs", base).href;
   globalThis.__cdpk = {

package/runtime/comm.d.mts

@@ -1,30 +1,116 @@
 /** A comm message as a handler receives it. */
 export interface CommMessage {
+  /** The message's JSON data. */
   data: { [key: string]: unknown };
+  /** The message's metadata. */
   metadata: { [key: string]: unknown };
+  /** Binary buffers sent with the message. */
   buffers: Uint8Array[];
 }
 
+/** Options for sending, opening or closing a comm. */
 export interface CommSendOptions {
+  /** Metadata for the message. Default `{}`. */
   metadata?: { [key: string]: unknown };
+  /** Binary buffers sent with the message. Default `[]`. */
   buffers?: Uint8Array[];
 }
 
-/** One end of a Jupyter comm channel. */
+/** One end of a Jupyter comm channel, from `jupyter.comm.open` or a target handler. */
 export interface Comm {
+  /** The comm id, shared with the frontend's end. */
   readonly id: string;
+  /** The target the comm was opened on. */
   readonly targetName: string;
+  /** Whether either end has closed the comm. */
   readonly closed: boolean;
+  /**
+   * Send a message to the frontend's end. Does nothing once closed.
+   *
+   * @param data The message's JSON data. Default `{}`.
+   * @param options Metadata and binary buffers.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target");
+   * comm.send({ ping: true }, { buffers: [new Uint8Array([1, 2, 3])] });
+   * ```
+   */
   send(data?: { [key: string]: unknown }, options?: CommSendOptions): void;
+  /**
+   * Close the comm and tell the frontend. Its `onClose` handlers start
+   * right away, without being awaited. Does nothing once closed.
+   *
+   * @param data Data sent with the close message. Default `{}`.
+   * @param options Metadata and binary buffers.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target");
+   * comm.close({ reason: "done" });
+   * ```
+   */
   close(data?: { [key: string]: unknown }, options?: CommSendOptions): void;
+  /**
+   * Handle messages from the frontend's end. A handler runs like a cell:
+   * its output goes to the notebook, and an exception shows on stderr.
+   *
+   * @param handler Called with each message; may be async.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target");
+   * comm.onMsg(({ data, buffers }) => console.log(data, buffers.length));
+   * ```
+   */
   onMsg(handler: (msg: CommMessage) => void | Promise<void>): void;
+  /**
+   * Handle the comm closing, from either end.
+   *
+   * @param handler Called with the close message; may be async.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target");
+   * comm.onClose(() => console.log("closed"));
+   * ```
+   */
   onClose(handler: (msg: CommMessage) => void | Promise<void>): void;
 }
 
 /** `jupyter.comm`: open comms, and accept comms the frontend opens. */
 export interface CommApi {
+  /**
+   * Open a comm to a target the frontend registered.
+   *
+   * @param targetName The frontend's target name.
+   * @param data Data sent with the open message. Default `{}`.
+   * @param options Metadata and binary buffers.
+   * @returns The kernel's end of the comm.
+   * @example
+   * ```ts
+   * const comm = jupyter.comm.open("my.target", { hello: 1 });
+   * comm.onMsg((m) => console.log(m.data));
+   * ```
+   */
   open(targetName: string, data?: { [key: string]: unknown }, options?: CommSendOptions): Comm;
+  /**
+   * Accept comms the frontend opens on `targetName`. Registering the same
+   * name again replaces the handler.
+   *
+   * @param targetName The target name the frontend opens comms on.
+   * @param handler Called with the new comm and its open message.
+   * @example
+   * ```ts
+   * jupyter.comm.registerTarget("echo", (comm) => comm.onMsg((m) => comm.send(m.data)));
+   * ```
+   */
   registerTarget(targetName: string, handler: (comm: Comm, msg: CommMessage) => void | Promise<void>): void;
+  /**
+   * Stop accepting new comms on `targetName`. Comms already open stay open.
+   *
+   * @param targetName The target to remove.
+   * @example
+   * ```ts
+   * jupyter.comm.unregisterTarget("echo");
+   * ```
+   */
   unregisterTarget(targetName: string): void;
 }