@statewalker/webrun-modules 0.1.0

package/dist/index.js

@@ -0,0 +1,809 @@
+import { readText, writeText } from "@statewalker/webrun-files";
+import semver from "semver";
+import { legacy, resolve } from "resolve.exports";
+import { MemFilesApi } from "@statewalker/webrun-files-mem";
+import { gunzipSync } from "fflate";
+import { init, parse } from "cjs-module-lexer";
+import { init as init$1, parse as parse$1 } from "es-module-lexer";
+import { transform } from "sucrase";
+//#region src/resolution/node-builtins.ts
+/** Node core module names (static list — an isomorphic lib can't read `node:module`). */
+const NODE_BUILTINS = new Set([
+	"assert",
+	"async_hooks",
+	"buffer",
+	"child_process",
+	"cluster",
+	"console",
+	"constants",
+	"crypto",
+	"dgram",
+	"diagnostics_channel",
+	"dns",
+	"domain",
+	"events",
+	"fs",
+	"http",
+	"http2",
+	"https",
+	"inspector",
+	"module",
+	"net",
+	"os",
+	"path",
+	"perf_hooks",
+	"process",
+	"punycode",
+	"querystring",
+	"readline",
+	"repl",
+	"stream",
+	"string_decoder",
+	"sys",
+	"timers",
+	"tls",
+	"trace_events",
+	"tty",
+	"url",
+	"util",
+	"v8",
+	"vm",
+	"wasi",
+	"worker_threads",
+	"zlib"
+]);
+/** Strip a `node:` prefix and any subpath, returning the core module name. */
+function nodeBuiltinName(spec) {
+	const bare = spec.replace(/^node:/, "");
+	const root = bare.split("/")[0];
+	return NODE_BUILTINS.has(root) ? bare : void 0;
+}
+/**
+* Map a Node-builtin specifier under a given target:
+* - `browser` → a `@jspm/core` browser-polyfill package ref (served locally).
+* - `node`    → `{ external }` (leave the `node:`-prefixed specifier in place).
+*
+* The subpath is `nodelibs/${name}` (not `nodelibs/browser/…`): `@jspm/core`'s
+* `exports` map (`"./nodelibs/*"` → `default: "./nodelibs/browser/*.js"`) supplies
+* the `browser` segment via the export condition. Hard-coding it here would make
+* the wildcard expand to `nodelibs/browser/browser/${name}.js` — a path that
+* doesn't exist.
+*/
+function resolveNodeBuiltin(spec, target) {
+	const name = nodeBuiltinName(spec);
+	if (name === void 0) return void 0;
+	if (target === "node") return { external: `node:${name}` };
+	return { ref: {
+		pkg: "@jspm/core",
+		subpath: `nodelibs/${name}`
+	} };
+}
+//#endregion
+//#region src/resolution/resolve-entry.ts
+/** Strip a leading `./` or `/` so the result is a package-relative file path. */
+function norm(p) {
+	return p.replace(/^\.?\//, "");
+}
+/** Call resolve.exports, swallowing its "no known conditions" throw. */
+function tryResolve(manifest, entry, opts) {
+	try {
+		return resolve(manifest, entry, opts);
+	} catch {
+		return;
+	}
+}
+/**
+* Resolve a package + subpath to the concrete file path inside the package,
+* honoring `package.json` `exports` conditions for the given `target`, with a
+* `main`/`module`/`browser` legacy fallback. Returns a package-relative path
+* (e.g. `"dist/index.js"`).
+*/
+function resolveEntry(manifest, subpath, target) {
+	const browser = target === "browser";
+	const clean = (subpath ?? "").replace(/^\.?\//, "");
+	const entry = clean ? `./${clean}` : ".";
+	if (manifest.exports !== void 0) {
+		const conditions = browser ? ["browser"] : ["node"];
+		const out = tryResolve(manifest, entry, {
+			browser,
+			conditions
+		}) ?? tryResolve(manifest, entry, {
+			browser,
+			conditions,
+			require: true
+		});
+		if (out?.length) return norm(out[0]);
+	}
+	if (entry === ".") {
+		const leg = legacy(manifest, {
+			browser,
+			fields: browser ? [
+				"browser",
+				"module",
+				"main"
+			] : ["module", "main"]
+		});
+		if (typeof leg === "string") return norm(leg);
+		if (manifest.exports !== void 0) throw new Error(`${manifest.name}: package has no root entry ("." is not exported)`);
+	}
+	return clean || "index.js";
+}
+//#endregion
+//#region src/types.ts
+/** Thrown when a package / version / subpath cannot be resolved. */
+var ModuleResolveError = class extends Error {
+	constructor(ref, reason) {
+		super(`Cannot resolve ${JSON.stringify(ref)}: ${reason}`);
+		this.ref = ref;
+		this.reason = reason;
+		this.name = "ModuleResolveError";
+	}
+};
+/** Thrown when a file cannot be transformed to runnable ESM. */
+var ModuleTransformError = class extends Error {
+	constructor(path, reason) {
+		super(`Cannot transform ${path}: ${reason}`);
+		this.path = path;
+		this.reason = reason;
+		this.name = "ModuleTransformError";
+	}
+};
+//#endregion
+//#region src/sources/untar.ts
+/**
+* Untar an npm `.tgz` (gzipped ustar) into a map of path → bytes, isomorphically
+* (no `node:zlib`, no `Buffer`). npm tarballs prefix every entry with `package/`;
+* that prefix is stripped so keys are relative to the package root.
+*/
+function untarTgz(tgz) {
+	return untar(gunzipSync(tgz));
+}
+const td = new TextDecoder();
+function str(buf, start, end) {
+	return td.decode(buf.subarray(start, end)).replace(/\0.*/s, "");
+}
+/** Parse a raw ustar archive (512-byte blocks). */
+function untar(buf) {
+	const out = /* @__PURE__ */ new Map();
+	let off = 0;
+	while (off + 512 <= buf.length) {
+		const name = str(buf, off, off + 100);
+		if (!name) break;
+		const size = Number.parseInt(str(buf, off + 124, off + 136).trim() || "0", 8);
+		const type = str(buf, off + 156, off + 157);
+		const prefix = str(buf, off + 345, off + 500);
+		const full = prefix ? `${prefix}/${name}` : name;
+		const start = off + 512;
+		if (type === "0" || type === "") out.set(full.replace(/^package\//, ""), buf.subarray(start, start + size));
+		off = start + Math.ceil(size / 512) * 512;
+	}
+	return out;
+}
+//#endregion
+//#region src/sources/npm-registry-source.ts
+/**
+* The default acquisition `Source`: resolves a version from npm registry
+* metadata, downloads the tarball, untars it into a fresh `FilesApi`, and returns
+* the package files + manifest. Fully isomorphic (`fetch` + pure-JS untar).
+*/
+function npmRegistrySource(opts = {}) {
+	const registry = (opts.registryUrl ?? "https://registry.npmjs.org").replace(/\/+$/, "");
+	const doFetch = opts.fetch ?? globalThis.fetch;
+	const createFiles = opts.createFiles ?? (() => new MemFilesApi());
+	return {
+		matches(ref) {
+			return "pkg" in ref;
+		},
+		async load(ref) {
+			if (!("pkg" in ref)) throw new ModuleResolveError(ref, "not an npm reference");
+			const name = ref.pkg;
+			const metaRes = await doFetch(`${registry}/${encodeName(name)}`);
+			if (!metaRes.ok) throw new ModuleResolveError(ref, `registry ${metaRes.status} for ${name}`);
+			const meta = await metaRes.json();
+			const version = resolveVersion(meta, ref.version, ref);
+			const vmeta = meta.versions?.[version];
+			const tarball = vmeta?.dist?.tarball;
+			if (!tarball) throw new ModuleResolveError(ref, `no tarball for ${name}@${version}`);
+			const tgzRes = await doFetch(tarball);
+			if (!tgzRes.ok) throw new ModuleResolveError(ref, `tarball ${tgzRes.status} for ${name}@${version}`);
+			const entries = untarTgz(new Uint8Array(await tgzRes.arrayBuffer()));
+			const files = createFiles();
+			for (const [path, bytes] of entries) await files.write(`/${path}`, [bytes]);
+			return {
+				name,
+				version,
+				files,
+				manifest: {
+					...vmeta,
+					name,
+					version
+				}
+			};
+		}
+	};
+}
+/** Resolve a dist-tag, exact version, or semver range to a concrete version. */
+function resolveVersion(meta, spec, ref) {
+	const versions = Object.keys(meta.versions ?? {});
+	const tags = meta["dist-tags"] ?? {};
+	const s = spec ?? "latest";
+	if (tags[s]) return tags[s];
+	if (versions.includes(s)) return s;
+	const range = semver.validRange(s);
+	if (range) {
+		const best = semver.maxSatisfying(versions, range);
+		if (best) return best;
+	}
+	throw new ModuleResolveError(ref, `no version satisfies "${s}"`);
+}
+/** Encode a package name for a registry URL (scoped names need the `/` escaped). */
+function encodeName(name) {
+	return name.startsWith("@") ? name.replace("/", "%2F") : name;
+}
+//#endregion
+//#region src/transform/transform-cjs.ts
+let lexerReady$1;
+const REQUIRE_RE$1 = /require\(\s*(['"])((?:(?!\1)[^\\]|\\.)*)\1\s*\)/g;
+const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Collect the unique static-string `require(...)` specifiers in a CJS source. */
+function findRequires(source) {
+	const set = /* @__PURE__ */ new Set();
+	for (const m of source.matchAll(REQUIRE_RE$1)) set.add(m[2]);
+	return [...set];
+}
+/**
+* Transform a CommonJS file into served, browser-runnable ESM — no global runtime
+* registry: each static `require` target is a static namespace import, so the ESM
+* module graph itself provides load ordering and circular-dep handling. The CJS
+* body runs synchronously against a synthetic `require` that maps specifiers to
+* those namespaces; named exports (via `cjs-module-lexer`) are re-exported as
+* eval-time snapshots (valid because the body executed synchronously above).
+* Computed `require(expr)` hits the synthetic require's miss path (throws) — the
+* declared `esbuild-wasm` fallback's job.
+*/
+function newCjsTransform() {
+	return { async transform(file, rewrite) {
+		lexerReady$1 ??= init();
+		await lexerReady$1;
+		const specs = findRequires(file.source);
+		const importLines = [];
+		const mapEntries = [];
+		specs.forEach((spec, i) => {
+			importLines.push(`import * as __d${i} from ${JSON.stringify(rewrite(spec))};`);
+			mapEntries.push(`  ${JSON.stringify(spec)}: __d${i},`);
+		});
+		let names = [];
+		let reexports = [];
+		try {
+			const parsed = parse(file.source);
+			names = parsed.exports.filter((n) => IDENT_RE.test(n) && n !== "default");
+			reexports = parsed.reexports;
+		} catch {
+			names = [];
+		}
+		const namedExports = [...new Set(names)].map((n) => `export const ${n} = module.exports.${n};`).join("\n");
+		const reexportLines = [...new Set(reexports)].map((spec) => `export * from ${JSON.stringify(rewrite(spec))};`).join("\n");
+		const dir = file.path.replace(/\/[^/]*$/, "");
+		return [
+			...importLines,
+			`const __ns = {\n${mapEntries.join("\n")}\n};`,
+			`const module = { exports: {} };`,
+			`const require = (s) => {`,
+			`  const m = __ns[s];`,
+			`  if (!m) throw new Error("Cannot require (computed/unresolved): " + s);`,
+			`  return m.default !== undefined ? m.default : m;`,
+			`};`,
+			`(function (module, exports, require, __filename, __dirname) {`,
+			file.source,
+			`}).call(module.exports, module, module.exports, require, ${JSON.stringify(file.path)}, ${JSON.stringify(dir)});`,
+			`export default module.exports;`,
+			namedExports,
+			reexportLines
+		].filter(Boolean).join("\n");
+	} };
+}
+//#endregion
+//#region src/transform/to-js.ts
+/**
+* Strip TS/JSX to plain JS (leave already-ESM/CJS JS untouched). Shared by the
+* ESM transform and the specifier scanner so both see the *same* JS — raw TS/JSX
+* cannot be lexed directly (`es-module-lexer` throws on JSX). JSX uses the
+* automatic runtime, so scanning the output also surfaces the `react/jsx-runtime`
+* import the runtime injects.
+*/
+function toJs(source, format, path) {
+	if (format === "ts" || format === "tsx") return transform(source, {
+		transforms: format === "tsx" ? ["typescript", "jsx"] : ["typescript"],
+		jsxRuntime: "automatic",
+		filePath: path
+	}).code;
+	return source;
+}
+//#endregion
+//#region src/transform/transform-esm.ts
+let lexerReady;
+/**
+* The default per-file transform for ESM (and TS/JSX) sources: transpile to plain
+* JS, then rewrite every static/dynamic-string import & re-export specifier in
+* place via `rewrite`, leaving quotes and everything else byte-for-byte intact.
+* Computed dynamic specifiers (no static string) are left untouched.
+*/
+function newEsmTransform() {
+	return { async transform(file, rewrite) {
+		lexerReady ??= init$1;
+		await lexerReady;
+		const js = toJs(file.source, file.format, file.path);
+		const [imports] = parse$1(js, file.path);
+		let out = js;
+		for (let i = imports.length - 1; i >= 0; i--) {
+			const imp = imports[i];
+			if (imp.n == null) continue;
+			const q = out[imp.s];
+			const replacement = q === "\"" || q === "'" || q === "`" ? q + rewrite(imp.n) + q : rewrite(imp.n);
+			out = out.slice(0, imp.s) + replacement + out.slice(imp.e);
+		}
+		return out;
+	} };
+}
+//#endregion
+//#region src/transform/index.ts
+/** The default per-file transform: dispatch ESM/TS/JSX vs CJS by `file.format`. */
+function newDefaultTransform() {
+	const esm = newEsmTransform();
+	const cjs = newCjsTransform();
+	return { transform(file, rewrite) {
+		return file.format === "cjs" ? cjs.transform(file, rewrite) : esm.transform(file, rewrite);
+	} };
+}
+const CJS_EXPORTS = /\bmodule\.exports\b|\bexports\s*[.[]/;
+const ESM_STMT = /(^|[\s;])(import|export)[\s{*'"]/;
+const REQUIRE_CALL = /(^|[^.\w])require\s*\(/;
+/**
+* Decide a file's `SourceFormat` from its extension, the package `type`, and
+* (for ambiguous `.js`) a content sniff. Mirrors Node: `.mjs`=ESM, `.cjs`=CJS,
+* `.js` follows `package.json#type`; with no `type`, a package `.js` is CJS
+* (Node's default) unless real ESM syntax is present. Definitive CJS markers
+* (`module.exports`/`exports.x`) win over a loose `import`/`export` word-match,
+* so a CJS file with "export" in a string is not mis-read as ESM.
+*/
+function detectFormat(path, source, manifest) {
+	if (path.endsWith(".ts")) return "ts";
+	if (path.endsWith(".tsx") || path.endsWith(".jsx")) return "tsx";
+	if (path.endsWith(".mjs")) return "esm";
+	if (path.endsWith(".cjs")) return "cjs";
+	if (manifest?.type === "module") return "esm";
+	if (manifest?.type === "commonjs") return "cjs";
+	if (CJS_EXPORTS.test(source)) return "cjs";
+	if (ESM_STMT.test(source)) return "esm";
+	if (REQUIRE_CALL.test(source)) return "cjs";
+	return manifest ? "cjs" : "esm";
+}
+//#endregion
+//#region src/transform/scan.ts
+const REQUIRE_RE = /require\(\s*(['"])((?:(?!\1)[^\\]|\\.)*)\1\s*\)/g;
+let esmReady;
+let cjsReady;
+/**
+* List the import specifiers a file's transform will rewrite — the exact same set
+* the ESM/CJS transforms discover — so the server can pre-resolve them (async)
+* before running the synchronous rewrite. For TS/JSX the raw source is scanned;
+* `es-module-lexer` tolerates types well enough to find every specifier.
+*/
+async function scanSpecifiers(source, format) {
+	if (format === "cjs") {
+		cjsReady ??= init();
+		await cjsReady;
+		return [...new Set([...source.matchAll(REQUIRE_RE)].map((m) => m[2]))];
+	}
+	esmReady ??= init$1;
+	await esmReady;
+	const [imports] = parse$1(toJs(source, format));
+	const out = /* @__PURE__ */ new Set();
+	for (const imp of imports) if (imp.n != null) out.add(imp.n);
+	return [...out];
+}
+//#endregion
+//#region src/server/specifiers.ts
+/** Split a bare specifier into package name + optional subpath (scope-aware). */
+function parseSpecifier(spec) {
+	const parts = spec.split("/");
+	if (spec.startsWith("@")) {
+		const pkg = parts.slice(0, 2).join("/");
+		const subpath = parts.slice(2).join("/");
+		return subpath ? {
+			pkg,
+			subpath
+		} : { pkg };
+	}
+	const [pkg, ...rest] = parts;
+	const subpath = rest.join("/");
+	return subpath ? {
+		pkg,
+		subpath
+	} : { pkg };
+}
+/**
+* Relative URL from one canonical module id to another (both are slash paths with
+* no leading slash, filename last). Keeps served imports mount-prefix-portable.
+*/
+function relativeUrl(fromId, toId) {
+	const from = fromId.split("/").slice(0, -1);
+	const to = toId.split("/");
+	let i = 0;
+	while (i < from.length && i < to.length && from[i] === to[i]) i++;
+	const ups = from.length - i;
+	const rel = [...Array(ups).fill(".."), ...to.slice(i)].join("/");
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+//#endregion
+//#region src/server/new-module-server.ts
+const RAW_EXT = [
+	"",
+	".js",
+	".mjs",
+	".cjs",
+	".json",
+	"/index.js",
+	"/index.mjs"
+];
+/** JS/TS module files — the only ones the transform touches. */
+const MODULE_EXT = /\.(?:m|c)?[jt]sx?$/;
+const isModuleFile = (path) => MODULE_EXT.test(path);
+const CONTENT_TYPES = {
+	json: "application/json",
+	css: "text/css",
+	md: "text/markdown",
+	html: "text/html",
+	svg: "image/svg+xml",
+	wasm: "application/wasm",
+	map: "application/json",
+	txt: "text/plain"
+};
+/** Guess a content-type from a file path (non-module resources). */
+function contentType(path) {
+	return CONTENT_TYPES[path.split(".").pop()?.toLowerCase() ?? ""] ?? "application/octet-stream";
+}
+/** Create a module/dependency server over an injected `FilesApi` cache. */
+function newModuleServer(options) {
+	const cache = options.cache;
+	const project = options.project;
+	const sources = options.sources ?? [npmRegistrySource()];
+	const transformer = options.transform ?? newDefaultTransform();
+	const target = options.target ?? "browser";
+	const basePath = normalizeBase(options.basePath ?? "/");
+	const depsPrefix = normalizeDeps(options.depsPath ?? "");
+	const lock = { ...options.lock ?? {} };
+	const tRoot = `/t/${target}`;
+	let ready;
+	const init = () => {
+		ready ??= (async () => {
+			if (await cache.exists("/lock.json")) Object.assign(lock, JSON.parse(await readText(cache, "/lock.json")), options.lock ?? {});
+		})();
+		return ready;
+	};
+	const urlPath = (id) => id.startsWith("~/") ? id : depsPrefix + id;
+	const urlFor = (id) => basePath + urlPath(id);
+	const idFromPath = (pathname) => {
+		let p = pathname.startsWith(basePath) ? pathname.slice(basePath.length) : pathname.replace(/^\//, "");
+		if (depsPrefix && p.startsWith(depsPrefix)) p = p.slice(depsPrefix.length);
+		return p;
+	};
+	function matchSource(ref) {
+		const s = sources.find((x) => x.matches(ref));
+		if (!s) throw new ModuleResolveError(ref, "no source matches");
+		return s;
+	}
+	function reusable(locked, spec) {
+		if (!spec) return true;
+		if (semver.valid(spec)) return locked === spec;
+		if (semver.validRange(spec)) return semver.satisfies(locked, spec);
+		return true;
+	}
+	async function cachedManifest(pkgKey) {
+		return JSON.parse(await readText(cache, `/raw/${pkgKey}/package.json`));
+	}
+	/** Persist a loaded package's files under `/raw/{name}@{version}/…` (idempotent).
+	*  The manifest is written as `package.json` (the authority — a Source's files
+	*  are not required to include one). */
+	async function cacheRaw(name, version, files, manifest) {
+		const key = `${name}@${version}`;
+		if (await cache.exists(`/raw/${key}/package.json`)) return;
+		for await (const info of files.list("/", { recursive: true })) if (info.kind === "file") await cache.write(`/raw/${key}${info.path}`, [await collect(files.read(info.path))]);
+		if (!await cache.exists(`/raw/${key}/package.json`)) await writeText(cache, `/raw/${key}/package.json`, JSON.stringify(manifest));
+	}
+	/** Lazily load a package's raw files by its `name@version` cache key (idempotent). */
+	async function ensureRawByKey(pkgKey) {
+		if (await cache.exists(`/raw/${pkgKey}/package.json`)) return;
+		const at = pkgKey.lastIndexOf("@");
+		const ref = {
+			pkg: pkgKey.slice(0, at),
+			version: pkgKey.slice(at + 1)
+		};
+		const loaded = await matchSource(ref).load(ref);
+		await cacheRaw(loaded.name, loaded.version, loaded.files, loaded.manifest);
+	}
+	/** Ensure a package's raw files + manifest are cached; return its pinned id. */
+	async function ensurePackage(ref) {
+		const name = ref.pkg;
+		const locked = lock[name];
+		let version;
+		let manifest;
+		if (locked && reusable(locked, ref.version)) {
+			version = locked;
+			await ensureRawByKey(`${name}@${version}`);
+			manifest = await cachedManifest(`${name}@${version}`);
+		} else {
+			const loaded = await matchSource(ref).load({
+				pkg: name,
+				version: ref.version
+			});
+			version = loaded.version;
+			await cacheRaw(name, version, loaded.files, loaded.manifest);
+			manifest = loaded.manifest;
+			if (!locked) lock[name] = version;
+		}
+		const entry = resolveEntry(manifest, ref.subpath, target);
+		const file = await resolveRawFile(`${name}@${version}`, entry);
+		return {
+			name,
+			version,
+			file,
+			id: `${name}@${version}/${file}`,
+			manifest
+		};
+	}
+	/** Resolve an import specifier (from `fromId`) to what to emit + its cache id. */
+	async function resolveSpec(spec, fromId) {
+		if (/^(https?:|data:)/.test(spec)) return { url: spec };
+		const builtin = resolveNodeBuiltin(spec, target);
+		if (builtin) {
+			if ("external" in builtin) return { url: builtin.external };
+			const t = await ensurePackage(builtin.ref);
+			return {
+				url: relativeUrl(urlPath(fromId), urlPath(t.id)),
+				id: t.id
+			};
+		}
+		if (spec.startsWith(".")) {
+			const id = await resolveRelativeId(fromId, spec);
+			return {
+				url: jsonModuleUrl(relativeUrl(urlPath(fromId), urlPath(id)), id),
+				id
+			};
+		}
+		const { pkg, subpath } = parseSpecifier(spec);
+		const t = await ensurePackage({
+			pkg,
+			version: await importerVersion(pkg, fromId),
+			subpath
+		});
+		return {
+			url: jsonModuleUrl(relativeUrl(urlPath(fromId), urlPath(t.id)), t.id),
+			id: t.id
+		};
+	}
+	/** The version constraint a bare specifier should resolve to, from the importer's
+	*  package: self-reference → the importer's own version; a dependency → the
+	*  importer's `package.json` range; otherwise undefined (global lock/latest). */
+	async function importerVersion(pkg, fromId) {
+		const m = fromId.match(/^((?:@[^/]+\/)?[^/]+)@([^/]+)\//);
+		if (!m) return void 0;
+		const [, impName, impVersion] = m;
+		if (pkg === impName) return impVersion;
+		const manifest = await cachedManifest(`${impName}@${impVersion}`).catch(() => void 0);
+		return manifest?.dependencies?.[pkg] ?? manifest?.peerDependencies?.[pkg] ?? (manifest?.optionalDependencies)?.[pkg];
+	}
+	/** A `.json` imported by a JS module is served as an ESM (`export default …`);
+	*  mark its URL with `?module` so `fetch` wraps it instead of serving raw JSON. */
+	function jsonModuleUrl(url, id) {
+		return id.endsWith(".json") ? `${url}?module` : url;
+	}
+	/** Resolve a relative specifier against an importer id to a concrete cache id. */
+	async function resolveRelativeId(fromId, spec) {
+		const dir = fromId.split("/").slice(0, -1);
+		for (const part of spec.split("/")) {
+			if (part === "." || part === "") continue;
+			if (part === "..") dir.pop();
+			else dir.push(part);
+		}
+		const base = dir.join("/");
+		const pkgKey = base.match(/^(?:@[^/]+\/)?[^/]+@[^/]+/)?.[0];
+		if (pkgKey) return `${pkgKey}/${await resolveRawFile(pkgKey, base.slice(pkgKey.length + 1))}`;
+		return base;
+	}
+	/** Try extension/index variants for a package-relative file; return what exists. */
+	async function resolveRawFile(pkgKey, file) {
+		for (const ext of RAW_EXT) if (await cache.exists(`/raw/${pkgKey}/${file}${ext}`)) return file + ext;
+		return file;
+	}
+	/** Load a canonical id's raw source + format context. */
+	async function loadRaw(id) {
+		if (id.startsWith("~/")) {
+			if (!project) throw new ModuleResolveError({ url: id }, "no project FilesApi");
+			const path = `/${id.slice(2)}`;
+			const source = await readText(project, path);
+			return {
+				path,
+				source,
+				format: detectFormat(path, source)
+			};
+		}
+		const m = id.match(/^((?:@[^/]+\/)?[^/]+@[^/]+)\/(.+)$/);
+		if (!m) throw new ModuleResolveError({ url: id }, "not a module id");
+		const [, pkgKey, rawFile] = m;
+		await ensureRawByKey(pkgKey);
+		const file = await resolveRawFile(pkgKey, rawFile);
+		const source = await readText(cache, `/raw/${pkgKey}/${file}`);
+		const manifest = await cachedManifest(pkgKey).catch(() => void 0);
+		return {
+			path: `/${pkgKey}/${file}`,
+			source,
+			format: detectFormat(file, source, manifest)
+		};
+	}
+	/** Transform a module (pre-resolving its specifiers) and cache the ESM output. */
+	async function transformAndCache(id) {
+		const { path, source, format } = await loadRaw(id);
+		const specs = await scanSpecifiers(source, format);
+		const map = /* @__PURE__ */ new Map();
+		for (const spec of specs) map.set(spec, (await resolveSpec(spec, id)).url);
+		const out = await transformer.transform({
+			path,
+			source,
+			format
+		}, (s) => map.get(s) ?? s);
+		await writeText(cache, `${tRoot}/${id}`, out);
+		return out;
+	}
+	/** Resolve a file id (project `~/…` or `{pkg}@{ver}/{file}`) to its raw bytes. */
+	async function rawBytes(id) {
+		if (id.startsWith("~/")) {
+			const path = `/${id.slice(2)}`;
+			if (!project || !await project.exists(path)) return void 0;
+			return collect(project.read(path));
+		}
+		const m = id.match(/^((?:@[^/]+\/)?[^/]+@[^/]+)\/(.+)$/);
+		if (!m) return void 0;
+		await ensureRawByKey(m[1]);
+		const file = await resolveRawFile(m[1], m[2]);
+		if (!await cache.exists(`/raw/${m[1]}/${file}`)) return void 0;
+		return collect(cache.read(`/raw/${m[1]}/${file}`));
+	}
+	/** Serve a file's raw bytes (non-module resources, or `?raw`). */
+	async function serveRaw(id, asOctet) {
+		const bytes = await rawBytes(id);
+		if (!bytes) return new Response(null, { status: 404 });
+		return new Response(bytes, {
+			status: 200,
+			headers: { "content-type": asOctet ? "application/octet-stream" : contentType(id) }
+		});
+	}
+	/** Serve a JSON file as an ESM module (`export default …`) — how a JS `import`
+	*  of a `.json` is satisfied without relying on browser JSON-import attributes. */
+	async function serveJsonModule(id) {
+		const bytes = await rawBytes(id);
+		if (!bytes) return new Response(null, { status: 404 });
+		const json = new TextDecoder().decode(bytes);
+		return new Response(`export default ${json};`, {
+			status: 200,
+			headers: { "content-type": "text/javascript" }
+		});
+	}
+	async function resolveEntryId(ref) {
+		if ("url" in ref) {
+			if (/^https?:/.test(ref.url)) throw new ModuleResolveError(ref, "absolute URL is not local");
+			const p = idFromPath(ref.url);
+			return p.startsWith("~/") ? p : `~/${p.replace(/^\//, "")}`;
+		}
+		return (await ensurePackage(ref)).id;
+	}
+	/** Walk + transform + cache the whole graph from an entry; persist the lockfile.
+	*  Returns the entry id and every reachable module id. */
+	async function walkGraph(entry) {
+		const rootId = await resolveEntryId(entry);
+		const seen = /* @__PURE__ */ new Set();
+		const queue = [rootId];
+		while (queue.length) {
+			const id = queue.shift();
+			if (id === void 0 || seen.has(id)) continue;
+			seen.add(id);
+			if (!isModuleFile(id)) {
+				const m = id.match(/^((?:@[^/]+\/)?[^/]+@[^/]+)\//);
+				if (m) await ensureRawByKey(m[1]);
+				continue;
+			}
+			const { source, format } = await loadRaw(id);
+			for (const spec of await scanSpecifiers(source, format)) {
+				const { id: childId } = await resolveSpec(spec, id);
+				if (childId && !seen.has(childId)) queue.push(childId);
+			}
+			await transformAndCache(id);
+		}
+		await writeText(cache, "/lock.json", JSON.stringify(lock));
+		return {
+			rootId,
+			ids: [...seen]
+		};
+	}
+	return {
+		get lock() {
+			return lock;
+		},
+		async resolve(ref) {
+			await init();
+			return {
+				url: urlFor(await resolveEntryId(ref)),
+				target
+			};
+		},
+		async prime(entry) {
+			await init();
+			const { rootId } = await walkGraph(entry);
+			return {
+				url: urlFor(rootId),
+				target
+			};
+		},
+		async listResources(entry) {
+			await init();
+			const { ids } = await walkGraph(entry);
+			return ids.map(urlFor).sort();
+		},
+		async listPackageFiles(ref) {
+			await init();
+			if ("url" in ref) throw new ModuleResolveError(ref, "not a package reference");
+			const { name, version } = await ensurePackage({
+				pkg: ref.pkg,
+				version: ref.version
+			});
+			const key = `${name}@${version}`;
+			const files = [];
+			for await (const info of cache.list(`/raw/${key}`, { recursive: true })) if (info.kind === "file") files.push(info.path.replace(`/raw/${key}/`, ""));
+			return files.sort();
+		},
+		async fetch(request) {
+			await init();
+			const url = new URL(request.url);
+			const id = idFromPath(url.pathname);
+			try {
+				if (url.searchParams.has("raw")) return await serveRaw(id, true);
+				if (url.searchParams.has("module") && id.endsWith(".json")) return await serveJsonModule(id);
+				if (!isModuleFile(id)) return await serveRaw(id, false);
+				const body = await cache.exists(`${tRoot}/${id}`) ? await readText(cache, `${tRoot}/${id}`) : await transformAndCache(id);
+				return new Response(body, {
+					status: 200,
+					headers: { "content-type": "text/javascript" }
+				});
+			} catch {
+				return new Response(null, { status: 404 });
+			}
+		}
+	};
+}
+function normalizeBase(base) {
+	let b = base.startsWith("/") ? base : `/${base}`;
+	if (!b.endsWith("/")) b += "/";
+	return b;
+}
+function normalizeDeps(prefix) {
+	if (!prefix) return "";
+	const s = prefix.replace(/^\/+/, "").replace(/\/+$/, "");
+	return s ? `${s}/` : "";
+}
+async function collect(chunks) {
+	const parts = [];
+	let n = 0;
+	for await (const c of chunks) {
+		parts.push(c);
+		n += c.length;
+	}
+	const out = new Uint8Array(n);
+	let off = 0;
+	for (const p of parts) {
+		out.set(p, off);
+		off += p.length;
+	}
+	return out;
+}
+//#endregion
+export { ModuleResolveError, ModuleTransformError, detectFormat, newCjsTransform, newDefaultTransform, newEsmTransform, newModuleServer, npmRegistrySource, parseSpecifier, relativeUrl, untarTgz };