@ttsc/playground 0.14.0-dev.20260528.1

package/src/compiler/normalizeError.ts

@@ -0,0 +1,12 @@
+/** Best-effort error normalization for tgrid transport. */
+export function normalizeError(error: unknown): unknown {
+  if (error instanceof Error)
+    return { name: error.name, message: error.message, stack: error.stack };
+  if (
+    error &&
+    typeof error === "object" &&
+    "message" in (error as Record<string, unknown>)
+  )
+    return error;
+  return { name: "Error", message: String(error) };
+}

package/src/compiler/normalizeNodeModulePath.ts

@@ -0,0 +1,13 @@
+/**
+ * Accept either `node_modules/...` or `/node_modules/...` (or backslash
+ * variants); reject anything that escapes the node_modules root via `..`.
+ *
+ * Returns `null` for paths that don't match the expected shape — the caller
+ * skips those entries instead of writing them to the MemFS.
+ */
+export function normalizeNodeModulePath(path: string): string | null {
+  const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized.startsWith("node_modules/")) return null;
+  if (normalized.split("/").some((segment) => segment === "..")) return null;
+  return normalized;
+}

package/src/compiler/pickEmittedJS.ts

@@ -0,0 +1,23 @@
+/**
+ * Pick the most likely emitted JavaScript file from a compile result's output
+ * map. Tries common paths first, then falls back to the first `.js` entry.
+ * Returns null when no `.js` was emitted.
+ */
+export function pickEmittedJS(
+  output: Record<string, string>,
+  entryFile: string,
+): string | null {
+  const base = entryFile.replace(/\.[cm]?tsx?$/i, ".js");
+  const candidates = [
+    `dist/${base}`,
+    `dist/src/${base}`,
+    `src/${base}`,
+    base,
+  ];
+  for (const key of candidates) {
+    if (output[key] !== undefined) return output[key];
+  }
+  const jsKeys = Object.keys(output).filter((k) => k.endsWith(".js"));
+  if (jsKeys.length > 0) return output[jsKeys[0]!] ?? null;
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * `@ttsc/playground` — reusable Web Worker + React scaffolding for in-browser
+ * ttsc playgrounds built on `@ttsc/wasm`.
+ *
+ * The package is organized by concern: the `compiler/*` modules implement the
+ * worker-side `ICompilerService` contract; the `npm/*` modules install
+ * on-the-fly npm dependencies into the wasm MemFS; the `sandbox/*` modules
+ * drive an in-page `new Function` execute sandbox; the `react/*` modules
+ * render the shell, editor, and result panes.
+ *
+ * The package root re-exports everything; sub-path imports are not needed.
+ */
+
+// ── compiler / worker core ────────────────────────────────────────────────
+export { buildTsconfigJSON } from "./compiler/buildTsconfigJSON";
+export { createTypiaSourcePackMount } from "./compiler/createTypiaSourcePackMount";
+export { createWorkerCompiler } from "./compiler/createWorkerCompiler";
+export { DEFAULT_ENTRY_FILE } from "./compiler/DEFAULT_ENTRY_FILE";
+export { DEFAULT_LINT_PLUGIN_NAME } from "./compiler/DEFAULT_LINT_PLUGIN_NAME";
+export { DEFAULT_PLAYGROUND_COMPILER_OPTIONS } from "./compiler/DEFAULT_PLAYGROUND_COMPILER_OPTIONS";
+export { DEFAULT_TSCONFIG_PATH } from "./compiler/DEFAULT_TSCONFIG_PATH";
+export { DEFAULT_TYPIA_PLUGIN_NAME } from "./compiler/DEFAULT_TYPIA_PLUGIN_NAME";
+export { DEFAULT_WORK_DIR } from "./compiler/DEFAULT_WORK_DIR";
+export { installDependenciesIntoMemFS } from "./compiler/installDependenciesIntoMemFS";
+export { installTypiaSourcePack } from "./compiler/installTypiaSourcePack";
+export { lineColumnOf } from "./compiler/lineColumnOf";
+export { loadTypiaSourcePack } from "./compiler/loadTypiaSourcePack";
+export { mapDiagnostic } from "./compiler/mapDiagnostic";
+export { normalizeError } from "./compiler/normalizeError";
+export { normalizeNodeModulePath } from "./compiler/normalizeNodeModulePath";
+export { pickEmittedJS } from "./compiler/pickEmittedJS";
+
+// ── npm-from-the-browser dependency installer ─────────────────────────────
+export { BUILT_IN_PLAYGROUND_PACKAGES } from "./npm/BUILT_IN_PLAYGROUND_PACKAGES";
+export { collectExternalPackageNames } from "./npm/collectExternalPackageNames";
+export { installPlaygroundDependencies } from "./npm/installPlaygroundDependencies";
+export { packageNameFromSpecifier } from "./npm/packageNameFromSpecifier";
+
+// ── typia runtime sandbox (CJS-flavoured require over a pack JSON) ────────
+export { createSandboxRequire } from "./sandbox/createSandboxRequire";
+export { loadTypiaRuntimePack } from "./sandbox/loadTypiaRuntimePack";
+
+// ── React UI surface ──────────────────────────────────────────────────────
+export { ConsoleViewer } from "./react/ConsoleViewer";
+export { createCompilerClient } from "./react/createCompilerClient";
+export { DEFAULT_OPTION_TOGGLES } from "./react/DEFAULT_OPTION_TOGGLES";
+export { DependencyProgressModal } from "./react/DependencyProgressModal";
+export { DiagnosticsPanel } from "./react/DiagnosticsPanel";
+export { ExamplePicker } from "./react/ExamplePicker";
+export { LintPane } from "./react/LintPane";
+export { OptionsPanel } from "./react/OptionsPanel";
+export { PlaygroundShell } from "./react/PlaygroundShell";
+export { ResultViewer } from "./react/ResultViewer";
+export { SourceEditor } from "./react/SourceEditor";
+
+// ── structured types ──────────────────────────────────────────────────────
+export * from "./structures/index";

package/src/npm/BUILT_IN_PLAYGROUND_PACKAGES.ts

@@ -0,0 +1,11 @@
+/**
+ * Packages the typia source pack already mounts inside the wasm. The npm
+ * installer skips these so it doesn't try to fetch typia / @typia/* from
+ * the registry on top of the mounted source tree.
+ */
+export const BUILT_IN_PLAYGROUND_PACKAGES = [
+  "typia",
+  "@typia/interface",
+  "@typia/utils",
+  "@standard-schema/spec",
+] as const;

package/src/npm/collectExternalPackageNames.ts

@@ -0,0 +1,34 @@
+import { BUILT_IN_PLAYGROUND_PACKAGES } from "./BUILT_IN_PLAYGROUND_PACKAGES";
+import { packageNameFromSpecifier } from "./packageNameFromSpecifier";
+
+const MODULE_SPECIFIER_REGEXP =
+  /\b(?:import|export)\s+(?:type\s+)?(?:[^"'()]*?\s+from\s*)?["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)|require\s*\(\s*["']([^"']+)["']\s*\)/g;
+
+/**
+ * Scan `source` for `import` / `require` specifiers and return the unique
+ * sorted list of bare npm package names that are not in `ignoredPackages`.
+ */
+export function collectExternalPackageNames(
+  source: string,
+  ignoredPackages: Iterable<string> = BUILT_IN_PLAYGROUND_PACKAGES,
+): string[] {
+  const ignored = new Set(ignoredPackages);
+  const found = new Set<string>();
+  for (const specifier of collectModuleSpecifiers(source)) {
+    const packageName = packageNameFromSpecifier(specifier);
+    if (packageName && !ignored.has(packageName)) found.add(packageName);
+  }
+  return [...found].sort();
+}
+
+function collectModuleSpecifiers(source: string): string[] {
+  const out: string[] = [];
+  MODULE_SPECIFIER_REGEXP.lastIndex = 0;
+  for (;;) {
+    const match = MODULE_SPECIFIER_REGEXP.exec(source);
+    if (!match) break;
+    const specifier = match[1] ?? match[2] ?? match[3];
+    if (specifier) out.push(specifier);
+  }
+  return out;
+}

package/src/npm/installPlaygroundDependencies.ts

@@ -0,0 +1,163 @@
+import type { IPlaygroundDependencyInstallOptions } from "../structures/IPlaygroundDependencyInstallOptions";
+import type { IPlaygroundDependencyInstallResult } from "../structures/IPlaygroundDependencyInstallResult";
+import type { IPlaygroundDependencyProgressPhase } from "../structures/IPlaygroundDependencyProgressPhase";
+import { BUILT_IN_PLAYGROUND_PACKAGES } from "./BUILT_IN_PLAYGROUND_PACKAGES";
+import {
+  DECLARATION_FILE_REGEXP,
+  downloadTarball,
+  enqueuePackageDependencies,
+  fetchNpmMetadata,
+  type IQueueItem,
+  mountPackageFiles,
+  selectVersion,
+  throwIfAborted,
+  toTypesPackageName,
+  unpackNpmTarball,
+} from "./internal/npmRegistry";
+
+const DEFAULT_MAX_PACKAGES = 48;
+
+/**
+ * Resolve, download, and unpack a set of npm packages directly inside the
+ * browser, returning their files keyed for the wasm-side MemFS, Monaco's
+ * extra-libs registry, and the in-page execute sandbox `require`.
+ *
+ * Transitive dependencies are followed via the resolved `package.json`'s
+ * `dependencies` and (non-optional) `peerDependencies` fields. The walk is
+ * bounded by `maxPackages` to keep a single keystroke from exhausting the
+ * tab's network/memory budget.
+ */
+export async function installPlaygroundDependencies(
+  packageNames: Iterable<string>,
+  options: IPlaygroundDependencyInstallOptions = {},
+): Promise<IPlaygroundDependencyInstallResult> {
+  const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  if (!fetchImpl) {
+    throw new Error("installPlaygroundDependencies requires fetch.");
+  }
+  throwIfAborted(options.signal);
+
+  const ignored = new Set(
+    options.ignoredPackages ?? BUILT_IN_PLAYGROUND_PACKAGES,
+  );
+  const installed = new Set(options.installedPackages ?? []);
+  const maxPackages = options.maxPackages ?? DEFAULT_MAX_PACKAGES;
+  const queue: IQueueItem[] = [];
+  const queued = new Set<string>();
+  const done = new Set<string>();
+  const result: IPlaygroundDependencyInstallResult = {
+    packages: [],
+    compilerFiles: {},
+    editorLibs: {},
+    runtimeFiles: {},
+  };
+
+  const enqueue = (item: IQueueItem): void => {
+    if (ignored.has(item.name) || installed.has(item.name)) return;
+    if (queued.has(item.name) || done.has(item.name)) return;
+    queued.add(item.name);
+    queue.push(item);
+    report("queued", item, `Queued ${item.name}`);
+  };
+
+  const report = (
+    phase: IPlaygroundDependencyProgressPhase,
+    item: IQueueItem | null,
+    message: string,
+    version?: string,
+  ): void => {
+    options.onProgress?.({
+      phase,
+      packageName: item?.name,
+      version,
+      completed: done.size,
+      total: Math.max(queue.length, done.size + (item ? 1 : 0)),
+      message,
+    });
+  };
+
+  for (const name of packageNames) {
+    enqueue({ name, range: "latest", optional: false });
+  }
+
+  for (let index = 0; index < queue.length; index++) {
+    if (done.size >= maxPackages) {
+      throw new Error(
+        `Dependency install stopped after ${maxPackages} packages. Narrow the imports or raise maxPackages.`,
+      );
+    }
+
+    const item = queue[index]!;
+    if (installed.has(item.name) || done.has(item.name)) continue;
+    throwIfAborted(options.signal);
+
+    report("resolve", item, `Resolving ${item.name}`);
+    const metadata = await fetchNpmMetadata(
+      fetchImpl,
+      item.name,
+      item.optional,
+      options.signal,
+    );
+    throwIfAborted(options.signal);
+    if (!metadata) {
+      done.add(item.name);
+      report("skip", item, `Skipped optional ${item.name}`);
+      continue;
+    }
+
+    const version = selectVersion(metadata, item.range);
+    const versionMetadata = metadata.versions[version];
+    const tarball = versionMetadata?.dist?.tarball;
+    if (!versionMetadata || !tarball) {
+      if (item.optional) {
+        done.add(item.name);
+        report("skip", item, `Skipped optional ${item.name}`);
+        continue;
+      }
+      throw new Error(`No tarball found for ${item.name}@${version}.`);
+    }
+
+    report("download", item, `Downloading ${item.name}@${version}`, version);
+    const tgz = await downloadTarball(fetchImpl, tarball, options.signal);
+    throwIfAborted(options.signal);
+    report("extract", item, `Extracting ${item.name}@${version}`, version);
+    const unpacked = await unpackNpmTarball(tgz, options.signal);
+    throwIfAborted(options.signal);
+    const packageJson = {
+      ...versionMetadata,
+      ...unpacked.packageJson,
+    };
+    const mounted = mountPackageFiles(item.name, unpacked.files);
+
+    Object.assign(result.compilerFiles, mounted.compilerFiles);
+    Object.assign(result.editorLibs, mounted.editorLibs);
+    Object.assign(result.runtimeFiles, mounted.runtimeFiles);
+
+    const declarationCount = Object.keys(mounted.editorLibs).filter((key) =>
+      DECLARATION_FILE_REGEXP.test(key),
+    ).length;
+    result.packages.push({
+      name: item.name,
+      version,
+      tarball,
+      fileCount: Object.keys(mounted.compilerFiles).length,
+      declarationCount,
+    });
+
+    done.add(item.name);
+    installed.add(item.name);
+    report("done", item, `Installed ${item.name}@${version}`, version);
+
+    enqueuePackageDependencies(packageJson, enqueue);
+    if (declarationCount === 0 && !item.name.startsWith("@types/")) {
+      enqueue({
+        name: toTypesPackageName(item.name),
+        range: "latest",
+        optional: true,
+      });
+    }
+  }
+
+  report("done", null, "Dependency install complete");
+  return result;
+}

package/src/npm/internal/npmRegistry.ts

@@ -0,0 +1,288 @@
+// Internal npm-registry helpers used by `installPlaygroundDependencies`.
+// Grouped in one file because every helper is privately coupled to the tar
+// + version-resolve + tarball-extract flow; splitting them per the public
+// "one symbol per file" rule would make the install path harder to follow.
+
+interface IPackageJson {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+}
+
+export interface INpmVersionMetadata {
+  name: string;
+  version: string;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  dist?: {
+    tarball?: string;
+  };
+}
+
+export interface INpmMetadata {
+  name: string;
+  "dist-tags"?: Record<string, string>;
+  versions: Record<string, INpmVersionMetadata | undefined>;
+}
+
+export interface IUnpackedPackage {
+  files: Record<string, string>;
+  packageJson: IPackageJson;
+}
+
+export interface IQueueItem {
+  name: string;
+  range: string;
+  optional: boolean;
+}
+
+export type FetchLike = (
+  input: string,
+  init?: RequestInit,
+) => Promise<Response>;
+
+const TEXT_FILE_REGEXP =
+  /(^package\.json$|\.([cm]?js|jsx|[cm]?ts|tsx|json)$|\.d\.[cm]?ts$)/i;
+export const DECLARATION_FILE_REGEXP = /\.d\.[cm]?ts$/i;
+const RUNTIME_FILE_REGEXP = /(^package\.json$|\.([cm]?js|json)$)/i;
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  if (signal.reason !== undefined) throw signal.reason;
+  throw new DOMException("The operation was aborted.", "AbortError");
+}
+
+export async function fetchNpmMetadata(
+  fetchImpl: FetchLike,
+  packageName: string,
+  optional: boolean,
+  signal: AbortSignal | undefined,
+): Promise<INpmMetadata | null> {
+  const response = await fetchImpl(
+    `https://registry.npmjs.org/${encodeURIComponent(packageName)}`,
+    {
+      headers: {
+        Accept: "application/vnd.npm.install-v1+json, application/json",
+      },
+      signal,
+    },
+  );
+  if (response.status === 404 && optional) return null;
+  if (!response.ok) {
+    throw new Error(
+      `npm registry returned ${response.status} while resolving ${packageName}.`,
+    );
+  }
+  return (await response.json()) as INpmMetadata;
+}
+
+export function selectVersion(metadata: INpmMetadata, range: string): string {
+  const versions = metadata.versions;
+  if (versions[range]) return range;
+  const tag = metadata["dist-tags"]?.[range];
+  if (tag && versions[tag]) return tag;
+  const normalized = range.replace(/^[~^<>= ]+/, "").trim();
+  if (normalized && versions[normalized]) return normalized;
+  const latest = metadata["dist-tags"]?.latest;
+  if (latest && versions[latest]) return latest;
+  const all = Object.keys(versions).sort(compareVersionDesc);
+  const fallback = all[0];
+  if (!fallback) throw new Error(`No versions found for ${metadata.name}.`);
+  return fallback;
+}
+
+export async function downloadTarball(
+  fetchImpl: FetchLike,
+  tarball: string,
+  signal: AbortSignal | undefined,
+): Promise<ArrayBuffer> {
+  const response = await fetchImpl(tarball, { signal });
+  if (!response.ok) {
+    throw new Error(`tarball download failed with HTTP ${response.status}.`);
+  }
+  return response.arrayBuffer();
+}
+
+export async function unpackNpmTarball(
+  tgz: ArrayBuffer,
+  signal: AbortSignal | undefined,
+): Promise<IUnpackedPackage> {
+  throwIfAborted(signal);
+  const tar = await gunzip(tgz);
+  throwIfAborted(signal);
+  const decoder = new TextDecoder();
+  const files: Record<string, string> = {};
+  let packageJson: IPackageJson = {};
+  let offset = 0;
+  let longPath: string | null = null;
+  let paxPath: string | null = null;
+
+  while (offset + 512 <= tar.length) {
+    throwIfAborted(signal);
+    const header = tar.subarray(offset, offset + 512);
+    offset += 512;
+    if (header.every((value) => value === 0)) break;
+
+    const type = String.fromCharCode(header[156] ?? 0);
+    const size = parseOctal(header.subarray(124, 136));
+    const body = tar.subarray(offset, offset + size);
+    offset += Math.ceil(size / 512) * 512;
+
+    if (type === "L") {
+      longPath = trimNull(decoder.decode(body));
+      continue;
+    }
+    if (type === "x") {
+      paxPath = parsePaxPath(decoder.decode(body));
+      continue;
+    }
+    if (type !== "0" && type !== "\0") {
+      longPath = null;
+      paxPath = null;
+      continue;
+    }
+
+    const rawPath =
+      paxPath ?? longPath ?? readTarString(header.subarray(0, 100), decoder);
+    longPath = null;
+    paxPath = null;
+    const rel = stripTarRoot(rawPath);
+    if (!rel || !TEXT_FILE_REGEXP.test(rel)) continue;
+
+    const text = decoder.decode(body);
+    files[rel] = text;
+    if (rel === "package.json") {
+      try {
+        packageJson = JSON.parse(text) as IPackageJson;
+      } catch {
+        packageJson = {};
+      }
+    }
+  }
+
+  return { files, packageJson };
+}
+
+async function gunzip(input: ArrayBuffer): Promise<Uint8Array> {
+  if (!("DecompressionStream" in globalThis)) {
+    throw new Error(
+      "This browser cannot unpack npm tgz files because DecompressionStream is unavailable.",
+    );
+  }
+  const stream = new Blob([input])
+    .stream()
+    .pipeThrough(new DecompressionStream("gzip"));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+export interface IMountedFiles {
+  compilerFiles: Record<string, string>;
+  editorLibs: Record<string, string>;
+  runtimeFiles: Record<string, string>;
+}
+
+export function mountPackageFiles(
+  packageName: string,
+  files: Record<string, string>,
+): IMountedFiles {
+  const compilerFiles: Record<string, string> = {};
+  const editorLibs: Record<string, string> = {};
+  const runtimeFiles: Record<string, string> = {};
+
+  for (const [rel, text] of Object.entries(files)) {
+    const packageRel = `${packageName}/${rel}`;
+    compilerFiles[`node_modules/${packageRel}`] = text;
+    if (rel === "package.json" || DECLARATION_FILE_REGEXP.test(rel)) {
+      editorLibs[`file:///node_modules/${packageRel}`] = text;
+    }
+    if (RUNTIME_FILE_REGEXP.test(rel)) {
+      runtimeFiles[packageRel] = text;
+    }
+  }
+
+  return { compilerFiles, editorLibs, runtimeFiles };
+}
+
+export function enqueuePackageDependencies(
+  packageJson: { dependencies?: Record<string, string>; peerDependencies?: Record<string, string>; peerDependenciesMeta?: Record<string, { optional?: boolean }> },
+  enqueue: (item: IQueueItem) => void,
+): void {
+  for (const [name, range] of Object.entries(packageJson.dependencies ?? {})) {
+    if (isRegistryRange(range)) enqueue({ name, range, optional: false });
+  }
+  for (const [name, range] of Object.entries(
+    packageJson.peerDependencies ?? {},
+  )) {
+    const optional =
+      packageJson.peerDependenciesMeta?.[name]?.optional === true;
+    // Truly optional peers (peerDependenciesMeta[name].optional === true)
+    // are never enqueued. Required peers MUST propagate optional: false so
+    // a 404 on the registry surfaces as an install failure instead of a
+    // silent skip that leaves the wasm-side compile reporting a generic
+    // "Cannot find module" with no breadcrumb back to the dep installer.
+    if (!optional && isRegistryRange(range))
+      enqueue({ name, range, optional: false });
+  }
+}
+
+function isRegistryRange(range: string): boolean {
+  return !/^(file:|link:|workspace:|portal:|git\+|github:|https?:)/.test(range);
+}
+
+export function toTypesPackageName(packageName: string): string {
+  if (!packageName.startsWith("@")) return `@types/${packageName}`;
+  const [scope, name] = packageName.slice(1).split("/");
+  return scope && name ? `@types/${scope}__${name}` : `@types/${packageName}`;
+}
+
+function readTarString(bytes: Uint8Array, decoder: TextDecoder): string {
+  return trimNull(decoder.decode(bytes));
+}
+
+function trimNull(text: string): string {
+  const index = text.indexOf("\0");
+  return (index < 0 ? text : text.slice(0, index)).trim();
+}
+
+function parseOctal(bytes: Uint8Array): number {
+  const text = trimNull(new TextDecoder().decode(bytes)).trim();
+  return text ? Number.parseInt(text, 8) : 0;
+}
+
+function parsePaxPath(text: string): string | null {
+  let rest = text;
+  while (rest.length > 0) {
+    const space = rest.indexOf(" ");
+    if (space < 0) return null;
+    const length = Number(rest.slice(0, space));
+    if (!Number.isFinite(length) || length <= space) return null;
+    const record = rest.slice(space + 1, length - 1);
+    const eq = record.indexOf("=");
+    if (eq > 0 && record.slice(0, eq) === "path") return record.slice(eq + 1);
+    rest = rest.slice(length);
+  }
+  return null;
+}
+
+function stripTarRoot(path: string): string {
+  const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized) return "";
+  if (normalized.startsWith("package/"))
+    return normalized.slice("package/".length);
+  const slash = normalized.indexOf("/");
+  return slash < 0 ? normalized : normalized.slice(slash + 1);
+}
+
+function compareVersionDesc(a: string, b: string): number {
+  const pa = a.split(/[.-]/).map((part) => Number.parseInt(part, 10));
+  const pb = b.split(/[.-]/).map((part) => Number.parseInt(part, 10));
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const av = Number.isFinite(pa[i]) ? pa[i]! : 0;
+    const bv = Number.isFinite(pb[i]) ? pb[i]! : 0;
+    if (av !== bv) return bv - av;
+  }
+  return b.localeCompare(a);
+}

