snappy-prerender 2.6.0-rc.3 → 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

@@ -7,7 +7,7 @@
 [![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). While 2.6.0 is a release candidate it is published under the `next` tag, so install with `npm install --save-dev snappy-prerender@next`; the plain command below works once 2.6.0 is stable.
+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.**
@@ -74,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);
 }
 ```
 
@@ -154,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`.
@@ -175,6 +176,8 @@ 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.
@@ -243,7 +246,7 @@ 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.
 
@@ -253,7 +256,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 output files — a directory route becomes `/about/`, a `flatOutput` route becomes `/about.html` — with the base path applied and the not-found route left out. Each entry carries a `<lastmod>` of the run date.
+`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.
 
@@ -429,14 +432,15 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | --- | --- | --- |
 | `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 |
@@ -447,6 +451,7 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | `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 |
@@ -464,31 +469,40 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | `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` from the rendered routes and point an existing `robots.txt` at it; needs `metadata.siteUrl` |
+| `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 |
 | `removeAttributes` | `[]` | Attribute names or RegExps to drop from the output, for libraries that stamp per-load ids |
-| `removeStyleTags` | `false` | Strip every style tag from the output |
+| `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` |
 
@@ -501,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.
 
@@ -531,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.3",
+  "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,7 +68,7 @@
     "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",

package/src/cli.js

@@ -30,17 +30,33 @@ Options:
       --max-depth <n>         Crawl depth limit, 0 renders roots only (default: unlimited)
       --max-routes <n>        Stop after this many routes and fail the run (default: unlimited)
       --concurrency <n>       Parallel browser pages (default: derived from CPU count)
-      --timeout <ms>          Per-route timeout (default: 30000)
+      --timeout <ms>          Per-route navigation/settle timeout (default: 30000)
+      --quiet-period <ms>     Network must be idle this long before capture (default: 500)
+      --scroll-step-delay <ms>  Delay between scroll steps (default: 100)
+      --viewport <WxH>        Browser viewport (default: 1280x720)
+      --ready-selector <sel>  Selector awaited when set
+      --ready-flag <name>     Window flag awaited when defined (default: __prerenderReady)
+      --no-headless           Run the browser visibly
       --wait-for <selector>   Wait for a selector on every route before capture
       --browser <choice>      auto | chrome | msedge | chromium | path (default: auto)
       --no-browser-download   Refuse the Chrome for Testing fallback download
       --browser-download-hash <sha256>  Pin the fallback download to a SHA-256 digest
+      --browser-download-version <build>  Pin the Chrome for Testing build id
       --storage-state <file>  Playwright storage state for authenticated routes
       --no-verify             Skip the hydration verification pass
       --verify-changed-only   Skip verification for routes whose HTML did not change
       --fail-on-hydration-error  Fail the build when hydration errors are found
       --fail-on-rerender      Fail when a route re-renders instead of hydrating
       --fail-on-page-error    Fail when a page throws while it is being rendered
+      --no-fail-on-error      Report route errors without failing the run
+      --fail-on-empty-page    Fail when a route renders no app content (default: on)
+      --no-fail-on-empty-page Allow an empty page and report it instead
+      --fail-on-console-error Fail when the browser logs a console error while rendering
+      --fail-on-failed-request  Fail when a same-origin request fails while rendering
+      --fail-on-duplicate-content  Fail when two routes produce identical HTML
+      --fail-on-build-origin-metadata  Fail when metadata still points at the prerender server
+      --fail-on-undetected    Fail when verification cannot find a framework root
+      --fail-on-verification-error  Fail when the verification pass cannot run
       --block-third-party     Block third-party requests while rendering
       --no-block-third-party  Allow third-party requests (the default)
       --allowed-hosts <hosts>  Third-party hosts to allow while blocking the rest, comma separated
@@ -51,6 +67,7 @@ Options:
       --flat                  Write about.html instead of about/index.html
       --not-found <route>     Route emitted as 404.html (default: /404)
       --destination <dir>     Write output to another directory (default: in place)
+      --clean-destination     Empty the destination before copying the build output
       --save-as <format>      html | png | jpeg (default: html)
       --user-agent <value>    User agent used while rendering (default: SnappyPrerender)
       --metadata-site-url <url>       Public site URL for canonical and og:url
