snappy-prerender 2.7.0 → 2.8.1

package/src/core/seo-locale.js

@@ -0,0 +1,234 @@
+import { matchesPattern } from './routes.js';
+
+/**
+ * Resolves the SEO locale recipe for one route. The code comes from the route locale in
+ * path mode, from the active locale in single mode, or from seoLocale.code standalone.
+ * @param {object} config
+ * @param {object | null} locale
+ * @param {string} route
+ * @returns {object | null}
+ */
+export function resolveSeoLocale(config, locale, route) {
+  const seo = config.seoLocale;
+  if (!seo) return null;
+  if (!(seo.routes ?? []).some((pattern) => matchesPattern(route, pattern))) return null;
+  const code =
+    config.locales?.mode === 'path'
+      ? locale?.code
+      : (config.locales?.active ?? seo.code ?? locale?.code);
+  if (!code) return null;
+  return { ...seo, code, value: seo.value ?? code };
+}
+
+/**
+ * Seeds local storage before the app bundle runs. The init script runs on the page's
+ * origin, which is what makes it work with the ephemeral prerender server.
+ * @param {import('playwright-core').Page} page
+ * @param {object} seo
+ */
+export async function seedPageStorage(page, seo) {
+  if (seo.source !== 'localStorage' && seo.source !== 'both') return;
+  await seedLocalStorage(page, { [seo.localStorageKey]: seo.value }, seo.overwrite);
+}
+
+/**
+ * Seeds a fixed set of local storage entries before the app boots.
+ * @param {import('playwright-core').Page} page
+ * @param {Record<string, string>} entries
+ * @param {boolean} overwrite
+ */
+export async function seedLocalStorage(page, entries, overwrite = true) {
+  if (!entries || Object.keys(entries).length === 0) return;
+  await page.addInitScript(
+    ({ values, replace }) => {
+      try {
+        for (const [key, value] of Object.entries(values)) {
+          if (replace || window.localStorage.getItem(key) === null) {
+            window.localStorage.setItem(key, value);
+          }
+        }
+      } catch {
+        // Local storage can be unavailable in private contexts; the app still renders its default.
+      }
+    },
+    { values: entries, replace: overwrite },
+  );
+}
+
+/**
+ * Seeds the locale cookie in the browser context, using the current origin when no
+ * explicit domain is configured.
+ * @param {import('playwright-core').BrowserContext} context
+ * @param {string} origin
+ * @param {object} seo
+ */
+export async function seedContextCookie(context, origin, seo) {
+  if (seo.source !== 'cookie' && seo.source !== 'both') return;
+  if (!seo.overwrite) {
+    const existing = await context.cookies();
+    if (existing.some((cookie) => cookie.name === seo.cookie.name)) return;
+  }
+  await seedCookies(context, origin, [
+    {
+      ...seo.cookie,
+      value: seo.value,
+      httpOnly: false,
+    },
+  ]);
+}
+
+/**
+ * Adds cookies with the same attributes to the render and verification contexts.
+ * @param {import('playwright-core').BrowserContext} context
+ * @param {string} origin
+ * @param {Array<object>} cookies
+ */
+export async function seedCookies(context, origin, cookies = []) {
+  if (!Array.isArray(cookies) || cookies.length === 0) return;
+  const entries = cookies.map((cookie) => {
+    const secure = cookie.secure === true && !origin.startsWith('http://');
+    const sameSite = normaliseSameSite(cookie.sameSite);
+    const entry = {
+      name: cookie.name,
+      value: String(cookie.value),
+      httpOnly: cookie.httpOnly === true,
+      secure,
+      // Browsers reject SameSite=None without Secure; keep local HTTP previews usable.
+      sameSite: sameSite === 'None' && !secure ? 'Lax' : sameSite,
+      expires:
+        cookie.maxAge !== null && cookie.maxAge !== undefined
+          ? Math.floor(Date.now() / 1000) + cookie.maxAge
+          : -1,
+    };
+    if (cookie.domain) {
+      entry.domain = cookie.domain;
+      entry.path = cookie.path ?? '/';
+    } else {
+      entry.url = origin;
+    }
+    return entry;
+  });
+  await context.addCookies(entries);
+}
+
+/**
+ * Builds the small bootstrap script written into localized pages. Values are serialised as
+ * strings and cookie values are percent-encoded; no configuration value is interpolated
+ * as raw JavaScript.
+ * @param {object} seo
+ * @returns {string}
+ */
+export function buildSeoLocaleScript(seo) {
+  const key = JSON.stringify(seo.localStorageKey);
+  const value = JSON.stringify(seo.value);
+  const cookieName = JSON.stringify(seo.cookie.name);
+  const cookieAttributes =
+    `; path=${seo.cookie.path ?? '/'}` +
+    (seo.cookie.domain ? `; domain=${seo.cookie.domain}` : '') +
+    (seo.cookie.maxAge !== null && seo.cookie.maxAge !== undefined
+      ? `; max-age=${seo.cookie.maxAge}`
+      : '') +
+    `; SameSite=${normaliseSameSite(seo.cookie.sameSite)}` +
+    (seo.cookie.secure ? '; Secure' : '');
+  const cookieExpression = `${cookieName} + "=" + encodeURIComponent(${value}) + ${JSON.stringify(cookieAttributes)}`;
+  const localCondition = seo.overwrite ? 'true' : `window.localStorage.getItem(${key}) === null`;
+  const parts = ['(function () {'];
+  if (seo.source === 'localStorage' || seo.source === 'both') {
+    parts.push(
+      '  try {',
+      `    if (${localCondition}) {`,
+      `      window.localStorage.setItem(${key}, ${value});`,
+      '    }',
+      '  } catch (error) {}',
+    );
+  }
+  if (seo.source === 'cookie' || seo.source === 'both') {
+    parts.push(
+      '  try {',
+      `    var name = ${cookieName};`,
+      '    var has = document.cookie.split("; ").some(function (part) {',
+      '      return part.split("=")[0] === name;',
+      '    });',
+      `    if (${seo.overwrite ? 'true' : '!has'}) {`,
+      `      document.cookie = ${cookieExpression};`,
+      '    }',
+      '  } catch (error) {}',
+    );
+  }
+  parts.push('})();');
+  return parts.join('\n');
+}
+
+/**
+ * Inserts the bootstrap before the first head script, or at the end of the head when the
+ * document has no script. A generated marker makes reruns replace the same script.
+ * @param {object} document parse5 document
+ * @param {string} script
+ * @param {string | null} externalHref
+ */
+export function injectSeoLocaleScript(document, script, externalHref = null) {
+  const head = findHead(document);
+  if (!head) return;
+  head.childNodes = (head.childNodes ?? []).filter(
+    (node) => !node.attrs?.some((entry) => entry.name === 'data-snappy-seo-locale'),
+  );
+  const node = externalHref
+    ? {
+        nodeName: 'script',
+        tagName: 'script',
+        attrs: [
+          { name: 'src', value: externalHref },
+          { name: 'data-snappy-seo-locale', value: '' },
+        ],
+        namespaceURI: 'http://www.w3.org/1999/xhtml',
+        childNodes: [],
+        parentNode: null,
+      }
+    : {
+        nodeName: 'script',
+        tagName: 'script',
+        attrs: [{ name: 'data-snappy-seo-locale', value: '' }],
+        namespaceURI: 'http://www.w3.org/1999/xhtml',
+        childNodes: [{ nodeName: '#text', value: script, parentNode: null }],
+        parentNode: null,
+      };
+  const scriptIndex = (head.childNodes ?? []).findIndex((child) => child.tagName === 'script');
+  if (scriptIndex === -1) head.childNodes.push(node);
+  else head.childNodes.splice(scriptIndex, 0, node);
+}
+
+/**
+ * Returns the current head language and direction controls for metadata injection.
+ * @param {object | null} seo
+ * @returns {{ htmlLang: string | boolean, dir: string | null, forceHtmlLang: boolean }}
+ */
+export function seoLocaleMetadataOptions(seo) {
+  if (!seo) return { htmlLang: true, dir: null, forceHtmlLang: false };
+  return {
+    htmlLang: seo.htmlLang,
+    dir: seo.dir,
+    forceHtmlLang: seo.forceHtmlLang === true,
+  };
+}
+
+/**
+ * Normalises a cookie SameSite value to the form Playwright and document.cookie expect.
+ * @param {string | undefined} value
+ * @returns {'Strict' | 'Lax' | 'None'}
+ */
+function normaliseSameSite(value) {
+  const text = String(value ?? 'Lax').toLowerCase();
+  if (text === 'strict') return 'Strict';
+  if (text === 'none') return 'None';
+  return 'Lax';
+}
+
+/**
+ * Finds the document head in a parsed document.
+ * @param {object} document
+ * @returns {object | null}
+ */
+function findHead(document) {
+  const html = (document.childNodes ?? []).find((node) => node.tagName === 'html');
+  return (html?.childNodes ?? []).find((node) => node.tagName === 'head') ?? null;
+}

