snappy-prerender 2.6.0-rc.3 → 2.7.0

package/src/core/config.js

@@ -11,7 +11,8 @@ export const MAX_DEFAULT_CONCURRENCY = 8;
 const LOG_LEVELS = ['silent', 'error', 'warn', 'info', 'debug'];
 const BROWSER_CHOICES = ['auto', 'chrome', 'msedge', 'chromium'];
 const INLINE_CSS_STRATEGIES = [false, true, 'inline', 'critical'];
-const CSP_MODES = ['off', 'strict'];
+const CSP_MODES = ['off', 'strict', 'hash'];
+const FRAMEWORK_CHOICES = ['auto', 'react', 'vue', 'svelte', 'preact'];
 const SAVE_AS_CHOICES = ['html', 'png', 'jpeg'];
 const CRITICAL_CSS_PRELOAD = ['body', 'media', 'swap', 'swap-high', 'swap-low', 'js', 'js-lazy'];
 const NULLABLE_KEYS = [
@@ -24,8 +25,13 @@ const NULLABLE_KEYS = [
   'userAgent',
   'destination',
   'browserDownloadHash',
+  'browserDownloadVersion',
   'url',
   'serveCmd',
+  'reportPath',
+  'routesFile',
+  'routesFromSitemap',
+  'transformHtml',
 ];
 const ARRAY_KEYS = [
   'include',
@@ -34,11 +40,15 @@ const ARRAY_KEYS = [
   'browserArgs',
   'ignoreForPreload',
   'removeAttributes',
+  'auditIgnoreLinks',
+  'routePriority',
+  'routeOverrides',
 ];
 
 export const DEFAULTS = Object.freeze({
   sourceDir: 'dist',
   destination: null,
+  cleanDestination: false,
   base: '/',
   include: ['/'],
   exclude: [],
@@ -59,6 +69,7 @@ export const DEFAULTS = Object.freeze({
   browser: 'auto',
   browserDownload: true,
   browserDownloadHash: null,
+  browserDownloadVersion: null,
   browserArgs: [],
   headless: true,
   ignoreHTTPSErrors: false,
@@ -84,16 +95,40 @@ export const DEFAULTS = Object.freeze({
   preloadImages: false,
   preloadManifest: false,
   sitemap: false,
+  imageSitemap: false,
   ignoreForPreload: ['service-worker.js'],
   cacheAjaxRequests: false,
   maxCachedBytes: 5 * 1024 * 1024,
   flatOutput: false,
   notFoundRoute: '/404',
+  audit: true,
+  failOnAuditError: false,
+  auditIgnoreLinks: [],
+  reportPath: null,
+  routePriority: [],
+  routeOverrides: [],
+  transformHtml: null,
+  routesFile: null,
+  routesFromSitemap: null,
+  preloadLinks: false,
+  retries: 0,
+  retryDelay: 500,
+  traceOnError: false,
+  framework: 'auto',
   verify: true,
   verifyChangedOnly: false,
   failOnHydrationError: false,
   failOnRerender: false,
   failOnPageError: false,
+  failOnEmptyPage: true,
+  failOnUndetected: false,
+  failOnVerificationError: false,
+  failOnConsoleError: false,
+  failOnFailedRequest: false,
+  failOnDuplicateContent: false,
+  stripBuildOriginMetadata: true,
+  failOnBuildOriginMetadata: false,
+  pruneStaleRoutes: false,
   metadata: null,
   failOnError: true,
   dryRun: false,
@@ -107,6 +142,22 @@ export const DEFAULTS = Object.freeze({
 // below decide what is allowed.
 const MULTI_TYPE_KEYS = new Set(['inlineCss', 'minifyHtml', 'minifyCss']);
 
+// Freeze the nested list defaults as well, so a consumer cannot mutate the defaults
+// used by every later run in the same process.
+for (const key of [
+  'include',
+  'exclude',
+  'allowedHosts',
+  'browserArgs',
+  'ignoreForPreload',
+  'removeAttributes',
+  'auditIgnoreLinks',
+  'routePriority',
+  'routeOverrides',
+]) {
+  Object.freeze(DEFAULTS[key]);
+}
+
 // Every boolean option is validated, derived from the defaults so a new flag cannot be
 // forgotten in a hand-maintained list.
 const BOOLEAN_KEYS = Object.entries(DEFAULTS)
@@ -126,18 +177,126 @@ export function resolveConfig(userOptions = {}) {
   config.concurrency =
     userOptions.concurrency ??
     Math.max(1, Math.min(os.availableParallelism(), MAX_DEFAULT_CONCURRENCY));
-  config.includeProvided = userOptions.include !== undefined;
+  config.includeProvided =
+    userOptions.include !== undefined &&
+    !(config.include.length === 1 && config.include[0] === '/');
   // The CSP dial decides the defaults for the pieces that can move. Explicit options still
   // win, so a project can take 'strict' and put one part back.
-  if (userOptions.externalScripts === undefined) config.externalScripts = config.csp === 'strict';
+  if (userOptions.externalScripts === undefined) {
+    config.externalScripts = config.csp === 'strict' || config.csp === 'hash';
+  }
   if (userOptions.criticalCssPreload === undefined) {
-    config.criticalCssPreload = config.csp === 'strict' ? false : 'media';
+    config.criticalCssPreload = config.csp === 'strict' || config.csp === 'hash' ? false : 'media';
   }
   config.warnings = [];
   validateConfig(config);
+  addConfigWarnings(config, userOptions);
   return config;
 }
 
+/**
+ * Reports options that do nothing in the current combination, so a build does not
+ * quietly skip a gate the caller believes is active.
+ */
+function addConfigWarnings(config, userOptions) {
+  const warn = (message) => config.warnings.push(message);
+  for (const key of Object.keys(userOptions)) {
+    if (!Object.hasOwn(DEFAULTS, key)) {
+      warn(`unknown option "${key}" is ignored; check the spelling`);
+    }
+  }
+  if (!config.verify) {
+    for (const key of [
+      'verifyChangedOnly',
+      'failOnHydrationError',
+      'failOnRerender',
+      'failOnUndetected',
+      'failOnVerificationError',
+    ]) {
+      if (config[key]) warn(`${key} has no effect because verify is false`);
+    }
+  }
+  if (config.verify && (config.serveCmd || config.saveAs !== 'html')) {
+    for (const key of [
+      'failOnHydrationError',
+      'failOnRerender',
+      'failOnUndetected',
+      'failOnVerificationError',
+    ]) {
+      if (config[key]) {
+        warn(
+          `${key} has no effect because hydration verification is skipped with ${config.serveCmd ? 'serveCmd' : `saveAs: '${config.saveAs}'`}`,
+        );
+      }
+    }
+    if (userOptions.framework !== undefined) {
+      warn(
+        `framework has no effect because hydration verification is skipped with ${config.serveCmd ? 'serveCmd' : `saveAs: '${config.saveAs}'`}`,
+      );
+    }
+  }
+  if (!config.verify && userOptions.framework !== undefined) {
+    warn('framework has no effect because verify is false');
+  }
+  if (!config.audit && config.failOnAuditError) {
+    warn('failOnAuditError has no effect because audit is false');
+  }
+  if (!config.audit && config.auditIgnoreLinks.length > 0) {
+    warn('auditIgnoreLinks has no effect because audit is false');
+  }
+  if (config.preloadLinks && config.saveAs !== 'html') {
+    warn(`preloadLinks has no effect when saveAs is '${config.saveAs}'`);
+  }
+  if (config.preloadLinks && config.removeScriptTags) {
+    warn('preloadLinks skips script hints because removeScriptTags strips every script');
+  }
+  if (config.imageSitemap && !config.sitemap) {
+    warn('imageSitemap has no effect because sitemap is false');
+  }
+  if (config.traceOnError && config.dryRun) {
+    warn('traceOnError has no effect in dry-run mode');
+  }
+  if (
+    userOptions.criticalCssPreload !== undefined &&
+    config.criticalCssPreload !== false &&
+    config.inlineCss !== 'critical'
+  ) {
+    warn('criticalCssPreload has no effect unless inlineCss is "critical"');
+  }
+  if (config.minifyCss && !config.minifyHtml && !config.inlineCss) {
+    warn('minifyCss has no effect unless minifyHtml or inlineCss is enabled');
+  }
+  if (config.allowedHosts.length > 0 && !config.blockThirdParty) {
+    warn('allowedHosts has no effect unless blockThirdParty is true');
+  }
+  if (config.csp === 'strict' && config.inlineCss) {
+    warn(
+      "csp controls script-src; inlineCss emits inline styles, which need style-src 'unsafe-inline' or hashes",
+    );
+  }
+  if (
+    (config.csp === 'strict' || config.csp === 'hash') &&
+    userOptions.criticalCssPreload !== undefined &&
+    config.criticalCssPreload !== false
+  ) {
+    warn(
+      "criticalCssPreload emits an inline onload handler that a script-src 'self' policy blocks",
+    );
+  }
+  if (config.removeStyleTags && config.inlineCss === 'critical') {
+    warn('removeStyleTags removes CSS-in-JS styles before critical CSS is extracted');
+  }
+  if (config.sitemap && config.saveAs !== 'html') {
+    warn(`sitemap has no effect when saveAs is '${config.saveAs}'`);
+  }
+  const metadataBase = config.metadata?.base;
+  if (metadataBase && metadataBase !== config.base) {
+    warn(
+      `metadata.base (${metadataBase}) differs from base (${config.base}); canonical, social URLs and routing will disagree`,
+    );
+  }
+}
+
 /**
  * Ensures the base path always carries a leading and trailing slash so route and
  * URL helpers can strip or append it without branching on user input shape.
@@ -200,9 +359,25 @@ export function validateConfig(config) {
   stringList(config.browserArgs, 'browserArgs');
   stringList(config.ignoreForPreload, 'ignoreForPreload');
   patternList(config.removeAttributes, 'removeAttributes');
-  for (const key of ['readyFlag', 'readySelector', 'waitFor', 'notFoundRoute']) nullableString(key);
-  for (const key of ['userAgent', 'destination']) nullableString(key);
+  patternList(config.auditIgnoreLinks, 'auditIgnoreLinks');
+  patternList(config.routePriority, 'routePriority');
+  for (const key of [
+    'readyFlag',
+    'readySelector',
+    'waitFor',
+    'notFoundRoute',
+    'reportPath',
+    'routesFile',
+    'routesFromSitemap',
+  ]) {
+    nullableString(key);
+  }
+  for (const key of ['userAgent', 'destination', 'browserDownloadVersion']) nullableString(key);
+  if (config.transformHtml !== null && typeof config.transformHtml !== 'function') {
+    throw new TypeError('transformHtml must be a function or null');
+  }
   for (const key of BOOLEAN_KEYS) booleanOption(key);
+  validateRouteOverrides(config.routeOverrides);
 
   if (config.browserDownloadHash !== null && !/^[a-f0-9]{64}$/i.test(config.browserDownloadHash)) {
     throw new TypeError('browserDownloadHash must be a 64 character SHA-256 hex digest');
@@ -228,6 +403,12 @@ export function validateConfig(config) {
   if (config.maxRoutes !== null && (!Number.isInteger(config.maxRoutes) || config.maxRoutes < 1)) {
     throw new TypeError('maxRoutes must be null or a positive integer');
   }
+  if (!Number.isInteger(config.retries) || config.retries < 0) {
+    throw new TypeError('retries must be a non-negative integer');
+  }
+  if (!Number.isFinite(config.retryDelay) || config.retryDelay <= 0) {
+    throw new TypeError('retryDelay must be a positive number of milliseconds');
+  }
   if (!Number.isFinite(config.maxCachedBytes) || config.maxCachedBytes <= 0) {
     throw new TypeError('maxCachedBytes must be a positive number of bytes');
   }
@@ -244,6 +425,9 @@ export function validateConfig(config) {
       `browser must be one of: ${BROWSER_CHOICES.join(', ')} or a path to an executable`,
     );
   }
+  if (!FRAMEWORK_CHOICES.includes(config.framework)) {
+    throw new TypeError(`framework must be one of: ${FRAMEWORK_CHOICES.join(', ')}`);
+  }
   if (config.storageState !== null) {
     if (typeof config.storageState !== 'string' || !fs.existsSync(config.storageState)) {
       throw new TypeError('storageState must point to an existing Playwright storage state file');
@@ -257,6 +441,14 @@ export function validateConfig(config) {
   if (config.url !== null && !/^https?:\/\//.test(config.url)) {
     throw new TypeError('url must be an absolute http(s) URL');
   }
+  if (config.serveCmd !== null && config.url) {
+    const parsed = new URL(config.url);
+    if (parsed.pathname !== '/' && parsed.pathname !== '') {
+      throw new TypeError(
+        'url must be an origin without a path when serveCmd is used; set base for a sub-path deployment',
+      );
+    }
+  }
   if (!INLINE_CSS_STRATEGIES.includes(config.inlineCss)) {
     throw new TypeError("inlineCss must be false, true, 'inline' or 'critical'");
   }
@@ -281,12 +473,62 @@ export function validateConfig(config) {
   if (!SAVE_AS_CHOICES.includes(config.saveAs)) {
     throw new TypeError(`saveAs must be one of: ${SAVE_AS_CHOICES.join(', ')}`);
   }
+  if (config.removeStyleTags && (config.inlineCss === true || config.inlineCss === 'inline')) {
+    throw new TypeError(
+      "removeStyleTags cannot be combined with inlineCss 'inline' or true: it would strip the CSS the inline step just added",
+    );
+  }
   validateMetadata(config);
   if (config.sitemap && !config.metadata?.siteUrl) {
     throw new TypeError('sitemap needs metadata.siteUrl so the sitemap can list absolute URLs');
   }
 }
 
+// Per-route overrides may only change the settings that make sense for one route.
+const ROUTE_OVERRIDE_KEYS = new Set([
+  'match',
+  'timeout',
+  'waitFor',
+  'readySelector',
+  'readyFlag',
+  'crawl',
+  'storageState',
+]);
+
+/**
+ * Validates per-route overrides. Matching patterns stay strings or RegExp; every
+ * override key is checked so a typo cannot silently leave the base config in place.
+ */
+function validateRouteOverrides(overrides) {
+  for (const override of overrides) {
+    if (typeof override !== 'object' || override === null || Array.isArray(override)) {
+      throw new TypeError('routeOverrides entries must be objects');
+    }
+    for (const key of Object.keys(override)) {
+      if (!ROUTE_OVERRIDE_KEYS.has(key)) {
+        throw new TypeError(`routeOverrides.${key} is not a recognised option`);
+      }
+    }
+    if (!(typeof override.match === 'string' || override.match instanceof RegExp)) {
+      throw new TypeError('routeOverrides entries need a string or RegExp match');
+    }
+    if (override.timeout !== undefined) {
+      if (!Number.isFinite(override.timeout) || override.timeout <= 0) {
+        throw new TypeError('routeOverrides.timeout must be a positive number of milliseconds');
+      }
+    }
+    for (const key of ['waitFor', 'readySelector', 'readyFlag', 'storageState']) {
+      const value = override[key];
+      if (value !== undefined && typeof value !== 'string') {
+        throw new TypeError(`routeOverrides.${key} must be a string`);
+      }
+    }
+    if (override.crawl !== undefined && typeof override.crawl !== 'boolean') {
+      throw new TypeError('routeOverrides.crawl must be a boolean');
+    }
+  }
+}
+
 // The metadata keys the head component reads, so a typo is reported instead of ignored.
 const METADATA_KEYS = new Set([
   'siteUrl',
@@ -319,6 +561,14 @@ function validateMetadata(config) {
   if (metadata.siteUrl && !/^https?:\/\//.test(metadata.siteUrl)) {
     throw new TypeError('metadata.siteUrl must be an absolute http(s) URL');
   }
+  if (metadata.siteUrl) {
+    const parsed = new URL(metadata.siteUrl);
+    if (parsed.pathname !== '/' && parsed.pathname !== '') {
+      throw new TypeError(
+        'metadata.siteUrl must be an origin without a path; set base for a sub-path deployment',
+      );
+    }
+  }
   if (metadata.base && !metadata.base.startsWith('/')) {
     throw new TypeError('metadata.base must start with a slash, for example /app/');
   }

package/src/core/crawl.js

@@ -0,0 +1,300 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { renderRoute } from './render.js';
+import { resolveRouteConfig } from './route-config.js';
+import {
+  crawlRoots,
+  filterRoutes,
+  isIncludedRoute,
+  matchesPattern,
+  normaliseRoute,
+  withinDepth,
+} from './routes.js';
+import { createPool, mapLimit } from './scheduler.js';
+
+/**
+ * Runs the crawl and render pool. Each rendered page contributes its output, any new
+ * same-origin routes, and the resources recorded for the link-hint features.
+ */
+export async function renderAllRoutes({
+  browser,
+  server,
+  config,
+  log,
+  report,
+  outputDir,
+  sourceSeeds = [],
+}) {
+  const visited = new Set();
+  const scheduled = new Set();
+  const rendered = new Map();
+  const cap = config.maxRoutes ?? Number.POSITIVE_INFINITY;
+  let nextOrder = 0;
+
+  // Queues routes up to maxRoutes, recording exactly which candidates did not fit.
+  // A seed used only to reach wildcard routes is given output: false and is rendered
+  // for its links without being written.
+  const accept = (routes, outputFor = () => true) => {
+    const accepted = [];
+    const dropped = [];
+    for (const route of routes) {
+      if (scheduled.has(route)) continue;
+      if (scheduled.size >= cap) {
+        dropped.push(route);
+        continue;
+      }
+      scheduled.add(route);
+      accepted.push({ route, output: outputFor(route), order: nextOrder });
+      nextOrder += 1;
+    }
+    if (dropped.length > 0) {
+      const previous = report.truncated?.droppedRoutes ?? [];
+      report.truncated = {
+        limit: config.maxRoutes,
+        routes: scheduled.size,
+        droppedRoutes: [...new Set([...previous, ...dropped])].sort(),
+      };
+    }
+    return accepted;
+  };
+
+  const renderOne = async ({ route, output, depth = 0, order = null }) => {
+    if (visited.has(route)) return null;
+    visited.add(route);
+    log.debug(`rendering ${route}${output ? '' : ' as a crawl seed'}`);
+    const routeConfig = resolveRouteConfig(config, route);
+    const result = await renderWithRetries({
+      browser,
+      server,
+      route,
+      routeConfig,
+      config,
+      log,
+      report,
+      outputDir,
+      screenshot: config.saveAs !== 'html',
+    });
+    if (!result) return null;
+    result.depth = depth;
+    result.order = order;
+    try {
+      const notFoundRoute = config.notFoundRoute ? normaliseRoute(config.notFoundRoute) : null;
+      const isNotFoundRoute = notFoundRoute !== null && route === notFoundRoute;
+      if (result.statusCode === 404 && !isNotFoundRoute) {
+        report.errors.push({ route, message: 'returned 404' });
+        log.error(`  route ${route} returned 404`);
+        return null;
+      }
+      if (isNotFoundRoute) {
+        result.notFound = true;
+        if (!report.notFoundRoutes.includes(route)) report.notFoundRoutes.push(route);
+        if (result.statusCode !== null && result.statusCode !== 404) {
+          log.warn(`  ignored unknown prerender-status-code ${result.statusCode} on ${route}`);
+        }
+      } else if (result.statusCode !== null) {
+        log.warn(`  ignored unknown prerender-status-code ${result.statusCode} on ${route}`);
+      }
+      if (output && result.empty) {
+        report.emptyPages.push(route);
+        if (config.failOnEmptyPage) {
+          report.errors.push({ route, message: 'rendered an empty page' });
+          log.error(`  empty page ${route}: no app content was found`);
+          return null;
+        }
+        log.warn(`  empty page ${route}: no app content was found`);
+      }
+      if (output) {
+        rendered.set(route, result);
+        report.routes.push(route);
+        for (const to of result.links) report.links.push({ from: route, to });
+      }
+      for (const message of result.pageErrors) {
+        report.pageErrors.push({ route, message });
+        log.warn(`  page error on ${route}: ${message}`);
+      }
+      for (const message of result.consoleErrors) {
+        report.consoleErrors.push({ route, message });
+      }
+      if (result.consoleErrors.length > 0) {
+        log.debug(`  console error on ${route}: ${result.consoleErrors[0]}`);
+        if (config.failOnConsoleError) {
+          report.errors.push({ route, message: `console error: ${result.consoleErrors[0]}` });
+        }
+      }
+      for (const failure of result.failedRequests) {
+        report.failedRequests.push({ route, ...failure });
+        const detail = failure.status ? `HTTP ${failure.status}` : failure.error;
+        log.warn(`  failed request on ${route}: ${failure.url} (${detail})`);
+      }
+      if (result.failedRequests.length > 0 && config.failOnFailedRequest) {
+        const first = result.failedRequests[0];
+        report.errors.push({
+          route,
+          message: `failed request: ${first.url}${first.status ? ` (HTTP ${first.status})` : ''}`,
+        });
+      }
+      return { result, routeConfig };
+    } catch (error) {
+      report.errors.push({ route, message: error.message });
+      log.error(`  failed ${route}: ${error.message}`);
+      return null;
+    }
+  };
+
+  const outputFor = (route) => !config.includeProvided || isIncludedRoute(route, config.include);
+  const candidates = [];
+  if (sourceSeeds.length > 0) candidates.push(...sourceSeeds);
+  if (sourceSeeds.length === 0 || config.includeProvided) {
+    candidates.push(...crawlRoots(config));
+  }
+  const roots = accept([...new Set(sortRoutes(candidates, config))], outputFor);
+
+  const deterministic = config.maxRoutes !== null || config.routePriority.length > 0;
+  if (deterministic) {
+    await renderWaves({ config, accept, renderOne, roots, report, log });
+  } else {
+    const pool = createPool({
+      concurrency: config.concurrency,
+      handler: async ({ route, depth, output, order }) => {
+        const renderedRoute = await renderOne({ route, output, depth, order });
+        if (!renderedRoute) return;
+        const { result, routeConfig } = renderedRoute;
+        if (routeConfig.crawl && withinDepth(depth + 1, routeConfig.maxDepth)) {
+          const discovered = filterRoutes(result.links, {
+            include: config.includeProvided ? config.include : [],
+            exclude: config.exclude,
+          }).filter((candidate) => !scheduled.has(candidate));
+          const accepted = accept(sortRoutes(discovered, config));
+          pool.push(accepted.map((item) => ({ ...item, depth: depth + 1 })));
+        }
+      },
+    });
+    pool.push(roots.map((item) => ({ ...item, depth: 0 })));
+    const { errors } = await pool.run();
+    for (const { item, error } of errors) {
+      report.errors.push({ route: item.route, message: error.message });
+      log.error(`  pool error on ${item.route}: ${error.message}`);
+    }
+  }
+  return rendered;
+}
+
+/**
+ * Renders one route with the configured retry policy. A retryable failure is retried
+ * after retryDelay; the final failure records the attempt count and, when traceOnError
+ * is on, a Playwright trace written under the output directory.
+ */
+async function renderWithRetries({
+  browser,
+  server,
+  route,
+  routeConfig,
+  config,
+  log,
+  report,
+  outputDir,
+  screenshot,
+}) {
+  const attempts = config.retries + 1;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const traceFile =
+      config.traceOnError && !config.dryRun && attempt === attempts
+        ? await prepareTraceFile(outputDir, route, attempt)
+        : null;
+    try {
+      const result = await renderRoute({
+        browser,
+        origin: server.origin,
+        route,
+        config: routeConfig,
+        screenshot,
+        traceFile,
+      });
+      if (attempt > 1) log.info(`  ${route}: succeeded on attempt ${attempt}`);
+      result.attempts = attempt;
+      return result;
+    } catch (error) {
+      if (error.tracePath) {
+        report.traces.push({ route, attempt, file: error.tracePath });
+        log.warn(`  trace for ${route}: ${error.tracePath}`);
+      }
+      if (error.retryable !== false && attempt < attempts) {
+        log.warn(
+          `  attempt ${attempt}/${attempts} failed for ${route}: ${error.message}; retrying`,
+        );
+        await delay(config.retryDelay);
+        continue;
+      }
+      report.errors.push({ route, message: error.message, attempts: attempt });
+      log.error(`  failed ${route} after ${attempt} attempt(s): ${error.message}`);
+      return null;
+    }
+  }
+  return null;
+}
+
+// Creates the trace directory and returns the archive path for one failed attempt.
+async function prepareTraceFile(outputDir, route, attempt) {
+  const slug = route
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/[^a-z0-9._-]+/gi, '-')
+    .toLowerCase();
+  const dir = path.join(outputDir, 'snappy-traces');
+  await fs.mkdir(dir, { recursive: true });
+  return path.join(dir, `${slug || 'root'}-${attempt}.zip`);
+}
+
+// Waits between retry attempts.
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Deterministic BFS crawl used when maxRoutes or routePriority is set. Each depth level
+ * is sorted, capped and rendered as a wave, so the accepted set never depends on which
+ * concurrent page happened to finish first.
+ */
+async function renderWaves({ config, accept, renderOne, roots, report, log }) {
+  let frontier = roots.map((item) => ({ ...item, depth: 0 }));
+  let depth = 0;
+  while (frontier.length > 0) {
+    const { results, errors } = await mapLimit(frontier, config.concurrency, async (item) => ({
+      item,
+      rendered: await renderOne(item),
+    }));
+    for (const { item, error } of errors) {
+      report.errors.push({ route: item.route, message: error.message });
+      log.error(`  pool error on ${item.route}: ${error.message}`);
+    }
+    const discovered = [];
+    for (const { rendered: renderedRoute } of results) {
+      if (!renderedRoute) continue;
+      if (!renderedRoute.routeConfig.crawl) continue;
+      if (!withinDepth(depth + 1, config.maxDepth)) continue;
+      discovered.push(
+        ...filterRoutes(renderedRoute.result.links, {
+          include: config.includeProvided ? config.include : [],
+          exclude: config.exclude,
+        }),
+      );
+    }
+    if (!withinDepth(depth + 1, config.maxDepth)) break;
+    const next = accept(sortRoutes(discovered, config));
+    frontier = next.map((item) => ({ ...item, depth: depth + 1 }));
+    depth += 1;
+  }
+}
+
+// Orders routes by routePriority first, then by path for a stable frontier.
+function sortRoutes(routes, config) {
+  return [...routes].sort((a, b) => sortRoute(a, b, config));
+}
+
+function sortRoute(a, b, config) {
+  const rank = (route) => {
+    const index = config.routePriority.findIndex((pattern) => matchesPattern(route, pattern));
+    return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+  };
+  const difference = rank(a) - rank(b);
+  return difference === 0 ? a.localeCompare(b) : difference;
+}