@tlockney/cdp-kernel 0.11.0 → 0.12.1

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.1";
 /**
  * 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.1";
 /**
  * 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.1",
   "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,17 @@ 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) },
+    // The URL `modules` maps a specifier to, or null: jupyter.sql's DuckDB
+    // files load from the page this way.
+    mapped: (specifier) => (modules && Object.hasOwn(modules, specifier) ? new URL(modules[specifier], url).href : null),
     // 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: {},
@@ -457,12 +462,18 @@ export function createJupyter(host) {
 
   // jupyter.sql (#477): DuckDB, loaded on the first query; an interrupt
   // (jupyter.signal) interrupts the query.
-  const sql = createSql({ importModule: cellImport("jupyter.sql"), signal: () => current.signal });
+  const sql = createSql({
+    importModule: cellImport("jupyter.sql"),
+    mapped: (specifier) => globalThis.__cdpk?.mapped?.(specifier) ?? null,
+    signal: () => current.signal,
+  });
 
   // jupyter.chart (#479): vega, vega-lite or linkedom, loaded on first use.
   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/sql.d.mts

@@ -2,6 +2,19 @@ import type { Displayable } from "./display.d.mts";
 
 export const NODE_API: string;
 export const DUCKDB_WASM: string;
+export interface DuckDBBundle {
+  mainModule: string;
+  mainWorker: string;
+  pthreadWorker?: string | null;
+}
+export const DUCKDB_FILES: {
+  readonly mvp: { readonly mainModule: string; readonly mainWorker: string };
+  readonly eh: { readonly mainModule: string; readonly mainWorker: string };
+};
+export function duckdbBundles(
+  jsDelivr: Record<string, DuckDBBundle>,
+  mapped?: (specifier: string) => string | null | undefined,
+): Record<string, DuckDBBundle>;
 
 /** One column of a query's result. */
 export interface SqlColumn {
@@ -142,6 +155,7 @@ export interface SqlEngine {
 
 export function createSql(options: {
   importModule: (specifier: string) => Promise<any>;
+  mapped?: (specifier: string) => string | null | undefined;
   signal?: () => AbortSignal | undefined;
   openEngine?: () => Promise<SqlEngine>;
 }): Sql;

package/runtime/sql.mjs

@@ -21,6 +21,35 @@ export { timeText, uniqueNames };
 export const NODE_API = "npm:@duckdb/node-api@1.5.6-r.2";
 export const DUCKDB_WASM = "npm:@duckdb/duckdb-wasm@1.29.0";
 
+/**
+ * The files duckdb-wasm runs from besides its module, by the specifier a
+ * browser kernel's `modules` option maps to a URL the page serves. A
+ * variant whose wasm and worker are both mapped loads from those URLs;
+ * the others load from jsDelivr, as duckdb-wasm's own list has them.
+ */
+export const DUCKDB_FILES = {
+  mvp: { mainModule: `${DUCKDB_WASM}/dist/duckdb-mvp.wasm`, mainWorker: `${DUCKDB_WASM}/dist/duckdb-browser-mvp.worker.js` },
+  eh: { mainModule: `${DUCKDB_WASM}/dist/duckdb-eh.wasm`, mainWorker: `${DUCKDB_WASM}/dist/duckdb-browser-eh.worker.js` },
+};
+
+/**
+ * duckdb-wasm's bundles: jsDelivr's, with each variant `mapped` gives
+ * both files for in their place.
+ *
+ * @param {Record<string, { mainModule: string, mainWorker: string, pthreadWorker?: string | null }>} jsDelivr
+ * @param {(specifier: string) => string | null | undefined} [mapped]
+ */
+export function duckdbBundles(jsDelivr, mapped) {
+  const bundles = { ...jsDelivr };
+  if (!mapped) return bundles;
+  for (const [variant, files] of Object.entries(DUCKDB_FILES)) {
+    const mainModule = mapped(files.mainModule);
+    const mainWorker = mapped(files.mainWorker);
+    if (mainModule && mainWorker) bundles[variant] = { mainModule, mainWorker, pthreadWorker: null };
+  }
+  return bundles;
+}
+
 const $display = Symbol.for("Jupyter.display");
 const RAW = Symbol("cdpk.sql.raw");
 
@@ -190,6 +219,7 @@ const DUCK_TYPES = {
 /**
  * @param {{
  *   importModule: (specifier: string) => Promise<any>,
+ *   mapped?: (specifier: string) => string | null | undefined,
  *   signal?: () => AbortSignal | undefined,
  *   openEngine?: () => Promise<Engine>,
  * }} options
@@ -201,9 +231,9 @@ const DUCK_TYPES = {
  *   connection: unknown,
  * }} Engine
  */
-export function createSql({ importModule, signal, openEngine }) {
+export function createSql({ importModule, mapped, signal, openEngine }) {
   let engine = null;
-  const open = () => (engine ??= (openEngine ?? (() => defaultEngine(importModule)))().catch((err) => {
+  const open = () => (engine ??= (openEngine ?? (() => defaultEngine(importModule, mapped)))().catch((err) => {
     engine = null;
     throw err;
   }));
@@ -321,9 +351,9 @@ function hasNativeRuntime() {
     typeof globalThis.process?.versions?.node === "string" && !inWorker();
 }
 
-async function defaultEngine(importModule) {
+async function defaultEngine(importModule, mapped) {
   if (hasNativeRuntime()) return nativeEngine(importModule);
-  if (inWorker() && typeof Worker === "function") return wasmEngine(importModule);
+  if (inWorker() && typeof Worker === "function") return wasmEngine(importModule, mapped);
   throw new Error("jupyter.sql needs Node, Deno, Bun or the browser target; workerd and celld have no DuckDB");
 }
 
@@ -355,9 +385,10 @@ async function nativeEngine(importModule) {
   };
 }
 
-async function wasmEngine(importModule) {
+async function wasmEngine(importModule, mapped) {
   const duckdb = await importModule(DUCKDB_WASM);
-  const bundle = await duckdb.selectBundle(duckdb.getJsDelivrBundles());
+  // An app that serves the files (DUCKDB_FILES) runs SQL offline.
+  const bundle = await duckdb.selectBundle(duckdbBundles(duckdb.getJsDelivrBundles(), mapped));
   // A Worker can only start from its own origin's scripts, so a Blob
   // script loads DuckDB's.
   const loader = URL.createObjectURL(new Blob([`importScripts(${JSON.stringify(bundle.mainWorker)});`], { type: "text/javascript" }));

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