snappy-prerender 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -6,6 +6,55 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 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.8.0] - 2026-10-31
+
+### Added
+
+- `freezeTime`, `timezone` and `randomSeed` make `Date`/`Date.now()` and optional
+  `Math.random()` deterministic across render and verification. `SOURCE_DATE_EPOCH` is
+  honoured, and pages can read `window.__SNAPPY_NOW__` / `window.__SNAPPY_NOW_ISO__`.
+- `hydration.allowRerender` and `hydration.skip`, plus `routeOverrides[].hydration`, let
+  explicitly dynamic routes re-render without being reported as failures.
+- `locales` adds path or single locale modes with automatic `<html lang>`, canonical,
+  `og:locale`, `og:locale:alternate`, self/alternate/`x-default` hreflang, sitemap
+  alternates, translated route maps and hreflang audit rules.
+- `seoLocale` seeds a cookie or `localStorage` locale before render and verification, and
+  optionally writes a pre-app bootstrap into the output. It supports localStorage, cookie
+  or both, `overwrite`, `navigator`, `forceHtmlLang`, route scoping, CSP hash and strict
+  externalization.
+- CLI flags for the clock, hydration policies, simple locale matrices and SEO locale.
+- Report fields for the fixed clock, locale counts, per-route locale, hydration policy,
+  allowed re-renders, ignored hydration errors and generated locale scripts.
+- `Head` accepts `tags` for arbitrary `script`, `style`, `noscript` and `base` elements,
+  with attribute objects, text, trusted `noscript` HTML and explicit keys.
+- `Head` accepts `htmlAttributes`, `bodyAttributes` and `titleAttributes`, restoring the
+  document's original attributes when no Head wants them.
+- `Head` accepts `defaultTitle`, multiple `images` and multiple `alternateLocales`; repeated
+  same-name `extra` metas can opt into duplicates. These replace the client-side surface of
+  React Helmet and React Helmet Async.
+- `Head` accepts `onChangeClientState` for observing added, removed and changed entries
+  after real DOM updates.
+- React 19 native `<meta>` and `<link>` tags are adopted and updated instead of
+  duplicated. A correct native `<title>` is left to React so navigation can remove it, while
+  older template titles are removed.
+- The head entry documents `HeadProps`, `HeadTag`, `HeadAttributes` and `HeadChange` with
+  JSDoc types; the package remains plain JavaScript and adds no TypeScript files.
+
+### Changed
+
+- Final HTML processing uses one parsed document for preload injection, CSP hashes,
+  page metadata and preload resources instead of reparsing after each step.
+- Render and verification use fewer Playwright round trips.
+- Route writes, audit link checks, destination copies and sitemap-index fetches run with
+  bounded concurrency; route reports are merged in deterministic order.
+- Preload hints are sorted, so repeated builds do not reorder modulepreload links.
+- Inline stylesheet text and critical CSS processor state are cached within a run.
+- Relative route-source loading and browser/server startup overlap where safe.
+- The JSON report includes phase timings, and `npm run benchmark` measures large sites.
+- `reuseVerificationContext` optionally reuses one browser context per verification worker.
+- A not-found page's generated noindex replaces an existing robots directive instead of
+  adding a second meta tag.
+
 ## [2.7.0] - 2026-10-29
 
 ### Added

package/README.md

