freestruct 1.0.0 → 1.2.0

package/engine/seo.js

@@ -7,45 +7,197 @@
 
 import fs from 'fs';
 import path from 'path';
-import { hasSeoType } from './scan.js';
-import { pageUrlFor } from './urls.js';
+import { hasSeoType, htmlIsNoindex, htmlToText } from './scan.js';
+import { pageUrlFor, slugMatchesGlob, globSpecificity } from './urls.js';
 
 function minifyHtml(html) {
-  // Conservative HTML minifier - removes unnecessary whitespace
-  // Preserves content inside <pre>, <textarea>, <script>, <style> tags
-  let inBlock = false;
-  let result = '';
-  let i = 0;
-  while (i < html.length) {
-    if (html.slice(i, i + 5) === '<pre>') inBlock = true;
-    else if (html.slice(i, i + 10) === '<textarea') inBlock = true;
-    else if (html.slice(i, i + 8) === '<script>') inBlock = true;
-    else if (html.slice(i, i + 7) === '<style>') inBlock = true;
-    else if (html.slice(i, i + 6) === '</pre>') inBlock = false;
-    else if (html.slice(i, i + 11) === '</textarea>') inBlock = false;
-    else if (html.slice(i, i + 9) === '</script>') inBlock = false;
-    else if (html.slice(i, i + 8) === '</style>') inBlock = false;
-
-    if (inBlock) result += html[i];
-    else if (html[i] === '\n' || html[i] === '\r' || html[i] === '\t') { /* skip */ }
-    else result += html[i];
-    i++;
-  }
-  return result
+  // Conservative HTML minifier - removes unnecessary whitespace OUTSIDE
+  // verbatim blocks. The <pre>/<script>/<style>/<textarea> CONTENT is
+  // preserved byte-for-byte (README's contract): whitespace there is
+  // significant (code fences, inline JS with `//` comments, CSS), so the
+  // collapse must never reach inside a block. Blocks are matched with their
+  // attribute forms (`<pre class="highlight">`, `<script type="...">`) - the
+  // old open-tag literals only caught a bare `<pre>`.
+  const blockRe = /<(pre|script|style|textarea)\b[^>]*>[\s\S]*?<\/\1\s*>/gi;
+  const shrink = (s) => s
+    .replace(/\r/g, '')
+    // A line break inside TEXT is a word separator, never a joiner: the old
+    // `[ \t]*\n[ \t]* -> ''` fused 'Hello\nworld' into 'Helloworld'. Collapse
+    // the break to a single space instead; the between-tag rule below then
+    // removes the ones that sit between tags (where whitespace is meaningless).
+    .replace(/[ \t]*\n[ \t]*/g, ' ')
     .replace(/>\s+</g, '><')
-    .replace(/\s+/g, ' ')
+    .replace(/[ \t]{2,}/g, ' ')
     .trim();
+  const parts = [];
+  let last = 0;
+  let m;
+  while ((m = blockRe.exec(html)) !== null) {
+    if (m.index > last) parts.push(shrink(html.slice(last, m.index)));
+    parts.push(m[0]);
+    last = blockRe.lastIndex;
+  }
+  if (last < html.length) parts.push(shrink(html.slice(last)));
+  return parts.join('').trim();
+}
+
+// ---------- SEO-gap pass helpers (feed link / SearchAction / breadcrumb / article / hreflang) ----------
+
+// The root-home stem is the root document; glob '**' retries use it too.
+const rootHomeSlug = '/';
+
+// Literal prefix of a locale pattern: the part every matched slug must start
+// with (glob patterns drop the glob tail; the root document retries to '').
+function stemForPattern(pattern) {
+  if (pattern === rootHomeSlug) return '';
+  if (typeof pattern === 'string') {
+    const star = pattern.indexOf('*');
+    if (star !== -1) return pattern.slice(0, star);
+    return pattern;
+  }
+  return rootHomeSlug;
+}
+
+// Root-home retries: a rest of '/' or '' is the home page, not '//'.
+function slugForHomePage(slug) { return slug === rootHomeSlug ? rootHomeSlug : slug; }
+
+/**
+ * Per-page article LD+JSON type (SEO-gap pass): config.article.scoped is a
+ * slug-glob map of type strings; the most specific pattern matching the page
+ * wins (exact > glob), invalid types are skipped (config.js warned loudly
+ * at load).
+ */
+const ARTICLE_TYPES = Object.freeze(['Article', 'TechArticle', 'NewsArticle']);
+function articleTypeForPage(page, config) {
+  const scoped = config.article?.scoped;
+  if (!scoped || typeof scoped !== 'object' || Array.isArray(scoped)) return null;
+  let bestScore = -1;
+  let best = null;
+  for (const [pattern, v] of Object.entries(scoped)) {
+    if (!ARTICLE_TYPES.includes(String(v))) continue;
+    if (!slugMatchesGlob(pattern, page.slug)) continue;
+    const score = globSpecificity(pattern);
+    if (score > bestScore) { bestScore = score; best = String(v); }
+  }
+  return best;
+}
+
+/**
+ * Auto BreadcrumbList (SEO-gap pass): config.breadcrumb true builds the
+ * breadcrumb from the page's own position in the URL tree - the site root,
+ * then every URL segment in order, with the page's own title for the tail.
+ * The root page (no segments) gets nothing - a one-element breadcrumb is
+ * not a breadcrumb.
+ */
+function breadcrumbJsonLd(page, config) {
+  if (config.breadcrumb !== true) return null;
+  const segs = String(page.slug).split('/').filter(Boolean);
+  if (segs.length === 0) return null;
+  const items = [{ position: 1, name: config.site.name, url: pageUrlFor(config, rootHomeSlug) }];
+  let acc = '';
+  segs.forEach((seg, i) => {
+    acc += '/' + seg;
+    // The LEAF item is the current page: use its own canonical slug, so a
+    // directory page's breadcrumb URL matches its canonical ('/guide/', not
+    // the segment-join '/guide' the intermediate levels use). Intermediate
+    // segments have no page of their own, so the join stays their URL.
+    const isLeaf = i === segs.length - 1;
+    items.push({
+      position: i + 2,
+      name: (isLeaf && page.title) ? page.title : seg.replace(/[-_]/g, ' '),
+      url: pageUrlFor(config, isLeaf ? page.slug : acc),
+    });
+  });
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((it) => ({
+      '@type': 'ListItem',
+      position: it.position,
+      name: it.name,
+      item: it.url,
+    })),
+  };
+}
+
+/**
+ * Does this config's jsonLd take the SCOPED map form (every key a page-slug
+ * glob)? The injection path (below) and the generated-extras skip must agree
+ * on this - they diverged once: the injection accepted the bare `**` key
+ * (documented as "anywhere at all") while the skip required every key to
+ * start with '/', so a `**`-keyed map injected its block AND the generated
+ * article, shipping two article blocks on the page.
+ */
+function isScopedJsonLdMap(jc) {
+  return !Array.isArray(jc) && Boolean(jc) && typeof jc === 'object'
+    && Object.keys(jc).length > 0
+    && Object.keys(jc).every((k) => /(^\/|^\*$|^\*\*$|\*)/.test(k));
 }
 
