@tlockney/cdp-kernel 0.8.0 → 0.9.0

package/dist/globals.d.ts

@@ -16,7 +16,7 @@ import type { Displayable, DisplayOptions, JupyterNamespace, MediaBundle } from
 export type { Displayable, DisplayOptions, JupyterNamespace, MediaBundle };
 /** Options for the notebook's `prompt()`. */
 export interface PromptOptions {
-    /** Ask the frontend to hide what is typed. */
+    /** Ask the frontend to hide what is typed, for secrets. Default `false`. */
     password?: boolean;
 }
 declare global {
@@ -27,10 +27,41 @@ declare global {
      */
     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.
+     * Ask for a line of input in the notebook: the frontend shows an input
+     * box under the cell, and the cell waits for the answer.
+     *
+     * @param message The question. Default `"Prompt"`. A non-empty
+     *   `defaultValue` is shown after it, as `message [default]`.
+     * @param defaultValue Returned when the answer is empty. Default `""`.
+     * @param options `password: true` hides what is typed.
+     * @returns The typed text, `defaultValue` for an empty answer, or `null`
+     *   when nothing can answer (the frontend allows no input, as in
+     *   `nbconvert --execute`).
+     * @availability On workerd and celld it always returns `null`.
+     * @example
+     * ```ts
+     * const name = prompt("What's your name?", "world");
+     * `Hello, ${name}!`;
+     * ```
+     * @example
+     * ```ts
+     * const apiKey = prompt("API key", "", { password: true });
+     * ```
+     * @see jupyter-api.md#asking-for-input-prompt-and-confirm
      */
     function prompt(message?: string, defaultValue?: string, options?: PromptOptions): string | null;
-    /** Ask a yes/no question over the Jupyter stdin channel. */
+    /**
+     * Ask a yes/no question in the notebook. `[y/N]` is added to the message.
+     *
+     * @param message The question. Default `"Confirm"`.
+     * @returns `true` only for `y` or `Y`; `false` otherwise, and when
+     *   nothing can answer.
+     * @availability On workerd and celld it always returns `false`.
+     * @example
+     * ```ts
+     * if (confirm("Delete the cache?")) console.log("deleting");
+     * ```
+     * @see jupyter-api.md#asking-for-input-prompt-and-confirm
+     */
     function confirm(message?: string): boolean;
 }

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))]);

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.9.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-09";
 /**
  * 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

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.9.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-09";
 /**
  * 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.8.0",
+  "version": "0.9.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>",

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;
 }
 

package/runtime/display.d.mts

@@ -3,8 +3,18 @@ import type { Widget, WidgetOptions } from "./widget.d.mts";
 
 export type { CommApi, Widget, WidgetOptions };
 
+/**
+ * The symbol a class implements to choose how its instances appear. At
+ * runtime it is `Symbol.for("Jupyter.display")`, so a library can use that
+ * form without the `jupyter` global.
+ */
 export const $display: unique symbol;
 
