@tlockney/cdp-kernel 0.0.0-stage → 0.1.1

package/runtime/deno-compat.d.mts

@@ -0,0 +1,116 @@
+export class NotFound extends Error {
+  code?: string;
+}
+export class AlreadyExists extends Error {
+  code?: string;
+}
+export class PermissionDenied extends Error {
+  code?: string;
+}
+export class IsADirectory extends Error {
+  code?: string;
+}
+export class NotADirectory extends Error {
+  code?: string;
+}
+
+export interface DenoErrors {
+  NotFound: typeof NotFound;
+  AlreadyExists: typeof AlreadyExists;
+  PermissionDenied: typeof PermissionDenied;
+  IsADirectory: typeof IsADirectory;
+  NotADirectory: typeof NotADirectory;
+}
+
+export interface FileInfo {
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymlink: boolean;
+  size: number;
+  mtime: Date | null;
+  atime: Date | null;
+  birthtime: Date | null;
+  mode: number;
+  uid: number;
+  gid: number;
+}
+
+export interface DirEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymlink: boolean;
+}
+
+export type PathLike = string | URL;
+
+export interface WriteFileOptions {
+  append?: boolean;
+  createNew?: boolean;
+}
+
+export interface MakeTempOptions {
+  dir?: string;
+  prefix?: string;
+  suffix?: string;
+}
+
+export interface DenoEnv {
+  get(key: string): string | undefined;
+  set(key: string, value: string): void;
+  delete(key: string): void;
+  has(key: string): boolean;
+  toObject(): Record<string, string | undefined>;
+}
+
+export interface DenoWriter {
+  write(bytes: Uint8Array): Promise<number>;
+  writeSync(bytes: Uint8Array): number;
+}
+
+export interface DenoShim {
+  jupyter: unknown;
+  version: { deno: string; v8: string; typescript: string };
+  build: { os: string; arch: string; target: string };
+  errors: DenoErrors;
+  pid: number;
+  args: string[];
+  noColor: boolean;
+  execPath: () => string;
+  cwd: () => string;
+  chdir: (dir: PathLike) => void;
+  exit: (code?: number) => never;
+  env: DenoEnv;
+  inspect: (value: unknown, options?: object) => string;
+
+  readTextFile: (path: PathLike) => Promise<string>;
+  readTextFileSync: (path: PathLike) => string;
+  readFile: (path: PathLike) => Promise<Uint8Array>;
+  readFileSync: (path: PathLike) => Uint8Array;
+  writeTextFile: (path: PathLike, data: string, options?: WriteFileOptions) => Promise<void>;
+  writeTextFileSync: (path: PathLike, data: string, options?: WriteFileOptions) => void;
+  writeFile: (path: PathLike, data: Uint8Array | string, options?: WriteFileOptions) => Promise<void>;
+  writeFileSync: (path: PathLike, data: Uint8Array | string, options?: WriteFileOptions) => void;
+  readDir: (path: PathLike) => AsyncIterable<DirEntry>;
+  readDirSync: (path: PathLike) => DirEntry[];
+  stat: (path: PathLike) => Promise<FileInfo>;
+  statSync: (path: PathLike) => FileInfo;
+  lstat: (path: PathLike) => Promise<FileInfo>;
+  lstatSync: (path: PathLike) => FileInfo;
+  mkdir: (path: PathLike, options?: { recursive?: boolean }) => Promise<void>;
+  mkdirSync: (path: PathLike, options?: { recursive?: boolean }) => void;
+  remove: (path: PathLike, options?: { recursive?: boolean }) => Promise<void>;
+  removeSync: (path: PathLike, options?: { recursive?: boolean }) => void;
+  rename: (from: PathLike, to: PathLike) => Promise<void>;
+  renameSync: (from: PathLike, to: PathLike) => void;
+  realPath: (path: PathLike) => Promise<string>;
+  realPathSync: (path: PathLike) => string;
+  makeTempDir: (options?: MakeTempOptions) => Promise<string>;
+  makeTempDirSync: (options?: MakeTempOptions) => string;
+  makeTempFile: (options?: MakeTempOptions) => Promise<string>;
+  stdout: DenoWriter;
+  stderr: DenoWriter;
+}
+
+export function denoError<E>(err: E): E | NotFound | AlreadyExists | PermissionDenied | IsADirectory | NotADirectory;
+export function createDenoShim(options: { jupyter: unknown }): DenoShim;

package/runtime/deno-compat.mjs

