@seanhogg/builderforce-webcontainers-core 2026.10.1 → 2026.10.3

package/src/installer/index.ts

@@ -0,0 +1,13 @@
+export { installPackages, chooseVersion } from './install.js';
+export type { InstallOptions, InstallResult, InstallProgress } from './install.js';
+export { RegistryClient, createMemoryCache, verifyIntegrity, DEFAULT_REGISTRY } from './registry.js';
+export type { FetchLike, PackageCache, PackageManifest, Packument, RegistryOptions, BinField } from './registry.js';
+export { resolveTree, childLocation, parentLocation, PLATFORM } from './tree.js';
+export type { ResolvedPackage, ResolveTreeOptions } from './tree.js';
+export { parseLockfile, buildLockfile, lockMatchesPackage } from './lockfile.js';
+export type { Lockfile, LockEntry } from './lockfile.js';
+export { parseInstallSpec, parseDependency } from './spec.js';
+export type { ParsedSpec, PackageJson } from './spec.js';
+export { normalizeBin, readBinLink, binShim, linkBins } from './bins.js';
+export { untar, tar } from './tar.js';
+export * as semver from './semver.js';

package/src/installer/install.ts

@@ -0,0 +1,275 @@
+/**
+ * `npm install` into the virtual file system: read package.json, resolve the
+ * tree (lockfile first, registry second), prune what is no longer wanted, unpack
+ * what is missing, link `.bin`, write package-lock.json.
+ *
+ * Install scripts (`preinstall`/`install`/`postinstall`) are NOT run. Nearly all
+ * of them compile native addons (node-gyp) or download platform binaries, neither
+ * of which can work in a browser; running the rest would mean executing arbitrary
+ * package code at install time for little gain. Packages that declare them are
+ * reported in `warnings`.
+ */
+import { gunzipSync } from 'fflate';
+import type { VirtualFileSystem } from '../vfs.js';
+import { join } from '../paths.js';
+import { RegistryClient, type FetchLike, type PackageCache, type PackageManifest, type Packument } from './registry.js';
+import { parseInstallSpec, sortObject, type PackageJson, type ParsedSpec } from './spec.js';
+import { childLocation, parentLocation, resolveTree, type ResolvedPackage } from './tree.js';
+import { buildLockfile, lockMatchesPackage, lockedManifests, parseLockfile, pickLocked, type Lockfile } from './lockfile.js';
+import { maxSatisfying, satisfies, validRange, valid } from './semver.js';
+import { untar } from './tar.js';
+import { linkBins } from './bins.js';
+
+export interface InstallProgress {
+  phase: 'resolve' | 'fetch' | 'done';
+  /** `name@version` being worked on. */
+  package?: string;
+  done: number;
+  total: number;
+}
+
+export interface InstallOptions {
+  fs: VirtualFileSystem;
+  fetch: FetchLike;
+  registry?: string;
+  cache?: PackageCache;
+  /** The project directory holding package.json. Default `/`. */
+  cwd?: string;
+  /** Specs to add first, as `npm install <spec…>` does (`react`, `zod@^3`, `@scope/x@next`). */
+  add?: string[];
+  /** Save added specs to devDependencies. */
+  saveDev?: boolean;
+  /** `npm ci`: install exactly what the lockfile says; fail when it is missing or stale. */
+  ci?: boolean;
+  /** Leave devDependencies out. */
+  production?: boolean;
+  /** Parallel downloads. Default 8. */
+  concurrency?: number;
+  signal?: AbortSignal;
+  onProgress?(progress: InstallProgress): void;
+}
+
+export interface InstallResult {
+  /** Packages unpacked this run. */
+  added: number;
+  /** Packages removed (no longer in the tree, or replaced by another version). */
+  removed: number;
+  /** Packages in the tree. */
+  total: number;
+  /** Top-level bins: name → absolute path of the script. */
+  bins: Record<string, string>;
+  lockfile: Lockfile;
+  warnings: string[];
+}
+
+const fatalDecoder = new TextDecoder('utf-8', { fatal: true });
+const BINARY_EXT = /\.(?:png|jpe?g|gif|webp|ico|bmp|wasm|node|gz|tgz|zip|br|woff2?|ttf|otf|eot|pdf|mp[34]|webm|ogg|wav|bin|dat)$/i;
+
+/** Store text as strings (what the module loader reads), binaries as bytes. */
+function decodeIfText(path: string, data: Uint8Array): string | Uint8Array {
+  if (BINARY_EXT.test(path)) return data.slice();
+  const head = data.subarray(0, 8000);
+  if (head.includes(0)) return data.slice();
+  try {
+    return fatalDecoder.decode(data);
+  } catch {
+    return data.slice();
+  }
+}
+
+/** Highest version allowed by `range` (or a dist-tag), preferring `latest` as npm does. */
+export function chooseVersion(packument: Packument, range: string): string {
+  const tags = packument['dist-tags'] ?? {};
+  const r = range || '*';
+  if (!validRange(r)) {
+    const tagged = tags[r];
+    if (tagged && packument.versions[tagged]) return tagged;
+    throw new Error(`No version of ${packument.name} is tagged "${range}".`);
+  }
+  const latest = tags.latest;
+  if (latest && packument.versions[latest] && satisfies(latest, r)) return latest;
+  const best = maxSatisfying(Object.keys(packument.versions), r);
+  if (!best) throw new Error(`No matching version found for ${packument.name}@${range}.`);
+  return best;
+}
+
+async function pool<T>(items: T[], size: number, run: (item: T) => Promise<void>): Promise<void> {
+  let next = 0;
+  const workers = Array.from({ length: Math.min(size, items.length) }, async () => {
+    while (next < items.length) await run(items[next++]!);
+  });
+  await Promise.all(workers);
+}
+
+function readJson<T>(fs: VirtualFileSystem, path: string): T | undefined {
+  try {
+    const text = fs.readText(path);
+    return text === undefined ? undefined : (JSON.parse(text) as T);
+  } catch {
+    return undefined;
+  }
+}
+
+const writeJson = (fs: VirtualFileSystem, path: string, value: unknown) => fs.writeFile(path, JSON.stringify(value, null, 2) + '\n');
+
+/** What is on disk now: location → `name@version`. */
+function installedPackages(fs: VirtualFileSystem, base: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (loc: string) => {
+    const nm = join(base, loc, 'node_modules');
+    const names: string[] = [];
+    for (const entry of fs.readdir(nm)) {
+      if (entry.startsWith('.')) continue;
+      if (entry.startsWith('@')) for (const sub of fs.readdir(join(nm, entry))) names.push(`${entry}/${sub}`);
+      else names.push(entry);
+    }
+    for (const name of names) {
+      const at = childLocation(loc, name);
+      const pkg = readJson<PackageJson>(fs, join(base, at, 'package.json'));
+      out.set(at, `${pkg?.name ?? ''}@${pkg?.version ?? ''}`);
+      walk(at);
+    }
+  };
+  walk('');
+  return out;
+}
+
+async function addSpecs(client: RegistryClient, pkg: PackageJson, specs: string[], dev: boolean): Promise<void> {
+  const save = dev ? 'devDependencies' : 'dependencies';
+  const other = dev ? 'dependencies' : 'devDependencies';
+  for (const raw of specs) {
+    const spec: ParsedSpec = parseInstallSpec(raw);
+    let saved = spec.range;
+    if (!saved || !validRange(saved)) saved = `^${chooseVersion(await client.packument(spec.registryName), saved || 'latest')}`;
+    else if (valid(saved)) saved = `^${valid(saved)}`;
+    if (spec.registryName !== spec.name) saved = `npm:${spec.registryName}@${saved}`;
+    pkg[save] = sortObject({ ...(pkg[save] ?? {}), [spec.name]: saved });
+    if (pkg[other]?.[spec.name]) {
+      const rest = { ...pkg[other] };
+      delete rest[spec.name];
+      pkg[other] = rest;
+    }
+  }
+}
+
+export async function installPackages(options: InstallOptions): Promise<InstallResult> {
+  const { fs, signal } = options;
+  const base = join('/', options.cwd ?? '/');
+  const pkgPath = join(base, 'package.json');
+  const lockPath = join(base, 'package-lock.json');
+  const warnings: string[] = [];
+  const client = new RegistryClient({ fetch: options.fetch, registry: options.registry, cache: options.cache, signal });
+  const progress = (p: InstallProgress) => options.onProgress?.(p);
+
+  let pkg = readJson<PackageJson>(fs, pkgPath);
+  if (!pkg) {
+    if (fs.isFile(pkgPath)) throw new Error(`${pkgPath} is not valid JSON.`);
+    if (!options.add?.length) throw new Error(`No package.json in ${base}.`);
+    pkg = {};
+  }
+  if (options.add?.length) {
+    await addSpecs(client, pkg, options.add, options.saveDev ?? false);
+    writeJson(fs, pkgPath, pkg);
+  }
+
+  const lock = parseLockfile(fs.readText(lockPath));
+  if (options.ci) {
+    if (!lock) throw new Error('npm ci needs a package-lock.json (lockfileVersion 2 or 3).');
+    if (!lockMatchesPackage(lock, pkg)) throw new Error('package.json and package-lock.json are out of sync. Run npm install to update the lockfile.');
+    fs.rm(join(base, 'node_modules'));
+  }
+  const locked = lockedManifests(lock);
+
+  const picks = new Map<string, Promise<PackageManifest>>();
+  const pick = (spec: ParsedSpec): Promise<PackageManifest> => {
+    const key = `${spec.registryName}@${spec.range}`;
+    let pending = picks.get(key);
+    if (!pending) {
+      const hit = pickLocked(locked, spec.registryName, spec.range);
+      if (hit) pending = Promise.resolve(hit);
+      else if (options.ci) pending = Promise.reject(new Error(`${key} is missing from package-lock.json. Run npm install to update it.`));
+      else pending = client.packument(spec.registryName).then((p) => {
+        const manifest = p.versions[chooseVersion(p, spec.range)]!;
+        return { ...manifest, name: manifest.name ?? spec.registryName };
+      });
+      pending.catch(() => undefined); // observed by whoever awaits it
+      picks.set(key, pending);
+    }
+    return pending;
+  };
+
+  let resolved = 0;
+  const tree = await resolveTree({
+    root: pkg,
+    pick,
+    prefetch: (spec) => void (pickLocked(locked, spec.registryName, spec.range) || options.ci || client.packument(spec.registryName).catch(() => undefined)),
+    production: options.production,
+    warn: (message) => warnings.push(message),
+    onResolved: ({ name, version }) => progress({ phase: 'resolve', package: `${name}@${version}`, done: ++resolved, total: resolved }),
+  });
+  signal?.throwIfAborted();
+
+  // Prune: anything not in the tree, or there at another version, goes (shallow first).
+  let removed = 0;
+  for (const [location, id] of [...installedPackages(fs, base)].sort(([a], [b]) => a.length - b.length)) {
+    const dir = join(base, location);
+    if (!fs.exists(dir)) continue; // went with an enclosing package
+    const want = tree.get(location);
+    if (!want || id !== `${want.manifest.name}@${want.manifest.version}`) {
+      fs.rm(dir);
+      removed++;
+    }
+  }
+
+  const missing = [...tree.values()].filter((node) => !fs.isFile(join(base, node.location, 'package.json')));
+  let fetched = 0;
+  await pool(missing, options.concurrency ?? 8, async (node) => {
+    signal?.throwIfAborted();
+    await unpack(fs, join(base, node.location), await client.tarball(node.manifest));
+    progress({ phase: 'fetch', package: `${node.name}@${node.manifest.version}`, done: ++fetched, total: missing.length });
+  });
+
+  for (const node of tree.values()) {
+    if (node.manifest.hasInstallScript) warnings.push(`skipped install scripts of ${node.name}@${node.manifest.version} (they cannot run in the browser)`);
+    if (node.manifest.deprecated) warnings.push(`deprecated ${node.name}@${node.manifest.version}: ${node.manifest.deprecated}`);
+  }
+
+  const bins = relinkBins(fs, base, tree);
+  const lockfile = buildLockfile(pkg, tree);
+  writeJson(fs, lockPath, lockfile);
+  progress({ phase: 'done', done: tree.size, total: tree.size });
+  return { added: missing.length, removed, total: tree.size, bins, lockfile, warnings };
+}
+
+/** gunzip + untar into `dir`, stripping the archive's top folder (`package/`). */
+async function unpack(fs: VirtualFileSystem, dir: string, tgz: Uint8Array): Promise<void> {
+  const entries = untar(gunzipSync(tgz));
+  let manifest: Uint8Array | undefined;
+  for (const entry of entries) {
+    if (entry.type !== 'file') continue;
+    const relative = entry.path.split('/').slice(1).join('/');
+    if (!relative || relative.split('/').includes('..')) continue;
+    // package.json goes last: its presence is what marks the package as installed.
+    if (relative === 'package.json') manifest = entry.data;
+    else fs.writeFile(join(dir, relative), decodeIfText(relative, entry.data));
+  }
+  if (!manifest) throw new Error(`The tarball for ${dir} has no package.json.`);
+  fs.writeFile(join(dir, 'package.json'), decodeIfText('package.json', manifest));
+}
+
+/** Rebuild every `.bin` directory from the tree; returns the top-level bins. */
+function relinkBins(fs: VirtualFileSystem, base: string, tree: Map<string, ResolvedPackage>): Record<string, string> {
+  const groups = new Map<string, ResolvedPackage[]>();
+  for (const node of tree.values()) {
+    const parent = parentLocation(node.location);
+    groups.set(parent, [...(groups.get(parent) ?? []), node]);
+  }
+  fs.rm(join(base, 'node_modules/.bin'));
+  let top: Record<string, string> = {};
+  for (const [parent, nodes] of groups) {
+    const binDir = join(base, parent, 'node_modules/.bin');
+    const linked = linkBins(fs, binDir, nodes.map((n) => ({ dir: join(base, n.location), name: n.name, bin: readJson<PackageJson>(fs, join(base, n.location, 'package.json'))?.bin ?? n.manifest.bin })));
+    if (parent === '') top = linked;
+  }
+  return top;
+}