package/src/core/settle.js

@@ -112,15 +112,13 @@ export async function settlePage(page, config, tracker) {
  * normalisation.
  */
 export async function freezeAnimations(page) {
-  await page.evaluate((css) => {
+  await page.evaluate(async (css) => {
     const style = document.createElement('style');
     style.id = 'snappy-freeze';
     style.textContent = css;
     document.head.appendChild(style);
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
   }, FREEZE_CSS);
-  await page.evaluate(
-    () => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))),
-  );
 }
 
 /**

package/src/core/sitemap.js

@@ -26,7 +26,7 @@ export function buildSitemap({ files, config, maxUrls = SITEMAP_MAX_URLS }) {
         })
       : publicPath(file.file);
     entries.push({
-      loc: `${siteUrl}${toPublicPath(path, config.base)}`,
+      loc: file.localeUrl ?? `${siteUrl}${toPublicPath(path, config.base)}`,
       alternates: normaliseAlternates(file.alternates ?? [], siteUrl, config.base),
       images: config.imageSitemap ? normaliseImages(file.images ?? [], siteUrl, config.base) : [],
     });

package/src/core/text-separators.js

@@ -1,12 +1,12 @@
 /**
- * Inserts comment separators between adjacent text nodes before the DOM is
- * serialised. HTML cannot express two neighbouring text nodes, so serialising a
- * client-rendered DOM merges them, and hydration then finds one node where the
- * client expects two — which React reports as a failed hydration. React's own server
- * rendering emits the same separators, so this makes captured markup equivalent.
+ * Final page snapshot: inserts comment separators between adjacent text nodes and
+ * returns the LCP URL and anchor hrefs in the same browser round trip. HTML cannot
+ * express two neighbouring text nodes, so serialising a client-rendered DOM merges
+ * them and hydration then finds one node where the client expects two. React's own
+ * server rendering emits the same separators.
  */
