freestruct 1.1.0 → 1.2.0

package/engine/inject.js

@@ -35,8 +35,8 @@ import path from 'path';
 import { pathToFileURL, fileURLToPath } from 'url';
 
 import { loadConfig } from './config.js';
-import { getHtmlFiles, buildPages, computeBuildHash, htmlIsNoindex, hasSeoType } from './scan.js';
-import { injectPage, addReadingTime, addLastModified, addLazyLoading } from './seo.js';
+import { getHtmlFiles, buildPages, computeBuildHash, htmlIsNoindex, hasSeoType, dedupeBySlug } from './scan.js';
+import { injectPage, addReadingTime, addLastModified, addLazyLoading, addTableWrap } from './seo.js';
 import { generateSitemap, generateRobots, generateFeed } from './xmllike.js';
 import { generate404, pipeline404 } from './notfound.js';
 import { checkLinks } from './linkcheck.js';
@@ -55,14 +55,35 @@ const _flags = _argv.filter(a => FLAG_VALUES.has(a));
 // any other bare word stays the outputDir override it always was.
 const COMMANDS = new Set(['validate', 'init', 'help', 'audit', 'indexnow']);
 const _firstArg = _argv.find(a => !a.startsWith('--'));
-const _positional = _firstArg && !COMMANDS.has(_firstArg) ? _firstArg : undefined;
-// Pass 26.16: dash-shaped args are FLAGS, never output dirs. The audit and
-// indexnow subcommands validate their own flags; the default run must do the
-// same for its set, instead of letting a typo'd flag ride as a positional
-// and inject somewhere the user never meant (the same quiet-mistake class
-// the source-tree guard closes).
-const KNOWN_DEFAULT_DASHES = ['-h', '--help', '--version', '--strict', '--tolerant'];
-const unknownDashArgs = _argv.filter(a => a.startsWith('-') && !KNOWN_DEFAULT_DASHES.includes(a));
+// Args that follow a subcommand word (`_argv` minus the command itself).
+const afterCommand = (name) => _argv.slice(_argv.indexOf(name) + 1);
+
+// Pass 26.16 + 26.44: dash-shaped args are FLAGS, never output dirs, and each
+// command's flag/positional surface is CLOSED. An unknown flag or a surplus
+// positional is a typo, refused with the supported set instead of silently
+// ignored - before this, `init --bogus` scaffolded into a directory literally
+// named `--bogus`, `init a b c` dropped `b`/`c`, `audit -x` rode as an output
+// dir (exit 3, "not found") and `validate --bogus` ran as if clean.
+const GLOBAL_FLAGS = ['-h', '--help', '--version', '--strict', '--tolerant'];
+function parseArgs(args, { command, flags = [], maxPositionals = 0 }) {
+  const allowed = new Set([...GLOBAL_FLAGS, ...flags]);
+  const seen = new Set();
+  const positionals = [];
+  for (const a of args) {
+    if (a.startsWith('-')) {
+      if (!allowed.has(a)) {
+        fail(command + ': unknown flag ' + a + ' - run freestruct --help for the flag list (supported: ' + (flags.length ? flags.join(' ') : 'none') + ')');
+      }
+      seen.add(a);
+    } else {
+      positionals.push(a);
+    }
+  }
+  if (positionals.length > maxPositionals) {
+    fail(command + ': too many arguments (got ' + positionals.length + ', expected at most ' + maxPositionals + ')');
+  }
+  return { positionals, flags: seen };
+}
 
 export const EXIT_OK = 0;
 export const EXIT_CONFIG = 1;