@@ -58,6 +75,7 @@ Options:
       --metadata-title-template <t>   Title template, for example '%s | Example'
       --metadata-default-image <url>  Share image for routes without one
       --metadata-trailing-slash <mode>  preserve | always | never
+      --metadata-base <path>  Base path used for absolute metadata URLs
       --inline-css <strategy> inline | critical (critical needs the beasties package)
       --critical-css-preload <mode>  Swap for deferred CSS: none | body | media | swap | swap-high | swap-low | js | js-lazy
       --minify-html           Minify the generated HTML
@@ -69,6 +87,7 @@ Options:
       --sitemap               Write sitemap.xml from the rendered routes (needs metadata.siteUrl)
       --ignore-for-preload <names>  File names excluded from the manifest, comma separated
       --cache-ajax-requests   Expose captured JSON responses as window.snapStore
+      --max-cached-bytes <n>  Largest JSON response cached per request (default: 5242880)
       --remove-scripts        Strip every script tag from the output
       --remove-styles         Strip every style tag from the output
       --async-scripts         Mark external scripts async
@@ -76,10 +95,14 @@ Options:
       --csp <mode>            off | strict: strict makes the output work under script-src 'self'
       --no-remove-blobs       Keep blob stylesheet links instead of dropping them
       --remove-attributes <names>  Drop these attributes from the output, comma separated
+      --no-strip-build-origin-metadata  Keep tags that point at the prerender server
+      --prune-stale-routes    Delete pages listed by the previous run's manifest
       --ignore-https-errors   Ignore TLS errors while rendering
       --browser-args <args>   Extra browser launch arguments, comma separated
       --url <url>             App URL to connect to when using --serve-cmd
       --serve-cmd <command>   Command that starts the app server instead of static serving
+      --serve-cmd-timeout <ms>  How long to wait for the command server (default: 30000)
+      --shutdown-timeout <ms>  Grace period before force-killing the server (default: 5000)
       --dry-run               Render and report without writing files
       --log-level <level>     silent | error | warn | info | debug (default: info)
       --yes, -y               Accept every default, for a shell without a terminal
