@tokenoftrust/storefront-runner 2.5.5 → 3.0.0

package/packages/public-runtime/src/capture-rewrites.ts

@@ -0,0 +1,687 @@
+/**
+ * Capture rewrites: replace each captured image reference in artifact text with its platform-owned
+ * `/_a/<sha256><ext>` URL, leaving every reference that was not captured exactly as written.
+ *
+ * One engine for every place a captured revision is rendered: the hosted preview overlay
+ * (`hosted-preview-image-capture.ts`) and the static publish, which rewrites the checked-out tenant
+ * tree from the same sealed manifest before it builds (`scripts/publish/apply-captured-images.mjs`),
+ * so both CDNs serve the bytes the preview showed. Pure string work with no runtime imports, so the
+ * publish scripts load it directly.
+ */
+import type { ImageDependency, ImageDependencyArtifact } from "./image-dependencies.js";
+
+export type CaptureRewrite = {
+  /** Effect-only; never log or render. */
+  canonicalLocator: string;
+  /** Additional spellings present in artifact text (raw locator, sealed path). */
+  aliases: string[];
+  /**
+   * Remote spellings (also listed in `aliases`) that match only as written: a following `?query`
+   * is a different URL, and a different image, so it is never absorbed into the match.
+   */
+  exactAliases?: string[];
+  platformUrl: string;
+  address: string;
+  mediaType: string;
+};
+
+/** A sealed capture-manifest entry, as `original-image-capture.ts` writes it. */
+export interface CapturedManifestEntry {
+  /** Remote `locator` is query-stripped for display; remote entries are matched by `locatorDigest`. */
+  provenance: { kind: "local" | "remote"; locator: string };
+  address: string;
+  mediaType: string;
+  /** Remote entries: digest of the exact fetched locator, query included (`captureLocatorDigest`). */
+  locatorDigest?: string;
+}
+
+export function stripQueryFragment(value: string): string {
+  return value.split(/[?#]/, 1)[0] ?? value;
+}
+
+export function isAbsoluteHttpLocator(value: string): boolean {
+  return /^https?:\/\//i.test(value) || value.startsWith("//");
+}
+
+/** Bare local path with a leading slash; absolute http(s) locators stay absolute. */
+export function normalizeRewriteLocator(value: string): string {
+  const bare = stripQueryFragment(value);
+  if (isAbsoluteHttpLocator(bare)) return bare;
+  return bare.startsWith("/") ? bare : `/${bare}`;
+}
+
+export function localPathKey(value: string): string {
+  return stripQueryFragment(value).replace(/^\//, "");
+}
+
+export function addAlias(aliases: string[], value: string | undefined, canonical: string): void {
+  if (!value || value === canonical || aliases.includes(value)) return;
+  aliases.push(value);
+}
+
+export function locatorWasCaptured(captured: ReadonlySet<string>, locator: string): boolean {
+  if (captured.has(locator)) return true;
+  // A remote query names a different image, so only that exact spelling (fragment aside) counts:
+  // `render?id=1` captured says nothing about `render?id=2`.
+  if (isAbsoluteHttpLocator(locator)) return captured.has(locator.split("#", 1)[0]!);
+  const bare = stripQueryFragment(locator);
+  if (captured.has(bare) || captured.has(bare.replace(/^\//, "")) || captured.has(`/${bare.replace(/^\//, "")}`)) {
+    return true;
+  }
+  const key = localPathKey(locator);
+  for (const item of captured) {
+    if (localPathKey(item) === key) return true;
+    if (stripQueryFragment(item) === bare) return true;
+  }
+  return false;
+}
+
+/** Characters that may continue a longer absolute URL around a locator token. */
+const URL_TOKEN_CONTINUE = /[A-Za-z0-9._~:@%+\-]/;
+/**
+ * Path/query/fragment glue inside an absolute URL token.
+ * Includes `;` so HTML `&amp;`-joined query embeds stay one enclosing token.
+ */
+const URL_TOKEN_INNER = /[A-Za-z0-9._~:@%+\-/?#&=;]/;
+
+function isLocatorLeftEdge(prev: string | undefined, haystack?: string, start?: number): boolean {
+  if (prev == null) return true;
+  // Attribute/CSS value starts — not URL query/fragment/assignment glue.
+  // `(` and `,` are NOT standalone edges: enclosingUrlToken cannot span them, so
+  // a captured alias after `(` / `,` inside a longer absolute/root-relative URL
+  // would otherwise rewrite in place. `(` is allowed only for flush `url(`;
+  // spaced srcset candidates use whitespace as the edge.
+  if (prev === '"' || prev === "'" || prev === "=" || /\s/.test(prev)) {
+    return true;
+  }
+  if (prev === "(" && haystack != null && start != null) {
+    // `url(/path)` or `url(  /path)` — optional whitespace already handled when
+    // prev is whitespace; here prev is the opening paren flush against the locator.
+    const before = haystack.slice(Math.max(0, start - 4), start);
+    if (before.toLowerCase() === "url(") return true;
+    return false;
+  }
+  // `,` is never a standalone left edge. Spaced srcset/imagesrcset candidates
+  // (`1x, /path`) already have whitespace as prev. A comma inside an absolute
+  // URL query list (`?list=/u.png,/path`) must not rewrite the post-comma alias.
+  if (prev === ",") return false;
+  // HTML entity-quoted CSS url(&quot;/path&quot;)
+  if (
+    haystack != null
+    && start != null
+    && start >= 6
+    && haystack.slice(start - 6, start).toLowerCase() === "&quot;"
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function isLocatorRightEdge(next: string | undefined): boolean {
+  if (next == null) return true;
+  return next === '"' || next === "'" || next === ")" || next === "?" || next === "#" || next === ","
+    || /\s/.test(next);
+}
+
+/**
+ * Start of the current tag region before `index`. Quotes are only meaningful
+ * inside tags, so text apostrophes (don't) cannot poison later markup.
+ */
+function currentTagStart(haystack: string, index: number): number {
+  let quote: string | null = null;
+  let inTag = false;
+  let last = 0;
+  for (let i = 0; i < index; i++) {
+    const ch = haystack[i]!;
+    if (!inTag) {
+      if (ch === "<") {
+        inTag = true;
+        quote = null;
+        last = i;
+      }
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ">") {
+      inTag = false;
+      last = i + 1;
+    }
+  }
+  return last;
+}
+
+/** True when index sits inside attribute quotes within the current tag. */
+function isInsideQuotes(haystack: string, index: number): boolean {
+  let quote: string | null = null;
+  let inTag = false;
+  for (let i = 0; i < index; i++) {
+    const ch = haystack[i]!;
+    if (!inTag) {
+      if (ch === "<") {
+        inTag = true;
+        quote = null;
+      }
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ">") {
+      inTag = false;
+      quote = null;
+    }
+  }
+  return inTag && quote != null;
+}
+
+/**
+ * HTML/SVG void self-close (`…png/>`) outside quoted attribute values.
+ * Inside quotes, `/>` is path text.
+ */
+function isHtmlSelfCloseSlash(haystack: string, slashIndex: number): boolean {
+  if (haystack[slashIndex] !== "/" || haystack[slashIndex + 1] !== ">") return false;
+  return !isInsideQuotes(haystack, slashIndex);
+}
+
+/**
+ * Strip an unquoted `attr=` glue prefix that enclosingUrlToken may attach
+ * (`src=https://…`, `href=//cdn…`).
+ */
+function stripAttrAssignmentPrefix(value: string): string {
+  return value.replace(/^[A-Za-z_:][\w:.-]*=/, "");
+}
+
+/**
+ * Expand [start, end) through URL-significant characters to the enclosing
+ * absolute-or-path token (stops at quotes, whitespace, parens).
+ */
+function enclosingUrlToken(haystack: string, start: number, end: number): { start: number; end: number; value: string } {
+  let left = start;
+  while (left > 0 && URL_TOKEN_INNER.test(haystack[left - 1]!)) {
+    // Do not absorb a wrapping `&quot;` entity into the URL token.
+    if (
+      haystack[left - 1] === ";"
+      && left >= 6
+      && haystack.slice(left - 6, left).toLowerCase() === "&quot;"
+    ) {
+      break;
+    }
+    left -= 1;
+  }
+  let right = end;
+  while (right < haystack.length && URL_TOKEN_INNER.test(haystack[right]!)) {
+    // Markup self-close (`…png/>`) is not URL path — stop before absorbing `/`.
+    if (isHtmlSelfCloseSlash(haystack, right)) break;
+    // Closing `&quot;` wrapper around a CSS url() argument.
+    if (haystack.slice(right, right + 6).toLowerCase() === "&quot;") break;
+    right += 1;
+  }
+  return { start: left, end: right, value: haystack.slice(left, right) };
+}
+
+/**
+ * Start of the HTML/CSS attribute (or url()) value that contains `index`.
+ * Returns -1 when no value opener is found in the current tag.
+ */
+function attributeValueStart(haystack: string, index: number): number {
+  const from = currentTagStart(haystack, index);
+  let valueStart = -1;
+  let inQuote: string | null = null;
+  let inUnquotedValue = false;
+  for (let j = from; j < index; j++) {
+    const ch = haystack[j]!;
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+        valueStart = -1;
+      }
+      continue;
+    }
+    if (inUnquotedValue) {
+      // `=` inside an unquoted value (mailto?body=…) is not a new attribute.
+      if (/\s/.test(ch)) {
+        inUnquotedValue = false;
+        valueStart = -1;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inQuote = ch;
+      valueStart = j + 1;
+      continue;
+    }
+    if (ch === "=") {
+      let k = j + 1;
+      while (k < index && /\s/.test(haystack[k]!)) k += 1;
+      // k may equal index when the locator begins the unquoted value.
+      if (k > index) continue;
+      if (k < haystack.length && (haystack[k] === '"' || haystack[k] === "'")) continue;
+      valueStart = k;
+      inUnquotedValue = true;
+      continue;
+    }
+    if (ch === "(") {
+      valueStart = j + 1;
+    }
+  }
+  return valueStart;
+}
+
+/**
+ * True when the match sits inside a mailto:/sms:/tel: attribute value.
+ * Only the current attribute value is inspected (not earlier attrs on the tag).
+ */
+function isInsideContactScheme(haystack: string, start: number): boolean {
+  const valueStart = attributeValueStart(haystack, start);
+  if (valueStart < 0 || valueStart > start) return false;
+  return /^(?:mailto|sms|tel):/i.test(haystack.slice(valueStart, start).trimStart());
+}
+
+/** Attribute name for the value containing `index`, or null. */
+function currentAttributeName(haystack: string, index: number): string | null {
+  const valueStart = attributeValueStart(haystack, index);
+  if (valueStart < 0) return null;
+  let i = valueStart - 1;
+  while (i >= 0 && (haystack[i] === '"' || haystack[i] === "'" || haystack[i] === "=" || /\s/.test(haystack[i]!))) {
+    i -= 1;
+  }
+  const end = i + 1;
+  while (i >= 0 && /[\w:-]/.test(haystack[i]!)) i -= 1;
+  const name = haystack.slice(i + 1, end);
+  return name ? name.toLowerCase() : null;
+}
+
+/**
+ * If `index` is inside a CSS `url(…)`, return the optional quote that opened
+ * the url argument. Null when not inside url(.
+ */
+function cssUrlArgContext(haystack: string, index: number): { quote: string | null } | null {
+  let from = attributeValueStart(haystack, index);
+  if (from < 0) {
+    from = 0;
+    for (let i = index - 1; i >= 0; i--) {
+      const ch = haystack[i]!;
+      if (ch === "{" || ch === ";" || ch === "<") {
+        from = i + 1;
+        break;
+      }
+    }
+  } else {
+    // valueStart may sit just after `url(` or inside `url("…")` / `url('…')`,
+    // including arbitrary whitespace: `url(        "…" )`. Walk back over an
+    // optional quote then whitespace and require a flush `url(` — no fixed
+    // suffix window (a 12-char cap breaks at ≥8 spaces before the quote).
+    let i = from;
+    if (i > 0 && (haystack[i - 1] === '"' || haystack[i - 1] === "'")) {
+      i -= 1;
+    }
+    while (i > 0 && /\s/.test(haystack[i - 1]!)) i -= 1;
+    if (i >= 4 && haystack.slice(i - 4, i).toLowerCase() === "url(") {
+      from = i - 4;
+    }
+  }
+  // Bound the scan so a prior attribute's `url(` cannot poison this value.
+  const before = haystack.slice(from, index);
+  let lastUrl = -1;
+  let quote: string | null = null;
+  for (let i = 0; i < before.length; i++) {
+    const ch = before[i]!;
+    // CSS escapes: \X is literal; keep quote state across \" inside url("…").
+    if (ch === "\\" && i + 1 < before.length) {
+      i += 1;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (before.slice(i, i + 4).toLowerCase() === "url(") {
+      lastUrl = i;
+      i += 3;
+    }
+  }
+  if (lastUrl < 0) return null;
+  const afterUrl = before.slice(lastUrl + 4);
+  let q: string | null = null;
+  let depth = 1;
+  for (let i = 0; i < afterUrl.length; i++) {
+    const ch = afterUrl[i]!;
+    if (ch === "\\" && i + 1 < afterUrl.length) {
+      i += 1;
+      continue;
+    }
+    if (q) {
+      if (ch === q) q = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      q = ch;
+      continue;
+    }
+    if (ch === "(") depth += 1;
+    if (ch === ")") {
+      depth -= 1;
+      if (depth === 0) return null;
+    }
+  }
+  const argOpen = afterUrl.match(/^\s*(['"]|&quot;)/i);
+  if (!argOpen) return { quote: null };
+  const opener = argOpen[1]!;
+  return { quote: opener.toLowerCase() === "&quot;" ? "&quot;" : opener };
+}
+
+/**
+ * Extend through a locator's own query/fragment until a context delimiter.
+ * - CSS `url(`: stop at the argument's quote or unquoted `)`
+ * - srcset: stop before descriptor whitespace / quotes (spaced candidate lists)
+ * - other quoted attrs: through the value (query may contain `,` `>` `)`)
+ * - unquoted attrs: through URL-safe query chars plus `,` / parentheses
+ */
+function extendOwnQueryEnd(haystack: string, queryStart: number): number {
+  const valueStart = attributeValueStart(haystack, queryStart);
+  const opener = valueStart > 0
+    && (haystack[valueStart - 1] === '"' || haystack[valueStart - 1] === "'")
+    ? haystack[valueStart - 1]!
+    : null;
+  const cssUrl = cssUrlArgContext(haystack, queryStart);
+  const attrName = currentAttributeName(haystack, queryStart);
+  const inSrcset = attrName === "srcset" || attrName === "imagesrcset";
+  let i = queryStart;
+  let unquotedUrlDepth = cssUrl && !cssUrl.quote ? 1 : 0;
+  while (i < haystack.length) {
+    const ch = haystack[i]!;
+    if (cssUrl) {
+      // CSS escapes: \X is a literal X inside url(), not a delimiter.
+      if (ch === "\\" && i + 1 < haystack.length) {
+        i += 2;
+        continue;
+      }
+      if (cssUrl.quote === "&quot;") {
+        if (haystack.slice(i, i + 6).toLowerCase() === "&quot;") break;
+      } else if (cssUrl.quote) {
+        if (ch === cssUrl.quote) break;
+      } else {
+        if (ch === "(") unquotedUrlDepth += 1;
+        if (ch === ")") {
+          unquotedUrlDepth -= 1;
+          if (unquotedUrlDepth <= 0) break;
+        }
+      }
+      i += 1;
+      continue;
+    }
+    if (inSrcset) {
+      // Stop at descriptor whitespace / quotes only. Comma heuristics fight
+      // mid-query path commas vs dense next-candidates; prefer full query
+      // strip (PII) and require spaced srcset forms (`?v=1 1x, other.png`).
+      if (/\s/.test(ch)) break;
+      if (opener && ch === opener) break;
+      if (!opener && (ch === '"' || ch === "'" || ch === "<" || ch === ">" )) break;
+      if (isHtmlSelfCloseSlash(haystack, i)) break;
+      if (!URL_TOKEN_INNER.test(ch) && ch !== "," && ch !== "(" && ch !== ")") break;
+      i += 1;
+      continue;
+    }
+    if (opener) {
+      if (ch === opener) break;
+      i += 1;
+      continue;
+    }
+    // HTML entity closer for url(&quot;…&quot;)
+    if (
+      (ch === "&")
+      && haystack.slice(i, i + 6).toLowerCase() === "&quot;"
+    ) {
+      break;
+    }
+    if (ch === '"' || ch === "'" || ch === "<" || ch === ">" || /\s/.test(ch)) break;
+    if (isHtmlSelfCloseSlash(haystack, i)) break;
+    // Unquoted src/href queries may include parentheses and commas.
+    if (!URL_TOKEN_INNER.test(ch) && ch !== "," && ch !== "(" && ch !== ")") break;
+    i += 1;
+  }
+  return i;
+}
+
+/**
+ * When needle is a standalone locator, return the end index to replace
+ * (may extend through the locator's own ?query/#fragment). Otherwise null.
+ */
+function standaloneReplaceEnd(haystack: string, start: number, end: number, needle: string, exact = false): number | null {
+  const prev = start > 0 ? haystack[start - 1] : undefined;
+  const next = end < haystack.length ? haystack[end] : undefined;
+  // An exact (remote) spelling followed by its own query is a different URL.
+  if (exact && next === "?") return null;
+  if (!isLocatorLeftEdge(prev, haystack, start)) return null;
+  if (isInsideContactScheme(haystack, start)) return null;
+  // Bare path may be followed by its own query when a longer alias was absent.
+  // A trailing `/` before `>` is HTML/SVG self-close, not path continuation.
+  if (!isLocatorRightEdge(next) && next !== "?" && next !== "#" && !isHtmlSelfCloseSlash(haystack, end)) {
+    if (URL_TOKEN_CONTINUE.test(next!) || next === "/") return null;
+  }
+  const enclosing = enclosingUrlToken(haystack, start, end);
+  const payload = stripAttrAssignmentPrefix(enclosing.value);
+  const payloadOrigin = enclosing.start + (enclosing.value.length - payload.length);
+  // Longer enclosing token ⇒ needle is embedded (absolute/relative/mailto/sms
+  // query or path). attr= glue alone is stripped first so unquoted absolute
+  // capture targets still match. A locator's own ?query/#fragment is standalone
+  // and replaced in full so query PII never rides onto `/_a/…`.
+  if (payload !== needle && payload.length > needle.length) {
+    const ownSuffix = payload[needle.length];
+    if (
+      start === payloadOrigin
+      && payload.startsWith(needle)
+      && (ownSuffix === "?" || ownSuffix === "#")
+    ) {
+      return extendOwnQueryEnd(haystack, start + needle.length);
+    }
+    return null;
+  }
+  // Bare needle at value start with an immediate own query/fragment.
+  if (next === "?" || next === "#") {
+    return extendOwnQueryEnd(haystack, end);
+  }
+  return end;
+}
+
+/** HTML source may keep `&amp;` while scan aliases decode to `&`. */
+function htmlAmpVariants(value: string): string[] {
+  if (!value.includes("&") || value.includes("&amp;")) return [];
+  return [value.replace(/&/g, "&amp;")];
+}
+
+/**
+ * Replace only full locator / URL tokens (src/url values), never a bare path
+ * substring inside a longer absolute URL.
+ */
+function replaceAllLocatorTokens(haystack: string, needle: string, replacement: string, exact = false): string {
+  if (!needle || needle === replacement) return haystack;
+  let out = "";
+  let cursor = 0;
+  while (cursor < haystack.length) {
+    const idx = haystack.indexOf(needle, cursor);
+    if (idx === -1) {
+      out += haystack.slice(cursor);
+      break;
+    }
+    out += haystack.slice(cursor, idx);
+    const end = idx + needle.length;
+    const replaceEnd = standaloneReplaceEnd(haystack, idx, end, needle, exact);
+    if (replaceEnd != null) {
+      out += replacement;
+      cursor = replaceEnd;
+    } else {
+      out += haystack[idx]!;
+      cursor = idx + 1;
+    }
+  }
+  return out;
+}
+
+/** Replace captured locators with platform-owned URLs. Leaves unresolved refs intact. */
+export function applyCaptureRewrites(
+  artifacts: readonly ImageDependencyArtifact[],
+  rewrites: readonly CaptureRewrite[],
+): ImageDependencyArtifact[] {
+  if (rewrites.length === 0) return artifacts.map((a) => ({ ...a }));
+  const prepared = rewrites.map((rewrite) => {
+    // Longer needles first so `/path?v=1` wins over slash-stripped `path`.
+    // Include `&amp;` spellings so HTML-escaped query joins still match.
+    const baseNeedles = [rewrite.canonicalLocator, ...rewrite.aliases].filter(Boolean);
+    const needles = [...new Set(baseNeedles.flatMap((n) => [n, ...htmlAmpVariants(n)]))]
+      .sort((a, b) => b.length - a.length);
+    // Every needle normally contains the shortest one, so an artifact without it holds none of
+    // them: one native search skips the rewrite. A catalog is thousands of rewrites over thousands
+    // of files, and most files name a handful of images.
+    const shortest = needles[needles.length - 1] ?? "";
+    const key = shortest && needles.every((needle) => needle.includes(shortest)) ? shortest : null;
+    const exact = new Set((rewrite.exactAliases ?? []).flatMap((n) => [n, ...htmlAmpVariants(n)]));
+    return { rewrite, needles, key, exact };
+  });
+  return artifacts.map((artifact) => {
+    let content = artifact.content;
+    for (const { rewrite, needles, key, exact } of prepared) {
+      if (key !== null && !content.includes(key)) continue;
+      for (const needle of needles) {
+        content = replaceAllLocatorTokens(content, needle, rewrite.platformUrl, exact.has(needle));
+      }
+    }
+    // Guard: slash-stripped local needles must not leave a protocol-relative URL.
+    content = content.replace(/\/{2,}_a\//g, "/_a/");
+    return { ...artifact, content };
+  });
+}
+
+/**
+ * One rewrite per sealed address, carrying every spelling of it the scan saw.
+ *
+ * A local entry names a repo file, so its query is irrelevant: it matches by path and carries the
+ * sealed path with and without its leading slash, plus every query-bearing spelling of that path.
+ * A remote entry names exactly the URL that was fetched, query included: it matches only a
+ * reference whose canonical locator has its `locatorDigest`, and carries only that reference's
+ * own spellings, never the query-stripped path (which would rewrite a query-distinct sibling, a
+ * different image, to this one). A key that names more than one address is never resolved.
+ */
+export function buildCaptureRewrites(input: {
+  entries: readonly CapturedManifestEntry[];
+  dependencies: readonly Pick<ImageDependency, "disposition" | "reason" | "canonicalLocator" | "locator">[];
+  platformUrl(address: string, mediaType: string): string;
+  /** `captureLocatorDigest`: sha256 hex of the canonical locator, fragment dropped. */
+  locatorDigest(canonicalLocator: string): string;
+}): CaptureRewrite[] {
+  const rewrites: CaptureRewrite[] = [];
+  const byAddress = new Map<string, CaptureRewrite>();
+  const rewriteFor = (entry: CapturedManifestEntry, canonicalLocator: string): CaptureRewrite => {
+    const existing = byAddress.get(entry.address);
+    if (existing) return existing;
+    const rewrite: CaptureRewrite = {
+      canonicalLocator,
+      aliases: [],
+      platformUrl: input.platformUrl(entry.address, entry.mediaType),
+      address: entry.address,
+      mediaType: entry.mediaType,
+    };
+    byAddress.set(entry.address, rewrite);
+    rewrites.push(rewrite);
+    return rewrite;
+  };
+
+  // Indexed rather than scanned: a catalog seals thousands of entries for thousands of references.
+  // `null` marks a key that names more than one address.
+  const localByKey = new Map<string, CapturedManifestEntry | null>();
+  const remoteByDigest = new Map<string, CapturedManifestEntry | null>();
+  const index = (table: Map<string, CapturedManifestEntry | null>, key: string, entry: CapturedManifestEntry) => {
+    const current = table.get(key);
+    if (current === undefined) table.set(key, entry);
+    else if (current !== null && current.address !== entry.address) table.set(key, null);
+  };
+  for (const entry of input.entries) {
+    if (entry.provenance.kind === "local") index(localByKey, localPathKey(entry.provenance.locator), entry);
+    else if (entry.locatorDigest) index(remoteByDigest, entry.locatorDigest, entry);
+  }
+
+  for (const entry of input.entries) {
+    if (entry.provenance.kind !== "local" || !localByKey.get(localPathKey(entry.provenance.locator))) continue;
+    const sealed = entry.provenance.locator;
+    const rewrite = rewriteFor(entry, normalizeRewriteLocator(sealed));
+    addAlias(rewrite.aliases, sealed, rewrite.canonicalLocator);
+    addAlias(rewrite.aliases, sealed.replace(/^\//, ""), rewrite.canonicalLocator);
+    addAlias(rewrite.aliases, `/${sealed.replace(/^\//, "")}`, rewrite.canonicalLocator);
+  }
+
+  for (const dep of input.dependencies) {
+    if (dep.disposition !== "capture-required") continue;
+    if (dep.reason === "local") {
+      const keys = new Set([localPathKey(dep.canonicalLocator), localPathKey(dep.locator)]);
+      const hits = [...keys].map((key) => localByKey.get(key));
+      if (hits.some((hit) => hit === null)) continue;
+      const entry = hits.find((hit): hit is CapturedManifestEntry => hit !== undefined);
+      if (!entry) continue;
+      const rewrite = rewriteFor(entry, normalizeRewriteLocator(dep.canonicalLocator));
+      rewrite.canonicalLocator = normalizeRewriteLocator(dep.canonicalLocator);
+      addAlias(rewrite.aliases, dep.locator, rewrite.canonicalLocator);
+      addAlias(rewrite.aliases, dep.canonicalLocator, rewrite.canonicalLocator);
+      addAlias(rewrite.aliases, stripQueryFragment(dep.locator), rewrite.canonicalLocator);
+      addAlias(rewrite.aliases, stripQueryFragment(dep.canonicalLocator), rewrite.canonicalLocator);
+      addAlias(rewrite.aliases, entry.provenance.locator, rewrite.canonicalLocator);
+    } else if (dep.reason === "third-party") {
+      const entry = remoteByDigest.get(input.locatorDigest(dep.canonicalLocator));
+      if (!entry) continue;
+      const exact = dep.canonicalLocator.split("#", 1)[0]!;
+      const rewrite = rewriteFor(entry, exact);
+      const exactAliases = (rewrite.exactAliases ??= []);
+      for (const spelling of [exact, dep.locator, dep.locator.split("#", 1)[0]!]) {
+        addAlias(rewrite.aliases, spelling, rewrite.canonicalLocator);
+        if (spelling && !exactAliases.includes(spelling)) exactAliases.push(spelling);
+      }
+    }
+  }
+  return rewrites;
+}
+
+/**
+ * Rewrite a JSON document whose image references are whole string values, such as the catalog
+ * listing projection: every string equal to a captured spelling becomes its platform URL, and the
+ * document is re-serialized. Linear in the document, where the text engine above is linear in the
+ * document per rewrite — a listing is one multi-megabyte document naming every catalog image.
+ * Returns null for text that is not JSON.
+ */
+export function rewriteJsonImageValues(content: string, rewrites: readonly CaptureRewrite[]): string | null {
+  let root: unknown;
+  try {
+    root = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  const byNeedle = new Map<string, string>();
+  for (const rewrite of rewrites) {
+    for (const needle of [rewrite.canonicalLocator, ...rewrite.aliases]) {
+      if (needle && !byNeedle.has(needle)) byNeedle.set(needle, rewrite.platformUrl);
+    }
+  }
+  const visit = (value: unknown): unknown => {
+    if (typeof value === "string") return byNeedle.get(value.trim()) ?? value;
+    if (Array.isArray(value)) return value.map(visit);
+    if (value && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, child]) => [key, visit(child)]));
+    }
+    return value;
+  };
+  return JSON.stringify(visit(root));
+}