snappy-prerender 2.6.0-rc.2

package/src/core/minify.js

@@ -0,0 +1,42 @@
+import CleanCSS from 'clean-css';
+import { minify as minifyMarkup } from 'html-minifier-terser';
+
+/**
+ * Options matching react-snap's defaults, kept as the baseline so behaviour is
+ * familiar. Whitespace collapsing can change text nodes, which React notices during
+ * hydration, so minification stays opt-in and the hydration verifier is the check.
+ */
+const HTML_MINIFY_DEFAULTS = {
+  collapseBooleanAttributes: true,
+  collapseWhitespace: true,
+  decodeEntities: true,
+  keepClosingSlash: true,
+  sortAttributes: true,
+  sortClassName: false,
+};
+
+/**
+ * Minifies serialised HTML. `minifyCss` options are forwarded so styles inlined into
+ * the document are minified in the same pass. html-minifier-terser is async, so this
+ * resolves to the minified markup.
+ */
+export async function minifyHtml(html, options = {}, minifyCssOptions = false) {
+  const merged = {
+    ...HTML_MINIFY_DEFAULTS,
+    ...(options === true ? {} : options),
+  };
+  if (minifyCssOptions) merged.minifyCSS = minifyCssOptions === true ? {} : minifyCssOptions;
+  return minifyMarkup(html, merged);
+}
+
+/**
+ * Minifies a CSS string with clean-css, used for stylesheets inlined by the
+ * inlineCss feature.
+ */
+export function minifyCss(css, options = {}) {
+  const result = new CleanCSS(options === true ? {} : options).minify(css);
+  if (result.errors.length > 0) {
+    throw new Error(`CSS minification failed: ${result.errors.join('; ')}`);
+  }
+  return result.styles;
+}

package/src/core/normalize.js

