@tlockney/cdp-kernel 0.11.0 → 0.12.0

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.11.0";
+export declare const VERSION = "0.12.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-13";
+export declare const RELEASE_DATE = "2026-11-14";
 /**
  * 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-13";
  * 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", "host.mjs", "widget.mjs", "table.mjs", "sql.mjs", "chart.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", "table.mjs", "table-paging.mjs", "sql.mjs", "chart.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.11.0";
+export const VERSION = "0.12.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-13";
+export const RELEASE_DATE = "2026-11-14";
 /**
  * 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
@@ -46,6 +46,7 @@ export const RUNTIME_FILES = [
     "host.mjs",
     "widget.mjs",
     "table.mjs",
+    "table-paging.mjs",
     "sql.mjs",
     "chart.mjs",
     "node-hooks.mjs",

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", "host.mjs", "widget.mjs", "table.mjs", "sql.mjs", "chart.mjs", "evaluator.mjs", "introspect.mjs"];
+export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "host.mjs", "widget.mjs", "table.mjs", "table-paging.mjs", "sql.mjs", "chart.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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.11.0",
+  "version": "0.12.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/browser-worker.mjs

@@ -72,6 +72,8 @@ let paramsText;
 
 // --- Modules ----------------------------------------------------------------
 let cdn = DEFAULT_CDN;
+/** Specifiers the page serves itself, such as jupyter.chart's libraries in the Ganymede apps. */
+let modules;
 
 
 // --- The host page (#384) -----------------------------------------------------
