snappy-prerender 2.6.0-rc.2 → 2.6.0

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Earlier history predates
+the release tags; see the Git history for those changes.
+
+## [2.6.0] - 2026-10-27
+
+### Added
+
+- `cleanDestination` empties the destination before copying the build output, so assets
+  removed from a build do not linger.
+- `pruneStaleRoutes` removes pages recorded by the previous run's `.snappy-manifest.json`
+  when they are no longer produced, without touching assets or user files.
+- New build gates: `failOnEmptyPage` (on by default), `failOnConsoleError`,
+  `failOnFailedRequest`, `failOnDuplicateContent`, `failOnUndetected`,
+  `failOnVerificationError` and the optional `failOnBuildOriginMetadata`.
+- `browserDownloadVersion` pins the Chrome for Testing build id; a cached build is now
+  used without contacting the version feed, so offline rebuilds work.
+- `stripBuildOriginMetadata` removes canonical and social tags that point at the
+  prerender server instead of shipping loopback URLs.
+- Reports now expose `consoleErrors`, `failedRequests`, `emptyPages`, `duplicatePages`
+  and `pruned`; page files carry `noindex`, and verification entries carry `status` and
+  `empty`.
+- CLI flags for the new gates and for `quietPeriod`, `scrollStepDelay`,
+  `serveCmdTimeout`, `shutdownTimeout`, `maxCachedBytes`, `viewport`, `readyFlag`,
+  `readySelector`, `headless`, `cleanDestination` and `metadata.base`.
+- A Node 22/24 test workflow and a dedicated integration suite for the audit fixes.
+
+### Changed
+
+- **Breaking:** the minimum supported Node version is now 22.12, matching
+  `@puppeteer/browsers`.
+- **Breaking:** an explicit `browser` choice no longer falls back to another engine.
+  `chromium` uses a Playwright-managed Chromium and asks you to install it when missing;
+  `auto` is the only choice that walks machine, Playwright cache, cached Chrome for
+  Testing, then download.
+- **Breaking:** `include` is a true output allowlist. A wildcard-only list still seeds the
+  root for crawling, but the seed itself is not written. Passing `include: ['/']` is
+  treated as the default and leaves crawling enabled.
+- **Breaking:** canonical, Open Graph and sitemap URLs share one page-path policy:
+  directory output keeps its trailing slash, flat output stays extensionless, and an
+  explicit `trailingSlash` wins.
+- **Breaking:** sitemap entries no longer carry `lastmod` (a build date claimed every page
+  changed), noindex pages are excluded, and sitemaps above 50,000 URLs are split behind a
+  sitemap index.
+- **Breaking:** `metadata.siteUrl` must be an origin without a path; sub-path deployments
+  belong in `base`. A `serveCmd` URL with a path is rejected for the same reason.
+- **Breaking:** `removeStyleTags` combined with `inlineCss: 'inline'` or `true` is
+  rejected instead of silently removing the CSS that was just inlined.
+- Empty output now fails a route by default; 404 pages are emitted with a robots
+  `noindex` tag.
+- Third-party blocking now covers WebSockets and accepts hostnames with ports, wildcard
+  suffixes and leading-dot suffixes. Service workers are blocked during rendering and
+  verification.
+- Verification uses a real browser user agent and the same reduced-motion context as the
+  render pass; mode counts are always logged and can fail the build with
+  `failOnUndetected`.
+- Inlined stylesheets rebase relative `url()` values against their source stylesheet;
+  sheets using `@import` stay linked to preserve the cascade.
+- Preload manifests are derived from the final HTML, so inline CSS, tag surgery and failed
+  writes no longer leave stale hints. The not-found route is omitted.
+- Screenshots use the same unchanged-file check as HTML and dry runs report the image file
+  instead of an HTML one.
+- `init` reads Vite's resolved `outDir` and `base`, and Create React App's `homepage`, so
+  the wizard no longer guesses `dist` and `/` for custom projects. During a prerelease it
+  prints the `@next` install tag.
+- Unknown config keys and options that have no effect in the current combination now
+  produce warnings instead of being ignored silently.
+- Rendered output is split across smaller modules; `run.js` is back under the 600-line
+  limit.
+
+### Fixed
+
+- `setHead` called an undefined helper and threw `ReferenceError`.
+- HTTP 4xx/5xx navigations, empty pages and zero-route runs could be written and reported
+  as successful; they now fail with route-level errors.
+- The static server served `index.html` for dead extensionless links and failed dotted
+  routes; HTML navigations now fall back deliberately and duplicate output is detected.
+- Canonical and `og:url` doubled a non-root `base` path.
+- `verifyChangedOnly` could skip a changed page when a shared state script was unchanged.
+- `asyncScriptTags` marked the injected state script `async`, allowing it to run after the
+  application bundle.
+- `removeAttributes` with a global or sticky RegExp skipped every other match.
+- Output collisions that differ only by case are detected on case-insensitive
+  filesystems.
+- A destination inside the source directory recursed until the path length limit.
+- Inlined CSS lost relative font and image URLs.
+- Build-server metadata shipped loopback canonical and social URLs.
+- Preload manifests described resources the final page no longer loaded.
+- Sitemap and canonical URLs disagreed on trailing slashes and flat output.
+- Allowed-host matching ignored ports and wildcards, and WebSocket requests bypassed
+  blocking.
+- Browser downloads needed the network even when a cached browser was available.
+- The CLI advertised `--preconnect-third-party` without defining it, and several other
+  documented flags had no CLI equivalent.
+
+## [2.6.0-rc.3] - 2026-10-03
+
+### Added
+
+- Computed config files: `snappy.config.js` may export an async function that returns
+  options, so routes can come from a CMS, sitemap or file listing.
+- Sitemap generation and the `sitemap` option.
+- Stable output: unchanged pages, state scripts and artifacts are left untouched.
+- React 16.8 and 17 fixtures and integration coverage.
+
+### Changed
+
+- Documentation links to the npm package and notes the release-candidate channel.
+
+## [2.6.0-rc.2] - 2026-09-26
+
+### Added
+
+- `snappy-prerender init` setup wizard, with flags for non-interactive use.
+- CSP-friendly output: `csp: 'off' | 'strict'`, `externalScripts` and configurable
+  `criticalCssPreload`.
+
+## [2.6.0-rc.1] - 2026-09-26
+
+### Added
+
+- The `snappy-prerender/head` entry point: `Head`, `setHead`, `clearHead`, metadata
+  defaults, canonical, Open Graph and Twitter tags, and client-side reconciliation.
+- Head-layer audit fixes for tag ownership, restoration and repeated runs.
+
+## [2.5.0] - 2026-09-25
+
+### Added
+
+- react-snap feature parity for v2: `inlineCss`, `minifyHtml`, `minifyCss`,
+  `preloadImages`, `cacheAjaxRequests`, `snapSaveState`, `preloadManifest`,
+  `removeBlobs`, `removeStyleTags`, `removeScriptTags`, `asyncScriptTags`,
+  `destination`, `saveAs`, `browserArgs` and `ignoreHTTPSErrors`.
+- Hydration verification that reports `hydrated`, `re-rendered`, `undetected` and
+  `unknown`, plus per-route React mismatch messages.
+- Third-party requests allowed by default, with opt-in blocking and host allowlists.

