@duffcloudservices/cms 0.11.0 → 0.13.0

package/dist/plugins/index.js

@@ -1,5 +1,5 @@
-import { buildSitemapXml, isHandAuthoredRobotsAcceptable, buildRobotsTxt, buildLlmsTxt, matchesExcludedGlob, breadcrumbTrailFromRoute, findReviewItemsForPage, findBusinessLicense, buildHeadTags, spliceHeadHtml, routeToOutputFile, loadPagesManifest, isBodyPrerenderEnabled, prerenderBodies } from '../chunk-F3EIWEZD.js';
-export { buildVitePressSeoHead, createSeoTransformPageData, defaultRelativePathToRoute } from '../chunk-F3EIWEZD.js';
+import { buildSitemapXml, isHandAuthoredRobotsAcceptable, buildRobotsTxt, buildLlmsTxt, routeExclusionReason, breadcrumbTrailFromRoute, findReviewItemsForPage, findBusinessLicense, buildHeadTags, spliceHeadHtml, routeToOutputFile, loadPagesManifest, hoistCharsetMeta, checkCharsetBudget, isBodyPrerenderEnabled, resolveHonestyMode, assertHeadHonestyExecuted, findHeadHonestyViolations, assertHeadHonesty, isRouteEmitted, findDuplicateNormalizedPaths, formatDuplicateNormalizedPaths, prerenderBodies, CharsetBudgetError, formatCharsetHeadroomWarning, dedupeUrls, collectEmittedUrlsFromFiles, classifyUrl, auditSameOriginAssets, checkRemoteAssets, auditCheckedTotal, EmittedUrlNotRunError, formatEmittedUrlAudit, formatEmittedUrlReport, EmittedUrlError } from '../chunk-HVSF23P7.js';
+export { buildVitePressSeoHead, createSeoTransformPageData, defaultRelativePathToRoute } from '../chunk-HVSF23P7.js';
 import fs5 from 'fs';
 import path5 from 'path';
 import yaml4 from 'js-yaml';
@@ -65,7 +65,7 @@ function dcsMotionTokensStyleTag() {
     tag: "style",
     attrs: { "data-dcs-motion-tokens": "" },
     children: DCS_MOTION_TOKENS_CSS,
-    injectTo: "head-prepend"
+    injectTo: "head"
   };
 }
 var DEFAULT_AGENT_API_BASE_URL = "https://portal.duffcloudservices.com";