@@ -1,7 +1,13 @@
+<p align="center">
+  <img src="assets/snappy-logo.png" width="150" alt="snappy-prerender logo">
+</p>
+
 # snappy-prerender
 
 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)
 [![node](https://img.shields.io/node/v/snappy-prerender.svg)](https://www.npmjs.com/package/snappy-prerender)
@@ -146,27 +152,77 @@ 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:
 - `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. Duplicate identities are reduced to one.
+- 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.
+- 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.
+- `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>` and `<meta>` from JSX and leaves an existing template title alone, which can produce two titles. Use one metadata system; the run warns when a page has more than one `<title>`.
+- 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 for this entry point. Non-React code can call `setHead(id, props)` and `clearHead(id)`.
 
@@ -184,7 +240,7 @@ Findings are returned in `report.audit` and logged. They do not fail the run unl
 
 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` and `storageState` 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.
+`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.
 
@@ -217,6 +273,103 @@ A verification navigation that returns HTTP 4xx/5xx, or a container with no cont
 
 **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:
+
+```js
+snappy({
+  hydration: {
+    allowRerender: ['/status', '/live/*'],
+    skip: ['/admin/*'],
+  },
+  routeOverrides: [
+    { match: '/live/private', hydration: 'strict' },
+  ],
+});
+```
+
+`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`.
+
+## Locales and hreflang
+
+`locales` adds config-driven language metadata. Existing manual `Head` props still win; generated tags only fill missing values.
+
+```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
 
 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:
@@ -473,7 +626,13 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | `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 }`; later entries win |
+| `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 |
@@ -535,6 +694,7 @@ The function is awaited once per run, and whatever it returns must be a plain op
 | `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 |
@@ -577,7 +737,6 @@ The report exposes `routes`, `files` (with per-route `status` and `noindex`), `r
 [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)

package/docs/limitations.md

@@ -6,7 +6,10 @@
 - **Hydration mismatches are your app's to fix.** The verifier tells you exactly which route
   and which framework error. Common causes: `Date.now()`, `Math.random()`, `localStorage`
   reads during render, viewport-dependent markup, and CSS-in-JS that re-injects styles on
-  hydration.
+  hydration. Use `freezeTime` and `randomSeed` for deterministic build-time values, and
+  `hydration.allowRerender`/`skip` for genuinely live routes. A fixed clock is a build and
+  verification control only; production still uses real time. `performance.now()` is not
+  frozen because schedulers rely on it, and `crypto.randomUUID()` is not patched.
 - **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
@@ -14,6 +17,18 @@
   `<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.
+- **Path locale prefixes need app routing.** `locales.mode: 'path'` renders `/fr/...` pages,
+  but the app still has to route that prefix or use translated `routes`. The prerenderer
+  cannot rewrite the client router. Path mode expects one public origin; use single mode
+  for separate locale domains.
+- **Hreflang needs distinct URLs.** A locale selected only by cookie or `localStorage` is
+  not a crawlable alternate URL. Use path prefixes, subdomains or separate deployments.
+- **`seoLocale` does not create new URLs.** In single mode it produces one locale per
+  output. It seeds the prerender/verification browser and optionally writes a bootstrap,
+  but it does not create multiple locale URLs. `inject: false` localizes the HTML without
+  forcing the visitor's stored locale.
+- **`forceHtmlLang` overrides app metadata.** Use it only when the app hardcodes a language
+  that disagrees with the SEO locale.
 - **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.
@@ -23,9 +38,24 @@
   so incomplete output is never shipped silently. With `maxRoutes` or `routePriority`, the
   crawl runs in deterministic waves and reports exactly which routes did not fit in
   `truncated.droppedRoutes`.
-- **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>`.
+- **React 19 native metadata.** React hoists `<title>`, `<meta>` and `<link>` rendered in
+  JSX. `Head` adopts a matching hoisted `<meta>` or `<link>` and updates it. A hoisted
+  `<title>` that already carries the Head text is left to React (so React can remove it on
+  navigation) and older template titles are removed. `titleAttributes` apply only when
+  `Head` owns the title. An app should still use one owner per tag: either native React 19
+  metadata or `Head`. The run warns when a page ships more than one `<title>`.
+- **`Head` is client-side only.** It manages the live document head while the app runs and
+  the prerenderer captures the result. It does not provide `HelmetProvider`,
+  `helmetContext`, `HelmetData`, `renderStatic()`, streaming head extraction or a
+  server-rendering API. A server-rendered app still needs React 19 native metadata or a
+  server head manager.
+- **`tags` and `noscript.html` are trusted input.** Script and style text is escaped so it
+  cannot close its own element, but a `noscript` value is written as inner HTML exactly as
+  supplied. Never pass user-generated content there.
+- **Attributes belong to the mounted `Head`.** html, body and title attributes are restored
+  when no Head wants them, including after client navigation and prerendered hydration. A
+  value written outside the head layer while a Head owns the same attribute is overwritten
+  on the next render.
 - 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
@@ -54,5 +84,11 @@
 - **CSP `hash` mode cannot cover inline event handlers or `style=""` attributes.** Move
   those styles into a `<style>` element or a stylesheet; the audit warns when attributes are
   present.
+- **CSP `strict` does not rewrite `Head` `tags`.** An inline script supplied through
+  `tags` is the app's own policy decision; give it a `nonce` the host policy allows or
+  externalise it with `src`. The package only externalises its own captured state and SEO
+  locale bootstrap.
+- **`reuseVerificationContext` shares browser storage between routes.** Use it only for
+  stateless apps; authenticated routes can see cookies or storage from another route.
 - **Failure traces can contain request data.** `traceOnError` is opt-in and writes a
   Playwright archive under `snappy-traces/` in the output directory.

package/docs/report.md

@@ -9,18 +9,37 @@ is skipped in `--dry-run`.
   "version": 1,
   "generatedAt": "2026-10-28T00:00:00.000Z",
   "durationMs": 0,
+  "timings": { "render": 0, "write": 0, "artifacts": 0, "verify": 0, "audit": 0 },
   "ok": true,
+  "clock": { "fixedTime": 0, "timezone": "UTC" },
+  "locales": {
+    "mode": "path",
+    "default": "en",
+    "active": null,
+    "rendered": { "en": 0, "fr": 0 }
+  },
+  "seoLocale": {
+    "code": "fr",
+    "source": "both",
+    "inject": true,
+    "script": "snappy-seo-locale-abc123.js",
+    "scripts": ["snappy-seo-locale-abc123.js"]
+  },
   "summary": { "routes": 0, "files": 0, "errors": 0, "warnings": 0 },
   "verification": {
     "ok": true,
     "modes": { "hydrated": 0, "re-rendered": 0, "undetected": 0, "unknown": 0 },
     "frameworks": { "react": 0 },
     "skipped": 0,
+    "policySkipped": 0,
+    "allowed": 0,
+    "allowedRerender": 0,
     "errors": []
   },
   "routes": [
     {
       "route": "/",
+      "locale": "en",
       "order": 0,
       "file": "index.html",
       "status": "written",
@@ -39,12 +58,19 @@ is skipped in `--dry-run`.
         "description": "",
         "canonical": "",
         "robots": "",
+        "lang": "en",
+        "dir": null,
+        "ogLocale": "en_US",
         "h1Count": 1,
         "alternates": [],
+        "localeUrl": null,
         "images": [],
         "inlineStyleAttributes": 0
       },
       "hydrationErrors": [],
+      "ignoredHydrationErrors": [],
+      "hydrationPolicy": "strict",
+      "hydrationAllowed": false,
       "pageErrors": [],
       "consoleErrors": [],
       "failedRequests": [],
@@ -63,9 +89,10 @@ is skipped in `--dry-run`.
 }
 ```
 
-The document never includes configuration, `storageState`, captured AJAX state, cookies,
-tokens, request bodies or full asset URLs containing credentials. URLs in the JSON are
-reduced to their origin and path, and the configured `storageState` path is redacted
+The document never includes the full configuration, `storageState`, captured AJAX state,
+cookies, tokens, request bodies or full asset URLs containing credentials. It does include
+non-secret summaries of the fixed clock, locale mode and SEO locale source. URLs in the JSON
+are reduced to their origin and path, and the configured `storageState` path is redacted
 wherever it appears in a message. `order` is the crawl acceptance order; with
 `maxRoutes` or `routePriority` it follows the deterministic wave order rather than the
 alphabetical write order.
@@ -85,6 +112,9 @@ Errors:
 - `broken-internal-link` — an internal link with no written route or output file.
 - `duplicate-title` — two routes share a title.
 - `multiple-titles` — a page ships more than one document `<title>`.
+- `hreflang-invalid` — an alternate has an invalid language code.
+- `hreflang-duplicate` — the same hreflang appears more than once on a page.
+- `hreflang-missing-return` — same-build alternates do not link back to each other.
 - `sitemap-missing-page` — an indexable page is absent from the sitemap.
 - `sitemap-unknown-page` — the sitemap lists a URL with no indexable page.
 - `sitemap-noindex-page` — the sitemap lists a noindex or 404 page.
@@ -94,6 +124,9 @@ Warnings:
 - `missing-title`, `missing-description`, `missing-canonical`.
 - `duplicate-description`.
 - `heading-count` — zero or more than one `<h1>`.
+- `hreflang-missing-self`, `hreflang-missing-x-default`.
+- `hreflang-canonical-mismatch`, `html-lang-missing`, `html-lang-mismatch`,
+  `og-locale-missing`.
 - `canonical-mismatch` — canonical differs from the expected public URL.
 - `build-origin-metadata` — a tag still points at the build server.
 - `orphan-page` — an indexable page no written page links to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snappy-prerender",
-  "version": "2.7.0",
+  "version": "2.8.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",
@@ -40,6 +40,7 @@
   },
   "files": [
     "src",
+    "assets",
     "docs",
     "CHANGELOG.md",
     "LICENSE",
@@ -51,6 +52,7 @@
   "scripts": {
     "test": "node scripts/run-tests.mjs tests/unit",
     "test:integration": "node scripts/run-tests.mjs tests/integration",
+    "benchmark": "node scripts/benchmark.mjs",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "prepublishOnly": "npm run lint && npm test && npm run test:integration"