package/README.md

@@ -3,11 +3,14 @@
 **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.
 
 [![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)
 [![node](https://img.shields.io/node/v/snappy-prerender.svg)](https://www.npmjs.com/package/snappy-prerender)
 [![license](https://img.shields.io/npm/l/snappy-prerender.svg)](https://github.com/sayakmukherjee080/snappy-prerender/blob/main/LICENSE)
 
+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 18 and React 19, Vite 6/7/8, or any static build.**
+- **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.
 
 ## Who this is for
@@ -60,6 +63,7 @@ npx snappy-prerender dist --include /,/pricing,/blog/* --exclude /blog/drafts/*
 npx snappy-prerender dist --block-third-party --allowed-hosts cms.example.com
 npx snappy-prerender dist --metadata-site-url https://example.com --metadata-title-template '%s | Example'
 npx snappy-prerender dist --inline-css critical --minify-html --preload-manifest
+npx snappy-prerender dist --sitemap --verify-changed-only
 npx snappy-prerender dist --csp strict --inline-css critical
 ```
 
@@ -70,9 +74,10 @@ import { prerender } from 'snappy-prerender/core';
 
 const report = await prerender({ sourceDir: 'dist', include: ['/'] });
 if (!report.ok) {
-  for (const failure of report.verification.routes.filter((entry) => !entry.ok)) {
+  for (const failure of report.verification?.routes.filter((entry) => !entry.ok) ?? []) {
     console.error(failure.route, failure.hydrationErrors);
   }
+  for (const failure of report.errors) console.error(failure.route, failure.message);
 }
 ```
 
@@ -150,7 +155,7 @@ Rules worth knowing:
 - 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. Without `metadata.siteUrl` they fall back to the browser origin, which during prerendering is the build server — the run warns when that happens. The `trailingSlash` convention applies to page URLs only; asset URLs are left alone.
+- 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>`.
 - Every metadata value has a CLI flag: `--metadata-site-url`, `--metadata-site-name`, `--metadata-title-template`, `--metadata-default-image`, `--metadata-trailing-slash`.
@@ -171,10 +176,16 @@ After writing the output, every route is loaded again with the real client bundl
 | `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. |
 
+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.
+
 `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.
 
 **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.
 
+**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.
+
+**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.
+
 ## Ready contract
 
 Most apps work with no configuration because the network-quiet heuristic is enough. Apps that fetch data after load can opt into a stronger signal:
@@ -235,10 +246,20 @@ 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.
 - `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 it used, filtered by `ignoreForPreload` (default `['service-worker.js']`). 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` 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.
 
 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.
 
+### Sitemap
+
+```js
+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.
+
+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.
+
 ### Tag surgery
 
 ```js
@@ -252,6 +273,24 @@ snappy({
 
 The persisted metadata element is exempt from `removeScriptTags`; everything else is removed as asked.
 
+### Removing volatile markup
+
+Mark any element with `data-prerender-remove` and it is dropped from the output:
+
+```jsx
+<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.
+
+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:
+
+```js
+snappy({ removeAttributes: ['data-menu-id', 'aria-controls'] });
+```
+
+As with removed markup, only strip attributes React does not render as props; if you guess wrong, the hydration verifier tells you which route.
+
 ### Strict CSP
 
 One dial decides how the injected pieces are delivered. `csp: 'off'` (default) leaves them inline, which is cheapest to load. `csp: 'strict'` makes the whole output work under `script-src 'self'` with no `unsafe-inline`:
@@ -370,20 +409,38 @@ export default {
 };
 ```
 
+The config can also be an async function that returns the options. That is how routes get discovered from a CMS, a sitemap or a directory listing, without a separate prebuild script:
+
+```js
+// snappy.config.js
+export default async function () {
+  const response = await fetch('https://cms.example.com/api/posts?fields=slug');
+  const posts = await response.json();
+  return {
+    sourceDir: 'dist',
+    include: ['/', '/blog', ...posts.map((post) => `/blog/${post.slug}`)],
+    metadata: { siteUrl: 'https://example.com', siteName: 'Example' },
+  };
+}
+```
+
+The function is awaited once per run, and whatever it returns must be a plain options object. If it throws, the CLI reports the reason and stops before rendering anything.
+
 ## Options
 
 | Option | Default | Description |
 | --- | --- | --- |
 | `sourceDir` | `dist` | Built output directory |
 | `destination` | `null` | Copy the output here and write results here instead of in place |
+| `cleanDestination` | `false` | Empty the destination before copying, so removed assets do not linger |
 | `base` | `/` | Public base path |
-| `include` | `['/']` | Seed routes and allowlist. Wildcards (`/blog/*`) filter discovered routes, only concrete paths are seeded. Supplying your own list switches discovery off, so the listed routes are all that is rendered; leave it unset to render the root and crawl everything linked from it |
+| `include` | `['/']` | Seed routes and output allowlist. Wildcards (`/blog/*`) filter discovered routes, only concrete paths are seeded, and a seed that does not match the list is used for crawling but not written. Passing `['/']` is treated as the default: crawl everything linked from the root |
 | `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 |
 | `concurrency` | derived | Parallel pages, derived from CPU count, capped at 8 |
-| `timeout` | `30000` | Per-route timeout in ms |
+| `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 |
 | `readyFlag` | `__prerenderReady` | Window flag awaited when defined |
 | `readySelector` | `null` | Selector awaited when set |
@@ -394,6 +451,7 @@ export default {
 | `browser` | `auto` | `auto`, `chrome`, `msedge`, `chromium`, or a path to an executable |
 | `browserDownload` | `true` | Allow the Chrome for Testing fallback download |
 | `browserDownloadHash` | `null` | SHA-256 digest the fallback download must match, verified before use |
+| `browserDownloadVersion` | `null` | Chrome for Testing build id to use for the cache and download instead of resolving `stable` |
 | `browserArgs` | `[]` | Extra browser launch arguments |
 | `headless` | `true` | Run the browser headless |
 | `ignoreHTTPSErrors` | `false` | Ignore TLS errors while rendering |
@@ -411,28 +469,40 @@ export default {
 | `minifyCss` | `false` | Minify CSS with clean-css, also applied to inlined CSS |
 | `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 |
+| `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 |
+| `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` |
 | `cacheAjaxRequests` | `false` | Expose captured JSON responses as `window.snapStore` |
-| `maxCachedBytes` | `5242880` | Largest JSON response cached per route, measured on the serialised body |
+| `maxCachedBytes` | `5242880` | Largest JSON response cached per request, measured on the serialised body |
 | `removeBlobs` | `true` | Drop stylesheet links pointing at dead `blob:` URLs |
-| `removeStyleTags` | `false` | Strip every style tag from the output |
+| `removeAttributes` | `[]` | Attribute names or RegExps to drop from the output, for libraries that stamp per-load ids |
+| `stripBuildOriginMetadata` | `true` | Remove canonical and social tags whose URL points at the prerender server |
+| `failOnBuildOriginMetadata` | `false` | Fail when metadata still points at the prerender server after stripping |
+| `pruneStaleRoutes` | `false` | Delete pages listed by the previous run's manifest that this run no longer writes |
+| `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'` |
 | `flatOutput` | `false` | Write `about.html` instead of `about/index.html` |
-| `notFoundRoute` | `/404` | Route emitted as `404.html`; a notice is logged when it is never prerendered |
-| `saveAs` | `html` | `html`, `png` or `jpeg` |
-| `metadata` | `null` | Defaults for the head component: `siteUrl`, `siteName`, `titleTemplate`, `defaultImage`, `trailingSlash`, `base` |
+| `notFoundRoute` | `/404` | Route emitted as `404.html` with a robots noindex tag; a notice is logged when it is never prerendered |
+| `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 |
+| `verifyChangedOnly` | `false` | Skip verification for routes whose HTML file did not change since the last run |
 | `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 |
+| `failOnEmptyPage` | `true` | Fail when a route renders no app content |
+| `failOnConsoleError` | `false` | Fail when the browser logs a console error while rendering |
+| `failOnFailedRequest` | `false` | Fail when a same-origin request fails while rendering |
+| `failOnDuplicateContent` | `false` | Fail when two routes produce byte-identical HTML |
+| `failOnUndetected` | `false` | Fail when verification cannot classify any route as hydrated or re-rendered |
+| `failOnVerificationError` | `false` | Fail when the verification pass cannot run on a route |
 | `failOnError` | `true` | Fail the run on route render errors |
 | `dryRun` | `false` | Render and report without writing |
 | `logLevel` | `info` | `silent`, `error`, `warn`, `info`, `debug` |
 | `serveCmd` | `null` | Command that starts the app server instead of static serving |
-| `url` | `null` | App URL, required with `serveCmd` |
+| `url` | `null` | App origin, required with `serveCmd`; put a sub-path in `base` instead |
 | `serveCmdTimeout` | `30000` | How long to wait for `serveCmd` to answer |
 | `shutdownTimeout` | `5000` | Grace period before force-killing `serveCmd` |
 
@@ -445,13 +515,14 @@ import { prerender } from 'snappy-prerender/core';
 
 const report = await prerender({ sourceDir: 'dist', include: ['/'] });
 if (!report.ok) {
-  for (const failure of report.verification.routes.filter((entry) => !entry.ok)) {
+  for (const failure of report.verification?.routes.filter((entry) => !entry.ok) ?? []) {
     console.error(failure.route, failure.hydrationErrors);
   }
+  for (const failure of report.errors) console.error(failure.route, failure.message);
 }
 ```
 
-The report exposes `routes`, `files` (with per-route `status`), `errors`, `pageErrors` (uncaught browser errors seen while rendering), `duplicateTitles` (routes shipping more than one title), `verification` (per-route `mode` plus a `modes` summary), `preloadManifest`, `truncated`, and `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`.
 
 `snappy-prerender` exports `DEFAULTS`, `prerender` and `resolveConfig`; the default export is the Vite plugin.
 
@@ -475,16 +546,22 @@ Dropped: `sourceMaps` (declared but never referenced in react-snap's code), `fix
 - 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.
-- Output files from routes that no longer exist are left in place; clean the output directory or use a fresh `destination` when route sets shrink.
+- 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.
 
 ## Requirements
 
-- Node.js >= 20.19
+- 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)
 
-Browser resolution order: installed Chrome, installed Edge, a Playwright-managed browser, then a Chrome for Testing download from Google's version-pinned HTTPS bucket into `SNAPPY_BROWSER_CACHE_DIR` (defaults to the platform cache directory). Chrome for Testing publishes no checksum feed, so that archive is trusted on the strength of HTTPS and the pinned URL unless you set `browserDownloadHash`, which makes the download fail if the SHA-256 does not match. Set `browserDownload: false` to forbid downloads entirely.
+Browser resolution order: installed Chrome, installed Edge, a Playwright-managed browser, a Chrome for Testing build already in the tool cache, then a Chrome for Testing download from Google's version-pinned HTTPS bucket into `SNAPPY_BROWSER_CACHE_DIR` (defaults to the platform cache directory). An explicit `browser` choice never falls back to another engine. Set `browserDownloadVersion` to pin the build id and `browserDownloadHash` to pin the archive digest; without a hash the download is trusted on the strength of HTTPS and the pinned URL. Set `browserDownload: false` to forbid downloads entirely.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snappy-prerender",
-  "version": "2.6.0-rc.2",
+  "version": "2.6.0",
   "description": "Drop-in prerendering for existing single-page apps. Renders your built app in a real browser, writes static HTML per route, reports React hydration mismatches, and optimises the output with critical CSS, link hints and cached AJAX state.",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,7 @@
     "playwright"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.12.0"
   },
   "main": "./src/index.js",
   "exports": {
@@ -36,14 +36,17 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "snappy-prerender": "./src/cli.js"
+    "snappy-prerender": "src/cli.js"
   },
   "files": [
     "src",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/head/manager.js"
+  ],
   "scripts": {
     "test": "node scripts/run-tests.mjs tests/unit",
     "test:integration": "node scripts/run-tests.mjs tests/integration",
@@ -65,14 +68,16 @@
     "beasties": "0.4.1",
     "react": "19.2.0",
     "react-dom": "19.2.0",
-    "vite": "7.3.6"
+    "vite": "7.3.7"
   },
   "workspaces": [
+    "tests/fixtures/react16-app",
+    "tests/fixtures/react17-app",
     "tests/fixtures/react18-app"
   ],
   "peerDependencies": {
     "beasties": ">=0.4.1",
-    "react": ">=18.0.0",
+    "react": ">=16.8.0",
     "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
   },
   "peerDependenciesMeta": {