@@ -153,13 +155,14 @@ async function preload(urls, base) {
 // --- The shim cells and the evaluator use -----------------------------------
 let handle = null;
 
-function install({ base, cdn: cdnBase, params }) {
+function install({ base, cdn: cdnBase, modules: moduleMap, params }) {
   if (typeof params === "string") paramsText = params;
   if (typeof cdnBase === "string") cdn = cdnBase.endsWith("/") ? cdnBase : cdnBase + "/";
+  if (moduleMap !== null && typeof moduleMap === "object") modules = { ...moduleMap };
   const url = new URL("$cdpk$repl.mjs", base).href;
   globalThis.__cdpk = {
-    import: (specifier, options) => import(resolveSpecifier(specifier, url, cdn), options),
-    meta: { url, resolve: (specifier) => resolveSpecifier(specifier, url, cdn) },
+    import: (specifier, options) => import(resolveSpecifier(specifier, url, cdn, modules), options),
+    meta: { url, resolve: (specifier) => resolveSpecifier(specifier, url, cdn, modules) },
     // inspect_request (#10): by descriptor, so nothing runs.
     describeForInspect: (value, detail) => describeValue(value, { inspect: (v) => inspect(v, { depth: 2 }), detail }),
     inspectPath: (path, detail) => inspectPath(path, { inspect: (v) => inspect(v, { depth: 2 }), detail }),

package/runtime/cdn.d.mts

@@ -1,2 +1,7 @@
 export const DEFAULT_CDN: string;
-export function resolveSpecifier(specifier: string, base: string, cdn?: string): string;
+export function resolveSpecifier(
+  specifier: string,
+  base: string,
+  cdn?: string,
+  modules?: { readonly [specifier: string]: string },
+): string;

package/runtime/cdn.mjs

@@ -6,8 +6,13 @@
 
 export const DEFAULT_CDN = "https://esm.sh/";
 
-/** The URL `specifier`, imported from `base`, loads from. */
-export function resolveSpecifier(specifier, base, cdn = DEFAULT_CDN) {
+/**
+ * The URL `specifier`, imported from `base`, loads from. `modules` maps
+ * specifiers, as written, to URLs (resolved against `base`) that win over
+ * the CDN: an app ships the packages it needs offline this way.
+ */
+export function resolveSpecifier(specifier, base, cdn = DEFAULT_CDN, modules = undefined) {
+  if (modules && Object.hasOwn(modules, specifier)) return new URL(modules[specifier], base).href;
   if (/^(?:https?|data|blob):/.test(specifier)) return specifier;
   if (/^\.{0,2}\//.test(specifier)) return new URL(specifier, base).href;
   if (specifier.startsWith("npm:")) return cdn + specifier.slice(4);

package/runtime/display.d.mts

@@ -83,33 +83,6 @@ export interface Displayable {
  * 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
@@ -142,22 +115,6 @@ export interface JupyterNamespace {
    * @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.
@@ -250,109 +207,48 @@ export interface JupyterNamespace {
    */
   $display: typeof $display;
   /**
-   * 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;
-  /**
-   * 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;
-  /**
-   * 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;
-  /**
-   * The parameters of this run: a frozen object, empty unless whoever
-   * started the kernel passed some, such as `ganymede execute -p
-   * counter="2nd Ave"`. They arrive as a JSON object in the kernel's
-   * `GANYMEDE_PARAMS` environment variable. Take defaults with
-   * destructuring, so the notebook also runs on its own.
+   * 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.
    *
-   * @throws {TypeError} `GANYMEDE_PARAMS` is set but isn't a JSON object.
-   * @availability Node, Deno, Bun, workerd and celld read the kernel's
-   *   environment; the browser target takes `params` from its options.
+   * @param obj The value to format.
+   * @returns The bundle, for example `{ "text/plain": "\x1b[33m42\x1b[39m" }`
+   *   for `42`.
    * @example
    * ```ts
-   * const { counter = "Fremont", days = 30 } = jupyter.params as { counter?: string; days?: number };
-   * `${counter}, last ${days} days`;
+   * const bundle = await jupyter.format(jupyter.md`# Weekly report`);
+   * bundle["text/markdown"]; // "# Weekly report"
    * ```
-   * @see jupyter-api.md#parameters-and-named-results
+   * @see jupyter-api.md#getting-a-bundle-with-format
    */
-  readonly params: { readonly [name: string]: JsonValue };
+  format(obj: unknown): Promise<MediaBundle>;
   /**
-   * Publish a value under a name, as an output that a run's caller reads
-   * by name instead of parsing outputs: `ganymede execute --results`, or
-   * another notebook. The output has the MIME type
-   * `application/vnd.ganymede.result+json` holding `{ name, value }`, and
-   * a `text/plain` line `name = value` for frontends that don't know the
-   * type. When a name is published twice, readers take the last one.
+   * 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 name The result's name.
-   * @param value Any value `JSON.stringify` accepts; it is stored as JSON,
-   *   so a `Date` becomes its ISO string.
-   * @throws {TypeError} `name` is empty, or `value` isn't JSON (a
-   *   function, `undefined`, a `BigInt` or a cycle).
+   * @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
-   * const counts = [3120, 2890, 2410];
-   * jupyter.result("weekday_drop", (counts[2] - counts[0]) / counts[0]);
-   * jupyter.result("counts", counts);
+   * // 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#parameters-and-named-results
+   * @see jupyter-api.md#raw-messages-with-broadcast
    */
-  result(name: string, value: unknown): void;
+  broadcast(
+    msgType: string,
+    content: object,
+    options?: { metadata?: object; buffers?: Uint8Array[] },
+  ): void;
   /**
    * Show rows and columns as a table. The output has Ganymede's table
    * type, `application/vnd.dataresource+json` (Table Schema fields, up to
@@ -456,6 +352,111 @@ export interface JupyterNamespace {
    * @see jupyter-api.md#charts
    */
   chart(chart: object, options?: ChartOptions | Record<string, unknown>): Displayable;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * Create an [anywidget](https://anywidget.dev)-compatible [widget
+   * model](widgets-reference.md#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](https://anywidget.dev) 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;
+  /**
+   * The parameters of this run: a frozen object, empty unless whoever
+   * started the kernel passed some, such as `ganymede execute -p
+   * counter="2nd Ave"`. They arrive as a JSON object in the kernel's
+   * `GANYMEDE_PARAMS` environment variable. Take defaults with
+   * destructuring, so the notebook also runs on its own.
+   *
+   * @throws {TypeError} `GANYMEDE_PARAMS` is set but isn't a JSON object.
+   * @availability Node, Deno, Bun, workerd and celld read the kernel's
+   *   environment; the browser target takes `params` from its options.
+   * @example
+   * ```ts
+   * const { counter = "Fremont", days = 30 } = jupyter.params as { counter?: string; days?: number };
+   * `${counter}, last ${days} days`;
+   * ```
+   * @see jupyter-api.md#parameters-and-named-results
+   */
+  readonly params: { readonly [name: string]: JsonValue };
+  /**
+   * Publish a value under a name, as an output that a run's caller reads
+   * by name instead of parsing outputs: `ganymede execute --results`, or
+   * another notebook. The output has the MIME type
+   * `application/vnd.ganymede.result+json` holding `{ name, value }`, and
+   * a `text/plain` line `name = value` for frontends that don't know the
+   * type. When a name is published twice, readers take the last one.
+   *
+   * @param name The result's name.
+   * @param value Any value `JSON.stringify` accepts; it is stored as JSON,
+   *   so a `Date` becomes its ISO string.
+   * @throws {TypeError} `name` is empty, or `value` isn't JSON (a
+   *   function, `undefined`, a `BigInt` or a cycle).
+   * @example
+   * ```ts
+   * const counts = [3120, 2890, 2410];
+   * jupyter.result("weekday_drop", (counts[2] - counts[0]) / counts[0]);
+   * jupyter.result("counts", counts);
+   * ```
+   * @see jupyter-api.md#parameters-and-named-results
+   */
+  result(name: string, value: unknown): void;
   /**
    * The Ganymede server running this kernel, through its host API: read,
    * search and (when granted) run other notebooks under its root. The

package/runtime/display.mjs

@@ -23,7 +23,8 @@ import { createHost } from "./host.mjs";
 import { createWidgetFactory } from "./widget.mjs";
 import { createSql } from "./sql.mjs";
 import { createChart } from "./chart.mjs";
-import { isTableLike, tableBundle, tableSource } from "./table.mjs";
+import { isTableLike, pageTable, tableBundle, tableSource } from "./table.mjs";
+import { createTablePager } from "./table-paging.mjs";
 
 export const $display = Symbol.for("Jupyter.display");
 
@@ -368,10 +369,14 @@ export function createJupyter(host) {
     host.send(msgType, content, metadata, buffers);
   }
 
+  // Set below, once the comms are: a table cut by the cap is kept for
+  // paging when it is sent as an output, not when it is formatted.
+  let pager;
+
   async function display(obj, options = { raw: false, update: false }) {
     const bundle = options.raw && isMediaBundle(obj) ? obj : await format(obj);
     broadcast(options.update ? "update_display_data" : "display_data", {
-      data: bundle,
+      data: pageTable(bundle, pager, options.display_id),
       metadata: {},
       transient: options.display_id ? { display_id: options.display_id } : {},
     });
@@ -382,7 +387,7 @@ export function createJupyter(host) {
     try {
       broadcast("execute_result", {
         execution_count: executionCount,
-        data: await format(result),
+        data: pageTable(await format(result), pager),
         metadata: {},
         // nbclient crashes on a null `transient`; Deno learned this too.
         transient: {},
@@ -463,6 +468,8 @@ export function createJupyter(host) {
   const chart = createChart({ importModule: cellImport("jupyter.chart"), summarizeSpec: summarizeChart });
 
   const comms = createComms((msgType, content, metadata, buffers) => host.send(msgType, content, metadata, buffers));
+  // Tables cut by the cap page through the kernel over a comm (ganymede#747).
+  pager = createTablePager(comms.api);
 
   // jupyter.signal (#418): aborted when the kernel is interrupted, so cell
   // code can stop waiting on what the interrupt can't reach, such as a comm

package/runtime/table-paging.d.mts

@@ -0,0 +1,19 @@
+import type { CommApi } from "./comm.d.mts";
+import type { TablePager } from "./table.d.mts";
+
+/** The comm target a frontend opens, with `{ id }`, to page through a table. */
+export const PAGE_TARGET: "ganymede.table.v1";
+/** How many tables the kernel keeps for paging, the newest. */
+export const KEEP: number;
+/** The most rows one request returns. */
+export const MAX_PAGE: number;
+/** The most rows a table can have to be sorted in the kernel. */
+export const MAX_SORT: number;
+
+/** Compares two encoded values of a column as the Ganymede apps' table does. */
+export function compareEncoded(a: unknown, b: unknown, type: string | undefined, descending?: boolean): number;
+
+export function createTablePager(
+  commApi: CommApi,
+  options?: { keep?: number; newId?: () => string },
+): TablePager & { size(): number };