+/**
+ * Does this page RECEIVE a scoped jsonLd block? The scoped map form keys
+ * slug globs to block lists (config.js reads legacy forms - a schema object
+ * or an array of them - as the global set, with non-glob keys). Pages that
+ * receive a scoped block skip the GENERATED article block (the documented
+ * skip: a consumer-authored block outranks the derived one), while the
+ * breadcrumb trail coexists with any config jsonLd form.
+ */
+function pageReceivesScopedJsonLd(page, config) {
+  const jsonLd = config.jsonLd;
+  if (!isScopedJsonLdMap(jsonLd)) return false;
+  return Object.keys(jsonLd).some((k) => slugMatchesGlob(k, page.slug));
+}
+
+/**
+ * hreflang alternates for a page: the locales map keys slug globs to
+ * language codes; the most specific matching pattern decides the page's own
+ * language, the others give the replica slugs (the page's slug with the
+ * matched stem swapped for each sibling stem). This is a stem-SWAP guess,
+ * not a file-existence contract: a page that only exists in one language
+ * still gets the alternates entry, and its 404 is the SSG's problem.
+ */
+function hreflangAlternatesFor(page, config) {
+  const locales = config.locales;
+  if (!locales || typeof locales !== 'object' || Array.isArray(locales)) return null;
+  const entries = Object.entries(locales).filter(([, v]) => typeof v === 'string' && v !== '');
+  if (entries.length === 0) return null;
+  let bestScore = -1;
+  let ownPattern = null;
+  let ownLang = null;
+  for (const [pattern, lang] of entries) {
+    if (!slugMatchesGlob(pattern, page.slug)) continue;
+    const score = globSpecificity(pattern);
+    if (score > bestScore) { bestScore = score; ownPattern = pattern; ownLang = lang; }
+  }
+  if (!ownPattern) return null;
+  const ownStem = stemForPattern(ownPattern);
+  const stripLen = ownStem === rootHomeSlug ? 0 : ownStem.length;
+  let rest = String(page.slug).slice(stripLen);
+  if (!rest.startsWith('/')) rest = '/' + rest;
+  const out = [];
+  for (const [pattern, lang] of entries) {
+    if (lang === ownLang) continue;
+    const stem = stemForPattern(pattern);
+    const stemClean = stem === rootHomeSlug ? '' : stem.replace(/\/+$/, '');
+    out.push([lang, pageUrlFor(config, stemClean === '' ? (rest === '/' ? rootHomeSlug : rest) : slugForHomePage(stemClean + rest))]);
+  }
+  // x-default follows the root document's locale when one is configured.
+  const rootEntry = entries.find(([pattern]) => stemForPattern(pattern) === rootHomeSlug);
+  if (rootEntry && rootEntry[1] !== ownLang) {
+    out.push(['x-default', pageUrlFor(config, rest === '/' ? rootHomeSlug : rest)]);
+  }
+  return out.length ? out : null;
+} 
 // ---------- injection value escaping ----------
 
+
 // HTML-attribute escaping for config/page values that land inside
 // content="..." or href="...": a raw " in a site description silently
 // truncates every generated tag (ported from prestruct's escapeHtmlAttr).
 // '&' is deliberately NOT escaped: the battery pins the raw ampersand in
 // canonical attributes as valid HTML, and escaping it would double-encode
 // legit URLs that already contain &amp; from the SSG.
