freestruct 1.0.0 → 1.1.0

package/engine/scan.js

@@ -13,31 +13,34 @@ export function getHtmlFiles(dir) {
   for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
     const fp = path.join(dir, item.name);
     if (item.isDirectory()) files.push(...getHtmlFiles(fp));
-    else if (item.name.endsWith('.html')) files.push(fp);
+    // Case-insensitive .html/.htm (Pass 26.10): a consumer SSG that emits
+    // .HTM or upper-case extensions is a page like any other - the old
+    // suffix test silently dropped it from every artifact.
+    else if (/\.html?$/i.test(item.name)) files.push(fp);
   }
   return files;
 }
 
-/**
- * Canonical slug for a file relative to the output root.
+/** Canonical slug for a file relative to the output root.
  *   index.html       -> '/'
  *   guide/index.html -> '/guide/'
  *   a&b.html         -> '/a&b'
+ *   legacy.htm       -> '/legacy' (case-insensitive .html/.htm)
  */
 export function slugFor(rel) {
   let p = String(rel).replace(/\\/g, '/');
-  if (p === '/index.html' || p === 'index.html') return '/';
+  if (/^\/?index\.html?$/i.test(p)) return '/';
   p = '/' + p;
   p = p
-    .replace(/\/index\.html$/, '/')
-    .replace(/\.html$/, '');
+    .replace(/\/index\.html?$/i, '/')
+    .replace(/\.html?$/i, '');
   return p;
 }
 
 /** 404.html at root or any directory level is the 404 pipeline's business. */
 export function is404File(rel) {
   const p = String(rel).replace(/\\/g, '/');
-  return p === '404.html' || p.endsWith('/404.html');
+  return /(^|\/)404\.html?$/i.test(p);
 }
 
 /** Robots noindex detection on (possibly injected) HTML. */
