@tlockney/cdp-kernel 0.3.0 → 0.5.0

package/dist/ws-client.js

@@ -2,13 +2,14 @@
 // target's session with its driver Worker (#26). The WebSocket that Node
 // and Deno provide can't connect to a Unix socket, and a TCP listener would
 // be reachable by every local process. Text messages only: that's all the
-// session carries.
+// session carries, so binary messages are dropped.
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes } from "node:crypto";
 import { connect } from "node:net";
 const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 export const OP_CONTINUATION = 0x0;
 export const OP_TEXT = 0x1;
+export const OP_BINARY = 0x2;
 export const OP_CLOSE = 0x8;
 export const OP_PING = 0x9;
 export const OP_PONG = 0xa;
@@ -40,14 +41,24 @@ export function encodeFrame(opcode, payload, mask = randomBytes(4)) {
     }
     return out;
 }
-/** Splits a byte stream into frames, holding back a partial one. */
+/**
+ * Splits a byte stream into frames, holding back a partial one. Chunks of a
+ * large frame are only joined once the whole frame has arrived.
+ */
 export class FrameDecoder {
-    #buffer = Buffer.alloc(0);
+    #chunks = [];
+    #length = 0;
+    /** Bytes the frame at the front needs, once its header is known. */
+    #needed = 0;
     push(chunk) {
-        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        this.#chunks.push(chunk);
+        this.#length += chunk.length;
+        if (this.#length < this.#needed)
+            return [];
+        let b = this.#chunks.length === 1 ? this.#chunks[0] : Buffer.concat(this.#chunks, this.#length);
+        this.#needed = 0;
         const frames = [];
         for (;;) {
-            const b = this.#buffer;
             if (b.length < 2)
                 break;
             const masked = (b[1] & 0x80) !== 0;
@@ -68,15 +79,19 @@ export class FrameDecoder {
             const maskAt = offset;
             if (masked)
                 offset += 4;
-            if (b.length < offset + len)
+            if (b.length < offset + len) {
+                this.#needed = offset + len;
                 break;
+            }
             const payload = Buffer.from(b.subarray(offset, offset + len));
             if (masked)
                 for (let i = 0; i < len; i++)
                     payload[i] ^= b[maskAt + (i & 3)];
             frames.push({ fin: (b[0] & 0x80) !== 0, opcode: b[0] & 0x0f, payload });
-            this.#buffer = b.subarray(offset + len);
+            b = b.subarray(offset + len);
         }
+        this.#chunks = b.length ? [b] : [];
+        this.#length = b.length;
         return frames;
     }
 }
@@ -95,6 +110,9 @@ export function connectUnixWebSocket(socketPath, { path = "/", headers = {} } =
         let head = Buffer.alloc(0);
         const decoder = new FrameDecoder();
         let parts = [];
+        // The opcode of the message whose fragments are arriving.
+        let messageOpcode = null;
+        let closeSent = false;
         const finish = () => {
             if (closed)
                 return;
@@ -108,30 +126,45 @@ export function connectUnixWebSocket(socketPath, { path = "/", headers = {} } =
             if (!closed)
                 socket.write(encodeFrame(opcode, payload));
         };
+        const sendClose = (payload) => {
+            if (closeSent)
+                return;
+            closeSent = true;
+            write(OP_CLOSE, payload);
+        };
         const channel = {
             send: (text) => write(OP_TEXT, Buffer.from(text)),
             onMessage: (listener) => void messageListeners.push(listener),
             onClose: (listener) => void closeListeners.push(listener),
             close() {
-                write(OP_CLOSE, Buffer.alloc(0));
+                sendClose(Buffer.alloc(0));
                 socket.end();
             },
         };
         const onFrames = (frames) => {
             for (const frame of frames) {
-                if (frame.opcode === OP_TEXT || frame.opcode === OP_CONTINUATION) {
-                    parts.push(frame.payload);
+                if (frame.opcode === OP_TEXT || frame.opcode === OP_BINARY || frame.opcode === OP_CONTINUATION) {
+                    if (frame.opcode !== OP_CONTINUATION) {
+                        messageOpcode = frame.opcode;
+                        parts = [];
+                    }
+                    if (messageOpcode === OP_TEXT)
+                        parts.push(frame.payload);
                     if (frame.fin) {
-                        const text = Buffer.concat(parts).toString("utf8");
+                        const text = messageOpcode === OP_TEXT ? Buffer.concat(parts).toString("utf8") : null;
                         parts = [];
-                        for (const listener of messageListeners)
-                            listener(text);
+                        messageOpcode = null;
+                        if (text !== null)
+                            for (const listener of messageListeners)
+                                listener(text);
                     }
                 }
                 else if (frame.opcode === OP_PING) {
                     write(OP_PONG, frame.payload);
                 }
                 else if (frame.opcode === OP_CLOSE) {
+                    // Echo the status code, as RFC 6455 section 5.5.1 asks.
+                    sendClose(frame.payload.subarray(0, 2));
                     socket.end();
                 }
             }

package/dist/zmtp.d.ts

@@ -20,6 +20,8 @@ export declare function recvMultipart(reader: SocketReader): Promise<Uint8Array[
 /** Async FIFO with blocking pop. */
 export declare class Queue<T> {
     #private;
+    /** Items waiting to be popped. */
+    get size(): number;
     push(item: T): void;
     pop(): Promise<T>;
 }
@@ -29,7 +31,11 @@ export interface RoutedMessage {
     peer: string;
     frames: Uint8Array[];
 }
-/** ROUTER socket: each TCP connection is one peer with a generated identity. */
+/**
+ * ROUTER socket: each TCP connection is one peer with a generated identity.
+ * Writes ignore socket.write's backpressure signal: node:net buffers the
+ * rest, which is fine for loopback peers that read promptly.
+ */
 export declare class RouterSocket {
     #private;
     readonly incoming: Queue<RoutedMessage>;

package/dist/zmtp.js

@@ -36,6 +36,10 @@ export class SocketReader {
         this.#waiter = null;
         waiter?.();
     }
+    // Each call joins every buffered chunk, so a reader that keeps a large
+    // backlog while small chunks trickle in recopies it per call (quadratic).
+    // Jupyter traffic over loopback arrives in few, large chunks; a chunk
+    // list with an offset would avoid the copies if that ever changes.
     async readExact(n) {
         while (this.#buffered < n) {
             if (this.#error)
@@ -136,11 +140,28 @@ export async function recvMultipart(reader) {
             return frames;
     }
 }
+/** How long a port from the connection file may stay taken before the kernel gives up. */
+const LISTEN_RETRY_MS = 5000;
+const LISTEN_RETRY_INTERVAL_MS = 100;
 function listen(port, host, onConn) {
     const server = createServer((socket) => {
         socket.setNoDelay(true);
         onConn(socket);
     });
+    // The frontend picks these ports by binding and releasing them, so another
+    // socket can take one before the kernel binds it. Wait for it to be freed
+    // rather than die before kernel_info.
+    const deadline = Date.now() + LISTEN_RETRY_MS;
+    const onError = (err) => {
+        if (err.code !== "EADDRINUSE" || Date.now() >= deadline) {
+            server.off("error", onError);
+            server.emit("error", err);
+            return;
+        }
+        setTimeout(() => server.listen(port, host), LISTEN_RETRY_INTERVAL_MS);
+    };
+    server.on("error", onError);
+    server.once("listening", () => server.off("error", onError));
     server.listen(port, host);
     return server;
 }
@@ -148,6 +169,10 @@ function listen(port, host, onConn) {
 export class Queue {
     #items = [];
     #waiters = [];
+    /** Items waiting to be popped. */
+    get size() {
+        return this.#items.length;
+    }
     push(item) {
         const waiter = this.#waiters.shift();
         if (waiter)
@@ -173,7 +198,11 @@ export function startHeartbeat(port, host) {
         })().catch(() => socket.destroy());
     });
 }
-/** ROUTER socket: each TCP connection is one peer with a generated identity. */
+/**
+ * ROUTER socket: each TCP connection is one peer with a generated identity.
+ * Writes ignore socket.write's backpressure signal: node:net buffers the
+ * rest, which is fine for loopback peers that read promptly.
+ */
 export class RouterSocket {
     incoming = new Queue();
     peers = new Map();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.3.0",
-  "description": "Deno's Jupyter kernel, extracted to run notebooks on any V8 runtime over the Chrome DevTools Protocol",
+  "version": "0.5.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>",
   "repository": {
@@ -42,7 +42,8 @@
   "files": [
     "dist/",
     "runtime/*.mjs",
-    "runtime/*.d.mts"
+    "runtime/*.d.mts",
+    "THIRD-PARTY-NOTICES"
   ],
   "publishConfig": {
     "access": "public"
@@ -50,6 +51,10 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "check": "tsc -p tsconfig.json",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:notebooks": "node docs/.vitepress/run-notebooks.ts",
+    "docs:widgets": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/widget_screenshots.py",
     "install:node": "node src/main.ts install --runtime node",
     "install:deno": "node src/main.ts install --runtime deno",
     "install:node-deno": "node src/main.ts install --runtime node --deno-compat",
@@ -57,7 +62,7 @@
     "install:workerd": "node src/main.ts install --runtime workerd",
     "install:celld": "node src/main.ts install --runtime celld",
     "prepack": "npm run build",
-    "test": "node --test test/*.test.ts",
+    "test": "node --test --test-timeout=300000 test/*.test.ts",
     "e2e": "uv run --with nbclient --with nbformat --with jupyter_client python test/e2e.py",
     "test:lab": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/lab_widgets.py"
   },
@@ -69,6 +74,7 @@
   "devDependencies": {
     "@types/node": "^24.19.2",
     "typescript": "^5.9.3",
+    "vitepress": "^1.6.4",
     "workerd": "1.20261015.1",
     "wrangler": "4.151.0"
   }

package/runtime/bootstrap.mjs

@@ -12,6 +12,7 @@
 
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJupyter } from "./display.mjs";
+import { describeValue, inspectPath, resolvePath } from "./introspect.mjs";
 
 const isDeno = typeof globalThis.Deno?.version?.deno === "string";
 const isBun = typeof globalThis.Bun?.version === "string";
@@ -26,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, readFile, writeOut, writeErr, readStdinLine } = await platform();
+const { inspect, inspectPlain, readFile, writeOut, writeErr, readStdinLine } = await platform();
 
 function base64(bytes) {
   let binary = "";
@@ -54,7 +55,12 @@ function barrier(gated = false) {
 function send(payload) {
   const binding = globalThis.__cdpk_send;
   if (typeof binding !== "function") return; // host not attached yet
-  binding(JSON.stringify({ ...payload, barrier: barrier(true) }));
+  // 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)}`);
 }
 
 const jupyter = createJupyter({
@@ -71,6 +77,13 @@ const jupyter = createJupyter({
     const line = readStdinLine();
     if (line === null) return null;
     const reply = JSON.parse(line);
+    if (reply.interrupted === true) {
+      // Interrupted while waiting for the answer: unwind the cell, as
+      // KeyboardInterrupt does in Python's input() (#121).
+      const err = new Error("Execution interrupted");
+      err.name = "Interrupted";
+      throw err;
+    }
     return typeof reply.value === "string" ? reply.value : null;
   },
 });
@@ -122,7 +135,7 @@ function bunResolve(specifier) {
   if (specifier.startsWith("npm:")) pkg = packages.parsePackageSpecifier(specifier.slice(4));
   else if (specifier.startsWith("jsr:")) pkg = packages.jsrToNpm(specifier.slice(4));
   if (pkg) {
-    const { dir, alias } = packages.ensureInstalled(pkg, "bun");
+    const { dir, alias } = packages.ensureInstalled(pkg, "bun", { lockFile: packages.findLockFile(cwd) });
     return Bun.resolveSync(alias + pkg.subpath, dir);
   }
   // Relative, absolute, or a URL scheme such as node:, bun: or file:.
@@ -130,6 +143,24 @@ function bunResolve(specifier) {
   return Bun.resolveSync(specifier, cwd);
 }
 
+// The inspector holds a promise it awaits (callFunctionOn with awaitPromise)
+// only weakly until its then-callback runs, so a GC after the promise
+// settles but before that callback fails the call with "Promise was
+// collected" (#55). hold() keeps the promise until a macrotask after it
+// settles, by which time the inspector's callback has run.
+const held = new Set();
+function hold(value) {
+  const promise = Promise.resolve(value);
+  held.add(promise);
+  const release = () => setTimeout(() => held.delete(promise), 0);
+  promise.then(release, release);
+  return promise;
+}
+
+// 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 = {
   // Cell code awaits this first; see PRELUDE in src/transform.ts.
   tick: () => new Promise((resolve) => setTimeout(resolve, 0)),
@@ -148,7 +179,20 @@ globalThis.__cdpk = {
     resolve: (specifier) => new URL(specifier, replUrl).href,
   },
   barrier,
+  hold,
+  // inspect_request (#10). CDP targets find the value with
+  // throwOnSideEffect and describe it here; Bun resolves the path here
+  // too, by descriptor, so nothing runs.
+  describeForInspect: (value, detail) => describeValue(value, { inspect: inspectPlain, detail }),
+  inspectPath: (path, detail) => inspectPath(path, { inspect: inspectPlain, detail }),
+  resolvePath,
   broadcastResult: jupyter.broadcastResult,
+  // The debugger's rich variable viewer (#18), synchronously: it runs while
+  // the target is paused. A value whose $display is async shows as text.
+  richBundle(value) {
+    const bundle = jupyter.formatNow(value);
+    return JSON.stringify(typeof bundle?.then === "function" ? { "text/plain": inspectPlain(value) } : bundle);
+  },
   // 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) {
@@ -158,7 +202,9 @@ globalThis.__cdpk = {
   },
   describeError(value) {
     if (value instanceof Error) {
-      return JSON.stringify({ name: value.name, message: value.message, stack: value.stack ?? "" });
+      const message = explainError(value.message);
+      const stack = stackOf(value).replace(value.message, () => message);
+      return JSON.stringify({ name: value.name, message, stack });
     }
     return JSON.stringify({ name: "Error", message: inspect(value), stack: "" });
   },
@@ -171,26 +217,48 @@ globalThis.confirm = jupyter.confirm;
 if (isDeno) {
   // Existing Deno notebooks use Deno.jupyter, but outside `deno jupyter`
   // that is a non-configurable getter that throws. The global binding
-  // itself is configurable, so swap in a proxy that answers `jupyter` and
-  // forwards everything else to the real namespace.
+  // itself is configurable, so swap in an object with its own `jupyter`
+  // that inherits everything else from the real namespace. Not a Proxy:
+  // completion can't list a Proxy's properties, and Shift-Tab's
+  // side-effect-free evaluation can't read through one (#132). So
+  // Object.keys(Deno) and console.log(Deno) show only `jupyter`, and
+  // Deno's functions are called with `this` set to this object (they
+  // don't use it).
   const real = globalThis.Deno;
   const descriptor = Object.getOwnPropertyDescriptor(globalThis, "Deno");
-  const proxy = new Proxy(real, {
-    get: (target, key) => (key === "jupyter" ? jupyter.namespace : Reflect.get(target, key, target)),
+  const shim = Object.create(real, {
+    jupyter: { value: jupyter.namespace, enumerable: true, configurable: true, writable: true },
   });
-  Object.defineProperty(globalThis, "Deno", { ...descriptor, value: proxy });
+  Object.defineProperty(globalThis, "Deno", { ...descriptor, value: shim });
 } else if (process.env.CDPK_DENO_COMPAT === "1" && globalThis.Deno === undefined) {
   // Opt-in (install --deno-compat): a Deno namespace for notebooks written
   // against `deno jupyter`. See runtime/deno-compat.mjs for the trade-off.
   // Absolute URL: the resolve hook re-parents this module's relative
   // imports to the notebook directory.
-  const { createDenoShim } = await import(new URL("./deno-compat.mjs", import.meta.url).href);
-  globalThis.Deno = createDenoShim({ jupyter: jupyter.namespace });
+  const { createDenoShim, explainMissing } = await import(new URL("./deno-compat.mjs", import.meta.url).href);
+  const shim = createDenoShim({ jupyter: jupyter.namespace });
+  globalThis.Deno = shim;
+  explainError = (text) => explainMissing(text, shim);
+}
+
+/**
+ * An error's stack, with its first line naming the error. Bun now and then
+ * (about one throw in twenty, #216) records a stack whose first line is a
+ * bare "Error", though name and message are set; the frames are right, so
+ * only the header is rebuilt.
+ */
+function stackOf(err) {
+  const stack = err.stack;
+  if (typeof stack !== "string") return "";
+  const nl = stack.indexOf("\n");
+  const first = nl === -1 ? stack : stack.slice(0, nl);
+  if (first !== "Error" || !err.message) return stack;
+  return `${err.name}: ${err.message}${nl === -1 ? "" : stack.slice(nl)}`;
 }
 
 // An error thrown later by a cell's timer or promise must not kill the kernel.
 function reportUncaught(kind, err) {
-  writeErr(`${kind}: ${err instanceof Error ? (err.stack ?? err.message) : inspect(err)}\n`);
+  writeErr(`${kind}: ${explainError(err instanceof Error ? (stackOf(err) || err.message) : inspect(err))}\n`);
 }
 if (isDeno) {
   globalThis.addEventListener("unhandledrejection", (e) => {
@@ -209,6 +277,29 @@ if (isDeno) {
 // Keep the event loop alive between cells.
 setInterval(() => {}, 1 << 30);
 
+// A host killed by SIGKILL can't stop its runtime, and nothing visible to
+// JS here changes when its inspector sessions drop, so watch for the host
+// itself going: reparented, or no longer there (#219). Bun exits on its
+// channel's EOF instead.
+if (!isBun) {
+  // Held here, so a cell that reassigns them can't break the watch.
+  const proc = process;
+  const exit = process.exit.bind(process);
+  const host = proc.ppid;
+  const hostGone = () => {
+    if (proc.ppid !== host) return true;
+    try {
+      proc.kill(host, 0);
+      return false;
+    } catch (err) {
+      return err?.code === "ESRCH";
+    }
+  };
+  setInterval(() => {
+    if (hostGone()) exit(1);
+  }, 2000);
+}
+
 if (isBun) {
   const { startChannel } = await import("./bun-channel.mjs");
   const { createHandler } = await import("./evaluator.mjs");
@@ -222,6 +313,7 @@ async function platform() {
     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)),
@@ -231,8 +323,17 @@ async function platform() {
   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
+  // never reach the host (#131). Blocking writes finish before readSync
+  // starts, as Node already does on Windows. Bun has no _handle and needs
+  // its own fix (#180).
+  if (isBun) await syncBunOutput();
+  else for (const stream of [process.stdout, process.stderr]) stream._handle?.setBlocking?.(true);
   return {
     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),
@@ -250,6 +351,31 @@ async function platform() {
   };
 }
 
+// Bun makes stdout and stderr non-blocking once process.stdout or
+// process.stderr exists, and then queues what doesn't fit in the pipe for
+// its event loop, console.log's output included. input() blocks the main
+// thread in readSync, so queued output, and the input_request's barrier
+// marker after it, would never reach the host (#180). Here every write
+// finishes before it returns: process.stdout.write and process.stderr.write
+// write through, and console is Node's Console over them, so console output
+// is formatted as on Node.
+async function syncBunOutput() {
+  const { writeAll } = await import("./bun-channel.mjs");
+  const { Console } = await import("node:console");
+  for (const [stream, fd] of [[process.stdout, 1], [process.stderr, 2]]) {
+    stream.write = (chunk, encoding, callback) => {
+      if (typeof encoding === "function") [callback, encoding] = [encoding, undefined];
+      writeAll(fd, typeof chunk === "string" ? Buffer.from(chunk, encoding) : chunk);
+      if (callback) process.nextTick(callback);
+      return true;
+    };
+  }
+  const sync = new Console({ stdout: process.stdout, stderr: process.stderr, colorMode: true });
+  for (const key of Object.keys(console)) {
+    if (typeof sync[key] === "function") console[key] = sync[key].bind(sync);
+  }
+}
+
 function readLine(nextByte) {
   const bytes = [];
   for (;;) {

package/runtime/bun-channel.d.mts

@@ -1,3 +1,6 @@
 import type { Handler } from "./evaluator.mjs";
 
 export function startChannel(handle: Handler, ready: { [key: string]: unknown }, fd?: number): void;
+
+/** Writes all of `text` to `fd` before returning, even if the fd is non-blocking. */
+export function writeAll(fd: number, text: string | Uint8Array): void;

package/runtime/bun-channel.mjs

@@ -14,8 +14,8 @@ import fs from "node:fs";
 const CHANNEL_FD = 3;
 
 /** Synchronous, like a CDP binding call, so output order is kept. */
-function writeAll(fd, text) {
-  const bytes = Buffer.from(text);
+export function writeAll(fd, text) {
+  const bytes = typeof text === "string" ? Buffer.from(text) : Buffer.from(text.buffer, text.byteOffset, text.byteLength);
   for (let offset = 0; offset < bytes.length;) {
     try {
       offset += fs.writeSync(fd, bytes, offset);

package/runtime/comm.mjs

@@ -89,7 +89,17 @@ export function createComms(send, newId = () => crypto.randomUUID()) {
     if (msgType === "comm_open") {
       const handler = targets.get(content.target_name);
       if (!handler) return false;
-      await handler(track(content.comm_id, content.target_name), msg);
+      const comm = track(content.comm_id, content.target_name);
+      try {
+        await handler(comm, msg);
+      } catch (err) {
+        // The host answers a failed comm_open with comm_close, so the comm
+        // is gone on the frontend: drop it here too, without running close
+        // handlers or sending anything (#137).
+        comm.closed = true;
+        forget(comm.id);
+        throw err;
+      }
       return true;
     }
     const comm = comms.get(content.comm_id);

package/runtime/deno-compat.d.mts

@@ -114,3 +114,5 @@ export interface DenoShim {
 
 export function denoError<E>(err: E): E | NotFound | AlreadyExists | PermissionDenied | IsADirectory | NotADirectory;
 export function createDenoShim(options: { jupyter: unknown }): DenoShim;
+/** Adds the cause to "Deno.x is not a function" when `shim` lacks `x`. */
+export function explainMissing(message: string, shim: object): string;

package/runtime/deno-compat.mjs

@@ -7,7 +7,8 @@
 // shim installed they take their Deno code paths, which may call APIs not
 // covered here (Deno.serve, Deno.Command, Deno.openKv, permissions...).
 // Uncovered APIs are simply absent rather than throwing on access, so
-// feature checks like `typeof Deno.serve === "function"` still work.
+// feature checks like `typeof Deno.serve === "function"` still work. The
+// error from calling one says so instead (explainMissing, #172).
 
 import fs from "node:fs";
 import fsp from "node:fs/promises";
@@ -100,6 +101,18 @@ const writeFlag = (options) => (options?.append ? "a" : options?.createNew ? "wx
 const OS_NAMES = { darwin: "darwin", linux: "linux", win32: "windows", freebsd: "freebsd" };
 const ARCH_NAMES = { arm64: "aarch64", x64: "x86_64" };
 
+const MEMBERS_DOC = "https://cdp-kernel.org/docs/jupyter-api#notebooks-written-for-deno";
+
+/**
+ * Adds the cause to V8's "Deno.serve is not a function" when `shim` lacks
+ * that member (#172), or returns `message` unchanged.
+ */
+export function explainMissing(message, shim) {
+  return message.replace(/\b(Deno\.([\w$]+)) is not a (?:function|constructor)\b/, (all, expr, name) =>
+    name in shim ? all : `${all}: ${expr} is not implemented by cdp-kernel's --deno-compat namespace (see ${MEMBERS_DOC})`
+  );
+}
+
 export function createDenoShim({ jupyter }) {
   return {
     jupyter,
@@ -161,7 +174,9 @@ export function createDenoShim({ jupyter }) {
     rename: async((from, to) => fsp.rename(toPath(from), toPath(to))),
     renameSync: sync((from, to) => fs.renameSync(toPath(from), toPath(to))),
     realPath: async((p) => fsp.realpath(toPath(p))),
-    realPathSync: sync((p) => fs.realpathSync(toPath(p))),
+    // The native call, like fsp.realpath above: the JavaScript one leaves
+    // Windows 8.3 names (RUNNER~1) unexpanded, so the two disagreed (#32).
+    realPathSync: sync((p) => fs.realpathSync.native(toPath(p))),
     makeTempDir: async((options) =>
       fsp.mkdtemp(path.join(options?.dir ?? os.tmpdir(), options?.prefix ?? "deno-"))
     ),

package/runtime/display.d.mts

@@ -47,6 +47,8 @@ export interface JupyterNamespace {
 export interface Jupyter {
   namespace: JupyterNamespace;
   broadcastResult(executionCount: number, result: unknown): Promise<void>;
+  /** format without awaiting; a $display method's promise is returned as is. */
+  formatNow(obj: unknown): unknown;
   confirm(message?: string): boolean;
   prompt(message?: string, defaultValue?: string, options?: { password?: boolean }): string | null;
   /** Routes a frontend comm message into the kernel's comms. */

package/runtime/display.mjs

@@ -146,7 +146,14 @@ function isMediaBundle(obj) {
  */
 export function createJupyter(host) {
   async function format(obj) {
-    if (hasDisplaySymbol(obj)) return await obj[$display]();
+    return await formatNow(obj);
+  }
+
+  // format without awaiting: the debugger's variable viewer formats values
+  // while the target is paused, when no promise settles (#18). A $display
+  // method's promise is the caller's to handle.
+  function formatNow(obj) {
+    if (hasDisplaySymbol(obj)) return obj[$display]();
     if (typeof obj !== "object" || obj === null) return { "text/plain": host.inspect(obj) };
     if (isCanvasLike(obj)) {
       const [prefix, data] = obj.toDataURL().split(",");
@@ -173,7 +180,14 @@ export function createJupyter(host) {
   }
 
   function image(obj) {
-    if (typeof obj === "string") obj = host.readFile(obj);
+    if (typeof obj === "string") {
+      // As Deno does: a path that can't be read gets the TypeError below.
+      try {
+        obj = host.readFile(obj);
+      } catch {
+        // fall through
+      }
+    }
     if (isJpg(obj)) return { [$display]: () => ({ "image/jpeg": host.base64(obj) }) };
     if (isPng(obj)) return { [$display]: () => ({ "image/png": host.base64(obj) }) };
     throw new TypeError(
@@ -240,6 +254,7 @@ export function createJupyter(host) {
       widget: createWidgetFactory(comms.api, $display),
     },
     broadcastResult,
+    formatNow,
     confirm,
     prompt,
     commDispatch: comms.dispatch,

package/runtime/evaluator.d.mts

@@ -4,6 +4,10 @@ export interface EvaluatorShim {
   describeError(value: unknown): string;
   commDispatch(msgType: string, content: object, metadata: object, buffers64: string[]): Promise<unknown>;
   barrier(): number;
+  /** inspect_request's text for a dotted path, or null (#10). */
+  inspectPath(path: string, detail: number): string | null;
+  /** Resolves a dotted path without running getters; see introspect.mjs. */
+  resolvePath?(path: string): import("./introspect.mjs").Resolved;
 }
 
 /** A request from the host: an `op` plus its parameters. */