@statewalker/webrun-bundler 0.0.0-stage → 0.1.0

package/src/bundle.ts

@@ -0,0 +1,245 @@
+import { readText } from "@statewalker/webrun-files";
+import type { Loader, Plugin } from "esbuild-wasm";
+import { inlineInputMap } from "./input-maps.js";
+import { nodeModulesPackages } from "./packages.js";
+import { idOf, joinWithin, pathOf, readManifest } from "./paths.js";
+import { resolveSpecifier } from "./resolve.js";
+import type {
+  BundleOptions,
+  BundleResult,
+  ExternalPattern,
+  Mount,
+  SourceMap,
+  TranspileOptions,
+  TranspileResult,
+} from "./types.js";
+
+/** esbuild's namespace for the files the bundler serves; its source-map names drop it. */
+const NS = "webrun";
+/** esbuild's namespace for the host's modules (`modules`): `virtual:<specifier>` in maps. */
+const VNS = "webrun-virtual";
+/** Marks an `inject` entry, so that it resolves like an import, not like the entry point. */
+const INJECT = "webrun-inject:";
+
+/** esbuild `supported` flags that lower `await` to generators. */
+const LOWER_AWAIT = { "async-await": false, "async-generator": false, "for-await": false };
+
+const LOADERS: Record<string, Loader> = {
+  ts: "ts",
+  mts: "ts",
+  cts: "ts",
+  tsx: "tsx",
+  jsx: "jsx",
+  js: "js",
+  mjs: "js",
+  cjs: "js",
+  json: "json",
+  css: "css",
+  txt: "text",
+  wasm: "binary",
+};
+export const loaderFor = (path: string): Loader =>
+  LOADERS[/\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase() ?? ""] ?? "js";
+
+const isExternal = (spec: string, patterns: ExternalPattern[]) =>
+  /^(https?:|data:)/.test(spec) ||
+  patterns.some((p) =>
+    typeof p === "string"
+      ? p.endsWith("*")
+        ? spec.startsWith(p.slice(0, -1))
+        : spec === p
+      : p.test(spec),
+  );
+
+/** A source name of esbuild's map → the file id it stands for. */
+const sourceId = (s: string) =>
+  s
+    .replace(/^(\.\.\/)*/, "")
+    .replace(new RegExp(`^${VNS}:`), "virtual:")
+    .replace(new RegExp(`^${NS}:`), "");
+
+const toBase64 = (text: string) => {
+  const bytes = new TextEncoder().encode(text);
+  let bin = "";
+  for (let i = 0; i < bytes.length; i += 0x8000)
+    bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(bin);
+};
+
+/** `code` with its trailing map link replaced: by `map` inlined, or by a link to `name`. */
+function linkMap(code: string, map: SourceMap, how: "external" | "inline", name: string) {
+  const body = code.replace(/\n?\/\/# sourceMappingURL=\S+\s*$/, "");
+  const url =
+    how === "inline"
+      ? `data:application/json;base64,${toBase64(JSON.stringify(map))}`
+      : `${name.split("/").pop()}.map`;
+  return `${body}\n//# sourceMappingURL=${url}\n`;
+}
+
+/**
+ * Bundles `entry` of a project into one module with esbuild (esbuild-wasm in browsers).
+ * Every file is read through FilesApi (the project's, or a package's from `packages`):
+ * esbuild resolves and loads nothing itself. esbuild transpiles TypeScript and JSX,
+ * converts CommonJS, lowers `await` when asked, and bundles, all in one pass, and its
+ * source map goes back through each step to the files it read; where a package ships
+ * its own map (TypeScript compiled to `.js`), to the package's original source. The
+ * map's sources are file ids: `~/src/app.ts`, `npm:pkg@1.2.3/src/index.ts`.
+ */
+export async function bundle(opts: BundleOptions): Promise<BundleResult> {
+  const root = opts.root ?? "/";
+  const project: Mount = {
+    prefix: "~",
+    files: opts.files,
+    root,
+    manifest: await readManifest(opts.files, root),
+  };
+  const packages = opts.packages ?? nodeModulesPackages();
+  const external = opts.external ?? [];
+  const browser = (opts.platform ?? "browser") === "browser";
+  const conditions = opts.conditions ?? ["browser"];
+  const outfile = opts.outfile ?? "bundle.js";
+  const mounts = new Map<string, Mount>([[project.prefix, project]]);
+  const supplied = opts.modules;
+  const virtualSource = (spec: string) =>
+    typeof supplied === "function" ? supplied(spec) : supplied?.[spec];
+
+  /** The mount and path of a file id; the longest prefix wins (`npm:@a/b@1.0.0/…`). */
+  const locate = (id: string) => {
+    let best: Mount | undefined;
+    for (const m of mounts.values())
+      if (id.startsWith(`${m.prefix}/`) && (!best || m.prefix.length > best.prefix.length))
+        best = m;
+    const path = best && pathOf(best, id);
+    if (!best || !path) throw new Error(`webrun-bundler: no file ${id}`);
+    return { mount: best, path };
+  };
+
+  const plugin: Plugin = {
+    name: "webrun-files",
+    setup(b) {
+      b.onResolve({ filter: /.*/ }, async (args) => {
+        const injected = args.path.startsWith(INJECT);
+        const spec = injected ? args.path.slice(INJECT.length) : args.path;
+        if (args.kind === "entry-point" && !injected) {
+          const path = joinWithin(root, root, args.path.replace(/^\/+/, ""));
+          if (!path) return { errors: [{ text: `entry ${args.path} is outside the project` }] };
+          return { path: idOf(project, path), namespace: NS };
+        }
+        if (virtualSource(spec) !== undefined) return { path: spec, namespace: VNS };
+        if (isExternal(spec, external)) return { path: spec, external: true };
+        // The host's modules and `inject` entries import from the project's root.
+        const importer =
+          injected || args.namespace === VNS
+            ? { mount: project, path: `${root === "/" ? "" : root}/` }
+            : locate(args.importer);
+        const require = args.kind === "require-call" || args.kind === "require-resolve";
+        const failed = (why?: string) => ({
+          errors: [
+            {
+              text: `Could not resolve "${spec}" (imported by ${args.importer || "inject"})${why ? `: ${why}` : ""}`,
+            },
+          ],
+        });
+        let r: Awaited<ReturnType<typeof resolveSpecifier>>;
+        try {
+          r = await resolveSpecifier(spec, importer, packages, {
+            conditions,
+            require,
+            browser,
+          });
+        } catch (e) {
+          return failed((e as Error)?.message ?? String(e));
+        }
+        if (!r) return failed();
+        mounts.set(r.mount.prefix, r.mount);
+        return { path: idOf(r.mount, r.path), namespace: NS };
+      });
+      b.onLoad({ filter: /.*/, namespace: VNS }, (args) => ({
+        contents: virtualSource(args.path) ?? "",
+        loader: "js",
+      }));
+      b.onLoad({ filter: /.*/, namespace: NS }, async (args) => {
+        const { mount, path } = locate(args.path);
+        const loader = loaderFor(path);
+        if (loader === "binary") {
+          const chunks: Uint8Array[] = [];
+          for await (const c of mount.files.read(path)) chunks.push(c);
+          const bytes = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+          let at = 0;
+          for (const c of chunks) {
+            bytes.set(c, at);
+            at += c.length;
+          }
+          return { contents: bytes, loader };
+        }
+        const text = await readText(mount.files, path);
+        const js = loader === "js" || loader === "ts" || loader === "jsx" || loader === "tsx";
+        return { contents: js ? await inlineInputMap(mount, path, text) : text, loader };
+      });
+    },
+  };
+
+  const { plugins: extraPlugins = [], ...rest } = opts.esbuildOptions ?? {};
+  const result = await opts.esbuild.build({
+    entryPoints: [opts.entry],
+    bundle: true,
+    write: false,
+    format: opts.format ?? "esm",
+    platform: opts.platform ?? "browser",
+    target: opts.target ?? "es2022",
+    outfile,
+    absWorkingDir: "/",
+    metafile: true,
+    logLevel: "silent",
+    minify: opts.minify,
+    define: opts.define,
+    ...(opts.lowerAwait ? { supported: LOWER_AWAIT } : {}),
+    ...rest,
+    ...(opts.inject?.length ? { inject: opts.inject.map((s) => INJECT + s) } : {}),
+    sourcemap: "external",
+    sourcesContent: true,
+    plugins: [...extraPlugins, plugin],
+  });
+  const out = result.outputFiles ?? [];
+  const jsFile = out.find((f) => !f.path.endsWith(".map"));
+  const mapFile = out.find((f) => f.path.endsWith(".map"));
+  if (!jsFile || !mapFile) throw new Error("webrun-bundler: esbuild produced no output");
+  const raw = JSON.parse(mapFile.text) as SourceMap;
+  const map: SourceMap = {
+    ...raw,
+    file: outfile.split("/").pop(),
+    sources: raw.sources.map(sourceId),
+  };
+  delete map.sourceRoot;
+  return {
+    code: linkMap(jsFile.text, map, opts.sourcemap ?? "external", outfile),
+    map,
+    metafile: result.metafile as BundleResult["metafile"],
+    warnings: result.warnings,
+  };
+}
+
+/**
+ * Transpiles one file (TypeScript, JSX, modern syntax down to `target`; `await` lowered
+ * when asked) with a source map back to it. A map the code carries (`sourceMappingURL`,
+ * inline) is composed in, so the result still traces to the original.
+ */
+export async function transpile(code: string, opts: TranspileOptions): Promise<TranspileResult> {
+  const r = await opts.esbuild.transform(code, {
+    loader: loaderFor(opts.path),
+    sourcefile: opts.path,
+    sourcemap: "external",
+    sourcesContent: true,
+    format: opts.format,
+    target: opts.target ?? "es2022",
+    minify: opts.minify,
+    define: opts.define,
+    ...(opts.lowerAwait ? { supported: LOWER_AWAIT } : {}),
+  });
+  const map = JSON.parse(r.map) as SourceMap;
+  return {
+    code: linkMap(r.code, map, opts.sourcemap ?? "external", opts.path.replace(/\.[^./]+$/, ".js")),
+    map,
+    warnings: r.warnings,
+  };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { bundle, loaderFor, transpile } from "./bundle.js";
+export { inlineInputMap } from "./input-maps.js";
+export { chainPackages, nodeModulesPackages, npmPackages } from "./packages.js";
+export { resolveSpecifier } from "./resolve.js";
+export type {
+  BundleOptions,
+  BundleResult,
+  Esbuild,
+  ExternalPattern,
+  Importer,
+  Mount,
+  PackageManifest,
+  PackageStore,
+  SourceMap,
+  TranspileOptions,
+  TranspileResult,
+} from "./types.js";

package/src/input-maps.ts

@@ -0,0 +1,79 @@
+import { tryReadText } from "@statewalker/webrun-files";
+import { dirOf, idOf, joinWithin } from "./paths.js";
+import type { Mount, SourceMap } from "./types.js";
+
+// The last `//# sourceMappingURL=…` (or `//@`) comment of a JS file.
+const MAP_COMMENT = /\/\/[#@]\s*sourceMappingURL=(\S+)\s*$/;
+
+const toBase64 = (text: string) => {
+  const bytes = new TextEncoder().encode(text);
+  let bin = "";
+  for (let i = 0; i < bytes.length; i += 0x8000)
+    bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(bin);
+};
+const fromBase64 = (b64: string) =>
+  new TextDecoder().decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)));
+
+/**
+ * A file's own source map, made usable by esbuild, which reads only maps inlined in
+ * the file it loads (it cannot follow a linked `.map` through a FilesApi):
+ *
+ * - a linked map (`//# sourceMappingURL=index.js.map`) is read from the same tree and
+ *   inlined; an inline `data:` map is kept;
+ * - its sources become ids of the same tree (`npm:pkg@1.0.0/src/index.ts`), so the
+ *   bundle's map names the package's original files, not the published JavaScript;
+ * - missing `sourcesContent` is filled from the tree when the original file ships
+ *   with the package.
+ *
+ * esbuild then composes it with its own: a bundled line traces to the original source.
+ * A map that is missing or unreadable is dropped (the file maps to itself).
+ */
+export async function inlineInputMap(mount: Mount, path: string, code: string): Promise<string> {
+  const lines = code.trimEnd().split("\n");
+  const last = lines[lines.length - 1] ?? "";
+  const match = MAP_COMMENT.exec(last);
+  if (!match) return code;
+  const url = match[1] as string;
+  const body = lines.slice(0, -1).join("\n");
+  let text: string | undefined;
+  let mapDir = dirOf(path);
+  if (url.startsWith("data:")) {
+    const comma = url.indexOf(",");
+    const meta = url.slice(5, comma);
+    const payload = url.slice(comma + 1);
+    try {
+      text = meta.endsWith(";base64") ? fromBase64(payload) : decodeURIComponent(payload);
+    } catch {
+      text = undefined;
+    }
+  } else if (!/^[a-z][a-z0-9+.-]*:/i.test(url)) {
+    const mapPath = joinWithin(mount.root, dirOf(path), decodeURIComponent(url));
+    if (mapPath) {
+      text = await tryReadText(mount.files, mapPath);
+      mapDir = dirOf(mapPath);
+    }
+  }
+  let map: SourceMap;
+  try {
+    map = JSON.parse(text ?? "") as SourceMap;
+  } catch {
+    return body; // no usable map: the file is its own source
+  }
+  const sourceDir = map.sourceRoot
+    ? (joinWithin("/", mapDir, map.sourceRoot.replace(/\/$/, "")) ?? mapDir)
+    : mapDir;
+  const contents: (string | null)[] = map.sourcesContent ? [...map.sourcesContent] : [];
+  const sources: string[] = [];
+  for (let i = 0; i < map.sources.length; i++) {
+    const src = map.sources[i] as string;
+    const local = /^[a-z][a-z0-9+.-]*:/i.test(src)
+      ? undefined
+      : joinWithin(mount.root, sourceDir, src);
+    sources.push(local ? idOf(mount, local) : src);
+    if (contents[i] == null && local) contents[i] = (await tryReadText(mount.files, local)) ?? null;
+  }
+  const fixed: SourceMap = { ...map, sources, sourcesContent: contents };
+  delete fixed.sourceRoot;
+  return `${body}\n//# sourceMappingURL=data:application/json;base64,${toBase64(JSON.stringify(fixed))}\n`;
+}