+/**
+ * A Jupyter MIME bundle: media type to content, such as
+ * `{ "text/plain": "42", "text/html": "<b>42</b>" }`. Binary images are
+ * base64 strings; JSON types (`application/json`, Vega-Lite) are objects.
+ */
 export type MediaBundle = { [mediaType: string]: unknown };
 
 export interface DisplayHost {
@@ -15,37 +25,262 @@ export interface DisplayHost {
   input: (prompt: string, password: boolean) => string | null;
 }
 
+/** Options for `jupyter.display`. */
 export interface DisplayOptions {
+  /**
+   * Send a plain object as the MIME bundle itself instead of formatting
+   * it. Default `false`.
+   */
   raw?: boolean;
+  /**
+   * Replace every earlier output that has the same `display_id`, including
+   * one shown by an earlier cell, instead of adding an output. Needs
+   * `display_id`. Default `false`.
+   */
   update?: boolean;
+  /** An id that a later display with `update: true` can replace. */
   display_id?: string;
 }
 
+/** A value that renders as rich output: it has a `[jupyter.$display]` method. */
 export interface Displayable {
+  /** Returns the value's MIME bundle, or a promise of one. */
   [$display]: () => MediaBundle | Promise<MediaBundle>;
 }
 
+/**
+ * The `jupyter` global: how values appear in the notebook. The same object
+ * as `Deno.jupyter` in `deno jupyter`.
+ */
 export interface JupyterNamespace {
+  /**
+   * Send a raw Jupyter message on the kernel's output channel (IOPub), as a
+   * reply to the running cell. The other helpers are built on it. It does
+   * not check the message: a wrong field is ignored or mishandled by the
+   * frontend.
+   *
+   * @param msgType An IOPub message type, such as `"clear_output"` or
+   *   `"display_data"`.
+   * @param content The message content, as the messaging spec defines it
+   *   for `msgType`.
+   * @param options `metadata` for the message, and binary `buffers`.
+   * @example
+   * ```ts
+   * // Count down in place: clear_output with wait avoids a flicker.
+   * for (const n of [3, 2, 1]) {
+   *   jupyter.broadcast("clear_output", { wait: true });
+   *   await jupyter.display(jupyter.md`Launching in **${n}**…`);
+   *   await new Promise((resolve) => setTimeout(resolve, 1000));
+   * }
+   * ```
+   * @see jupyter-api.md#raw-messages-with-broadcast
+   */
   broadcast(
     msgType: string,
     content: object,
     options?: { metadata?: object; buffers?: Uint8Array[] },
   ): void;
+  /**
+   * Show a value now, in the middle of a cell, or replace one shown
+   * earlier. The value can be anything a cell could end with: a template
+   * from `md`, `html` or `svg`, an image, a widget, an object with a
+   * `[jupyter.$display]` method, or a plain value, shown as text.
+   *
+   * @param obj The value to show.
+   * @param options `display_id` and `update` to replace an earlier output;
+   *   `raw` to send a plain object as the MIME bundle itself.
+   * @returns Resolves once the output is sent. Without `await` the output
+   *   still appears, but later output in the cell can appear before it.
+   * @example
+   * ```ts
+   * const bar = (pct: number) => jupyter.html`<progress value="${pct}" max="100"></progress>`;
+   * await jupyter.display(bar(0), { display_id: "download" });
+   * for (let pct = 25; pct <= 100; pct += 25) {
+   *   await new Promise((resolve) => setTimeout(resolve, 500));
+   *   await jupyter.display(bar(pct), { display_id: "download", update: true });
+   * }
+   * ```
+   * @example
+   * ```ts
+   * // A MIME bundle sent as is: JupyterLab renders it as a JSON tree.
+   * const user = { name: "Ada", active: true };
+   * await jupyter.display(
+   *   { "application/json": user, "text/plain": JSON.stringify(user) },
+   *   { raw: true },
+   * );
+   * ```
+   * @see jupyter-api.md#showing-output-with-display
+   */
   display(obj: unknown, options?: DisplayOptions): Promise<void>;
+  /**
+   * The MIME bundle that displaying a value would send, without showing
+   * anything. For plain values `text/plain` holds terminal color codes,
+   * as the notebook shows them.
+   *
+   * @param obj The value to format.
+   * @returns The bundle, for example `{ "text/plain": "\x1b[33m42\x1b[39m" }`
+   *   for `42`.
+   * @example
+   * ```ts
+   * const bundle = await jupyter.format(jupyter.md`# Weekly report`);
+   * bundle["text/markdown"]; // "# Weekly report"
+   * ```
+   * @see jupyter-api.md#getting-a-bundle-with-format
+   */
   format(obj: unknown): Promise<MediaBundle>;
+  /**
+   * A tagged template that renders as Markdown. Interpolated values are
+   * inserted as is, without escaping.
+   *
+   * @returns A value that shows as `text/markdown` as a cell's result or
+   *   through `display`.
+   * @example
+   * ```ts
+   * const scores = { Ada: 92, Grace: 88 };
+   * const rows = Object.entries(scores).map(([n, s]) => `| ${n} | ${s} |`).join("\n");
+   * jupyter.md`| Name | Score |
+   * | --- | --- |
+   * ${rows}`;
+   * ```
+   * @see jupyter-api.md#markdown
+   */
   md(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  /**
+   * A tagged template that renders as HTML. Interpolated values are
+   * inserted as is, without escaping: escape text from users, files or
+   * the network yourself.
+   *
+   * @returns A value that shows as `text/html`.
+   * @example
+   * ```ts
+   * const escape = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+   * const comment = "<script>alert(1)</script>";
+   * jupyter.html`<p>${escape(comment)}</p>`;
+   * ```
+   * @see jupyter-api.md#html
+   */
   html(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  /**
+   * A tagged template that renders as SVG. Include the `xmlns` attribute.
+   * Interpolated values are inserted as is, without escaping.
+   *
+   * @returns A value that shows as `image/svg+xml`.
+   * @example
+   * ```ts
+   * const data = [4, 8, 15, 16];
+   * const bars = data.map((v, i) => `<rect x="${i * 20}" y="${40 - v * 2}" width="16" height="${v * 2}"/>`).join("");
+   * jupyter.svg`<svg xmlns="http://www.w3.org/2000/svg" width="80" height="40">${bars}</svg>`;
+   * ```
+   * @see jupyter-api.md#svg
+   */
   svg(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  /**
+   * Show a PNG or JPEG. The format is read from the bytes, not the file
+   * name.
+   *
+   * @param obj A file path, relative to the notebook's directory, or the
+   *   image's bytes.
+   * @returns A value that shows as `image/png` or `image/jpeg`.
+   * @throws {TypeError} The bytes are not PNG or JPEG, or the path can't
+   *   be read.
+   * @availability Paths need a file system: on workerd and celld pass
+   *   bytes.
+   * @example
+   * ```ts
+   * jupyter.image("./chart.png");
+   * ```
+   * @example
+   * ```ts
+   * const response = await fetch("https://www.python.org/static/img/python-logo.png");
+   * jupyter.image(new Uint8Array(await response.arrayBuffer()));
+   * ```
+   * @see jupyter-api.md#images
+   */
   image(obj: string | Uint8Array): Displayable;
+  /**
+   * The symbol a class implements to choose how its instances appear. The
+   * method returns a MIME bundle, or a promise of one. It is used for a
+   * cell's result, `display` and `format`, but not for objects nested in
+   * other values. At runtime it is `Symbol.for("Jupyter.display")`.
+   *
+   * @example
+   * ```ts
+   * class Temperature {
+   *   celsius: number;
+   *   constructor(celsius: number) {
+   *     this.celsius = celsius;
+   *   }
+   *   [jupyter.$display]() {
+   *     return { "text/plain": `${this.celsius}°C`, "text/html": `<b>${this.celsius}°C</b>` };
+   *   }
+   * }
+   * new Temperature(21);
+   * ```
+   * @see jupyter-api.md#custom-display-for-your-own-classes
+   */
   $display: typeof $display;
-  /** Jupyter comms: bidirectional channels to the frontend. */
+  /**
+   * Jupyter comms: message channels to the frontend outside cell
+   * execution. Its methods are in the widgets and comms reference.
+   *
+   * @see widgets.md#comms
+   */
   comm: CommApi;
-  /** An anywidget-compatible widget; display the result to show it. */
+  /**
+   * Create an anywidget-compatible widget model. Display it (or end the
+   * cell with it) to show a view.
+   *
+   * @param options The view module, its CSS, and the initial state.
+   * @returns The model, synced with every view of it.
+   * @throws {TypeError} `options.esm` is not a string.
+   * @availability The frontend needs the anywidget extension.
+   * @example
+   * ```ts
+   * const counter = jupyter.widget({
+   *   esm: `export default {
+   *     render({ model, el }) {
+   *       const button = document.createElement("button");
+   *       const update = () => {
+   *         button.textContent = "count is " + model.get("count");
+   *       };
+   *       button.onclick = () => {
+   *         model.set("count", model.get("count") + 1);
+   *         model.save_changes();
+   *       };
+   *       model.on("change:count", update);
+   *       update();
+   *       el.append(button);
+   *     },
+   *   };`,
+   *   state: { count: 0 },
+   * });
+   * counter; // the cell's result: displays the widget
+   * ```
+   * ![A JupyterLab cell that creates a counter widget with jupyter.widget. Below the code, the output is a button reading "count is 3" after three clicks.](https://cdp-kernel.org/images/widgets/counter.png)
+   * @see widgets.md#a-first-widget-a-counter
+   */
   widget(options: WidgetOptions): Widget;
   /**
-   * Aborted when the kernel interrupts this cell. Each cell gets its own,
-   * as does a comm handler that starts while no cell runs. Read it when
-   * the work starts: a later read gets the signal of whatever started last.
+   * An `AbortSignal` that an interrupt aborts, so code waiting on something
+   * only it can end can stop and clean up. Each cell gets its own, as does
+   * a comm handler that starts while no cell runs. Read it once when the
+   * work starts: a later read gets the signal of whatever started last.
+   * The abort reason is a `DOMException` named `AbortError`.
+   *
+   * @example
+   * ```ts
+   * const response = await fetch("https://example.com/large.csv", { signal: jupyter.signal });
+   * ```
+   * @example
+   * ```ts
+   * const signal = jupyter.signal;
+   * const ask = jupyter.comm.open("my.app", { question: "ready?" });
+   * const answer = await new Promise((resolve, reject) => {
+   *   ask.onMsg((m) => resolve(m.data));
+   *   signal.addEventListener("abort", () => { ask.close(); reject(signal.reason); }, { once: true });
+   * });
+   * ```
+   * @see jupyter-api.md#stopping-on-interrupt-jupyter-signal
    */
   readonly signal: AbortSignal;
 }