@tlockney/cdp-kernel 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.5.0",
+  "version": "0.7.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>",
@@ -20,7 +20,7 @@
   ],
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": ">=22.18"
   },
   "bin": {
     "cdp-kernel": "dist/main.js"
@@ -34,6 +34,11 @@
       "types": "./dist/globals.d.ts",
       "default": "./dist/globals.js"
     },
+    "./browser": {
+      "types": "./dist/browser/mod.d.ts",
+      "default": "./dist/browser/kernel.js"
+    },
+    "./browser/worker": "./dist/browser/worker.js",
     "./globals/deno-compat": {
       "types": "./dist/globals-deno-compat.d.ts",
       "default": "./dist/globals-deno-compat.js"
@@ -49,7 +54,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/build-browser.mjs dist/browser",
     "check": "tsc -p tsconfig.json",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
@@ -64,18 +69,23 @@
     "prepack": "npm run build",
     "test": "node --test --test-timeout=300000 test/*.test.ts",
     "e2e": "uv run --with nbclient --with nbformat --with jupyter_client python test/e2e.py",
+    "bench": "uv run --with jupyter_client python test/bench.py",
+    "soak": "uv run --with jupyter_client python test/soak.py",
     "test:lab": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/lab_widgets.py"
   },
   "dependencies": {
     "acorn": "^8.15.0",
     "acorn-walk": "^8.3.4",
-    "esbuild": "^0.25.10"
+    "esbuild": "^0.25.10",
+    "typescript": "^6.0.3"
   },
   "devDependencies": {
     "@types/node": "^24.19.2",
-    "typescript": "^5.9.3",
     "vitepress": "^1.6.4",
     "workerd": "1.20261015.1",
     "wrangler": "4.151.0"
+  },
+  "optionalDependencies": {
+    "sucrase": "^3.35.1"
   }
 }

package/runtime/bootstrap.mjs

@@ -2,8 +2,8 @@
 //   node --inspect=127.0.0.1:0 runtime/bootstrap.mjs
 //   deno run -A --inspect=127.0.0.1:0 runtime/bootstrap.mjs
 // then drives it over CDP. Everything the host needs from inside the
-// runtime lives on globalThis.__cdpk; output to the host goes through the
-// `__cdpk_send` CDP binding (Runtime.addBinding) plus plain stdout/stderr.
+// runtime lives on globalThis.__cdpk; output to the host goes over plain
+// stdout/stderr, with messages as records on stdout (see send below).
 // Bun is launched as `bun runtime/bootstrap.mjs` and driven over a pipe
 // instead; see bun-channel.mjs.
 //
@@ -27,7 +27,7 @@ const cwdUrl = pathToFileURL(cwd.endsWith("/") ? cwd : cwd + "/");
 // Stand-in referrer for cell code, like Deno's ./$deno$jupyter_repl.mts.
 const replUrl = new URL("$cdpk$repl.mjs", cwdUrl);
 
