@tlockney/cdp-kernel 0.6.0 → 0.7.1

package/runtime/browser-worker.mjs

@@ -0,0 +1,202 @@
+// 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).
+//
+// The page can also offer cells its own features (#384): `host` requests go
+// to the page's handler, and `preload` modules run before the first cell.
+
+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 host page (#384) -----------------------------------------------------
+// Requests to the page's `host` handler (src/browser/target.ts), and events
+// it sends. Preload modules get this object; cells only through them.
+const hostCalls = new Map();
+const hostListeners = new Set();
+let nextHostId = 0;
+
+function hostError(error) {
+  const err = new Error(String(error?.message ?? "the host request failed"));
+  if (typeof error?.name === "string") err.name = error.name;
+  if (error?.code !== undefined) err.code = error.code;
+  return err;
+}
+
+const host = {
+  /** Resolves with the page's answer; aborting `signal` cancels the call on the page too. */
+  request(method, params, { signal, transfer } = {}) {
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    const id = ++nextHostId;
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        hostCalls.delete(id);
+        post({ kind: "host", id, cancel: true });
+        reject(signal.reason);
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      const done = () => signal?.removeEventListener("abort", onAbort);
+      try {
+        globalThis.postMessage({ kind: "host", id, method, params }, transfer ?? []);
+      } catch (err) {
+        done(); // params structured clone can't copy
+        throw err;
+      }
+      hostCalls.set(id, { resolve, reject, done });
+    });
+  },
+  /** Calls `listener(event, value)` for each event the page sends; returns a function that stops it. */
+  onEvent(listener) {
+    hostListeners.add(listener);
+    return () => hostListeners.delete(listener);
+  },
+};
+
+function receiveHost(msg) {
+  if (msg.id === undefined) {
+    for (const listener of hostListeners) {
+      try {
+        listener(msg.event, msg.value);
+      } catch (err) {
+        reportUncaught("Uncaught", err);
+      }
+    }
+    return;
+  }
+  const call = hostCalls.get(msg.id);
+  if (!call) return; // cancelled
+  hostCalls.delete(msg.id);
+  call.done();
+  if (msg.error !== undefined) call.reject(hostError(msg.error));
+  else call.resolve(msg.result);
+}
+
+// Each module is imported in order, and a default export that is a function
+// is called with the host. A module that fails is reported, and the kernel
+// runs without it.
+async function preload(urls, base) {
+  for (const specifier of Array.isArray(urls) ? urls : []) {
+    try {
+      const mod = await import(new URL(specifier, base).href);
+      if (typeof mod.default === "function") await mod.default({ host, jupyter: jupyter.namespace });
+    } catch (err) {
+      reportUncaught(`Preloading ${specifier} failed`, err);
+    }
+  }
+}
+
+// --- 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,
+    // execute_request's user_expressions (#340).
+    formatJson: async (value) => JSON.stringify(await jupyter.namespace.format(value)),
+    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);
+    await preload(req.preload, req.base);
+    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;
+  if (req?.op === "host") return receiveHost(req);
+  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/evaluator.mjs

@@ -56,6 +56,8 @@ export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
       case "broadcast":
         await shim.broadcastResult(request.count, take(request.handle));
         return {};
+      case "format":
+        return { value: await shim.formatJson(request.handle === undefined ? undefined : take(request.handle)) };
       case "describe":
         return { value: shim.describeError(take(request.handle)) };
       case "comm":

package/runtime/format.d.mts

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

package/runtime/format.mjs