package/src/installer/lockfile.ts

@@ -0,0 +1,146 @@
+/**
+ * package-lock.json, lockfileVersion 3 (npm 7+): a flat `packages` map keyed by
+ * install location. Reading it lets an install skip the registry's metadata
+ * entirely when nothing changed — every locked entry carries its version,
+ * tarball, integrity and dependency ranges.
+ */
+import type { BinField, PackageManifest } from './registry.js';
+import type { ResolvedPackage } from './tree.js';
+import { sortObject, type PackageJson } from './spec.js';
+import { satisfies, validRange } from './semver.js';
+
+export interface LockEntry {
+  name?: string;
+  version?: string;
+  resolved?: string;
+  integrity?: string;
+  dev?: boolean;
+  optional?: boolean;
+  license?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  bin?: BinField;
+  engines?: Record<string, string>;
+  os?: string[];
+  cpu?: string[];
+  hasInstallScript?: boolean;
+  deprecated?: string;
+}
+
+export interface Lockfile {
+  name?: string;
+  version?: string;
+  lockfileVersion: number;
+  requires?: boolean;
+  packages: Record<string, LockEntry>;
+}
+
+export function parseLockfile(text: string | undefined): Lockfile | undefined {
+  if (!text) return undefined;
+  try {
+    const lock = JSON.parse(text) as Lockfile;
+    // v1 lockfiles only have the nested `dependencies` tree; re-resolving is simpler than translating.
+    return lock.lockfileVersion >= 2 && lock.packages ? lock : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const nameFromLocation = (location: string) => location.slice(location.lastIndexOf('node_modules/') + 'node_modules/'.length);
+
+/** A locked entry as the manifest the resolver works with. */
+export function lockEntryManifest(location: string, entry: LockEntry): PackageManifest | undefined {
+  if (!entry.version || !entry.resolved) return undefined;
+  return {
+    name: entry.name ?? nameFromLocation(location),
+    version: entry.version,
+    dependencies: entry.dependencies,
+    optionalDependencies: entry.optionalDependencies,
+    peerDependencies: entry.peerDependencies,
+    peerDependenciesMeta: entry.peerDependenciesMeta,
+    bin: entry.bin,
+    engines: entry.engines,
+    os: entry.os,
+    cpu: entry.cpu,
+    hasInstallScript: entry.hasInstallScript,
+    deprecated: entry.deprecated,
+    license: entry.license,
+    dist: { tarball: entry.resolved, integrity: entry.integrity },
+  };
+}
+
+/** Locked manifests by registry package name, for "prefer what is locked". */
+export function lockedManifests(lock: Lockfile | undefined): Map<string, PackageManifest[]> {
+  const out = new Map<string, PackageManifest[]>();
+  for (const [location, entry] of Object.entries(lock?.packages ?? {})) {
+    if (!location.includes('node_modules/')) continue;
+    const manifest = lockEntryManifest(location, entry);
+    if (!manifest) continue;
+    const list = out.get(manifest.name) ?? [];
+    list.push(manifest);
+    out.set(manifest.name, list);
+  }
+  return out;
+}
+
+/** The highest locked version of `name` satisfying `range`, if any. */
+export function pickLocked(locked: Map<string, PackageManifest[]>, name: string, range: string): PackageManifest | undefined {
+  const r = range || '*';
+  if (!validRange(r)) return undefined;
+  let best: PackageManifest | undefined;
+  for (const m of locked.get(name) ?? []) {
+    if (satisfies(m.version, r) && (!best || satisfies(m.version, `>${best.version}`))) best = m;
+  }
+  return best;
+}
+
+const ROOT_FIELDS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'] as const;
+
+/** Do the lockfile's root ranges match package.json exactly? (`npm ci`'s precondition.) */
+export function lockMatchesPackage(lock: Lockfile, pkg: PackageJson): boolean {
+  const root = lock.packages[''] ?? {};
+  return ROOT_FIELDS.every((field) => {
+    const a = pkg[field] ?? {};
+    const b = (root as Record<string, Record<string, string> | undefined>)[field] ?? {};
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    return [...keys].every((k) => a[k] === b[k]);
+  });
+}
+
+const nonEmpty = <T extends object>(record: T | undefined): T | undefined => (record && Object.keys(record).length ? record : undefined);
+
+export function buildLockfile(pkg: PackageJson, tree: Map<string, ResolvedPackage>): Lockfile {
+  const root: LockEntry & { name?: string } = { name: pkg.name, version: pkg.version };
+  for (const field of ROOT_FIELDS) if (nonEmpty(pkg[field])) (root as Record<string, unknown>)[field] = pkg[field];
+  if (pkg.bin) root.bin = pkg.bin;
+  const packages: Record<string, LockEntry> = { '': JSON.parse(JSON.stringify(root)) as LockEntry };
+
+  for (const location of [...tree.keys()].sort()) {
+    const node = tree.get(location)!;
+    const m = node.manifest;
+    const entry: LockEntry = {
+      name: m.name !== node.name ? m.name : undefined,
+      version: m.version,
+      resolved: m.dist.tarball,
+      integrity: m.dist.integrity,
+      dev: node.dev || undefined,
+      optional: node.optional || undefined,
+      license: m.license,
+      dependencies: nonEmpty(m.dependencies && sortObject(m.dependencies)),
+      optionalDependencies: nonEmpty(m.optionalDependencies),
+      peerDependencies: nonEmpty(m.peerDependencies),
+      peerDependenciesMeta: nonEmpty(m.peerDependenciesMeta),
+      bin: m.bin,
+      engines: nonEmpty(m.engines),
+      os: m.os,
+      cpu: m.cpu,
+      hasInstallScript: m.hasInstallScript || undefined,
+      deprecated: m.deprecated,
+    };
+    packages[location] = JSON.parse(JSON.stringify(entry)) as LockEntry; // drops the undefineds
+  }
+  return { name: pkg.name, version: pkg.version, lockfileVersion: 3, requires: true, packages };
+}

package/src/installer/registry.ts

@@ -0,0 +1,175 @@
+/**
+ * Talking to an npm registry: packuments (version metadata) and tarballs, both
+ * through an optional cache PORT so the browser can back it with Cache Storage
+ * and tests with a Map. The installer never touches `globalThis.fetch` — the
+ * caller injects one, which is what keeps this testable against a fake registry.
+ */
+
+export type FetchLike = (url: string, init?: { headers?: Record<string, string>; signal?: AbortSignal }) => Promise<{
+  ok: boolean;
+  status: number;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+
+/** A byte cache keyed by string. Tarballs are immutable, so they are cached forever. */
+export interface PackageCache {
+  get(key: string): Promise<Uint8Array | undefined>;
+  put(key: string, data: Uint8Array): Promise<void>;
+}
+
+export function createMemoryCache(): PackageCache & { readonly size: number } {
+  const store = new Map<string, Uint8Array>();
+  return {
+    get: async (key) => store.get(key),
+    put: async (key, data) => void store.set(key, data),
+    get size() {
+      return store.size;
+    },
+  };
+}
+
+export type BinField = string | Record<string, string>;
+
+/** One version from a packument — the fields the abbreviated format carries. */
+export interface PackageManifest {
+  name: string;
+  version: string;
+  dependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+  bundleDependencies?: string[] | boolean;
+  bundledDependencies?: string[] | boolean;
+  bin?: BinField;
+  os?: string[];
+  cpu?: string[];
+  engines?: Record<string, string>;
+  hasInstallScript?: boolean;
+  deprecated?: string;
+  license?: string;
+  dist: { tarball: string; integrity?: string; shasum?: string };
+}
+
+export interface Packument {
+  name: string;
+  'dist-tags': Record<string, string>;
+  versions: Record<string, PackageManifest>;
+}
+
+export interface RegistryOptions {
+  fetch: FetchLike;
+  registry?: string;
+  cache?: PackageCache;
+  /** How long a cached packument is trusted. Default 10 minutes. */
+  packumentMaxAgeMs?: number;
+  signal?: AbortSignal;
+}
+
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/** The abbreviated ("corgi") document: a fraction of the full packument's size. */
+const ABBREVIATED = 'application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(binary);
+}
+
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Check `integrity` (SRI, `sha512-…`) or the legacy sha1 `shasum`. Skipped where
+ * WebCrypto is missing — a tarball from the configured registry over https is
+ * still trustworthy, the check only guards against a corrupt cache entry.
+ */
+export async function verifyIntegrity(data: Uint8Array, dist: { integrity?: string; shasum?: string }): Promise<boolean> {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) return true;
+  const digest = async (algo: string) => new Uint8Array(await subtle.digest(algo, data as unknown as ArrayBuffer));
+  if (dist.integrity) {
+    const algos: Record<string, string> = { sha512: 'SHA-512', sha384: 'SHA-384', sha256: 'SHA-256', sha1: 'SHA-1' };
+    for (const token of dist.integrity.split(/\s+/)) {
+      const dash = token.indexOf('-');
+      const algo = algos[token.slice(0, dash)];
+      if (algo && toBase64(await digest(algo)) === token.slice(dash + 1)) return true;
+    }
+    return false;
+  }
+  if (dist.shasum) return toHex(await digest('SHA-1')) === dist.shasum;
+  return true;
+}
+
+export class RegistryClient {
+  readonly registry: string;
+  private readonly packuments = new Map<string, Promise<Packument>>();
+
+  constructor(private readonly options: RegistryOptions) {
+    this.registry = (options.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, '');
+  }
+
+  /** Version metadata for a package, fetched once per client. */
+  packument(name: string): Promise<Packument> {
+    let pending = this.packuments.get(name);
+    if (!pending) {
+      pending = this.loadPackument(name);
+      pending.catch(() => this.packuments.delete(name));
+      this.packuments.set(name, pending);
+    }
+    return pending;
+  }
+
+  /** The tarball's bytes (still gzipped), integrity-checked. */
+  async tarball(manifest: Pick<PackageManifest, 'name' | 'version' | 'dist'>): Promise<Uint8Array> {
+    const { dist } = manifest;
+    const key = `tarball:${dist.integrity ?? dist.shasum ?? dist.tarball}`;
+    const cached = await this.options.cache?.get(key);
+    if (cached && (await verifyIntegrity(cached, dist))) return cached;
+    const data = await this.get(dist.tarball, {});
+    if (!(await verifyIntegrity(data, dist))) throw new Error(`Integrity check failed for ${manifest.name}@${manifest.version}`);
+    await this.options.cache?.put(key, data);
+    return data;
+  }
+
+  private async loadPackument(name: string): Promise<Packument> {
+    const key = `packument:${this.registry}/${name}`;
+    const maxAge = this.options.packumentMaxAgeMs ?? 10 * 60_000;
+    const cached = await this.options.cache?.get(key);
+    if (cached) {
+      try {
+        const entry = JSON.parse(decoder.decode(cached)) as { t: number; p: Packument };
+        if (Date.now() - entry.t < maxAge) return entry.p;
+      } catch {
+        // a corrupt entry is just a miss
+      }
+    }
+    const url = `${this.registry}/${name.startsWith('@') ? '@' + encodeURIComponent(name.slice(1)) : encodeURIComponent(name)}`;
+    const bytes = await this.get(url, { accept: ABBREVIATED }, name);
+    const packument = JSON.parse(decoder.decode(bytes)) as Packument;
+    if (!packument.versions) throw new Error(`The registry returned no versions for "${name}".`);
+    await this.options.cache?.put(key, encoder.encode(JSON.stringify({ t: Date.now(), p: packument })));
+    return packument;
+  }
+
+  private async get(url: string, headers: Record<string, string>, packageName?: string): Promise<Uint8Array> {
+    let lastError: unknown;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      let response: Awaited<ReturnType<FetchLike>>;
+      try {
+        response = await this.options.fetch(url, { headers, signal: this.options.signal });
+      } catch (error) {
+        if (this.options.signal?.aborted) throw error;
+        lastError = error; // network blip: retry once
+        continue;
+      }
+      if (response.status === 404 && packageName) throw new Error(`Package "${packageName}" was not found in ${this.registry}.`);
+      if (!response.ok) throw new Error(`GET ${url} failed with HTTP ${response.status}.`);
+      return new Uint8Array(await response.arrayBuffer());
+    }
+    throw new Error(`GET ${url} failed: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+  }
+}