@tlockney/cdp-kernel 0.3.0 → 0.5.0

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

@@ -8,14 +8,74 @@ export function parsePackageSpecifier(spec: string): PackageSpecifier;
 export function jsrToNpm(spec: string): PackageSpecifier;
 export function aliasFor(name: string, range: string): string;
 export type Installer = "npm" | "bun";
+/** Where `installer` keeps its packages: $XDG_CACHE_HOME/cdp-kernel/<installer>, or CDPK_CACHE_DIR for npm. */
+export function cacheDirPath(
+  installer: Installer,
+  env?: { [name: string]: string | undefined },
+  home?: string,
+): string;
 export function installCommand(
   installer: Installer,
   alias: string,
   name: string,
   range: string,
-): { cmd: string; args: string[] };
+): { cmd: string; args: string[]; env?: { [name: string]: string } };
+/** How to spawn an install command; on Windows, npm runs through cmd.exe. */
+export function spawnCommand(
+  cmd: string,
+  args: string[],
+  platform?: string,
+): { cmd: string; args: string[]; shell: boolean };
+/** 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 };
+/** ensureInstalled without blocking the event loop; `run` may return a promise. */
+export function ensureInstalledAsync(
+  pkg: { name: string; range: string },
+  installer?: Installer,
+  options?: {
+    lockFile?: string | null;
+    run?: (...args: Parameters<InstallRunner>) => ReturnType<InstallRunner> | Promise<ReturnType<InstallRunner>>;
+  },
+): Promise<{ 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 withInstallLockAsync<T>(dir: string, fn: () => T | Promise<T>, options?: { timeoutMs?: number }): Promise<T>;
+/** Compiles one TypeScript or JSX file with the esbuild binary at `binary`; `run` is replaceable in tests. */
+export function compileTypeScript(
+  source: string,
+  filename: string,
+  binary: string,
+  run?: (cmd: string, args: string[], options: object) => { status: number | null; stdout: string; stderr: string; error?: Error },
+  loader?: "ts" | "tsx" | "jsx",
+): string;
+export interface LoadResult {
+  format?: string | null;
+  source?: string | ArrayBuffer | ArrayBufferView | null;
+  shortCircuit?: boolean;
+}
+/** The load hook: Node's own result unless its type stripping would reject the file; .tsx/.jsx always compiled. */
+export function loadTypeScript(
+  url: string,
+  context: object,
+  nextLoad: (url: string, context: object) => LoadResult,
+  binary: string | undefined,
+): LoadResult;
 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
@@ -8,18 +9,22 @@
 //     one package can coexist (Deno keeps a global cache the same way).
 //   - jsr:@scope/name[@range][/subpath] maps onto JSR's npm compatibility
 //     registry (npm.jsr.io) as @jsr/scope__name.
+//   - TypeScript files a cell imports load with Node's own type stripping
+//     where it can; syntax that needs code generation (enum, namespaces with
+//     values, parameter properties) is compiled by esbuild instead (#73).
+//     Node can't load JSX at all, so .tsx/.jsx files are always compiled (#91).
 // Uses module.registerHooks (synchronous, in-thread; Node >= 23.5), so the
 // install can run with spawnSync inside resolve.
 
 // Not a named import: Bun, which loads this file for its npm:/jsr: helpers,
 // has no registerHooks, and a missing named export fails at link time.
 import module from "node:module";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, 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 = /^((?:@[^/@]+\/)?[^/@]+)(?:@([^/]+))?(\/.*)?$/;
 
@@ -43,12 +48,19 @@ export function aliasFor(name, range) {
   return `cdpk-${digest}`;
 }
 
-// Each installer keeps its own cache, so npm's and Bun's lockfiles never
-// meet; both read the @jsr registry from .npmrc.
+/**
+ * Each installer keeps its own cache, so npm's and Bun's lockfiles never
+ * meet. Both sit beside the runtime cache (cacheRoot in src/package.ts);
+ * CDPK_CACHE_DIR overrides npm's.
+ */
+export function cacheDirPath(installer, env = process.env, home = homedir()) {
+  if (installer === "npm" && env.CDPK_CACHE_DIR) return env.CDPK_CACHE_DIR;
+  return join(env.XDG_CACHE_HOME || join(home, ".cache"), "cdp-kernel", installer);
+}
+
+// Both caches read the @jsr registry from .npmrc.
 function cacheDir(installer) {
-  const dir = installer === "npm"
-    ? process.env.CDPK_CACHE_DIR ?? join(homedir(), ".cache", "cdp-kernel", "npm")
-    : join(homedir(), ".cache", "cdp-kernel", installer);
+  const dir = cacheDirPath(installer);
   if (!existsSync(join(dir, "package.json"))) {
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, "package.json"), '{ "private": true }\n');
@@ -58,35 +70,356 @@ 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 };
+}
+
+// --- 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) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8") || "{}");
+  } catch (err) {
+    throw new Error(`cannot read ${path}: ${err instanceof Error ? err.message : err}`);
+  }
+  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. Written to a
+ * temporary file and renamed into place, so a crash mid-write can't leave
+ * a truncated lockfile (#144).
+ */
+export function writeLock(path, lock) {
+  const packages = Object.fromEntries(Object.entries(lock.packages).sort(([a], [b]) => a.localeCompare(b)));
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, packages }, null, 2) + "\n");
+  renameSync(tmp, path);
+}
+
+// --- 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;
+// one whose holder is alive is waited on.
+
+const LOCK_DIR = ".install-lock";
+/** How long a waiter waits for a live holder before giving up. */
+const WAIT_MS = 10 * 60 * 1000;
+/** A lock this old is taken over even if its pid is alive: the pid was reused. */
+const ABANDONED_MS = 60 * 60 * 1000;
+
+function sleep(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function holderPid(lockDir) {
+  try {
+    return Number(readFileSync(join(lockDir, "pid"), "utf8"));
+  } catch {
+    return NaN;
+  }
 }
 
-/** Installs a package into the installer's cache unless it's there already. */
-export function ensureInstalled({ name, range }, installer = "npm") {
+function holderAlive(lockDir) {
+  try {
+    const pid = holderPid(lockDir);
+    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";
+  }
+}
+
+/** Takes the install lock at `lockDir` if it's free: false means wait and try again. */
+function tryLock(lockDir, deadline) {
+  for (;;) {
+    try {
+      mkdirSync(lockDir);
+      writeFileSync(join(lockDir, "pid"), String(process.pid));
+      return true;
+    } 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. The grace period covers the gap between mkdir
+      // and writing the pid. A live holder is waited on rather than stolen
+      // from, which would run a second install alongside its own (#144),
+      // unless the lock is so old its pid must have been reused.
+      if ((age > 1000 && !holderAlive(lockDir)) || age > ABANDONED_MS) {
+        rmSync(lockDir, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() > deadline) throw new Error(`timed out waiting for the install lock ${lockDir}`);
+      return false;
+    }
+  }
+}
+
+/** Removes the lock only if still ours: a waiter that took it over owns it now. */
+function releaseLock(lockDir) {
+  if (holderPid(lockDir) === process.pid) rmSync(lockDir, { recursive: true, force: true });
+}
+
+/** Runs `fn` holding the cache's install lock. Synchronous, like the resolve hook. */
+export function withInstallLock(dir, fn, { timeoutMs = WAIT_MS } = {}) {
+  const lockDir = join(dir, LOCK_DIR);
+  const deadline = Date.now() + timeoutMs;
+  while (!tryLock(lockDir, deadline)) sleep(100);
+  try {
+    return fn();
+  } finally {
+    releaseLock(lockDir);
+  }
+}
+
+/** withInstallLock for a caller that mustn't block its event loop while it waits. */
+export async function withInstallLockAsync(dir, fn, { timeoutMs = WAIT_MS } = {}) {
+  const lockDir = join(dir, LOCK_DIR);
+  const deadline = Date.now() + timeoutMs;
+  while (!tryLock(lockDir, deadline)) await new Promise((resolve) => setTimeout(resolve, 100));
+  try {
+    return await fn();
+  } finally {
+    releaseLock(lockDir);
+  }
+}
+
+function installedVersion(dir, alias) {
+  try {
+    return JSON.parse(readFileSync(join(dir, "node_modules", alias, "package.json"), "utf8")).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * How to spawn an install command on `platform`. On Windows npm is npm.cmd,
+ * which Node runs only through a shell (#51). cmd.exe reads ^ < > | & as
+ * operators, and semver ranges use them, so each argument is double-quoted,
+ * where cmd.exe leaves them alone. A " or % would still be read, so they're
+ * refused; no package name or valid range contains either.
+ */
+export function spawnCommand(cmd, args, platform = process.platform) {
+  if (platform !== "win32" || cmd !== "npm") return { cmd, args, shell: false };
+  const bad = args.find((arg) => /["%\r\n]/.test(arg));
+  if (bad !== undefined) throw new TypeError(`can't pass ${JSON.stringify(bad)} to npm through cmd.exe`);
+  return { cmd, args: args.map((arg) => `"${arg}"`), shell: true };
+}
+
+function spawnInstall(cmd, args, cwd, env = {}) {
+  const spawned = spawnCommand(cmd, args);
+  return spawnSync(spawned.cmd, spawned.args, { cwd, encoding: "utf8", env: { ...process.env, ...env }, shell: spawned.shell });
+}
+
+/** spawnInstall without blocking: the kernel host keeps answering while it runs (#149). */
+function spawnInstallAsync(cmd, args, cwd, env = {}) {
+  const spawned = spawnCommand(cmd, args);
+  return new Promise((resolve) => {
+    let stderr = "";
+    const child = spawn(spawned.cmd, spawned.args, {
+      cwd,
+      env: { ...process.env, ...env },
+      shell: spawned.shell,
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+    child.on("error", (error) => resolve({ status: null, stderr, error }));
+    child.on("close", (status) => resolve({ status, stderr }));
+  });
+}
+
+/** The version to install for `name@range`: the locked one, if the lockfile has it. */
+function lockedRequest(name, range, lockFile) {
+  const lock = lockFile ? readLock(lockFile) : null;
+  const locked = lock?.packages[`${name}@${range}`];
+  const version = typeof locked === "string" ? locked : range;
+  return { lock, locked: typeof locked === "string", version, alias: aliasFor(name, version) };
+}
+
+/** Records an unlocked request's installed version in the lockfile. */
+function recordLock(dir, name, range, lockFile, { lock, locked, alias }) {
+  if (!lock || locked) return;
+  const resolved = installedVersion(dir, alias);
+  if (resolved !== null) {
+    lock.packages[`${name}@${range}`] = resolved;
+    writeLock(lockFile, lock);
+  }
+}
+
+function checkInstall(result, installer, name, version) {
+  if (result.status !== 0) throw new Error(`${installer} install ${name}@${version} failed:\n${result.stderr || result.error}`);
+}
+
+/**
+ * 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);
+  return withInstallLock(dir, () => {
+    const request = lockedRequest(name, range, lockFile);
+    if (installedVersion(dir, request.alias) === null) {
+      const { cmd, args, env } = installCommand(installer, request.alias, name, request.version);
+      checkInstall(run(cmd, args, dir, env), installer, name, request.version);
+    }
+    recordLock(dir, name, range, lockFile, request);
+    return { dir, alias: request.alias };
+  });
+}
+
+/** ensureInstalled for the kernel host (workerd's bundler), which mustn't block (#149). */
+export function ensureInstalledAsync({ name, range }, installer = "npm", { lockFile = null, run = spawnInstallAsync } = {}) {
   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}`);
+  return withInstallLockAsync(dir, async () => {
+    const request = lockedRequest(name, range, lockFile);
+    if (installedVersion(dir, request.alias) === null) {
+      const { cmd, args, env } = installCommand(installer, request.alias, name, request.version);
+      checkInstall(await run(cmd, args, dir, env), installer, name, request.version);
     }
+    recordLock(dir, name, range, lockFile, request);
+    return { dir, alias: request.alias };
+  });
+}
+
+// --- Imported TypeScript (#73) --------------------------------------------------
+// Node strips types in place, so line and column numbers stay those of the
+// file, but it rejects TypeScript that needs code generation. Such a file
+// is compiled with esbuild, as cells are, with an inline source map. The
+// host passes its esbuild binary in CDPK_ESBUILD_BINARY: the runtime files
+// may have been copied away from any node_modules (src/package.ts), and the
+// esbuild binary, unlike its JavaScript API, works from anywhere.
+
+// Both match a file: URL's path, so a query or fragment (`./x.ts?v=2`, the
+// cache-busting idiom for a module being edited) doesn't hide the extension (#145).
+const TS_FILE = /\.[cm]?ts$/;
+// Node has no format for these extensions, so its loader is never asked.
+const JSX_FILE = /\.([jt]sx)$/;
+const TS_FORMATS = { "module-typescript": "module", "commonjs-typescript": "commonjs" };
+
+function isUnsupportedSyntax(err) {
+  return err?.code === "ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX";
+}
+
+/** Node's strip-only transform, without its once-per-process ExperimentalWarning. */
+function stripTypes(source) {
+  const emitWarning = process.emitWarning;
+  process.emitWarning = function (warning, ...rest) {
+    if (String(warning?.message ?? warning).includes("stripTypeScriptTypes")) return;
+    return emitWarning.call(this, warning, ...rest);
+  };
+  try {
+    return module.stripTypeScriptTypes(source, { mode: "strip" });
+  } finally {
+    process.emitWarning = emitWarning;
+  }
+}
+
+/**
+ * Compiles one TypeScript (or, with loader "tsx"/"jsx", JSX) file with the
+ * esbuild binary at `binary`, as cells are compiled. JSX takes esbuild's
+ * default, classic React.createElement, which is what cells use on Node
+ * (no project config there); a file's own @jsx/@jsxImportSource pragma wins.
+ */
+export function compileTypeScript(source, filename, binary, run = spawnSync, loader = "ts") {
+  const args = [
+    `--loader=${loader}`,
+    "--target=esnext",
+    "--sourcemap=inline",
+    `--sourcefile=${filename}`,
+    '--tsconfig-raw={"compilerOptions":{"verbatimModuleSyntax":true}}',
+    "--log-level=error",
+    "--color=false",
+  ];
+  const result = run(binary, args, { input: source, encoding: "utf8", maxBuffer: 1 << 30 });
+  if (result.status !== 0) {
+    throw new SyntaxError(`${filename}: ${(result.stderr || String(result.error)).trim()}`);
+  }
+  return result.stdout;
+}
+
+/** The load hook: Node's result unless it would reject the file's TypeScript. */
+export function loadTypeScript(url, context, nextLoad, binary) {
+  const path = url.startsWith("file:") ? new URL(url).pathname : "";
+  const jsx = JSX_FILE.exec(path);
+  if (binary && jsx) {
+    // Notebooks import ES modules, so it's compiled as one.
+    const filename = fileURLToPath(url);
+    const source = compileTypeScript(readFileSync(filename, "utf8"), filename, binary, spawnSync, jsx[1]);
+    return { format: "module", source, shortCircuit: true };
+  }
+  if (!binary || !TS_FILE.test(path)) return nextLoad(url, context);
+  let result;
+  try {
+    result = nextLoad(url, context);
+  } catch (err) {
+    // A .ts file outside a package.json "type" is stripped while Node
+    // detects its format, so the rejection surfaces here. Notebooks import
+    // ES modules, so it's compiled as one.
+    if (!isUnsupportedSyntax(err)) throw err;
+    const filename = fileURLToPath(url);
+    return { format: "module", source: compileTypeScript(readFileSync(filename, "utf8"), filename, binary), shortCircuit: true };
+  }
+  const format = TS_FORMATS[result.format];
+  if (format === undefined || typeof module.stripTypeScriptTypes !== "function") return result;
+  const source = typeof result.source === "string" ? result.source : new TextDecoder().decode(result.source);
+  try {
+    return { ...result, format, source: stripTypes(source) };
+  } catch (err) {
+    if (!isUnsupportedSyntax(err)) throw err;
+    return { ...result, format, source: compileTypeScript(source, fileURLToPath(url), binary) };
   }
-  return { dir, alias };
 }
 
 export function installNodeResolveHooks({ shimUrl, replUrl }) {
+  const esbuild = process.env.CDPK_ESBUILD_BINARY;
   module.registerHooks({
+    load: (url, context, nextLoad) => loadTypeScript(url, context, nextLoad, esbuild),
     resolve(specifier, context, nextResolve) {
       let pkg = null;
       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 });
       }