@tlockney/cdp-kernel 0.10.0 → 0.11.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.10.0";
+export declare const VERSION = "0.11.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-11";
+export declare const RELEASE_DATE = "2026-11-13";
 /**
  * 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-11";
  * 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", "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", "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.10.0";
+export const VERSION = "0.11.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-11";
+export const RELEASE_DATE = "2026-11-13";
 /**
  * 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
@@ -45,6 +45,9 @@ export const RUNTIME_FILES = [
     "comm.mjs",
     "host.mjs",
     "widget.mjs",
+    "table.mjs",
+    "sql.mjs",
+    "chart.mjs",
     "node-hooks.mjs",
     "deno-compat.mjs",
     "node-modules-resolve.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", "evaluator.mjs", "introspect.mjs"];
+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"];
 /** 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.10.0",
+  "version": "0.11.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/chart.d.mts

@@ -0,0 +1,23 @@
+export const VEGA: string;
+export const VEGA_LITE: string;
+export const LINKEDOM: string;
+export const WARN_BYTES: number;
+export const VEGA_CONFIG: Record<string, unknown>;
+
+export function isPlotModule(value: unknown): boolean;
+export function isSvgElement(value: unknown): boolean;
+export function isVegaSpec(spec: Record<string, unknown>): boolean;
+export function specOf(value: unknown): Record<string, unknown>;
+export function svgSize(svg: string): { width: number; height: number };
+export function withNamespace(svg: string): string;
+export function legendSVG(scale: unknown, width: number, form?: "ramp" | "swatches"): { svg: string; height: number };
+export function composeSVG(
+  inner: string,
+  parts: { title?: string; subtitle?: string; caption?: string; legend?: { svg: string; height: number } },
+): string;
+export function summarizePlot(element: unknown, options: Record<string, unknown>): string;
+export function createChart(options: {
+  importModule: (specifier: string) => Promise<any>;
+  summarizeSpec?: (spec: Record<string, unknown>) => string | undefined;
+  warn?: (message: string) => void;
+}): (chart: unknown, options?: unknown) => import("./display.d.mts").Displayable;

package/runtime/chart.mjs

@@ -0,0 +1,359 @@
+// @ts-self-types="./chart.d.mts"
+// jupyter.chart (cdp-kernel#479, ganymede#747): a Vega-Lite (or Vega) spec,
+// or Observable Plot options, drawn in the kernel as one SVG with its
+// legend and title inside, plus a text summary. An SVG shows the same in
+// every reader: the Ganymede apps, JupyterLab, VS Code, a published page,
+// and an agent that gets it as a PNG. Plot draws a categorical legend as
+// HTML beside its SVG, so the legend is drawn here instead, from the
+// plot's color scale.
+//
+// vega, vega-lite and linkedom (Plot's DOM where there is none) load
+// through the cell's own import on first use, as jupyter.sql's DuckDB
+// does, so nothing loads for a notebook that draws no chart.
+//
+// No static imports: this file must load in every target.
+
+export const VEGA = "npm:vega@6";
+export const VEGA_LITE = "npm:vega-lite@6";
+export const LINKEDOM = "npm:linkedom@0.18";
+/** Past this much SVG, jupyter.chart warns: aggregate or sample first. */
+export const WARN_BYTES = 2_000_000;
+
+const $display = Symbol.for("Jupyter.display");
+/** Plot scales with a legend option, besides color. */
+const OTHER_LEGENDS = ["opacity", "r", "symbol"];
+const FONT = "system-ui, sans-serif";
+
+const rawToEntity = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => rawToEntity[c]);
+
+function isObject(value) {
+  return value !== null && typeof value === "object";
+}
+
+/** Plot's module: it has plot() and mark factories. */
+export function isPlotModule(value) {
+  return (isObject(value) || typeof value === "function") && typeof value.plot === "function" &&
+    typeof value.barY === "function";
+}
+
+/** Keys one of which every Vega-Lite or Vega spec has. */
+const SPEC_KEYS = ["$schema", "mark", "marks", "layer", "spec", "concat", "hconcat", "vconcat", "facet", "repeat"];
+
+/** A spec object, or anything with toSpec() (vega-lite-api). */
+export function specOf(value) {
+  const spec = isObject(value) && typeof value.toSpec === "function" ? value.toSpec() : value;
+  if (!isObject(spec) || Array.isArray(spec) || !SPEC_KEYS.some((key) => key in spec)) {
+    throw new TypeError(
+      "jupyter.chart takes a Vega-Lite or Vega spec, the Plot module and Plot options, or an SVG element",
+    );
+  }
+  return spec;
+}
+
+/** An SVG element already drawn, such as Plot's output without a legend. */
+export function isSvgElement(value) {
+  return isObject(value) && typeof value.outerHTML === "string" && /^<svg\b/i.test(value.outerHTML);
+}
+
+export function isVegaSpec(spec) {
+  return typeof spec.$schema === "string" && /\/schema\/vega\/v\d/.test(spec.$schema);
+}
+
+// --- SVG helpers --------------------------------------------------------------
+
+/** An SVG's width and height from its attributes or viewBox. */
+export function svgSize(svg) {
+  const open = /<svg\b[^>]*>/i.exec(svg)?.[0] ?? "";
+  const attr = (name) => {
+    const m = new RegExp(`\\s${name}="([^"]*)"`, "i").exec(open);
+    return m ? m[1] : undefined;
+  };
+  let width = parseFloat(attr("width") ?? "");
+  let height = parseFloat(attr("height") ?? "");
+  const box = attr("viewBox")?.trim().split(/[\s,]+/).map(Number);
+  if (!Number.isFinite(width) && box?.length === 4) width = box[2];
+  if (!Number.isFinite(height) && box?.length === 4) height = box[3];
+  return { width: Number.isFinite(width) ? width : 640, height: Number.isFinite(height) ? height : 400 };
+}
+
+/** The SVG with the namespace an <img> needs (an HTML DOM leaves it out). */
+export function withNamespace(svg) {
+  return /<svg\b[^>]*\sxmlns=/i.test(svg) ? svg : svg.replace(/<svg\b/i, '<svg xmlns="http://www.w3.org/2000/svg"');
+}
+
+/** A short FNV-1a hash of `text`, in base 36. */
+function hash(text) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193);
+  return (h >>> 0).toString(36);
+}
+
+const textWidth = (text, size) => String(text).length * size * 0.6;
+
+/**
+ * A legend for a color scale, as SVG: swatches for a categorical scale,
+ * a ramp for a continuous one, or the form `form` names ("swatches" or
+ * "ramp", as Plot's `legend` option does). `scale` is Plot's scale
+ * description.
+ */
+export function legendSVG(scale, width, form) {
+  if (!isObject(scale) || typeof scale.apply !== "function" || !Array.isArray(scale.domain)) return { svg: "", height: 0 };
+  const label = typeof scale.label === "string" && scale.label ? scale.label : "";
+  const parts = [];
+  let y = 0;
+  if (label) {
+    parts.push(`<text x="0" y="10" font-weight="bold">${esc(label)}</text>`);
+    y = 16;
+  }
+  const continuous = form === "ramp" ||
+    (form !== "swatches" &&
+      /^(linear|log|pow|sqrt|symlog|utc|time|sequential|diverging|quantize|threshold|quantile)/.test(String(scale.type)));
+  if (!continuous) {
+    let x = 0;
+    let row = y;
+    for (const value of scale.domain) {
+      const text = String(value);
+      const w = 14 + textWidth(text, 10) + 12;
+      if (x > 0 && x + w > width) {
+        x = 0;
+        row += 16;
+      }
+      parts.push(
+        `<rect x="${x}" y="${row}" width="10" height="10" fill="${esc(scale.apply(value))}"/>` +
+          `<text x="${x + 14}" y="${row + 9}">${esc(text)}</text>`,
+      );
+      x += w;
+    }
+    return { svg: parts.join(""), height: row + 14 };
+  }
+  const [lo, hi] = [scale.domain[0], scale.domain.at(-1)];
+  const n = 16;
+  const stops = [];
+  // Plot's interpolator runs over the scale's output (its range), so
+  // sampling it spaces a log or sqrt scale's colors as the chart does;
+  // without one, step through the domain, Dates as their times.
+  const range = Array.isArray(scale.range) && scale.range.length >= 2 && scale.range.every((r) => typeof r === "number")
+    ? [scale.range[0], scale.range.at(-1)]
+    : undefined;
+  const numeric = (v) => (v instanceof Date ? v.getTime() : typeof v === "number" ? v : NaN);
+  const [a, b] = [numeric(lo), numeric(hi)];
+  for (let i = 0; i <= n; i++) {
+    const t = i / n;
+    let color;
+    if (typeof scale.interpolate === "function" && range) color = scale.interpolate(range[0] + (range[1] - range[0]) * t);
+    else if (Number.isFinite(a) && Number.isFinite(b)) {
+      const v = a + (b - a) * t;
+      color = scale.apply(lo instanceof Date ? new Date(v) : v);
+    } else color = scale.apply(i === 0 ? lo : hi);
+    stops.push(`<stop offset="${t * 100}%" stop-color="${esc(color)}"/>`);
+  }
+  // From the stops, so the same chart gives the same SVG on every run.
+  const id = `ramp-${hash(stops.join(""))}`;
+  const rampWidth = Math.min(240, width);
+  const fmt = (v) => (v instanceof Date ? v.toISOString().slice(0, 10) : typeof v === "number" ? String(Number(v.toPrecision(4))) : String(v));
+  parts.push(
+    `<defs><linearGradient id="${id}">${stops.join("")}</linearGradient></defs>` +
+      `<rect x="0" y="${y}" width="${rampWidth}" height="10" fill="url(#${id})"/>` +
+      `<text x="0" y="${y + 22}">${esc(fmt(lo))}</text>` +
+      `<text x="${rampWidth}" y="${y + 22}" text-anchor="end">${esc(fmt(hi))}</text>`,
+  );
+  return { svg: parts.join(""), height: y + 26 };
+}
+
+/**
+ * Plot's SVG with a title, subtitle, legend and caption around it, all in
+ * one SVG.
+ */
+export function composeSVG(inner, { title, subtitle, caption, legend }) {
+  const { width, height } = svgSize(inner);
+  const head = [];
+  let y = 0;
+  if (title) {
+    head.push(`<text x="0" y="${y + 16}" font-size="16" font-weight="bold">${esc(title)}</text>`);
+    y += 24;
+  }
+  if (subtitle) {
+    head.push(`<text x="0" y="${y + 13}" font-size="13">${esc(subtitle)}</text>`);
+    y += 20;
+  }
+  if (legend?.svg) {
+    head.push(`<g transform="translate(0,${y})" font-size="10">${legend.svg}</g>`);
+    y += legend.height + 8;
+  }
+  const body = withNamespace(inner).replace(/<svg\b/i, `<svg x="0" y="${y}"`);
+  let total = y + height;
+  let foot = "";
+  if (caption) {
+    foot = `<text x="0" y="${total + 16}" font-size="12">${esc(caption)}</text>`;
+    total += 24;
+  }
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${total}" viewBox="0 0 ${width} ${total}" ` +
+    `font-family="${FONT}" fill="currentColor">${head.join("")}${body}${foot}</svg>`
+  );
+}
+
+// --- Summaries ----------------------------------------------------------------
+
+function markName(mark) {
+  if (typeof mark?.ariaLabel === "string" && mark.ariaLabel) return mark.ariaLabel;
+  return mark?.constructor?.name?.toLowerCase() ?? "mark";
+}
+
+function describeScale(name, scale) {
+  if (!isObject(scale)) return null;
+  const label = typeof scale.label === "string" && scale.label ? scale.label : "";
+  const domain = Array.isArray(scale.domain) ? scale.domain : [];
+  let range = "";
+  if (domain.length && domain.every((v) => typeof v === "number" || v instanceof Date) && !/ordinal|band|point/.test(scale.type)) {
+    const fmt = (v) => (v instanceof Date ? v.toISOString().slice(0, 10) : String(Number(v.toPrecision(4))));
+    range = `${fmt(domain[0])} to ${fmt(domain.at(-1))}`;
+  } else if (domain.length) {
+    range = `${domain.length} ${domain.length === 1 ? "value" : "values"}`;
+  }
+  const details = [scale.type, range].filter(Boolean).join(", ");
+  return `${name}${label ? `=${label}` : ""}${details ? ` (${details})` : ""}`;
+}
+
+/** A few lines about a Plot chart, for readers that can't see it. */
+export function summarizePlot(element, options) {
+  const marks = (Array.isArray(options.marks) ? options.marks.flat(Infinity) : []).filter(isObject);
+  const names = [...new Set(marks.map(markName))];
+  const scales = ["x", "y", "fx", "fy", "color", "r", "opacity", "symbol"]
+    .map((name) => (typeof element?.scale === "function" ? describeScale(name, element.scale(name)) : null))
+    .filter(Boolean);
+  const rows = marks.map((m) => (Array.isArray(m.data) ? m.data.length : typeof m.data?.length === "number" ? m.data.length : 0));
+  const most = rows.length ? Math.max(...rows) : 0;
+  const title = typeof options.title === "string" && options.title ? ` "${options.title}"` : "";
+  const parts = [...scales];
+  if (most) parts.push(`${most} ${most === 1 ? "row" : "rows"}`);
+  return `Plot ${names.length ? `${names.join(", ")} ` : ""}chart${title}${parts.length ? `: ${parts.join(", ")}` : ""}`;
+}
+
+// --- Vega's defaults, for a chart on any background ----------------------------
+
+const INK = "currentColor";
+/**
+ * Text and lines in `currentColor`, on no background: the page's text
+ * color when the SVG is inline, and in the Ganymede apps, which give an
+ * SVG image the page's color. In a plain <img> it is black.
+ */
+export const VEGA_CONFIG = {
+  background: "transparent",
+  axis: { labelColor: INK, titleColor: INK, domainColor: INK, tickColor: INK, gridColor: INK, gridOpacity: 0.15 },
+  legend: { labelColor: INK, titleColor: INK },
+  title: { color: INK, subtitleColor: INK },
+  header: { labelColor: INK, titleColor: INK },
+  view: { stroke: null },
+};
+
+function mergeConfig(base, own) {
+  if (!isObject(own)) return base;
+  const out = { ...base };
+  for (const [key, value] of Object.entries(own)) {
+    out[key] = isObject(value) && isObject(base[key]) && !Array.isArray(value) ? mergeConfig(base[key], value) : value;
+  }
+  return out;
+}
+
+// --- The helper -----------------------------------------------------------------
+
+/**
+ * @param {{
+ *   importModule: (specifier: string) => Promise<any>,
+ *   summarizeSpec?: (spec: object) => string | undefined,
+ *   warn?: (message: string) => void,
+ * }} options
+ */
+export function createChart({ importModule, summarizeSpec, warn = (m) => console.warn(m) }) {
+  let dom;
+  async function document() {
+    if (globalThis.document && typeof globalThis.document.createElementNS === "function") return globalThis.document;
+    // A failed load isn't kept, so the next chart tries again.
+    dom ??= importModule(LINKEDOM)
+      .then(({ parseHTML }) => parseHTML("<!doctype html><html><body></body></html>").document)
+      .catch((err) => {
+        dom = undefined;
+        throw err;
+      });
+    return dom;
+  }
+
+  async function renderVega(spec, options) {
+    const keepSpec = isObject(options) && options.spec === true;
+    const [vega, vl] = await Promise.all([importModule(VEGA), isVegaSpec(spec) ? null : importModule(VEGA_LITE)]);
+    const config = mergeConfig(VEGA_CONFIG, spec.config);
+    const vgSpec = vl ? vl.compile({ ...spec, config }).spec : { ...spec, config };
+    const view = new vega.View(vega.parse(vgSpec), { renderer: "none" });
+    let svg;
+    try {
+      svg = await view.toSVG();
+    } finally {
+      view.finalize();
+    }
+    const bundle = { "image/svg+xml": withNamespace(svg) };
+    const summary = summarizeSpec?.({ $schema: "https://vega.github.io/schema/vega-lite/v5.json", ...spec });
+    if (summary) bundle["text/plain"] = summary;
+    if (keepSpec) {
+      const v4 = /\/schema\/vega-lite\/v4/.test(String(spec.$schema));
+      bundle[vl ? (v4 ? "application/vnd.vegalite.v4+json" : "application/vnd.vegalite.v5+json") : "application/vnd.vega.v5+json"] = spec;
+    }
+    return bundle;
+  }
+
+  async function renderPlot(Plot, options) {
+    if (!isObject(options)) throw new TypeError("jupyter.chart(Plot, options): options must be Plot's options object");
+    const { title, subtitle, caption, ...rest } = options;
+    const color = isObject(rest.color) ? rest.color : undefined;
+    const wantLegend = Boolean(color?.legend);
+    const plotOptions = { ...rest, document: await document(), figure: false };
+    if (color) plotOptions.color = { ...color, legend: false };
+    // Only the color legend is drawn; Plot would put the others in an
+    // HTML figure, which a reader that shows only images drops.
+    const others = OTHER_LEGENDS.filter((name) => isObject(rest[name]) && rest[name].legend);
+    if (others.length) {
+      warn(`jupyter.chart draws only a color legend; the ${others.join(", ")} legend is left out`);
+    }
+    const element = Plot.plot(plotOptions);
+    const inner = element.outerHTML;
+    const { width } = svgSize(inner);
+    const scale = wantLegend && typeof element.scale === "function" ? element.scale("color") : undefined;
+    const form = color?.legend === "ramp" || color?.legend === "swatches" ? color.legend : undefined;
+    const legend = scale ? legendSVG({ ...scale, label: scale.label ?? color.label }, width, form) : undefined;
+    const svg = composeSVG(inner, { title, subtitle, caption, legend });
+    return { "image/svg+xml": withNamespace(svg), "text/plain": summarizePlot(element, options) };
+  }
+
+  function chart(first, second) {
+    // Checked now, so a wrong argument fails the call.
+    const spec = isPlotModule(first) || isSvgElement(first) ? undefined : specOf(first);
+    if (isPlotModule(first) && !isObject(second)) {
+      throw new TypeError("jupyter.chart(Plot, options): options must be Plot's options object");
+    }
+    if (isSvgElement(first)) {
+      const bundle = { "image/svg+xml": withNamespace(first.outerHTML) };
+      return { [$display]: () => bundle };
+    }
+    let pending;
+    const render = () =>
+      (pending ??= (async () => {
+        const bundle = spec ? await renderVega(spec, second) : await renderPlot(first, second);
+        const size = bundle["image/svg+xml"].length;
+        if (size > WARN_BYTES) {
+          warn(
+            `jupyter.chart: the SVG is ${(size / 1e6).toFixed(1)} MB, which makes the notebook large; ` +
+              "aggregate or sample the data first",
+          );
+        }
+        return bundle;
+      })().catch((err) => {
+        // Not kept, so displaying the chart again retries.
+        pending = undefined;
+        throw err;
+      }));
+    return { [$display]: render };
+  }
+
+  return chart;
+}

