freestruct 1.1.0 → 1.2.0

package/engine/seo.js

@@ -7,34 +7,38 @@
 
 import fs from 'fs';
 import path from 'path';
-import { hasSeoType, htmlIsNoindex } from './scan.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) ----------
@@ -54,8 +58,7 @@ function stemForPattern(pattern) {
   return rootHomeSlug;
 }
 
-// Root-home retries: a rest of '/
-' or '/' is the home page, not '//'.
+// Root-home retries: a rest of '/' or '' is the home page, not '//'.
 function slugForHomePage(slug) { return slug === rootHomeSlug ? rootHomeSlug : slug; }
 
 /**
@@ -94,10 +97,15 @@ function breadcrumbJsonLd(page, config) {
   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: (i === segs.length - 1 && page.title) ? page.title : seg.replace(/[-_]/g, ' '),
-      url: pageUrlFor(config, acc),
+      name: (isLeaf && page.title) ? page.title : seg.replace(/[-_]/g, ' '),
+      url: pageUrlFor(config, isLeaf ? page.slug : acc),
     });
   });
   return {
@@ -112,6 +120,20 @@ function breadcrumbJsonLd(page, config) {
   };
 }
 
+/**
+ * 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
@@ -122,11 +144,8 @@ function breadcrumbJsonLd(page, config) {
  */
 function pageReceivesScopedJsonLd(page, config) {
   const jsonLd = config.jsonLd;
-  if (!jsonLd || typeof jsonLd !== 'object' || Array.isArray(jsonLd)) return false;
-  const keys = Object.keys(jsonLd);
-  if (keys.length === 0) return false;
-  if (!keys.every((k) => typeof k === 'string' && k.startsWith('/'))) return false;
-  return keys.some((k) => slugMatchesGlob(k, page.slug));
+  if (!isScopedJsonLdMap(jsonLd)) return false;
+  return Object.keys(jsonLd).some((k) => slugMatchesGlob(k, page.slug));
 }
 
 /**
@@ -178,7 +197,7 @@ function hreflangAlternatesFor(page, config) {
 // '&' 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;')
@@ -239,10 +258,39 @@ 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).
  */
