snappy-prerender 2.6.0 → 2.8.0

package/README.md

@@ -1,6 +1,12 @@
+<p align="center">
+  <img src="assets/snappy-logo.png" width="150" alt="snappy-prerender logo">
+</p>
+
 # snappy-prerender
 
-**Prerender your single-page app without rewriting it.** Point it at your build output, and every route is rendered in a real browser and written to disk as static HTML — content, titles, meta tags, canonical links and Open Graph tags included. Search engines and social crawlers get the full page; your users get the same app they had before.
+Render a single-page app to static HTML at build time. Point the tool at the build output; it renders each route in Chrome, writes one HTML file per route, and leaves the app unchanged. The output includes page content, titles, meta tags, canonical links and Open Graph tags.
+
+Version 2.8 adds deterministic clock and randomness controls, locale and hreflang generation, cookie/localStorage SEO locale seeding, and a client-side head layer that replaces React Helmet or React Helmet Async for prerendered apps.
 
 [![npm](https://img.shields.io/npm/v/snappy-prerender.svg)](https://www.npmjs.com/package/snappy-prerender)
 [![npm downloads](https://img.shields.io/npm/dm/snappy-prerender.svg)](https://www.npmjs.com/package/snappy-prerender)
@@ -9,15 +15,15 @@
 
 Package page: [npmjs.com/package/snappy-prerender](https://www.npmjs.com/package/snappy-prerender). Install with `npm install --save-dev snappy-prerender`. Release notes are in [CHANGELOG.md](CHANGELOG.md).
 
-- **No SSR entry, no framework migration, no app changes.** If it builds to a `dist` directory, it can be prerendered.
-- **React 16.8, 17, 18 and 19, Vite 6/7/8, or any static build.**
-- **Inspired by [react-snap](https://github.com/stereobooster/react-snap)** and rebuilt from scratch for current toolchains: a browser-based prerenderer with a hydration report attached, not another SSR framework.
+- No SSR entry, framework migration or app changes. If the app builds to a directory, it can be prerendered.
+- React 16.8, 17, 18 and 19, Vite 6/7/8, or any static build.
+- Based on the react-snap approach, reimplemented for current toolchains with Playwright and a hydration check.
 
 ## Who this is for
 
-**Use it when** your app renders in the browser and you want the crawler-visible HTML to match: Create React App, Vite + React, plain SPAs, CMS-driven sites, marketing pages behind a client router.
+Use it for client-rendered apps that need crawler-visible HTML: Create React App, Vite + React, other SPAs, CMS-backed sites and client-routed marketing pages.
 
-**Skip it when** you already render HTML on the server — Next.js, Remix, Astro and friends do not need prerendering, and this tool will not improve on what they ship.
+Do not use it for apps that already render HTML on the server, such as Next.js, Remix or Astro.
 
 ## Quick start
 
@@ -81,41 +87,41 @@ if (!report.ok) {
 }
 ```
 
-## Inspired by react-snap
+## Based on react-snap
 
-react-snap proved the idea that makes this approach attractive: you do not need a server, a second renderer or a rewrite to give crawlers real HTML — you need a browser, a router and a build step. It carried a generation of webpack-era SPAs and has been unmaintained since 2019.
+[react-snap](https://github.com/stereobooster/react-snap) showed that a browser and a build step can produce crawler-readable HTML without a server renderer. It has been unmaintained since 2019.
 
-`snappy-prerender` is a fresh implementation of that idea for current toolchains. It is not a fork: no react-snap code was reused. What changed is the machinery around the same core trick — Playwright instead of an old Puppeteer, Chrome or Edge from the machine you already have, Vite plugin support, a head and metadata layer with client-side updates, hydration verification that tells you how each page booted, and option names that say what they do.
+snappy-prerender reimplements that approach; no react-snap code is reused. It uses Playwright, resolves an installed Chrome or Edge, supports Vite, ships a head layer, and verifies hydration.
 
-If you are moving over, the [differences and migration table](#differences-from-react-snap) maps every option.
+If you are moving over, [Migrating from react-snap](docs/react-snap-migration.md) maps the options.
 
 ## What you get
 
 | | |
 | --- | --- |
-| **Static HTML per route** | `route/index.html` (or `route.html` with `flatOutput`), plus a `404.html` from your not-found route. Identical files are left untouched, so rebuilds and CI caches stay stable. |
-| **Head and metadata** | A `Head` component writes per-route title, description, robots, canonical, Open Graph and Twitter tags — and keeps updating them on client-side navigation, exactly like a page-per-request site. |
-| **Hydration report** | Every written page is reloaded with the real bundle and reported as `hydrated`, `re-rendered`, `undetected` or `unknown`, with React mismatch messages per route. |
-| **A ready contract** | `window.__prerenderReady`, a selector, or network quiescence — whichever fits your app. |
-| **Output optimisation** | Critical CSS, HTML/CSS minification, preconnect hints, image preload, a preload manifest, script and style surgery. |
-| **CSS-in-JS support** | CSSOM-only styles (emotion, styled-components in speedy mode) and constructable stylesheets are folded back into the HTML. |
-| **Ajax state replay** | Captured JSON and `window.snapSaveState()` are injected before the first script, so hydration sees the same data the prerender did. |
-| **Guided setup** | `snappy-prerender init` asks the handful of questions that matter — build directory, base path, routes, site URL, site name, title template — and writes a `snappy.config.js` with your answers, detected from the project where it can. |
-| **Any static build** | Base paths, `serveCmd` for apps that need a live API, screenshots, dry runs, bounded concurrency. |
+| **Static HTML per route** | `route/index.html` (or `route.html` with `flatOutput`), plus `404.html`. Identical files are left untouched. |
+| **Head and metadata** | Per-route title, description, robots, canonical, Open Graph and Twitter tags, updated on client-side navigation. |
+| **Hydration report** | Each route is reloaded with the real bundle and reported as `hydrated`, `re-rendered`, `undetected` or `unknown`, with mismatch messages. |
+| **Ready contract** | `window.__prerenderReady`, a selector, or network quiescence. |
+| **Output optimisation** | Critical CSS, HTML/CSS minification, preconnect hints, image preload, a preload manifest, script and style removal. |
+| **CSS-in-JS support** | CSSOM-only styles and constructable stylesheets are written back into the HTML. |
+| **Ajax state replay** | Captured JSON and `window.snapSaveState()` are injected before the first script. |
+| **Guided setup** | `snappy-prerender init` writes a `snappy.config.js` from the project settings and a few answers. |
+| **Any static build** | Base paths, `serveCmd`, screenshots, dry runs and bounded concurrency. |
 
 ## How it works
 
-1. Serves the built output on an ephemeral loopback port (or copies it to `destination` first).
-2. Crawls same-origin links from the seed routes, rendering each page in a fresh browser context.
-3. Waits for the app to settle: ready contract, quiet network, fonts, two animation frames.
-4. Freezes CSS animations, optionally blocks third-party requests, records the resources the page used, and reconciles any head tags the app rendered.
-5. Serialises the DOM, then post-processes it: removes the freeze style and `data-prerender-remove` elements, de-duplicates head styles, drops dead blob stylesheets, adds link hints, optionally inlines CSS, removes or marks scripts, optionally minifies, and notes metadata that points at the build server or ships more than one title.
-6. Writes `route/index.html` (or a screenshot), leaving identical files untouched.
-7. Reloads every written file with the real client bundle, reports React hydration errors, and records whether each route hydrated or re-rendered.
+1. Serves the built output on an ephemeral loopback port, or copies it to `destination`.
+2. Crawls same-origin links from the seed routes in a fresh browser context per page.
+3. Waits for the ready contract, quiet network, fonts and two animation frames.
+4. Freezes CSS animations, optionally blocks third-party requests, records resources and reconciles head tags.
+5. Serialises the DOM and post-processes it: removes freeze styles and `data-prerender-remove` elements, de-duplicates head styles, drops dead blob stylesheets, adds link hints, optionally inlines CSS, removes or marks scripts, optionally minifies, and records metadata issues.
+6. Writes `route/index.html` or a screenshot, leaving identical files untouched.
+7. Reloads each written file with the client bundle and reports hydration errors and boot mode.
 
 ## Head and metadata
 
-Per-route titles, descriptions, canonical links and Open Graph/Twitter tags come from a `Head` component the package ships. It writes into the document head while the route is mounted and reconciles on every render, so client-side navigation updates the head exactly like a site that renders a page per request — and the prerenderer captures whatever is there, because the head is part of the page it serialises.
+Per-route titles, descriptions, canonical links and Open Graph/Twitter tags come from the package's `Head` component. It updates the document head on every render, including client-side navigation, and the prerenderer captures the result.
 
 ```jsx
 import { Head } from 'snappy-prerender/head';
@@ -127,11 +133,18 @@ import { Head } from 'snappy-prerender/head';
   type="article"
   locale="en_GB"
   robots="index,follow"
+  lang="en"
+  dir="ltr"
+  structuredData={{ '@context': 'https://schema.org', '@type': 'WebPage', name: 'Awards' }}
+  alternates={[
+    { hreflang: 'en', href: '/awards' },
+    { hreflang: 'x-default', href: '/awards' },
+  ]}
   extra={[{ name: 'keywords', content: 'polymer' }, { rel: 'alternate', href: '/feed.xml' }]}
 />
 ```
 
-Project-wide values come from the `metadata` option. The prerenderer injects them into every page, so the component composes absolute URLs from the public site rather than the build server:
+Project-wide values come from the `metadata` option. The prerenderer injects them into every page, so the component builds absolute URLs from the public site instead of the build server:
 
 ```js
 snappy({
@@ -139,52 +152,223 @@ snappy({
     siteUrl: 'https://example.com',
     siteName: 'Example',
     titleTemplate: '%s | Example',
+    defaultTitle: 'Example',
     defaultImage: '/share.png',
     trailingSlash: 'never', // 'preserve' | 'always' | 'never'
   },
 });
 ```
 
+### Replacing React Helmet or React Helmet Async
+
+For a client-rendered app, `Head` covers the tag and attribute surface React Helmet and React Helmet Async expose on the client. An app does not need either package:
+
+```jsx
+<Head
+  title="Awards"
+  titleAttributes={{ itemProp: 'name' }}
+  htmlAttributes={{ className: 'theme-dark', 'data-theme': 'dark' }}
+  bodyAttributes={{ className: 'root', 'data-scroll': 'locked' }}
+  images={['/share/awards.png', '/share/awards-square.png']}
+  alternateLocales={['en_GB', 'fr_FR']}
+  tags={[
+    { tag: 'base', attrs: { href: '/' } },
+    { tag: 'script', attrs: { src: '/analytics.js', async: true } },
+    { tag: 'script', attrs: { type: 'application/json' }, text: '{"feature":true}' },
+    { tag: 'style', attrs: { media: 'screen' }, text: 'body { color: #111 }' },
+    { tag: 'noscript', html: '<img src="/pixel.png" alt="">' },
+  ]}
+  onChangeClientState={(state, added, removed) => {}}
+/>
+```
+
+`Head` does not accept JSX children; use `tags`, `extra` or the props below for every value.
+
+`tags` accepts `script`, `style`, `noscript` and `base`:
+
+- `attrs` takes arbitrary attributes. `true` emits an empty attribute; `false`, `null` and `undefined` omit it. `className`, `htmlFor`, `httpEquiv` and the other React spellings map to their DOM names.
+- `text` sets `textContent` for `script`, `style` and `noscript`. A closing-tag sequence inside script or style text is escaped, so the value cannot terminate its own element.
+- `html` sets trusted `innerHTML` on `noscript` only. Never pass untrusted input.
+- `key` gives a tag an explicit identity. Without one, external scripts key by `src` and inline tags key per mounted `Head`, so several scripts or styles survive together.
+- `base` is a singleton; the last mounted `Head` that sets one wins.
+
+`htmlAttributes`, `bodyAttributes` and `titleAttributes` write arbitrary attributes on the document element, body and generated title. Values the document already had are restored when no Head wants them, including after client-side navigation and after a prerendered page hydrates. `lang` and `dir` remain shortcuts; an entry in `htmlAttributes` wins when both are supplied.
+
+`defaultTitle` fills the document title only when no mounted Head supplied a real `title`. It is not run through `titleTemplate`. `images` emits one `og:image` per URL and uses the first for `twitter:image`. `alternateLocales` emits one `og:locale:alternate` per value. Both keep every value through the merge.
+
+`extra` stays the escape hatch for additional `meta` and `link` tags. Set `duplicates: true` on repeated same-name metas (for example `article:tag`) so each value keeps its own tag; an explicit `key` still works.
+
+`onChangeClientState(state, added, removed)` runs after a real DOM change, not on every render. `state` groups the merged entries into `title`, `meta`, `link`, `script`, `style`, `noscript`, `base`, `htmlAttributes`, `bodyAttributes` and `titleAttributes`. `added` and `removed` are entry descriptors with `kind`, `key` and their value.
+
+React 19 hoists native `<title>`, `<meta>` and `<link>` elements. `Head` adopts an existing tag with the same identity and updates it instead of adding a second one. Use one owner per tag: either React 19 native metadata or `Head`, not both for the same tag. The run still warns when a page ships more than one `<title>`.
+
+The `snappy-prerender/head` entry is plain JavaScript with JSDoc types for `HeadProps`, `HeadTag`, `HeadAttributes`, `HeadChange` and the imperative API. It ships no TypeScript files.
+
+This is a client-side head manager. It deliberately has no `HelmetProvider`, `helmetContext`, `HelmetData`, `renderStatic()`, streaming or server rendering API; the prerenderer renders the real app in a browser and captures the live head.
+
 What it emits, per route: `title` (with the template applied unless the title already carries its suffix), `meta[name=description]`, `meta[name=robots]`, `link[rel=canonical]`, `og:title`, `og:description`, `og:type`, `og:url`, `og:image`, `og:site_name`, `og:locale`, and `twitter:card` / `twitter:title` / `twitter:description` / `twitter:image`. Switch a family off with `openGraph: false` or `twitter: false`, and skip the canonical with `canonical: false`.
 
-Rules worth knowing:
-
-- `metadata` values are defaults; a `Head`'s own props win. When several Heads render, the later one in render order wins per tag, so a page overrides its layout.
-- Tags are matched on the attribute a crawler reads, so an existing tag is updated in place rather than duplicated. Two tags with the same identity already in the document — a `name`, `property`, `http-equiv` or `rel` match — are reduced to one.
-- A tag the head layer generated carries `data-snappy-head-created` beside `data-snappy-head`, so a later page load can tell it apart from one the app wrote.
-- When no Head wants a tag any more, a generated one is removed and one the app wrote is restored to the value it had before the head layer touched it. That original is recorded into the page during prerendering, so a route change brings the template's fallback metadata back.
-- The component renders nothing, so it cannot affect hydration of the page content.
-- The title template applies unless the title already ends with the template's fixed part, or is the site name itself, so a title composed by hand is never suffixed twice.
-- Absolute URLs are required for `og:url`, `og:image` and canonical. `metadata.siteUrl` must be an origin (no path); put a sub-path deployment in `base`. Without `siteUrl`, URLs that fall back to the build server are removed from the output by default (`stripBuildOriginMetadata: true`) and the run warns. The `trailingSlash` convention applies to page URLs only; asset URLs are left alone. Canonical, social and sitemap URLs share one page-path policy: directory output keeps its slash, flat output stays extensionless, and an explicit `trailingSlash` wins.
-- `metadata.base` overrides the base path used for absolute URLs and defaults to the `base` option.
-- On React 19, React hoists `<title>` and `<meta>` rendered in JSX and leaves an existing template tag alone, so a page can end up with two titles. Use React's native metadata or this component, not both; the run warns when the output carries more than one `<title>`.
+Rules:
+- `metadata` values are defaults; a `Head` prop wins. When several Heads render, the last one wins per tag.
+- Tags are matched by the attribute a crawler reads, so existing tags are updated instead of duplicated. Tags that may legitimately repeat keep a value-specific identity, so multiple images, alternate locales, scripts and styles survive.
+- `defaultTitle` is used only when no mounted Head supplied a title, and it is never run through `titleTemplate`.
+- Generated tags carry `data-snappy-head-created` beside `data-snappy-head`, so a later page load can tell them from tags the app wrote.
+- When no Head wants a tag, a generated one is removed and an app-written one is restored to its previous value. That original is recorded in the page during prerendering, together with the original html, body and title attributes.
+- The component renders nothing, so it does not affect hydration of page content.
+- The title template is skipped when the title already ends with its fixed part, or is the site name, so a hand-built title is not suffixed twice.
+- `structuredData` emits `<script type="application/ld+json">` for one object or an array, keyed per mounted `Head`. Values are escaped; add `@context` when needed.
+- `lang` and `dir` are written on `<html>`. Later Heads win, and the original values return when no Head wants them. `htmlAttributes` covers every other document attribute, and `bodyAttributes` / `titleAttributes` do the same for body and title.
+- `alternateLocales` emits `og:locale:alternate` for each listed locale.
+- `alternates` emits `<link rel="alternate" hreflang="...">` with absolute URLs using the same `siteUrl`/`base`/`trailingSlash` policy as canonical links. The same alternates feed sitemap `xhtml:link` entries.
+- `og:url`, `og:image` and canonical need absolute URLs. `metadata.siteUrl` must be an origin; put a sub-path deployment in `base`. Without `siteUrl`, build-server URLs are removed by default and the run warns. `trailingSlash` applies to page URLs only. Canonical, social and sitemap URLs share the page-path policy: directory output keeps its slash, flat output stays extensionless, and `trailingSlash` wins.
+- `metadata.base` overrides the base path for absolute URLs and defaults to `base`.
+- On React 19, React also hoists `<title>`, `<meta>` and `<link>` from JSX. `Head` adopts a matching hoisted `<meta>` or `<link>` and updates it in place. A hoisted `<title>` that already has the Head text is left untouched so React can remove it on navigation; older template titles are removed so the written page has one document title. `titleAttributes` apply only when `Head` owns the title. Use one metadata system; the run warns when a page still ships more than one `<title>`.
 - Every metadata value has a CLI flag: `--metadata-site-url`, `--metadata-site-name`, `--metadata-title-template`, `--metadata-default-image`, `--metadata-trailing-slash`.
-- `react` is an optional peer dependency, needed only for this entry point. Non-React code can call `setHead(id, props)` and `clearHead(id)` instead.
+- `react` is an optional peer dependency for this entry point. Non-React code can call `setHead(id, props)` and `clearHead(id)`.
+
+## Audit, reports and route sources
+
+The audit runs by default and reports:
+
+- route errors, truncation, empty or duplicate output, broken internal links;
+- duplicate or missing metadata, canonical mismatches, heading counts, sitemap disagreement and orphan pages;
+- CSP violations reported by the browser.
+
+Findings are returned in `report.audit` and logged. They do not fail the run unless `failOnAuditError` is true. `auditIgnoreLinks` excludes dynamic links, and `--no-audit` skips the audit. See [docs/report.md](docs/report.md) for the rule list and JSON schema.
+
+`reportPath` (or `--report`) writes the report as versioned JSON. URLs are reduced to origin and path, and the storage-state path is redacted.
+
+Routes can come from `include` and crawling, from a text/JSON `routesFile`, or from a local or remote sitemap via `routesFromSitemap`. Relative source paths resolve against the config file. Root-relative sitemap locations have `base` stripped, and a remote sitemap's off-origin locations are ignored. If either source is supplied and `include` is not set, the root is not seeded implicitly. With `maxRoutes` or `routePriority`, crawling runs in deterministic breadth-first waves sorted by priority then path. `truncated.droppedRoutes` lists routes that did not fit.
+
+`routeOverrides` applies `timeout`, `waitFor`, `readySelector`, `readyFlag`, `crawl`, `storageState` and `hydration` to matching routes; later entries win per key. `transformHtml` runs once per route after minification and before preload/CSP injection. It may be async and must return a string or nothing.
+
+`preloadLinks` injects `<link rel="modulepreload">` for runtime chunks, font preloads with their response content type, and the LCP image. It complements `preloadManifest`: the manifest is for hosts that send Early Hints, while the injected links work on any static host. Script hints are skipped when `removeScriptTags` is on.
+
+`csp: 'hash'` adds a `<meta http-equiv="Content-Security-Policy">` with SHA-256 hashes for inline scripts and styles. It implies `externalScripts: true` and no CSS swap handler, like `strict`. The policy allows `'self'` only, so third-party scripts or styles need their own policy; the audit warns when the browser reports a blocked request. An existing CSP meta is kept and reported. Inline `style=""` attributes and event handlers cannot be hashed; the audit warns about the attributes.
 
 ## Hydration verification
 
-After writing the output, every route is loaded again with the real client bundle in a fresh browser context. The pass reports two things, and by default neither fails the build: the static HTML that crawlers read is already written and is unaffected by what the client does afterwards. Set `failOnHydrationError: true` (or pass `--fail-on-hydration-error`) when you want hydration treated as a build gate.
+After writing the output, each route is loaded again in a fresh browser context with the client bundle. By default the results are reported but do not fail the build; the static HTML is already written. Set `failOnHydrationError: true` (or pass `--fail-on-hydration-error`) to make hydration a build gate.
+
+**Hydration errors.** Mismatch messages for React, Vue, Svelte and Preact are reported with the route, framework and message. React text mismatches and minified production codes (`#418`, `#423`, `#425`) are recognised; Preact uses the React-compatible messages. A mismatch means the client re-renders the page instead of adopting the static markup. The crawler-visible HTML is unchanged.
 
-**Hydration errors.** React mismatch messages, text mismatches and the minified production codes (`#418`, `#423`, `#425`) are reported with the route and the message. They mean the client re-renders that page instead of adopting the markup, which costs the user some work on load but leaves the static output — search engines and social crawlers still read the prerendered HTML. Enforce them with `failOnHydrationError: true` when you want the stricter gate.
+The framework is detected from DOM markers only (`__reactContainer`, `__vue_app__`/`__vue__`, `__k`, `data-svelte-h`); nothing is imported or executed. Set `framework` when a custom root defeats detection. When a route has hydration errors or re-rendered, `firstMismatch` reports the first difference between the written HTML and the live container as `{ path, kind, expected, actual }`, bounded to 5,000 nodes and depth 20.
 
-**How the app booted.** A probe installed before the app's scripts run remembers the first prerendered node in the container and checks whether it survived:
+A probe installed before the app's scripts run records the first prerendered node and checks whether it survived:
 
 | Mode | Meaning |
 | --- | --- |
-| `hydrated` | The app adopted the prerendered markup, which is the goal. |
+| `hydrated` | The app kept the prerendered markup. |
 | `re-rendered` | The app discarded it and rendered from scratch. |
-| `undetected` | No React root was found on the container, so the mode could not be judged. |
-| `unknown` | The prerendered node was never seen, for example a container outside the usual ids. |
+| `undetected` | No framework root was found on the container. |
+| `unknown` | The prerendered node was not seen, for example a container outside the usual ids. |
+
+A verification navigation that returns HTTP 4xx/5xx, or a container with no content, is reported as failed with its `status` or `empty` flag. `undetected` and `unknown` are reported as counts; `failOnUndetected: true` fails the build for them. A verification pass that cannot run is listed in `verification.errors`; `failOnVerificationError: true` fails separately from hydration errors.
+
+`re-rendered` usually means the app calls `createRoot` instead of `hydrateRoot`. Since `createRoot` does not emit a hydration error, the mode report is the only signal. It is reported per route as `verification.routes[].mode` and summarised in `verification.modes`. Set `failOnRerender: true` to fail the build.
+
+**Page errors.** Uncaught browser errors are reported as warnings, and console errors at debug level. Errors thrown during rendering are counted in the summary and reported per route; `failOnPageError: true` makes them fail the build. By default the static HTML is still written.
+
+**React 16 and 17.** Hydration and boot modes are judged the same way, and their dev mismatch warnings are recognised. Their production builds report nothing for a mismatch, so the boot mode (`hydrated` versus `re-rendered`) is the signal.
+
+**Rebuilds.** `verifyChangedOnly: true` skips verification for routes whose HTML file did not change. The report shows how many routes were skipped.
+
+## Deterministic time
+
+Copyright lines and dated content often differ between prerendering and the verification reload. Fix the clock for both passes:
+
+```js
+snappy({
+  freezeTime: true,       // SOURCE_DATE_EPOCH, or the run start
+  timezone: 'UTC',
+  randomSeed: 42,         // optional; deterministic Math.random for demo content
+});
+```
+
+`freezeTime` also accepts an ISO string or epoch milliseconds, which is the reproducible-build option:
+
+```js
+freezeTime: '2026-05-04T12:00:00Z'
+```
+
+Playwright's fixed clock is installed before navigation and keeps real timers running, so settling and scheduled work are unaffected. The page can read `window.__SNAPPY_NOW__` (epoch ms) or `window.__SNAPPY_NOW_ISO__`. `SOURCE_DATE_EPOCH` is honoured when `freezeTime` is `true`. A fixed clock is a build and verification control only: production still uses real time. For a live clock, render it client-only or use a hydration allow-list. `performance.now()` is not frozen because schedulers rely on it.
+
+## Hydration policies
+
+If a route is intentionally live or random, allow its re-render explicitly instead of suppressing verification globally:
 
-A route whose verification navigation returns HTTP 4xx/5xx, or whose container renders no content, is reported as failed with its `status` or `empty` flag. `undetected` and `unknown` are reported as mode counts; set `failOnUndetected: true` to make any such route fail the build. A verification pass that cannot run is listed in `verification.errors`; set `failOnVerificationError: true` to fail on those separately from hydration errors.
+```js
+snappy({
+  hydration: {
+    allowRerender: ['/status', '/live/*'],
+    skip: ['/admin/*'],
+  },
+  routeOverrides: [
+    { match: '/live/private', hydration: 'strict' },
+  ],
+});
+```
 
-`re-rendered` matters because an app calling `createRoot` instead of `hydrateRoot` throws the prerendered DOM away on boot — and because `createRoot` cannot raise a hydration error, nothing else would ever tell you. It is reported per route as `verification.routes[].mode` and summarised in `verification.modes`, with a warning in the log. Set `failOnRerender: true` to make it fail the build as well.
+`allow-rerender` keeps the mode in the report but moves its hydration errors to `ignoredHydrationErrors` and does not fail the run. `skip` omits the route from verification and records it in `verification.skippedRoutes`. A matching `routeOverrides[].hydration` wins over the global lists; `skip` wins if both global lists match. The CLI flags are `--allow-rerender` and `--skip-hydration`.
 
-**Page errors.** Errors the browser logs while verifying are reported too: uncaught exceptions as warnings, console errors at debug level. Errors thrown during rendering itself are counted in the summary and reported per route, and `failOnPageError: true` turns them into a build failure; by default an app that throws still ships what it managed to render, because the static output is what crawlers read.
+## Locales and hreflang
 
-**React 16 and 17.** Hydration and boot modes are judged the same way, and their dev mismatch warnings ("Text content did not match", "Did not expect server HTML to contain") are recognised. Their production builds report nothing for a mismatch at all — no warning, no minified code — so on 16 and 17 the boot-mode report (`hydrated` versus `re-rendered`) is the signal that something drifted.
+`locales` adds config-driven language metadata. Existing manual `Head` props still win; generated tags only fill missing values.
 
-**Rebuilds.** On a large site most routes are unchanged between builds, and reloading them proves nothing new. `verifyChangedOnly: true` skips the verification pass for routes whose HTML file was left untouched, which roughly halves rebuild time; the report notes how many routes were skipped, and the first run after a change still verifies everything that moved.
+```js
+snappy({
+  locales: {
+    mode: 'path',
+    default: 'en',
+    xDefault: 'en',
+    hreflang: true,
+    list: [
+      { code: 'en', prefix: '', htmlLang: 'en', ogLocale: 'en_US' },
+      {
+        code: 'fr',
+        prefix: '/fr',
+        htmlLang: 'fr',
+        ogLocale: 'fr_FR',
+        routes: { '/about': '/a-propos' },
+      },
+    ],
+  },
+});
+```
+
+In `path` mode, the default locale is crawled once and every locale variant is rendered from the same base routes. `routes` maps translated slugs; a value is the path without the locale prefix. In `single` mode, `active` selects the locale rendered in this build and `list[].url` supplies the other deployments for hreflang. A locale entry can carry `locale` (Playwright/navigator), `timezone`, `storageState`, `cookies` and `localStorage`.
+
+The package sets `<html lang>`/`dir` when missing, adds canonical URLs, `og:locale`, `og:locale:alternate`, self/alternate/`x-default` hreflang links, and feeds the same alternates into the sitemap. `Head` also accepts `alternateLocales={['en_US', 'de_DE']}` for app-managed Open Graph tags. The audit checks invalid and duplicate hreflang codes, missing self links, missing `x-default`, reciprocal links inside the same build, and an `<html lang>` that disagrees with the active locale.
+
+Path mode requires one public origin and an app that routes the prefix or uses the translated `routes` map. Hreflang needs distinct crawlable URLs; a cookie-only locale does not create them. Use single mode for separate locale domains.
+
+## Cookie/localStorage SEO locale
+
+For an app whose locale lives in a cookie or `localStorage`, `seoLocale` selects the SEO language before the app boots:
+
+```js
+snappy({
+  seoLocale: {
+    code: 'fr',
+    source: 'both',          // 'localStorage' | 'cookie' | 'both'
+    localStorageKey: 'locale',
+    cookie: { name: 'locale', path: '/', sameSite: 'Lax', secure: false },
+    seedRender: true,
+    seedVerification: true,
+    inject: true,
+    overwrite: true,
+    forceHtmlLang: true,
+    navigator: false,
+    routes: ['/*'],
+  },
+});
+```
+
+`seedRender` and `seedVerification` put the value into the prerender and verification browsers. `inject` writes a small bootstrap before the app bundle so real visitors get the same locale the static HTML was rendered in. `overwrite: false` only sets the value when missing, preserving a visitor's existing choice. `forceHtmlLang` overrides an app-owned `<html lang>`; `navigator` also emulates `navigator.language`/`Accept-Language`. In path mode the value comes from each locale's code; in single mode it comes from `locales.active` or `seoLocale.code`.
+
+Under `csp: 'hash'` the bootstrap is hashed with the other inline scripts. Under `csp: 'strict'` or `externalScripts` it is written as a same-origin script. Combining `inject: true` with `removeScriptTags: true` is rejected because the bootstrap would be stripped.
+
+This control does not create new crawlable URLs by itself. In single mode it produces one locale per output; for multiple crawlable locales use path-prefixed locales or separate builds/deployments. With `inject: false` the HTML is localized but a visitor with different storage may see another locale after hydration.
 
 ## Ready contract
 
@@ -228,7 +412,7 @@ snappy({ inlineCss: true })       // alias for 'inline'
 npm install --save-dev beasties
 ```
 
-It inlines the critical CSS and converts the remaining stylesheets to non-blocking loads using `media="print"` plus an inline `onload` handler, with a `<noscript>` fallback. Note that the inline handler is inline JavaScript: a strict `script-src` CSP without `unsafe-inline` will leave the deferred stylesheets unapplied. In that case use `'inline'` or a nonce-aware setup.
+It inlines the critical CSS and converts the remaining stylesheets to non-blocking loads using `media="print"` plus an inline `onload` handler, with a `<noscript>` fallback. The inline handler is inline JavaScript, so a strict `script-src` without `unsafe-inline` leaves the deferred stylesheets unapplied. Use `'inline'` or a nonce-aware setup in that case.
 
 ### Minification
 
@@ -236,7 +420,7 @@ It inlines the critical CSS and converts the remaining stylesheets to non-blocki
 snappy({ minifyHtml: true, minifyCss: true });
 ```
 
-`minifyHtml` uses html-minifier-terser with react-snap's defaults (whitespace collapsing, boolean attribute collapsing, attribute sorting). **Whitespace collapsing changes text nodes, which React notices during hydration** — the verifier is your safety net, and `{ collapseWhitespace: false }` is the usual fix. `minifyCss` is passed through to clean-css and also minifies CSS inlined into the HTML.
+`minifyHtml` uses html-minifier-terser with react-snap's defaults (whitespace collapsing, boolean attribute collapsing, attribute sorting). **Whitespace collapsing changes text nodes, which React detects during hydration.** Use `{ collapseWhitespace: false }` if the verifier reports mismatches. `minifyCss` is passed to clean-css and also minifies CSS inlined into the HTML.
 
 ### Link hints
 
@@ -244,11 +428,11 @@ snappy({ minifyHtml: true, minifyCss: true });
 snappy({ preconnectThirdParty: true, preloadImages: true, preloadManifest: true });
 ```
 
-- `preconnectThirdParty` (default `true`) records every third-party origin the page tried to reach — including ones blocked by `blockThirdParty` — and adds `<link rel="preconnect">` for each.
+- `preconnectThirdParty` (default `true`) records every third-party origin the page tried to reach, including blocked ones, and adds `<link rel="preconnect">` for each.
 - `preloadImages` adds `<link rel="preload" as="image">` for same-origin images the page loaded.
-- `preloadManifest` writes `preload-manifest.json` into the output directory: for each route, a `Link` header value listing the scripts and stylesheets the final HTML still references, filtered by `ignoreForPreload` (default `['service-worker.js']`). Inline CSS and tag surgery are already reflected, the not-found route is omitted, and hints and route keys carry the base path, so serve these as Early Hints or `Link` response headers as they are.
+- `preloadManifest` writes `preload-manifest.json`: per route, a `Link` header value for the scripts and stylesheets the final HTML still references. Entries respect `ignoreForPreload` (default `['service-worker.js']`), inline CSS, tag removal and the base path. Serve them as Early Hints or `Link` headers.
 
-react-snap called this `http2PushManifest`. Browsers removed HTTP/2 push (Chrome in v106), so the manifest is now a header list rather than a push list.
+react-snap called this `http2PushManifest`. Browsers removed HTTP/2 push (Chrome 106), so the manifest is a header list rather than a push list.
 
 ### Sitemap
 
@@ -256,7 +440,7 @@ react-snap called this `http2PushManifest`. Browsers removed HTTP/2 push (Chrome
 snappy({ sitemap: true, metadata: { siteUrl: 'https://example.com' } });
 ```
 
-`snappy` already knows every route it rendered, so it can write the sitemap for you. `sitemap.xml` is generated from the routes that were written — using the same page path policy as canonical URLs, with the base path applied, `noindex` pages and the not-found route left out — and split behind a sitemap index when it exceeds 50,000 URLs. Entries carry no `<lastmod>`, because a build date would claim every page changed on every build.
+The sitemap is generated from the written routes using the same page-path policy as canonical URLs. `noindex` pages and the not-found route are omitted. Above 50,000 URLs it is split behind a sitemap index. Entries have no `<lastmod>`; a build date would claim every page changed on every build.
 
 When the output directory already has a `robots.txt`, a `Sitemap:` line is appended to it if it does not point anywhere yet; an existing directive is left alone. Without a `robots.txt`, the run logs the exact line to add instead of creating a file you did not ask for.
 
@@ -271,7 +455,7 @@ snappy({
 });
 ```
 
-The persisted metadata element is exempt from `removeScriptTags`; everything else is removed as asked.
+The persisted metadata element is kept when `removeScriptTags` is on; other scripts are removed.
 
 ### Removing volatile markup
 
@@ -281,9 +465,9 @@ Mark any element with `data-prerender-remove` and it is dropped from the output:
 <div data-prerender-remove>{ads.render()}</div>
 ```
 
-Use it for regions that only make sense after the client takes over — ads, chat widgets, anything injected after mount. The rule of thumb: remove markup that React will *not* render on its first client pass. Removing something React does expect causes the very hydration mismatch it was meant to avoid, which is exactly what the verifier would then report.
+Use it for regions that only exist after the client takes over, such as ads or chat widgets. Remove markup that React does not render on its first client pass. Removing markup React expects causes the hydration mismatch the verifier reports.
 
-Some libraries stamp values that change on every page load — antd's `rc-menu` writes `data-menu-id="rc-menu-uuid-…"` — which makes every rebuild rewrite every file and leaves `verifyChangedOnly` nothing to skip. List those attribute names (or RegExps) and they are dropped from the output:
+Some libraries stamp values that change on every load. Ant Design's `rc-menu`, for example, writes `data-menu-id="rc-menu-uuid-…"`, which makes every rebuild rewrite every file and leaves `verifyChangedOnly` nothing to skip. List those attribute names (or RegExps) and they are removed from the output:
 
 ```js
 snappy({ removeAttributes: ['data-menu-id', 'aria-controls'] });
@@ -314,21 +498,21 @@ Two things the dial cannot remove, because they are what prerendered HTML is:
 
 ## Third-party requests
 
-Third-party requests are **allowed by default**. Most React sites get their content from a CMS, headless API or a separate service origin, and blocking those during prerendering produces pages that render without data — so the default keeps them working, matching react-snap.
+Third-party requests are allowed by default. Most React sites load content from a CMS, headless API or separate service origin; blocking those during prerendering produces pages without data. The default matches react-snap.
 
 ```js
-snappy({ blockThirdParty: false });                    // default: allow everything
-snappy({ blockThirdParty: true });                     // abort every third-party request
+snappy({ blockThirdParty: false });                    // default: allow all
+snappy({ blockThirdParty: true });                     // abort third-party requests
 snappy({ blockThirdParty: true, allowedHosts: ['cms.example.com'] }); // block all but the CMS
 ```
 
-Turning blocking on makes rendering deterministic and keeps analytics, ads and chat widgets from executing during a build. `allowedHosts` is the usual setting for a CMS-backed site: the API stays reachable while everything else is cut.
+Blocking makes rendering deterministic and keeps analytics, ads and chat widgets from executing during a build. `allowedHosts` keeps a CMS API reachable while blocking everything else.
 
-Preconnect hints are generated for **every** third-party origin the page contacts — including hosts you allowlist while blocking — so the deployed page can start those connections early. Set `preconnectThirdParty: false` to turn the hints off. The CLI equivalent for blocking is `--block-third-party`.
+Preconnect hints are generated for every third-party origin the page contacts, including allowlisted hosts while blocking. Set `preconnectThirdParty: false` to disable them. The CLI equivalent for blocking is `--block-third-party`.
 
 ## CSS-in-JS
 
-Emotion, styled-components, vanilla-extract, stitches, JSS and friends work out of the box as long as their styles end up as text inside a `<style>` tag. Three things need more than plain serialisation:
+Emotion, styled-components, vanilla-extract, stitches and JSS work when their styles end up as text inside a `<style>` tag. Three cases need extra handling:
 
 **CSSOM-only styles.** In production, emotion and styled-components v5 switch to `CSSStyleSheet.insertRule` ("speedy" mode), which puts rules in the CSS object model and leaves the style element empty in the DOM. Serialising the page would drop every one of those rules. `captureRuntimeStyles` (default `true`) copies them back into the element text, and also folds document-level constructable stylesheets (`document.adoptedStyleSheets`) into a `<style>` tag. Set it to `false` to leave stylesheets untouched.
 
@@ -363,7 +547,7 @@ if (cached) return cached;
 return fetch('/api/items?page=2').then((response) => response.json());
 ```
 
-`window.snapStore` is keyed by the request path (including its query string), exactly as your app requested it. Responses larger than `maxCachedBytes` (default 5 MiB) are skipped, so one heavy endpoint cannot bloat every page.
+`window.snapStore` is keyed by the request path, including its query string. Responses larger than `maxCachedBytes` (default 5 MiB) are skipped so one large endpoint cannot bloat every page.
 
 **App state.** Define `window.snapSaveState` and whatever it returns is injected as globals before the first script:
 
@@ -438,7 +622,18 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | `exclude` | `[]` | Routes to skip, strings or RegExp |
 | `crawl` | `true` | Follow same-origin links from seeds |
 | `maxDepth` | `null` | Crawl depth limit, `null` is unlimited, `0` renders seeds only |
-| `maxRoutes` | `null` | Stop after this many routes; hitting the cap marks the run incomplete |
+| `maxRoutes` | `null` | Stop after this many routes; hitting the cap marks the run incomplete and lists the routes that did not fit in `truncated.droppedRoutes` |
+| `routePriority` | `[]` | Patterns ranked first when crawling, strings or RegExp; setting it selects deterministic BFS |
+| `routesFile` | `null` | Text or JSON route seeds, one route per line or `{ "routes": [] }`; a relative path resolves against the config file |
+| `routesFromSitemap` | `null` | Local path or http(s) URL whose `<loc>` entries seed routes; sitemap indexes are followed one level, the public base is stripped from root-relative locs, and off-origin locs are ignored. Absolute locs in a local sitemap need `metadata.siteUrl` or a remote sitemap origin |
+| `routeOverrides` | `[]` | Per-route `{ match, timeout, waitFor, readySelector, readyFlag, crawl, storageState, hydration }`; later entries win |
+| `freezeTime` | `false` | `true`, an ISO string or epoch ms; fixes `Date`/`Date.now()` in render and verification. `true` uses `SOURCE_DATE_EPOCH` or the run start |
+| `timezone` | `null` | IANA timezone applied to render and verification contexts |
+| `randomSeed` | `null` | Deterministic `Math.random()` during render and verification; never for security |
+| `hydration` | `{ allowRerender: [], skip: [] }` | Route patterns whose re-render is allowed or whose verification is skipped |
+| `locales` | `null` | Locale matrix for path or single mode, automatic hreflang, canonical, `og:locale` and sitemap alternates |
+| `seoLocale` | `null` | Optional cookie/localStorage locale seed and output bootstrap for SEO builds |
+| `transformHtml` | `null` | Function `(html, { route, file, stats, config })` run before preload/CSP injection; may be async |
 | `concurrency` | derived | Parallel pages, derived from CPU count, capped at 8 |
 | `timeout` | `30000` | Navigation, ready and network-settle timeout in ms; each wait gets this budget |
 | `quietPeriod` | `500` | Network must be idle this long before capture |
@@ -462,7 +657,7 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | `scrollStepDelay` | `100` | Delay between scroll steps when `scrollToBottom` is on |
 | `captureRuntimeStyles` | `true` | Fold CSSOM-only styles and constructable stylesheets into the output |
 | `captureFormState` | `true` | Sync `checked` and `selected` into the output markup |
-| `csp` | `'off'` | `'off'` leaves the injected pieces inline; `'strict'` makes the output work under `script-src 'self'` by moving state to a same-origin file and dropping the CSS swap handlers |
+| `csp` | `'off'` | `'off'` leaves the injected pieces inline; `'strict'` makes the output work under `script-src 'self'` by moving state to a same-origin file and dropping the CSS swap handlers; `'hash'` adds a meta policy with SHA-256 hashes for inline scripts and styles |
 | `inlineCss` | `false` | `'inline'`, `'critical'` (needs beasties) or `true` for `'inline'` |
 | `criticalCssPreload` | `'media'` | Swap used for CSS deferred by `inlineCss: 'critical'`; `false` emits no swap handlers, for a strict script-src |
 | `minifyHtml` | `false` | Minify output HTML, `true` for defaults or an html-minifier-terser options object |
@@ -470,8 +665,10 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | `preconnectThirdParty` | `true` | Add preconnect hints for every third-party origin the page contacts |
 | `preloadImages` | `false` | Add preload hints for same-origin images |
 | `preloadManifest` | `false` | Write `preload-manifest.json` with Link header hints, derived from the final HTML |
-| `ignoreForPreload` | `['service-worker.js']` | File names excluded from the manifest |
+| `preloadLinks` | `false` | Inject module, font and LCP image preload hints for static hosts; script hints are skipped when `removeScriptTags` is on |
+| `ignoreForPreload` | `['service-worker.js']` | File names excluded from the manifest and injected hints |
 | `sitemap` | `false` | Write `sitemap.xml` (or a sitemap index above 50,000 URLs) from the routes that do not declare noindex, and point an existing `robots.txt` at it; needs `metadata.siteUrl` |
+| `imageSitemap` | `false` | List same-origin page images in the sitemap |
 | `cacheAjaxRequests` | `false` | Expose captured JSON responses as `window.snapStore` |
 | `maxCachedBytes` | `5242880` | Largest JSON response cached per request, measured on the serialised body |
 | `removeBlobs` | `true` | Drop stylesheet links pointing at dead `blob:` URLs |
@@ -482,13 +679,22 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | `removeStyleTags` | `false` | Strip every style tag from the output; cannot be combined with `inlineCss` `'inline'` |
 | `removeScriptTags` | `false` | Strip every script tag from the output |
 | `asyncScriptTags` | `false` | Mark external scripts async |
-| `externalScripts` | `false` | Write injected state scripts as content-hashed same-origin files instead of inline; set by `csp: 'strict'` |
+| `externalScripts` | `false` | Write injected state scripts as content-hashed same-origin files instead of inline; set by `csp: 'strict'` or `'hash'` |
 | `flatOutput` | `false` | Write `about.html` instead of `about/index.html` |
-| `notFoundRoute` | `/404` | Route emitted as `404.html` with a robots noindex tag; a notice is logged when it is never prerendered |
+| `notFoundRoute` | `/404` | Route emitted as `404.html` with a robots noindex tag, even when the server answers HTTP 404; a notice is logged when it is never prerendered. A page can also declare `<meta name="prerender-status-code" content="404">` |
+| `audit` | `true` | Check the written site for route health, broken links, metadata, sitemap and CSP issues |
+| `failOnAuditError` | `false` | Fail when the audit finds an error |
+| `auditIgnoreLinks` | `[]` | Link patterns excluded from the audit, strings or RegExp |
+| `reportPath` | `null` | Write the versioned JSON run report to this file; URLs and the storage-state path are redacted |
 | `saveAs` | `html` | `html`, `png` or `jpeg`; identical screenshots are left untouched |
 | `metadata` | `null` | Defaults for the head component: `siteUrl` (origin only), `siteName`, `titleTemplate`, `defaultImage`, `trailingSlash`, `base` |
 | `verify` | `true` | Run the hydration verification pass |
+| `framework` | `auto` | `auto`, `react`, `vue`, `svelte` or `preact`; detects the mounted framework from DOM markers |
+| `retries` | `0` | Retry a retryable render failure this many times |
+| `retryDelay` | `500` | Wait between render attempts, in ms |
+| `traceOnError` | `false` | Write a Playwright trace for the final failed attempt under `snappy-traces/` |
 | `verifyChangedOnly` | `false` | Skip verification for routes whose HTML file did not change since the last run |
+| `reuseVerificationContext` | `false` | Reuse one browser context per verification worker; routes share storage, so use only for stateless apps |
 | `failOnHydrationError` | `false` | Fail the run on hydration errors; off by default, where they are reported instead |
 | `failOnRerender` | `false` | Fail the run when a route re-renders instead of hydrating |
 | `failOnPageError` | `false` | Fail the run when a page throws while rendering; off by default, where page errors are reported |
@@ -522,41 +728,15 @@ if (!report.ok) {
 }
 ```
 
-The report exposes `routes`, `files` (with per-route `status` and `noindex`), `errors`, `pageErrors` (uncaught browser errors seen while rendering), `consoleErrors`, `failedRequests`, `emptyPages`, `duplicatePages`, `duplicateTitles` (routes shipping more than one title), `verification` (nullable; per-route `mode`, `status` and `empty` plus a `modes` summary), `preloadManifest`, `sitemap`, `pruned`, `truncated`, and `ok`.
+The report exposes `routes`, `files` (with per-route `status` and `noindex`), `routeDetails` (the per-route records used by the JSON report), `errors`, `pageErrors` (uncaught browser errors seen while rendering), `consoleErrors`, `failedRequests`, `emptyPages`, `duplicatePages`, `duplicateTitles` (routes shipping more than one title), `verification` (nullable; per-route `mode`, `framework`, `firstMismatch`, `status` and `empty` plus `modes` and `frameworks` summaries), `audit` (nullable; `errors`, `warnings`, `linksChecked`), `preloadManifest`, `sitemap`, `pruned`, `truncated`, `notFoundRoutes`, `cspSkipped`, `traces`, and `ok`. See [docs/report.md](docs/report.md) for the JSON schema.
 
 `snappy-prerender` exports `DEFAULTS`, `prerender` and `resolveConfig`; the default export is the Vite plugin.
 
-## Differences from react-snap
-
-Kept: crawling, include, concurrency, viewport, waitFor, executable path, external server, third-party skipping (now on by default), `userAgent`, `inlineCss`, `minifyHtml`, `minifyCss`, `cacheAjaxRequests`, `snapSaveState`, `preconnectThirdParty`, `preloadImages`, `removeBlobs`, `removeStyleTags`, `removeScriptTags`, `asyncScriptTags`, `destination`, `saveAs` (html/png/jpeg).
+## Further reading
 
-Changed: `http2PushManifest` became `preloadManifest` (browsers removed HTTP/2 push), `fixInsertRule` became `captureRuntimeStyles` and also covers constructable stylesheets, `fixFormFields` became `captureFormState`, `puppeteerArgs` became `browserArgs`, `puppeteerIgnoreHTTPSErrors` became `ignoreHTTPSErrors`, `skipThirdPartyRequests` became `blockThirdParty` with the same default of allowing them, `exclude` and `maxRoutes` are new, and `notFoundRoute` replaces the `/404` include convention.
-
-Dropped: `sourceMaps` (declared but never referenced in react-snap's code), `fixWebpackChunksIssue` and `fixInsertRule` (webpack/Chrome-era workarounds), `port` (ephemeral loopback port instead), `puppeteer.cache`, and the preload polyfill (modulepreload is universally supported).
-
-## Limitations
-
-- **Build-time data is a snapshot.** Anything fetched during rendering is frozen into the HTML until the next build. Use `cacheAjaxRequests` and `snapSaveState` so the client replays the same data.
-- **Hydration mismatches are your app's to fix.** The verifier tells you exactly which route and which React error. Common causes: `Date.now()`, `Math.random()`, `localStorage` reads during render, viewport-dependent markup, and CSS-in-JS that re-injects styles on hydration.
-- **Markup that depends on load state cannot hydrate.** A component that swaps a placeholder for real content once an image or widget loads renders one thing during prerendering (where the network has settled) and another on the client's first render. The verifier reports those routes as `re-rendered`. Render deterministic markup instead — a plain `<img loading="lazy">` rather than a JS placeholder swap — or accept the re-render.
-- **Authenticated routes need `storageState`.** Never prerender personal data into static HTML without deciding to.
-- **Runtime-only routes** (heavy API dependence, real-time data) are better served by `serveCmd` or left client-rendered.
-- Route query strings are ignored; routes are deduplicated without them.
-- Routes whose decoded path contains dot segments or backslashes are skipped, so encoded traversal cannot create stray directories.
-- Crawling is unbounded unless `maxRoutes` is set; hitting the cap marks the run as failed so incomplete output is never shipped silently. Which routes are cut is concurrency-dependent on a large site — narrow `include`/`exclude` instead when you need a deterministic set.
-- **React 19 native metadata.** React hoists `<title>` and `<meta>` rendered in JSX and leaves an existing template title in place, so using both systems produces two titles in the output. Use one of them; the run warns when a page ships more than one `<title>`.
-- If two routes would write the same file — such as `/` and `/index` with `flatOutput` — neither is written and the run fails with a collision error.
-- Screenshots are viewport-width full-page captures, so they reflect the configured `viewport`, not a device matrix. Identical screenshots are left untouched.
-- **Output files from routes that no longer exist** are left in place unless `pruneStaleRoutes` is enabled, which deletes only files listed in the previous run's `.snappy-manifest.json`.
-- **Dead extensionless links** are indistinguishable from SPA routes to the static server, so a missing page can render the shell or the app's catch-all 404. Duplicate output is reported; set `failOnDuplicateContent` to enforce it, and use an app-level 404 marker where possible.
-- **Metadata pointing at the build server** is removed by default (`stripBuildOriginMetadata: true`) and reported. Set `metadata.siteUrl` so canonical and social URLs survive.
-- **`inlineCss`** rebases relative font and image URLs against each stylesheet. A sheet that uses `@import` is left as a link because concatenating it would change the cascade.
-- **`verifyChangedOnly` compares the generated HTML only.** If a bundle keeps the same filename while its contents change, that route's HTML is unchanged and its verification is skipped; content-hashed asset names (Vite and CRA defaults) make the HTML change as well.
-- **Destination directories are merged unless `cleanDestination` is on.** That option empties the destination first; `pruneStaleRoutes` separately removes pages the run itself generated.
-- **`removeStyleTags`** cannot be combined with `inlineCss: 'inline'` or `true`; the config is rejected instead of silently shipping pages without CSS.
+[Limitations](docs/limitations.md), [report schema and audit rules](docs/report.md), [migrating from react-snap](docs/react-snap-migration.md).
 
 ## Requirements
-
 - Node.js >= 22.12
 - Chrome or Edge installed (detected automatically), or allow the one-time Chrome for Testing download fallback
 - `beasties` only if you use `inlineCss: 'critical'` (optional peer dependency)