@@ -128,6 +149,7 @@ function printHelp() {
  * exits EXIT_CONFIG, honoring --tolerant like every other fatal.
  */
 function cmdValidate() {
+  parseArgs(afterCommand('validate'), { command: 'validate' });
   let loaded;
   try {
     loaded = loadConfig(process.cwd());
@@ -144,7 +166,9 @@ function cmdValidate() {
  * clobbering an existing file. Mirrors the manual `cp -r node_modules/
  * freestruct/init/docs .` shape the init kit README describes.
  */
-function cmdInit(dirArg) {
+function cmdInit() {
+  const { positionals } = parseArgs(afterCommand('init'), { command: 'init', maxPositionals: 1 });
+  const dirArg = positionals[0];
   const targetRoot = path.resolve(process.cwd(), dirArg || '.');
   const docsDir = path.join(targetRoot, 'docs');
   // engine/inject.js -> package root -> init/docs (files list ships init/)
@@ -178,11 +202,12 @@ export function runInject(options = {}) {
   // them (with --external the only path that lives past the import, this
   // guard is what keeps the engine from re-injecting mid-audit).
   if (_firstArg && COMMANDS.has(_firstArg)) return;
-  // Unknown dash-words are typos, not directories: fail with the usage hint
-  // instead of riding as a positional (Pass 26.16).
-  if (unknownDashArgs.length) {
-    fail('unknown flag(s): ' + unknownDashArgs.join(' ') + ' - run freestruct --help for the flag list', EXIT_CONFIG);
-  }
+  // The default run's own closed surface (Pass 26.44): flags are the three
+  // run-shaping ones, and at most ONE positional (the output-dir override).
+  // An unknown flag or a surplus positional is refused with the usage hint
+  // instead of riding as a directory (Pass 26.16's typo class, closed).
+  const { positionals: defaultPositionals } = parseArgs(_argv, { command: 'freestruct', flags: ['--strict', '--tolerant'], maxPositionals: 1 });
+  const _positional = defaultPositionals[0];
   const cwd = options.cwd || process.cwd();
   console.log('freestruct: Loading config...');
 
@@ -239,6 +264,22 @@ export function runInject(options = {}) {
   if (!fs.existsSync(templatePath)) {
     fail('Template not found: ' + templatePath + ' (shipped copy also missing at ' + packageTemplateDir + ')', EXIT_TEMPLATE);
   }
+  // Template-shape warning (issue #46): a STAGED inject-brand.html REPLACES
+  // the packaged default outright (it is the whole head template, not a
+  // per-slot merge), so a partial file silently drops every slot it does not
+  // list - the packaged default carries canonical + the full og/twitter set +
+  // identity JSON-LD, and a host that stages "just the layer the layout lacks"
+  // loses the rest on EVERY page. Name the core slots a staged template omits.
+  const stagedTemplatePath = path.join(configDir, '_freestruct', 'inject-brand.html');
+  if (fs.existsSync(stagedTemplatePath)) {
+    const stagedTemplate = fs.readFileSync(stagedTemplatePath, 'utf8');
+    const CORE_SLOTS = ['{{canonicalUrl}}', '{{pageTitle}}'];
+    const missingSlots = CORE_SLOTS.filter(k => !stagedTemplate.includes(k));
+    if (missingSlots.length) {
+      console.log('[freestruct] config warning: staged docs/_freestruct/inject-brand.html REPLACES the packaged head template (it is not merged per slot) and omits '
+        + missingSlots.join(', ') + ' - those head slots ship missing on every page. Carry the full default set, or delete the file to use the packaged template.');
+    }
+  }
   const template = fs.readFileSync(templatePath, 'utf8');
 
   const htmlFiles = getHtmlFiles(outputDir);
@@ -282,14 +323,18 @@ export function runInject(options = {}) {
 
     // 404 pipeline: generated when absent, user-supplied folded into the
     // same full treatment (Phase 1.4). Runs after regular pages so a 404
-    // already present in the tree is not double-processed above.
+    // already present in the tree is not double-processed above. EVERY 404
+    // file gets the treatment: a tree carrying both 404.html and 404.htm (a
+    // valid pair on hosts that serve either) had only the FIRST processed, so
+    // the second shipped with no noindex meta and the audit failed the run's
+    // own output.
     const processed404s = [];
     if (config.generate404 !== false) {
-      let page404 = pages.find(p => p.is404);
-      if (!page404) {
+      const found404s = pages.filter(p => p.is404);
+      if (found404s.length === 0) {
         const file404 = generate404(config, outputDir, buildHash, template, snippetDir);
         const html404 = fs.readFileSync(file404, 'utf8');
-        page404 = {
+        found404s.push({
           file: file404,
           rel: '404.html',
           slug: '/404',
@@ -298,9 +343,9 @@ export function runInject(options = {}) {
           mtime: new Date(),
           title: html404.match(/<title>([^<]+)<\/title>/i)?.[1]?.split(' | ')[0] || null,
           description: html404.match(/<meta name="description" content="([^"]+)"/i)?.[1] || null,
-        };
+        });
       }
-      processed404s.push(pipeline404(page404, injectCtx));
+      for (const page404 of found404s) processed404s.push(pipeline404(page404, injectCtx));
     }
 
     // Late passes over every processed page, 404s included (Phase 1.4)
@@ -308,17 +353,42 @@ export function runInject(options = {}) {
     if (config.readingTime !== false) for (const page of latePages) addReadingTime(page.file);
     if (config.lastModified !== false) for (const page of latePages) addLastModified(page.file);
     if (config.lazyLoad !== false) for (const page of latePages) addLazyLoading(page.file);
+    // table guard (issue #35): wrap wide tables so every downstream site is
+    // mobile-safe by construction. Default-on; `tableWrap: false` opts out.
+    if (config.tableWrap !== false) for (const page of latePages) addTableWrap(page.file);
+
+    // Restore each page's pre-injection mtime after our writes. freestruct
+    // rewrites every page it decorates, so without this the NEXT run's
+    // buildPages snapshot captures freestruct's own write as the page mtime -
+    // and feed pubDate / sitemap lastmod (both derived from that mtime, the
+    // issue #9 honest-date contract: "the date the page last actually
+    // changed, not the build time") churned on every rerun with no content
+    // change. Restoring makes the dates stable across reruns and still
+    // advances when the SSG rebuilds the page. The generated 404 is excluded
+    // (freestruct owns it; it never reaches the feed/sitemap).
+    for (const page of latePages) {
+      try { fs.utimesSync(page.file, page.mtime, page.mtime); } catch (e) { /* mtime best-effort */ }
+    }
 
     // noindex is honored by default (owner decision, issue #5):
     // noindex pages never ship into sitemap/feed/search
-    const indexablePages = pages.filter(p => !p.is404 && !htmlIsNoindex(p.html));
+    // Dedupe by slug first: a tree with both `a.html` and `a.htm` (or
+    // `index.html`/`index.htm` in one dir) maps two files onto ONE url, and
+    // without this the artifact lists that url twice (duplicate <loc>/<item>).
+    // Both files still get decorated above; only the url listings collapse.
+    const indexablePages = dedupeBySlug(pages.filter(p => !p.is404 && !htmlIsNoindex(p.html)));
 
     if (config.generateSitemap !== false) generateSitemap(indexablePages, config, outputDir);
     if (config.generateRobots !== false) generateRobots(config, outputDir);
     if (config.generateFeed !== false) generateFeed(indexablePages, config, outputDir);
 
-    // link check over regular pages (404 targets excluded by design)
-    const brokenLinks = config.linkCheck !== false ? checkLinks(sitePages.map(p => p.file), outputDir) : [];
+    // link check over regular pages (404 targets excluded by design).
+    // basePath threads through so root-absolute hrefs on a baseurl'd site
+    // (which carry the deploy prefix) resolve against the tree, not the
+    // prefix as a directory (issue #32).
+    const brokenLinks = config.linkCheck !== false
+      ? checkLinks(sitePages.map(p => p.file), outputDir, config.basePath)
+      : [];
 
     // opt-in search index (owner decision: search.json is opt-in as of Phase 2)
     if (config.searchIndex === true) generateSearchIndex(indexablePages, config, outputDir);
@@ -378,8 +448,12 @@ export function runInject(options = {}) {
 // (the pre-change --version module-level check had the same shape). Library
 // importers pass no such argv and simply skip all of these.
 if (_flags.includes('--version')) { printVersion(); process.exit(0); }
-// `help` is the subcommand; --help is the flag alias (both print the same text)
-if (_firstArg === 'help' || _argv.includes('--help')) { printHelp(); process.exit(EXIT_OK); }
+// `help` is the subcommand; --help and -h are the flag aliases (all print the
+// same text). -h must be handled HERE: it is listed in KNOWN_DEFAULT_DASHES,
+// so without this branch it passes the unknown-flag guard and then rides as
+// the positional output dir (the run then dies with "Output directory not
+// found: .../-h").
+if (_firstArg === 'help' || _argv.includes('--help') || _argv.includes('-h')) { printHelp(); process.exit(EXIT_OK); }
 // ---------- audit subcommand (issue #18) ----------
 
 // `freestruct audit [outputDir] [--json]`: verify the BAKED output (heads +
@@ -389,14 +463,12 @@ if (_firstArg === 'help' || _argv.includes('--help')) { printHelp(); process.exi
 // the run walks up from cwd (it maps basePath for the on-disk asset checks);
 // a configless audit just runs without the disk-mapping extras.
 async function cmdAudit() {
-  const auditArgs = _argv.slice(_argv.indexOf('audit') + 1);
-  const useJson = auditArgs.includes('--json');
-  const useExternal = auditArgs.includes('--external');
-  const explicitDir = auditArgs.find(a => !a.startsWith('--'));
-
-  if (auditArgs.filter(a => a.startsWith('--')).some(a => a !== '--json' && a !== '--external')) {
-    fail('audit: only --json and --external are supported flags (got ' + auditArgs.filter(a => a.startsWith('--')).join(' ') + ')');
-  }
+  const { positionals, flags } = parseArgs(afterCommand('audit'), {
+    command: 'audit', flags: ['--json', '--external'], maxPositionals: 1,
+  });
+  const useJson = flags.has('--json');
+  const useExternal = flags.has('--external');
+  const explicitDir = positionals[0];
 
   let config = null;
   let configDir = process.cwd();
@@ -443,13 +515,11 @@ async function cmdAudit() {
 // verify ownership, so this is documented as the post-deploy step (CI often
 // wants --dry-run at build time). Exit 0 accepted/dry-run | 1 failure.
 async function cmdIndexNow() {
-  const idxArgs = _argv.slice(_argv.indexOf('indexnow') + 1);
-  const dryRun = idxArgs.includes('--dry-run');
-  const explicitDir = idxArgs.find(a => !a.startsWith('--'));
-
-  if (idxArgs.filter(a => a.startsWith('--')).some(a => a !== '--dry-run')) {
-    fail('indexnow: only --dry-run is a supported flag');
-  }
+  const { positionals, flags } = parseArgs(afterCommand('indexnow'), {
+    command: 'indexnow', flags: ['--dry-run'], maxPositionals: 1,
+  });
+  const dryRun = flags.has('--dry-run');
+  const explicitDir = positionals[0];
 
   let config = null;
   let configDir = process.cwd();
@@ -482,7 +552,7 @@ async function cmdIndexNow() {
 }
 
 if (_firstArg === 'validate') cmdValidate();
-if (_firstArg === 'init') cmdInit(_argv[_argv.indexOf('init') + 1]);
+if (_firstArg === 'init') cmdInit();
 if (_firstArg === 'audit') cmdAudit().catch((e) => fail('audit: ' + (e && e.message ? e.message : e)));
 if (_firstArg === 'indexnow') { cmdIndexNow(); }
 

package/engine/linkcheck.js

@@ -15,9 +15,21 @@ import path from 'path';
  * then the .html/.htm sibling file. Assets stay out of the checker's
  * purview (see the shape test above the flags).
  */
-export function checkLinks(files, outputDir) {
+export function checkLinks(files, outputDir, basePath = '') {
   const broken = [];
 
+  // basePath is the URL path prefix the output tree is SERVED under (same
+  // semantics urls.js owns for canonical/sitemap). A root-absolute href on a
+  // baseurl'd site carries that prefix ("/myrepo/guides/cli"), but inside the
+  // output tree the prefix is not a directory - resolving it literally turned
+  // every nav link into a miss and failed --strict for every baseurl'd site
+  // (issue #32). Strip the EXACT prefix before resolving; an href carrying a
+  // DIFFERENT prefix stays broken (the strip must match the configured
+  // basePath, not "any leading segment").
+  const prefix = basePath
+    ? ('/' + String(basePath).replace(/^\/+/, '')).replace(/\/+$/, '')
+    : '';
+
   for (const file of files) {
     // Payload stripping (Pass 26.14): inline JS template strings
     // ("<a href=" + url + ">" shapes) are NOT links; rouge-fenced code
@@ -31,10 +43,16 @@ export function checkLinks(files, outputDir) {
       .replace(/<code[\s\S]*?<\/code>/gi, '');
     const baseDir = path.dirname(file);
 
-    const linkRegex = /href="([^"#]+)(?:#[^"]*)?"/g;
+    // Both quote styles (bug fix): the old /href="..."/ only saw
+    // double-quoted hrefs, so a single-quoted broken link (`href='/gone/'`,
+    // valid HTML) sailed through --strict. The backreference keeps the pair
+    // consistent; the fragment is stripped from the checked target either way.
+    // Case-insensitive (HTML attribute names are): an upper-case `HREF=`
+    // (valid markup) was skipped entirely, so a broken link shipped green.
+    const linkRegex = /href=(["'])([^"'#]+)(?:#[^"']*)?\1/gi;
     let match;
     while ((match = linkRegex.exec(html)) !== null) {
-      const link = match[1];
+      const link = match[2];
 
       // Skip external, absolute-protocol, and ANY scheme-shaped target
       // (data:, javascript:, tel:, mailto:, ...): schemes are not routes.
@@ -44,9 +62,23 @@ export function checkLinks(files, outputDir) {
       // against the OUTPUT ROOT - path.join(baseDir, '/x') APPENDS, it never
       // resets, which turned every menu link on a nested page into a miss
       // (the CI --strict run caught it). Relative hrefs stay page-relative.
-      const absPath = link.startsWith('/')
-        ? path.join(outputDir, link)
-        : path.join(baseDir, link);
+      // A root-absolute href that carries the configured basePath has that
+      // prefix stripped first (issue #32); one with a different prefix keeps
+      // it and resolves (correctly) as broken.
+      let target = link;
+      // A query string is not part of the route: '/guide?foo=bar' serves the
+      // same page as '/guide'. Resolving the raw value looked for a file
+      // literally named 'guide?foo=bar' and reported a valid link broken
+      // (failing --strict on any site whose nav carries query params, e.g. a
+      // utm-tagged or search-fed link). Strip it before resolving.
+      const q = target.indexOf('?');
+      if (q !== -1) target = target.slice(0, q);
+      if (target.startsWith('/') && prefix && (target === prefix || target.startsWith(prefix + '/'))) {
+        target = target.slice(prefix.length) || '/';
+      }
+      const absPath = target.startsWith('/')
+        ? path.join(outputDir, target)
+        : path.join(baseDir, target);
       const normalized = path.normalize(absPath);
 
       // Targeted file link: extension decides the check shape (case-

package/engine/llms.js

@@ -23,6 +23,17 @@ function oneline(value) {
     .trim();
 }
 
+/**
+ * A markdown link LABEL: `[` and `]` inside it would close the label early,
+ * so the emitted link renders as broken text (a title like 'Foo] bar' or a
+ * '[preview]' tag produced '- [Foo] bar](url)' - the URL spilled into the
+ * prose and the link broke). Escape the brackets, and the backslash itself,
+ * so the label always renders as the literal title.
+ */
+function mdLabel(value) {
+  return oneline(value).replace(/([\\\[\]])/g, '\\$1');
+}
+
 /**
  * Write llms.txt into the output dir. Pages only: indexable = non-404,
  * non-noindex (the same gate sitemap/feed honor, so noindex stays honored
@@ -41,7 +52,7 @@ export function generateLlms(indexablePages, config, outputDir) {
   lines.push('', '## Docs', '');
   for (const page of indexablePages) {
     const url = pageUrlFor(config, page.slug);
-    const title = oneline(page.title || page.slug);
+    const title = mdLabel(page.title || page.slug);
     const desc = page.description ? ': ' + oneline(page.description) : '';
     lines.push('- [' + title + '](' + url + ')' + desc);
   }

package/engine/notfound.js

@@ -5,7 +5,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { injectPage } from './seo.js';
+import { injectPage, escAttr } from './seo.js';
 import { pageUrlFor } from './urls.js';
 import { stripRobotsMeta } from './scan.js';
 
@@ -14,8 +14,12 @@ export function generate404(config, outputDir, buildHash, template, snippetDir)
   const file = path.join(outputDir, '404.html');
   // Links follow the pageUrlFor contract (basePath-aware) - raw site.url
   // guesses like '/docs/' point at 404s on sub-path installs (#3 class).
-  const siteName = config.site.name || 'Site';
-  const homeUrl = pageUrlFor(config, '/');
+  // The site name and the home URL land in HTML text/attribute slots, so they
+  // ride escAttr: a quote-bearing or '<'-bearing site name otherwise broke the
+  // <title> and could inject markup into the error page (the Pass 26.21 walk
+  // claimed this was escaped - it was not).
+  const siteName = escAttr(config.site.name || 'Site');
+  const homeUrl = escAttr(pageUrlFor(config, '/'));
   const notFound = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -64,10 +68,22 @@ export function pipeline404(page, context) {
   // drop any pre-existing robots meta so ours is the single source of truth
   // (scan.js's stripper exists for exactly this - one regex, one owner)
   html = stripRobotsMeta(html);
-  html = html.replace(/<\/head>/i, '<meta name="robots" content="noindex, nofollow">\n</head>');
-  fs.writeFileSync(page.file, html);
   page.html = html;
+  fs.writeFileSync(page.file, html);
 
   injectPage(page, context);
+
+  // Assert the noindex AFTER injectPage, not before: injectPage's rerun
+  // hygiene (stripInjectedRegions) deletes everything from the
+  // `<!-- freestruct -->` marker to `</head>`, so a noindex inserted before
+  // the marker on run 1 fell INSIDE that span once the marker existed on
+  // run 2 and was stripped - a second `freestruct` run silently dropped the
+  // 404 noindex and the audit then failed the page. Re-assert it here, past
+  // the strip, and it stays put across reruns.
+  let out = fs.readFileSync(page.file, 'utf8');
+  out = stripRobotsMeta(out);
+  out = out.replace(/<\/head>/i, '<meta name="robots" content="noindex, nofollow">\n</head>');
+  fs.writeFileSync(page.file, out);
+  page.html = out;
   return page;
 }

package/engine/scan.js

@@ -43,6 +43,37 @@ export function is404File(rel) {
   return /(^|\/)404\.html?$/i.test(p);
 }
 
+/**
+ * Collapse pages that map to the SAME slug (one URL) to a single entry, so a
+ * tree carrying both `a.html` and `a.htm` (or `index.html` and `index.htm` in
+ * one directory) does not list one URL twice in sitemap.xml / feed.xml /
+ * search.json / llms.txt. Deterministic winner: `.html` over `.htm` (the
+ * pretty-URL resolver's own preference), then the lexicographically smaller
+ * rel path. Order is preserved by first appearance.
+ */
+export function dedupeBySlug(pages) {
+  const bySlug = new Map();
+  for (const page of pages) {
+    const current = bySlug.get(page.slug);
+    if (!current) { bySlug.set(page.slug, page); continue; }
+    const better = (a, b) => {
+      const aHtml = /\.html$/i.test(a.rel) ? 0 : 1;
+      const bHtml = /\.html$/i.test(b.rel) ? 0 : 1;
+      if (aHtml !== bHtml) return aHtml < bHtml ? a : b;
+      return a.rel <= b.rel ? a : b;
+    };
+    bySlug.set(page.slug, better(current, page));
+  }
+  const seen = new Set();
+  const out = [];
+  for (const page of pages) {
+    if (seen.has(page.slug)) continue;
+    seen.add(page.slug);
+    out.push(bySlug.get(page.slug));
+  }
+  return out;
+}
+
 /** Robots noindex detection on (possibly injected) HTML. */
 export function htmlIsNoindex(html) {
   const m = html.match(/<meta[^>]*name=["']robots["'][^>]*>/i);
@@ -54,17 +85,81 @@ export function stripRobotsMeta(html) {
   return html.replace(/<meta[^>]*name=["']robots["'][^>]*>/i, '');
 }
 
-/** Extract SEO candidates from raw page HTML. (kept from 0.3.x semantics) */
+/**
+ * Decode the HTML entities an SSG routinely writes into <title>/meta content
+ * (&amp; &lt; &gt; &quot; &#39;). Without this, an entity-encoded source fact
+ * flowed verbatim into the generated artifacts: the feed re-escaped the
+ * already-escaped '&amp;' into '&amp;amp;' (double-encoded text a reader
+ * sees as '&amp;'), and search.json/llms.txt carried raw entities into
+ * plain-text/JSON contexts that render them literally.
+ */
+// Common named entities (the ones that realistically appear in titles and
+// descriptions) plus numeric forms. A title carrying '&#8217;' or '&mdash;'
+// was left literal by the old five-entry map, so the feed double-escaped it
+// ('&amp;#8217;', which renders as the literal entity text) and the length
+// graders counted the markup instead of the character.
+const NAMED_ENTITIES = {
+  lt: '<', gt: '>', quot: '"', apos: "'", amp: '&',
+  nbsp: '\u00a0', mdash: '\u2014', ndash: '\u2013', hellip: '\u2026',
+  lsquo: '\u2018', rsquo: '\u2019', ldquo: '\u201c', rdquo: '\u201d',
+  copy: '\u00a9', reg: '\u00ae', trade: '\u2122', deg: '\u00b0',
+  times: '\u00d7', laquo: '\u00ab', raquo: '\u00bb', middot: '\u00b7',
+  bull: '\u2022', euro: '\u20ac', pound: '\u00a3', yen: '\u00a5',
+  cent: '\u00a2', sect: '\u00a7', para: '\u00b6', dagger: '\u2020',
+  plusmn: '\u00b1', frac12: '\u00bd', frac14: '\u00bc', frac34: '\u00be',
+};
+
+export function decodeEntities(value) {
+  return String(value == null ? '' : value)
+    // Numeric forms first: decimal '&#8217;' and hex '&#x2019;'. Doing these
+    // before the named pass keeps single-pass semantics ('&amp;#65;' stays
+    // the literal '&#65;' after the amp pass, never '<').
+    .replace(/&#x([0-9a-f]+);/gi, (m, hex) => {
+      const cp = parseInt(hex, 16);
+      return cp >= 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+    })
+    .replace(/&#(\d+);/g, (m, dec) => {
+      const cp = parseInt(dec, 10);
+      return cp >= 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
+    })
+    .replace(/&([a-z][a-z0-9]*);/gi, (m, name) => {
+      const key = name.toLowerCase();
+      return Object.prototype.hasOwnProperty.call(NAMED_ENTITIES, key) ? NAMED_ENTITIES[key] : m;
+    });
+}
+
+// Quoted-attribute reader (same shape audit.js owns): the closing quote must
+// MATCH the opening one, so a value holding the other quote kind (an
+// apostrophe in a description) is read whole instead of truncated at it.
+function attrValue(tag, attr) {
+  const quoted = tag.match(new RegExp(`\\b${attr}=(["'])([\\s\\S]*?)\\1`, 'i'));
+  if (quoted) return quoted[2];
+  const bare = tag.match(new RegExp(`\\b${attr}=([^\\s>]+)`, 'i'));
+  return bare ? bare[1] : null;
+}
+
+/**
+ * Extract SEO candidates from raw page HTML. Attribute-ORDER tolerant and
+ * quote-agnostic (Pass 26.21): the old fixed `name="title" content="..."`
+ * shape missed a reordered or single-quoted meta, so the page silently fell
+ * back to the site-level value. Values are entity-decoded so downstream
+ * artifacts (feed/search/llms) receive plain text, not raw entities.
+ */
 export function extractTitle(html) {
-  const m = html.match(/<meta name="title" content="([^"]+)"/i);
-  if (m) return m[1];
-  const t = html.match(/<title>([^<]+)<\/title>/i);
-  return t ? t[1].split(' | ')[0] : null;
+  const meta = html.match(/<meta\b[^>]*\bname=["']title["'][^>]*>/i);
+  if (meta) {
+    const v = attrValue(meta[0], 'content');
+    if (v) return decodeEntities(v);
+  }
+  const t = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+  return t ? decodeEntities(t[1]).split(' | ')[0] : null;
 }
 
 export function extractDescription(html) {
-  const m = html.match(/<meta name="description" content="([^"]+)"/i);
-  return m ? m[1] : null;
+  const meta = html.match(/<meta\b[^>]*\bname=["']description["'][^>]*>/i);
+  if (!meta) return null;
+  const v = attrValue(meta[0], 'content');
+  return v ? decodeEntities(v) : null;
 }
 
 /**
@@ -92,11 +187,33 @@ export function hasSeoType(html, type) {
     return /<link[^>]+rel=["']canonical["']/i.test(html);
   }
   if (type === 'description') {
-    return /<meta[^>]*name=["']description["']/.test(html);
+    // Case-insensitive like every branch above: an SSG/author emitting an
+    // upper- or mixed-case meta (<META NAME="description" ...>, valid HTML)
+    // missed this gate, so freestruct injected a SECOND description and its
+    // own audit then failed the page for the duplicate it caused.
+    return /<meta[^>]*name=["']description["']/i.test(html);
   }
   return false;
 }
 
+/**
+ * Visible text of an HTML fragment: script/style bodies and comments drop
+ * first, then every tag, whitespace collapses, and entities decode. Shared by
+ * the search index and the reading-time estimator - both count page prose, and
+ * both were inflated by raw JS/CSS when each stripped tags alone.
+ */
+export function htmlToText(html) {
+  return decodeEntities(
+    String(html)
+      .replace(/<script[\s\S]*?<\/script\s*>/gi, ' ')
+      .replace(/<style[\s\S]*?<\/style\s*>/gi, ' ')
+      .replace(/<!--[\s\S]*?-->/g, ' ')
+      .replace(/<[^>]+>/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim(),
+  );
+}
+
 /**
  * Snapshot every page once, before freestruct writes anything.
  * mtime is captured HERE so sitemap lastmod / RSS pubDate reflect the last
@@ -150,7 +267,16 @@ export function computeBuildHash(config, pages) {
   const stable = (html) => html
     .replace(/<meta[^>]*name="(freestruct-build|last-modified|reading-time|robots)"[^>]*>/gi, '')
     .replace(/<!-- freestruct -->[\s\S]*?(?=<\/head>)/i, '')
-    .replace(/\?v=[0-9a-f]{8}/g, '')
+    // Body-start/footer snippets (marker-wrapped by seo.js) are the tool's own
+    // output; strip them too or a rerun's body text differs from run 1 and the
+    // content-derived hash churns every pass.
+    .replace(/<!-- freestruct:snippet -->[\s\S]*?<!-- \/freestruct:snippet -->/gi, '')
+    // The tableWrap pass (seo.js addTableWrap) wraps each outermost table in a
+    // tool-owned div AFTER the hash is computed, so a rerun's page content
+    // carries the wrapper the first run did not - without this strip the
+    // content-derived hash churned on every pass for any site with a table.
+    .replace(/<div class="fs-table-wrap"[^>]*>\s*(<table[\s\S]*?<\/table>)\s*<\/div>/gi, '$1')
+    .replace(/[?&]v=[0-9a-f]{8}/g, '')
     .replace(/ loading="lazy"/g, '');
   for (const page of pages.filter(p => !p.is404).sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0))) {
     h.update(page.rel);

package/engine/search.js

@@ -8,6 +8,7 @@
 import fs from 'fs';
 import path from 'path';
 import { pageUrlFor } from './urls.js';
+import { extractTitle, extractDescription, htmlToText } from './scan.js';
 
 export function generateSearchIndex(pages, config, outputDir) {
   const index = [];
@@ -19,18 +20,20 @@ export function generateSearchIndex(pages, config, outputDir) {
     // would search; raw file content at this point is the injected page).
     const html = fs.readFileSync(page.file, 'utf8');
 
-    const titleMatch = html.match(/<title>([^<]+)<\/title>/i);
-    const descMatch = html.match(/<meta[^>]*name="description"[^>]*content="([^"]+)"/i);
-    const h1Match = html.match(/<h1[^>]*>([^<]+)<\/h1>/i);
+    // Entity-decoded, tag-free extraction (Pass 26.21 / 26.24): search.json is
+    // JSON consumed by JS, where '&amp;' renders literally as '&amp;' and a
+    // stray '<em>' renders as nothing. htmlToText drops script/style bodies
+    // and comments, strips every tag, and decodes entities, so the index
+    // carries plain page text (the old tag-only strip shipped raw JS/CSS, and
+    // the heading pass returned the h1's inner HTML with its tags).
+    const h1Match = html.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i);
 
     const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
-    const content = bodyMatch
-      ? bodyMatch[1].replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 500)
-      : '';
+    const content = bodyMatch ? htmlToText(bodyMatch[1]).slice(0, 500) : '';
 
-    const title = titleMatch ? titleMatch[1].split(' | ')[0] : path.basename(page.file).replace(/\.html?$/i, '');
-    const description = descMatch ? descMatch[1] : '';
-    const heading = h1Match ? h1Match[1] : title;
+    const title = extractTitle(html) || path.basename(page.file).replace(/\.html?$/i, '');
+    const description = extractDescription(html) || '';
+    const heading = h1Match ? htmlToText(h1Match[1]) : title;
     const url = pageUrlFor(config, page.slug);
 
     index.push({ title, heading, description, content, url });