snappy-prerender 2.6.0-rc.3 → 2.7.0

package/src/core/write.js

@@ -0,0 +1,363 @@
+import { createHash } from 'node:crypto';
+import { findBuildOriginUrls } from './build-origin.js';
+import { applyCspHashes } from './csp.js';
+import { inlineCriticalCss } from './inline-css.js';
+import { minifyHtml } from './minify.js';
+import { normaliseHtml } from './normalize.js';
+import {
+  findOutputCollisions,
+  routeToFile,
+  routeToScreenshotFile,
+  writeBufferIfChanged,
+  writeFileIfChanged,
+  writeRouteHtml,
+} from './output.js';
+import { collectPageMeta } from './page-meta.js';
+import { collectScriptSources, injectPreloadLinks } from './preload-links.js';
+import { collectPageResources } from './preload-manifest.js';
+import { resolveRouteConfig } from './route-config.js';
+import { normaliseRoute, toPublicPath } from './routes.js';
+
+/**
+ * Writes every rendered route and returns the routes that can be verified. A write
+ * failure is recorded against its route instead of aborting the remaining writes.
+ */
+export async function writeAllRoutes({
+  rendered,
+  outputDir,
+  config,
+  log,
+  report,
+  state,
+  manifestEntries,
+}) {
+  const sorted = [...report.routes].sort();
+  const conflicted = reportOutputCollisions({ routes: sorted, config, log, report });
+
+  await writeStateScripts({ rendered, outputDir, config, log, report });
+
+  const verifiable = [];
+  const hashes = new Map();
+  for (const route of sorted) {
+    if (conflicted.has(route)) continue;
+    try {
+      const routeConfig = resolveRouteConfig(config, route);
+      const result = rendered.get(route);
+      const { file, resources } = await writeRouteOutput({
+        route,
+        result,
+        outputDir,
+        config: routeConfig,
+        log,
+        state,
+        report,
+      });
+      report.files.push(file);
+      report.routeDetails.push({
+        route,
+        order: result.order ?? null,
+        file: file.file,
+        status: file.status,
+        bytes: file.bytes,
+        depth: result.depth ?? null,
+        attempts: result.attempts ?? 1,
+        httpStatus: result.httpStatus ?? null,
+        finalUrl: result.finalUrl ?? null,
+        empty: result.empty === true,
+        notFound: file.notFound === true,
+        noindex: file.noindex === true,
+        meta: file.meta ?? null,
+        images: file.images ?? [],
+        alternates: file.alternates ?? [],
+        mode: null,
+        framework: null,
+        hydrationErrors: [],
+        pageErrors: result.pageErrors ?? [],
+        consoleErrors: result.consoleErrors ?? [],
+        failedRequests: result.failedRequests ?? [],
+        firstMismatch: null,
+        buildOriginUrls: file.buildOriginUrls ?? [],
+      });
+      if (resources) manifestEntries.push({ route, ...resources });
+      if (file.hash) {
+        const group = hashes.get(file.hash) ?? [];
+        group.push(route);
+        hashes.set(file.hash, group);
+      }
+      verifiable.push(route);
+    } catch (error) {
+      report.errors.push({ route, message: `write failed: ${error.message}` });
+      log.error(`  write failed for ${route}: ${error.message}`);
+    }
+  }
+  reportDuplicatePages({ groups: [...hashes.values()], config, log, report });
+  return verifiable;
+}
+
+/**
+ * Reports routes that produced byte-identical HTML. The usual cause is an SPA fallback
+ * serving the shell for a path the app does not route, which would otherwise publish a
+ * copy of another page under a dead URL.
+ */
+function reportDuplicatePages({ groups, config, log, report }) {
+  for (const routes of groups) {
+    if (routes.length < 2) continue;
+    report.duplicatePages.push({ routes });
+    log.warn(
+      `identical output for ${routes.join(', ')}: check for a dead link served by the SPA fallback`,
+    );
+    if (config.failOnDuplicateContent) {
+      for (const route of routes) {
+        report.errors.push({
+          route,
+          message: `identical output to ${routes.filter((other) => other !== route).join(', ')}`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Writes the captured-state scripts routes reference when externalScripts is on. The payload
+ * is content-addressed, so routes that inject the same state share one file and a rerun
+ * leaves it untouched.
+ */
+async function writeStateScripts({ rendered, outputDir, config, log, report }) {
+  const seen = new Set();
+  for (const [route, result] of rendered) {
+    const stateScript = result?.stateScript;
+    if (!stateScript || seen.has(stateScript.file)) continue;
+    seen.add(stateScript.file);
+    if (config.dryRun) {
+      report.files.push({
+        route,
+        file: stateScript.file,
+        status: 'dry-run',
+        bytes: Buffer.byteLength(stateScript.contents),
+      });
+      continue;
+    }
+    try {
+      const written = await writeFileIfChanged({
+        dir: outputDir,
+        file: stateScript.file,
+        contents: stateScript.contents,
+      });
+      report.files.push({ route, ...written });
+      log.debug(`  wrote ${stateScript.file}: ${written.status}`);
+    } catch (error) {
+      report.errors.push({ route, message: `write failed: ${error.message}` });
+      log.error(`  write failed for ${stateScript.file}: ${error.message}`);
+    }
+  }
+}
+
+/**
+ * Records an error for every route involved in an output file collision and returns
+ * the routes to skip, so an ambiguous write can never overwrite another route.
+ */
+function reportOutputCollisions({ routes, config, log, report }) {
+  const conflicted = new Set();
+  for (const [file, colliding] of findOutputCollisions(routes, config)) {
+    for (const route of colliding) {
+      conflicted.add(route);
+      const others = colliding.filter((other) => other !== route).join(', ');
+      report.errors.push({
+        route,
+        message: `output file collision: ${file} is also written by ${others}`,
+      });
+    }
+    log.error(`  output file collision on ${file}: ${colliding.join(', ')}`);
+  }
+  return conflicted;
+}
+
+/**
+ * Applies the configured post-processing to one rendered route and writes it: DOM
+ * cleanups and link hints, critical CSS extraction, then optional minification.
+ */
+async function writeRouteOutput({ route, result, outputDir, config, log, state, report }) {
+  if (result.screenshot) {
+    const file = routeToScreenshotFile(route, config);
+    if (config.dryRun) {
+      return {
+        file: {
+          route,
+          file,
+          status: 'dry-run',
+          bytes: result.screenshot.length,
+        },
+        resources: null,
+      };
+    }
+    const written = await writeBufferIfChanged({
+      dir: outputDir,
+      file,
+      buffer: result.screenshot,
+    });
+    return { file: { route, ...written }, resources: null };
+  }
+
+  const { html, stats } = normaliseHtml(result.html, {
+    removeStyleTags: config.removeStyleTags,
+    removeScriptTags: config.removeScriptTags,
+    asyncScriptTags: config.asyncScriptTags,
+    removeBlobs: config.removeBlobs,
+    removeAttributes: config.removeAttributes,
+    stripBuildOriginMetadata: config.stripBuildOriginMetadata,
+    noindex:
+      config.notFoundRoute !== null &&
+      normaliseRoute(route) === normaliseRoute(config.notFoundRoute),
+    preconnectOrigins: config.preconnectThirdParty
+      ? [...result.collector.thirdPartyOrigins].sort()
+      : [],
+    preloadImages: config.preloadImages
+      ? [...result.collector.images].sort().map((image) => toPublicPath(image, config.base))
+      : [],
+  });
+  if (
+    stats.removedElements > 0 ||
+    stats.removedAttributes > 0 ||
+    stats.dedupedStyles > 0 ||
+    stats.hints > 0 ||
+    stats.textSeparators > 0
+  ) {
+    log.debug(
+      `  cleaned ${route}: ${stats.removedElements} element(s) removed, ${stats.removedAttributes} attribute(s) removed, ${stats.dedupedStyles} duplicate style(s), ${stats.hints} hint(s), ${stats.textSeparators} text separator(s)`,
+    );
+  }
+  if ((result.inlineCssSkipped ?? []).length > 0) {
+    log.debug(`  inline css: left ${result.inlineCssSkipped.length} stylesheet(s) as links`);
+  }
+
+  let output = html;
+  if (config.inlineCss === 'critical') {
+    output = await applyCriticalCss({ output, outputDir, config, log, state });
+  }
+  if (config.minifyHtml) {
+    output = await minifyHtml(output, config.minifyHtml, config.minifyCss);
+  }
+  const preTransformScripts = config.transformHtml ? collectScriptSources(output) : new Set();
+  if (config.transformHtml) {
+    const transformed = await config.transformHtml(output, {
+      route,
+      file: routeToFile(route, config),
+      stats,
+      config,
+    });
+    if (transformed !== null && transformed !== undefined && typeof transformed !== 'string') {
+      throw new TypeError('transformHtml must return a string, null or undefined');
+    }
+    output = transformed ?? output;
+  }
+  if (config.preloadLinks) {
+    const basePrefix = config.base === '/' ? '' : config.base.slice(0, -1);
+    const skipScripts = new Set(
+      [...preTransformScripts].map((src) => {
+        if (!src.startsWith('/')) return src;
+        const appRelative =
+          basePrefix && (src === basePrefix || src.startsWith(`${basePrefix}/`))
+            ? src.slice(basePrefix.length)
+            : src;
+        return toPublicPath(appRelative, config.base);
+      }),
+    );
+    output = injectPreloadLinks(output, {
+      scripts: config.removeScriptTags ? [] : [...result.collector.scripts],
+      fonts: result.collector.fonts,
+      lcpImage: result.lcpImage,
+      base: config.base,
+      ignoreForPreload: config.ignoreForPreload,
+      skipScripts,
+    });
+  }
+  if (config.csp === 'hash') {
+    const policy = applyCspHashes(output);
+    if (policy.existingPolicy) {
+      log.warn(`  ${route}: kept the existing CSP meta and injected no hashes`);
+      report.cspSkipped.push(route);
+    } else {
+      output = policy.html;
+      log.debug(
+        `  csp ${route}: hashed ${policy.hashedScripts} script(s) and ${policy.hashedStyles} style(s)`,
+      );
+    }
+  }
+  const meta = collectPageMeta(output);
+  warnOnBuildOriginMetadata({
+    origins: stats.metadataOrigins,
+    removed: stats.removedMetadata,
+    route,
+    log,
+    state,
+  });
+  if (meta.titleCount > 1) report.duplicateTitles.push(route);
+  const buildOrigins = findBuildOriginUrls(output);
+  if (config.failOnBuildOriginMetadata) {
+    if (buildOrigins.length > 0) {
+      const message = `metadata still points at the build server: ${buildOrigins.join(', ')}`;
+      report.errors.push({ route, message });
+      log.error(`  ${route}: ${message}`);
+    }
+  }
+  const file = await writeRouteHtml({ dir: outputDir, route, html: output, config });
+  const resources = config.preloadManifest
+    ? collectPageResources(output, { base: config.base, route })
+    : null;
+  return {
+    file: {
+      ...file,
+      // Hash the captured DOM before post-processing adds route-specific extras such as
+      // the not-found noindex, so a dead link serving the 404 page is still detected.
+      hash: createHash('sha256')
+        .update(result.html ?? output)
+        .digest('hex'),
+      noindex: meta.noindex,
+      notFound: result.notFound === true,
+      meta,
+      images: meta.images,
+      alternates: meta.alternates,
+      inlineStyleAttributes: meta.inlineStyleAttributes,
+      buildOriginUrls: buildOrigins,
+    },
+    resources,
+  };
+}
+
+/**
+ * Inlines critical CSS, or explains once why it cannot: the strategy reads stylesheets from
+ * the output directory, which a command server does not have to serve.
+ */
+async function applyCriticalCss({ output, outputDir, config, log, state }) {
+  if (!config.serveCmd) {
+    return inlineCriticalCss({
+      html: output,
+      outputDir,
+      base: config.base,
+      preload: config.criticalCssPreload,
+    });
+  }
+  if (!state.warnedCriticalCssSkipped) {
+    state.warnedCriticalCssSkipped = true;
+    log.warn(
+      "inlineCss: 'critical' is skipped with serveCmd: stylesheets are read from the output directory, which the command server does not have to serve",
+    );
+  }
+  return output;
+}
+
+/**
+ * Warns once when metadata contains the build server's origin, which means the page was
+ * composed without a public siteUrl and og:url, og:image or canonical would ship wrong.
+ */
+function warnOnBuildOriginMetadata({ origins, removed = 0, route, log, state }) {
+  if (state.warnedBuildOriginMetadata || origins.length === 0) return;
+  state.warnedBuildOriginMetadata = true;
+  log.warn(
+    `metadata on ${route} points at the build server (${origins.join(', ')}); ${
+      removed > 0
+        ? `removed ${removed} affected tag(s). Set metadata.siteUrl so canonical, og:url and og:image match the deployed site`
+        : 'set metadata.siteUrl so og:url, og:image and canonical match the deployed site'
+    }`,
+  );
+}

package/src/head/index.js

@@ -26,7 +26,7 @@ export function Head(props) {
     sequenceRef.current = sequence;
   }
 
-  const entries = buildHeadEntries(props, readMetadataDefaults());
+  const entries = buildHeadEntries(props, readMetadataDefaults(), idRef.current);
 
   // A layout effect so a route change updates the head before the browser paints, and a
   // plain effect on the server, where layout effects never run.
@@ -45,7 +45,7 @@ export function Head(props) {
  */
 export function setHead(id, props) {
   sequence += 1;
-  registerHead(id, sequence, buildHeadEntries(props, readDefaults()));
+  registerHead(id, sequence, buildHeadEntries(props, readMetadataDefaults(), id));
 }
 
 /**

package/src/head/manager.js

@@ -5,6 +5,7 @@ const CREATED_ATTRIBUTE = 'data-snappy-head-created';
 const stack = [];
 const snapshots = new WeakMap();
 const createdElements = new WeakSet();
+const htmlOriginals = new Map();
 const originals = readRecordedOriginals();
 publishOriginals();
 
@@ -56,7 +57,9 @@ function applyMerged() {
   if (typeof document === 'undefined' || !document.head) return;
   const head = document.head;
   const merged = mergeHeadEntries(stack);
-  const desired = new Map(merged.map((entry) => [headKey(entry), entry]));
+  const headEntries = merged.filter((entry) => entry.kind !== 'html');
+  const htmlEntries = merged.filter((entry) => entry.kind === 'html');
+  const desired = new Map(headEntries.map((entry) => [headKey(entry), entry]));
 
   for (const [key, entry] of desired) {
     const matches = findTags(head, key);
@@ -74,7 +77,27 @@ function applyMerged() {
     if (!desired.has(key)) releaseTag(element, key);
   }
 
-  orderTags(head, merged);
+  applyHtmlAttributes(htmlEntries);
+  orderTags(head, headEntries);
+}
+
+// Applies lang/dir to the document element and restores the original value when no Head
+// wants the attribute any more.
+function applyHtmlAttributes(entries) {
+  if (typeof document === 'undefined' || !document.documentElement) return;
+  const root = document.documentElement;
+  const desired = new Map(entries.map((entry) => [entry.key, entry.value]));
+  for (const [key, value] of desired) {
+    if (!htmlOriginals.has(key)) htmlOriginals.set(key, root.getAttribute(key));
+    root.setAttribute(key, value);
+  }
+  for (const key of [...htmlOriginals.keys()]) {
+    if (desired.has(key)) continue;
+    const previous = htmlOriginals.get(key);
+    if (previous === null) root.removeAttribute(key);
+    else root.setAttribute(key, previous);
+    htmlOriginals.delete(key);
+  }
 }
 
 /**
@@ -87,6 +110,9 @@ function findTags(head, key) {
     const title = head.querySelector('title');
     return title ? [title] : [];
   }
+  const owned = head.querySelector(`[${OWNER_ATTRIBUTE}="${cssEscape(key)}"]`);
+  if (owned) return [owned];
+  if (key.startsWith('link:')) return findLinkTags(head, key.slice(5));
   const [kind, attribute, ...rest] = key.split(':');
   const value = rest.join(':');
   if (
@@ -95,18 +121,32 @@ function findTags(head, key) {
   ) {
     return [...head.querySelectorAll(`meta[${attribute}="${cssEscape(value)}"]`)];
   }
-  if (kind === 'link' && attribute === 'rel') return findRelLinks(head, value);
-  const owned = head.querySelector(`[${OWNER_ATTRIBUTE}="${cssEscape(key)}"]`);
-  return owned ? [owned] : [];
+  return [];
 }
 
-// Matches links by rel, and by href when the key carries one, so two links that share a rel
-// but point elsewhere stay distinct.
-function findRelLinks(head, value) {
-  const [rel, href] = value.split('|');
-  const links = [...head.querySelectorAll(`link[rel="${cssEscape(rel)}"]`)];
-  if (href === undefined) return links;
-  return links.filter((link) => link.getAttribute('href') === href);
+// Matches links that a previous run or the app itself wrote. Head-owned links carry the
+// owner attribute and are found above; this handles adoption on the first run.
+function findLinkTags(head, spec) {
+  const links = [...head.querySelectorAll('link')];
+  if (spec.startsWith('rel:')) {
+    const [rel, hreflang, href] = spec.slice(4).split('|');
+    return links.filter(
+      (link) =>
+        link.getAttribute('rel') === rel &&
+        (hreflang === undefined || link.getAttribute('hreflang') === hreflang) &&
+        (href === undefined || link.getAttribute('href') === href),
+    );
+  }
+  if (!spec.includes('=')) return [];
+  const attrs = Object.fromEntries(
+    spec.split('|').map((pair) => {
+      const index = pair.indexOf('=');
+      return [pair.slice(0, index), pair.slice(index + 1)];
+    }),
+  );
+  return links.filter((link) =>
+    Object.entries(attrs).every(([name, value]) => link.getAttribute(name) === value),
+  );
 }
 
 function createTag(head, entry) {
@@ -140,6 +180,7 @@ function writeTag(element, entry, key) {
     if (!Object.hasOwn(entry.attrs, attribute.name)) element.removeAttribute(attribute.name);
   }
   for (const [name, value] of Object.entries(entry.attrs)) element.setAttribute(name, value);
+  if (entry.kind === 'script') element.textContent = entry.text;
 }
 
 // Remembers what a tag looked like before the head layer first touched it, so an app-owned
@@ -155,7 +196,7 @@ function snapshotTag(element, key) {
   }
   const snapshot = {
     attrs: Object.fromEntries(attrs),
-    text: element.tagName === 'TITLE' ? element.textContent : null,
+    text: element.tagName === 'TITLE' || element.tagName === 'SCRIPT' ? element.textContent : null,
   };
   snapshots.set(element, snapshot);
   if (createdElements.has(element) || element.hasAttribute(CREATED_ATTRIBUTE)) return;

package/src/head/tags.js

@@ -1,4 +1,4 @@
-import { collectBuildOrigins } from '../core/metadata-origin.js';
+import { pagePath, withTrailingSlash } from '../core/url-policy.js';
 
 const ABSOLUTE = /^https?:\/\//i;
 const PROTOCOL_RELATIVE = /^\/\//;
@@ -11,12 +11,19 @@ const SINGLETON_LINK_RELS = new Set(['canonical']);
  * caller did not supply are simply absent, so the component never invents metadata the app
  * did not ask for.
  */
-export function buildHeadEntries(props = {}, defaults = {}) {
+export function buildHeadEntries(props = {}, defaults = {}, id = 'default') {
   const entries = [];
   const template = props.titleTemplate ?? defaults.titleTemplate ?? null;
   const siteName = props.siteName ?? defaults.siteName ?? null;
   const image = props.image ?? defaults.defaultImage ?? null;
 
+  if (typeof props.lang === 'string' && props.lang.length > 0) {
+    entries.push({ kind: 'html', key: 'lang', value: props.lang });
+  }
+  if (props.dir === 'ltr' || props.dir === 'rtl' || props.dir === 'auto') {
+    entries.push({ kind: 'html', key: 'dir', value: props.dir });
+  }
+
   const title = props.title ? applyTitleTemplate(props.title, template, siteName) : null;
   if (title) entries.push({ kind: 'title', text: title });
   if (title && props.openGraph !== false) entries.push(metaProp('og:title', title));
@@ -34,7 +41,7 @@ export function buildHeadEntries(props = {}, defaults = {}) {
     entries.push(metaProp('og:type', props.type ?? 'website'));
     if (siteName) entries.push(metaProp('og:site_name', siteName));
     if (props.locale) entries.push(metaProp('og:locale', props.locale));
-    const url = pageUrl(props.canonical ?? currentPath(), defaults);
+    const url = pageUrl(props.canonical ?? defaultPagePath(defaults), defaults);
     if (url) entries.push(metaProp('og:url', url));
     if (image) entries.push(metaProp('og:image', absoluteUrl(image, defaults)));
   }
@@ -45,11 +52,29 @@ export function buildHeadEntries(props = {}, defaults = {}) {
   }
 
   if (props.canonical !== false) {
-    const url = pageUrl(props.canonical ?? currentPath(), defaults);
+    const url = pageUrl(props.canonical ?? defaultPagePath(defaults), defaults);
     if (url)
       entries.push({ kind: 'link', key: 'rel:canonical', attrs: { rel: 'canonical', href: url } });
   }
 
+  for (const alternate of props.alternates ?? []) {
+    const href = pageUrl(alternate.href, defaults);
+    const hreflang = alternate.hreflang ?? alternate.lang;
+    if (!href || !hreflang) continue;
+    const attrs = { rel: 'alternate', hreflang, href };
+    if (alternate.type) attrs.type = alternate.type;
+    entries.push({ kind: 'link', key: `rel:alternate|${hreflang}|${href}`, attrs });
+  }
+
+  if (props.structuredData !== undefined && props.structuredData !== null) {
+    entries.push({
+      kind: 'script',
+      key: `script:ld+json:${id}`,
+      attrs: { type: 'application/ld+json' },
+      text: serializeStructuredData(props.structuredData),
+    });
+  }
+
   for (const extra of props.extra ?? []) entries.push(extraEntry(extra));
 
   return entries;
@@ -77,6 +102,8 @@ export function mergeHeadEntries(stack = []) {
  */
 export function headKey(entry) {
   if (entry.kind === 'title') return 'title';
+  if (entry.kind === 'html') return `html:${entry.key}`;
+  if (entry.kind === 'script') return entry.key;
   if (entry.kind === 'link') return `link:${entry.key ?? attrsKey(entry.attrs)}`;
   if (entry.key) return `meta:${entry.key}`;
   const name = attrsValue(entry.attrs, 'name');
@@ -88,14 +115,6 @@ export function headKey(entry) {
   return `meta:${attrsKey(entry.attrs)}`;
 }
 
-/**
- * Collects the absolute metadata URLs in a document that point at the machine the
- * prerenderer ran on, which happens when no public siteUrl was configured.
- */
-export function findBuildOriginUrls(html) {
-  return collectBuildOrigins(html);
-}
-
 // Applies the site's title template unless the title already carries its suffix or is the
 // site name itself, so an app that composed its own title never gets it suffixed twice.
 function applyTitleTemplate(title, template, siteName) {
@@ -139,23 +158,24 @@ function encodeSpaces(url) {
   return url.replace(/ /g, '%20');
 }
 
-// Applies the site's trailing slash convention to a URL, leaving the root alone.
-function withTrailingSlash(url, convention) {
-  if (convention !== 'always' && convention !== 'never') return url;
-  const [path, query] = url.split('?');
-  const isRoot = /^https?:\/\/[^/]+\/?$/i.test(path);
-  if (convention === 'always') {
-    const next = path.endsWith('/') ? path : `${path}/`;
-    return query ? `${next}?${query}` : next;
-  }
-  if (isRoot) return query ? `${path.replace(/\/$/, '/')}?${query}` : path.replace(/\/?$/, '/');
-  const next = path.replace(/\/+$/, '');
-  return query ? `${next}?${query}` : next;
+// Reads the route being rendered, which under prerendering is the page being captured,
+// and removes the public base path so absoluteUrl does not add it a second time.
+function currentPath(defaults = {}) {
+  const pathname = typeof location === 'undefined' ? '/' : location.pathname;
+  const base = defaults.base ?? '/';
+  if (base === '/') return pathname;
+  const prefix = base.replace(/\/$/, '');
+  if (pathname === prefix) return '/';
+  if (pathname.startsWith(`${prefix}/`)) return pathname.slice(prefix.length);
+  return pathname;
 }
 
-// Reads the route being rendered, which under prerendering is the page being captured.
-function currentPath() {
-  return typeof location === 'undefined' ? '/' : location.pathname;
+// Builds the default canonical path from the current route and the output's URL policy.
+function defaultPagePath(defaults) {
+  return pagePath(currentPath(defaults), {
+    flatOutput: defaults.flatOutput === true,
+    trailingSlash: defaults.trailingSlash,
+  });
 }
 
 function metaName(name, content) {
@@ -202,10 +222,29 @@ function attrsValue(attrs = {}, name) {
   return attrs[name];
 }
 
-// Keeps output deterministic: title, then name/property metas, then links.
+// Serialises JSON-LD so a value can never close the script element. The escapes remain
+// valid JSON, so crawlers parse the same object the caller supplied.
+function serializeStructuredData(value) {
+  return JSON.stringify(value).replace(
+    /[<>&\u2028\u2029]/g,
+    (char) =>
+      ({
+        '<': '\\u003C',
+        '>': '\\u003E',
+        '&': '\\u0026',
+        '\u2028': '\\u2028',
+        '\u2029': '\\u2029',
+      })[char],
+  );
+}
+
+// Keeps output deterministic: title, metas, links, JSON-LD scripts, then html attributes.
 function sortMetasFirst(entries) {
-  return [...entries].sort((a, b) => {
-    const rank = (entry) => (entry.kind === 'meta' ? 0 : 1);
-    return rank(a) - rank(b);
-  });
+  const rank = (entry) => {
+    if (entry.kind === 'meta') return 0;
+    if (entry.kind === 'link') return 1;
+    if (entry.kind === 'script') return 2;
+    return 3;
+  };
+  return [...entries].sort((a, b) => rank(a) - rank(b));
 }