@@ -0,0 +1,185 @@
+// An opt-in `Deno` namespace for Node targets, so notebooks written for
+// `deno jupyter` keep working: Deno.jupyter plus the file, env and process
+// APIs notebooks commonly reach for, implemented on Node's.
+//
+// Opt-in because libraries feature-detect Deno with `typeof Deno`; with a
+// shim installed they take their Deno code paths, which may call APIs not
+// covered here (Deno.serve, Deno.Command, Deno.openKv, permissions...).
+// Uncovered APIs are simply absent rather than throwing on access, so
+// feature checks like `typeof Deno.serve === "function"` still work.
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import util from "node:util";
+
+class NotFound extends Error {
+  name = "NotFound";
+}
+class AlreadyExists extends Error {
+  name = "AlreadyExists";
+}
+class PermissionDenied extends Error {
+  name = "PermissionDenied";
+}
+class IsADirectory extends Error {
+  name = "IsADirectory";
+}
+class NotADirectory extends Error {
+  name = "NotADirectory";
+}
+
+const ERRNO_TO_ERROR = {
+  ENOENT: NotFound,
+  EEXIST: AlreadyExists,
+  EACCES: PermissionDenied,
+  EPERM: PermissionDenied,
+  EISDIR: IsADirectory,
+  ENOTDIR: NotADirectory,
+};
+
+/** Rethrows Node fs errors as the Deno.errors class Deno would use. */
+export function denoError(err) {
+  const Ctor = err && ERRNO_TO_ERROR[err.code];
+  if (!Ctor) return err;
+  const mapped = new Ctor(err.message, { cause: err });
+  mapped.code = err.code;
+  return mapped;
+}
+
+function sync(fn) {
+  return (...args) => {
+    try {
+      return fn(...args);
+    } catch (err) {
+      throw denoError(err);
+    }
+  };
+}
+
+function async(fn) {
+  return async (...args) => {
+    try {
+      return await fn(...args);
+    } catch (err) {
+      throw denoError(err);
+    }
+  };
+}
+
+const toPath = (p) => (p instanceof URL ? p : String(p));
+
+function fileInfo(stats) {
+  return {
+    isFile: stats.isFile(),
+    isDirectory: stats.isDirectory(),
+    isSymlink: stats.isSymbolicLink(),
+    size: stats.size,
+    mtime: stats.mtime,
+    atime: stats.atime,
+    birthtime: stats.birthtime,
+    mode: stats.mode,
+    uid: stats.uid,
+    gid: stats.gid,
+  };
+}
+
+function dirEntry(dirent) {
+  return {
+    name: dirent.name,
+    isFile: dirent.isFile(),
+    isDirectory: dirent.isDirectory(),
+    isSymlink: dirent.isSymbolicLink(),
+  };
+}
+
+const writeFlag = (options) => (options?.append ? "a" : options?.createNew ? "wx" : "w");
+
+const OS_NAMES = { darwin: "darwin", linux: "linux", win32: "windows", freebsd: "freebsd" };
+const ARCH_NAMES = { arm64: "aarch64", x64: "x86_64" };
+
+export function createDenoShim({ jupyter }) {
+  return {
+    jupyter,
+    version: { deno: "0.0.0-cdp-kernel", v8: process.versions.v8, typescript: "5" },
+    build: {
+      os: OS_NAMES[process.platform] ?? process.platform,
+      arch: ARCH_NAMES[process.arch] ?? process.arch,
+      target: `${ARCH_NAMES[process.arch] ?? process.arch}-node-${process.platform}`,
+    },
+    errors: { NotFound, AlreadyExists, PermissionDenied, IsADirectory, NotADirectory },
+    pid: process.pid,
+    args: process.argv.slice(2),
+    noColor: Boolean(process.env.NO_COLOR),
+    execPath: () => process.execPath,
+    cwd: () => process.cwd(),
+    chdir: sync((dir) => process.chdir(toPath(dir))),
+    exit: (code) => process.exit(code),
+    env: {
+      get: (key) => process.env[key],
+      set: (key, value) => {
+        process.env[key] = value;
+      },
+      delete: (key) => {
+        delete process.env[key];
+      },
+      has: (key) => Object.hasOwn(process.env, key),
+      toObject: () => ({ ...process.env }),
+    },
+    inspect: (value, options) => util.inspect(value, options),
+
+    readTextFile: async((p) => fsp.readFile(toPath(p), "utf8")),
+    readTextFileSync: sync((p) => fs.readFileSync(toPath(p), "utf8")),
+    readFile: async(async (p) => new Uint8Array(await fsp.readFile(toPath(p)))),
+    readFileSync: sync((p) => new Uint8Array(fs.readFileSync(toPath(p)))),
+    writeTextFile: async((p, data, options) => fsp.writeFile(toPath(p), data, { flag: writeFlag(options) })),
+    writeTextFileSync: sync((p, data, options) => fs.writeFileSync(toPath(p), data, { flag: writeFlag(options) })),
+    writeFile: async((p, data, options) => fsp.writeFile(toPath(p), data, { flag: writeFlag(options) })),
+    writeFileSync: sync((p, data, options) => fs.writeFileSync(toPath(p), data, { flag: writeFlag(options) })),
+    async *readDir(p) {
+      let entries;
+      try {
+        entries = await fsp.readdir(toPath(p), { withFileTypes: true });
+      } catch (err) {
+        throw denoError(err);
+      }
+      for (const entry of entries) yield dirEntry(entry);
+    },
+    readDirSync: sync((p) => fs.readdirSync(toPath(p), { withFileTypes: true }).map(dirEntry)),
+    stat: async(async (p) => fileInfo(await fsp.stat(toPath(p)))),
+    statSync: sync((p) => fileInfo(fs.statSync(toPath(p)))),
+    lstat: async(async (p) => fileInfo(await fsp.lstat(toPath(p)))),
+    lstatSync: sync((p) => fileInfo(fs.lstatSync(toPath(p)))),
+    mkdir: async((p, options) => fsp.mkdir(toPath(p), { recursive: options?.recursive ?? false }).then(() => {})),
+    mkdirSync: sync((p, options) => {
+      fs.mkdirSync(toPath(p), { recursive: options?.recursive ?? false });
+    }),
+    remove: async((p, options) => fsp.rm(toPath(p), { recursive: options?.recursive ?? false })),
+    removeSync: sync((p, options) => fs.rmSync(toPath(p), { recursive: options?.recursive ?? false })),
+    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))),
+    makeTempDir: async((options) =>
+      fsp.mkdtemp(path.join(options?.dir ?? os.tmpdir(), options?.prefix ?? "deno-"))
+    ),
+    makeTempDirSync: sync((options) =>
+      fs.mkdtempSync(path.join(options?.dir ?? os.tmpdir(), options?.prefix ?? "deno-"))
+    ),
+    makeTempFile: async(async (options) => {
+      const dir = await fsp.mkdtemp(path.join(options?.dir ?? os.tmpdir(), "deno-"));
+      const file = path.join(dir, `${options?.prefix ?? ""}tmp${options?.suffix ?? ""}`);
+      await fsp.writeFile(file, "");
+      return file;
+    }),
+    stdout: {
+      write: (bytes) => new Promise((resolve) => process.stdout.write(bytes, () => resolve(bytes.length))),
+      writeSync: (bytes) => (process.stdout.write(bytes), bytes.length),
+    },
+    stderr: {
+      write: (bytes) => new Promise((resolve) => process.stderr.write(bytes, () => resolve(bytes.length))),
+      writeSync: (bytes) => (process.stderr.write(bytes), bytes.length),
+    },
+  };
+}