-function escAttr(value) {
+export function escAttr(value) {
   return String(value == null ? '' : value)
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
@@ -106,12 +258,50 @@ function readPageOverrides(html, page) {
  * pages that ship their own OG/Twitter/JSON-LD/canonical/description keep them.
  * Page-level freestruct comments refine the injected tags (see PERPAGE_KEYS).
  */
-export function injectPage(page, { config, template, buildHash, snippetDir }) {
+// Marker-wrapped custom snippets: the wrapper makes the injected region
+// identifiable so a RERUN can drop the previous copy before re-adding it
+// (without this, each pass stacked another snippet and, for body/footer
+// snippets, changed the body text - churning the content-derived build hash
+// every run). The wrapper is freestruct's own; snippet content comments are
+// already stripped by readSnippet.
+const SNIPPET_OPEN = '<!-- freestruct:snippet -->';
+const SNIPPET_CLOSE = '<!-- /freestruct:snippet -->';
+
+/**
+ * Remove every region a PREVIOUS freestruct run wrote into a page, so a
+ * second pass re-derives it instead of stacking duplicates. Two tool-owned
+ * regions: the generated head tail (the `<!-- freestruct -->` marker through
+ * `</head>`: seo block, version tag, header snippet) and the marker-wrapped
+ * body-start/footer snippets. Both are entirely freestruct's, so removing
+ * them is safe; consumer/SSG content never lives inside either.
+ */
+function stripInjectedRegions(html) {
+  return html
+    .replace(/<!-- freestruct -->[\s\S]*?(?=<\/head>)/i, '')
+    // The snippets are inserted with NO surrounding newlines (the snippet
+    // files' own trailing newline rides INSIDE the markers), so this removal
+    // restores the page to its pre-injection bytes and a rerun is byte-identical.
+    .replace(/<!-- freestruct:snippet -->[\s\S]*?<!-- \/freestruct:snippet -->/gi, '');
+}
+
+export function injectPage(page, { config, template, buildHash, snippetDir, injectWarnings, generatedImages }) {
   let html = page.html;
   const siteName = config.site.name;
   const siteUrl = config.site.url;
+  // Rerun hygiene first: drop the previous pass's output so this pass derives
+  // the same result (idempotent reruns) rather than duplicating snippets.
+  html = stripInjectedRegions(html);
   const overrides = readPageOverrides(html, page);
 
+  // Headless-page diagnostics (Pass 26.13): every injected surface anchors
+  // on the head close tag, so a .html file without one silently takes NO
+  // head injection - the audit names the gaps afterwards, but the RUN says
+  // so here too (headless fragments are the octet-stream post class: never
+  // die silently).
+  if (!/<\/head>/i.test(html)) {
+    pageWarn(page, 'no </head> found - the whole head-injection surface skips this page');
+  }
+
   let pageTitle = (page.title || siteName) + ' | ' + siteName;
   let pageDescription = (page.description !== undefined && page.description !== null)
     ? page.description
@@ -128,31 +318,209 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
   const canonicalUrl = pageUrlFor(config, page.slug)
     + (config.cacheBusting?.hashInCanonicalUrl === true ? '?v=' + buildHash : '');
 
-  // og image: the per-page comment wins over config; relative values are
-  // joined onto the site url, absolute HTTP(S) values pass through as-is.
-  // No image anywhere: no og:image/twitter:image ship at all (prestruct
-  // parity - a bare image tag pointing at the site root is a broken card).
-  const rawOgImage = (overrides?.ogImage !== undefined && overrides.ogImage !== '')
+  // og image (issue #20): config accepts the back-compat string form or the
+  // structured { src, width, height, alt } object form (shared prestruct
+  // shape so configs move between engines). Per-page overrides win over the
+  // config either way; relative values join onto the site url, absolute
+  // HTTP(S) values pass through as-is. No image anywhere: no og:image/
+  // twitter:image ship at all (a bare image tag pointing at the site root is
+  // a broken card).
+  const ogImageCfg = config.og?.image;
+  const ogImageObj = (ogImageCfg !== undefined && ogImageCfg !== null
+    && typeof ogImageCfg === 'object' && !Array.isArray(ogImageCfg))
+    ? ogImageCfg : null;
+  const hasPerpageOgImage = overrides?.ogImage !== undefined && overrides.ogImage !== '';
+  // Resolution order (issue #20 + #22): per-page override > per-page
+  // GENERATED image (issue #22 deliverables, keyed by slug) > the config
+  // (object or string form). Pages that ship their own og:image keep it
+  // before any of this matters - missing-only.
+  const generatedForPage = (generatedImages && generatedImages[page.slug]) || null;
+  // og.scoped (issue #25 follow-on): image variants keyed by the same slug
+  // globs as jsonLd; the MOST SPECIFIC matching pattern wins (exact > glob).
+  // Per-page overrides and per-page generated images (#22) still rank ahead;
+  // the global og.image is the deepest fallback.
+  const ogScopedCfg = config.og?.scoped;
+  let scopedForPage = null;
+  if (ogScopedCfg && typeof ogScopedCfg === 'object' && !Array.isArray(ogScopedCfg)) {
+    let bestScore = -1;
+    for (const [pattern, variant] of Object.entries(ogScopedCfg)) {
+      if (!slugMatchesGlob(pattern, page.slug)) continue;
+      const score = globSpecificity(pattern);
+      if (score > bestScore) { bestScore = score; scopedForPage = variant; }
+    }
+  }
+  // Defensive shape gate (config.js already warns loudly at load): a variant
+  // that is neither a string nor a plain object (god forbid a list - one page
+  // matches ONE image) resolves to NO image, never to synthesized garbage.
+  if (scopedForPage !== null && scopedForPage !== undefined
+      && typeof scopedForPage !== 'string'
+      && (typeof scopedForPage !== 'object' || Array.isArray(scopedForPage))) {
+    scopedForPage = null;
+  }
+  const scopedIsObject = scopedForPage !== null && typeof scopedForPage === 'object' && !Array.isArray(scopedForPage);
+  const allowSvgAccept = scopedForPage === null
+    ? (ogImageObj ? ogImageObj.allowSvg === true : false)
+    : (scopedIsObject ? scopedForPage.allowSvg === true : false);
+  const companionsSource = hasPerpageOgImage ? null
+    : (generatedForPage || (scopedIsObject ? scopedForPage : null) || (!scopedForPage ? ogImageObj : null));
+  const rawOgImage = hasPerpageOgImage
     ? String(overrides.ogImage)
-    : config.og?.image || '';
+    : (generatedForPage ? generatedForPage.src
+      : (scopedForPage !== null
+        ? (scopedIsObject ? String(scopedForPage.src || '') : String(scopedForPage))
+        : (ogImageObj ? String(ogImageObj.src || '') : (ogImageCfg || ''))));
   const ogImageFull = rawOgImage && !/^(https?:)?\/\//i.test(rawOgImage)
-    ? siteUrl + rawOgImage
+    ? pageUrlFor(config, rawOgImage)
     : rawOgImage;
 
+  // issue #20, the SVG trap: an SVG og:image cannot be rendered by most
+  // social scrapers and the share preview blanks. Loud warning always from
+  // here (config value or per-page override); under --strict the orchestrator
+  // graduates the collected offenses to build failures (same ladder as the
+  // report classes), and allowSvg: true is the explicit way out.
+  if (rawOgImage && /\.svg$/i.test(rawOgImage.split(/[?#]/)[0])
+      && hasPerpageOgImage !== true && !allowSvgAccept) {
+    // Loud in every run; under --strict the orchestrator also graduates the
+    // collected offenses (injectWarnings) to build failures.
+    pageWarn(page, 'og image "' + rawOgImage + '" is an SVG: most social scrapers cannot render it and the share preview blanks (ship a raster image, or set allowSvg: true in the og.image object to accept it)');
+    injectWarnings.push('og image "' + rawOgImage + '" is an SVG: most social scrapers cannot render it and the share preview blanks (ship a raster image, or set allowSvg: true in the og.image object to accept it)');
+  }
+
   // Add cache-busting query param to assets (css, js, images, fonts, ...)
   if (config.cacheBusting?.assetQueryParam !== false) {
-    const assetExts = '.css.js.png.jpg.jpeg.gif.svg.webp.ico.woff.woff2.ttf.otf.wasm.json';
-    html = html.replace(/(href|src)=\"([^\"]+)\"/gi,
-      (match, attr, url) => {
-        const cleanUrl = url.replace(/\?v=[^"]*/, '');
-        const ext = cleanUrl.substring(cleanUrl.lastIndexOf('.'));
-        if (assetExts.includes(ext)) {
-          return attr + '=\"' + cleanUrl + '?v=' + buildHash + '\"';
-        }
-        return match;
+    // A real extension SET, matched case-insensitively. The old
+    // `assetExts.includes(ext)` was a substring test, so '/x.cs' ('.cs' is a
+    // substring of '.css'), '/x.tt' ('.ttf'), '/x.j' ('.js') all got busted
+    // while a genuine '/img.PNG' was missed.
+    const assetExts = new Set(['.css', '.js', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico', '.woff', '.woff2', '.ttf', '.otf', '.wasm', '.json']);
+    // Both quote styles (Pass 26.21): the old double-quote-only pattern left
+    // a single-quoted href/src (valid HTML, common in hand-authored markup)
+    // un-busted, so a stale asset survived a content change on those pages.
+    //
+    // Protected blocks (Pass 26.22): a docs page that SHOWS a link in a code
+    // example (`<pre><code>&lt;link href="/style.css"&gt;</code></pre>`) is
+    // markup-in-prose, not a live asset reference - rewriting it turned the
+    // example into fiction. An inline <script> body can likewise carry
+    // href=/src= string literals. Mask those regions, bust the live
+    // attributes, then restore; a <script src> OPENING tag stays live (only
+    // its body is masked). Same payload-stripping doctrine linkcheck owns.
+    const masks = [];
+    const mask = (s) => { masks.push(s); return '\u0000FS' + (masks.length - 1) + '\u0000'; };
+    html = html
+      .replace(/<script\b[^>]*>([\s\S]*?)<\/script\s*>/gi, (m) => {
+        const openEnd = m.indexOf('>') + 1;
+        const closeLen = m.match(/<\/script\s*>$/i)[0].length;
+        return m.slice(0, openEnd) + mask(m.slice(openEnd, m.length - closeLen)) + m.slice(m.length - closeLen);
+      })
+      .replace(/<(pre|code|textarea|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, (m) => mask(m));
+    // Same-origin policy (owner fix): only the site's own assets are ours to
+    // invalidate. An off-site URL (another CDN's host) gains nothing from a
+    // ?v= param, and a SIGNED url (an S3 presigned link carrying
+    // X-Amz-Signature) is actively CORRUPTED by an appended param - the
+    // signature no longer matches and the asset 403s. Absolute (scheme://host)
+    // and protocol-relative (//host) references are busted only when the host
+    // is the configured site; every other scheme (data:, blob:, mailto:, tel:)
+    // is left alone.
+    const siteOrigin = (() => {
+      try { return new URL(config.site?.url || '').origin; } catch { return null; }
+    })();
+    const siteHost = (() => {
+      try { return new URL(config.site?.url || '').host; } catch { return null; }
+    })();
+    // { origin, pathname } for a reference we may bust (origin '' = same-origin
+    // relative), or null to skip outright (fragment-only, or a non-http scheme).
+    const parseAssetRef = (raw) => {
+      if (!raw || raw[0] === '#') return null;
+      if (raw.startsWith('//')) {
+        const host = raw.slice(2).split(/[/?#]/)[0];
+        return { origin: '//' + host, pathname: raw.slice(2 + host.length) };
+      }
+      const m = /^([a-z][a-z0-9+.-]*):\/\//i.exec(raw);
+      if (m) {
+        const rest = raw.slice(m[0].length);
+        const host = rest.split(/[/?#]/)[0];
+        return { origin: m[1].toLowerCase() + '://' + host, pathname: rest.slice(host.length) };
+      }
+      if (/^[a-z][a-z0-9+.-]*:/i.test(raw)) return null; // data:, blob:, mailto:, tel:, ...
+      return { origin: '', pathname: raw }; // same-origin relative
+    };
+    const isSameOrigin = (origin) => origin === ''
+      || (siteOrigin !== null && origin === siteOrigin)
+      || (siteHost !== null && origin === '//' + siteHost);
+    // The extension lives on the PATH: split the fragment and query off first,
+    // so an asset the SSG emitted with an existing query ('style.css?foo=bar')
+    // or fragment ('style.css#iefix') is still recognized. The version param
+    // joins the existing query with '&' and a previous freestruct 'v=' is
+    // dropped (rerun hygiene). Returns the URL unchanged when it is not a
+    // bustable same-origin asset.
+    const bustAssetRef = (raw) => {
+      const ref = parseAssetRef(raw);
+      if (!ref || !isSameOrigin(ref.origin)) return raw;
+      const { origin, pathname } = ref;
+      const hashAt = pathname.indexOf('#');
+      const fragment = hashAt === -1 ? '' : pathname.slice(hashAt);
+      const noFrag = hashAt === -1 ? pathname : pathname.slice(0, hashAt);
+      const qAt = noFrag.indexOf('?');
+      const pathPart = qAt === -1 ? noFrag : noFrag.slice(0, qAt);
+      const query = qAt === -1 ? '' : noFrag.slice(qAt + 1);
+      const dot = pathPart.lastIndexOf('.');
+      const ext = dot === -1 ? '' : pathPart.slice(dot).toLowerCase();
+      if (!assetExts.has(ext)) return raw;
+      const keptParams = query.split('&').filter(p => p && !/^v=/.test(p));
+      keptParams.push('v=' + buildHash);
+      return origin + pathPart + '?' + keptParams.join('&') + fragment;
+    };
+    html = html.replace(/(href|src)=(["'])([^"']+)\2/gi,
+      (match, attr, quote, url) => attr + '=' + quote + bustAssetRef(url) + quote);
+    // srcset (responsive images): the SAME url list rides <img srcset>,
+    // <picture><source srcset> and <link imagesrcset>, and it was never
+    // busted - so on any responsive image the primary (largest) candidate
+    // stayed stale at the edge while src moved on. A candidate is
+    // "url [descriptor]"; a naive comma split corrupts a data: URI (its
+    // payload carries commas), so this follows the HTML spec's splitting
+    // loop: skip whitespace/commas, take the non-whitespace run as the url
+    // (stripping trailing separators), then the run up to the next comma as
+    // the descriptor. Rejoined with the canonical ", " separator.
+    const isSrcsetWs = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f';
+    const parseSrcset = (value) => {
+      const out = [];
+      let i = 0;
+      const n = value.length;
+      while (i < n) {
+        while (i < n && (isSrcsetWs(value[i]) || value[i] === ',')) i++;
+        if (i >= n) break;
+        let start = i;
+        while (i < n && !isSrcsetWs(value[i])) i++;
+        let url = value.slice(start, i);
+        while (url.endsWith(',')) url = url.slice(0, -1);
+        if (url === '') continue;
+        while (i < n && isSrcsetWs(value[i])) i++;
+        start = i;
+        while (i < n && value[i] !== ',') i++;
+        out.push({ url, descriptor: value.slice(start, i).trim() });
+      }
+      return out;
+    };
+    html = html.replace(/srcset=(["'])([^"']*)\1/gi,
+      (match, quote, value) => {
+        const busted = parseSrcset(value)
+          .map(({ url, descriptor }) => bustAssetRef(url) + (descriptor ? ' ' + descriptor : ''))
+          .join(', ');
+        return 'srcset=' + quote + busted + quote;
       });
+    html = html.replace(/\u0000FS(\d+)\u0000/g, (m, i) => masks[Number(i)]);
   }
 
+  // SearchAction (config.search.url, SEO-gap pass): the seam expands to ''
+  // (no potentialAction at all - the hardcoded ?s= default is gone) or to
+  // the configured search target. The {search_term_string} placeholder is
+  // required by the schema.org contract; config.js already warns loudly at
+  // load when it is missing (and the block then never ships).
+  const searchActionJson = (config.search?.url && config.search.url.includes('{search_term_string}'))
+    ? ',\n  "potentialAction": { "@type": "SearchAction", "target": "'
+      + escJson(config.search.url) + '", "query-input": "required name=search_term_string" }'
+    : '';
+
   const replacements = {
     '{{pageTitle}}': escAttr(pageTitle),
     '{{pageDescription}}': escAttr(pageDescription),
@@ -178,29 +546,105 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
       ? ',\n  "founder": { "@type": "Person", "name": "' + escJson(config.author.name) + '"'
         + (config.author.url ? ', "url": "' + escJson(config.author.url) + '"' : '') + ' }'
       : '',
+    // searchActionJson seam (SEO-gap pass): '' or the configured block
+    '{{searchActionJson}}': searchActionJson,
   };
 
-  // Custom JSON-LD hook (config.jsonLd): a single object or an array of
-  // objects appended after the built-in blocks. Ships through the same
-  // missing-only gate as the built-ins, and '<' is neutralized so a value
-  // cannot close the script tag early (same posture as the XML escape-or-fail).
+  // Custom JSON-LD hook (config.jsonLd, issue #25): three accepted shapes -
+  //   single object, array of objects (legacy, every page), or the scoped
+  //   map form keyed by page-slug globs ('/' exact, '/blog/*' one segment,
+  //   '/guides/**' the tree). The scoped form lands per page: global first,
+  //   then every matching scoped block in specificity order (exact >
+  //   literal-heavy > '**'). missing-only is untouched: pages shipping
+  //   their own JSON-LD get nothing here, scoped or not. All blocks ship
+  //   through the same serialization ('<' neutralized) as the legacy form.
   let customJsonLd = '';
   if (config.jsonLd !== undefined) {
-    const blocks = Array.isArray(config.jsonLd) ? config.jsonLd : [config.jsonLd];
-    for (let i = 0; i < blocks.length; i++) {
-      const block = blocks[i];
-      if (!block || typeof block !== 'object' || Array.isArray(block)) {
-        console.log('[freestruct] config warning: jsonLd[' + i + '] is not an object; block skipped');
-        continue;
+    const jc = config.jsonLd;
+    const isScopedMap = isScopedJsonLdMap(jc);
+    if (isScopedMap) {
+      const keys = Object.keys(jc).sort((a, b) => globSpecificity(b) - globSpecificity(a));
+      for (const key of keys) {
+        if (!slugMatchesGlob(key, page.slug)) continue;
+        const blocks = Array.isArray(jc[key]) ? jc[key] : [jc[key]];
+        if (!blocks.length || blocks.some((b) => !b || typeof b !== 'object' || Array.isArray(b))) {
+          console.log('[freestruct] config warning: jsonLd "' + key + '" must map to an LD+JSON object or a list of them; block skipped');
+          continue;
+        }
+        for (const block of blocks) {
+          const serialized = JSON.stringify(block).replace(/</g, '\\u003c');
+          customJsonLd += '\n<script type="application/ld+json">\n' + serialized + '\n</script>\n';
+        }
       }
+    } else {
+      const blocks = Array.isArray(jc) ? jc : [jc];
+      for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        if (!block || typeof block !== 'object' || Array.isArray(block)) {
+          console.log('[freestruct] config warning: jsonLd[' + i + '] is not an object; block skipped');
+          continue;
+        }
+        const serialized = JSON.stringify(block).replace(/</g, '\\u003c');
+        customJsonLd += '\n<script type="application/ld+json">\n' + serialized + '\n</script>\n';
+      }
+    }
+  }
+
+  // Per-page Article/TechArticle LD+JSON (SEO-gap pass, config.article
+  // scoped) + auto BreadcrumbList (config.breadcrumb, SEO-gap pass): both
+  // auto-emit ONLY for pages that ship no JSON-LD of their own AND get no
+  // configured jsonLd block at all (missing-only, and a scoped jsonLd key
+  // counts as the consumer's explicit per-page choice - no double block).
+  // 404 pages keep the FULL pipeline's per-page tags (issue #11: the 404 is
+  // finished like every page), but the generated extras are probe-junk on a
+  // noindex page: a breadcrumb trail for a 404, typed article schema, hreflang
+  // alternates, the feed alternate and verification metas all say nothing to
+  // a crawler that has been told to skip the page. The extras therefore skip
+  // 404s AND robots-noindex pages (the same exclusion class sitemap/feed/
+  // search/llms already honor); the core injected set stays everywhere.
+  const noindexExtrasGate = page.is404 === true || htmlIsNoindex(html);
+  // Missing-only class: the page's OWN pre-existing ld+json suppresses the
+  // generated extras. Config-level jsonLd is OUR block - it coexists with
+  // the generated ones (Pass 26.9: the old gate refused the extras whenever
+  // ANY config jsonLd existed, silently killing breadcrumb/article on sites
+  // that also ship a global custom block - the docs site itself was bit).
+  const pageOwnsJsonLd = hasSeoType(html, 'jsonld');
+  if (!noindexExtrasGate && !pageOwnsJsonLd) {
+    const articleType = !pageReceivesScopedJsonLd(page, config)
+      ? articleTypeForPage(page, config)
+      : null;
+    if (articleType) {
+      const block = {
+        '@context': 'https://schema.org',
+        '@type': articleType,
+        headline: pageTitle,
+        url: canonicalUrl,
+      };
+      const artAuthor = overrides?.author || config.author?.name;
+      if (artAuthor) block.author = { '@type': 'Person', name: String(artAuthor) };
+      if (overrides?.publishedTime) block.datePublished = String(overrides.publishedTime);
+      if (pageDescription) block.description = pageDescription;
+      if (ogImageFull) block.image = ogImageFull;
       const serialized = JSON.stringify(block).replace(/</g, '\\u003c');
       customJsonLd += '\n<script type="application/ld+json">\n' + serialized + '\n</script>\n';
     }
+    const breadcrumbLd = breadcrumbJsonLd(page, config);
+    if (breadcrumbLd) {
+      const serialized = JSON.stringify(breadcrumbLd).replace(/</g, '\\u003c');
+      customJsonLd += '\n<script type="application/ld+json">\n' + serialized + '\n</script>\n';
+    }
   }
 
   let seo = template;
   for (const [k, v] of Object.entries(replacements)) seo = seo.split(k).join(v);
   if (customJsonLd) seo += customJsonLd;
+  // A page (and site) with no description source anywhere must not ship an
+  // EMPTY description tag: `content=""` is a present-but-empty description,
+  // worse to a crawler than none, and the engine's own audit then fails the
+  // page it just decorated. Omit the description-bearing lines instead.
+  if (!pageDescription) {
+    seo = seo.replace(/^[^\n]*<meta (name="description"|property="og:description"|name="twitter:description")[^\n]*>\n?/gim, '');
+  }
   // image tags ship only when an og image exists (config-level or per-page)
   if (!ogImageFull) {
     seo = seo.replace(/^[^\n]*<meta (property="og:image"|name="twitter:image")[^\n]*>\n?/gim, '');
@@ -223,6 +667,15 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
   const hasJsonLd = hasSeoType(html, 'jsonld');
   const hasCanonical = hasSeoType(html, 'canonical');
 
+  // Per-tag missing-only within a SET: the og/twitter gates are group-level
+  // (og:title/og:description; twitter:card/twitter:title), but a page can ship
+  // a PARTIAL set - e.g. its own og:url with no og:title. The group gate is
+  // then false, the whole config set injects, and the page ends up with TWO
+  // og:url tags (the engine's own audit only counts og:title, so the duplicate
+  // shipped green). Filter each candidate tag against the page's own head.
+  const pageHasMeta = (attr, key) => new RegExp('<meta[^>]+' + attr + '=["\']'
+    + String(key).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '["\']', 'i').test(html);
+
   let seoInjection = '';
   // FIX (was 0.4.x wart): plain description meta now really reaches bare pages
   if (!hasSeoType(html, 'description')) {
@@ -230,23 +683,60 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
     if (descMatch) seoInjection += '\n' + descMatch[0];
   }
   if (!hasOg) {
-    const ogMatch = seo.match(/<meta property="og:[^"]*"[^>]*>/gi);
-    if (ogMatch) seoInjection += '\n' + ogMatch.join('\n');
+    const ogTags = (seo.match(/<meta property="og:[^"]*"[^>]*>/gi) || [])
+      .filter((tag) => {
+        const key = (tag.match(/property=["'](og:[^"']*)["']/i) || [])[1];
+        // og:image is handled SLOT-level below (issue #46): a page carrying
+        // its own og basics still needs the config image, so the image is
+        // injected there for every page shape, never inside this group gate.
+        return key && key !== 'og:image' && !pageHasMeta('property', key);
+      });
+    if (ogTags.length) seoInjection += '\n' + ogTags.join('\n');
     // article:* companions for per-page article facts
     const articleTags = [];
-    if (overrides?.publishedTime) articleTags.push('<meta property="article:published_time" content="' + escAttr(overrides.publishedTime) + '">');
-    if (overrides?.author) articleTags.push('<meta property="article:author" content="' + escAttr(overrides.author) + '">');
-    if (overrides?.section) articleTags.push('<meta property="article:section" content="' + escAttr(overrides.section) + '">');
+    if (overrides?.publishedTime && !pageHasMeta('property', 'article:published_time')) articleTags.push('<meta property="article:published_time" content="' + escAttr(overrides.publishedTime) + '">');
+    if (overrides?.author && !pageHasMeta('property', 'article:author')) articleTags.push('<meta property="article:author" content="' + escAttr(overrides.author) + '">');
+    if (overrides?.section && !pageHasMeta('property', 'article:section')) articleTags.push('<meta property="article:section" content="' + escAttr(overrides.section) + '">');
     if (articleTags.length) seoInjection += '\n' + articleTags.join('\n');
-  } else if (overrides && [overrides.ogType, overrides.ogImage, overrides.publishedTime, overrides.author, overrides.section].some(v => v !== undefined)) {
+  } else if (overrides && [overrides.ogType, overrides.publishedTime, overrides.author, overrides.section].some(v => v !== undefined)) {
     pageWarn(page, 'page ships its own Open Graph tags; og/author per-page overrides were not applied');
   }
   if (!hasTwitter) {
-    const twMatch = seo.match(/<meta name="twitter:[^"]*"[^>]*>/gi);
-    if (twMatch) seoInjection += '\n' + twMatch.join('\n');
+    const twTags = (seo.match(/<meta name="twitter:[^"]*"[^>]*>/gi) || [])
+      .filter((tag) => {
+        const key = (tag.match(/name=["'](twitter:[^"']*)["']/i) || [])[1];
+        // twitter:image is SLOT-level, same rule as og:image (issue #46).
+        return key && key !== 'twitter:image' && !pageHasMeta('name', key);
+      });
+    if (twTags.length) seoInjection += '\n' + twTags.join('\n');
   } else if (overrides && overrides.twitterCard !== undefined) {
     pageWarn(page, 'page ships its own Twitter tags; the twitterCard override was not applied');
   }
+
+  // Image slots are SLOT-level, not set-level (issue #46): the og/twitter
+  // group gates above mark a page "covered" as soon as it ships its own
+  // og:title (or twitter:card), so a host layout that hand-writes its own og
+  // basics NEVER received the config og.image - the share image was starved on
+  // every page of such a site, while the canonical in the same head was
+  // correct. Inject the image (and its companions) whenever the page itself
+  // lacks og:image / twitter:image, independent of the group gate.
+  if (ogImageFull && !pageHasMeta('property', 'og:image')) {
+    seoInjection += '\n<meta property="og:image" content="' + escAttr(ogImageFull) + '">';
+    // issue #20: the structured og.image object form also emits its
+    // companions; only when the shipped image IS the config object - a
+    // per-page override ships its own image and replaces the set wholesale
+    // (companionsSource is null then).
+    if (companionsSource) {
+      const companions = [];
+      if (companionsSource.width !== undefined && companionsSource.width !== '') companions.push('<meta property="og:image:width" content="' + escAttr(companionsSource.width) + '">');
+      if (companionsSource.height !== undefined && companionsSource.height !== '') companions.push('<meta property="og:image:height" content="' + escAttr(companionsSource.height) + '">');
+      if (companionsSource.alt !== undefined && companionsSource.alt !== '') companions.push('<meta property="og:image:alt" content="' + escAttr(companionsSource.alt) + '">');
+      if (companions.length) seoInjection += '\n' + companions.join('\n');
+    }
+  }
+  if (ogImageFull && !pageHasMeta('name', 'twitter:image')) {
+    seoInjection += '\n<meta name="twitter:image" content="' + escAttr(ogImageFull) + '">';
+  }
   if (overrides && overrides.description !== undefined && hasSeoType(html, 'description')) {
     pageWarn(page, 'page has its own description meta; the description override was not applied');
   }
@@ -259,11 +749,54 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
     if (canMatch) seoInjection += '\n' + canMatch[0];
   }
 
+  // Feed autodiscovery (SEO-gap pass): feed.xml ships with honest dates,
+  // but nothing in any head pointed feed readers at it. One line in every
+  // injected head - gated on the page not carrying an alternate/rss link of
+  // its own, in either attribute order (missing-only, as always).
+  if (config.generateFeed !== false && !noindexExtrasGate
+      && !/(rel\s*=\s*["']alternate["'][^>]*type\s*=\s*["']application\/(rss|atom)\+xml["'])/i.test(html)
+      && !/(type\s*=\s*["']application\/(rss|atom)\+xml["'][^>]*rel\s*=\s*["']alternate["'])/i.test(html)) {
+    seoInjection += '\n<link rel="alternate" type="application/rss+xml" title="' + escAttr(siteName) + ' feed" href="' + escAttr(pageUrlFor(config, '/feed.xml')) + '">';
+  }
+
+  // Site verification metas (SEO-gap pass, config.verification): the
+  // provider -> code map drops straight into site-owned meta tags, with the
+  // engine-owned name spellings (search engines match on name, not content).
+  const VERIFICATION_META_NAMES = { google: 'google-site-verification', bing: 'msvalidate.01', yandex: 'yandexVerification', pinterest: 'pinterest-site-verification' };
+  if (config.verification && !noindexExtrasGate && typeof config.verification === 'object' && !Array.isArray(config.verification)) {
+    const verificationMetas = [];
+    for (const [provider, code] of Object.entries(config.verification)) {
+      const metaName = VERIFICATION_META_NAMES[provider];
+      if (!metaName || typeof code !== 'string' || code === '') continue; // config.js warned
+      // missing-only, attribute-ORDER tolerant: a page that writes its own
+      // verification meta in the other attribute order still suppresses ours
+      if (new RegExp('<meta[^>]*name=["\']' + metaName + '["\']', 'i').test(html)) continue;
+      verificationMetas.push('<meta name="' + metaName + '" content="' + escAttr(code) + '">');
+    }
+    if (verificationMetas.length) seoInjection += '\n' + verificationMetas.join('\n');
+  }
+
+  // hreflang/i18n alternates (SEO-gap pass, config.locales): slug-stem swap
+  // alternates for pages inside a locale tree; skipped entirely when the
+  // page carries any hreflang of its own (the SSG or the author owns it).
+  if (config.locales && !noindexExtrasGate && typeof config.locales === 'object' && !Array.isArray(config.locales)
+      && !/(\shreflang\s*=)/i.test(html)) {
+    const alternates = hreflangAlternatesFor(page, config);
+    if (alternates) {
+      seoInjection += '\n' + alternates
+        .map(([lang, url]) => '<link rel="alternate" hreflang="' + escAttr(lang) + '" href="' + escAttr(url) + '">')
+        .join('\n');
+    }
+  }
+
   const versionTag = '<meta name="freestruct-build" content="' + buildHash + '">';
   // Marker goes FIRST so the entire generated tail (seo block, later snippet
   // and late-pass insertions land downstream of it) is one strippable region
   // for computeBuildHash's stable view (scan.js) across reruns.
-  html = html.replace(/<\/head>/i, '<!-- freestruct -->\n' + seoInjection + '\n' + versionTag + '\n</head>');
+  // Sequence 3, spot 2 (issue #24): seoInjection is config/page-carried, so
+  // it rides a FUNCTION replacer - in string form any $& / $1..9 inside the
+  // injected head would be treated as replacement syntax and rewrite the page.
+  html = html.replace(/<\/head>/i, () => '<!-- freestruct -->\n' + seoInjection + '\n' + versionTag + '\n</head>');
 
   // Custom snippet passes: comments stripped, advertised placeholders
   // ({{siteName}}, {{siteUrl}}, {{buildHash}}, ...) substituted - FIX for
@@ -273,20 +806,29 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
     if (!fs.existsSync(snippetPath)) return null;
     let snippet = fs.readFileSync(snippetPath, 'utf8');
     for (const [k, v] of Object.entries(replacements)) snippet = snippet.split(k).join(v);
-    return snippet.replace(/<!--[\s\S]*?-->/g, '');
+    const stripped = snippet.replace(/<!--[\s\S]*?-->/g, '');
+    // The shipped snippet templates are comments-only (placeholders/docs for
+    // the consumer to edit), so they strip to whitespace. Injecting that wraps
+    // an empty region in the markers on EVERY page (and the footer's dozen
+    // blank lines): treat a comments-only snippet as absent, not as an empty
+    // injection.
+    return stripped.trim() === '' ? null : stripped;
   }
 
-  // Custom header injection before </head>
+  // Snippet bodies (issue #24): snippet/config-carried text always rides
+  // function replacers - a literal $ sequence in a snippet must print
+  // literally, never interfere with the surrounding document.
   const header = readSnippet('inject-header.html');
-  if (header) html = html.replace(/<\/head>/i, header + '\n</head>');
+  if (header) html = html.replace(/<\/head>/i, () => header + '\n</head>');
 
-  // Custom body-start injection after <body>
+  // Custom body-start injection after <body>. Marker-wrapped so a rerun can
+  // drop the previous copy (stripInjectedRegions) instead of stacking it.
   const bodyStart = readSnippet('inject-body-start.html');
-  if (bodyStart) html = html.replace(/<body[^>]*>/i, '$&' + bodyStart);
+  if (bodyStart) html = html.replace(/<body[^>]*>/i, (m) => m + SNIPPET_OPEN + bodyStart + SNIPPET_CLOSE);
 
-  // Custom footer injection before </body>
+  // Custom footer injection before </body> (marker-wrapped, same reason).
   const footer = readSnippet('inject-footer.html');
-  if (footer) html = html.replace(/<\/body>/i, footer + '\n</body>');
+  if (footer) html = html.replace(/<\/body>/i, () => SNIPPET_OPEN + footer + SNIPPET_CLOSE + '</body>');
 
   if (config.minify) html = minifyHtml(html);
 
@@ -302,7 +844,11 @@ export function addReadingTime(filePath) {
   const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
   if (!bodyMatch) return;
 
-  const text = bodyMatch[1].replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+  // Script/style bodies and comments are not page prose: counting them
+  // inflated the estimate on any page with an inline bundle or a CSS block
+  // (the docs site's own pages carry both). htmlToText strips them, then tags,
+  // then collapses whitespace - the same view the search index reads.
+  const text = htmlToText(bodyMatch[1]);
   const words = text.split(/\s+/).filter(w => w.length > 0);
   const minutes = Math.max(1, Math.ceil(words.length / 200));
 
@@ -324,8 +870,73 @@ export function addLastModified(filePath) {
 export function addLazyLoading(filePath) {
   let html = fs.readFileSync(filePath, 'utf8');
   html = html.replace(/(<img[^>]*(?<!loading)=)[^>]*>/gi, (match) => {
-    if (match.includes('loading=')) return match;
-    return match.replace(/>$/, ' loading="lazy">');
+    // Case-insensitive, whitespace-tolerant guard: HTML attribute names are
+    // case-insensitive and `loading = "eager"` is valid, so a lowercase-only
+    // check let `<img ... LOADING="eager">` collect a SECOND loading attribute.
+    if (/loading\s*=/i.test(match)) return match;
+    // Insert BEFORE the closing `>` (and before a self-closing `/>`), never
+    // between the slash and the bracket - the old `/>`-unaware append left a
+    // dangling `/ loading="lazy">` on `<img ... />` (valid-ish to a browser,
+    // malformed markup everywhere else).
+    return match.replace(/\s*\/?>$/, ' loading="lazy">');
   });
   fs.writeFileSync(filePath, html);
 }
+
+/**
+ * Wrap every <table> in a scroll container so a wide table scrolls inside its
+ * own box instead of pinning the whole page to the table's min-content width
+ * (issue #35: on a ~426px phone a wide docs table clipped the H1, the nav and
+ * everything else). The wrapper carries the class (for consumer theming) plus
+ * the scroll properties inline, so the guard holds by construction on any
+ * layout, including ones whose CSS predates the rule.
+ *
+ * Depth-aware so nested tables wrap once (the outermost); idempotent (a table
+ * already inside a table-ish wrapper is skipped, so runs never stack); and it
+ * leaves the tree untouched when there is no table to wrap (no rewrite, no
+ * spurious build-hash flip).
+ */
+export function addTableWrap(filePath) {
+  let html = fs.readFileSync(filePath, 'utf8');
+  if (!/<table[\s>]/i.test(html)) return;
+
+  // Depth-aware span scan: record [start, end) of each OUTERMOST table block.
+  const tagRe = /<table\b[^>]*>|<\/table\s*>/gi;
+  const spans = [];
+  let depth = 0;
+  let start = -1;
+  let m;
+  while ((m = tagRe.exec(html)) !== null) {
+    if (/^<\/table/i.test(m[0])) {
+      if (depth > 0) {
+        depth--;
+        if (depth === 0) spans.push([start, tagRe.lastIndex]);
+      }
+    } else {
+      if (depth === 0) start = m.index;
+      depth++;
+    }
+  }
+
+  // Skip a table whose immediate ancestor is already a table-style wrapper
+  // (ours from a prior pass, or a consumer's own .table-wrap/.table-responsive).
+  // "table" must be a DELIMITED class segment: "printable"/"portable" do not
+  // count, so a table after an unrelated div still wraps.
+  const wrapped = /<div\b[^>]*\bclass=["']([^"']*)["'][^>]*>\s*$/i;
+  const tableish = (cls) => cls.split(/\s+/).some((tok) => /^table([-_]|$)|[-_]table([-_]|$)/i.test(tok));
+  const todo = spans.filter(([s]) => {
+    const mm = html.slice(0, s).match(wrapped);
+    return !(mm && tableish(mm[1]));
+  });
+  if (todo.length === 0) return;
+
+  // Insert from the end backward so earlier offsets stay valid.
+  let out = html;
+  for (let i = todo.length - 1; i >= 0; i--) {
+    const [s, e] = todo[i];
+    out = out.slice(0, s)
+      + '<div class="fs-table-wrap" style="overflow-x:auto;-webkit-overflow-scrolling:touch;max-width:100%">'
+      + out.slice(s, e) + '</div>' + out.slice(e);
+  }
+  fs.writeFileSync(filePath, out);
+}