@@ -76,7 +76,7 @@ function buildAgentWidgetLoaderScript(options) {
   const slug = encodeForInlineScript(options.siteSlug);
   const api = encodeForInlineScript(trimTrailingSlash(options.apiBaseUrl || DEFAULT_AGENT_API_BASE_URL));
   const cdn = encodeForInlineScript(options.cdnScriptUrl || DEFAULT_AGENT_WIDGET_SCRIPT_URL);
-  return "(function(){try{if(window.__DCS_AGENT_LOADER__)return;window.__DCS_AGENT_LOADER__=1;try{if(window.self!==window.top)return;}catch(e){return;}if(/[?&]dcs-hide-widget(?:[=&]|$)/.test(location.search))return;var S=" + slug + ",A=" + api + ",C=" + cdn + ';var go=function(){try{fetch(A+"/api/v1/sites/"+encodeURIComponent(S)+"/agent/config",{headers:{Accept:"application/json"}}).then(function(r){return r&&r.ok?r.json():null;}).then(function(c){if(!c||!c.enabled)return;window.__DCS_AGENT_BOOTSTRAP__={siteSlug:S,apiBaseUrl:A,config:c};var s=document.createElement("script");s.src=C;s.async=true;s.setAttribute("data-dcs-agent-slug",S);(document.head||document.documentElement).appendChild(s);}).catch(function(){});}catch(e){}};if("requestIdleCallback"in window){requestIdleCallback(go,{timeout:4000});}else{setTimeout(go,1200);}}catch(e){}})();';
+  return "(function(){try{if(window.__DCS_AGENT_LOADER__)return;window.__DCS_AGENT_LOADER__=1;try{if(window.self!==window.top)return;}catch(e){return;}if(/[?&]dcs-hide-widget(?:[=&]|$)/.test(location.search))return;var S=" + slug + ",A=" + api + ",C=" + cdn + ';var go=function(){try{var p=function(u){return fetch(u,{headers:{Accept:"application/json"}}).then(function(r){if(!r||(r.headers.get("content-type")||"").indexOf("json")===-1)return null;return r.ok?r.json()["catch"](function(){return null;}):0;})["catch"](function(){return null;});};p("/api/v1/agent/config").then(function(c){return c===null?p(A+"/api/v1/sites/"+encodeURIComponent(S)+"/agent/config"):c;}).then(function(c){if(!c||!c.enabled)return;window.__DCS_AGENT_BOOTSTRAP__={siteSlug:S,apiBaseUrl:A,config:c};var s=document.createElement("script");s.src=C;s.async=true;s.setAttribute("data-dcs-agent-slug",S);(document.head||document.documentElement).appendChild(s);}).catch(function(){});}catch(e){}};if("requestIdleCallback"in window){requestIdleCallback(go,{timeout:4000});}else{setTimeout(go,1200);}}catch(e){}})();';
 }
 var SITE_YAML_CANDIDATES = [".dcs/site.yaml", "../.dcs/site.yaml"];
 function readSiteSlug(projectRoot) {
@@ -189,8 +189,12 @@ function dcsContentPlugin(options = {}) {
      *    — the fleet-wide seam that gives every DCS site the shared `--motion-*`
      *    vocabulary. It carries no per-site data, so (unlike the content inject)
      *    it is NOT gated on `isDev`: it runs in both `serve` and `build`.
-     *    `head-prepend` keeps it ABOVE the bundled site CSS, so a site's own
-     *    `:root` (theme `tailwind.css` / `style.css`) can still override a token.
+     *    It is injected `head` (append), NOT `head-prepend` — C-414. Appending
+     *    still lands it ABOVE the bundled site CSS (Vite injects the build's
+     *    `<link rel=stylesheet>` AFTER this `order: 'pre'` hook's tags), so a
+     *    site's own `:root` (theme `tailwind.css` / `style.css`) can still
+     *    override a token — while leaving the site's `<meta charset>` first in
+     *    `<head>` instead of 858 bytes deep. See `motionTokens.ts`.
      *
      * 2. Dev-only: the FRESH on-disk `content.yaml` as an inline
      *    `globalThis.__DCS_CONTENT__ = {…}` classic script. Runs on every dev
@@ -371,8 +375,19 @@ async function createPlaywrightRenderer(options) {
     );
     return null;
   }
-  const staticServer = await startStaticServer(outDir);
-  const context = await browser.newContext({ reducedMotion: "reduce" });
+  let staticServer;
+  let context;
+  try {
+    staticServer = await startStaticServer(outDir);
+    context = await browser.newContext({ reducedMotion: "reduce" });
+  } catch (err) {
+    await staticServer?.close().catch(() => {
+    });
+    await browser.close().catch(() => {
+    });
+    throw err;
+  }
+  const server = staticServer;
   const renderer = {
     async renderRoute(routePath) {
       const page = await context.newPage();
@@ -386,7 +401,7 @@ async function createPlaywrightRenderer(options) {
       await page.route("**/*", (route) => {
         let sameOrigin = false;
         try {
-          sameOrigin = new URL(route.request().url()).origin === staticServer.origin;
+          sameOrigin = new URL(route.request().url()).origin === server.origin;
         } catch {
           sameOrigin = false;
         }
@@ -399,7 +414,7 @@ async function createPlaywrightRenderer(options) {
         }
       });
       try {
-        await page.goto(staticServer.origin + routePath, {
+        await page.goto(server.origin + routePath, {
           waitUntil: "load",
           timeout: navTimeoutMs
         });
@@ -413,7 +428,17 @@ async function createPlaywrightRenderer(options) {
         );
         if (settleMs > 0) await page.waitForTimeout(settleMs);
         const bodyHtml = await page.$eval("#app", (el) => el.innerHTML);
-        return { bodyHtml: bodyHtml ?? "", errors };
+        const head = await page.evaluate(() => {
+          const metas = Array.from(
+            document.querySelectorAll('meta[name="description" i]')
+          );
+          return {
+            title: document.title ?? null,
+            description: metas.length ? metas[metas.length - 1].getAttribute("content") : null,
+            descriptionCount: metas.length
+          };
+        });
+        return { bodyHtml: bodyHtml ?? "", errors, head };
       } catch (err) {
         errors.push(err instanceof Error ? err.message : String(err));
         return { bodyHtml: "", errors };
@@ -422,23 +447,40 @@ async function createPlaywrightRenderer(options) {
       }
     }
   };
+  let teardown = null;
   return {
     renderer,
-    async close() {
-      try {
-        await context.close();
-      } catch {
-      }
-      try {
-        await browser.close();
-      } catch {
-      }
-      await staticServer.close();
+    close() {
+      teardown ??= (async () => {
+        try {
+          await context.close();
+        } catch {
+        }
+        try {
+          await browser.close();
+        } catch {
+        }
+        try {
+          await server.close();
+        } catch {
+        }
+      })();
+      return teardown;
     }
   };
 }
 
 // src/plugins/dcsSeoPlugin.ts
+function readHonestyBlock(value) {
+  if (value === void 0) return { allow: [] };
+  if (typeof value === "boolean" || typeof value === "string") return { mode: value, allow: [] };
+  return {
+    mode: value.mode,
+    allow: Array.isArray(value.allow) ? value.allow : [],
+    checkDescription: value.checkDescription,
+    network: value.network
+  };
+}
 function resolveOutDir(config) {
   const out = config.build?.outDir || "dist";
   return path5.isAbsolute(out) ? out : path5.resolve(config.root || process.cwd(), out);
@@ -510,6 +552,48 @@ function loadExcludedGlobs(projectRoot, pagesPath) {
     return [];
   }
 }
+function assertNoDuplicateRoutePaths(routes) {
+  const dupes = findDuplicateNormalizedPaths(routes);
+  if (dupes.length === 0) return;
+  throw new Error(`[dcs-seo] ${formatDuplicateNormalizedPaths(dupes)}`);
+}
+function collectNoindexMatchKeys(routes) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const route of routes) {
+    if (route.path) keys.add(route.path);
+    if (route.slug) keys.add(route.slug);
+  }
+  return keys;
+}
+function findOrphanNoindexEntries(noindex, routes) {
+  const known = collectNoindexMatchKeys(routes);
+  const seen = /* @__PURE__ */ new Set();
+  const orphans = [];
+  for (const entry of noindex) {
+    if (known.has(entry) || seen.has(entry)) continue;
+    seen.add(entry);
+    orphans.push(entry);
+  }
+  return orphans;
+}
+var NoindexOrphanError = class extends Error {
+  orphans;
+  knownKeys;
+  constructor(orphans, knownKeys) {
+    super(
+      `[dcs-seo] noindex entr${orphans.length === 1 ? "y" : "ies"} matching NO page in the route manifest: ${orphans.map((o) => JSON.stringify(o)).join(", ")}. A noindex entry is a predicate over pages.yaml, not a standalone directive: with no matching page NOTHING is emitted for that route, so the entry is a silent no-op and the URL stays "index, follow" to crawlers \u2014 which is exactly how six homepage-clone URLs on KEPT stayed indexable. Fix it by adding the page to pages.yaml (it then gets a real robots: noindex, nofollow document, sitemap/llms omission, and a runtime re-assert), or by deleting the stale entry. Matchable keys are the manifest's paths and slugs: ${knownKeys.map((k) => JSON.stringify(k)).join(", ") || "(manifest is empty)"}`
+    );
+    this.name = "NoindexOrphanError";
+    this.orphans = orphans;
+    this.knownKeys = knownKeys;
+  }
+};
+function assertNoOrphanNoindexEntries(noindex, routes) {
+  if (noindex.length === 0) return;
+  const orphans = findOrphanNoindexEntries(noindex, routes);
+  if (orphans.length === 0) return;
+  throw new NoindexOrphanError(orphans, [...collectNoindexMatchKeys(routes)].sort());
+}
 function deriveLastmod(seoConfig, projectRoot, pagesPath) {
   const fromSeo = seoConfig?.lastUpdated;
   if (typeof fromSeo === "string" && fromSeo.length > 0) return fromSeo;
@@ -630,7 +714,6 @@ function emitStaticSeoHtml(params) {
     excludedGlobs = [],
     debug = false
   } = params;
-  const excludeSet = new Set(exclude);
   const noindexSet = new Set(noindex);
   const siteUrl = seoConfig?.global?.siteUrl ?? "";
   const routeTitles = { "/": "Home" };
@@ -639,12 +722,13 @@ function emitStaticSeoHtml(params) {
   }
   let written = 0;
   for (const route of routes) {
-    if (excludeSet.has(route.path) || route.slug && excludeSet.has(route.slug)) {
-      if (debug) console.log(`[dcs-seo] skip (excluded): ${route.path}`);
-      continue;
-    }
-    if (matchesExcludedGlob(route.path, excludedGlobs)) {
-      if (debug) console.log(`[dcs-seo] skip (excluded glob): ${route.path}`);
+    const exclusion = routeExclusionReason(route, { exclude, excludedGlobs });
+    if (exclusion) {
+      if (debug) {
+        console.log(
+          `[dcs-seo] skip (${exclusion === "excluded-glob" ? "excluded glob" : "excluded"}): ${route.path}`
+        );
+      }
       continue;
     }
     const forceNoindex = noindexSet.has(route.path) || route.slug && noindexSet.has(route.slug);
@@ -679,9 +763,27 @@ function emitStaticSeoHtml(params) {
   return written;
 }
 async function runBodyPrerender(ctx, opts) {
-  const handle = await createPlaywrightRenderer({ outDir: ctx.outDir, debug: opts.debug });
-  if (!handle) return;
-  console.log("[dcs-seo] body-prerender: rendering routes via headless Chromium\u2026");
+  const forcedAbsent = process.env.DCS_SEO_FORCE_NO_RENDERER === "1";
+  if (forcedAbsent) {
+    console.warn(
+      "[dcs-seo] DCS_SEO_FORCE_NO_RENDERER=1 \u2014 pretending the headless renderer is absent (kill-test hook; in error mode this MUST fail the build)."
+    );
+  }
+  const handle = forcedAbsent ? null : await createPlaywrightRenderer({ outDir: ctx.outDir, debug: opts.debug });
+  if (!handle) {
+    console.warn(
+      "[dcs-seo] no headless renderer available: body prerender AND the P1 baked-vs-rendered <head> assert were both SKIPPED for this build."
+    );
+    return {
+      rendererAvailable: false,
+      headObservations: [],
+      eligibleRoutes: [],
+      filteredRoutes: []
+    };
+  }
+  console.log(
+    opts.spliceBody ? "[dcs-seo] body-prerender: rendering routes via headless Chromium\u2026" : "[dcs-seo] head-honesty: rendering routes via headless Chromium (observe-only)\u2026"
+  );
   try {
     const result = await prerenderBodies({
       outDir: ctx.outDir,
@@ -690,15 +792,151 @@ async function runBodyPrerender(ctx, opts) {
       exclude: opts.exclude,
       noindex: opts.noindex,
       excludedGlobs: ctx.excludedGlobs,
+      spliceBody: opts.spliceBody,
       debug: opts.debug
     });
-    console.log(
-      `[dcs-seo] body-prerender: ${result.prerendered} route(s) now have crawler-visible body content (${result.skipped} skipped)`
-    );
+    if (opts.spliceBody) {
+      console.log(
+        `[dcs-seo] body-prerender: ${result.prerendered} route(s) now have crawler-visible body content (${result.skipped} skipped)`
+      );
+    }
+    return {
+      rendererAvailable: true,
+      headObservations: result.headObservations,
+      eligibleRoutes: result.eligibleRoutes,
+      filteredRoutes: result.filteredRoutes
+    };
   } finally {
     await handle.close();
   }
 }
+async function runEmittedUrlHonesty(params) {
+  const { outDir, projectRoot, routes, siteUrl, base, mode, allow, network, debug, sink } = params;
+  if (mode === "off") {
+    console.warn(
+      "[dcs-seo] emitted-URL honesty is OFF for this build \u2014 nothing is checking that the logo/og:image/sitemap URLs this site publishes actually resolve."
+    );
+    return null;
+  }
+  if (allow.length > 0) {
+    console.warn(
+      `[dcs-seo] emitted-URL honesty: ${allow.length} URL(s) EXEMPTED: ${allow.join(", ")}`
+    );
+  }
+  const files = [];
+  for (const route of routes) {
+    files.push({ path: routeToOutputFile(outDir, route.path), from: route.path, kind: "html" });
+  }
+  files.push({ path: path5.join(outDir, "sitemap.xml"), from: "sitemap.xml", kind: "sitemap" });
+  files.push({ path: path5.join(outDir, "llms.txt"), from: "llms.txt", kind: "llms" });
+  const collected = dedupeUrls(collectEmittedUrlsFromFiles(files));
+  const classified = collected.map((u) => classifyUrl(u, siteUrl));
+  const sameOrigin = auditSameOriginAssets({ urls: classified, outDir, base, allow });
+  const violations = [...sameOrigin.violations];
+  const audit = {
+    collected: classified.length,
+    sameOriginAssetsChecked: sameOrigin.checked,
+    remoteAssetsChecked: 0,
+    remoteProbed: 0,
+    remoteCached: 0,
+    unknown: 0,
+    pagesUnverified: classified.filter((u) => u.expectation === "page").length,
+    unfetchable: classified.filter((u) => u.locality === "unfetchable").length,
+    exempted: sameOrigin.exempted,
+    failed: 0
+  };
+  if (network) {
+    const remote = await checkRemoteAssets(classified, { projectRoot, allow, debug });
+    violations.push(...remote.violations);
+    for (const w of remote.warnings) {
+      console.warn(`[dcs-seo] emitted-URL honesty (UNKNOWN, not a failure): ${w.url} \u2014 ${w.reason}`);
+    }
+    audit.remoteAssetsChecked = remote.checked ?? 0;
+    audit.remoteProbed = remote.probed;
+    audit.remoteCached = remote.cached;
+    audit.unknown = remote.warnings.length;
+    audit.exempted += remote.exempted ?? 0;
+    if (debug) {
+      console.log(
+        `[dcs-seo] emitted-URL honesty: remote probes \u2014 ${remote.probed} network, ${remote.cached} cached`
+      );
+    }
+  } else {
+    audit.unknown = classified.filter(
+      (u) => u.locality === "remote" && u.expectation === "asset"
+    ).length;
+    console.log(
+      `[dcs-seo] emitted-URL honesty: cross-origin probes disabled \u2014 ${audit.unknown} remote asset URL(s) are UNCHECKED this build; same-origin still enforced`
+    );
+  }
+  audit.failed = violations.length;
+  sink?.(audit, violations);
+  const checkedTotal = auditCheckedTotal(audit);
+  if (audit.collected === 0) {
+    const err = new EmittedUrlNotRunError(
+      audit,
+      `0 URLs were collected from ${files.length} emitted artifact(s)`
+    );
+    if (mode === "error") throw err;
+    console.warn(err.message);
+    console.warn("[dcs-seo] emitted-URL honesty is in WARN mode; this build is NOT gated on the above.");
+    return audit;
+  }
+  if (checkedTotal === 0) {
+    console.warn(
+      `[dcs-seo] emitted-URL honesty VERIFIED NOTHING this build: ${audit.collected} URL(s) were collected but none was a checkable asset (${audit.pagesUnverified} page(s), ${audit.unknown} unknown, ${audit.exempted} exempted, ${audit.unfetchable} unfetchable).`
+    );
+  }
+  if (violations.length === 0) {
+    console.log(formatEmittedUrlAudit(audit, routes.length));
+    return audit;
+  }
+  if (mode === "warn") {
+    console.warn(formatEmittedUrlReport(violations));
+    console.warn(formatEmittedUrlAudit(audit, routes.length));
+    console.warn("[dcs-seo] emitted-URL honesty is in WARN mode; this build is NOT gated on the above.");
+    return audit;
+  }
+  throw new EmittedUrlError(violations);
+}
+function runCharsetBudget(params) {
+  const { outDir, routes, mode, debug, sink } = params;
+  if (mode === "off") return;
+  const checked = [];
+  let failed = 0;
+  let worstOffset = 0;
+  const emit = () => sink?.({ checked: checked.length, failed, worstOffset });
+  for (const route of routes) {
+    const file = routeToOutputFile(outDir, route.path);
+    let html;
+    try {
+      html = fs5.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const rel = path5.relative(outDir, file);
+    const result = checkCharsetBudget(html);
+    worstOffset = Math.max(worstOffset, result.offset);
+    if (!result.ok) {
+      failed += 1;
+      if (mode === "warn") {
+        console.warn(new CharsetBudgetError(rel, result).message);
+        continue;
+      }
+      emit();
+      throw new CharsetBudgetError(rel, result);
+    }
+    const warning = formatCharsetHeadroomWarning(rel, result);
+    if (warning) console.warn(warning);
+    checked.push(rel);
+  }
+  emit();
+  if (debug || checked.length > 0) {
+    console.log(
+      `[dcs-seo] charset budget: ${checked.length} emitted document(s) declare their encoding inside the first 1024 bytes`
+    );
+  }
+}
 function dcsSeoPlugin(options = {}) {
   const {
     seoPath = ".dcs/seo.yaml",
@@ -713,6 +951,9 @@ function dcsSeoPlugin(options = {}) {
     // sites already using emitStaticHtml gain sitemap/robots/llms with no edit.
     emitSiteFiles: emitSiteFilesOpt = emitStaticHtml,
     siteUrl,
+    headHonesty: headHonestyOpt,
+    urlHonesty: urlHonestyOpt,
+    charsetBudget: charsetBudgetOpt,
     robots = {},
     // Self-detect preview builds from DCS_PREVIEW (mirrors dcsEditorPlugin) so a
     // release/** SWA preview build never body-prerenders; an explicit option wins.
@@ -731,16 +972,43 @@ function dcsSeoPlugin(options = {}) {
       if (env.command === "serve") {
         return {
           define: {
-            __DCS_SEO__: "globalThis.__DCS_SEO__"
+            __DCS_SEO__: "globalThis.__DCS_SEO__",
+            __DCS_PAGES__: "globalThis.__DCS_PAGES__"
           }
         };
       }
       const projectRoot = config.root || process.cwd();
+      const pagesDefine = (() => {
+        const routes = loadPagesManifest(projectRoot, pagesPath, debug);
+        if (!routes) {
+          if (noindex.length > 0) {
+            console.warn(
+              `[dcs-seo] noindex has ${noindex.length} entr${noindex.length === 1 ? "y" : "ies"} but ${pagesPath} is missing or empty \u2014 the list matches nothing and is inert.`
+            );
+          }
+          return "undefined";
+        }
+        assertNoOrphanNoindexEntries(noindex, routes);
+        const excludedGlobs = loadExcludedGlobs(projectRoot, pagesPath);
+        const emitted = routes.filter(
+          (r) => isRouteEmitted(r, { exclude, excludedGlobs })
+        );
+        assertNoDuplicateRoutePaths(emitted);
+        return JSON.stringify({
+          routes: emitted.map((r) => ({
+            slug: r.slug,
+            path: r.path,
+            ...r.title ? { title: r.title } : {}
+          })),
+          noindex
+        });
+      })();
       const loaded = loadSeoConfig(projectRoot, seoPath, debug);
       if (!loaded) {
         return {
           define: {
-            __DCS_SEO__: "undefined"
+            __DCS_SEO__: "undefined",
+            __DCS_PAGES__: pagesDefine
           }
         };
       }
@@ -754,7 +1022,8 @@ function dcsSeoPlugin(options = {}) {
       }
       return {
         define: {
-          __DCS_SEO__: JSON.stringify(loaded.config)
+          __DCS_SEO__: JSON.stringify(loaded.config),
+          __DCS_PAGES__: pagesDefine
         }
       };
     },
@@ -778,6 +1047,8 @@ function dcsSeoPlugin(options = {}) {
         return;
       }
       let bodyPrerenderCtx = null;
+      let charsetShell = null;
+      let honestyCtx = null;
       try {
         const projectRoot = resolvedConfig?.root || process.cwd();
         const outDir = resolveOutDir(resolvedConfig);
@@ -805,7 +1076,29 @@ function dcsSeoPlugin(options = {}) {
             `[dcs-seo] emitStaticHtml: ${seoPath} missing or unparseable; emitting with defaults only`
           );
         }
-        const shellHtml = fs5.readFileSync(shellPath, "utf8");
+        const rawShellHtml = fs5.readFileSync(shellPath, "utf8");
+        const shellHtml = hoistCharsetMeta(rawShellHtml);
+        {
+          const b = checkCharsetBudget(rawShellHtml);
+          const a = checkCharsetBudget(shellHtml);
+          charsetShell = {
+            hoisted: shellHtml !== rawShellHtml,
+            beforeOffset: b.offset,
+            beforeHeadroom: b.headroom,
+            beforeOk: b.ok,
+            afterOffset: a.offset,
+            afterHeadroom: a.headroom,
+            afterOk: a.ok
+          };
+        }
+        if (shellHtml !== rawShellHtml) {
+          fs5.writeFileSync(shellPath, shellHtml, "utf8");
+          const before = checkCharsetBudget(rawShellHtml);
+          const after = checkCharsetBudget(shellHtml);
+          console.log(
+            `[dcs-seo] charset budget: hoisted <meta charset> from byte ${before.offset} to byte ${after.offset} (${after.headroom} bytes of the 1024-byte encoding-sniffing window now free)`
+          );
+        }
         const excludedGlobs = loadExcludedGlobs(projectRoot, pagesPath);
         const contentConfig = loadContentConfig(projectRoot, contentPath, debug);
         const written = emitStaticSeoHtml({
@@ -845,12 +1138,13 @@ function dcsSeoPlugin(options = {}) {
         }
         const buildBase = resolvedConfig?.base ?? "/";
         const baseIsRoot = buildBase === "/" || buildBase === "./" || buildBase === "";
-        if (isBodyPrerenderEnabled({
+        const bodyPrerenderOn = isBodyPrerenderEnabled({
           emitStaticHtml,
           prerenderBodyOption: prerenderBody,
           preview,
           seoPrerenderBody: loaded?.config?.prerenderBody
-        })) {
+        });
+        if (bodyPrerenderOn) {
           if (baseIsRoot) {
             bodyPrerenderCtx = { outDir, routes, excludedGlobs };
           } else {
@@ -859,11 +1153,161 @@ function dcsSeoPlugin(options = {}) {
             );
           }
         }
+        const headOptBlock = readHonestyBlock(headHonestyOpt);
+        const urlOptBlock = readHonestyBlock(urlHonestyOpt);
+        const charsetOptBlock = readHonestyBlock(charsetBudgetOpt);
+        const seoHeadBlock = readHonestyBlock(loaded?.config?.headHonesty ?? void 0);
+        const seoUrlBlock = readHonestyBlock(loaded?.config?.urlHonesty ?? void 0);
+        const seoCharsetBlock = readHonestyBlock(loaded?.config?.charsetBudget ?? void 0);
+        const headMode = resolveHonestyMode({
+          env: process.env.DCS_SEO_HEAD_HONESTY,
+          seoYaml: seoHeadBlock.mode,
+          option: headOptBlock.mode,
+          fallback: "error"
+        });
+        const urlMode = resolveHonestyMode({
+          env: process.env.DCS_SEO_URL_HONESTY,
+          seoYaml: seoUrlBlock.mode,
+          option: urlOptBlock.mode,
+          fallback: "error"
+        });
+        const charsetMode = resolveHonestyMode({
+          env: process.env.DCS_SEO_CHARSET_BUDGET,
+          seoYaml: seoCharsetBlock.mode,
+          option: charsetOptBlock.mode,
+          fallback: "error"
+        });
+        const renderForHonestyOnly = !bodyPrerenderOn && headMode !== "off" && baseIsRoot;
+        if (renderForHonestyOnly) {
+          bodyPrerenderCtx = { outDir, routes, excludedGlobs };
+        }
+        if (headMode !== "off" && !baseIsRoot) {
+          console.warn(
+            `[dcs-seo] head honesty SKIPPED: non-root base "${buildBase}" (the prerender server cannot serve this build, so the rendered <head> cannot be observed)`
+          );
+        }
+        honestyCtx = {
+          outDir,
+          projectRoot,
+          routes,
+          siteUrl: siteUrl || loaded?.config?.global?.siteUrl,
+          base: buildBase,
+          headMode: baseIsRoot ? headMode : "off",
+          headAllow: [...headOptBlock.allow, ...seoHeadBlock.allow],
+          headCheckDescription: seoHeadBlock.checkDescription ?? headOptBlock.checkDescription ?? true,
+          urlMode,
+          urlAllow: [...urlOptBlock.allow, ...seoUrlBlock.allow],
+          urlNetwork: process.env.DCS_SEO_URL_HONESTY_NETWORK?.toLowerCase() === "off" ? false : seoUrlBlock.network ?? urlOptBlock.network ?? true,
+          charsetMode,
+          renderForHonestyOnly
+        };
       } catch (error) {
         console.warn("[dcs-seo] emitStaticHtml failed; build output left unchanged:", error);
       }
+      let headObservations = [];
+      let rendererAvailable = false;
+      let eligibleRoutes = [];
+      let filteredRoutes = [];
       if (bodyPrerenderCtx) {
-        await runBodyPrerender(bodyPrerenderCtx, { exclude, noindex, debug });
+        const outcome = await runBodyPrerender(bodyPrerenderCtx, {
+          exclude,
+          noindex,
+          debug,
+          spliceBody: !(honestyCtx?.renderForHonestyOnly ?? false)
+        });
+        headObservations = outcome.headObservations;
+        rendererAvailable = outcome.rendererAvailable;
+        eligibleRoutes = outcome.eligibleRoutes;
+        filteredRoutes = outcome.filteredRoutes;
+      }
+      if (honestyCtx) {
+        const ctx = honestyCtx;
+        const reportPath = process.env.DCS_SEO_HONESTY_REPORT;
+        const report = {
+          schema: 1,
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          projectRoot: ctx.projectRoot,
+          outDir: ctx.outDir,
+          siteUrl: ctx.siteUrl ?? null,
+          base: ctx.base,
+          routes: ctx.routes.length,
+          p1: {
+            mode: ctx.headMode,
+            rendererAvailable,
+            eligible: eligibleRoutes.length,
+            observed: headObservations.length,
+            unobserved: eligibleRoutes.filter(
+              (r) => !headObservations.some((o) => o.route === r)
+            ),
+            filtered: filteredRoutes,
+            exempted: ctx.headAllow.length,
+            divergent: null,
+            executed: false
+          },
+          p12: { mode: ctx.charsetMode, shell: charsetShell, checked: 0, failed: 0, worstOffset: 0 },
+          p2: { mode: ctx.urlMode, network: ctx.urlNetwork, audit: null }
+        };
+        const p1 = report.p1;
+        try {
+          const shouldCompare = assertHeadHonestyExecuted(
+            {
+              rendererAvailable,
+              eligibleRoutes,
+              observedRoutes: headObservations.map((o) => o.route),
+              filteredRoutes,
+              totalRoutes: ctx.routes.length
+            },
+            { mode: ctx.headMode }
+          );
+          p1.executed = shouldCompare;
+          if (shouldCompare || ctx.headMode === "off") {
+            const found = findHeadHonestyViolations(headObservations, {
+              allow: ctx.headAllow,
+              checkDescription: ctx.headCheckDescription
+            });
+            p1.divergent = found.length;
+            p1.violations = found;
+            assertHeadHonesty(headObservations, {
+              mode: ctx.headMode,
+              allow: ctx.headAllow,
+              checkDescription: ctx.headCheckDescription,
+              debug
+            });
+          }
+          runCharsetBudget({
+            outDir: ctx.outDir,
+            routes: ctx.routes,
+            mode: ctx.charsetMode,
+            debug,
+            sink: (s) => Object.assign(report.p12, s)
+          });
+          await runEmittedUrlHonesty({
+            outDir: ctx.outDir,
+            projectRoot: ctx.projectRoot,
+            routes: ctx.routes,
+            siteUrl: ctx.siteUrl,
+            base: ctx.base,
+            mode: ctx.urlMode,
+            allow: ctx.urlAllow,
+            network: ctx.urlNetwork,
+            debug,
+            sink: (a, v) => {
+              const p2 = report.p2;
+              p2.audit = a;
+              p2.violations = v;
+            }
+          });
+        } finally {
+          if (reportPath) {
+            try {
+              fs5.mkdirSync(path5.dirname(path5.resolve(reportPath)), { recursive: true });
+              fs5.writeFileSync(path5.resolve(reportPath), JSON.stringify(report, null, 2), "utf8");
+              console.log(`[dcs-seo] honesty report written: ${path5.resolve(reportPath)}`);
+            } catch (err) {
+              console.warn("[dcs-seo] could not write honesty report:", err);
+            }
+          }
+        }
       }
     },
     /**
@@ -873,24 +1317,61 @@ function dcsSeoPlugin(options = {}) {
      * on-disk SEO edits on the portal's `?_hc` hard reload with no restart.
      * Gated on `isDev` so it never runs in `vite`/`vitepress build` (the build
      * path keeps the baked `define` literal + the `writeBundle` emitter).
+     *
+     * `__DCS_PAGES__` (the `installSeoHead` route manifest) rides the same
+     * refresh. It is injected INDEPENDENTLY of seo.yaml: a site can have a
+     * pages.yaml and no seo.yaml, and returning early on a missing seo.yaml
+     * would leave the router hook manifest-less (and therefore inert) in dev
+     * only — a dev/prod behaviour split is exactly the kind of divergence this
+     * plan exists to stop.
      */
     transformIndexHtml: {
       order: "pre",
       handler(html) {
         if (!isDev) return html;
         const projectRoot = resolvedConfig?.root || process.cwd();
+        const tags = [];
         const config = readDcsYamlFresh(projectRoot, seoPath, "dcs-seo", debug);
-        if (config === void 0) return html;
-        if (debug) {
-          console.log("[dcs-seo] serve: injecting fresh __DCS_SEO__ into <head>");
-        }
-        const tags = [
-          {
+        if (config !== void 0) {
+          if (debug) {
+            console.log("[dcs-seo] serve: injecting fresh __DCS_SEO__ into <head>");
+          }
+          tags.push({
             tag: "script",
             children: buildGlobalAssignScript("__DCS_SEO__", config),
             injectTo: "head-prepend"
+          });
+        }
+        const routes = loadPagesManifest(projectRoot, pagesPath, debug);
+        if (routes) {
+          const excludedGlobs = loadExcludedGlobs(projectRoot, pagesPath);
+          const emitted = routes.filter((r) => isRouteEmitted(r, { exclude, excludedGlobs }));
+          const dupes = findDuplicateNormalizedPaths(emitted);
+          if (dupes.length > 0) {
+            console.error(
+              `[dcs-seo] serve: ${formatDuplicateNormalizedPaths(dupes)}
+[dcs-seo] serve: this is reported here and FAILS the production build.`
+            );
+          }
+          if (debug) {
+            console.log(
+              `[dcs-seo] serve: injecting fresh __DCS_PAGES__ (${emitted.length} of ${routes.length} route(s), excluded ones omitted) into <head>`
+            );
           }
-        ];
+          tags.push({
+            tag: "script",
+            children: buildGlobalAssignScript("__DCS_PAGES__", {
+              routes: emitted.map((r) => ({
+                slug: r.slug,
+                path: r.path,
+                ...r.title ? { title: r.title } : {}
+              })),
+              noindex
+            }),
+            injectTo: "head-prepend"
+          });
+        }
+        if (tags.length === 0) return html;
         return { html, tags };
       }
     },
@@ -1003,7 +1484,7 @@ if (document.readyState === 'loading') {
      *
      * These are virtual modules resolved via absolute paths (e.g.
      * `/__dcs-editor-bridge.js`). When base !== '/', the app is served at a
-     * sub-path (e.g. /handyman-bryan/) and the absolute virtual paths are NOT
+     * sub-path (e.g. /iron-oak-contractors/) and the absolute virtual paths are NOT
      * routed to the Vite dev server by the reverse proxy — they hit the main
      * DCS server instead and get redirected to portal.duffcloudservices.com
      * (no CORS headers), causing browser console errors.
@@ -1052,13 +1533,22 @@ function dcsPreviewPlugin(ribbonComponent, options = {}) {
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+function dimensionAttrs(entry) {
+  const w = entry.width;
+  const h2 = entry.height;
+  if (typeof w === "number" && w > 0 && typeof h2 === "number" && h2 > 0) {
+    return ` width="${w}" height="${h2}"`;
+  }
+  return "";
+}
 function buildPictureElement(entry, alt, extraAttrs, sizes) {
   const variants = entry.variants ?? [];
+  const dims = dimensionAttrs(entry);
   const displayVariants = variants.filter(
     (v) => v.suffix === "-sm" || v.suffix === "-md" || v.suffix === "-lg"
   );
   if (displayVariants.length === 0) {
-    return `<img src="${escapeHtml(entry.cdnUrl)}" alt="${escapeHtml(alt)}"${extraAttrs} loading="lazy" decoding="async" />`;
+    return `<img src="${escapeHtml(entry.cdnUrl)}" alt="${escapeHtml(alt)}"${extraAttrs}${dims} loading="lazy" decoding="async" />`;
   }
   const srcset = displayVariants.map((v) => `${v.cdnUrl} ${v.width}w`).join(", ");
   const mdVariant = variants.find((v) => v.suffix === "-md");
@@ -1066,7 +1556,7 @@ function buildPictureElement(entry, alt, extraAttrs, sizes) {
   return [
     "<picture>",
     `  <source srcset="${srcset}" type="image/webp" sizes="${escapeHtml(sizes)}" />`,
-    `  <img src="${escapeHtml(fallbackSrc)}" alt="${escapeHtml(alt)}"${extraAttrs} loading="lazy" decoding="async" />`,
+    `  <img src="${escapeHtml(fallbackSrc)}" alt="${escapeHtml(alt)}"${extraAttrs}${dims} loading="lazy" decoding="async" />`,
     "</picture>"
   ].join("\n");
 }
@@ -1140,12 +1630,15 @@ function dcsCdnImagePlugin(options = {}) {
       if (!entry) return _match;
       const altMatch = (beforeSrc + afterSrc).match(/alt=["']([^"']*)["']/);
       const alt = altMatch ? altMatch[1] : "";
-      const otherAttrs = (beforeSrc + afterSrc).replace(/\balt=["'][^"']*["']/gi, "").replace(/\bloading=["'][^"']*["']/gi, "").replace(/\bdecoding=["'][^"']*["']/gi, "").trim();
+      let otherAttrs = (beforeSrc + afterSrc).replace(/\balt=["'][^"']*["']/gi, "").replace(/\bloading=["'][^"']*["']/gi, "").replace(/\bdecoding=["'][^"']*["']/gi, "").trim();
+      if (dimensionAttrs(entry)) {
+        otherAttrs = otherAttrs.replace(/\b(?:width|height)=(?:"[^"]*"|'[^']*'|[^\s"'>/]+)/gi, "").replace(/\s{2,}/g, " ").trim();
+      }
       const extraAttrs = otherAttrs ? " " + otherAttrs : "";
       const sizesMatch = (beforeSrc + afterSrc).match(/data-sizes=["']([^"']*)["']/);
       const sizes = sizesMatch ? sizesMatch[1] : defaultSizes;
       if (!entry.variants || entry.variants.length === 0) {
-        return `<img src="${escapeHtml(entry.cdnUrl)}" alt="${escapeHtml(alt)}"${extraAttrs} loading="lazy" decoding="async" />`;
+        return `<img src="${escapeHtml(entry.cdnUrl)}" alt="${escapeHtml(alt)}"${extraAttrs}${dimensionAttrs(entry)} loading="lazy" decoding="async" />`;
       }
       return buildPictureElement(entry, alt, extraAttrs, sizes);
     });
@@ -1338,7 +1831,88 @@ function responsiveImagePlugin(md) {
     ].join("\n");
   };
 }
+var BASE_CDN_ASSET = /^https?:\/\/files\.[^/]+\/(?:content\/)?[^/]+\/assets\/(?:[^/]+\/)*[a-f0-9-]+\.\w+(?:[?#].*)?$/i;
+function isFullSizeCdnUrl(url) {
+  return BASE_CDN_ASSET.test(url.trim());
+}
+function readAttr(tag, name) {
+  const m = tag.match(new RegExp(`\\b${name}=("([^"]*)"|'([^']*)')`, "i"));
+  if (!m) return null;
+  return m[2] ?? m[3] ?? "";
+}
+function findFullSizeCdnImages(html) {
+  const violations = [];
+  for (const m of html.matchAll(/<img\b[^>]*>/gi)) {
+    const src = readAttr(m[0], "src");
+    if (src && isFullSizeCdnUrl(src)) {
+      violations.push({ url: src.trim(), tag: "img" });
+    }
+  }
+  for (const m of html.matchAll(/<source\b[^>]*>/gi)) {
+    const srcset = readAttr(m[0], "srcset");
+    if (!srcset) continue;
+    for (const candidate of srcset.split(",")) {
+      const url = candidate.trim().split(/\s+/)[0];
+      if (url && isFullSizeCdnUrl(url)) {
+        violations.push({ url, tag: "source" });
+      }
+    }
+  }
+  return violations;
+}
+function dcsResponsiveImageLint(options = {}) {
+  const { failOnViolation = false, extensions = [".html"], debug = false } = options;
+  return async (siteConfig) => {
+    const report = { filesScanned: 0, violations: [] };
+    const outDir = siteConfig.outDir;
+    if (!outDir || !fs5.existsSync(outDir)) return report;
+    const walk = (dir) => {
+      for (const entry of fs5.readdirSync(dir, { withFileTypes: true })) {
+        const full = path5.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+        } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+          report.filesScanned++;
+          const html = fs5.readFileSync(full, "utf8");
+          if (!html.includes("/assets/")) continue;
+          const rel = path5.relative(outDir, full);
+          for (const v of findFullSizeCdnImages(html)) {
+            report.violations.push({ ...v, file: rel });
+            if (debug) {
+              console.log(`[dcs-responsive-lint] ${rel}: <${v.tag}> full-size ${v.url}`);
+            }
+          }
+        }
+      }
+    };
+    walk(outDir);
+    if (report.violations.length > 0) {
+      const lines = report.violations.map((v) => `  ${v.file}: <${v.tag}> ${v.url}`).join("\n");
+      const summary = `[dcs-responsive-lint] ${report.violations.length} full-size CDN image(s) shipped without a -sm/-md/-lg responsive variant across ${report.filesScanned} file(s):
+${lines}`;
+      if (failOnViolation) {
+        throw new Error(summary);
+      }
+      console.warn(summary);
+    } else if (debug) {
+      console.log(
+        `[dcs-responsive-lint] clean \u2014 scanned ${report.filesScanned} file(s), no full-size images.`
+      );
+    }
+    return report;
+  };
+}
+function chainBuildEnd(...hooks) {
+  const active = hooks.filter(
+    (h2) => typeof h2 === "function"
+  );
+  return async (siteConfig) => {
+    for (const hook of active) {
+      await hook(siteConfig);
+    }
+  };
+}
 
-export { DCS_MOTION_TOKENS_CSS, DEFAULT_AGENT_API_BASE_URL, DEFAULT_AGENT_WIDGET_SCRIPT_URL, buildAgentWidgetLoaderScript, dcsAgentWidgetLoaderTag, dcsCdnBuildEnd, dcsCdnImagePlugin, dcsContentPlugin, dcsEditorPlugin, dcsMotionTokensStyleTag, dcsPreviewPlugin, dcsSeoPlugin, emitSiteFiles, emitStaticSeoHtml, readSiteSlug, responsiveImagePlugin };
+export { DCS_MOTION_TOKENS_CSS, DEFAULT_AGENT_API_BASE_URL, DEFAULT_AGENT_WIDGET_SCRIPT_URL, NoindexOrphanError, buildAgentWidgetLoaderScript, chainBuildEnd, collectNoindexMatchKeys, dcsAgentWidgetLoaderTag, dcsCdnBuildEnd, dcsCdnImagePlugin, dcsContentPlugin, dcsEditorPlugin, dcsMotionTokensStyleTag, dcsPreviewPlugin, dcsResponsiveImageLint, dcsSeoPlugin, emitSiteFiles, emitStaticSeoHtml, findFullSizeCdnImages, findOrphanNoindexEntries, isFullSizeCdnUrl, readSiteSlug, responsiveImagePlugin };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map