package/runtime/display.d.mts

@@ -1,7 +1,9 @@
 import type { CommApi, Comms } from "./comm.d.mts";
 import type { Host, HostCallOptions, HostError, HostErrorCode, HostNotebooks, HostOptions, HostSelf, NotebookEntry, NotebookHit, NotebookSearch } from "./host.d.mts";
 import type { Widget, WidgetOptions } from "./widget.d.mts";
+import type { Sql, SqlColumn, SqlFragment, SqlResult } from "./sql.d.mts";
 
+export type { Sql, SqlColumn, SqlFragment, SqlResult };
 export type { CommApi, Host, HostCallOptions, HostError, HostErrorCode, HostNotebooks, HostOptions, HostSelf, NotebookEntry, NotebookHit, NotebookSearch, Widget, WidgetOptions };
 
 /**
@@ -34,6 +36,25 @@ export const RESULT_MIME: "application/vnd.ganymede.result+json";
 /** A JSON value, as `JSON.parse` returns it. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 
+/** Options for `jupyter.table`. */
+export interface TableOptions {
+  /** Rows to embed: default 1,000, at most 10,000, and never past 1 MB of JSON. */
+  limit?: number;
+  /** The columns to show, in order. Names an array of arrays' columns. */
+  columns?: string[];
+  /** A caption for the table. */
+  title?: string;
+}
+
+/** Options for `jupyter.chart` with a Vega-Lite or Vega spec. */
+export interface ChartOptions {
+  /**
+   * Also keep the spec under its Vega MIME type, for a frontend that
+   * draws Vega itself. Default `false`: the SVG and a text summary only.
+   */
+  spec?: boolean;
+}
+
 /** Options for `jupyter.display`. */
 export interface DisplayOptions {
   /**
@@ -332,6 +353,109 @@ export interface JupyterNamespace {
    * @see jupyter-api.md#parameters-and-named-results
    */
   result(name: string, value: unknown): void;
+  /**
+   * Show rows and columns as a table. The output has Ganymede's table
+   * type, `application/vnd.dataresource+json` (Table Schema fields, up to
+   * `limit` rows as JSON, and the total row count), which the Ganymede
+   * apps show with sorting and paging; a plain HTML table of the first
+   * and last rows for JupyterLab and VS Code; and a text summary of each
+   * column's type and range for agents and consoles.
+   *
+   * An Arrow table, a Polars DataFrame or a DuckDB result also shows this
+   * way when it is a cell's value; pass one here to set `limit`,
+   * `columns` or `title`.
+   *
+   * @param value An array of row objects, an array of arrays (name them
+   *   with `columns`), an Arrow table (apache-arrow, duckdb-wasm), a
+   *   Polars DataFrame, or a `@duckdb/node-api` result.
+   * @param options `limit`: rows to embed, default 1,000, at most 10,000,
+   *   and never more than 1 MB of JSON. `columns`: which columns, in order.
+   *   `title`: a caption.
+   * @throws {TypeError} `value` isn't one of those, or `limit` isn't a
+   *   whole number.
+   * @example
+   * ```ts
+   * const moons = [
+   *   { moon: "Io", radius_km: 1821.6, discovered: new Date("1610-01-08") },
+   *   { moon: "Europa", radius_km: 1560.8, discovered: new Date("1610-01-08") },
+   *   { moon: "Ganymede", radius_km: 2634.1, discovered: new Date("1610-01-07") },
+   * ];
+   * jupyter.table(moons, { title: "Galilean moons" });
+   * ```
+   * @see jupyter-api.md#tables
+   */
+  table(value: unknown, options?: TableOptions): Displayable;
+  /**
+   * Run SQL on an in-memory [DuckDB](https://duckdb.org) database, as a
+   * tagged template: each `${value}` becomes a bound parameter, never
+   * query text, so values can't change the query. Resolves to a
+   * `SqlResult`, which shows as a table and has `columns` and `rows`.
+   *
+   * The database opens on the first query and lasts until the kernel
+   * restarts or `jupyter.sql.close()`. DuckDB reads CSV, Parquet and JSON
+   * files by path or URL; `jupyter.sql.load` makes a table from rows the
+   * notebook already has. An interrupt stops a running query.
+   *
+   * @throws {TypeError} Called as a function rather than a tag.
+   * @availability Node, Deno and Bun use `@duckdb/node-api`; the browser
+   *   target (the Ganymede apps) uses duckdb-wasm from a CDN. Not on
+   *   workerd or celld.
+   * @example
+   * ```ts
+   * const min = 2000;
+   * await jupyter.sql`
+   *   select moon, radius_km
+   *   from (values ('Io', 1821.6), ('Ganymede', 2634.1), ('Callisto', 2410.3)) as m(moon, radius_km)
+   *   where radius_km > ${min}
+   *   order by radius_km desc`;
+   * ```
+   * @see jupyter-api.md#sql-with-duckdb
+   */
+  readonly sql: Sql;
+  /**
+   * Draw a chart in the kernel as one SVG, with its title and legend
+   * inside, plus a text summary for readers that can't see it. The SVG
+   * shows the same in the Ganymede apps, JupyterLab, VS Code and a
+   * published page. Text and axes are drawn in `currentColor`: the
+   * notebook's text color in the Ganymede apps, black in JupyterLab.
+   *
+   * Pass a [Vega-Lite](https://vega.github.io/vega-lite/) or Vega spec
+   * (or a vega-lite-api chart), or the
+   * [Observable Plot](https://observablehq.com/plot/) module and the
+   * options you would give `Plot.plot`. Plot's `title`, `subtitle`,
+   * `caption` and the color legend (`legend: true`, `"swatches"` or
+   * `"ramp"`) are drawn into the SVG; other scales' legends are left
+   * out. An SVG element shows as it is.
+   *
+   * vega and vega-lite (version 6), and linkedom for Plot where there is
+   * no DOM, load through the cell's import on first use. A chart past
+   * 2 MB of SVG logs a warning: aggregate or sample first.
+   *
+   * @param chart A Vega-Lite or Vega spec, the Plot module, or an SVG
+   *   element.
+   * @param options With a spec, `ChartOptions`; with Plot, Plot's options.
+   * @throws {TypeError} `chart` is none of those, or Plot comes without
+   *   options.
+   * @example
+   * ```ts
+   * jupyter.chart({
+   *   title: "Galilean moons",
+   *   data: { values: [
+   *     { moon: "Io", radius_km: 1821.6 },
+   *     { moon: "Europa", radius_km: 1560.8 },
+   *     { moon: "Ganymede", radius_km: 2634.1 },
+   *     { moon: "Callisto", radius_km: 2410.3 },
+   *   ] },
+   *   mark: "bar",
+   *   encoding: {
+   *     x: { field: "moon", sort: "-y" },
+   *     y: { field: "radius_km", type: "quantitative" },
+   *   },
+   * });
+   * ```
+   * @see jupyter-api.md#charts
+   */
+  chart(chart: object, options?: ChartOptions | Record<string, unknown>): Displayable;
   /**
    * The Ganymede server running this kernel, through its host API: read,
    * search and (when granted) run other notebooks under its root. The