@@ -0,0 +1,197 @@
+import { parse, serialize } from 'parse5';
+import { collectBuildOrigins, isMetadataUrlNode, metadataUrlValue } from './metadata-origin.js';
+
+const FREEZE_STYLE_ID = 'snappy-freeze';
+const REMOVE_ATTRIBUTE = 'data-prerender-remove';
+const MAX_METADATA_ORIGINS = 3;
+
+/**
+ * Cleans and post-processes the browser-serialised DOM before it is written to disk.
+ * Always: strips the injected animation-freezing style, removes elements marked with
+ * data-prerender-remove, and drops duplicate head styles emitted by CSS-in-JS.
+ * Optionally: removes style or script tags, marks scripts async, drops dead blob
+ * stylesheets, and adds preconnect and image preload hints.
+ */
+export function normaliseHtml(html, options = {}) {
+  const document = parse(html);
+  const stats = {
+    removedElements: 0,
+    dedupedStyles: 0,
+    hints: 0,
+    textSeparators: 0,
+    titleElements: 0,
+    metadataOrigins: [],
+  };
+  const seenStyles = new Set();
+  cleanChildren(document, stats, seenStyles, false, options);
+
+  const preconnectOrigins = options.preconnectOrigins ?? [];
+  const preloadImages = options.preloadImages ?? [];
+  if (preconnectOrigins.length > 0 || preloadImages.length > 0) {
+    stats.hints = appendHints(document, { preconnectOrigins, preloadImages });
+  }
+  return { html: serialize(document), stats };
+}
+
+// Rebuilds a node's child list, dropping removed nodes, separating adjacent text nodes
+// and de-duplicating head styles.
+function cleanChildren(parent, stats, seenStyles, inHead, options) {
+  const children = parent.childNodes ?? [];
+  const kept = [];
+  for (const child of children) {
+    const childInHead = inHead || child.tagName === 'head';
+    if (shouldRemove(child, stats, options)) continue;
+    if (childInHead && child.tagName === 'style' && dedupeStyle(child, stats, seenStyles)) continue;
+    if (childInHead && child.tagName === 'title') stats.titleElements += 1;
+    if (childInHead) collectMetadataOrigins(child, stats);
+    if (options.asyncScriptTags && child.tagName === 'script') markScriptAsync(child);
+    cleanChildren(child, stats, seenStyles, childInHead, options);
+    if (child.content) cleanChildren(child.content, stats, seenStyles, childInHead, options);
+    if (isText(kept[kept.length - 1]) && isText(child)) {
+      kept.push(createComment());
+      stats.textSeparators += 1;
+    }
+    kept.push(child);
+  }
+  parent.childNodes = kept;
+}
+
+// Reports whether a node is a text node.
+function isText(node) {
+  return node?.nodeName === '#text';
+}
+
+// Builds the comment node that keeps two text siblings apart, matching what React's
+// own server rendering emits so hydration finds the same node boundaries.
+function createComment() {
+  return { nodeName: '#comment', data: ' ', parentNode: null };
+}
+
+// Reports whether a node is removed for any of the configured reasons. The metadata script is
+// exempt: the head layer reads it on the client, so stripping it would lose the site defaults.
+function shouldRemove(node, stats, options) {
+  if (node.tagName === 'script' && hasAttribute(node, 'data-snappy-meta', null)) return false;
+  const reason =
+    (node.tagName === 'style' && hasAttribute(node, 'id', FREEZE_STYLE_ID)) ||
+    hasAttribute(node, REMOVE_ATTRIBUTE, null) ||
+    (options.removeStyleTags && node.tagName === 'style') ||
+    (options.removeScriptTags && node.tagName === 'script') ||
+    (options.removeBlobs && isBlobStylesheet(node));
+
+  if (!reason) return false;
+  stats.removedElements += 1;
+  return true;
+}
+
+// Records the build server origins that metadata URLs point at, so the run can warn once
+// about metadata composed without a public site URL.
+function collectMetadataOrigins(node, stats) {
+  if (stats.metadataOrigins.length >= MAX_METADATA_ORIGINS) return;
+  if (!isMetadataUrlNode(node)) return;
+  for (const origin of collectBuildOrigins(metadataUrlValue(node))) {
+    if (!stats.metadataOrigins.includes(origin)) stats.metadataOrigins.push(origin);
+  }
+}
+
+// Drops a style tag whose text was already seen, reporting it through stats.
+function dedupeStyle(node, stats, seenStyles) {
+  const text = textContent(node);
+  if (seenStyles.has(text)) {
+    stats.dedupedStyles += 1;
+    return true;
+  }
+  seenStyles.add(text);
+  return false;
+}
+
+// Adds async to external scripts that are neither async nor defer yet.
+function markScriptAsync(node) {
+  const attrs = node.attrs ?? [];
+  if (!attrs.some((attribute) => attribute.name === 'src')) return;
+  if (attrs.some((attribute) => attribute.name === 'async' || attribute.name === 'defer')) return;
+  attrs.push({ name: 'async', value: '' });
+}
+
+// Reports whether a node is a stylesheet link pointing at a dead blob URL.
+function isBlobStylesheet(node) {
+  if (node.tagName !== 'link') return false;
+  if (attributeValue(node, 'rel').toLowerCase() !== 'stylesheet') return false;
+  return attributeValue(node, 'href').startsWith('blob:');
+}
+
+// Appends preconnect and image preload links to the head, skipping duplicates.
+function appendHints(document, { preconnectOrigins, preloadImages }) {
+  const head = findHead(document);
+  if (!head) return 0;
+  const existing = new Set(
+    (head.childNodes ?? [])
+      .filter((node) => node.tagName === 'link')
+      .map((node) => `${attributeValue(node, 'rel')}|${attributeValue(node, 'href')}`),
+  );
+
+  let added = 0;
+  for (const origin of preconnectOrigins) {
+    if (existing.has(`preconnect|${origin}`)) continue;
+    existing.add(`preconnect|${origin}`);
+    head.childNodes.push(
+      createElement('link', [
+        { name: 'rel', value: 'preconnect' },
+        { name: 'href', value: origin },
+      ]),
+    );
+    added += 1;
+  }
+  for (const image of preloadImages) {
+    if (existing.has(`preload|${image}`)) continue;
+    existing.add(`preload|${image}`);
+    head.childNodes.push(
+      createElement('link', [
+        { name: 'rel', value: 'preload' },
+        { name: 'as', value: 'image' },
+        { name: 'href', value: image },
+      ]),
+    );
+    added += 1;
+  }
+  return added;
+}
+
+// Locates the head element of a parsed document.
+function findHead(document) {
+  const html = (document.childNodes ?? []).find((node) => node.tagName === 'html');
+  return (html?.childNodes ?? []).find((node) => node.tagName === 'head') ?? null;
+}
+
+// Builds a minimal parse5 element node for injection into the tree.
+function createElement(tagName, attrs = []) {
+  return {
+    nodeName: tagName,
+    tagName,
+    attrs,
+    namespaceURI: 'http://www.w3.org/1999/xhtml',
+    childNodes: [],
+    parentNode: null,
+  };
+}
+
+// Reads an attribute, optionally requiring an exact value.
+function hasAttribute(node, name, value) {
+  const attribute = node.attrs?.find((candidate) => candidate.name === name);
+  if (!attribute) return false;
+  return value === null || attribute.value === value;
+}
+
+// Reads an attribute value, defaulting to an empty string.
+function attributeValue(node, name) {
+  return node.attrs?.find((attribute) => attribute.name === name)?.value ?? '';
+}
+
+// Concatenates all text nodes beneath a node, used to compare style contents.
+function textContent(node) {
+  let text = '';
+  for (const child of node.childNodes ?? []) {
+    if (child.nodeName === '#text') text += child.value;
+    else text += textContent(child);
+  }
+  return text;
+}