package/src/packages.ts

@@ -0,0 +1,126 @@
+import type { Source } from "@statewalker/webrun-modules";
+import { dirOf, readManifest } from "./paths.js";
+import type { Importer, Mount, PackageStore } from "./types.js";
+
+const mountPrefix = (name: string, version: string | undefined) =>
+  `npm:${name}@${version ?? "0.0.0"}`;
+
+/**
+ * Packages from `node_modules` folders, found as Node finds them: in the importing
+ * file's directory and each parent, inside the importer's own FilesApi. A package
+ * installed in the project (or in another package's `node_modules`) is read where it is.
+ *
+ * pnpm layouts: a package's own dependencies sit next to its real directory in
+ * `node_modules/.pnpm`, which Node reaches through the symlink's real path and a FilesApi
+ * cannot see. When the walk finds nothing, each ancestor's `node_modules/.pnpm/node_modules`
+ * (pnpm's hoisted links to every installed package) is tried too.
+ */
+export function nodeModulesPackages(): PackageStore {
+  const mounts = new Map<string, Mount>();
+  const at = async (files: Mount["files"], root: string, name: string) => {
+    const known = mounts.get(root);
+    if (known && known.files === files) return known;
+    const manifest = await readManifest(files, root);
+    if (!manifest) return undefined;
+    const mount: Mount = { prefix: mountPrefix(name, manifest.version), files, root, manifest };
+    mounts.set(root, mount);
+    return mount;
+  };
+  const ancestors = (path: string) => {
+    const dirs: string[] = [];
+    for (let dir = dirOf(path); ; dir = dirOf(dir)) {
+      dirs.push(dir === "/" ? "" : dir);
+      if (dir === "/") return dirs;
+    }
+  };
+  return {
+    async get(name, importer) {
+      const files = importer.mount.files;
+      const dirs = ancestors(importer.path);
+      for (const dir of dirs) {
+        const m = await at(files, `${dir}/node_modules/${name}`, name);
+        if (m) return m;
+      }
+      for (const dir of dirs) {
+        const m = await at(files, `${dir}/node_modules/.pnpm/node_modules/${name}`, name);
+        if (m) return m;
+      }
+      return undefined;
+    },
+  };
+}
+
+const DEPENDENCY_FIELDS = [
+  "dependencies",
+  "peerDependencies",
+  "optionalDependencies",
+  "devDependencies",
+] as const;
+
+/** The version range `importer`'s `package.json` gives `name`, if any. */
+function rangeFor(name: string, importer: Importer): string | undefined {
+  const m = importer.mount.manifest;
+  for (const field of DEPENDENCY_FIELDS) {
+    const range = m?.[field]?.[name];
+    if (range) return range;
+  }
+  return undefined;
+}
+
+/**
+ * Packages fetched on demand (default: the npm registry, through webrun-modules'
+ * `npmRegistrySource`) and kept in memory: each one is its own FilesApi tree. The
+ * version is the range the importer's `package.json` declares (the project's for the
+ * project's files), else the latest; one range loads once.
+ */
+export function npmPackages(opts: { source?: Source } = {}): PackageStore {
+  // Loaded only when used: a bundle of the bundler that brings its own source stays small.
+  let registry: Promise<Source> | undefined;
+  const source: Source = opts.source ?? {
+    matches: (ref) => "pkg" in ref,
+    load: async (ref) => {
+      registry ??= import("@statewalker/webrun-modules").then((m) => m.npmRegistrySource());
+      return (await registry).load(ref);
+    },
+  };
+  const byRange = new Map<string, Promise<Mount>>();
+  const byVersion = new Map<string, Mount>();
+  return {
+    get(name, importer) {
+      const range = rangeFor(name, importer);
+      const key = `${name}@${range ?? "latest"}`;
+      let mount = byRange.get(key);
+      if (!mount) {
+        mount = source.load({ pkg: name, version: range }).then((p) => {
+          const prefix = mountPrefix(p.name, p.version);
+          const seen = byVersion.get(prefix);
+          if (seen) return seen; // two ranges, one version: one copy of the package
+          const m: Mount = { prefix, files: p.files, root: "/", manifest: p.manifest };
+          byVersion.set(prefix, m);
+          return m;
+        });
+        byRange.set(key, mount);
+      }
+      return mount;
+    },
+  };
+}
+
+/** The first store that has the package wins (`node_modules` first, then the registry). */
+export function chainPackages(...stores: PackageStore[]): PackageStore {
+  return {
+    async get(name, importer) {
+      let failure: unknown;
+      for (const s of stores) {
+        try {
+          const m = await s.get(name, importer);
+          if (m) return m;
+        } catch (e) {
+          failure ??= e; // the next store may still have it
+        }
+      }
+      if (failure) throw failure;
+      return undefined;
+    },
+  };
+}