-const { inspect, inspectPlain, readFile, writeOut, writeErr, readStdinLine } = await platform();
+const { inspect, inspectPlain, readFile, writeOut, writeErr, readStdin } = await platform();
 
 function base64(bytes) {
   let binary = "";
@@ -38,11 +38,12 @@ function base64(bytes) {
 }
 
 // --- Output ordering ----------------------------------------------------
-// stdout/stderr reach the host over pipes; display messages over the
-// WebSocket. To keep them in order, every binding message is preceded by a
-// numbered marker written to both pipes. The host holds the message until
-// both pipes have delivered that marker, and a gated marker ("m") holds
-// later pipe output until the message has gone out.
+// stdout/stderr reach the host over pipes, and so do messages: as records
+// on stdout on Node and Deno, over Bun's channel on Bun. Every message has
+// a number; stderr gets a gated marker ("m") with it, and stdout the record
+// (Bun: a gated marker on both pipes). The host holds the message until
+// both pipes have reached that number, and holds later pipe output until
+// the message has gone out.
 let barrierSeq = 0;
 function barrier(gated = false) {
   const n = ++barrierSeq;
@@ -52,15 +53,32 @@ function barrier(gated = false) {
   return n;
 }
 
+// Node and Deno: messages were a CDP binding's events, but an event just
+// before an evaluate's reply delays the reply ~40 ms (#271). A record is
+// the message's JSON, which holds no raw ESC, between "\x1b[cdpk:<" and
+// "\x1b]". Cells can call this too; the host drops what isn't a message
+// (#122).
+let attached = false;
+function sendRecord(text) {
+  text = String(text);
+  if (attached && !text.includes("\x1b")) writeOut(`\x1b[cdpk:<${text}\x1b]`);
+}
+if (!isBun) globalThis.__cdpk_send = sendRecord;
+
 function send(payload) {
-  const binding = globalThis.__cdpk_send;
-  if (typeof binding !== "function") return; // host not attached yet
+  if (isBun ? typeof globalThis.__cdpk_send !== "function" : !attached) return; // host not attached yet
   // Serialize before writing the marker: if the payload can't be
   // serialized (a BigInt, a cycle), the error reaches the cell without a
   // gated marker the host would wait on forever (#129). `payload` always
   // has a `kind`, so `body` is never "{}".
   const body = JSON.stringify(payload);
-  binding(`{"barrier":${barrier(true)},${body.slice(1)}`);
+  if (isBun) {
+    globalThis.__cdpk_send(`{"barrier":${barrier(true)},${body.slice(1)}`);
+    return;
+  }
+  const n = ++barrierSeq;
+  writeErr(`\x1b[cdpk:${n}m]\x1b`);
+  sendRecord(`{"barrier":${n},${body.slice(1)}`);
 }
 
 const jupyter = createJupyter({
@@ -74,7 +92,7 @@ const jupyter = createJupyter({
   // stdin for its JSON-line reply.
   input(prompt, password) {
     send({ kind: "input_request", prompt, password });
-    const line = readStdinLine();
+    const line = readInputReply();
     if (line === null) return null;
     const reply = JSON.parse(line);
     if (reply.interrupted === true) {
@@ -157,13 +175,23 @@ function hold(value) {
   return promise;
 }
 
+// Yields one macrotask. Code the inspector dispatches calls this, and Node
+// and Deno dispatch a message that arrives while JavaScript runs from a V8
+// interrupt, which can land inside their timer code. A setTimeout there can
+// create a timer list while the timer heap is mid-update, and the heap then
+// loses it: every later setTimeout of that duration never fires (#237).
+// setImmediate only appends to a linked list.
+const yieldTask = () => new Promise((resolve) => setImmediate(resolve));
+
 // Adds the cause to an error from a Deno member the --deno-compat shim
 // lacks (#172); the identity everywhere else.
 let explainError = (text) => text;
 
 globalThis.__cdpk = {
+  // The host calls this once it reads message records (Node and Deno).
+  attach: () => void (attached = true),
   // Cell code awaits this first; see PRELUDE in src/transform.ts.
-  tick: () => new Promise((resolve) => setTimeout(resolve, 0)),
+  tick: yieldTask,
   // Node: the resolve hook re-parents these imports. Deno would resolve
   // relative paths against this file, so denoImport does it here.
   import: (specifier, options) =>
@@ -196,10 +224,19 @@ globalThis.__cdpk = {
   // Frontend comm messages (#9), from the host's shell channel. Handlers
   // run after one macrotask, like cells, so interrupt can reach them.
   async commDispatch(msgType, content, metadata, buffers64) {
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await yieldTask();
     const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
     return await jupyter.commDispatch(msgType, content, metadata, buffers);
   },
+  // The same, for a message the host wrote to stdin (Node and Deno). A
+  // value passed as a CDP call argument is compiled as source, and V8's
+  // compilation cache keeps that source until the heap nears its limit, so
+  // each message's data would stay in memory (#287). Read before the first
+  // await, so messages are taken in the order the host wrote them.
+  commDispatchFromStdin() {
+    const { msgType, content, metadata, buffers } = readCommRecord();
+    return globalThis.__cdpk.commDispatch(msgType, content, metadata, buffers);
+  },
   describeError(value) {
     if (value instanceof Error) {
       const message = explainError(value.message);
@@ -308,21 +345,24 @@ if (isBun) {
   });
 }
 
+function writeAllSync(stream, bytes) {
+  while (bytes.length > 0) bytes = bytes.subarray(stream.writeSync(bytes));
+}
+
 async function platform() {
   if (isDeno) {
-    const stdinBuf = new Uint8Array(1);
     return {
       inspect: (v) => Deno.inspect(v, { colors: true, depth: 4 }),
       inspectPlain: (v) => Deno.inspect(v, { colors: false, depth: 2 }),
       readFile: (p) => Deno.readFileSync(p),
-      writeOut: (s) => Deno.stdout.writeSync(ENC.encode(s)),
-      writeErr: (s) => Deno.stderr.writeSync(ENC.encode(s)),
-      readStdinLine: () => readLine(() => (Deno.stdin.readSync(stdinBuf) ? stdinBuf[0] : null)),
+      // writeSync can write part of the buffer; a record must go out whole.
+      writeOut: (s) => writeAllSync(Deno.stdout, ENC.encode(s)),
+      writeErr: (s) => writeAllSync(Deno.stderr, ENC.encode(s)),
+      readStdin: (bytes) => Deno.stdin.readSync(bytes) ?? 0,
     };
   }
   const util = await import("node:util");
   const fs = await import("node:fs");
-  const buf = Buffer.alloc(1);
   // Node writes to a pipe without blocking and queues what doesn't fit for
   // the event loop to flush. input() blocks the main thread in readSync, so
   // queued output, and the input_request's barrier marker after it, would
@@ -335,19 +375,20 @@ async function platform() {
     inspect: (v) => util.inspect(v, { colors: true, depth: 4 }),
     inspectPlain: (v) => util.inspect(v, { colors: false, depth: 2 }),
     readFile: (p) => fs.readFileSync(p),
-    writeOut: (s) => process.stdout.write(s),
-    writeErr: (s) => process.stderr.write(s),
-    readStdinLine: () =>
-      readLine(() => {
-        for (;;) {
-          try {
-            return fs.readSync(0, buf, 0, 1, null) === 1 ? buf[0] : null;
-          } catch (err) {
-            if (err.code !== "EAGAIN") throw err;
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
-          }
+    // Bound now: a cell or library that patches process.stdout.write to
+    // capture output must not swallow message records (#271).
+    writeOut: process.stdout.write.bind(process.stdout),
+    writeErr: process.stderr.write.bind(process.stderr),
+    readStdin: (bytes) => {
+      for (;;) {
+        try {
+          return fs.readSync(0, bytes, 0, bytes.length, null);
+        } catch (err) {
+          if (err.code !== "EAGAIN") throw err;
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
         }
-      }),
+      }
+    },
   };
 }
 
@@ -376,12 +417,51 @@ async function syncBunOutput() {
   }
 }
 
-function readLine(nextByte) {
+// The host writes two kinds of record to stdin, both read synchronously: a
+// prompt's reply, as one JSON line, and a frontend comm message (#287), as
+// a `comm <length>` line followed by that many bytes of JSON.
+const COMM_HEADER = /^comm (\d+)$/;
+
+/** `n` bytes from stdin, or null if it ends first. */
+function readExactly(n) {
+  const bytes = new Uint8Array(n);
+  for (let at = 0; at < n;) {
+    const got = readStdin(bytes.subarray(at));
+    if (!got) return null;
+    at += got;
+  }
+  return bytes;
+}
+
+function readLine() {
   const bytes = [];
   for (;;) {
-    const byte = nextByte();
+    const byte = readExactly(1)?.[0] ?? null;
     if (byte === null) return bytes.length ? new TextDecoder().decode(new Uint8Array(bytes)) : null;
     if (byte === 0x0a) return new TextDecoder().decode(new Uint8Array(bytes));
     bytes.push(byte);
   }
 }
+
+/** The next prompt reply's line, past any comm record left unread. */
+function readInputReply() {
+  for (;;) {
+    const line = readLine();
+    const comm = line === null ? null : COMM_HEADER.exec(line);
+    if (comm === null) return line;
+    readExactly(Number(comm[1]));
+  }
+}
+
+/** The next comm message, past any prompt reply left unread. */
+function readCommRecord() {
+  for (;;) {
+    const line = readLine();
+    if (line === null) throw new Error("stdin closed before a comm message arrived");
+    const comm = COMM_HEADER.exec(line);
+    if (comm === null) continue;
+    const body = readExactly(Number(comm[1]));
+    if (body === null) throw new Error("stdin closed in the middle of a comm message");
+    return JSON.parse(new TextDecoder().decode(body));
+  }
+}

package/runtime/browser-worker.mjs

@@ -0,0 +1,119 @@
+// The driver for the browser target: a module Web Worker that runs cells.
+//
+// The page's kernel (src/browser/target.ts) sends each request as a
+// message and gets a reply message back, as over the workerd driver's
+// WebSocket (runtime/workerd-worker.mjs), whose shape this follows. Cells
+// come from transformCellForEval and run as global code with indirect
+// eval, so their declarations persist from cell to cell.
+//
+// A Worker has no module resolution beyond URLs, so `npm:` and `jsr:`
+// specifiers, and bare package names, load from a CDN (esm.sh by default).
+
+import { createJupyter } from "./display.mjs";
+import { createHandler } from "./evaluator.mjs";
+import { format, inspect } from "./format.mjs";
+import { describeValue, inspectPath, resolvePath } from "./introspect.mjs";
+import { DEFAULT_CDN, resolveSpecifier } from "./cdn.mjs";
+
+function base64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  }
+  return btoa(binary);
+}
+
+const post = (message) => globalThis.postMessage(message);
+
+// --- Output -----------------------------------------------------------------
+const stream = (name) => (...args) => post({ kind: "stream", name, text: format(...args) + "\n" });
+Object.assign(console, {
+  log: stream("stdout"),
+  info: stream("stdout"),
+  debug: stream("stdout"),
+  dir: (value) => post({ kind: "stream", name: "stdout", text: inspect(value, { depth: 4 }) + "\n" }),
+  warn: stream("stderr"),
+  error: stream("stderr"),
+});
+
+// An error thrown later by a cell's timer or promise goes to stderr, as on
+// the other targets.
+function reportUncaught(kind, err) {
+  post({ kind: "stream", name: "stderr", text: `${kind}: ${err instanceof Error ? (err.stack ?? err.message) : inspect(err)}\n` });
+}
+globalThis.addEventListener("unhandledrejection", (event) => {
+  event.preventDefault();
+  reportUncaught("Uncaught (in promise)", event.reason);
+});
+globalThis.addEventListener("error", (event) => {
+  event.preventDefault();
+  reportUncaught("Uncaught", event.error ?? event.message);
+});
+
+const jupyter = createJupyter({
+  inspect: (value) => inspect(value, { depth: 4 }),
+  base64,
+  readFile() {
+    throw new Error("the browser target has no file system to read from; pass the image bytes instead");
+  },
+  send(msgType, content, metadata, buffers) {
+    post({ kind: "iopub", msg_type: msgType, content, metadata, buffers: buffers.map(base64), barrier: 0 });
+  },
+  // A synchronous prompt would need SharedArrayBuffer and Atomics.wait, so
+  // a cross-origin isolated page; until then, as with no stdin.
+  input: () => null,
+});
+
+// --- Modules ----------------------------------------------------------------
+let cdn = DEFAULT_CDN;
+
+
+// --- The shim cells and the evaluator use -----------------------------------
+let handle = null;
+
+function install({ base, cdn: cdnBase }) {
+  if (typeof cdnBase === "string") cdn = cdnBase.endsWith("/") ? cdnBase : cdnBase + "/";
+  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) },
+    // 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 }),
+    resolvePath,
+    barrier: () => 0,
+    broadcastResult: jupyter.broadcastResult,
+    async commDispatch(msgType, content, metadata, buffers64) {
+      const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
+      return await jupyter.commDispatch(msgType, content, metadata, buffers);
+    },
+    describeError(value) {
+      if (value instanceof Error) {
+        return JSON.stringify({ name: value.name, message: value.message, stack: value.stack ?? "" });
+      }
+      return JSON.stringify({ name: "Error", message: inspect(value), stack: "" });
+    },
+  };
+  Object.defineProperty(globalThis, "__cdpk", { enumerable: false });
+  globalThis.jupyter = jupyter.namespace;
+  globalThis.prompt = jupyter.prompt;
+  globalThis.confirm = jupyter.confirm;
+  handle = createHandler(globalThis.__cdpk, (code) => (0, eval)(code));
+}
+
+async function answer(req) {
+  if (req.op === "info") {
+    install(req);
+    return { userAgent: globalThis.navigator?.userAgent ?? "" };
+  }
+  if (handle === null) throw new Error("the driver wasn't sent info first");
+  return await handle(req);
+}
+
+globalThis.addEventListener("message", (event) => {
+  const req = event.data;
+  answer(req).then(
+    (reply) => post({ kind: "reply", id: req.id, ...reply }),
+    (err) => post({ kind: "reply", id: req.id, failure: String(err?.stack ?? err) }),
+  );
+});

package/runtime/cdn.d.mts

@@ -0,0 +1,2 @@
+export const DEFAULT_CDN: string;
+export function resolveSpecifier(specifier: string, base: string, cdn?: string): string;

package/runtime/cdn.mjs

@@ -0,0 +1,17 @@
+// Where a browser cell's imports load from. A Worker resolves only URLs, so
+// packages come from a CDN that serves npm and jsr as ES modules: esm.sh by
+// default, with its jsr/ prefix for jsr packages.
+//
+// No imports: this file must load in every target.
+
+export const DEFAULT_CDN = "https://esm.sh/";
+
+/** The URL `specifier`, imported from `base`, loads from. */
+export function resolveSpecifier(specifier, base, cdn = DEFAULT_CDN) {
+  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);
+  if (specifier.startsWith("jsr:")) return `${cdn}jsr/${specifier.slice(4).replace(/^\//, "")}`;
+  // esm.sh serves polyfills for Node's builtins under node:.
+  return cdn + specifier;
+}

package/runtime/display.mjs

@@ -45,7 +45,201 @@ function extractVega(obj) {
   } else if (spec.$schema === "https://vega.github.io/schema/vega-lite/v5.json") {
     mediaType = "application/vnd.vegalite.v5+json";
   }
-  return { [mediaType]: spec };
+  const summary = summarizeChart(spec);
+  return summary === undefined ? { [mediaType]: spec } : { [mediaType]: spec, "text/plain": summary };
+}
+
+// A few lines of text/plain next to a chart, for frontends that can't draw
+// it (jupyter console, nbconvert to text, agents reading the notebook):
+// mark, encodings with value ranges, title and row count (#321). The
+// approach follows nteract's repr-llm summarize_viz (BSD-3).
+const VL_TYPES = { Q: "quantitative", N: "nominal", O: "ordinal", T: "temporal", G: "geojson" };
+const MAX_CHILDREN = 6;
+
+function clip(str, max = 60) {
+  return str.length > max ? `${str.slice(0, max - 1)}…` : str;
+}
+
+function formatNumber(n) {
+  return Number.isInteger(n) ? String(n) : String(Number(n.toPrecision(4)));
+}
+
+function titleText(title) {
+  const text = typeof title === "object" && title !== null && !Array.isArray(title) ? title.text : title;
+  const str = Array.isArray(text) ? text.join(" ") : typeof text === "string" ? text : "";
+  return str ? ` "${clip(str, 80)}"` : "";
+}
+
+function getField(row, field) {
+  if (row === null || typeof row !== "object") return undefined;
+  if (field in row) return row[field];
+  // Vega-Lite reads "a.b" as a nested path and "a\.b" as a key with a dot.
+  if (field.includes("\\")) return row[field.replace(/\\(.)/g, "$1")];
+  return field.split(".").reduce((obj, key) => (obj === null || typeof obj !== "object" ? undefined : obj[key]), row);
+}
+
+function fieldStats(rows, field, type) {
+  const values = [];
+  for (const row of rows) {
+    const value = getField(row, field);
+    if (value !== undefined && value !== null && value !== "") values.push(value);
+  }
+  if (values.length === 0) return "";
+  if (type === "quantitative") {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const value of values) {
+      const n = Number(value);
+      if (!Number.isFinite(n)) continue;
+      if (n < min) min = n;
+      if (n > max) max = n;
+    }
+    if (min > max) return "";
+    return min === max ? formatNumber(min) : `${formatNumber(min)} to ${formatNumber(max)}`;
+  }
+  if (type === "temporal") {
+    let min;
+    let max;
+    for (const value of values) {
+      const t = value instanceof Date ? value.getTime() : typeof value === "number" ? value : Date.parse(String(value));
+      if (!Number.isFinite(t)) continue;
+      if (min === undefined || t < min.t) min = { t, value };
+      if (max === undefined || t > max.t) max = { t, value };
+    }
+    if (min === undefined) return "";
+    const show = ({ value }) =>
+      typeof value === "string" ? clip(value, 30) : new Date(value instanceof Date ? value.getTime() : value).toISOString();
+    return min.t === max.t ? show(min) : `${show(min)} to ${show(max)}`;
+  }
+  const distinct = new Set(values.map((value) => typeof value === "object" ? JSON.stringify(value) : String(value)));
+  return `${distinct.size} ${distinct.size === 1 ? "value" : "values"}`;
+}
+
+function encodingSummary(encoding, rows) {
+  const parts = [];
+  for (const [channel, def] of Object.entries(encoding)) {
+    if (channel === "tooltip" || def === null || typeof def !== "object" || Array.isArray(def)) continue;
+    if (def.field === undefined && def.aggregate === undefined) continue;
+    let name = typeof def.field === "string" ? def.field : def.field?.repeat ? `repeat ${def.field.repeat}` : "";
+    if (def.aggregate !== undefined) name = `${def.aggregate}(${name})`;
+    else if (def.timeUnit !== undefined) name = `${typeof def.timeUnit === "string" ? def.timeUnit : "time"}(${name})`;
+    const type = VL_TYPES[def.type] ?? def.type;
+    const details = [];
+    if (typeof type === "string") details.push(type);
+    if (rows && typeof def.field === "string" && def.aggregate === undefined) {
+      const stats = fieldStats(rows, def.field, type);
+      if (stats) details.push(stats);
+    }
+    parts.push(`${channel}=${clip(name, 40)}${details.length ? ` (${details.join(", ")})` : ""}`);
+  }
+  return parts;
+}
+
+function vlRows(data, datasets) {
+  if (data === null || typeof data !== "object") return undefined;
+  if (Array.isArray(data.values)) return data.values;
+  if (typeof data.name === "string" && Array.isArray(datasets?.[data.name])) return datasets[data.name];
+  return undefined;
+}
+
+function vlDataNote(data, rows) {
+  if (rows) return `${rows.length} ${rows.length === 1 ? "row" : "rows"}`;
+  if (typeof data?.url === "string") return `data from ${clip(data.url)}`;
+  return "";
+}
+
+function fieldList(def) {
+  if (Array.isArray(def)) return def.join(", ");
+  if (def === null || typeof def !== "object") return "";
+  if (typeof def.field === "string") return def.field;
+  return Object.values(def).map(fieldList).filter(Boolean).join(", ");
+}
+
+function summarizeVegaLiteView(spec, label, inherited, datasets, depth, lines) {
+  const indent = "  ".repeat(depth);
+  const data = spec.data ?? inherited.data;
+  const rows = vlRows(data, datasets);
+  const head = `${indent}${label}`;
+  const title = titleText(spec.title);
+  const children = spec.layer ?? spec.concat ?? spec.hconcat ?? spec.vconcat;
+  if (Array.isArray(children)) {
+    const noun = spec.layer ? "layer" : "view";
+    const note = [`${children.length} ${children.length === 1 ? noun : `${noun}s`}`, vlDataNote(data, rows)].filter(Boolean);
+    lines.push(`${head}${spec.layer ? "layered" : "concatenated"} chart${title}: ${note.join(", ")}`);
+    const encoding = spec.layer ? { ...inherited.encoding, ...spec.encoding } : {};
+    children.slice(0, MAX_CHILDREN).forEach((child, i) => {
+      if (child !== null && typeof child === "object") {
+        summarizeVegaLiteView(child, `${noun} ${i + 1}: `, { data, encoding }, datasets, depth + 1, lines);
+      }
+    });
+    if (children.length > MAX_CHILDREN) lines.push(`${indent}  … ${children.length - MAX_CHILDREN} more`);
+    return;
+  }
+  if ((spec.facet !== undefined || spec.repeat !== undefined) && spec.spec !== null && typeof spec.spec === "object") {
+    const what = spec.facet !== undefined ? `faceted by ${fieldList(spec.facet)}` : `repeated over ${fieldList(spec.repeat)}`;
+    const note = vlDataNote(data, rows);
+    lines.push(`${head}chart${title} ${what}${note ? `, ${note}` : ""}`);
+    summarizeVegaLiteView(spec.spec, "each panel: ", { data, encoding: {} }, datasets, depth + 1, lines);
+    return;
+  }
+  const mark = typeof spec.mark === "string" ? spec.mark : spec.mark?.type;
+  const encoding = { ...inherited.encoding, ...spec.encoding };
+  const parts = encodingSummary(encoding, rows);
+  // A layer's rows were already counted on the layered chart's line.
+  if (spec.data !== undefined || depth === 0) {
+    const note = vlDataNote(data, rows);
+    if (note) parts.push(note);
+  }
+  lines.push(`${head}${typeof mark === "string" ? `${mark} ` : ""}chart${title}${parts.length ? `: ${parts.join(", ")}` : ""}`);
+}
+
+function vegaMarkTypes(marks, types) {
+  if (!Array.isArray(marks)) return types;
+  for (const mark of marks) {
+    if (typeof mark?.type === "string") types.add(mark.type);
+    vegaMarkTypes(mark?.marks, types);
+  }
+  return types;
+}
+
+function summarizeVega(spec) {
+  const sections = [];
+  const marks = [...vegaMarkTypes(spec.marks, new Set())];
+  if (marks.length) sections.push(`marks ${marks.join(", ")}`);
+  const list = (items, describe) => {
+    const shown = items.slice(0, MAX_CHILDREN).map(describe);
+    if (items.length > MAX_CHILDREN) shown.push(`… ${items.length - MAX_CHILDREN} more`);
+    return shown.join(", ");
+  };
+  const data = Array.isArray(spec.data) ? spec.data.filter((d) => d !== null && typeof d === "object") : [];
+  if (data.length) {
+    sections.push(`data ${list(data, (d) => {
+      const name = clip(String(d.name ?? "?"), 30);
+      if (Array.isArray(d.values)) return `${name} (${d.values.length} ${d.values.length === 1 ? "row" : "rows"})`;
+      if (typeof d.url === "string") return `${name} (from ${clip(d.url)})`;
+      if (d.source !== undefined) return `${name} (from ${clip(String(d.source), 30)})`;
+      return name;
+    })}`);
+  }
+  const scales = Array.isArray(spec.scales) ? spec.scales.filter((s) => s !== null && typeof s === "object") : [];
+  if (scales.length) {
+    sections.push(`scales ${list(scales, (s) => `${clip(String(s.name ?? "?"), 30)} (${s.type ?? "linear"})`)}`);
+  }
+  return `Vega chart${titleText(spec.title)}${sections.length ? `: ${sections.join("; ")}` : ""}`;
+}
+
+function summarizeChart(spec) {
+  try {
+    if (typeof spec.$schema === "string" && spec.$schema.includes("/vega-lite/")) {
+      const lines = [];
+      summarizeVegaLiteView(spec, "Vega-Lite ", { encoding: {} }, spec.datasets, 0, lines);
+      return lines.join("\n");
+    }
+    return summarizeVega(spec);
+  } catch {
+    // A summary is a fallback; a spec it doesn't understand still renders.
+    return undefined;
+  }
 }
 
 function isDataFrameLike(obj) {
@@ -95,9 +289,16 @@ function extractDataFrame(df) {
     html += "</tr>";
   }
   html += "</tbody></table>";
+  // Polars has `height`; the row count is left out when there isn't one.
+  const size = [];
+  if (Number.isInteger(df.height)) size.push(`${df.height} ${df.height === 1 ? "row" : "rows"}`);
+  size.push(`${fields.length} ${fields.length === 1 ? "column" : "columns"}`);
+  const columns = fields.slice(0, 20).map((field) => `${clip(String(field.name), 40)} (${field.type})`);
+  if (fields.length > 20) columns.push(`… ${fields.length - 20} more`);
   return {
     "application/vnd.dataresource+json": { data, schema: { fields } },
     "text/html": html,
+    "text/plain": `DataFrame (${size.join(", ")})${columns.length ? `: ${columns.join(", ")}` : ""}`,
   };
 }
 

package/runtime/format.d.mts

@@ -0,0 +1,2 @@
+export function inspect(value: unknown, options?: { depth?: number }): string;
+export function format(...args: unknown[]): string;