package/src/npm/packageNameFromSpecifier.ts

@@ -0,0 +1,61 @@
+const BUILTIN_MODULES = new Set([
+  "assert",
+  "buffer",
+  "child_process",
+  "console",
+  "constants",
+  "crypto",
+  "dns",
+  "events",
+  "fs",
+  "http",
+  "https",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "stream",
+  "string_decoder",
+  "timers",
+  "tls",
+  "tty",
+  "url",
+  "util",
+  "vm",
+  "worker_threads",
+  "zlib",
+]);
+
+/**
+ * Extract the package name from a module specifier.
+ *
+ * Returns `null` for relative paths, hash imports, URL specifiers, and
+ * Node built-in modules — the caller doesn't install those from npm.
+ */
+export function packageNameFromSpecifier(specifier: string): string | null {
+  if (
+    specifier.startsWith("#") ||
+    specifier.startsWith(".") ||
+    specifier.startsWith("/") ||
+    /^[a-z][a-z0-9+.-]*:/i.test(specifier)
+  )
+    return null;
+  const bare = specifier.startsWith("node:") ? specifier.slice(5) : specifier;
+  const first = bare.split("/")[0];
+  if (first && BUILTIN_MODULES.has(first)) return null;
+  if (bare.startsWith("@")) {
+    const firstSlash = bare.indexOf("/");
+    if (firstSlash < 0) return null;
+    if (firstSlash === 1) return null;
+    const secondSlash = bare.indexOf("/", firstSlash + 1);
+    if (secondSlash === firstSlash + 1) return null;
+    return secondSlash < 0 ? bare : bare.slice(0, secondSlash);
+  }
+  const slash = bare.indexOf("/");
+  return slash < 0 ? bare : bare.slice(0, slash);
+}