buninu-browser 0.0.2

package/lib/renderer/main.js

@@ -0,0 +1,234 @@
+/**
+ * Renderer process entry point.
+ *
+ * Holds one page pipeline and answers the controller over Bun's IPC channel.
+ * The renderer has no network access of its own: subresource requests are
+ * sent to the controller, which applies its policy and returns the bytes.
+ *
+ * Protocol (structured-clone messages):
+ *   controller -> renderer  { type: "call", id, method, params }
+ *                           { type: "fetch-result", id, result | error }
+ *   renderer -> controller  { type: "ready", sandbox: { seccomp, ses } } (each { installed, reason })
+ *                           { type: "result", id, result | error }
+ *                           { type: "fetch", id, url, kind }
+ *                           { type: "navigate", url }
+ *                           { type: "page-fetch", id, request }  (fetch/XHR, answered by fetch-result)
+ *                           { type: "cookie", value }            (document.cookie = value)
+ *                           { type: "lifecycle", name, generation } (DOMContentLoaded, load)
+ *                           { type: "ws-open", id, url, protocols } / { type: "ws-send", id, data }
+ *                           / { type: "ws-close", id, code, reason }  (page WebSockets)
+ *   controller -> renderer  { type: "ws-event", id, event, ... }  (open, message, error, close)
+ *
+ * With --compositor, a compositor Worker (compositor.js) answers screenshots
+ * and scrolling on fd 3 while this thread is busy; frames go to it with
+ * postMessage.
+ *
+ * Startup order matters for the sandbox:
+ *   1. load every module (SES included), start the compositor, and build the page pipeline;
+ *   2. warm up everything that loads lazily;
+ *   3. install seccomp, which forbids opening files, sockets and processes;
+ *   4. lockdown() (SES), after which page scripts run in compartments.
+ * bun:ffi (used by seccomp) stops working after lockdown, so 3 precedes 4.
+ */
+import "../../vendor/ses/dist/ses.mjs";
+import { createPageRenderer } from "./page-renderer.js";
+import { COMPOSITOR_FLAG, MOBILE_FLAG } from "./flags.js";
+import { installSeccomp } from "./seccomp.js";
+import { RENDERER_LOG_FLAG } from "../log.js";
+import wasmpeg from "../../vendor/wasmpeg/src/js/index.js";
+
+const DANGEROUSLY_ALLOW_HOST_JS = "--dangerously-allow-host-js";
+
+/** Methods the controller may invoke; anything else is ignored. */
+const METHODS = new Set([
+  "loadDocument", "showFragment", "runJavaScriptURL", "url", "scrollTo", "resize", "screenshot", "title",
+  "scroll", "press", "type", "scrollOffset", "click", "evaluate", "setUserAgent", "consoleMessages", "whenLoaded",
+  "applyCompositorScroll",
+]);
+
+// Set when the controller logs this renderer's output (BUNINU_LOG).
+const logging = process.argv.includes(RENDERER_LOG_FLAG);
+// Straight to stderr: with --dangerously-allow-host-js the page replaces the
+// global console, whose messages are themselves forwarded here.
+const stderr = process.stderr;
+const report = (text) => stderr.write(`${text}\n`);
+
+// As in browsers, a page's unhandled rejection is logged, not fatal.
+process.on("unhandledRejection", (reason) => {
+  const text = reason?.stack || (reason?.name ? `${reason.name}: ${reason.message}` : String(reason));
+  report(`buninu-browser: page error: unhandled rejection: ${logging ? text : text.split("\n")[0]}`);
+});
+
+const pendingFetches = new Map();
+let nextFetchId = 1;
+
+function fetchResource(url, kind) {
+  return new Promise((resolve, reject) => {
+    const id = nextFetchId++;
+    pendingFetches.set(id, { resolve, reject });
+    process.send({ type: "fetch", id, url, kind });
+  });
+}
+
+function pageFetch(request) {
+  return new Promise((resolve, reject) => {
+    const id = nextFetchId++;
+    pendingFetches.set(id, { resolve, reject });
+    process.send({ type: "page-fetch", id, request });
+  });
+}
+
+// Page WebSockets live in the controller (Bun's WebSocket); events come back as ws-event.
+const socketListeners = new Map();
+let nextSocketId = 1;
+const webSockets = {
+  open(url, protocols, onEvent) {
+    const id = nextSocketId++;
+    socketListeners.set(id, onEvent);
+    process.send({ type: "ws-open", id, url, protocols });
+    return id;
+  },
+  send: (id, data) => process.send({ type: "ws-send", id, data }),
+  close: (id, code, reason) => process.send({ type: "ws-close", id, code, reason }),
+};
+
+// Workers load their module from disk, so this happens before seccomp.
+const compositor = process.argv.includes(COMPOSITOR_FLAG) ? await startCompositor() : null;
+
+// Frames sent to the compositor and the latest one it confirmed.
+let framesSent = 0;
+let framesAcknowledged = 0;
+let frameWaiters = [];
+
+/** Resolves once the compositor holds every frame sent so far. */
+function compositorCaughtUp() {
+  if (framesAcknowledged >= framesSent) return Promise.resolve();
+  const target = framesSent;
+  return new Promise((resolve) => frameWaiters.push({ target, resolve }));
+}
+
+async function startCompositor() {
+  const worker = new Worker(new URL("./compositor.js", import.meta.url).href);
+  await new Promise((resolve, reject) => {
+    worker.addEventListener("message", resolve, { once: true });
+    worker.addEventListener("error", reject, { once: true });
+  });
+  worker.addEventListener("message", ({ data }) => {
+    if (data?.type === "scroll") renderer.applyCompositorScroll(data.x, data.y);
+    else if (data?.type === "frame-ack" && Number.isInteger(data.serial)) {
+      framesAcknowledged = Math.max(framesAcknowledged, data.serial);
+      frameWaiters = frameWaiters.filter((waiter) => {
+        if (waiter.target > framesAcknowledged) return true;
+        waiter.resolve();
+        return false;
+      });
+    }
+  });
+  return worker;
+}
+
+const renderer = await createPageRenderer({
+  fetchResource,
+  requestNavigation: (url) => process.send({ type: "navigate", url }),
+  pageFetch,
+  webSockets,
+  setCookie: (value) => process.send({ type: "cookie", value }),
+  reportError: (message) => report(`buninu-browser: page error: ${logging ? message : String(message).split("\n")[0]}`),
+  consoleMessage: logging ? (level, text) => report(`page console.${level}: ${text}`) : null,
+  trace: logging ? (text) => report(`timing: ${text}`) : null,
+  onFrame: compositor ? (frame) => compositor.postMessage({ type: "frame", serial: ++framesSent, ...frame }) : null,
+  onLifecycle: (name, generation) => process.send({ type: "lifecycle", name, generation }),
+  mobile: process.argv.includes(MOBILE_FLAG),
+  videoDecoder: wasmpeg,
+});
+await warmUp();
+const allowHostJs = process.argv.includes(DANGEROUSLY_ALLOW_HOST_JS);
+const seccomp = allowHostJs
+  ? { installed: false, reason: `disabled by ${DANGEROUSLY_ALLOW_HOST_JS}` }
+  : installSeccomp();
+const ses = allowHostJs ? { installed: false, reason: `disabled by ${DANGEROUSLY_ALLOW_HOST_JS}` } : lockdownRealm();
+renderer.setScripting(allowHostJs ? "host" : ses.installed ? "ses" : "off");
+
+/** Hardens the JavaScript realm so page scripts can run in SES compartments. */
+function lockdownRealm() {
+  try {
+    lockdown({
+      errorTaming: "safe",
+      overrideTaming: "severe",
+      consoleTaming: "unsafe",
+      localeTaming: "unsafe",
+      stackFiltering: "concise",
+      // SES otherwise lists every non-standard intrinsic it removes on stderr.
+      reporting: "none",
+    });
+    return { installed: true, reason: null };
+  } catch (error) {
+    return { installed: false, reason: String(error?.message ?? error) };
+  }
+}
+
+/**
+ * Exercises code paths that read files or initialise state on first use, so
+ * they do not need the file system once seccomp is installed.
+ */
+async function warmUp() {
+  await wasmpeg.load();
+  new Date().toString();
+  new Intl.DateTimeFormat(undefined, { dateStyle: "full", timeStyle: "full" }).format(0);
+  new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(1);
+  new Intl.Segmenter(undefined, { granularity: "word" }).segment("warm up");
+  crypto.getRandomValues(new Uint8Array(16));
+  crypto.randomUUID();
+  // 1x1 PNG: initialises Bun.Image's decoder before the sandbox is closed.
+  const png = Uint8Array.from(atob(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+  ), (character) => character.charCodeAt(0));
+  await new Bun.Image(png).metadata();
+  await renderer.loadDocument({
+    url: "about:warm-up",
+    source: `<!doctype html><html><head><title>w</title><style>body{color:red}</style></head><body>
+      <h1>h</h1><p>p <a href="#x">a</a> <b>b</b> <code>c</code></p><ul><li>l</li></ul><ol><li>o</li></ol>
+      <table><tr><td>t</td></tr></table><form><input value="i"><textarea>t</textarea><select><option>o</option></select><button>b</button></form>
+      <img alt=""><svg width="1" height="1"><rect width="1" height="1"/></svg><canvas></canvas><template><p>t</p></template>
+      <div style="display:flex"><span>f</span></div><div style="display:grid"><span>g</span></div><pre>pre</pre></body></html>`,
+  });
+  await renderer.resize(800, 600, 1);
+  await renderer.screenshot();
+  await renderer.loadDocument({ url: "about:blank" });
+}
+
+process.on("message", async (message) => {
+  if (message?.type === "fetch-result") {
+    const pending = pendingFetches.get(message.id);
+    if (!pending) return;
+    pendingFetches.delete(message.id);
+    if (message.error) pending.reject(new Error(message.error));
+    else pending.resolve(message.result);
+    return;
+  }
+  if (message?.type === "ws-event") {
+    const listener = socketListeners.get(message.id);
+    if (message.event === "close") socketListeners.delete(message.id);
+    listener?.(message);
+    return;
+  }
+  if (message?.type !== "call" || !METHODS.has(message.method)) return;
+  try {
+    const result = await renderer[message.method](...(Array.isArray(message.params) ? message.params : []));
+    // A screenshot requested after this result must include what the call painted.
+    await compositorCaughtUp();
+    process.send({ type: "result", id: message.id, result });
+  } catch (error) {
+    // SES "safe" error taming blanks .stack, so keep name and message too.
+    const text = error?.stack || (error?.name ? `${error.name}: ${error.message}` : String(error));
+    report(`buninu-browser: renderer ${message.method} failed: ${text}`);
+    process.send({ type: "result", id: message.id, error: text });
+  }
+});
+
+process.on("disconnect", () => {
+  renderer.dispose();
+  process.exit(0);
+});
+
+process.send({ type: "ready", sandbox: { seccomp, ses } });