+// 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
@@ -322,7 +370,7 @@ export function injectPage(page, { config, template, buildHash, snippetDir, inje
         ? (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
@@ -340,16 +388,127 @@ export function injectPage(page, { config, template, buildHash, snippetDir, inje
 
   // 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 ''
@@ -402,9 +561,7 @@ export function injectPage(page, { config, template, buildHash, snippetDir, inje
   let customJsonLd = '';
   if (config.jsonLd !== undefined) {
     const jc = config.jsonLd;
-    const isScopedMap = !Array.isArray(jc) && jc && typeof jc === 'object'
-      && Object.keys(jc).length > 0
-      && Object.keys(jc).every((k) => /(^\/|^\*$|^\*\*$|\*)/.test(k));
+    const isScopedMap = isScopedJsonLdMap(jc);
     if (isScopedMap) {
       const keys = Object.keys(jc).sort((a, b) => globSpecificity(b) - globSpecificity(a));
       for (const key of keys) {
@@ -481,6 +638,13 @@ export function injectPage(page, { config, template, buildHash, snippetDir, inje
   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, '');
@@ -503,6 +667,15 @@ export function injectPage(page, { config, template, buildHash, snippetDir, inje
   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')) {
@@ -510,32 +683,59 @@ export function injectPage(page, { config, template, buildHash, snippetDir, inje
     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 && !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.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 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.
-    if (ogImageFull && companionsSource && !hasPerpageOgImage) {
+    // 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');
     }
-    // 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 (articleTags.length) seoInjection += '\n' + articleTags.join('\n');
-  } else if (overrides && [overrides.ogType, overrides.ogImage, 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');
-  } else if (overrides && overrides.twitterCard !== undefined) {
-    pageWarn(page, 'page ships its own Twitter tags; the twitterCard override was not applied');
+  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');
@@ -606,7 +806,13 @@ export function injectPage(page, { config, template, buildHash, snippetDir, inje
     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;
   }
 
   // Snippet bodies (issue #24): snippet/config-carried text always rides
@@ -615,13 +821,14 @@ export function injectPage(page, { config, template, buildHash, snippetDir, inje
   const header = readSnippet('inject-header.html');
   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, (m) => m + 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);
 
@@ -637,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));
 
@@ -659,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);
+}

package/engine/xmllike.js

@@ -8,6 +8,7 @@
 import fs from 'fs';
 import path from 'path';
 import { pageUrlFor } from './urls.js';
+import { extractTitle, extractDescription } from './scan.js';
 
 /** Escape a value for XML text/attribute contexts. */
 export function escXml(value) {
@@ -85,10 +86,12 @@ export function generateFeed(pages, config, outputDir) {
   let items = '';
   for (const page of pages) {
     const html = fs.readFileSync(page.file, 'utf8');
-    const titleMatch = html.match(/<title>([^<]+)<\/title>/i);
-    const descMatch = html.match(/<meta[^>]*name="description"[^>]*content="([^"]+)"/i);
-    const title = titleMatch ? titleMatch[1].split(' | ')[0] : path.basename(page.file).replace(/\.html?$/i, '');
-    const desc = descMatch ? descMatch[1] : '';
+    // Entity-DECODED extraction: the SSG's '&amp;' must reach escXml as a raw
+    // '&' so it escapes ONCE. Reading the raw match and re-escaping double-
+    // encoded the text ('&amp;amp;', which renders literally as '&amp;').
+    const extracted = extractTitle(html);
+    const title = extracted || path.basename(page.file).replace(/\.html?$/i, '');
+    const desc = extractDescription(html) || '';
     const pageUrl = pageUrlFor(config, page.slug);
     const pubDate = page.mtime.toUTCString();
     items += '\n<item>\n'

package/init/README.md

@@ -1,10 +1,6 @@
 # Freestruct init kit
 
-This is the consumer scaffold kit (prestruct's `init/` pattern, sized to
-Freestruct): the minimum a brand-new project copies in to be Freestruct-ready
-in minutes. Freestruct runs AFTER your static site generator builds, so the
-kit is deliberately SSG-agnostic - your Jekyll/Hugo/Docusaurus/MkDocs setup
-stays untouched.
+This is the consumer scaffold kit (prestruct's `init/` pattern, sized to Freestruct): the minimum a brand-new project copies in to be Freestruct-ready in minutes. Freestruct runs AFTER your static site generator builds, so the kit is deliberately SSG-agnostic - your Jekyll/Hugo/Docusaurus/MkDocs setup stays untouched.
 
 ## What's in the kit
 
@@ -28,21 +24,11 @@ cp -r node_modules/freestruct/init/docs .
 
 Then:
 
-1. Edit `docs/freestruct.config.yml`: `site.name` and `site.url` are required;
-   adjust `site.description` to fit.
-2. Let your SSG build. `npx freestruct` discovers the output dir
-   (default `docs/_site`; override via the `outputDir` config key or a
-   positional CLI argument).
-3. Verify: `docs/_site` gains `sitemap.xml`, `robots.txt`, `feed.xml` and
-   (when missing) a `404.html`; injected pages carry canonical/OG tags and a
-   `freestruct-build` marker.
-4. Customize templates only if you need to: the packaged engine templates are
-   used automatically when no staged copy exists. To customize, edit
-   `docs/_freestruct/` copies (which you just copied in) - a staged template
-   always wins over the package-shipped one.
+1. Edit `docs/freestruct.config.yml`: `site.name` and `site.url` are required; adjust `site.description` to fit. The starter also seeds the family identity - an `author` block (the Creadev.org founder) and a `jsonLd` maintainer Person - so scaffolded ports ship ownership from birth; set the maintainer handle to your own.
+2. Let your SSG build. `npx freestruct` discovers the output dir (default `docs/_site`; override via the `outputDir` config key or a positional CLI argument).
+3. Verify: `docs/_site` gains `sitemap.xml`, `robots.txt`, `feed.xml` and (when missing) a `404.html`; injected pages carry canonical/OG tags and a `freestruct-build` marker.
+4. Customize templates only if you need to: the packaged engine templates are used automatically when no staged copy exists. To customize, edit `docs/_freestruct/` copies (which you just copied in) - a staged template always wins over the package-shipped one.
 
 ## Why a kit (not a lucky guess)
 
-Copying this kit means your first run exercises the exact shape the test
-battery and the tarball e2e verify: staged config + staged templates next to
-the docs folder, discovered by walking up from your project root.
+Copying this kit means your first run exercises the exact shape the test battery and the tarball e2e verify: staged config + staged templates next to the docs folder, discovered by walking up from your project root.

package/init/VERSION

@@ -1 +1 @@
-1.1.0
+1.2.0