package/runtime/display.d.mts

@@ -0,0 +1,48 @@
+export const $display: unique symbol;
+
+export type MediaBundle = { [mediaType: string]: unknown };
+
+export interface DisplayHost {
+  inspect: (value: unknown) => string;
+  base64: (bytes: Uint8Array) => string;
+  readFile: (path: string) => Uint8Array;
+  send: (msgType: string, content: object, metadata: object, buffers: Uint8Array[]) => void;
+  input: (prompt: string, password: boolean) => string | null;
+}
+
+export interface DisplayOptions {
+  raw?: boolean;
+  update?: boolean;
+  display_id?: string;
+}
+
+export interface Displayable {
+  [$display]: () => MediaBundle | Promise<MediaBundle>;
+}
+
+export interface JupyterNamespace {
+  broadcast(
+    msgType: string,
+    content: object,
+    options?: { metadata?: object; buffers?: Uint8Array[] },
+  ): void;
+  display(obj: unknown, options?: DisplayOptions): Promise<void>;
+  format(obj: unknown): Promise<MediaBundle>;
+  md(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  html(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  svg(strings: TemplateStringsArray, ...values: unknown[]): Displayable;
+  image(obj: string | Uint8Array): Displayable;
+  $display: typeof $display;
+}
+
+export interface Jupyter {
+  namespace: JupyterNamespace;
+  broadcastResult(executionCount: number, result: unknown): Promise<void>;
+  confirm(message?: string): boolean;
+  prompt(message?: string, defaultValue?: string, options?: { password?: boolean }): string | null;
+}
+
+export function escapeHTML(str: string): string;
+export function isJpg(obj: unknown): boolean;
+export function isPng(obj: unknown): boolean;
+export function createJupyter(host: DisplayHost): Jupyter;

package/runtime/display.mjs

@@ -0,0 +1,237 @@
+// The Jupyter display API that Deno exposes as `Deno.jupyter`, made
+// runtime-neutral. Runs inside the target runtime (Node or Deno).
+//
+// Ported from Deno's cli/js/40_jupyter.js (v2.9.6), which is
+// Copyright 2018-2026 the Deno authors, MIT license. The formatting rules
+// (display symbol, canvas, Vega, Polars-style DataFrames, JPEG/PNG bytes,
+// HTML/SVG elements) are unchanged; the Deno internals it used are injected:
+//   Deno[Deno.internal].inspectArgs -> host.inspect
+//   op_base64_encode_from_buffer    -> host.base64
+//   Deno.readFileSync               -> host.readFile
+//   op_jupyter_broadcast            -> host.send
+// WebGPU texture/buffer display depends on Deno's wgpu bindings and is
+// omitted.
+
+export const $display = Symbol.for("Jupyter.display");
+
+const rawToEntity = new Map([
+  ["&", "&"],
+  ["<", "&lt;"],
+  [">", "&gt;"],
+  ['"', "&quot;"],
+  ["'", "&#39;"],
+]);
+const rawRe = new RegExp(`[${[...rawToEntity.keys()].join("")}]`, "g");
+
+export function escapeHTML(str) {
+  return str.replaceAll(rawRe, (m) => rawToEntity.get(m) ?? m);
+}
+
+function isVegaLike(obj) {
+  return obj !== null && typeof obj === "object" && "toSpec" in obj;
+}
+
+function extractVega(obj) {
+  const spec = obj.toSpec();
+  if (typeof spec !== "object" || spec === null || !("$schema" in spec)) return null;
+  let mediaType = "application/vnd.vega.v5+json";
+  if (spec.$schema === "https://vega.github.io/schema/vega-lite/v4.json") {
+    mediaType = "application/vnd.vegalite.v4+json";
+  } else if (spec.$schema === "https://vega.github.io/schema/vega-lite/v5.json") {
+    mediaType = "application/vnd.vegalite.v5+json";
+  }
+  return { [mediaType]: spec };
+}
+
+function isDataFrameLike(obj) {
+  return obj !== null && typeof obj === "object" &&
+    obj.schema !== undefined && typeof obj.schema === "object" &&
+    typeof obj.head === "function" && typeof obj.toRecords === "function";
+}
+
+function mapPolarsTypeToJSONSchema(colType) {
+  const typeMapping = {
+    Null: "null",
+    Bool: "boolean",
+    Int8: "integer",
+    Int16: "integer",
+    Int32: "integer",
+    Int64: "integer",
+    UInt8: "integer",
+    UInt16: "integer",
+    UInt32: "integer",
+    UInt64: "integer",
+    Float32: "number",
+    Float64: "number",
+    Date: "string",
+    Datetime: "string",
+    Utf8: "string",
+    Categorical: "string",
+    List: "array",
+    Struct: "object",
+  };
+  // Polars DataTypes only expose their name through toJSON().
+  const dataType = typeof colType?.toJSON === "function" ? colType.toJSON()["DataType"] : undefined;
+  return typeMapping[dataType] || "string";
+}
+
+function extractDataFrame(df) {
+  const fields = [];
+  for (const [name, colType] of Object.entries(df.schema)) {
+    fields.push({ name, type: mapPolarsTypeToJSONSchema(colType) });
+  }
+  const data = df.head(50).toRecords();
+  let html = "<table><thead><tr>";
+  for (const field of fields) html += `<th>${escapeHTML(String(field.name))}</th>`;
+  html += "</tr></thead><tbody>";
+  for (const row of df.head(10).toRecords()) {
+    html += "<tr>";
+    for (const field of fields) html += `<td>${escapeHTML(String(row[field.name]))}</td>`;
+    html += "</tr>";
+  }
+  html += "</tbody></table>";
+  return {
+    "application/vnd.dataresource+json": { data, schema: { fields } },
+    "text/html": html,
+  };
+}
+
+function isCanvasLike(obj) {
+  return obj !== null && typeof obj === "object" && "toDataURL" in obj;
+}
+
+export function isJpg(obj) {
+  return obj instanceof Uint8Array && obj.length >= 4 &&
+    obj[0] === 0xff && obj[1] === 0xd8 &&
+    obj[obj.length - 2] === 0xff && obj[obj.length - 1] === 0xd9;
+}
+
+const PNG_SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+
+export function isPng(obj) {
+  return obj instanceof Uint8Array && obj.length >= PNG_SIGNATURE.length &&
+    PNG_SIGNATURE.every((byte, i) => obj[i] === byte);
+}
+
+function isSVGElementLike(obj) {
+  return obj !== null && typeof obj === "object" && typeof obj.outerHTML === "string" &&
+    obj.outerHTML.startsWith("<svg");
+}
+
+function isHTMLElementLike(obj) {
+  return obj !== null && typeof obj === "object" && typeof obj.outerHTML === "string";
+}
+
+function hasDisplaySymbol(obj) {
+  return obj !== null && typeof obj === "object" && typeof obj[$display] === "function";
+}
+
+function isMediaBundle(obj) {
+  return obj !== null && typeof obj === "object" && !Array.isArray(obj);
+}
+
+/**
+ * @param {{
+ *   inspect: (value: unknown) => string,
+ *   base64: (bytes: Uint8Array) => string,
+ *   readFile: (path: string) => Uint8Array,
+ *   send: (msgType: string, content: object, metadata: object, buffers: Uint8Array[]) => void,
+ *   input: (prompt: string, password: boolean) => string | null,
+ * }} host
+ */
+export function createJupyter(host) {
+  async function format(obj) {
+    if (hasDisplaySymbol(obj)) return await obj[$display]();
+    if (typeof obj !== "object" || obj === null) return { "text/plain": host.inspect(obj) };
+    if (isCanvasLike(obj)) {
+      const [prefix, data] = obj.toDataURL().split(",");
+      return { [prefix.split(":")[1].split(";")[0]]: data };
+    }
+    if (isVegaLike(obj)) {
+      const vega = extractVega(obj);
+      if (vega) return vega;
+    }
+    if (isDataFrameLike(obj)) return extractDataFrame(obj);
+    if (isJpg(obj)) return { "image/jpeg": host.base64(obj) };
+    if (isPng(obj)) return { "image/png": host.base64(obj) };
+    if (isSVGElementLike(obj)) return { "image/svg+xml": obj.outerHTML };
+    if (isHTMLElementLike(obj)) return { "text/html": obj.outerHTML };
+    return { "text/plain": host.inspect(obj) };
+  }
+
+  function taggedTemplate(mediatype) {
+    return (strings, ...values) => {
+      const payload = strings.reduce((acc, string, i) =>
+        acc + string + (values[i] !== undefined ? values[i] : ""), "");
+      return { [$display]: () => ({ [mediatype]: payload }) };
+    };
+  }
+
+  function image(obj) {
+    if (typeof obj === "string") obj = host.readFile(obj);
+    if (isJpg(obj)) return { [$display]: () => ({ "image/jpeg": host.base64(obj) }) };
+    if (isPng(obj)) return { [$display]: () => ({ "image/png": host.base64(obj) }) };
+    throw new TypeError(
+      "Object is not a valid image or a path to an image. `jupyter.image` supports displaying JPG or PNG images.",
+    );
+  }
+
+  function broadcast(msgType, content, { metadata = {}, buffers = [] } = {}) {
+    host.send(msgType, content, metadata, buffers);
+  }
+
+  async function display(obj, options = { raw: false, update: false }) {
+    const bundle = options.raw && isMediaBundle(obj) ? obj : await format(obj);
+    broadcast(options.update ? "update_display_data" : "display_data", {
+      data: bundle,
+      metadata: {},
+      transient: options.display_id ? { display_id: options.display_id } : {},
+    });
+  }
+
+  async function broadcastResult(executionCount, result) {
+    if (result === undefined) return;
+    try {
+      broadcast("execute_result", {
+        execution_count: executionCount,
+        data: await format(result),
+        metadata: {},
+        // nbclient crashes on a null `transient`; Deno learned this too.
+        transient: {},
+      });
+    } catch (err) {
+      broadcast("error", {
+        ename: err instanceof Error ? err.name : "Error",
+        evalue: err instanceof Error ? err.message : String(err),
+        traceback: err instanceof Error && err.stack ? err.stack.split("\n") : [],
+      });
+    }
+  }
+
+  function confirm(message = "Confirm") {
+    const answer = host.input(`${message} [y/N] `, false);
+    return answer === "Y" || answer === "y";
+  }
+
+  function prompt(message = "Prompt", defaultValue = "", { password = false } = {}) {
+    if (defaultValue != "") message += ` [${defaultValue}]`;
+    const answer = host.input(message, password);
+    return answer === "" ? defaultValue : answer;
+  }
+
+  return {
+    namespace: {
+      broadcast,
+      display,
+      format,
+      md: taggedTemplate("text/markdown"),
+      html: taggedTemplate("text/html"),
+      svg: taggedTemplate("image/svg+xml"),
+      image,
+      $display,
+    },
+    broadcastResult,
+    confirm,
+    prompt,
+  };
+}

package/runtime/node-hooks.d.mts

@@ -0,0 +1,10 @@
+export interface PackageSpecifier {
+  name: string;
+  range: string;
+  subpath: string;
+}
+
+export function parsePackageSpecifier(spec: string): PackageSpecifier;
+export function jsrToNpm(spec: string): PackageSpecifier;
+export function aliasFor(name: string, range: string): string;
+export function installNodeResolveHooks(urls: { shimUrl: string; replUrl: string }): void;

package/runtime/node-hooks.mjs

@@ -0,0 +1,87 @@
+// 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
+//     parent; re-parent them to the notebook's directory so "./x.ts" and
+//     bare package names resolve where the user expects.
+//   - npm:<name>[@range][/subpath] installs on first use into a per-user
+//     cache, each request under its own npm alias so different ranges of
+//     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.
+// Uses module.registerHooks (synchronous, in-thread; Node >= 23.5), so the
+// install can run with spawnSync inside resolve.
+
+import { registerHooks } from "node:module";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const SPEC_RE = /^((?:@[^/@]+\/)?[^/@]+)(?:@([^/]+))?(\/.*)?$/;
+
+/** Splits "name@range/sub/path" (name may be scoped). */
+export function parsePackageSpecifier(spec) {
+  const m = SPEC_RE.exec(spec);
+  if (!m) throw new TypeError(`invalid package specifier: ${spec}`);
+  return { name: m[1], range: m[2] ?? "*", subpath: m[3] ?? "" };
+}
+
+/** jsr:@std/path@^1/posix -> npm @jsr/std__path@^1 /posix */
+export function jsrToNpm(spec) {
+  const { name, range, subpath } = parsePackageSpecifier(spec);
+  const m = /^@([^/]+)\/(.+)$/.exec(name);
+  if (!m) throw new TypeError(`jsr packages are scoped: jsr:${spec}`);
+  return { name: `@jsr/${m[1]}__${m[2]}`, range, subpath };
+}
+
+export function aliasFor(name, range) {
+  const digest = createHash("sha256").update(`${name}@${range}`).digest("hex").slice(0, 12);
+  return `cdpk-${digest}`;
+}
+
+function cacheDir() {
+  const dir = process.env.CDPK_CACHE_DIR ?? join(homedir(), ".cache", "cdp-kernel", "npm");
+  if (!existsSync(join(dir, "package.json"))) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "package.json"), '{ "private": true }\n');
+    writeFileSync(join(dir, ".npmrc"), "@jsr:registry=https://npm.jsr.io\n");
+  }
+  return dir;
+}
+
+function ensureInstalled({ name, range }) {
+  const dir = cacheDir();
+  const alias = aliasFor(name, range);
+  if (!existsSync(join(dir, "node_modules", alias, "package.json"))) {
+    const result = spawnSync(
+      "npm",
+      ["install", "--no-audit", "--no-fund", "--loglevel=error", `${alias}@npm:${name}@${range}`],
+      { cwd: dir, encoding: "utf8" },
+    );
+    if (result.status !== 0) {
+      throw new Error(`npm install ${name}@${range} failed:\n${result.stderr || result.error}`);
+    }
+  }
+  return { dir, alias };
+}
+
+export function installNodeResolveHooks({ shimUrl, replUrl }) {
+  registerHooks({
+    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 parentURL = pathToFileURL(join(dir, "package.json")).href;
+        return nextResolve(alias + pkg.subpath, { ...context, parentURL });
+      }
+      if (context.parentURL === shimUrl) {
+        return nextResolve(specifier, { ...context, parentURL: replUrl });
+      }
+      return nextResolve(specifier, context);
+    },
+  });
+}