@tlockney/cdp-kernel 0.3.0 → 0.5.0

package/dist/sourcemap.js

@@ -0,0 +1,86 @@
+// Line mapping between a cell as written and the script that runs, for the
+// debugger (#18): a breakpoint set on a cell's line must land on the line
+// esbuild's output put it on, and a paused frame must report the line the
+// user wrote. Only lines: Jupyter's breakpoints are per line.
+const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const DIGIT = new Map([...BASE64].map((c, i) => [c, i]));
+/** One segment's VLQ fields: generated column, source, line, column, name. */
+export function decodeVlq(segment) {
+    const values = [];
+    let value = 0;
+    let shift = 0;
+    for (const char of segment) {
+        const digit = DIGIT.get(char);
+        if (digit === undefined)
+            throw new Error(`bad base64 VLQ digit ${JSON.stringify(char)}`);
+        value += (digit & 31) << shift;
+        if (digit & 32) {
+            shift += 5;
+            continue;
+        }
+        values.push(value & 1 ? -(value >>> 1) : value >>> 1);
+        value = 0;
+        shift = 0;
+    }
+    return values;
+}
+/**
+ * For each generated line (0-based), the first original line (0-based) a
+ * segment on it maps to, or -1. Source-map fields are relative to the
+ * previous segment's; only the original line is tracked.
+ */
+export function generatedToOriginalLines(mappings) {
+    const lines = [];
+    let original = 0;
+    for (const line of mappings.split(";")) {
+        let first = -1;
+        for (const segment of line.split(",")) {
+            if (!segment)
+                continue;
+            const fields = decodeVlq(segment);
+            if (fields.length >= 4) {
+                original += fields[2];
+                if (first === -1)
+                    first = original;
+            }
+        }
+        lines.push(first);
+    }
+    return lines;
+}
+/** Both directions between the lines of a cell and of its script (0-based). */
+export class LineMap {
+    #toOriginal;
+    #toGenerated = new Map();
+    /** `offset`: lines the script adds before esbuild's output (the prelude). */
+    constructor(mappings, offset = 0) {
+        const fromEsbuild = generatedToOriginalLines(mappings);
+        this.#toOriginal = [...Array(offset).fill(-1), ...fromEsbuild];
+        this.#toOriginal.forEach((original, generated) => {
+            if (original !== -1 && !this.#toGenerated.has(original))
+                this.#toGenerated.set(original, generated);
+        });
+    }
+    /** The cell line a script line came from: its own mapping, or the nearest one above. */
+    toOriginal(generated) {
+        for (let line = Math.min(generated, this.#toOriginal.length - 1); line >= 0; line--) {
+            if (this.#toOriginal[line] !== -1)
+                return this.#toOriginal[line];
+        }
+        return 0;
+    }
+    /**
+     * The script line for a cell line, or for the next cell line that has
+     * code (a breakpoint on a blank or comment line moves down, as debuggers
+     * do), or null past the end.
+     */
+    toGenerated(original) {
+        const last = Math.max(-1, ...this.#toGenerated.keys());
+        for (let line = original; line <= last; line++) {
+            const generated = this.#toGenerated.get(line);
+            if (generated !== undefined)
+                return generated;
+        }
+        return null;
+    }
+}

package/dist/target.d.ts

@@ -1,8 +1,9 @@
 import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
 import { type CellTransformOptions, transformCell } from "./transform.ts";
+import type { DebugChannel } from "./debugger.ts";
 /** Targets driven over CDP. */
 export type CdpRuntime = "node" | "deno";
-/** Bun and workerd have their own backends: src/bun-target.ts, src/workerd-target.ts. */
+/** Bun, workerd and celld have their own backends: src/bun-target.ts, src/workerd-target.ts, src/celld-target.ts. */
 export type RuntimeName = CdpRuntime | "bun" | "workerd" | "celld";
 /** What the kernel needs from a target runtime. */
 export interface KernelTarget {
@@ -37,7 +38,12 @@ export interface KernelTarget {
     }>;
     propertyNames(expression: string): Promise<string[]>;
     lexicalNames(): Promise<string[]>;
-    replyInput(value: string | null): void;
+    /** inspect_request (#10): text describing a dotted path's value, without running anything. */
+    inspect(path: string, detail: number): Promise<string | null>;
+    /** The Debugger domain, on targets driven over CDP (#18). */
+    readonly debug?: DebugChannel;
+    /** Answers the target's pending prompt; `interrupted` makes it throw instead (#121). */
+    replyInput(value: string | null, interrupted?: boolean): void;
     kill(): void;
 }
 export interface LaunchOptions {
@@ -51,6 +57,13 @@ export declare function launchCommand(runtime: CdpRuntime, bootstrap: string, {
     cmd: string;
     args: string[];
 };
+/**
+ * The esbuild binary this host's esbuild runs, for a Node target to compile
+ * imported TypeScript Node can't strip (#73); null when it can't be found.
+ * Resolved from esbuild's own location, so it's found in a node_modules
+ * install and in Deno's npm cache alike.
+ */
+export declare function esbuildBinary(resolve?: (specifier: string) => string, platform?: string, arch?: string): string | null;
 /** Messages the bootstrap sends through the CDP binding. */
 export type TargetMessage = {
     kind: "iopub";
@@ -65,6 +78,8 @@ export type TargetMessage = {
     password: boolean;
     barrier: number;
 };
+/** The parsed value, or undefined for text that isn't JSON. */
+export declare function parseJson(text: string): unknown;
 export declare function isTargetMessage(value: unknown): value is TargetMessage;
 /**
  * Splits one output pipe into text and barrier markers, and releases them
@@ -83,6 +98,19 @@ export declare class PipeDemux {
     /** Release everything (the process died). */
     close(): void;
 }
+/**
+ * Removes the runtime's own stderr lines (see INSPECTOR_CHATTER) and passes
+ * everything else on. A chatter line can arrive split across chunks, so a
+ * trailing partial line that could still turn out to be one is held back
+ * until its newline arrives; any other partial line passes straight through.
+ */
+export declare class StderrFilter {
+    #private;
+    constructor(runtime: CdpRuntime, emit: (text: string) => void);
+    push(chunk: string): void;
+    /** Releases a held partial line (the process died). */
+    flush(): void;
+}
 /** Promises keyed by barrier number, resolvable before or after first use. */
 export declare class Gates {
     #private;
@@ -113,7 +141,10 @@ export declare class Target implements KernelTarget {
         executable?: string;
         denoCompat?: boolean;
         denoConfig?: string;
+        startTimeoutMs?: number;
     }): Promise<Target>;
+    /** The Debugger domain on this target's session, for src/debugger.ts. */
+    get debug(): DebugChannel;
     /** Resolves once all output and messages sent so far have been delivered. */
     flush(): Promise<void>;
     /** Runs transformed cell code. Rejects with Interrupted after interrupt(). */
@@ -126,6 +157,10 @@ export declare class Target implements KernelTarget {
      * evaluate is abandoned here and the session stays usable.
      */
     interrupt(): Promise<void>;
+    /**
+     * For synchronous functions. With awaitPromise the inspector would wrap
+     * even a plain return value in a promise it holds only weakly (#55).
+     */
     callFunctionOn(functionDeclaration: string, args: CdpParams[]): Promise<CdpParams>;
     /** The broadcastResult step of Deno's execute flow (jupyter/mod.rs). */
     broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
@@ -149,7 +184,8 @@ export declare class Target implements KernelTarget {
         stack: string;
     }>;
     propertyNames(expression: string): Promise<string[]>;
+    inspect(path: string, detail: number): Promise<string | null>;
     lexicalNames(): Promise<string[]>;
-    replyInput(value: string | null): void;
+    replyInput(value: string | null, interrupted?: boolean): void;
     kill(): void;
 }

package/dist/target.js

@@ -4,17 +4,33 @@
 import { Buffer } from "node:buffer";
 import process from "node:process";
 import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { asEvaluateResult, CdpAbandoned, CdpSession } from "./cdp.js";
 import { SHIM, transformCell } from "./transform.js";
 import { hostRuntime, isInsideNodeModules, runtimeDir } from "./package.js";
+import { killOnExit } from "./children.js";
 const BINDING = "__cdpk_send";
+/** How long a target may take from spawn to a usable session. */
+const START_TIMEOUT_MS = 60_000;
 const MARKER_RE = /\x1b\[cdpk:(\d+)(m?)\]\x1b/;
 const MAX_MARKER_LEN = 24;
 // Lines the runtimes print to stderr on their own: inspector notices, and
 // Deno's npm/jsr "Download https://..." progress (which `deno jupyter`
-// sends to the server log rather than the notebook).
-const INSPECTOR_CHATTER = /^(?:\x1b\[[0-9;]*m)*(Debugger listening on |Debugger attached\.|For help, see: |Visit chrome:\/\/inspect|Waiting for the debugger to disconnect|Download(?:\x1b\[[0-9;]*m)* https?:\/\/).*\n/gm;
+// sends to the server log rather than the notebook). Each entry is the
+// line's start once colour codes are removed.
+const INSPECTOR_CHATTER = [
+    "Debugger listening on ",
+    "Debugger attached.",
+    "For help, see: https://nodejs.org/",
+    "Visit chrome://inspect",
+    "Waiting for the debugger to disconnect",
+];
+const DENO_CHATTER = [...INSPECTOR_CHATTER, "Download http://", "Download https://"];
+const ANSI_SGR = /\x1b\[[0-9;]*m/g;
+/** A colour code cut off at the end of a chunk. */
+const PARTIAL_SGR = /\x1b(?:\[[0-9;]*)?$/;
 /** `bootstrap` is the local path of runtime/bootstrap.mjs (see runtimeDir). */
 export function launchCommand(runtime, bootstrap, { executable, denoConfig } = {}) {
     // The CDP WebSocket has no authentication, so its URL must stay private:
@@ -41,6 +57,33 @@ export function launchCommand(runtime, bootstrap, { executable, denoConfig } = {
     const node = hostRuntime() === "node" ? process.execPath : "node";
     return { cmd: executable ?? node, args: [...inspect, bootstrap] };
 }
+/**
+ * The esbuild binary this host's esbuild runs, for a Node target to compile
+ * imported TypeScript Node can't strip (#73); null when it can't be found.
+ * Resolved from esbuild's own location, so it's found in a node_modules
+ * install and in Deno's npm cache alike.
+ */
+export function esbuildBinary(resolve = import.meta.resolve, platform = process.platform, arch = process.arch) {
+    if (process.env.ESBUILD_BINARY_PATH)
+        return process.env.ESBUILD_BINARY_PATH;
+    const subpath = platform === "win32" ? "esbuild.exe" : "bin/esbuild";
+    try {
+        const main = fileURLToPath(resolve("esbuild"));
+        return createRequire(main).resolve(`@esbuild/${platform}-${arch}/${subpath}`);
+    }
+    catch {
+        return null;
+    }
+}
+/** The parsed value, or undefined for text that isn't JSON. */
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function isTargetMessage(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -139,6 +182,66 @@ export class PipeDemux {
         void this.#pump();
     }
 }
+/**
+ * Removes the runtime's own stderr lines (see INSPECTOR_CHATTER) and passes
+ * everything else on. A chatter line can arrive split across chunks, so a
+ * trailing partial line that could still turn out to be one is held back
+ * until its newline arrives; any other partial line passes straight through.
+ */
+export class StderrFilter {
+    #starts;
+    #emit;
+    #held = "";
+    #atLineStart = true;
+    constructor(runtime, emit) {
+        this.#starts = runtime === "deno" ? DENO_CHATTER : INSPECTOR_CHATTER;
+        this.#emit = emit;
+    }
+    push(chunk) {
+        let text = this.#held + chunk;
+        this.#held = "";
+        let out = "";
+        if (!this.#atLineStart) {
+            // The rest of a line that already went out unfiltered.
+            const nl = text.indexOf("\n");
+            if (nl === -1) {
+                this.#emit(text);
+                return;
+            }
+            out = text.slice(0, nl + 1);
+            text = text.slice(nl + 1);
+        }
+        const lines = text.split("\n");
+        const last = lines.pop();
+        for (const line of lines)
+            if (!this.#isChatter(line, false))
+                out += line + "\n";
+        if (last && this.#isChatter(last, true))
+            this.#held = last;
+        else
+            out += last;
+        this.#atLineStart = last === "" || this.#held !== "";
+        if (out)
+            this.#emit(out);
+    }
+    /** Releases a held partial line (the process died). */
+    flush() {
+        if (this.#held)
+            this.#emit(this.#held);
+        this.#held = "";
+        this.#atLineStart = true;
+    }
+    /** Whether `line` is chatter or, when `partial`, could still become chatter. */
+    #isChatter(line, partial) {
+        let plain = line.replace(ANSI_SGR, "");
+        if (partial)
+            plain = plain.replace(PARTIAL_SGR, "");
+        // Any other escape may be a PipeDemux marker, which must never be dropped or held.
+        if (plain.includes("\x1b"))
+            return false;
+        return this.#starts.some((start) => plain.startsWith(start) || (partial && start.startsWith(plain)));
+    }
+}
 /** Promises keyed by barrier number, resolvable before or after first use. */
 export class Gates {
     #map = new Map();
@@ -167,6 +270,12 @@ export class Gates {
 export class Interrupted extends Error {
     name = "Interrupted";
 }
+/** A catch handler: a call interrupt() abandoned becomes Interrupted. */
+function interrupted(what) {
+    return (err) => {
+        throw err instanceof CdpAbandoned ? new Interrupted(`${what} interrupted`) : err;
+    };
+}
 export class Target {
     runtime;
     transform = transformCell;
@@ -179,10 +288,21 @@ export class Target {
     #contextId;
     #messages = Promise.resolve();
     #interrupted = false;
+    #paused = false;
+    /** Set once the main context is gone: the runtime is exiting (#130). */
+    #exiting = false;
+    #exited;
+    #baselineGlobals = new Set();
     versions;
     constructor(runtime, child, shell, control, stdout, stderr, gates, contextId, versions) {
         this.runtime = runtime;
         this.#child = child;
+        this.#exited = new Promise((resolve) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                resolve();
+            else
+                child.once("exit", () => resolve());
+        });
         this.#shell = shell;
         this.#control = control;
         this.#stdout = stdout;
@@ -206,18 +326,41 @@ export class Target {
             env.CDPK_DENO_COMPAT = "1";
         if (runtime === "deno" && options.denoConfig !== undefined)
             env.CDPK_DENO_PROJECT = "1";
+        const esbuild = runtime === "node" ? esbuildBinary() : null;
+        if (esbuild !== null)
+            env.CDPK_ESBUILD_BINARY = esbuild;
         delete env.NO_COLOR;
         const child = spawn(cmd, args, { cwd: options.cwd, stdio: ["pipe", "pipe", "pipe"], env });
+        killOnExit(child);
+        // A start that fails or stalls must not leave the runtime running: its
+        // pipes and inspector sockets would keep this process alive (#52).
+        const sessions = [];
+        const timeoutMs = options.startTimeoutMs ?? START_TIMEOUT_MS;
+        let timer;
+        const stalled = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${cmd} did not start within ${timeoutMs / 1000}s`)), timeoutMs);
+        });
+        try {
+            return await Promise.race([Target.#start(runtime, events, cmd, child, sessions), stalled]);
+        }
+        catch (error) {
+            for (const session of sessions)
+                session.close();
+            child.kill();
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    static async #start(runtime, events, cmd, child, sessions) {
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
         const gates = new Gates();
         const stdout = new PipeDemux((text) => events.stream("stdout", text), (n) => gates.wait(n));
         const stderr = new PipeDemux((text) => events.stream("stderr", text), (n) => gates.wait(n));
-        const pushStderr = (chunk) => {
-            const text = chunk.replace(INSPECTOR_CHATTER, "");
-            if (text)
-                stderr.push(text);
-        };
+        const filter = new StderrFilter(runtime, (text) => stderr.push(text));
+        const pushStderr = (chunk) => filter.push(chunk);
         // Until the inspector URL appears, stderr carries the runtime's banner.
         const wsUrl = await new Promise((resolve, reject) => {
             let banner = "";
@@ -238,12 +381,15 @@ export class Target {
         child.stdout.on("data", (c) => stdout.push(c));
         child.once("exit", (code) => {
             gates.openAll();
+            filter.flush();
             stdout.close();
             stderr.close();
             events.exit(code);
         });
         const shell = await CdpSession.connect(wsUrl);
+        sessions.push(shell);
         const control = await CdpSession.connect(wsUrl);
+        sessions.push(control);
         const contextReady = new Promise((resolve) => {
             shell.on("Runtime.executionContextCreated", (params) => {
                 const context = params.context;
@@ -255,24 +401,54 @@ export class Target {
         await shell.send("Runtime.addBinding", { name: BINDING });
         const contextId = await contextReady;
         const target = new Target(runtime, child, shell, control, stdout, stderr, gates, contextId, { runtime: "", engine: "" });
+        // process.exit() or Deno.exit() destroys the context, then the runtime
+        // waits for its inspector clients to disconnect before it exits. Let go,
+        // so it exits and the kernel starts a fresh one (#130).
+        shell.on("Runtime.executionContextDestroyed", (params) => {
+            if (params.executionContextId === contextId)
+                target.#onExit();
+        });
         shell.on("Runtime.bindingCalled", (params) => {
             if (params.name !== BINDING || typeof params.payload !== "string")
                 return;
-            const msg = JSON.parse(params.payload);
+            // __cdpk_send is an ordinary global, so a cell can call it with
+            // anything; that mustn't take the host down (#122).
+            const msg = parseJson(params.payload);
             if (isTargetMessage(msg))
                 target.#deliver(msg, events);
         });
-        // Wait for the bootstrap's top-level await to finish installing the shim.
-        for (let i = 0; i < 200; i++) {
-            const probe = await target.#evaluateRaw(`typeof globalThis.${SHIM}?.tick === "function"`);
+        // Wait for the bootstrap's top-level await to finish installing the
+        // shim. There is no cap here: launch's start timeout bounds the wait and
+        // kills the child, so a slow bootstrap never yields a target without
+        // the shim (#134).
+        for (;;) {
+            const probe = await target.#evaluateSync(`typeof globalThis.${SHIM}?.tick === "function"`);
             if (probe.result.value === true)
                 break;
             await new Promise((r) => setTimeout(r, 25));
         }
-        const versions = await target.#evaluateRaw(`JSON.stringify(typeof Deno !== "undefined" ? { runtime: Deno.version.deno, engine: "V8 " + Deno.version.v8 } : { runtime: process.versions.node, engine: "V8 " + process.versions.v8 })`);
+        const versions = await target.#evaluateSync(`JSON.stringify(typeof Deno !== "undefined" ? { runtime: Deno.version.deno, engine: "V8 " + Deno.version.v8 } : { runtime: process.versions.node, engine: "V8 " + process.versions.v8 })`);
         Object.assign(target.versions, JSON.parse(String(versions.result.value)));
+        // The runtime's own enumerable globals, before any cell: the debugger's
+        // variable views show only what cells added (#18).
+        const globals = asEvaluateResult(await shell.send("Runtime.evaluate", { expression: "Object.keys(globalThis)", contextId, returnByValue: true }));
+        const names = globals.result.value;
+        if (Array.isArray(names))
+            for (const name of names)
+                target.#baselineGlobals.add(String(name));
+        shell.on("Debugger.paused", () => (target.#paused = true));
+        shell.on("Debugger.resumed", () => (target.#paused = false));
         return target;
     }
+    /** The Debugger domain on this target's session, for src/debugger.ts. */
+    get debug() {
+        return {
+            send: (method, params = {}) => this.#shell.send(method, params),
+            on: (method, listener) => this.#shell.on(method, listener),
+            contextId: this.#contextId,
+            baselineGlobals: this.#baselineGlobals,
+        };
+    }
     // Binding messages wait until both pipes have caught up to their marker,
     // and are delivered strictly in order.
     #deliver(msg, events) {
@@ -284,11 +460,23 @@ export class Target {
     }
     /** Resolves once all output and messages sent so far have been delivered. */
     async flush() {
-        const n = await this.#evaluateRaw(`${SHIM}.barrier()`);
+        const n = await this.#evaluateSync(`${SHIM}.barrier()`).catch(interrupted("Execution"));
         const barrier = Number(n.result.value);
         await Promise.all([this.#stdout.waitFor(barrier), this.#stderr.waitFor(barrier)]);
         await this.#messages;
     }
+    /**
+     * For expressions that return a value without awaiting. With replMode or
+     * awaitPromise, the inspector holds the result promise only weakly until
+     * its then-callback runs, even when the expression returns a plain value:
+     * a GC in that window fails the call with "Promise was collected" (#50).
+     * A plain evaluate returns the value directly.
+     */
+    #evaluateSync(expression) {
+        return this.#shell
+            .send("Runtime.evaluate", { expression, contextId: this.#contextId, returnByValue: true })
+            .then(asEvaluateResult);
+    }
     #evaluateRaw(expression, session = this.#shell) {
         return session
             .send("Runtime.evaluate", { expression, contextId: this.#contextId, replMode: true, awaitPromise: true })
@@ -303,9 +491,27 @@ export class Target {
         catch (err) {
             if (err instanceof CdpAbandoned || this.#interrupted)
                 throw new Interrupted("Execution interrupted");
+            if (this.#exiting) {
+                // The child's exit, which drops this target in the kernel, comes
+                // first, so the next cell starts a fresh one.
+                await this.#exited;
+                throw new Error(`${this.runtime} exited`);
+            }
             throw err;
         }
     }
+    #onExit() {
+        if (this.#exiting)
+            return;
+        this.#exiting = true;
+        this.#shell.close();
+        this.#control.close();
+        // In case it still doesn't exit once both sessions are gone.
+        setTimeout(() => {
+            if (this.#child.exitCode === null && this.#child.signalCode === null)
+                this.#child.kill("SIGKILL");
+        }, 2000).unref();
+    }
     /**
      * Deno calls IsolateHandle::terminate_execution from another thread. The
      * CDP equivalent is Runtime.terminateExecution, sent on a second session
@@ -315,14 +521,33 @@ export class Target {
      */
     async interrupt() {
         this.#interrupted = true;
+        // A paused isolate runs nothing to terminate: let it go first (#18).
+        if (this.#paused)
+            await this.#shell.send("Debugger.resume").catch(() => { });
         await this.#control.send("Runtime.terminateExecution");
         this.#shell.abandonPending();
     }
+    /**
+     * For synchronous functions. With awaitPromise the inspector would wrap
+     * even a plain return value in a promise it holds only weakly (#55).
+     */
     callFunctionOn(functionDeclaration, args) {
         return this.#shell.send("Runtime.callFunctionOn", {
             functionDeclaration,
             arguments: args,
             executionContextId: this.#contextId,
+            returnByValue: true,
+        });
+    }
+    /**
+     * For functions that return a promise. The target holds it until after
+     * the inspector's then-callback has run, so a GC can't collect it first.
+     */
+    #callAsyncFunctionOn(functionDeclaration, args) {
+        return this.#shell.send("Runtime.callFunctionOn", {
+            functionDeclaration: `function (...args) { return globalThis.${SHIM}.hold((${functionDeclaration}).apply(this, args)); }`,
+            arguments: args,
+            executionContextId: this.#contextId,
             awaitPromise: true,
             returnByValue: true,
         });
@@ -334,10 +559,12 @@ export class Target {
             : result.unserializableValue !== undefined
                 ? { unserializableValue: result.unserializableValue }
                 : { value: result.value };
-        await this.callFunctionOn(`function (n, r) { return globalThis.${SHIM}.broadcastResult(n, r); }`, [
+        // An async $display method can still be running when interrupt()
+        // abandons the call (#135).
+        await this.#callAsyncFunctionOn(`function (n, r) { return globalThis.${SHIM}.broadcastResult(n, r); }`, [
             { value: executionCount },
             arg,
-        ]);
+        ]).catch(interrupted("Execution"));
     }
     /**
      * Hands a frontend comm message to the target's comms. Resolves to
@@ -348,18 +575,12 @@ export class Target {
         this.#interrupted = false;
         let res;
         try {
-            res = await this.#shell.send("Runtime.callFunctionOn", {
-                functionDeclaration: `function (t, c, m, b) { return globalThis.${SHIM}.commDispatch(t, c, m, b); }`,
-                arguments: [
-                    { value: msgType },
-                    { value: content },
-                    { value: metadata },
-                    { value: buffers.map((b) => Buffer.from(b).toString("base64")) },
-                ],
-                executionContextId: this.#contextId,
-                awaitPromise: true,
-                returnByValue: true,
-            });
+            res = await this.#callAsyncFunctionOn(`function (t, c, m, b) { return globalThis.${SHIM}.commDispatch(t, c, m, b); }`, [
+                { value: msgType },
+                { value: content },
+                { value: metadata },
+                { value: buffers.map((b) => Buffer.from(b).toString("base64")) },
+            ]);
         }
         catch (err) {
             if (err instanceof CdpAbandoned || this.#interrupted)
@@ -381,8 +602,21 @@ export class Target {
         const value = res.result?.value;
         return JSON.parse(typeof value === "string" ? value : '{"name":"Error","message":"","stack":""}');
     }
+    /**
+     * Evaluates without side effects: V8 throws instead of running anything
+     * that would change state (a call, a getter that writes), so completing
+     * or inspecting `obj.` never runs user code (#10). Not replMode, which
+     * returns a promise the inspector holds only weakly (#55); a plain
+     * evaluate sees the cells' let and const too.
+     */
+    #evaluatePure(expression) {
+        return this.#shell
+            .send("Runtime.evaluate", { expression, contextId: this.#contextId, throwOnSideEffect: true })
+            .then(asEvaluateResult)
+            .catch(() => null);
+    }
     async propertyNames(expression) {
-        const evaluated = await this.#evaluateRaw(`(${expression})`).catch(() => null);
+        const evaluated = await this.#evaluatePure(`(${expression})`);
         const objectId = evaluated?.result.objectId;
         if (!objectId || evaluated?.exceptionDetails)
             return [];
@@ -390,12 +624,29 @@ export class Target {
         const list = props.result;
         return (list ?? []).map((p) => p.name);
     }
+    async inspect(path, detail) {
+        const found = await this.#evaluatePure(path);
+        if (!found || found.exceptionDetails)
+            return null;
+        const value = found.result;
+        const arg = value.objectId
+            ? { objectId: value.objectId }
+            : value.unserializableValue !== undefined
+                ? { unserializableValue: value.unserializableValue }
+                : { value: value.value };
+        const res = await this.callFunctionOn(`function (v, d) { return globalThis.${SHIM}.describeForInspect(v, d); }`, [
+            arg,
+            { value: detail },
+        ]);
+        const text = res.result?.value;
+        return typeof text === "string" ? text : null;
+    }
     async lexicalNames() {
         const res = await this.#shell.send("Runtime.globalLexicalScopeNames", { executionContextId: this.#contextId });
         return res.names ?? [];
     }
-    replyInput(value) {
-        this.#child.stdin.write(JSON.stringify({ value }) + "\n");
+    replyInput(value, interrupted = false) {
+        this.#child.stdin.write(JSON.stringify({ value, interrupted }) + "\n");
     }
     kill() {
         this.#shell.close();

package/dist/text.d.ts

@@ -6,9 +6,19 @@ export type IsCompleteReply = {
 } | {
     status: "invalid";
 };
-/** Bracket/quote/comment scanner deciding whether a cell is finished. */
+/**
+ * Bracket/quote/comment scanner deciding whether a cell is finished. Regex
+ * literals are recognised heuristically (see startsRegex), and a template's
+ * `${...}` is skipped like the rest of the template.
+ */
 export declare function checkIsComplete(code: string): IsCompleteReply;
 /** The dotted expression ending at the cursor, e.g. "Math.fl". */
 export declare function exprAtCursor(code: string, cursor: number): string;
+/**
+ * The dotted name an inspect_request means (#10): the one the cursor is in
+ * or just after, or, right after "name(" while typing a call, that callee.
+ * Null when it isn't a plain path; nothing else is evaluated.
+ */
+export declare function inspectTarget(code: string, cursor: number): string | null;
 export declare function codePointToUtf16Index(str: string, cpOffset: number): number;
 export declare function utf16ToCodePointIndex(str: string, utf16Offset: number): number;