@@ -68,19 +71,25 @@ export function extractDescription(html) {
  * Does the page already import SEO of the given type from SSG/frontmatter?
  * Used by the missing-only injection gate ('description' added in Phase 1: a
  * plain <meta name="description"> counts as covered).
+ *
+ * Every probe is TAG-ANCHORED (Pass 26.12): substring matches fire on the
+ * page's own PROSE too - a docs page that quotes 'application/ld+json' in
+ * a code span silenced its own structured-data injection, exactly the
+ * configuration-reference page. Markup quotes markup: anchors, never
+ * discussion.
  */
 export function hasSeoType(html, type) {
   if (type === 'og') {
-    return html.includes('property="og:title"') || html.includes('property="og:description"');
+    return /<meta[^>]+property=["']og:(title|description)["']/i.test(html);
   }
   if (type === 'twitter') {
-    return html.includes('name="twitter:card"') || html.includes('name="twitter:title"');
+    return /<meta[^>]+name=["']twitter:(card|title)["']/i.test(html);
   }
   if (type === 'jsonld') {
-    return html.includes('application/ld+json');
+    return /<script[^>]+type=["']application\/ld\+json["']/i.test(html);
   }
   if (type === 'canonical') {
-    return html.includes('rel="canonical"');
+    return /<link[^>]+rel=["']canonical["']/i.test(html);
   }
   if (type === 'description') {
     return /<meta[^>]*name=["']description["']/.test(html);

package/engine/search.js

@@ -28,7 +28,7 @@ export function generateSearchIndex(pages, config, outputDir) {
       ? bodyMatch[1].replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 500)
       : '';
 
-    const title = titleMatch ? titleMatch[1].split(' | ')[0] : path.basename(page.file, '.html');
+    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 url = pageUrlFor(config, page.slug);

package/engine/seo.js

@@ -7,8 +7,8 @@
 
 import fs from 'fs';
 import path from 'path';
-import { hasSeoType } from './scan.js';
-import { pageUrlFor } from './urls.js';
+import { hasSeoType, htmlIsNoindex } from './scan.js';
+import { pageUrlFor, slugMatchesGlob, globSpecificity } from './urls.js';
 
 function minifyHtml(html) {
   // Conservative HTML minifier - removes unnecessary whitespace
@@ -37,8 +37,141 @@ function minifyHtml(html) {
     .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;
+    items.push({
+      position: i + 2,
+      name: (i === segs.length - 1 && page.title) ? page.title : seg.replace(/[-_]/g, ' '),
+      url: pageUrlFor(config, 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 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 (!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));
+}
+
+/**
+ * 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).
@@ -106,12 +239,21 @@ 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 }) {
+export function injectPage(page, { config, template, buildHash, snippetDir, injectWarnings, generatedImages }) {
   let html = page.html;
   const siteName = config.site.name;
   const siteUrl = config.site.url;
   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,17 +270,74 @@ 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
     : 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';
@@ -153,6 +352,16 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
       });
   }
 
+  // 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,24 +387,95 @@ 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 = !Array.isArray(jc) && jc && typeof jc === 'object'
+      && Object.keys(jc).length > 0
+      && Object.keys(jc).every((k) => /(^\/|^\*$|^\*\*$|\*)/.test(k));
+    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;
@@ -232,6 +512,16 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
   if (!hasOg) {
     const ogMatch = seo.match(/<meta property="og:[^"]*"[^>]*>/gi);
     if (ogMatch) seoInjection += '\n' + ogMatch.join('\n');
+    // 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) {
+      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) + '">');
@@ -259,11 +549,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
@@ -276,17 +609,19 @@ export function injectPage(page, { config, template, buildHash, snippetDir }) {
     return snippet.replace(/<!--[\s\S]*?-->/g, '');
   }
 
-  // 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>
   const bodyStart = readSnippet('inject-body-start.html');
-  if (bodyStart) html = html.replace(/<body[^>]*>/i, '$&' + bodyStart);
+  if (bodyStart) html = html.replace(/<body[^>]*>/i, (m) => m + bodyStart);
 
   // Custom footer injection before </body>
   const footer = readSnippet('inject-footer.html');
-  if (footer) html = html.replace(/<\/body>/i, footer + '\n</body>');
+  if (footer) html = html.replace(/<\/body>/i, () => footer + '\n</body>');
 
   if (config.minify) html = minifyHtml(html);
 

package/engine/urls.js

@@ -16,7 +16,14 @@ const _norm = s => '/' + String(s).replace(/^\/+/, '');
 
 export function pageUrlFor(config, slug) {
   const base = canonicalBase(config);
-  const basePath = config.basePath ? _norm(config.basePath) : '';
+  // Trailing slashes on a CONSUMER-PROVIDED basePath normalize away
+  // (Pass 26.13): '/myproject/' joined onto a lead-slash slug doubled the
+  // junction ('/myproject//guide/') through every injected URL class
+  // (canonical, sitemap, feed, hreflang). Directory SLUGS keep theirs -
+  // a directory page's trailing slash is canonical - only basePath strips.
+  const basePath = config.basePath
+    ? _norm(config.basePath).replace(/\/+$/, '')
+    : '';
   const slugPath = _norm(slug);
 
   // rel path already carries the deploy directory (e.g. tree nests docs/) -
@@ -26,3 +33,43 @@ export function pageUrlFor(config, slug) {
   }
   return base + basePath + slugPath;
 }
+
+// ---------- slug/glob matching (issues #25 + follow-on) ----------
+// The scoping contracts (jsonLd map keys, og.scoped keys) key on page slugs,
+// NOT raw urls - the engine keys pages by slug and never knows a deploy host.
+//   '/'        exact root
+//   '/faq'     exact page (trailing slashes normalized away)
+//   '/blog/*'  exactly one segment under /blog
+//   '/blog/**' /blog itself AND anything below it ('**' at the end only)
+// Specificity ranks exact > literal-heavy glob > '**'; callers use it to
+// pick the winning pattern when one value is decided (images).
+
+function _forMatch(s) {
+  return _norm(s).replace(/\/+$/, '') || '/';
+}
+
+export function slugMatchesGlob(pattern, slug) {
+  const p = _forMatch(pattern);
+  const s = _forMatch(slug);
+  // '**' (with or without the root slash) means everything
+  if (p === '**' || p === '/**') return true;
+  if (!p.includes('*')) return p === s;
+  // trailing '**' covers the stem directory itself AND everything below
+  if (p.endsWith('/**')) {
+    const stem = _forMatch(p.replace(/\/\*\*$/, ''));
+    return s === stem || s.startsWith(stem + '/');
+  }
+  // single '*' (and mid-pattern '**' degrading the same way): one segment
+  const re = new RegExp('^' + p
+    .split('*').map((seg) => seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('[^/]+') + '$');
+  return re.test(s);
+}
+
+// Higher number wins: exact match outranks every glob; between globs the
+// one carrying more literal path characters is the more specific contract.
+export function globSpecificity(pattern) {
+  const p = _forMatch(pattern);
+  if (!p.includes('*')) return 100000 + p.length;
+  return p.replace(/\*+/g, '').length;
+}

package/engine/xmllike.js

@@ -87,7 +87,7 @@ export function generateFeed(pages, config, outputDir) {
     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, '.html');
+    const title = titleMatch ? titleMatch[1].split(' | ')[0] : path.basename(page.file).replace(/\.html?$/i, '');
     const desc = descMatch ? descMatch[1] : '';
     const pageUrl = pageUrlFor(config, page.slug);
     const pubDate = page.mtime.toUTCString();

package/init/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

package/init/docs/_freestruct/inject-brand.html

@@ -38,11 +38,7 @@
   "@context": "https://schema.org",
   "@type": "WebSite",
   "name": "{{siteNameJson}}",
-  "url": "{{siteUrlJson}}",
-  "potentialAction": {
-    "@type": "SearchAction",
-    "target": "{{siteUrlJson}}/?s={search_term_string}"
-  }
+  "url": "{{siteUrlJson}}"{{searchActionJson}}
 }
 </script>