package/lib/renderer/module-transform.js

@@ -0,0 +1,399 @@
+/**
+ * Turns an ES module into an async function a page compartment can run.
+ *
+ * The result evaluates to
+ *
+ *   (async function (__buninu_module__) { … })
+ *
+ * and runs in two phases so cyclic graphs can see each other's exports:
+ *
+ *   1. up to `await __buninu_module__.linked`, the module defines its export
+ *      getters (live: they read the module's own bindings, so later
+ *      assignments are visible, and uninitialised let/const still throw) and
+ *      copies `export *` names;
+ *   2. after the loader resolves `linked`, the module body runs.
+ *
+ * Imported bindings are live: every reference to an imported name that is
+ * not shadowed by a local declaration is rewritten to a read of the
+ * dependency's namespace, so values assigned later (and cycles) behave as in
+ * ESM. `import.meta` and `import()` are rewritten to loader calls. Parsing
+ * uses Acorn.
+ */
+import { Parser } from "../../vendor/acorn/dist/acorn.mjs";
+import { boundNames } from "./script-rewrite.js";
+
+const MODULE = "__buninu_module__";
+
+/**
+ * @param {string} source module text
+ * @returns {{ code: string, requests: { specifier: string, type: string | null }[] }}
+ */
+export function transformModule(source) {
+  const program = Parser.parse(source, { ecmaVersion: "latest", sourceType: "module", allowHashBang: true });
+  const requests = [];
+  const requestIndex = new Map();
+  const request = (node) => {
+    const specifier = String(node.source.value);
+    const type = importType(node);
+    const key = `${type ?? ""}\n${specifier}`;
+    if (!requestIndex.has(key)) {
+      requestIndex.set(key, requests.length);
+      requests.push({ specifier, type });
+    }
+    return requestIndex.get(key);
+  };
+
+  const edits = [];
+  const getters = [];
+  const starExports = [];
+  // Imported locals re-exported with `export { a }` read the dependency's
+  // namespace directly, so they work before the body has run.
+  const importExpressions = new Map();
+  const namespace = (index) => `${MODULE}.namespaces[${index}]`;
+  const getter = (exported, expression) => getters.push(
+    `Object.defineProperty(${MODULE}.exports, ${JSON.stringify(exported)}, `
+    + `{ enumerable: true, configurable: true, get: () => ${expression} });`,
+  );
+  const exportedName = (node) => node.type === "Literal" ? String(node.value) : node.name;
+
+  for (const node of program.body) {
+    switch (node.type) {
+      case "ImportDeclaration": {
+        const index = request(node);
+        for (const specifier of node.specifiers) {
+          const local = specifier.local.name;
+          const expression = specifier.type === "ImportDefaultSpecifier" ? `${namespace(index)}.default`
+            : specifier.type === "ImportNamespaceSpecifier" ? namespace(index)
+              : `${namespace(index)}[${JSON.stringify(exportedName(specifier.imported))}]`;
+          importExpressions.set(local, expression);
+        }
+        edits.push({ start: node.start, end: node.end, text: "" });
+        break;
+      }
+      case "ExportNamedDeclaration": {
+        if (node.declaration) {
+          // `export const a = 1` -> `const a = 1` plus a getter per bound name.
+          edits.push({ start: node.start, end: node.declaration.start, text: "" });
+          const declaration = node.declaration;
+          const names = declaration.type === "VariableDeclaration"
+            ? declaration.declarations.flatMap((declarator) => boundNames(declarator.id))
+            : [declaration.id.name];
+          for (const name of names) getter(name, name);
+        } else if (node.source) {
+          const index = request(node);
+          for (const specifier of node.specifiers) {
+            getter(exportedName(specifier.exported), `${namespace(index)}[${JSON.stringify(exportedName(specifier.local))}]`);
+          }
+          edits.push({ start: node.start, end: node.end, text: "" });
+        } else {
+          for (const specifier of node.specifiers) {
+            const local = specifier.local.name;
+            getter(exportedName(specifier.exported), importExpressions.get(local) ?? local);
+          }
+          edits.push({ start: node.start, end: node.end, text: "" });
+        }
+        break;
+      }
+      case "ExportDefaultDeclaration": {
+        const declaration = node.declaration;
+        const named = (declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") && declaration.id;
+        if (named) {
+          edits.push({ start: node.start, end: declaration.start, text: "" });
+          getter("default", declaration.id.name);
+        } else {
+          // Prefix and suffix edits only, so edits inside the expression
+          // (import.meta, import()) never overlap this one.
+          const local = `${MODULE}_default`;
+          edits.push({ start: node.start, end: declaration.start, text: `const ${local} = (` });
+          edits.push({ start: declaration.end, end: declaration.end, text: ");" });
+          getter("default", local);
+        }
+        break;
+      }
+      case "ExportAllDeclaration": {
+        const index = request(node);
+        if (node.exported) getter(exportedName(node.exported), namespace(index));
+        else starExports.push(index);
+        edits.push({ start: node.start, end: node.end, text: "" });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  rewriteImportReferences(program, importExpressions, edits);
+
+  // import.meta and import() can appear anywhere in the module.
+  walk(program, (node) => {
+    if (node.type === "MetaProperty" && node.meta.name === "import") {
+      edits.push({ start: node.start, end: node.end, text: `${MODULE}.meta` });
+    } else if (node.type === "ImportExpression") {
+      // Replace only `import(`; the arguments keep their own edits.
+      edits.push({ start: node.start, end: node.source.start, text: `${MODULE}.importDynamic(` });
+    }
+    return true;
+  });
+
+  edits.sort((left, right) => right.start - left.start);
+  let body = source.startsWith("#!") ? source.slice(source.indexOf("\n") + 1) : source;
+  const offset = source.length - body.length;
+  for (const edit of edits) {
+    const start = edit.start - offset;
+    const end = edit.end - offset;
+    body = body.slice(0, start) + edit.text + body.slice(end);
+  }
+  const stars = starExports.map((index) => `${MODULE}.exportStar(${namespace(index)});`).join("\n");
+  const code = `(async function (${MODULE}) {
+"use strict";
+${getters.join("\n")}
+${stars}
+await ${MODULE}.linked;
+${body}
+})`;
+  return { code, requests };
+}
+
+/**
+ * Rewrites references to imported names into namespace reads. A scope stack
+ * tracks declarations so shadowed names (parameters, locals, catch
+ * parameters, block bindings) are left alone.
+ */
+function rewriteImportReferences(program, imports, edits) {
+  if (!imports.size) return;
+  const scopes = [];
+  const isImport = (name) => imports.has(name) && !scopes.some((scope) => scope.has(name));
+  const reference = (node) => {
+    if (isImport(node.name)) edits.push({ start: node.start, end: node.end, text: imports.get(node.name) });
+  };
+  const withScope = (names, fn) => {
+    scopes.push(names);
+    try {
+      fn();
+    } finally {
+      scopes.pop();
+    }
+  };
+
+  /** Declaration patterns: only default values and computed keys are expressions. */
+  const pattern = (node) => {
+    if (!node) return;
+    switch (node.type) {
+      case "Identifier": return;
+      case "ObjectPattern":
+        for (const property of node.properties) {
+          if (property.type === "RestElement") pattern(property.argument);
+          else {
+            if (property.computed) expression(property.key);
+            pattern(property.value);
+          }
+        }
+        return;
+      case "ArrayPattern":
+        for (const element of node.elements) pattern(element);
+        return;
+      case "AssignmentPattern":
+        pattern(node.left);
+        expression(node.right);
+        return;
+      case "RestElement":
+        pattern(node.argument);
+        return;
+      default:
+        expression(node);
+    }
+  };
+
+  const functionNode = (node) => {
+    const names = new Set();
+    if (node.type === "FunctionExpression" && node.id) names.add(node.id.name);
+    for (const parameter of node.params) for (const name of boundNames(parameter)) names.add(name);
+    if (node.body.type === "BlockStatement") {
+      collectVarNames(node.body, names);
+      for (const name of lexicalNames(node.body.body)) names.add(name);
+    }
+    withScope(names, () => {
+      for (const parameter of node.params) pattern(parameter);
+      if (node.body.type === "BlockStatement") for (const statement of node.body.body) expression(statement);
+      else expression(node.body);
+    });
+  };
+
+  const classNode = (node) => {
+    const names = new Set(node.type === "ClassExpression" && node.id ? [node.id.name] : []);
+    if (node.superClass) expression(node.superClass);
+    withScope(names, () => {
+      for (const member of node.body.body) {
+        if (member.type === "StaticBlock") {
+          withScope(new Set(lexicalNames(member.body)), () => member.body.forEach(expression));
+          continue;
+        }
+        if (member.computed) expression(member.key);
+        if (member.value) expression(member.value);
+      }
+    });
+  };
+
+  function expression(node) {
+    if (!node || typeof node.type !== "string") return;
+    switch (node.type) {
+      case "Identifier": reference(node); return;
+      case "ImportDeclaration":
+      case "MetaProperty":
+      case "BreakStatement":
+      case "ContinueStatement":
+        return;
+      case "FunctionDeclaration":
+      case "FunctionExpression":
+      case "ArrowFunctionExpression":
+        functionNode(node);
+        return;
+      case "ClassDeclaration":
+      case "ClassExpression":
+        classNode(node);
+        return;
+      case "VariableDeclaration":
+        for (const declarator of node.declarations) {
+          pattern(declarator.id);
+          expression(declarator.init);
+        }
+        return;
+      case "BlockStatement":
+      case "StaticBlock":
+        withScope(new Set(lexicalNames(node.body)), () => node.body.forEach(expression));
+        return;
+      case "SwitchStatement":
+        expression(node.discriminant);
+        withScope(new Set(node.cases.flatMap((entry) => lexicalNames(entry.consequent))), () => {
+          for (const entry of node.cases) {
+            expression(entry.test);
+            entry.consequent.forEach(expression);
+          }
+        });
+        return;
+      case "ForStatement":
+      case "ForInStatement":
+      case "ForOfStatement": {
+        const head = node.type === "ForStatement" ? node.init : node.left;
+        const names = head?.type === "VariableDeclaration" && head.kind !== "var"
+          ? new Set(head.declarations.flatMap((declarator) => boundNames(declarator.id)))
+          : new Set();
+        withScope(names, () => {
+          for (const key of ["init", "test", "update", "left", "right", "body"]) expression(node[key]);
+        });
+        return;
+      }
+      case "CatchClause": {
+        const names = new Set(node.param ? boundNames(node.param) : []);
+        withScope(names, () => {
+          pattern(node.param);
+          expression(node.body);
+        });
+        return;
+      }
+      case "LabeledStatement":
+        expression(node.body);
+        return;
+      case "MemberExpression":
+        expression(node.object);
+        if (node.computed) expression(node.property);
+        return;
+      case "Property":
+        if (node.computed) expression(node.key);
+        if (node.shorthand && node.value.type === "Identifier" && isImport(node.value.name)) {
+          // `{ a }` -> `{ a: <namespace read> }`
+          edits.push({ start: node.start, end: node.end, text: `${node.key.name}: ${imports.get(node.value.name)}` });
+        } else {
+          expression(node.value);
+        }
+        return;
+      case "MethodDefinition":
+      case "PropertyDefinition":
+        if (node.computed) expression(node.key);
+        expression(node.value);
+        return;
+      case "ExportNamedDeclaration":
+        expression(node.declaration);
+        return;
+      case "ExportSpecifier":
+      case "ExportAllDeclaration":
+        return;
+      default:
+        for (const [key, value] of Object.entries(node)) {
+          if (key === "type" || key === "start" || key === "end") continue;
+          for (const child of Array.isArray(value) ? value : [value]) {
+            if (child && typeof child === "object") expression(child);
+          }
+        }
+    }
+  }
+
+  program.body.forEach(expression);
+}
+
+/** let/const/class/function names declared directly in a statement list. */
+function lexicalNames(statements) {
+  const names = [];
+  for (const statement of statements) {
+    const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    if (!declaration) continue;
+    if (declaration.type === "VariableDeclaration" && declaration.kind !== "var") {
+      for (const declarator of declaration.declarations) names.push(...boundNames(declarator.id));
+    } else if ((declaration.type === "FunctionDeclaration" || declaration.type === "ClassDeclaration") && declaration.id) {
+      names.push(declaration.id.name);
+    }
+  }
+  return names;
+}
+
+/** `var` names anywhere in a function body, not crossing nested functions. */
+function collectVarNames(node, names) {
+  if (!node || typeof node.type !== "string") return;
+  if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") return;
+  if (node.type === "VariableDeclaration" && node.kind === "var") {
+    for (const declarator of node.declarations) for (const name of boundNames(declarator.id)) names.add(name);
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "type" || key === "start" || key === "end") continue;
+    for (const child of Array.isArray(value) ? value : [value]) {
+      if (child && typeof child === "object") collectVarNames(child, names);
+    }
+  }
+}
+
+function importType(node) {
+  const attribute = (node.attributes ?? []).find((entry) =>
+    (entry.key.name ?? entry.key.value) === "type");
+  return attribute ? String(attribute.value.value) : null;
+}
+
+/** Depth-first walk; the visitor returns false to skip a node's children. */
+function walk(node, visit) {
+  if (!node || typeof node.type !== "string") return;
+  if (visit(node) === false) return;
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "type" || key === "start" || key === "end") continue;
+    for (const child of Array.isArray(value) ? value : [value]) {
+      if (child && typeof child === "object") walk(child, visit);
+    }
+  }
+}
+
+/**
+ * Resolves a module specifier against its referrer and an import map
+ * ({ imports: { specifier: url } }, exact and trailing-slash prefix entries).
+ */
+export function resolveModuleSpecifier(specifier, referrer, importMap = null) {
+  const imports = importMap?.imports ?? {};
+  if (Object.hasOwn(imports, specifier)) return new URL(imports[specifier], referrer).href;
+  const prefix = Object.keys(imports)
+    .filter((key) => key.endsWith("/") && specifier.startsWith(key))
+    .sort((left, right) => right.length - left.length)[0];
+  if (prefix) return new URL(imports[prefix] + specifier.slice(prefix.length), referrer).href;
+  if (/^(?:\.{0,2}\/)/.test(specifier)) return new URL(specifier, referrer).href;
+  try {
+    return new URL(specifier).href;
+  } catch {
+    throw new TypeError(`Failed to resolve module specifier "${specifier}"`);
+  }
+}