snappy-prerender 2.6.0 → 2.8.0

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

@@ -15,7 +15,7 @@ export function buildSitemap({ files, config, maxUrls = SITEMAP_MAX_URLS }) {
   if (!siteUrl) return null;
   const notFound = config.notFoundRoute ? normaliseRoute(config.notFoundRoute) : null;
 
-  const locs = new Set();
+  const entries = [];
   for (const file of files) {
     if (!file.file.endsWith('.html') || file.noindex) continue;
     if (file.route && notFound && normaliseRoute(file.route) === notFound) continue;
@@ -25,31 +25,40 @@ export function buildSitemap({ files, config, maxUrls = SITEMAP_MAX_URLS }) {
           trailingSlash: config.metadata?.trailingSlash,
         })
       : publicPath(file.file);
-    locs.add(`${siteUrl}${toPublicPath(path, config.base)}`);
+    entries.push({
+      loc: file.localeUrl ?? `${siteUrl}${toPublicPath(path, config.base)}`,
+      alternates: normaliseAlternates(file.alternates ?? [], siteUrl, config.base),
+      images: config.imageSitemap ? normaliseImages(file.images ?? [], siteUrl, config.base) : [],
+    });
   }
-  if (locs.size === 0) return null;
+  if (entries.length === 0) return null;
 
-  const sorted = [...locs].sort();
+  entries.sort((a, b) => a.loc.localeCompare(b.loc));
   const chunks = [];
-  for (let index = 0; index < sorted.length; index += maxUrls) {
-    chunks.push(sorted.slice(index, index + maxUrls));
+  for (let index = 0; index < entries.length; index += maxUrls) {
+    chunks.push(entries.slice(index, index + maxUrls));
   }
 
   if (chunks.length === 1) {
-    return { files: [{ name: 'sitemap.xml', contents: urlSet(chunks[0]) }], routes: sorted.length };
+    return {
+      files: [{ name: 'sitemap.xml', contents: urlSet(chunks[0]) }],
+      routes: entries.length,
+      locs: entries.map((entry) => entry.loc),
+    };
   }
 
-  const entries = chunks.map((chunk, index) => {
+  const chunksWithNames = chunks.map((chunk, index) => {
     const name = `sitemap-${index + 1}.xml`;
     const loc = `${siteUrl}${toPublicPath(`/${name}`, config.base)}`;
     return { name, contents: urlSet(chunk), loc };
   });
   return {
     files: [
-      { name: 'sitemap.xml', contents: sitemapIndex(entries) },
-      ...entries.map(({ name, contents }) => ({ name, contents })),
+      { name: 'sitemap.xml', contents: sitemapIndex(chunksWithNames) },
+      ...chunksWithNames.map(({ name, contents }) => ({ name, contents })),
     ],
-    routes: sorted.length,
+    routes: entries.length,
+    locs: entries.map((entry) => entry.loc),
   };
 }
 
@@ -75,9 +84,76 @@ export function withSitemapDirective(robots, sitemapUrl) {
 }
 
 // Builds one urlset document.
-function urlSet(locs) {
-  const urls = locs.map((loc) => `  <url>\n    <loc>${escapeXml(loc)}</loc>\n  </url>`).join('\n');
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`;
+function urlSet(entries) {
+  const hasAlternates = entries.some((entry) => entry.alternates.length > 0);
+  const hasImages = entries.some((entry) => entry.images.length > 0);
+  const namespaces = [
+    'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"',
+    hasAlternates ? 'xmlns:xhtml="http://www.w3.org/1999/xhtml"' : null,
+    hasImages ? 'xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"' : null,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  const urls = entries
+    .map((entry) => {
+      const lines = [`    <loc>${escapeXml(entry.loc)}</loc>`];
+      for (const alternate of entry.alternates) {
+        lines.push(
+          `    <xhtml:link rel="alternate" hreflang="${escapeXml(alternate.hreflang)}" href="${escapeXml(alternate.href)}"/>`,
+        );
+      }
+      for (const image of entry.images) {
+        lines.push(
+          `    <image:image>\n      <image:loc>${escapeXml(image)}</image:loc>\n    </image:image>`,
+        );
+      }
+      return `  <url>\n${lines.join('\n')}\n  </url>`;
+    })
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset ${namespaces}>\n${urls}\n</urlset>\n`;
+}
+
+// Resolves hreflang links and removes duplicates.
+function normaliseAlternates(alternates, siteUrl, base) {
+  const seen = new Set();
+  const result = [];
+  for (const alternate of alternates) {
+    const href = absoluteSitemapUrl(alternate.href, siteUrl, base);
+    if (!href) continue;
+    const key = `${alternate.hreflang}|${href}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push({ hreflang: alternate.hreflang, href });
+  }
+  return result;
+}
+
+// Resolves image URLs to absolute same-origin URLs.
+function normaliseImages(images, siteUrl, base) {
+  const seen = new Set();
+  const result = [];
+  for (const image of images) {
+    const absolute = absoluteSitemapUrl(image, siteUrl, base);
+    if (!absolute || new URL(absolute).origin !== new URL(siteUrl).origin) continue;
+    if (seen.has(absolute)) continue;
+    seen.add(absolute);
+    result.push(absolute);
+  }
+  return result;
+}
+
+// Resolves a site-relative path against the public base, leaving absolute URLs alone.
+function absoluteSitemapUrl(value, siteUrl, base) {
+  if (!value) return null;
+  const raw = String(value);
+  if (/^https?:\/\//i.test(raw)) return raw;
+  if (raw.startsWith('//')) return `https:${raw}`;
+  const basePrefix = base === '/' ? '' : base.slice(0, -1);
+  if (basePrefix && (raw === basePrefix || raw.startsWith(`${basePrefix}/`))) {
+    return `${siteUrl}${raw}`;
+  }
+  const path = raw.startsWith('/') ? raw : `/${raw}`;
+  return `${siteUrl}${basePrefix}${path}`;
 }
 
 // Builds the sitemap index that points at the numbered sitemaps.

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),
+    };
   });
 }