@@ -105,16 +128,34 @@ async function main() {
       'max-routes': { type: 'string' },
       concurrency: { type: 'string' },
       timeout: { type: 'string' },
+      'quiet-period': { type: 'string' },
+      'scroll-step-delay': { type: 'string' },
+      'max-cached-bytes': { type: 'string' },
+      'serve-cmd-timeout': { type: 'string' },
+      'shutdown-timeout': { type: 'string' },
+      viewport: { type: 'string' },
+      'ready-flag': { type: 'string' },
+      'ready-selector': { type: 'string' },
+      headless: { type: 'boolean' },
       'wait-for': { type: 'string' },
       browser: { type: 'string' },
       'no-browser-download': { type: 'boolean' },
       'browser-download-hash': { type: 'string' },
+      'browser-download-version': { type: 'string' },
       'storage-state': { type: 'string' },
       'no-verify': { type: 'boolean' },
       'verify-changed-only': { type: 'boolean' },
       'fail-on-hydration-error': { type: 'boolean' },
+      'fail-on-error': { type: 'boolean' },
       'fail-on-rerender': { type: 'boolean' },
       'fail-on-page-error': { type: 'boolean' },
+      'fail-on-empty-page': { type: 'boolean' },
+      'fail-on-console-error': { type: 'boolean' },
+      'fail-on-failed-request': { type: 'boolean' },
+      'fail-on-duplicate-content': { type: 'boolean' },
+      'fail-on-build-origin-metadata': { type: 'boolean' },
+      'fail-on-undetected': { type: 'boolean' },
+      'fail-on-verification-error': { type: 'boolean' },
       'no-block-third-party': { type: 'boolean' },
       'block-third-party': { type: 'boolean' },
       'allowed-hosts': { type: 'string', multiple: true },
@@ -125,6 +166,7 @@ async function main() {
       flat: { type: 'boolean' },
       'not-found': { type: 'string' },
       destination: { type: 'string' },
+      'clean-destination': { type: 'boolean' },
       'save-as': { type: 'string' },
       'user-agent': { type: 'string' },
       'metadata-site-url': { type: 'string' },
@@ -132,12 +174,14 @@ async function main() {
       'metadata-title-template': { type: 'string' },
       'metadata-default-image': { type: 'string' },
       'metadata-trailing-slash': { type: 'string' },
+      'metadata-base': { type: 'string' },
       'inline-css': { type: 'string' },
       'critical-css-preload': { type: 'string' },
       csp: { type: 'string' },
       'minify-html': { type: 'boolean' },
       'minify-css': { type: 'boolean' },
       'no-preconnect-third-party': { type: 'boolean' },
+      'preconnect-third-party': { type: 'boolean' },
       'preload-images': { type: 'boolean' },
       'preload-manifest': { type: 'boolean' },
       sitemap: { type: 'boolean' },
@@ -149,6 +193,8 @@ async function main() {
       'external-scripts': { type: 'boolean' },
       'no-remove-blobs': { type: 'boolean' },
       'remove-attributes': { type: 'string', multiple: true },
+      'no-strip-build-origin-metadata': { type: 'boolean' },
+      'prune-stale-routes': { type: 'boolean' },
       'ignore-https-errors': { type: 'boolean' },
       'browser-args': { type: 'string', multiple: true },
       url: { type: 'string' },
@@ -205,18 +251,52 @@ function cliOptions({ values, positionals }) {
   if (values['max-routes'] !== undefined) options.maxRoutes = Number(values['max-routes']);
   if (values.concurrency !== undefined) options.concurrency = Number(values.concurrency);
   if (values.timeout !== undefined) options.timeout = Number(values.timeout);
+  if (values['quiet-period'] !== undefined) options.quietPeriod = Number(values['quiet-period']);
+  if (values['scroll-step-delay'] !== undefined) {
+    options.scrollStepDelay = Number(values['scroll-step-delay']);
+  }
+  if (values['max-cached-bytes'] !== undefined) {
+    options.maxCachedBytes = Number(values['max-cached-bytes']);
+  }
+  if (values['serve-cmd-timeout'] !== undefined) {
+    options.serveCmdTimeout = Number(values['serve-cmd-timeout']);
+  }
+  if (values['shutdown-timeout'] !== undefined) {
+    options.shutdownTimeout = Number(values['shutdown-timeout']);
+  }
+  if (values.viewport !== undefined) {
+    const match = /^(\d+)x(\d+)$/i.exec(values.viewport);
+    if (!match) throw new Error('viewport must look like 1280x720');
+    options.viewport = { width: Number(match[1]), height: Number(match[2]) };
+  }
+  if (values['ready-selector'] !== undefined) options.readySelector = values['ready-selector'];
+  if (values['ready-flag'] !== undefined) options.readyFlag = values['ready-flag'];
+  if (values.headless !== undefined) options.headless = values.headless;
   if (values['wait-for'] !== undefined) options.waitFor = values['wait-for'];
   if (values.browser !== undefined) options.browser = values.browser;
   if (values['no-browser-download']) options.browserDownload = false;
   if (values['browser-download-hash'] !== undefined) {
     options.browserDownloadHash = values['browser-download-hash'];
   }
+  if (values['browser-download-version'] !== undefined) {
+    options.browserDownloadVersion = values['browser-download-version'];
+  }
   if (values['storage-state'] !== undefined) options.storageState = values['storage-state'];
   if (values['no-verify']) options.verify = false;
   if (values['verify-changed-only']) options.verifyChangedOnly = true;
   if (values['fail-on-hydration-error']) options.failOnHydrationError = true;
   if (values['fail-on-rerender']) options.failOnRerender = true;
   if (values['fail-on-page-error']) options.failOnPageError = true;
+  if (values['fail-on-error'] !== undefined) options.failOnError = values['fail-on-error'];
+  if (values['fail-on-empty-page'] !== undefined) {
+    options.failOnEmptyPage = values['fail-on-empty-page'];
+  }
+  if (values['fail-on-console-error']) options.failOnConsoleError = true;
+  if (values['fail-on-failed-request']) options.failOnFailedRequest = true;
+  if (values['fail-on-duplicate-content']) options.failOnDuplicateContent = true;
+  if (values['fail-on-build-origin-metadata']) options.failOnBuildOriginMetadata = true;
+  if (values['fail-on-undetected']) options.failOnUndetected = true;
+  if (values['fail-on-verification-error']) options.failOnVerificationError = true;
   if (values['no-block-third-party']) options.blockThirdParty = false;
   if (values['block-third-party']) options.blockThirdParty = true;
   if (values['allowed-hosts'] !== undefined)
@@ -228,6 +308,7 @@ function cliOptions({ values, positionals }) {
   if (values.flat) options.flatOutput = true;
   if (values['not-found'] !== undefined) options.notFoundRoute = values['not-found'];
   if (values.destination !== undefined) options.destination = values.destination;
+  if (values['clean-destination']) options.cleanDestination = true;
   if (values['save-as'] !== undefined) options.saveAs = values['save-as'];
   if (values['user-agent'] !== undefined) options.userAgent = values['user-agent'];
   const metadata = metadataOptions(values);
@@ -241,6 +322,7 @@ function cliOptions({ values, positionals }) {
   if (values['minify-html']) options.minifyHtml = true;
   if (values['minify-css']) options.minifyCss = true;
   if (values['no-preconnect-third-party']) options.preconnectThirdParty = false;
+  if (values['preconnect-third-party']) options.preconnectThirdParty = true;
   if (values['preload-images']) options.preloadImages = true;
   if (values['preload-manifest']) options.preloadManifest = true;
   if (values.sitemap) options.sitemap = true;
@@ -256,6 +338,8 @@ function cliOptions({ values, positionals }) {
   if (values['remove-attributes'] !== undefined) {
     options.removeAttributes = splitList(values['remove-attributes']);
   }
+  if (values['no-strip-build-origin-metadata']) options.stripBuildOriginMetadata = false;
+  if (values['prune-stale-routes']) options.pruneStaleRoutes = true;
   if (values['ignore-https-errors']) options.ignoreHTTPSErrors = true;
   if (values['browser-args'] !== undefined) options.browserArgs = splitList(values['browser-args']);
   if (values.url !== undefined) options.url = values.url;
@@ -298,14 +382,14 @@ async function runInit({ values }) {
     force: values.force === true,
   });
   log.success(`Wrote ${CONFIG_FILE}`);
-  printNextSteps({ detected, log });
+  printNextSteps({ detected, log, tag: readVersion().includes('-') ? '@next' : '' });
 }
 
 // Turns the flags the CLI already understands into the wizard's starting answers.
 function defaultsFromFlags(detected, flags) {
   return {
     sourceDir: flags.sourceDir ?? detected.sourceDir,
-    base: flags.base ?? '/',
+    base: flags.base ?? detected.base ?? '/',
     include: flags.include ?? ['/'],
     crawl: flags.crawl ?? true,
     siteUrl: flags.metadata?.siteUrl ?? '',
@@ -388,9 +472,9 @@ function validatedAnswers(answers, log) {
 }
 
 // Prints what to do next: install if needed, run it, and where the head layer goes.
-function printNextSteps({ detected, log }) {
+function printNextSteps({ detected, log, tag = '' }) {
   const run = runnerCommand(detected.runner, PACKAGE_NAME);
-  const install = installCommand(detected.runner);
+  const install = installCommand(detected.runner, tag);
   log.info('');
   log.info('Next steps:');
   if (!detected.installed) log.info(`  Install      ${install}`);
@@ -419,10 +503,11 @@ function runnerCommand(runner, binary) {
 }
 
 // Builds the command that installs this package as a dev dependency.
-function installCommand(runner) {
-  if (runner === 'pnpm') return `pnpm add -D ${PACKAGE_NAME}`;
-  if (runner === 'yarn') return `yarn add -D ${PACKAGE_NAME}`;
-  return `npm install --save-dev ${PACKAGE_NAME}`;
+function installCommand(runner, tag = '') {
+  const pkg = `${PACKAGE_NAME}${tag}`;
+  if (runner === 'pnpm') return `pnpm add -D ${pkg}`;
+  if (runner === 'yarn') return `yarn add -D ${pkg}`;
+  return `npm install --save-dev ${pkg}`;
 }
 
 // Collects the metadata flags, or null when none was passed so a config file value survives.
@@ -441,6 +526,7 @@ function metadataOptions(values) {
   if (values['metadata-trailing-slash'] !== undefined) {
     metadata.trailingSlash = values['metadata-trailing-slash'];
   }
+  if (values['metadata-base'] !== undefined) metadata.base = values['metadata-base'];
   return Object.keys(metadata).length > 0 ? metadata : null;
 }