package/src/paths.ts

@@ -0,0 +1,62 @@
+import { normalizePath, tryReadText } from "@statewalker/webrun-files";
+import type { Mount, PackageManifest } from "./types.js";
+
+/** `path` joined to `dir`, with `.` and `..` resolved; `undefined` when it leaves `root`. */
+export function joinWithin(root: string, dir: string, path: string): string | undefined {
+  const parts = (path.startsWith("/") ? path : `${dir}/${path}`).split("/");
+  const out: string[] = [];
+  for (const p of parts) {
+    if (!p || p === ".") continue;
+    if (p === "..") {
+      if (!out.length) return undefined;
+      out.pop();
+    } else out.push(p);
+  }
+  const joined = `/${out.join("/")}`;
+  const r = normalizePath(root);
+  return r === "/" || joined === r || joined.startsWith(`${r}/`) ? joined : undefined;
+}
+
+export const dirOf = (path: string) => path.slice(0, path.lastIndexOf("/")) || "/";
+
+/** The id of a mount's file: `<prefix>/<path below root>`. */
+export function idOf(mount: Mount, path: string): string {
+  const r = normalizePath(mount.root);
+  const rel = r === "/" ? path : path.slice(r.length);
+  return `${mount.prefix}${rel || "/"}`;
+}
+
+/** A mount's file from its id; `undefined` when the id is not the mount's. */
+export function pathOf(mount: Mount, id: string): string | undefined {
+  if (!id.startsWith(`${mount.prefix}/`)) return undefined;
+  const r = normalizePath(mount.root);
+  const rel = id.slice(mount.prefix.length);
+  return r === "/" ? rel : `${r}${rel}`;
+}
+
+export async function isFile(mount: Mount, path: string): Promise<boolean> {
+  const s = await mount.files.stats(path);
+  return s?.kind === "file";
+}
+
+export async function readManifest(
+  files: Mount["files"],
+  dir: string,
+): Promise<PackageManifest | undefined> {
+  const text = await tryReadText(files, `${dir === "/" ? "" : dir}/package.json`);
+  if (text === undefined) return undefined;
+  try {
+    return JSON.parse(text) as PackageManifest;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `react` → `{ name: "react" }`; `@a/b/c.js` → `{ name: "@a/b", subpath: "c.js" }`. */
+export function parsePackageSpecifier(spec: string): { name: string; subpath?: string } {
+  const parts = spec.split("/");
+  const n = spec.startsWith("@") ? 2 : 1;
+  const name = parts.slice(0, n).join("/");
+  const subpath = parts.slice(n).join("/");
+  return subpath ? { name, subpath } : { name };
+}

package/src/resolve.ts

@@ -0,0 +1,116 @@
+import { imports as resolveImports, exports as resolvePackageExports } from "resolve.exports";
+import { dirOf, isFile, joinWithin, parsePackageSpecifier } from "./paths.js";
+import type { Importer, Mount, PackageManifest, PackageStore } from "./types.js";
+
+/** Extensions tried, in order, for a path written without one (or with `.js` for a `.ts` file). */
+const EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs", ".json"];
+
+export interface Resolved {
+  mount: Mount;
+  path: string;
+}
+
+/** `path` as written, else with an extension, else its `index` file. */
+async function resolveFile(mount: Mount, path: string): Promise<string | undefined> {
+  if (await isFile(mount, path)) return path;
+  // TypeScript sources import `./x.js` for `./x.ts`.
+  const js = /\.(m|c)?jsx?$/.exec(path);
+  if (js) {
+    const base = path.slice(0, -js[0].length);
+    for (const ext of [`.${js[1] ?? ""}ts`, ".tsx"])
+      if (await isFile(mount, base + ext)) return base + ext;
+  }
+  for (const ext of EXTENSIONS) if (await isFile(mount, path + ext)) return path + ext;
+  const dir = path.endsWith("/") ? path.slice(0, -1) : path;
+  for (const ext of EXTENSIONS)
+    if (await isFile(mount, `${dir}/index${ext}`)) return `${dir}/index${ext}`;
+  return undefined;
+}
+
+type Conditions = { conditions: string[]; require: boolean; browser: boolean };
+
+function exportsTarget(
+  manifest: PackageManifest,
+  entry: string,
+  c: Conditions,
+): string | undefined {
+  try {
+    const out = resolvePackageExports(manifest, entry, {
+      conditions: c.conditions,
+      require: c.require,
+      browser: c.browser,
+    }) as string[] | undefined;
+    return out?.[0];
+  } catch {
+    return undefined;
+  }
+}
+
+/** A package's file for `subpath`: `exports` first, then `module`/`main` (and `browser` when it is a string). */
+async function resolvePackageEntry(
+  mount: Mount,
+  subpath: string | undefined,
+  c: Conditions,
+): Promise<string | undefined> {
+  const manifest = mount.manifest ?? {};
+  const entry = subpath ? `./${subpath}` : ".";
+  if (manifest.exports !== undefined) {
+    const target = exportsTarget(manifest, entry, c);
+    if (!target) return undefined; // not exported: Node refuses it as well
+    return joinWithin(mount.root, mount.root, target);
+  }
+  if (subpath) return resolveFile(mount, joinWithin(mount.root, mount.root, subpath) ?? "");
+  const fields = [
+    ...(c.browser && typeof manifest.browser === "string" ? [manifest.browser] : []),
+    ...(c.require ? [] : [manifest.module]),
+    manifest.main,
+    "index.js",
+  ].filter((f): f is string => typeof f === "string");
+  for (const f of fields) {
+    const p = joinWithin(mount.root, mount.root, f);
+    const file = p && (await resolveFile(mount, p));
+    if (file) return file;
+  }
+  return undefined;
+}
+
+/**
+ * Resolves `spec` as written in `importer`: a path of the same tree (`./x`, `../y.js`,
+ * `/z`), a `#imports` alias of the importer's package, or a package found by `packages`
+ * (with its `exports`, `module` and `main`).
+ */
+export async function resolveSpecifier(
+  spec: string,
+  importer: Importer,
+  packages: PackageStore,
+  c: Conditions,
+): Promise<Resolved | undefined> {
+  const { mount } = importer;
+  if (spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/") || spec === ".") {
+    const base = spec.startsWith("/") ? mount.root : dirOf(importer.path);
+    const target = joinWithin(mount.root, base, spec.startsWith("/") ? spec.slice(1) : spec);
+    const path = target && (await resolveFile(mount, target));
+    return path ? { mount, path } : undefined;
+  }
+  if (spec.startsWith("#")) {
+    try {
+      const out = resolveImports(mount.manifest ?? {}, spec, {
+        conditions: c.conditions,
+        require: c.require,
+        browser: c.browser,
+      }) as string[] | undefined;
+      const target = out?.[0];
+      if (!target) return undefined;
+      if (!target.startsWith(".")) return resolveSpecifier(target, importer, packages, c);
+      const path = joinWithin(mount.root, mount.root, target);
+      return path && (await isFile(mount, path)) ? { mount, path } : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  const { name, subpath } = parsePackageSpecifier(spec);
+  const pkg = await packages.get(name, importer);
+  if (!pkg) return undefined;
+  const path = await resolvePackageEntry(pkg, subpath, c);
+  return path && (await isFile(pkg, path)) ? { mount: pkg, path } : undefined;
+}