package/src/core/output.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normaliseRoute } from './routes.js';
+
+/**
+ * Maps an app-relative route to its output file. The configured not-found route is
+ * always emitted as 404.html so hosts with static error pages pick it up.
+ */
+export function routeToFile(route, { flatOutput = false, notFoundRoute = null } = {}) {
+  const normalised = normaliseRoute(route);
+  if (notFoundRoute && normalised === normaliseRoute(notFoundRoute)) return '404.html';
+  if (normalised === '/') return 'index.html';
+  const relative = normalised.slice(1);
+  return flatOutput ? `${relative}.html` : path.posix.join(relative, 'index.html');
+}
+
+/**
+ * Maps a route to its screenshot file. The root route becomes index.png, other
+ * routes keep their path with the extension swapped.
+ */
+export function routeToScreenshotFile(route, { saveAs = 'png' } = {}) {
+  const normalised = normaliseRoute(route);
+  const extension = saveAs === 'jpeg' ? 'jpeg' : 'png';
+  if (normalised === '/') return `index.${extension}`;
+  return `${normalised.slice(1)}.${extension}`;
+}
+
+/**
+ * Finds routes that would write the same output file. Two routes can collide, most
+ * obviously with flatOutput where both "/" and "/index" map to index.html. Callers
+ * use this to refuse the ambiguous writes instead of letting one overwrite the other.
+ */
+export function findOutputCollisions(routes, config) {
+  const byFile = new Map();
+  const saveAs = config.saveAs ?? 'html';
+  for (const route of routes) {
+    const file =
+      saveAs === 'html' ? routeToFile(route, config) : routeToScreenshotFile(route, config);
+    const existing = byFile.get(file);
+    if (existing) existing.push(route);
+    else byFile.set(file, [route]);
+  }
+  return new Map([...byFile].filter(([, list]) => list.length > 1));
+}
+
+/**
+ * Writes one rendered route into the output directory. Identical existing files are
+ * left untouched, which keeps rebuilds and CI caches stable.
+ */
+export async function writeRouteHtml({ dir, route, html, config }) {
+  const file = routeToFile(route, config);
+  if (config.dryRun) {
+    return { route, file, status: 'dry-run', bytes: Buffer.byteLength(html) };
+  }
+  const written = await writeFileIfChanged({ dir, file, contents: html });
+  return { route, file, status: written.status, bytes: written.bytes };
+}
+
+/**
+ * Writes a generated file, leaving an identical one untouched. Page files and the state
+ * files routes reference both go through here so a rebuild only touches what changed.
+ */
+export async function writeFileIfChanged({ dir, file, contents }) {
+  const bytes = Buffer.byteLength(contents);
+  const target = path.join(dir, file);
+  const existing = await fs.readFile(target, 'utf8').catch(() => null);
+  if (existing === contents) return { file, status: 'unchanged', bytes };
+
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  // Written through a temporary file and renamed, so an interrupted run cannot leave a
+  // half-written file behind for a host to serve.
+  const temporary = `${target}.snappy-tmp`;
+  try {
+    await fs.writeFile(temporary, contents, 'utf8');
+    await fs.rename(temporary, target);
+  } catch (error) {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+  return { file, status: 'written', bytes };
+}

package/src/core/preload-manifest.js

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { toPublicPath } from './routes.js';
+
+/**
+ * Builds the preload manifest: for every route, the same-origin scripts and
+ * stylesheets it loaded, rendered as a Link header value. This replaces react-snap's
+ * http2PushManifest because browsers removed HTTP/2 push (Chrome in v106); hosts can
+ * still use these values for Early Hints or Link response headers. Hints and route keys
+ * both carry the base path so they match the URLs a host actually sees.
+ */
+export function buildPreloadManifest(entries, { ignoreForPreload = [], base = '/' } = {}) {
+  const ignored = new Set(ignoreForPreload);
+  const manifest = [];
+  for (const entry of entries) {
+    const hints = [];
+    for (const asset of [...entry.scripts, ...entry.styles]) {
+      if (ignored.has(path.posix.basename(asset))) continue;
+      const as = entry.scripts.includes(asset) ? 'script' : 'style';
+      hints.push(`<${toPublicPath(asset, base)}>;rel=preload;as=${as}`);
+    }
+    if (hints.length === 0) continue;
+    manifest.push({
+      source: toPublicPath(entry.route, base),
+      headers: [{ key: 'Link', value: hints.join(',') }],
+    });
+  }
+  return manifest;
+}

package/src/core/render.js

@@ -0,0 +1,228 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { captureFormState } from './form-state.js';
+import { inlineStylesheets } from './inline-css.js';
+import { createResourceCollector } from './resources.js';
+import { toAppRoute, toServerUrl } from './routes.js';
+import { captureRuntimeStyles } from './runtime-styles.js';
+import { freezeAnimations, scrollThroughPage, settlePage, trackNetwork } from './settle.js';
+import { separateTextNodes } from './text-separators.js';
+
+const SCRIPT_ESCAPES = {
+  '<': '\\u003C',
+  '>': '\\u003E',
+  '/': '\\u002F',
+  '\u2028': '\\u2028',
+  '\u2029': '\\u2029',
+};
+
+// Serialises a value for embedding in a script element without allowing tag breakout.
+function escapeForScript(value) {
+  return JSON.stringify(value).replace(/[<>/\u2028\u2029]/g, (char) => SCRIPT_ESCAPES[char]);
+}
+
+/**
+ * Renders one route in a fresh browser context and returns the serialised DOM plus
+ * the same-origin links discovered on it. Context isolation keeps cookies and
+ * storage from leaking between routes. When a screenshot path is supplied the route
+ * is captured as an image instead of HTML.
+ */
+export async function renderRoute({ browser, origin, route, config, screenshotPath }) {
+  const context = await browser.newContext({
+    viewport: config.viewport,
+    storageState: config.storageState ?? undefined,
+    userAgent: config.userAgent ?? undefined,
+    ignoreHTTPSErrors: config.ignoreHTTPSErrors,
+    reducedMotion: config.freezeAnimations ? 'reduce' : 'no-preference',
+  });
+  const page = await context.newPage();
+  const pageErrors = [];
+  let inlineCssSkipped = [];
+  page.on('pageerror', (error) => pageErrors.push(error.message));
+
+  const metadataDefaults = config.metadata ? { base: config.base, ...config.metadata } : null;
+  if (metadataDefaults) {
+    await page.addInitScript((defaults) => {
+      window.__SNAPPY_META__ = defaults;
+    }, metadataDefaults);
+  }
+
+  const collector = createResourceCollector({
+    origin,
+    base: config.base,
+    allowedHosts: config.allowedHosts,
+    blockThirdParty: config.blockThirdParty,
+    collectJson: config.cacheAjaxRequests,
+    maxCachedBytes: config.maxCachedBytes,
+  });
+  await collector.install(page);
+  const tracker = trackNetwork(page);
+  try {
+    await page.goto(toServerUrl(route, config.base, origin), {
+      waitUntil: 'domcontentloaded',
+      timeout: config.timeout,
+    });
+    await settlePage(page, config, tracker);
+
+    if (config.captureRuntimeStyles) await captureRuntimeStyles(page);
+    if (config.captureFormState) await captureFormState(page);
+    if (config.inlineCss === true || config.inlineCss === 'inline') {
+      const inlined = await inlineStylesheets({ page, minifyCssOptions: config.minifyCss });
+      inlineCssSkipped = inlined.skipped;
+    }
+    await collector.settled();
+    const stateScript = await injectCapturedState(page, collector.json, {
+      externalScripts: config.externalScripts,
+      base: config.base,
+    });
+    if (metadataDefaults) await injectMetadataDefaults(page, metadataDefaults);
+    if (config.freezeAnimations) await freezeAnimations(page);
+    if (config.scrollToBottom) await scrollThroughPage(page, config);
+    await separateTextNodes(page);
+
+    const links = await collectLinks(page, config.base, origin);
+
+    if (screenshotPath) {
+      await fs.mkdir(path.dirname(screenshotPath), { recursive: true });
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+      return {
+        route,
+        links,
+        pageErrors,
+        collector,
+        inlineCssSkipped,
+        stateScript,
+        screenshot: true,
+      };
+    }
+
+    const html = await page.content();
+    return { route, html, links, pageErrors, collector, inlineCssSkipped, stateScript };
+  } finally {
+    tracker.stop();
+    await context.close();
+  }
+}
+
+/**
+ * Injects captured JSON responses as window.snapStore and anything the app exposes
+ * through window.snapSaveState, before the first script runs. The client can then
+ * replay the same data during hydration instead of re-fetching and mismatching.
+ *
+ * Inline by default. With externalScripts the same payload is written as a content-hashed
+ * same-origin file and referenced with src, so a strict script-src can allow it without
+ * unsafe-inline. Returns that file for the caller to write, or null when nothing was needed.
+ */
+async function injectCapturedState(page, cache, { externalScripts = false, base = '/' } = {}) {
+  const store = Object.fromEntries(cache);
+  return page.evaluate(
+    async ({ captured, external, basePath }) => {
+      const UNSAFE_CHARS = /[<>/\u2028\u2029]/g;
+      const ESCAPED_CHARS = {
+        '<': '\\u003C',
+        '>': '\\u003E',
+        '/': '\\u002F',
+        '\u2028': '\\u2028',
+        '\u2029': '\\u2029',
+      };
+      const escapeJson = (value) =>
+        JSON.stringify(value).replace(UNSAFE_CHARS, (char) => ESCAPED_CHARS[char]);
+
+      const parts = [];
+      if (Object.keys(captured).length > 0) {
+        parts.push(`window.snapStore=${escapeJson(captured)};`);
+      }
+      const state = typeof window.snapSaveState === 'function' ? window.snapSaveState() : null;
+      if (state && typeof state === 'object') {
+        for (const [key, value] of Object.entries(state)) {
+          // Both the key and the value are escaped: JSON.stringify alone leaves angle
+          // brackets and slashes intact, which would let a dynamic key close the tag.
+          parts.push(`window[${escapeJson(key)}]=${escapeJson(value)};`);
+        }
+      }
+      // Replacing an earlier injection keeps a rerun against already prerendered output
+      // byte-identical instead of stacking a second copy of the state script.
+      document.querySelectorAll('script[data-snappy-state]').forEach((script) => script.remove());
+      if (parts.length === 0) return null;
+
+      // Inserted before the first script so the state exists before the bundle runs.
+      const insert = (element) => {
+        const first = document.scripts[0];
+        if (first?.parentNode) first.parentNode.insertBefore(element, first);
+        else document.head.appendChild(element);
+      };
+
+      const script = document.createElement('script');
+      script.setAttribute('data-snappy-state', '');
+      const text = parts.join('');
+
+      if (!external) {
+        script.textContent = text;
+        insert(script);
+        return null;
+      }
+
+      const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+      const hash = [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('')
+        .slice(0, 12);
+      const file = `snappy/state-${hash}.js`;
+      const prefix = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+      script.setAttribute('src', `${prefix}/${file}`);
+      insert(script);
+      return { file, contents: text };
+    },
+    { captured: store, external: externalScripts === true, basePath: base },
+  );
+}
+
+/**
+ * Persists the metadata defaults into the document itself, so the head component reads the
+ * public site URL on the client too, not only while prerendering. Anything the head layer
+ * recorded about the tags it overwrote is merged in, and an earlier injection from a previous
+ * run is replaced so repeated runs stay identical. Written as inert JSON rather than an
+ * executable script, so a strict script-src applies to nothing here.
+ */
+async function injectMetadataDefaults(page, defaults) {
+  const payload = await page.evaluate((fallback) => {
+    document.querySelectorAll('script[data-snappy-meta]').forEach((script) => script.remove());
+    const current = typeof window === 'undefined' ? null : window.__SNAPPY_META__;
+    const recorded = typeof window === 'undefined' ? null : window.__snappyHeadOriginals;
+    const merged = { ...(current ?? fallback) };
+    if (recorded) merged.originals = recorded;
+    return Object.keys(merged).length > 0 ? merged : fallback;
+  }, defaults);
+  const element = escapeForScript(payload);
+  await page.evaluate((text) => {
+    const script = document.createElement('script');
+    script.setAttribute('type', 'application/json');
+    script.setAttribute('data-snappy-meta', '');
+    script.textContent = text;
+    const first = document.scripts[0];
+    if (first?.parentNode) first.parentNode.insertBefore(script, first);
+    else document.head.appendChild(script);
+  }, element);
+}
+
+/**
+ * Collects same-origin link targets from the rendered page and converts them to
+ * app-relative routes for the crawler. Off-origin links are ignored so external
+ * URLs can never be mistaken for routes and written into the output directory.
+ */
+async function collectLinks(page, base, origin) {
+  const hrefs = await page.$$eval('a[href]', (anchors) => anchors.map((anchor) => anchor.href));
+  const routes = [];
+  for (const href of hrefs) {
+    let parsed;
+    try {
+      parsed = new URL(href);
+    } catch {
+      continue;
+    }
+    if (parsed.origin !== origin) continue;
+    const route = toAppRoute(href, base);
+    if (route) routes.push(route);
+  }
+  return routes;
+}

package/src/core/resources.js

@@ -0,0 +1,113 @@
+import { blockThirdPartyRequests } from './blocking.js';
+
+/**
+ * Watches one page's network traffic. Records every third-party origin for the
+ * preconnect hints, records same-origin asset paths for the preload features,
+ * captures JSON bodies when the AJAX cache is enabled, and optionally aborts
+ * third-party requests when blocking is switched on.
+ */
+export function createResourceCollector({
+  origin,
+  base,
+  allowedHosts = [],
+  blockThirdParty = false,
+  collectJson = false,
+  maxCachedBytes = Number.POSITIVE_INFINITY,
+}) {
+  const thirdPartyOrigins = new Set();
+  const images = new Set();
+  const scripts = new Set();
+  const styles = new Set();
+  const json = new Map();
+  const pending = [];
+
+  return {
+    thirdPartyOrigins,
+    images,
+    scripts,
+    styles,
+    json,
+    // Waits for in-flight JSON body reads so the cache is complete before injection.
+    async settled() {
+      await Promise.allSettled(pending);
+    },
+    async install(page) {
+      page.on('request', (request) => {
+        const parsed = parseUrl(request.url());
+        if (!parsed) return;
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return;
+        if (parsed.origin === origin) return;
+        thirdPartyOrigins.add(parsed.origin);
+      });
+
+      if (blockThirdParty) {
+        await blockThirdPartyRequests(page, origin, allowedHosts);
+      }
+
+      page.on('response', (response) => {
+        const request = response.request();
+        const url = request.url();
+        const parsed = parseUrl(url);
+        if (!parsed || parsed.origin !== origin) return;
+        const path = toAppPath(url, base);
+        if (!path) return;
+
+        const resourceType = request.resourceType();
+        if (resourceType === 'image') images.add(path);
+        else if (resourceType === 'script') scripts.add(path);
+        else if (resourceType === 'stylesheet') styles.add(path);
+        else if (collectJson && isJson(response)) {
+          const length = Number(response.headers()['content-length'] ?? Number.NaN);
+          if (Number.isFinite(length) && length > maxCachedBytes) return;
+          const capture = response
+            .json()
+            .then((body) => {
+              if (withinCacheLimit(body, maxCachedBytes)) json.set(path, body);
+            })
+            .catch(() => {
+              // A truncated or aborted response is simply not cached.
+            });
+          pending.push(capture);
+        }
+      });
+    },
+  };
+}
+
+/**
+ * Converts an absolute URL to the app-relative path, keeping the query string so
+ * cached responses stay addressable by the same key the app used.
+ */
+export function toAppPath(url, base) {
+  const parsed = parseUrl(url);
+  if (!parsed) return null;
+  let pathname = parsed.pathname;
+  if (base !== '/') {
+    const prefix = base.slice(0, -1);
+    if (pathname === prefix) pathname = '/';
+    else if (pathname.startsWith(`${prefix}/`)) pathname = pathname.slice(prefix.length);
+    else return null;
+  }
+  return `${pathname}${parsed.search}`;
+}
+
+/**
+ * Reports whether a captured JSON body fits the cache budget, measured on the serialised
+ * text so the check matches how much is injected into the page.
+ */
+export function withinCacheLimit(body, maxBytes) {
+  return JSON.stringify(body).length <= maxBytes;
+}
+
+function parseUrl(url) {
+  try {
+    return new URL(url);
+  } catch {
+    return null;
+  }
+}
+
+function isJson(response) {
+  const contentType = response.headers()['content-type'] ?? '';
+  return contentType.includes('json');
+}