@@ -0,0 +1,125 @@
+// A small stand-in for util.inspect and util.format, for targets that have
+// neither: the browser Worker (runtime/browser-worker.mjs). Output follows
+// Node's for the common cases (strings quoted when nested, objects and
+// arrays on one line, Map, Set, Date, Error, class names, circular
+// references), without colours.
+//
+// No imports: this file must load in every target.
+
+const MAX_ITEMS = 100;
+
+// Single quotes, unless the string has some and double quotes or
+// backticks would need no escapes, as util.inspect picks.
+function quote(s) {
+  const q = !s.includes("'") ? "'" : !s.includes('"') ? '"' : !s.includes("`") && !s.includes("${") ? "`" : "'";
+  const escaped = s.replaceAll("\\", "\\\\").replaceAll("\n", "\\n").replaceAll(q, `\\${q}`);
+  return `${q}${escaped}${q}`;
+}
+
+function key(k) {
+  return typeof k === "symbol" ? `[${k.toString()}]` : /^[A-Za-z_$][\w$]*$/.test(k) ? k : quote(k);
+}
+
+function className(value) {
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null) return "[Object: null prototype]";
+  const name = proto.constructor?.name;
+  return name && name !== "Object" ? name : "";
+}
+
+function list(open, items, close, more) {
+  if (more > 0) items.push(`... ${more} more item${more === 1 ? "" : "s"}`);
+  return items.length === 0 ? `${open}${close}` : `${open} ${items.join(", ")} ${close}`;
+}
+
+/** `value` as Node's util.inspect would show it, to `depth` levels. */
+export function inspect(value, { depth = 2 } = {}) {
+  const seen = [];
+  const show = (v, level) => {
+    switch (typeof v) {
+      case "string":
+        return quote(v);
+      case "bigint":
+        return `${v}n`;
+      case "symbol":
+        return v.toString();
+      case "undefined":
+        return "undefined";
+      case "function": {
+        const isClass = /^class\b/.test(Function.prototype.toString.call(v));
+        return isClass ? `[class ${v.name || "(anonymous)"}]` : `[Function${v.name ? `: ${v.name}` : " (anonymous)"}]`;
+      }
+      case "number":
+        return Object.is(v, -0) ? "-0" : String(v);
+      case "boolean":
+        return String(v);
+    }
+    if (v === null) return "null";
+    if (seen.includes(v)) return "[Circular *1]";
+    if (v instanceof Date) return Number.isNaN(v.getTime()) ? "Invalid Date" : v.toISOString();
+    if (v instanceof RegExp) return String(v);
+    if (v instanceof Error) return v.stack ?? `${v.name}: ${v.message}`;
+    if (v instanceof Promise) return "Promise { <unknown> }";
+    if (level > depth) return Array.isArray(v) ? "[Array]" : `[${className(v) || "Object"}]`;
+    seen.push(v);
+    try {
+      if (Array.isArray(v) || ArrayBuffer.isView(v)) {
+        const items = Array.from(v).slice(0, MAX_ITEMS).map((x) => show(x, level + 1));
+        const prefix = Array.isArray(v) ? "" : `${v.constructor.name}(${v.length}) `;
+        return prefix + list("[", items, "]", v.length - items.length);
+      }
+      if (v instanceof Map) {
+        const items = [...v].slice(0, MAX_ITEMS).map(([k, x]) => `${show(k, level + 1)} => ${show(x, level + 1)}`);
+        return `Map(${v.size}) ` + list("{", items, "}", v.size - items.length);
+      }
+      if (v instanceof Set) {
+        const items = [...v].slice(0, MAX_ITEMS).map((x) => show(x, level + 1));
+        return `Set(${v.size}) ` + list("{", items, "}", v.size - items.length);
+      }
+      const keys = Reflect.ownKeys(v).filter((k) => Object.getOwnPropertyDescriptor(v, k)?.enumerable);
+      const items = keys.slice(0, MAX_ITEMS).map((k) => {
+        const d = Object.getOwnPropertyDescriptor(v, k);
+        const shown = d.get || d.set ? `[${d.get ? "Getter" : ""}${d.get && d.set ? "/" : ""}${d.set ? "Setter" : ""}]` : show(d.value, level + 1);
+        return `${key(k)}: ${shown}`;
+      });
+      const name = className(v);
+      return (name ? `${name} ` : "") + list("{", items, "}", keys.length - items.length);
+    } finally {
+      seen.pop();
+    }
+  };
+  return show(value, 0);
+}
+
+/** console.log's formatting: strings as they are, everything else inspected, %s/%d/%i/%f/%o/%O/%j substituted. */
+export function format(...args) {
+  let out = [];
+  let rest = args;
+  if (typeof args[0] === "string" && args.length > 1 && args[0].includes("%")) {
+    let i = 1;
+    const text = args[0].replace(/%[sdifoOjc%]/g, (spec) => {
+      if (spec === "%%") return "%";
+      if (i >= args.length) return spec;
+      const a = args[i++];
+      switch (spec) {
+        case "%s":
+          return typeof a === "string" ? a : inspect(a, { depth: 1 });
+        case "%d":
+        case "%i":
+          return typeof a === "bigint" ? `${a}n` : String(spec === "%i" ? Math.trunc(Number(a)) : Number(a));
+        case "%f":
+          return String(Number(a));
+        case "%j":
+          return JSON.stringify(a);
+        case "%c":
+          return "";
+        default:
+          return inspect(a, { depth: 4 });
+      }
+    });
+    out = [text];
+    rest = args.slice(i);
+  }
+  for (const a of rest) out.push(typeof a === "string" ? a : inspect(a));
+  return out.join(" ");
+}

package/runtime/workerd-worker.mjs

@@ -141,6 +141,8 @@ function install(env) {
     resolvePath,
     barrier: () => 0,
     broadcastResult: jupyter.broadcastResult,
+    // execute_request's user_expressions (#340).
+    formatJson: async (value) => JSON.stringify(await jupyter.namespace.format(value)),
     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);