-export async function separateTextNodes(page) {
-  await page.evaluate(() => {
+export async function readRenderSnapshot(page) {
+  return page.evaluate(() => {
     // Elements whose children are raw text, where a comment would corrupt the content.
     const RAW_TEXT = new Set(['SCRIPT', 'STYLE', 'TEXTAREA', 'TITLE']);
 
@@ -26,5 +26,9 @@ export async function separateTextNodes(page) {
     };
 
     separate(document.documentElement);
+    return {
+      lcpUrl: window.__snappyLcp?.at(-1)?.url ?? null,
+      hrefs: Array.from(document.querySelectorAll('a[href]'), (anchor) => anchor.href),
+    };
   });
 }

package/src/core/verify.js

@@ -1,20 +1,19 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { blockThirdPartyRequests } from './blocking.js';
+import { installClock, installClockScripts } from './clock.js';
 import { DEFAULTS } from './config.js';
 import { frameworkFromMarkers, isHydrationError } from './frameworks.js';
 import { compareContainers } from './hydration-diff.js';
+import { isHydrationAllowed, resolveHydrationPolicy } from './hydration-policy.js';
+import { localeContextOptions, localeStorageState, seedLocaleContext } from './locale-context.js';
+import { activeLocale } from './locales.js';
 import { routeToFile } from './output.js';
-import { isPageEmpty } from './page-content.js';
+import { CONTAINER_SELECTOR, readBootState } from './page-content.js';
 import { resolveRouteConfig } from './route-config.js';
 import { normaliseRoute, toServerUrl } from './routes.js';
-import { mapLimit } from './scheduler.js';
 import { settlePage, trackNetwork } from './settle.js';
 
-// Containers used by the common setups, so the probe can find the prerendered
-// subtree without configuration.
-const CONTAINER_SELECTOR = '#root, #app, #__next';
-
 /**
  * Page-side probe installed before navigation. It remembers the first prerendered
  * child of the app container, which is what lets the verifier tell hydration from a
@@ -57,9 +56,53 @@ export function classifyBoot({ markupPreserved, frameworkMounted }) {
  * hydration errors plus how each route booted. This is the pass that catches markup
  * that only breaks once the app re-attaches, and apps that never attach to it at all.
  */
-export async function verifyRoutes({ browser, origin, routes, config, outputDir = null }) {
-  const { results, errors } = await mapLimit(routes, config.concurrency, (route) =>
-    verifyRoute({ browser, origin, route, config: resolveRouteConfig(config, route), outputDir }),
+export async function verifyRoutes({
+  browser,
+  origin,
+  routes,
+  config,
+  outputDir = null,
+  routeLocales = new Map(),
+}) {
+  const policySkipped = routes.filter((route) => resolveHydrationPolicy(config, route) === 'skip');
+  const policySkippedSet = new Set(policySkipped);
+  const toVerify = routes.filter((route) => !policySkippedSet.has(route));
+  const results = new Array(toVerify.length).fill(undefined);
+  const errors = [];
+  let cursor = 0;
+  const canReuse = config.reuseVerificationContext && !config.locales && !config.seoLocale;
+  const workerCount = Math.max(1, Math.min(config.concurrency, toVerify.length || 1));
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      let sharedContext = null;
+      try {
+        if (canReuse && toVerify.length > 0) {
+          sharedContext = await createContext(browser, config, activeLocale(config.locales));
+        }
+        while (cursor < toVerify.length) {
+          const index = cursor;
+          cursor += 1;
+          const route = toVerify[index];
+          try {
+            results[index] = await verifyRoute({
+              browser,
+              origin,
+              route,
+              config: resolveRouteConfig(config, route),
+              outputDir,
+              context: sharedContext,
+              locale:
+                routeLocales.get(route)?.locale ??
+                (config.locales?.mode === 'single' ? activeLocale(config.locales) : null),
+            });
+          } catch (error) {
+            errors.push({ item: route, error });
+          }
+        }
+      } finally {
+        if (sharedContext) await sharedContext.close();
+      }
+    }),
   );
   const verified = results.filter(Boolean);
   const modes = { hydrated: 0, 're-rendered': 0, undetected: 0, unknown: 0 };
@@ -73,26 +116,51 @@ export async function verifyRoutes({ browser, origin, routes, config, outputDir
     routes: verified,
     modes,
     frameworks,
+    allowed: verified.filter((entry) => entry.allowed).length,
+    allowedRerender: verified.filter((entry) => entry.allowed && entry.mode === 're-rendered')
+      .length,
+    skippedRoutes: policySkipped,
     ok: verified.every((entry) => entry.ok) && errors.length === 0,
     errors: errors.map(({ item, error }) => ({ route: item, message: error.message })),
   };
 }
 
-/**
- * Verifies one route against the same request rules as the render pass, so what is
- * verified matches what was rendered.
- */
-async function verifyRoute({ browser, origin, route, config, outputDir }) {
-  const context = await browser.newContext({
+// Creates the browser context a verification worker reuses across routes.
+function createContext(browser, config, locale = null) {
+  return browser.newContext({
     viewport: config.viewport,
-    storageState: config.storageState ?? undefined,
+    storageState: localeStorageState(config, locale),
     userAgent:
       config.userAgent === DEFAULTS.userAgent ? undefined : (config.userAgent ?? undefined),
     ignoreHTTPSErrors: config.ignoreHTTPSErrors,
     reducedMotion: config.freezeAnimations ? 'reduce' : 'no-preference',
     serviceWorkers: 'block',
+    ...localeContextOptions(config, locale),
+  });
+}
+
+/**
+ * Verifies one route against the same request rules as the render pass, so what is
+ * verified matches what was rendered. A supplied context is reused by the worker; the
+ * page is always fresh.
+ */
+async function verifyRoute({
+  browser,
+  origin,
+  route,
+  config,
+  outputDir,
+  context = null,
+  locale = null,
+}) {
+  const ownsContext = context === null;
+  const activeContext = context ?? (await createContext(browser, config, locale));
+  const page = await activeContext.newPage();
+  await installClock(page, config.fixedTime ?? null);
+  await installClockScripts(page, {
+    fixedTime: config.fixedTime ?? null,
+    randomSeed: config.randomSeed ?? null,
   });
-  const page = await context.newPage();
   const consoleMessages = [];
   const pageMessages = [];
   page.on('console', (message) => {
@@ -105,6 +173,15 @@ async function verifyRoute({ browser, origin, route, config, outputDir }) {
     if (config.blockThirdParty) {
       await blockThirdPartyRequests(page, origin, config.allowedHosts);
     }
+    await seedLocaleContext({
+      page,
+      context: activeContext,
+      origin,
+      config,
+      route,
+      locale,
+      phase: 'verify',
+    });
     await page.addInitScript(bootProbe);
     const response = await page.goto(toServerUrl(route, config.base, origin), {
       waitUntil: 'domcontentloaded',
@@ -112,47 +189,12 @@ async function verifyRoute({ browser, origin, route, config, outputDir }) {
     });
     const status = response?.status() ?? null;
     await settlePage(page, config, tracker);
-    const empty = await isPageEmpty(page);
-    const statusCode = await page.evaluate(() => {
-      const marker = document.querySelector('meta[name="prerender-status-code"]');
-      if (!marker) return null;
-      const value = Number.parseInt(marker.getAttribute('content') ?? '', 10);
-      return Number.isFinite(value) ? value : null;
-    });
+    const { empty, statusCode, markers, markupPreserved } = await readBootState(page);
     const notFoundRoute = config.notFoundRoute ? normaliseRoute(config.notFoundRoute) : null;
     const isNotFoundRoute = notFoundRoute !== null && normaliseRoute(route) === notFoundRoute;
     const notFound = statusCode === 404 || isNotFoundRoute;
 
-    const boot = await page.evaluate((selector) => {
-      const probe = window.__snappyBoot ?? {};
-      const container =
-        document.querySelector(selector) ?? document.body?.firstElementChild ?? null;
-      const markers = container
-        ? {
-            react: Object.keys(container).some(
-              (key) => key.startsWith('__reactContainer') || key === '_reactRootContainer',
-            ),
-            vue: Boolean(
-              container.__vue_app__ ||
-                container.__vueParentComponent ||
-                container._vnode ||
-                container.__vue__,
-            ),
-            preact: Boolean(
-              container.__k ||
-                container._children ||
-                container.firstElementChild?.__k ||
-                container.firstElementChild?._children,
-            ),
-            svelte: Boolean(
-              container.__svelte_meta || container.querySelector?.('[data-svelte-h]'),
-            ),
-          }
-        : {};
-      const child = probe.prerenderedChild ?? null;
-      return { markers, markupPreserved: child ? child.isConnected : null };
-    }, CONTAINER_SELECTOR);
-    const detected = frameworkFromMarkers(boot.markers, config.framework);
+    const detected = frameworkFromMarkers(markers, config.framework);
     // Classify only after the framework is known, so an explicit `framework` choice and
     // the detected framework select the matching message patterns.
     const hydrationErrors = [];
@@ -167,7 +209,7 @@ async function verifyRoute({ browser, origin, route, config, outputDir }) {
       else pageErrors.push(message);
     }
     const mode = classifyBoot({
-      markupPreserved: boot.markupPreserved,
+      markupPreserved,
       frameworkMounted: detected.mounted,
     });
     let firstMismatch = null;
@@ -180,6 +222,9 @@ async function verifyRoute({ browser, origin, route, config, outputDir }) {
       const expectedHtml = await fs.readFile(file, 'utf8').catch(() => null);
       if (liveHtml && expectedHtml) firstMismatch = compareContainers(expectedHtml, liveHtml);
     }
+    const hydrationPolicy = resolveHydrationPolicy(config, route);
+    const allowed = isHydrationAllowed(hydrationPolicy, { mode, hydrationErrors });
+    const effectiveHydrationErrors = allowed ? [] : hydrationErrors;
 
     return {
       route,
@@ -188,19 +233,23 @@ async function verifyRoute({ browser, origin, route, config, outputDir }) {
       notFound,
       framework: detected.name,
       empty,
-      hydrationErrors,
+      hydrationErrors: effectiveHydrationErrors,
+      ignoredHydrationErrors: allowed ? hydrationErrors : [],
+      hydrationPolicy,
+      allowed,
       consoleErrors,
       pageErrors,
       ok:
-        hydrationErrors.length === 0 &&
+        effectiveHydrationErrors.length === 0 &&
         (status === null || status < 400 || (isNotFoundRoute && status === 404)) &&
         !empty,
       mode,
       firstMismatch,
-      markupPreserved: boot.markupPreserved,
+      markupPreserved,
     };
   } finally {
     tracker.stop();
-    await context.close();
+    await page.close();
+    if (ownsContext) await activeContext.close();
   }
 }