@tlockney/cdp-kernel 0.3.0 → 0.4.0

package/dist/kernel.js

@@ -11,11 +11,13 @@ import { decodeMessage, encodeMessage, PROTOCOL_VERSION, verify } from "./wire.j
 import { PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
 import { Interrupted, Target } from "./target.js";
 import { BunTarget } from "./bun-target.js";
+import { Debugger } from "./debugger.js";
 import { WorkerdTarget } from "./workerd-target.js";
 import { launchCelld } from "./celld-target.js";
 import { CellSyntaxError, objectLiteralCandidate } from "./transform.js";
 import { loadDenoProject } from "./deno-config.js";
-import { checkIsComplete, codePointToUtf16Index, exprAtCursor, utf16ToCodePointIndex } from "./text.js";
+import { checkIsComplete, codePointToUtf16Index, exprAtCursor, inspectTarget, utf16ToCodePointIndex } from "./text.js";
+import { queryHistory } from "./history.js";
 import { VERSION } from "./package.js";
 export function parseConnectionInfo(json) {
     const raw = JSON.parse(json);
@@ -52,6 +54,10 @@ export class Kernel {
     #project;
     #projectWarning = null;
     #noticeShownFor = null;
+    /** JupyterLab's visual debugger, for targets driven over CDP (#18). */
+    #debugger;
+    /** Cells run with store_history, for history_request (#10). */
+    #history = [];
     #session = randomUUID();
     #shell;
     #control;
@@ -71,6 +77,9 @@ export class Kernel {
         this.#runtime = runtime;
         this.#denoCompat = options.denoCompat ?? false;
         this.#project = runtime === "deno" ? this.#loadProject(options.notebookDir ?? process.cwd()) : null;
+        this.#debugger = runtime === "node" || runtime === "deno"
+            ? new Debugger((event) => this.#publish("debug_event", event), () => this.#transformOptions())
+            : null;
         startHeartbeat(conn.hb_port, conn.ip);
         this.#shell = new RouterSocket(conn.shell_port, conn.ip);
         this.#control = new RouterSocket(conn.control_port, conn.ip);
@@ -181,7 +190,9 @@ export class Kernel {
     #ensureTarget() {
         if (this.#target)
             return Promise.resolve(this.#target);
-        this.#targetStarting ??= this.#launchTarget().then((target) => {
+        this.#targetStarting ??= this.#launchTarget().then(async (target) => {
+            // Before any cell runs on it, so breakpoints already apply.
+            await this.#debugger?.attachTarget(target.debug ?? null);
             this.#target = target;
             this.#targetStarting = null;
             return target;
@@ -197,6 +208,7 @@ export class Kernel {
             message: (msg) => void this.#onTargetMessage(msg),
             exit: (code, note) => {
                 this.#target = null;
+                void this.#debugger?.attachTarget(null);
                 if (!this.#shuttingDown) {
                     const text = note ?? `[cdp-kernel] ${this.#runtime} exited (${code}); restarting on next cell`;
                     this.#publish("stream", { name: "stderr", text: `\n${text}\n` });
@@ -272,7 +284,10 @@ export class Kernel {
             },
             banner: `cdp-kernel on ${this.#runtime} ${versions?.runtime ?? ""} (${versions?.engine || "?"})`,
             help_links: [],
-            debugger: false,
+            debugger: this.#debugger !== null,
+            // What current ipykernel advertises; JupyterLab itself goes by the
+            // kernelspec's metadata.debugger.
+            supported_features: this.#debugger !== null ? ["debugger"] : [],
         };
     }
     // --- control channel ------------------------------------------------------
@@ -285,6 +300,29 @@ export class Kernel {
                 await this.#interrupt();
                 this.#reply(this.#control, peer, msg, "interrupt_reply", { status: "ok" });
                 break;
+            case "debug_request": {
+                // JupyterLab treats a debug request as done only once the kernel
+                // reports idle for it, as ipykernel does for control messages.
+                // (Jupyter Server leaves debug_request out of the kernel's status.)
+                this.#status("busy", msg.header);
+                let reply;
+                try {
+                    if (this.#debugger === null) {
+                        reply = { type: "response", request_seq: msg.content.seq, command: msg.content.command, success: false, message: `${this.#runtime} targets have no debugger`, body: {} };
+                    }
+                    else {
+                        // Everything but debugInfo talks to the target, so make sure there is one.
+                        if (msg.content.command !== "debugInfo")
+                            await this.#ensureTarget().catch(() => null);
+                        reply = await this.#debugger.handle(msg.content);
+                    }
+                    this.#reply(this.#control, peer, msg, "debug_reply", reply);
+                }
+                finally {
+                    this.#status("idle", msg.header);
+                }
+                break;
+            }
             case "shutdown_request": {
                 const restart = msg.content.restart === true;
                 this.#reply(this.#control, peer, msg, "shutdown_reply", { status: "ok", restart });
@@ -316,10 +354,10 @@ export class Kernel {
                     this.#reply(this.#shell, peer, msg, "is_complete_reply", checkIsComplete(String(msg.content.code ?? "")));
                     break;
                 case "inspect_request":
-                    this.#reply(this.#shell, peer, msg, "inspect_reply", { status: "ok", found: false, data: {}, metadata: {} });
+                    this.#reply(this.#shell, peer, msg, "inspect_reply", await this.#inspect(msg));
                     break;
                 case "history_request":
-                    this.#reply(this.#shell, peer, msg, "history_reply", { status: "ok", history: [] });
+                    this.#reply(this.#shell, peer, msg, "history_reply", { status: "ok", history: queryHistory(this.#history, msg.content) });
                     break;
                 case "comm_info_request":
                     this.#reply(this.#shell, peer, msg, "comm_info_reply", { status: "ok", comms: this.#commInfo(msg.content) });
@@ -335,6 +373,19 @@ export class Kernel {
             this.#status("idle", msg.header);
         }
     }
+    /** The tooltip (Shift-Tab) for the name at the cursor (#10). */
+    async #inspect(msg) {
+        const code = String(msg.content.code ?? "");
+        const cursorCp = typeof msg.content.cursor_pos === "number"
+            ? msg.content.cursor_pos
+            : utf16ToCodePointIndex(code, code.length);
+        const path = inspectTarget(code, codePointToUtf16Index(code, cursorCp));
+        const detail = msg.content.detail_level === 1 ? 1 : 0;
+        const text = path === null ? null : await (await this.#ensureTarget()).inspect(path, detail);
+        return text === null
+            ? { status: "ok", found: false, data: {}, metadata: {} }
+            : { status: "ok", found: true, data: { "text/plain": text }, metadata: {} };
+    }
     async #complete(msg) {
         const code = String(msg.content.code ?? "");
         const cursorCp = typeof msg.content.cursor_pos === "number"
@@ -387,10 +438,14 @@ export class Kernel {
     async #evaluateCell(target, code) {
         // Object-literal wrapping (Deno's evaluate_line_with_object_wrapping):
         // try `({ ... })` first and fall back to the code as written.
+        // While debugging, cells carry the path JupyterLab gave them and keep a
+        // line map, so breakpoints bind and frames point at the cell (#18).
+        const debugging = this.#debugger?.started === true && target.debug !== undefined;
+        const transform = (source) => debugging && this.#debugger ? this.#debugger.cellScript(code, source) : target.transform(source, this.#transformOptions());
         const wrapped = objectLiteralCandidate(code);
         if (wrapped !== null) {
             try {
-                const result = await target.evaluate(target.transform(wrapped, this.#transformOptions()));
+                const result = await target.evaluate(transform(wrapped));
                 if (!result.exceptionDetails)
                     return result;
             }
@@ -399,14 +454,16 @@ export class Kernel {
                     throw err;
             }
         }
-        return target.evaluate(target.transform(code, this.#transformOptions()));
+        return target.evaluate(transform(code));
     }
     async #execute(msg, peer) {
         const parent = msg.header;
         const code = String(msg.content.code ?? "");
         const silent = msg.content.silent === true;
-        if (!silent && msg.content.store_history !== false)
+        if (!silent && msg.content.store_history !== false) {
             this.#executionCount++;
+            this.#history.push({ line: this.#executionCount, input: code });
+        }
         const count = this.#executionCount;
         this.#parent = parent;
         this.#allowStdin = msg.content.allow_stdin === true;

package/dist/main.js

@@ -42,7 +42,9 @@ function install(runtime, denoCompat, name, display) {
         // Interrupts arrive as interrupt_request on the control channel rather
         // than as SIGINT to this process.
         interrupt_mode: "message",
-        metadata: { runtime, denoCompat, version: VERSION },
+        // JupyterLab enables its visual debugger from metadata.debugger (#18);
+        // only the targets driven over CDP have one.
+        metadata: { runtime, denoCompat, version: VERSION, debugger: runtime === "node" || runtime === "deno" },
     };
     writeFileSync(join(dir, "kernel.json"), JSON.stringify(spec, null, 2) + "\n");
     console.log(`installed kernelspec ${name} -> ${dir}`);

package/dist/murmur2.d.ts

@@ -0,0 +1,2 @@
+/** The hash of a string's UTF-8 bytes. */
+export declare function murmur2(str: string, seed: number): number;

package/dist/murmur2.js

@@ -0,0 +1,41 @@
+// MurmurHash2 (32-bit), as the Jupyter debugger uses it to name a cell's
+// source (#18). JupyterLab computes a cell's path itself, as tmpFilePrefix +
+// murmur2(code, hashSeed) + tmpFileSuffix, and the kernel must name the
+// cell's script the same way, so this follows JupyterLab's
+// packages/debugger/src/hash.ts (Modified BSD License, Copyright (c) Jupyter
+// Development Team), itself adapted from Gary Court's murmurhash2_gc.js
+// (MIT License, Copyright (c) 2011 Gary Court).
+const M = 0x5bd1e995;
+const ENCODER = new TextEncoder();
+/** 32-bit multiply by M, without leaving the safe-integer range. */
+function mul(x) {
+    return (x & 0xffff) * M + ((((x >>> 16) * M) & 0xffff) << 16);
+}
+/** The hash of a string's UTF-8 bytes. */
+export function murmur2(str, seed) {
+    const data = ENCODER.encode(str);
+    let len = data.length;
+    let h = seed ^ len;
+    let i = 0;
+    while (len >= 4) {
+        let k = data[i] | (data[i + 1] << 8) | (data[i + 2] << 16) | (data[i + 3] << 24);
+        k = mul(k);
+        k ^= k >>> 24;
+        k = mul(k);
+        h = mul(h) ^ k;
+        len -= 4;
+        i += 4;
+    }
+    if (len === 3)
+        h ^= data[i + 2] << 16;
+    if (len >= 2)
+        h ^= data[i + 1] << 8;
+    if (len >= 1) {
+        h ^= data[i];
+        h = mul(h);
+    }
+    h ^= h >>> 13;
+    h = mul(h);
+    h ^= h >>> 15;
+    return h >>> 0;
+}

package/dist/package.d.ts

@@ -1,6 +1,20 @@
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export declare const VERSION = "0.3.0";
-export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "bun-channel.mjs", "evaluator.mjs", "workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "node-hooks.mjs", "deno-compat.mjs", "node-modules-resolve.mjs"];
+export declare const VERSION = "0.4.0";
+/**
+ * The UTC day this version was released, set with VERSION. The publish
+ * workflow refuses a tag unless it's today or yesterday, so it can't go
+ * stale: see dependencyCutoff.
+ */
+export declare const RELEASE_DATE = "2026-10-15";
+/**
+ * Deno blocks packages less than 24 hours old (minimum dependency age), so
+ * a kernelspec relaunching a release from JSR would fail on release day. It
+ * relaunches with this cutoff instead (#12): anything published up to two
+ * days after the release is allowed (the release itself included, however
+ * late in the day its tag was pushed), and nothing newer ever is.
+ */
+export declare function dependencyCutoff(releaseDate?: string): string;
+export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "bun-channel.mjs", "evaluator.mjs", "introspect.mjs", "workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "node-hooks.mjs", "deno-compat.mjs", "node-modules-resolve.mjs"];
 export type HostRuntime = "node" | "deno";
 export declare function hostRuntime(): HostRuntime;
 /** Where the CLI module was loaded from. */

package/dist/package.js

@@ -14,11 +14,32 @@ import { join, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";
+/**
+ * The UTC day this version was released, set with VERSION. The publish
+ * workflow refuses a tag unless it's today or yesterday, so it can't go
+ * stale: see dependencyCutoff.
+ */
+export const RELEASE_DATE = "2026-10-15";
+/**
+ * Deno blocks packages less than 24 hours old (minimum dependency age), so
+ * a kernelspec relaunching a release from JSR would fail on release day. It
+ * relaunches with this cutoff instead (#12): anything published up to two
+ * days after the release is allowed (the release itself included, however
+ * late in the day its tag was pushed), and nothing newer ever is.
+ */
+export function dependencyCutoff(releaseDate = RELEASE_DATE) {
+    const day = new Date(`${releaseDate}T00:00:00Z`);
+    if (Number.isNaN(day.getTime()))
+        throw new Error(`not a date: ${releaseDate}`);
+    day.setUTCDate(day.getUTCDate() + 2);
+    return day.toISOString().slice(0, 10);
+}
 export const RUNTIME_FILES = [
     "bootstrap.mjs",
     "bun-channel.mjs",
     "evaluator.mjs",
+    "introspect.mjs",
     "workerd-worker.mjs",
     "display.mjs",
     "comm.mjs",
@@ -54,7 +75,9 @@ export function kernelArgv(host, execPath, origin, args) {
     }
     // Deno: a checkout needs its deno.jsonc import map; a JSR package brings
     // its own, so skip whatever config the notebook's directory has.
-    const flags = origin.kind === "jsr" ? ["--no-config", "--no-lock"] : ["--no-lock"];
+    const flags = origin.kind === "jsr"
+        ? ["--no-config", "--no-lock", `--min-dep-age=${dependencyCutoff()}`]
+        : ["--no-lock"];
     const entry = origin.kind === "jsr" ? origin.specifier : origin.path;
     return [execPath, "run", "--allow-all", ...flags, entry, ...args];
 }

package/dist/sourcemap.d.ts

@@ -0,0 +1,22 @@
+/** One segment's VLQ fields: generated column, source, line, column, name. */
+export declare function decodeVlq(segment: string): number[];
+/**
+ * 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 declare function generatedToOriginalLines(mappings: string): number[];
+/** Both directions between the lines of a cell and of its script (0-based). */
+export declare class LineMap {
+    #private;
+    /** `offset`: lines the script adds before esbuild's output (the prelude). */
+    constructor(mappings: string, offset?: number);
+    /** The cell line a script line came from: its own mapping, or the nearest one above. */
+    toOriginal(generated: number): number;
+    /**
+     * 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: number): number | null;
+}

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,5 +1,6 @@
 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. */
@@ -37,6 +38,10 @@ export interface KernelTarget {
     }>;
     propertyNames(expression: string): Promise<string[]>;
     lexicalNames(): Promise<string[]>;
+    /** 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;
     replyInput(value: string | null): void;
     kill(): void;
 }
@@ -114,6 +119,8 @@ export declare class Target implements KernelTarget {
         denoCompat?: boolean;
         denoConfig?: string;
     }): 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(). */
@@ -149,6 +156,7 @@ 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;
     kill(): void;

package/dist/target.js

@@ -179,6 +179,8 @@ export class Target {
     #contextId;
     #messages = Promise.resolve();
     #interrupted = false;
+    #paused = false;
+    #baselineGlobals = new Set();
     versions;
     constructor(runtime, child, shell, control, stdout, stderr, gates, contextId, versions) {
         this.runtime = runtime;
@@ -271,8 +273,26 @@ export class Target {
         }
         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 })`);
         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) {
@@ -315,6 +335,9 @@ 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();
     }
@@ -381,8 +404,18 @@ 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).
+     */
+    #evaluatePure(expression) {
+        return this.#shell
+            .send("Runtime.evaluate", { expression, contextId: this.#contextId, replMode: true, throwOnSideEffect: true })
+            .then(asEvaluateResult, () => 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,6 +423,23 @@ 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 ?? [];

package/dist/text.d.ts

@@ -10,5 +10,11 @@ export type IsCompleteReply = {
 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;

package/dist/text.js

@@ -51,6 +51,23 @@ export function exprAtCursor(code, cursor) {
     const m = /[\w$.]+$/.exec(code.slice(0, cursor));
     return m ? m[0] : "";
 }
+/**
+ * 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 function inspectTarget(code, cursor) {
+    let end = cursor;
+    // Inside a call's parentheses with nothing typed yet: "add(|".
+    const before = code.slice(0, cursor);
+    const call = /([\w$.]+)\(\s*$/.exec(before);
+    if (call)
+        end = cursor - (before.length - before.lastIndexOf("(", cursor));
+    const head = /[\w$.]*$/.exec(code.slice(0, end))?.[0] ?? "";
+    const tail = call ? "" : (/^[\w$]*/.exec(code.slice(end))?.[0] ?? "");
+    const path = (head + tail).replace(/\.$/, "");
+    return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(path) ? path : null;
+}
 // Jupyter measures cursor_pos in Unicode codepoints; JS strings index UTF-16
 // code units (denoland/deno#22771).
 export function codePointToUtf16Index(str, cpOffset) {

package/dist/transform.d.ts

@@ -1,3 +1,4 @@
+import { LineMap } from "./sourcemap.ts";
 export declare const SHIM = "__cdpk";
 export declare class CellSyntaxError extends Error {
     name: string;
@@ -23,6 +24,15 @@ export interface CellTransformOptions {
 /** Rewrites module-only syntax in plain JavaScript into script syntax. */
 export declare function rewriteModuleSyntax(js: string): string;
 export declare function transformCell(code: string, options?: CellTransformOptions): string;
+/**
+ * transformCell, plus the map between the cell's lines and the script's,
+ * for the debugger (#18). The rewrite keeps lines (see applyEdits), so the
+ * script's lines are esbuild's, after the prelude's one.
+ */
+export declare function transformCellWithLines(code: string, options?: CellTransformOptions): {
+    script: string;
+    lines: LineMap;
+};
 /**
  * Like transformCell, for a target that evaluates cells itself, as global
  * code (an indirect eval), instead of through the inspector's replMode: see