@tlockney/cdp-kernel 0.6.0 → 0.7.0

package/dist/transform.js

@@ -23,7 +23,14 @@ export const SHIM = "__cdpk";
 // which is what lets a Runtime.terminateExecution from the control session
 // interrupt a busy loop. (Within that dispatch the inspector processes no
 // other messages, so an interrupt would never be seen.)
-const PRELUDE = `'use strict'; await ${SHIM}.tick();\n`;
+//
+// An expression that throws before its first await rejects the replMode
+// result promise at once, inside that dispatch, and a GC before the
+// inspector's then-callback runs fails the evaluate with "Promise was
+// collected" (#329). Yielding first moves the throw into a task, where
+// SETTLE's reasoning applies. The debug console uses YIELD for this.
+export const YIELD = `await ${SHIM}.tick();\n`;
+const PRELUDE = `'use strict'; ${YIELD}`;
 /**
  * Each replMode cell also ends by yielding one macrotask, so the script
  * settles with no other microtasks queued ahead of the inspector's

package/dist/wire.d.ts

@@ -1,35 +1,15 @@
+import { type Header, type JsonObject, type KernelMessage } from "./message.ts";
+export { makeHeader, PROTOCOL_VERSION } from "./message.ts";
+export type { Header, JsonObject, ReceivedHeader } from "./message.ts";
 export declare const DELIMITER: Uint8Array<ArrayBuffer>;
-export declare const PROTOCOL_VERSION = "5.3";
-export type JsonObject = {
-    [key: string]: unknown;
-};
-export interface Header extends JsonObject {
-    msg_id: string;
-    session: string;
-    date: string;
-    username: string;
-    msg_type: string;
-    version: string;
-}
-/** A header as received: the fields the kernel relies on, plus whatever else came. */
-export interface ReceivedHeader extends JsonObject {
-    msg_id: string;
-    msg_type: string;
-}
-export interface Message {
+export interface Message extends KernelMessage {
     identities: Uint8Array[];
     sig: string;
     /** Raw bytes of header, parent_header, metadata, content as received. */
     signedParts: Uint8Array[];
-    header: ReceivedHeader;
-    parentHeader: JsonObject;
-    metadata: JsonObject;
-    content: JsonObject;
-    buffers: Uint8Array[];
 }
 export declare function sign(key: string, parts: Uint8Array[]): string;
 export declare function verify(key: string, parts: Uint8Array[], sig: string): boolean;
-export declare function makeHeader(session: string, msgType: string): Header;
 export interface EncodeOptions {
     /** Defaults to a fresh header; pass one to know its msg_id. */
     header?: Header;

package/dist/wire.js

@@ -4,11 +4,12 @@
 // Copyright 2018-2026 the Deno authors, MIT license. The structure is kept;
 // WebCrypto's async HMAC is replaced with node:crypto's synchronous one.
 import { Buffer } from "node:buffer";
-import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { makeHeader } from "./message.js";
+export { makeHeader, PROTOCOL_VERSION } from "./message.js";
 const ENC = new TextEncoder();
 const DEC = new TextDecoder();
 export const DELIMITER = ENC.encode("<IDS|MSG>");
-export const PROTOCOL_VERSION = "5.3";
 export function sign(key, parts) {
     if (key.length === 0)
         return "";
@@ -29,16 +30,6 @@ export function verify(key, parts, sig) {
     const actual = Buffer.from(sig, "hex");
     return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
-export function makeHeader(session, msgType) {
-    return {
-        msg_id: randomUUID(),
-        session,
-        date: new Date().toISOString(),
-        username: "kernel",
-        msg_type: msgType,
-        version: PROTOCOL_VERSION,
-    };
-}
 export function encodeMessage(session, key, msgType, content, options = {}) {
     const parts = [
         options.header ?? makeHeader(session, msgType),

package/dist/zmq-channels.d.ts

@@ -0,0 +1,14 @@
+import type { ConnectionInfo } from "./kernel.ts";
+import type { ChannelName, KernelChannels, Received } from "./kernel-core.ts";
+import type { OutgoingMessage } from "./message.ts";
+export declare class ZmqChannels implements KernelChannels {
+    #private;
+    readonly ready: Promise<unknown>;
+    constructor(conn: ConnectionInfo, log: (text: string) => void);
+    recv(channel: ChannelName): Promise<Received | null>;
+    shellQueued(): number;
+    reply(channel: ChannelName, peer: string, msg: OutgoingMessage): void;
+    publish(msg: OutgoingMessage): void;
+    stdinPeers(): number;
+    sendStdin(msg: OutgoingMessage): void;
+}

package/dist/zmq-channels.js

@@ -0,0 +1,59 @@
+// KernelChannels over ZeroMQ: the connection file's five ports, with
+// messages framed and signed as src/wire.ts does it.
+import { decodeMessage, encodeMessage, verify } from "./wire.js";
+import { listening, PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
+export class ZmqChannels {
+    ready;
+    #key;
+    #log;
+    #routers;
+    #iopub;
+    constructor(conn, log) {
+        this.#key = conn.key;
+        this.#log = log;
+        const heartbeat = startHeartbeat(conn.hb_port, conn.ip);
+        this.#routers = {
+            shell: new RouterSocket(conn.shell_port, conn.ip),
+            control: new RouterSocket(conn.control_port, conn.ip),
+            stdin: new RouterSocket(conn.stdin_port, conn.ip),
+        };
+        this.#iopub = new PubSocket(conn.iopub_port, conn.ip);
+        // Settles once all five ports are bound (#257).
+        this.ready = Promise.all([heartbeat, ...Object.values(this.#routers).map((r) => r.server), this.#iopub.server].map(listening));
+    }
+    async recv(channel) {
+        const { peer, frames } = await this.#routers[channel].recv();
+        try {
+            const msg = decodeMessage(frames);
+            // Unsigned or forged messages are dropped, as in Deno.
+            return verify(this.#key, msg.signedParts, msg.sig) ? { peer, msg } : null;
+        }
+        catch (err) {
+            this.#log(`error handling message: ${err instanceof Error ? err.stack : err}`);
+            return null;
+        }
+    }
+    shellQueued() {
+        return this.#routers.shell.incoming.size;
+    }
+    #encode(msg) {
+        return encodeMessage(msg.header.session, this.#key, msg.header.msg_type, msg.content, {
+            header: msg.header,
+            parentHeader: msg.parentHeader,
+            metadata: msg.metadata,
+            buffers: msg.buffers,
+        });
+    }
+    reply(channel, peer, msg) {
+        this.#routers[channel].send(peer, this.#encode(msg));
+    }
+    publish(msg) {
+        this.#iopub.send(this.#encode(msg));
+    }
+    stdinPeers() {
+        return this.#routers.stdin.peers.size;
+    }
+    sendStdin(msg) {
+        this.#routers.stdin.sendAll(this.#encode(msg));
+    }
+}

package/package.json

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

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;