@tlockney/cdp-kernel 0.3.0 → 0.4.0

package/dist/transform.js

@@ -17,6 +17,7 @@
 import { transformSync } from "esbuild";
 import { parse } from "acorn";
 import { full, recursive } from "acorn-walk";
+import { LineMap } from "./sourcemap.js";
 export const SHIM = "__cdpk";
 // Each cell first yields one macrotask. User code then runs as an ordinary
 // task instead of nested inside the inspector's dispatch of Runtime.evaluate,
@@ -33,7 +34,8 @@ function jsxSettings(jsx) {
     }
     return { jsx: "transform", jsxFactory: jsx?.factory, jsxFragment: jsx?.fragment };
 }
-function stripTypes(code, options) {
+/** esbuild's output, with its source map's `mappings` when asked for. */
+function stripTypesMapped(code, options, sourcemap) {
     const compilerOptions = {
         verbatimModuleSyntax: true,
         ...(options.experimentalDecorators ? { experimentalDecorators: true } : {}),
@@ -42,13 +44,19 @@ function stripTypes(code, options) {
     let firstError;
     for (const loader of ["tsx", "ts"]) {
         try {
-            return transformSync(code, {
+            const result = transformSync(code, {
                 loader,
                 target: "esnext",
                 ...jsxSettings(options.jsx),
                 tsconfigRaw: { compilerOptions },
                 logLevel: "silent",
-            }).code;
+                ...(sourcemap ? { sourcemap: "external" } : {}),
+            });
+            const map = sourcemap ? JSON.parse(result.map) : null;
+            const mappings = typeof map?.mappings === "string"
+                ? map.mappings
+                : "";
+            return { code: result.code, mappings };
         }
         catch (err) {
             firstError ??= err;
@@ -57,6 +65,9 @@ function stripTypes(code, options) {
     const message = firstError instanceof Error ? firstError.message : String(firstError);
     throw new CellSyntaxError(message.replace(/^Transform failed with \d+ errors?:\n/, ""));
 }
+function stripTypes(code, options) {
+    return stripTypesMapped(code, options, false).code;
+}
 function importedName(spec) {
     const imported = spec.imported;
     if (!imported)
@@ -140,12 +151,25 @@ export function rewriteModuleSyntax(js) {
     // keyword edit doesn't overlap its arguments), so apply back to front.
     return applyEdits(js, edits);
 }
+function newlines(text) {
+    let count = 0;
+    for (const char of text)
+        if (char === "\n")
+            count++;
+    return count;
+}
 function applyEdits(js, edits) {
     // Back to front; at a shared start, a replacement goes before an insertion.
     edits.sort((a, b) => b.start - a.start || b.end - a.end);
     let out = js;
-    for (const edit of edits)
-        out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+    for (const edit of edits) {
+        // Keep every later line where it was, so a cell's lines still map to
+        // esbuild's (the debugger relies on it, #18): a multi-line import
+        // rewritten to one line is padded with the newlines it replaced.
+        const lost = newlines(js.slice(edit.start, edit.end)) - newlines(edit.text);
+        const text = lost > 0 ? edit.text + "\n".repeat(lost) : edit.text;
+        out = out.slice(0, edit.start) + text + out.slice(edit.end);
+    }
     return out;
 }
 /** Adds the names a binding pattern declares. */
@@ -266,6 +290,15 @@ function hoistForEval(js) {
 export function transformCell(code, options = {}) {
     return PRELUDE + rewriteModuleSyntax(stripTypes(code, options));
 }
+/**
+ * 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 function transformCellWithLines(code, options = {}) {
+    const stripped = stripTypesMapped(code, options, true);
+    return { script: PRELUDE + rewriteModuleSyntax(stripped.code), lines: new LineMap(stripped.mappings, newlines(PRELUDE)) };
+}
 /**
  * Like transformCell, for a target that evaluates cells itself, as global
  * code (an indirect eval), instead of through the inspector's replMode: see

package/dist/workerd-target.d.ts

@@ -115,6 +115,8 @@ export declare class WorkerdTarget implements KernelTarget {
         stack: string;
     }>;
     propertyNames(expression: string): Promise<string[]>;
+    /** Resolved by property descriptor in the driver, so nothing runs (#10). */
+    inspect(path: string, detail: number): Promise<string | null>;
     /** None: top-level declarations here are properties of globalThis. */
     lexicalNames(): Promise<string[]>;
     /** Never asked for: prompt() in workerd answers null without asking. */

package/dist/workerd-target.js

@@ -29,9 +29,9 @@ import { runtimeDir } from "./package.js";
 import { Interrupted, isTargetMessage } from "./target.js";
 import { connectUnixWebSocket } from "./ws-client.js";
 import { findWranglerConfig, startMiniflare } from "./workers-project.js";
-import { ensureInstalled, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
+import { ensureInstalled, findLockFile, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
 /** The driver Worker's modules; the first is its main module. */
-export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "evaluator.mjs"];
+export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "evaluator.mjs", "introspect.mjs"];
 /** See BunTarget: how long an interrupted cell has to show it isn't busy. */
 export const INTERRUPT_GRACE_MS = 500;
 export function restartNote(runtime) {
@@ -121,7 +121,7 @@ export async function bundleModule(specifier, cwd) {
                 ? jsrToNpm(specifier.slice(4))
                 : null;
         if (pkg) {
-            const { dir, alias } = ensureInstalled(pkg);
+            const { dir, alias } = ensureInstalled(pkg, "npm", { lockFile: findLockFile(cwd) });
             entry = alias + pkg.subpath;
             resolveDir = dir;
         }
@@ -435,6 +435,11 @@ export class WorkerdTarget {
         const reply = await this.#request("props", { expr: expression }).catch(() => null);
         return Array.isArray(reply?.names) ? reply.names.filter((n) => typeof n === "string") : [];
     }
+    /** Resolved by property descriptor in the driver, so nothing runs (#10). */
+    async inspect(path, detail) {
+        const reply = await this.#request("inspect", { path, detail }).catch(() => null);
+        return typeof reply?.text === "string" ? reply.text : null;
+    }
     /** None: top-level declarations here are properties of globalThis. */
     lexicalNames() {
         return Promise.resolve([]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on any V8 runtime over the Chrome DevTools Protocol",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
@@ -57,7 +57,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"
   },

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 = "";
@@ -122,7 +123,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:.
@@ -148,7 +149,19 @@ globalThis.__cdpk = {
     resolve: (specifier) => new URL(specifier, replUrl).href,
   },
   barrier,
+  // 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) {
@@ -222,6 +235,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)),
@@ -233,6 +247,7 @@ async function platform() {
   const buf = Buffer.alloc(1);
   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),

package/runtime/deno-compat.mjs

@@ -161,7 +161,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(",");
@@ -240,6 +247,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. */

package/runtime/evaluator.mjs

@@ -66,6 +66,12 @@ export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
           return { error: JSON.parse(shim.describeError(err)) };
         }
       case "props": {
+        // Completion's expression is a dotted path; resolved by descriptor
+        // where the shim can, so completing `obj.` never runs a getter (#10).
+        if (typeof shim.resolvePath === "function") {
+          const resolved = shim.resolvePath(request.expr);
+          return { names: resolved.found && !resolved.accessor ? propertyNames(resolved.value) : [] };
+        }
         let value;
         try {
           value = evaluate(`(${request.expr})`);
@@ -74,6 +80,8 @@ export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
         }
         return { names: propertyNames(value) };
       }
+      case "inspect":
+        return { text: shim.inspectPath(request.path, request.detail ?? 0) };
       case "barrier":
         return { value: shim.barrier() };
       default:

package/runtime/introspect.d.mts

@@ -0,0 +1,13 @@
+export type Resolved =
+  | { found: false }
+  | { found: true; accessor: true; name: string }
+  | { found: true; value: unknown; accessor?: undefined };
+
+export function resolvePath(path: string, root?: object): Resolved;
+// deno-lint-ignore ban-types -- classes and functions alike
+export function signatureOf(fn: Function): string;
+export function describeValue(value: unknown, options: { inspect: (value: unknown) => string; detail?: number }): string;
+export function inspectPath(
+  path: string,
+  options: { inspect: (value: unknown) => string; detail?: number; root?: object },
+): string | null;

package/runtime/introspect.mjs

@@ -0,0 +1,120 @@
+// What inspect_request (#10) shows for a value: the text of a JupyterLab
+// tooltip (Shift-Tab) or inspector panel. Shared by every target; the host
+// decides how the value is found (src/target.ts: CDP's throwOnSideEffect;
+// in-process targets: resolvePath, below).
+//
+// No imports: this file must load in every target. `inspect` (util.inspect
+// or Deno.inspect) is passed in.
+
+const PREVIEW_CHARS = 1500;
+const SOURCE_CHARS = 4000;
+const MAX_PROPERTIES = 40;
+
+const IDENTIFIER_PATH = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/;
+
+/**
+ * Looks up a dotted path such as "a.b.c" from globalThis, by property
+ * descriptor, so nothing runs: a getter along the way is reported rather
+ * than called. In-process targets (Bun, workerd, celld) have no way to
+ * evaluate without side effects, so inspection and completion use this.
+ */
+export function resolvePath(path, root = globalThis) {
+  if (!IDENTIFIER_PATH.test(path)) return { found: false };
+  let value = root;
+  for (const name of path.split(".")) {
+    if (value === null || value === undefined) return { found: false };
+    let descriptor;
+    for (let o = Object(value); o !== null && descriptor === undefined; o = Object.getPrototypeOf(o)) {
+      descriptor = Object.getOwnPropertyDescriptor(o, name);
+    }
+    if (descriptor === undefined) return { found: false };
+    if (!("value" in descriptor)) return { found: true, accessor: true, name };
+    value = descriptor.value;
+  }
+  return { found: true, value };
+}
+
+function truncate(text, limit) {
+  return text.length > limit ? `${text.slice(0, limit)}… (${text.length - limit} more characters)` : text;
+}
+
+/** "function add(a, b) {...}" -> "add(a, b)"; "class K {...}" -> "class K". */
+export function signatureOf(fn) {
+  let source;
+  try {
+    source = Function.prototype.toString.call(fn);
+  } catch {
+    return `${fn.name || "anonymous"}(…)`;
+  }
+  if (/^class\b/.test(source)) return `class ${fn.name || "(anonymous)"}`;
+  const params = /^[^(]*\(([^)]*)\)/.exec(source)?.[1];
+  const native = /\{\s*\[native code\]\s*\}$/.test(source);
+  // One line, however the parameters were spread over the source.
+  const written = (params ?? "").replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").trim();
+  const args = native ? Array.from({ length: fn.length }, (_, i) => `arg${i}`).join(", ") : written;
+  const arrow = !/^(?:async\s+)?function\b/.test(source) && /=>/.test(source.split("{")[0] ?? "");
+  const name = fn.name || (arrow ? "(arrow function)" : "anonymous");
+  const prefix = /^async\b/.test(source) ? "async " : "";
+  return `${prefix}${name}(${args})`;
+}
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (typeof value !== "object" && typeof value !== "function") return typeof value;
+  const name = Object.getPrototypeOf(value)?.constructor?.name;
+  if (typeof value === "function") return /^class\b/.test(safeSource(value)) ? "class" : "function";
+  return name && name !== "Object" ? `object (${name})` : "object";
+}
+
+function safeSource(fn) {
+  try {
+    return Function.prototype.toString.call(fn);
+  } catch {
+    return "";
+  }
+}
+
+function propertyNames(value) {
+  if ((typeof value !== "object" && typeof value !== "function") || value === null) return [];
+  try {
+    // A function's own internals aren't worth listing; older V8 (Node 24)
+    // also gives sloppy-mode functions own `arguments` and `caller`.
+    const internal = ["length", "name", "prototype", "arguments", "caller"];
+    return Object.getOwnPropertyNames(value).filter((n) => !(typeof value === "function" && internal.includes(n)));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The tooltip text for a value. `detail` 1 (Shift-Tab twice, or the
+ * inspector panel) adds a function's source.
+ */
+export function describeValue(value, { inspect, detail = 0 }) {
+  const lines = [`Type: ${typeOf(value)}`];
+  if (typeof value === "function") lines.push(`Signature: ${signatureOf(value)}`);
+  let preview;
+  try {
+    preview = inspect(value);
+  } catch (err) {
+    preview = `(inspect failed: ${err instanceof Error ? err.message : String(err)})`;
+  }
+  lines.push(`Value: ${truncate(preview, PREVIEW_CHARS)}`);
+  const names = propertyNames(value);
+  if (names.length > 0) {
+    const shown = names.slice(0, MAX_PROPERTIES).join(", ");
+    lines.push(`Properties: ${shown}${names.length > MAX_PROPERTIES ? `, … (${names.length - MAX_PROPERTIES} more)` : ""}`);
+  }
+  if (detail > 0 && typeof value === "function") lines.push(`Source:\n${truncate(safeSource(value), SOURCE_CHARS)}`);
+  return lines.join("\n");
+}
+
+/** inspect_request for in-process targets: resolvePath, then describeValue. */
+export function inspectPath(path, { inspect, detail = 0, root = globalThis }) {
+  const resolved = resolvePath(path, root);
+  if (!resolved.found) return null;
+  if (resolved.accessor) {
+    return `Type: accessor property\n${resolved.name} has a getter, which isn't called for inspection: it could have side effects.`;
+  }
+  return describeValue(resolved.value, { inspect, detail });
+}

package/runtime/node-hooks.d.mts

@@ -13,9 +13,27 @@ export function installCommand(
   alias: string,
   name: string,
   range: string,
-): { cmd: string; args: string[] };
+): { cmd: string; args: string[]; env?: { [name: string]: string } };
+/** Runs an install; `env` is added to the process environment. */
+export type InstallRunner = (
+  cmd: string,
+  args: string[],
+  cwd: string,
+  env?: { [name: string]: string },
+) => { status: number | null; stderr?: string; error?: Error };
 export function ensureInstalled(
   pkg: { name: string; range: string },
   installer?: Installer,
+  options?: { lockFile?: string | null; run?: InstallRunner },
 ): { dir: string; alias: string };
+
+export const LOCK_FILE: string;
+export interface Lock {
+  version: 1;
+  packages: { [nameAtRange: string]: string };
+}
+export function findLockFile(dir: string): string | null;
+export function readLock(path: string): Lock;
+export function writeLock(path: string, lock: Lock): void;
+export function withInstallLock<T>(dir: string, fn: () => T, options?: { timeoutMs?: number }): T;
 export function installNodeResolveHooks(urls: { shimUrl: string; replUrl: string }): void;

package/runtime/node-hooks.mjs

@@ -1,3 +1,4 @@
+// @ts-self-types="./node-hooks.d.mts"
 // Node-only module resolution for cell code: the part of Deno's module
 // loader a notebook leans on most.
 //   - Imports issued by cell code arrive with the bootstrap module as their
@@ -16,10 +17,10 @@
 import module from "node:module";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const SPEC_RE = /^((?:@[^/@]+\/)?[^/@]+)(?:@([^/]+))?(\/.*)?$/;
 
@@ -58,25 +59,151 @@ function cacheDir(installer) {
 }
 
 /** The command that installs name@range under `alias` with `installer`. */
+//   - Saved exactly (#40): npm records `npm:react@19.0.0` as `^19.0.0` by
+//     default, and every later install into the shared cache re-resolves the
+//     ranges, so pinned packages drifted (react 19.3.1 beside react-dom
+//     19.0.0). With an exact save, a version stays put and a range is frozen
+//     at what it first resolved to. Bun already saves exactly; the flag says so.
+//   - JSR packages come as tarballs from npm.jsr.io, which npm 12 refuses as
+//     "remote" unless allowed (#39). `root` is the narrowest value that works
+//     (`true`, which looks right, is invalid and warns), and only the JSR
+//     install gets it.
 export function installCommand(installer, alias, name, range) {
   const spec = `${alias}@npm:${name}@${range}`;
   // The Bun target runs this inside Bun, so it uses its own binary.
-  if (installer === "bun") return { cmd: process.execPath, args: ["add", "--silent", spec] };
-  return { cmd: "npm", args: ["install", "--no-audit", "--no-fund", "--loglevel=error", spec] };
+  if (installer === "bun") return { cmd: process.execPath, args: ["add", "--silent", "--exact", spec] };
+  const args = ["install", "--no-audit", "--no-fund", "--loglevel=error", "--save-exact", spec];
+  return name.startsWith("@jsr/") ? { cmd: "npm", args, env: { npm_config_allow_remote: "root" } } : { cmd: "npm", args };
 }
 
-/** Installs a package into the installer's cache unless it's there already. */
-export function ensureInstalled({ name, range }, installer = "npm") {
-  const dir = cacheDir(installer);
-  const alias = aliasFor(name, range);
-  if (!existsSync(join(dir, "node_modules", alias, "package.json"))) {
-    const { cmd, args } = installCommand(installer, alias, name, range);
-    const result = spawnSync(cmd, args, { cwd: dir, encoding: "utf8" });
-    if (result.status !== 0) {
-      throw new Error(`${installer} install ${name}@${range} failed:\n${result.stderr || result.error}`);
+// --- Lockfile (#14) -----------------------------------------------------------
+// A cdp-kernel.lock.json at or above the notebook pins each npm:/jsr:
+// request to the exact version it first resolved to, so the same notebook
+// gets the same packages on another machine. Opt-in: create the file (with
+// `{}` in it) to start locking; the kernel then fills it in.
+
+export const LOCK_FILE = "cdp-kernel.lock.json";
+
+/** The nearest cdp-kernel.lock.json at or above `dir`, or null. */
+export function findLockFile(dir) {
+  for (let at = dir;; at = dirname(at)) {
+    if (existsSync(join(at, LOCK_FILE))) return join(at, LOCK_FILE);
+    if (dirname(at) === at) return null;
+  }
+}
+
+/** `{ version: 1, packages: { "name@range": "exact version" } }`; `{}` counts as empty. */
+export function readLock(path) {
+  const parsed = JSON.parse(readFileSync(path, "utf8") || "{}");
+  const packages = parsed && typeof parsed.packages === "object" && parsed.packages !== null ? parsed.packages : {};
+  return { version: 1, packages };
+}
+
+/** Sorted, so a lockfile's diff shows only what changed. */
+export function writeLock(path, lock) {
+  const packages = Object.fromEntries(Object.entries(lock.packages).sort(([a], [b]) => a.localeCompare(b)));
+  writeFileSync(path, JSON.stringify({ version: 1, packages }, null, 2) + "\n");
+}
+
+// --- Serialized installs (#14) -------------------------------------------------
+// Kernels share one cache per installer, and npm/bun both rewrite its
+// package.json and node_modules, so installs take a lock: a directory, which
+// mkdir creates atomically. A lock left by a process that died is taken over.
+
+const LOCK_DIR = ".install-lock";
+const STALE_MS = 10 * 60 * 1000;
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function holderAlive(lockDir) {
+  try {
+    const pid = Number(readFileSync(join(lockDir, "pid"), "utf8"));
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: alive, but someone else's.
+    return err?.code === "EPERM";
+  }
+}
+
+/** Runs `fn` holding the cache's install lock. Synchronous, like the resolve hook. */
+export function withInstallLock(dir, fn, { timeoutMs = STALE_MS } = {}) {
+  const lockDir = join(dir, LOCK_DIR);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      mkdirSync(lockDir);
+      writeFileSync(join(lockDir, "pid"), String(process.pid));
+      break;
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+      let age = 0;
+      try {
+        age = Date.now() - statSync(lockDir).mtimeMs;
+      } catch {
+        continue; // released meanwhile
+      }
+      // A holder that died, or one stuck for longer than any install takes.
+      if ((age > 1000 && !holderAlive(lockDir)) || age > STALE_MS) {
+        rmSync(lockDir, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() > deadline) throw new Error(`timed out waiting for the install lock ${lockDir}`);
+      sleep(100);
     }
   }
-  return { dir, alias };
+  try {
+    return fn();
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+
+function installedVersion(dir, alias) {
+  try {
+    return JSON.parse(readFileSync(join(dir, "node_modules", alias, "package.json"), "utf8")).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function spawnInstall(cmd, args, cwd, env = {}) {
+  return spawnSync(cmd, args, { cwd, encoding: "utf8", env: { ...process.env, ...env } });
+}
+
+/**
+ * Installs a package into the installer's cache unless it's there already.
+ * With a lockfile, a locked request installs its exact version, and an
+ * unlocked one is recorded once installed. `run` is the install command
+ * runner, replaceable in tests.
+ */
+export function ensureInstalled({ name, range }, installer = "npm", { lockFile = null, run = spawnInstall } = {}) {
+  const dir = cacheDir(installer);
+  const key = `${name}@${range}`;
+  return withInstallLock(dir, () => {
+    const lock = lockFile ? readLock(lockFile) : null;
+    const locked = lock?.packages[key];
+    const version = typeof locked === "string" ? locked : range;
+    const alias = aliasFor(name, version);
+    if (installedVersion(dir, alias) === null) {
+      const { cmd, args, env } = installCommand(installer, alias, name, version);
+      const result = run(cmd, args, dir, env);
+      if (result.status !== 0) {
+        throw new Error(`${installer} install ${name}@${version} failed:\n${result.stderr || result.error}`);
+      }
+    }
+    if (lock && typeof locked !== "string") {
+      const resolved = installedVersion(dir, alias);
+      if (resolved !== null) {
+        lock.packages[key] = resolved;
+        writeLock(lockFile, lock);
+      }
+    }
+    return { dir, alias };
+  });
 }
 
 export function installNodeResolveHooks({ shimUrl, replUrl }) {
@@ -86,7 +213,8 @@ export function installNodeResolveHooks({ shimUrl, replUrl }) {
       if (specifier.startsWith("npm:")) pkg = parsePackageSpecifier(specifier.slice(4));
       else if (specifier.startsWith("jsr:")) pkg = jsrToNpm(specifier.slice(4));
       if (pkg) {
-        const { dir, alias } = ensureInstalled(pkg);
+        const lockFile = findLockFile(fileURLToPath(new URL(".", replUrl)));
+        const { dir, alias } = ensureInstalled(pkg, "npm", { lockFile });
         const parentURL = pathToFileURL(join(dir, "package.json")).href;
         return nextResolve(alias + pkg.subpath, { ...context, parentURL });
       }