@duffcloudservices/cms 0.11.0 → 0.13.0

package/dist/seo/index.d.ts

@@ -1,6 +1,8 @@
-export { h as HeadLinkTag, H as HeadMetaTag, i as HeadScriptTag, j as HeadTagOverrides, R as ResolvedHeadTags, b as buildHeadTags, f as escapeJsonLd, g as generateJsonLd, a as generateOpenGraphMeta, c as generateTwitterMeta, d as renderHeadTags, r as resolvePageSeo, s as spliceHeadHtml, e as stripManagedHeadTags } from '../spliceHeadHtml-CsBEucGy.js';
-import { Y as PageRouteEntry } from '../vitepressTransform-DfmABXmK.js';
-export { A as AI_BOTS, y as BlogMeta, x as BreadcrumbCrumb, v as BuildLlmsParams, u as BuildRobotsParams, B as BuildSitemapParams, E as ContentConfig, C as CreateSeoTransformPageDataOptions, D as DcsRobotsOptions, F as FaqSource, a7 as NormalisedFaq, a6 as NormalisedReview, R as ResolvedPageOverrides, a8 as ReviewSchemaParts, z as ReviewSource, w as SchemaObject, S as SeoPageContext, r as SeoPageTypeRule, t as VitePressHeadConfig, V as VitePressPageData, q as absolutizeUrl, j as breadcrumbTrailFromRoute, k as buildBlogPosting, h as buildBreadcrumbList, l as buildFaqPage, g as buildGlobalGraph, $ as buildHasCredential, f as buildLlmsTxt, m as buildReviewSchemaParts, e as buildRobotsTxt, a as buildSitemapXml, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute, a3 as deriveSameAs, o as filterRealFaq, n as filterRealReviews, a2 as findBusinessLicense, a0 as findLocalBusinessSchema, p as findReviewItemsForPage, a1 as graphAbsorbs, a4 as graphIds, a5 as isLocalBusinessType, i as isRouteIndexable, Z as loadPagesManifest, _ as parsePagesManifest, s as slugToTitle } from '../vitepressTransform-DfmABXmK.js';
+export { j as HeadLinkTag, H as HeadMetaTag, k as HeadScriptTag, l as HeadTagOverrides, I as InstallSeoHeadOptions, R as ResolvedHeadTags, z as SEO_HEAD_ROUTE_HAS_NO_META, o as SeoHeadClientLike, p as SeoHeadEntryLike, q as SeoHeadInput, t as SeoHeadPageRoute, u as SeoHeadPagesManifest, v as SeoHeadResolution, w as SeoHeadResolutionReason, A as SeoHeadRouteHasNoMeta, m as SeoHeadRouteLike, S as SeoHeadRouterLike, b as buildHeadTags, h as buildSeoHeadRouteMap, f as escapeJsonLd, x as findDuplicateNormalizedPaths, y as formatDuplicateNormalizedPaths, g as generateJsonLd, a as generateOpenGraphMeta, c as generateTwitterMeta, i as installSeoHead, n as normalizeSeoHeadPath, d as renderHeadTags, r as resolvePageSeo, s as spliceHeadHtml, e as stripManagedHeadTags } from '../installSeoHead-kWQwObez.js';
+import { Z as PageRouteEntry } from '../vitepressTransform-JG_zlaux.js';
+export { A as AI_BOTS, y as BlogMeta, x as BreadcrumbCrumb, v as BuildLlmsParams, u as BuildRobotsParams, B as BuildSitemapParams, E as ContentConfig, C as CreateSeoTransformPageDataOptions, D as DcsRobotsOptions, F as FaqSource, ac as NormalisedFaq, ab as NormalisedReview, R as ResolvedPageOverrides, ad as ReviewSchemaParts, z as ReviewSource, a2 as RouteEmissionRules, a3 as RouteExclusionReason, w as SchemaObject, S as SeoPageContext, r as SeoPageTypeRule, t as VitePressHeadConfig, V as VitePressPageData, q as absolutizeUrl, j as breadcrumbTrailFromRoute, k as buildBlogPosting, h as buildBreadcrumbList, l as buildFaqPage, g as buildGlobalGraph, a4 as buildHasCredential, f as buildLlmsTxt, m as buildReviewSchemaParts, e as buildRobotsTxt, a as buildSitemapXml, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute, a8 as deriveSameAs, o as filterRealFaq, n as filterRealReviews, a7 as findBusinessLicense, a5 as findLocalBusinessSchema, p as findReviewItemsForPage, a6 as graphAbsorbs, a9 as graphIds, aa as isLocalBusinessType, a0 as isRouteEmitted, i as isRouteIndexable, _ as loadPagesManifest, $ as parsePagesManifest, a1 as routeExclusionReason, s as slugToTitle } from '../vitepressTransform-JG_zlaux.js';
+import { a as HeadObservation } from '../headHonesty-OzxvLuwd.js';
+export { B as BakedHead, g as HeadHonestyError, l as HeadHonestyExecution, k as HeadHonestyNotRunError, p as HeadHonestyOptions, o as HeadHonestyViolation, H as HonestyMode, m as HonestyModeInput, b as assertHeadHonesty, h as assertHeadHonestyExecuted, d as decodeHtmlEntities, e as extractBakedHead, i as findHeadHonestyExecutionFaults, f as findHeadHonestyViolations, j as formatHeadHonestyExecutionReport, c as formatHeadHonestyReport, n as normalizeHeadText, r as resolveHonestyMode } from '../headHonesty-OzxvLuwd.js';
 import 'vue';
 
 /**
@@ -44,10 +46,30 @@ import 'vue';
  * head emitter import it without a plugin↔module cycle.
  */
 declare function routeToOutputFile(outDir: string, routePath: string): string;
+/**
+ * The `<head>` values the app left behind after it mounted — i.e. what a
+ * JS-rendering crawler (and every human) actually sees. Captured in the SAME
+ * render pass that produces the body, so the P1 head-honesty rail costs no extra
+ * page loads. See `headHonesty.ts` for what is done with it.
+ */
+interface RenderedHead {
+    /** `document.title` after mount. */
+    title: string | null;
+    /** The EFFECTIVE `meta[name=description]` (the last one in the DOM). */
+    description: string | null;
+    /** How many `meta[name=description]` tags exist — >1 is itself a smell. */
+    descriptionCount: number;
+}
 /** The rendered body of one route plus any fatal render errors observed. */
 interface RenderedRoute {
     /** The `innerHTML` of the app mount container (`#app`) after the app rendered. */
     bodyHtml: string;
+    /**
+     * The post-mount `<head>` observations, when the renderer captures them. The
+     * fake renderers in unit tests may omit it; the production Playwright renderer
+     * always provides it.
+     */
+    head?: RenderedHead;
     /**
      * FATAL render errors (uncaught exceptions / failed mount) that mean the body
      * is untrustworthy. A non-empty list makes `prerenderBodies` throw a
@@ -105,8 +127,25 @@ interface PrerenderBodiesParams {
     noindex?: string[];
     /** `pages.yaml` top-level `excluded:` globs — matching routes are skipped. */
     excludedGlobs?: string[];
+    /**
+     * Write the rendered body back into the per-route file (default `true`).
+     *
+     * Set `false` to run the pass purely as an OBSERVER: routes are still rendered
+     * and their `<head>` still captured for the P1 honesty rail, but `dist/` is not
+     * touched. That is what makes head honesty checkable on a site that has opted
+     * out of body prerender (`seo.yaml prerenderBody: false`) without giving it a
+     * second, duplicate browser pass.
+     */
+    spliceBody?: boolean;
     debug?: boolean;
 }
+/** Why a route never reached the renderer. */
+type PrerenderFilterReason = 'excluded' | 'excluded-glob' | 'noindex' | 'no-head-file';
+/** One route the pass never rendered, and why. */
+interface FilteredRoute {
+    route: string;
+    reason: PrerenderFilterReason;
+}
 /** Outcome of a body-prerender pass. */
 interface PrerenderBodiesResult {
     /** Number of per-route files whose body was filled. */
@@ -115,6 +154,25 @@ interface PrerenderBodiesResult {
     skipped: number;
     /** The route paths that were prerendered, in order (for logging/tests). */
     routes: string[];
+    /**
+     * Per-route baked-vs-rendered `<head>` observations, collected for every route
+     * this pass rendered (including ones whose body was skipped as empty). Consumed
+     * by the P1 rail; empty when the renderer does not report head values.
+     */
+    headObservations: HeadObservation[];
+    /**
+     * Every route that actually reached `renderer.renderRoute` — i.e. the set the
+     * P1 head-honesty rail COULD have observed. This is the denominator that makes
+     * "the rail ran" checkable: `headObservations.length < eligibleRoutes.length`
+     * means some eligible route produced no observation, and an empty
+     * `eligibleRoutes` means the pass checked nothing at all (C-338).
+     */
+    eligibleRoutes: string[];
+    /**
+     * Routes that never reached the renderer, each with the reason. Lets the
+     * caller name exactly what was NOT checked instead of reporting a bare zero.
+     */
+    filteredRoutes: FilteredRoute[];
 }
 /**
  * For each emitted route: render its body and splice it into the per-route
@@ -151,4 +209,705 @@ interface BodyPrerenderEnableInput {
  */
 declare function isBodyPrerenderEnabled(input: BodyPrerenderEnableInput): boolean;
 
-export { type BodyPrerenderEnableInput, BodyPrerenderError, PageRouteEntry, type PrerenderBodiesParams, type PrerenderBodiesResult, type RenderedRoute, type RouteRenderer, isBodyPrerenderEnabled, prerenderBodies, routeToOutputFile, spliceBodyHtml };
+/**
+ * THE HEAD-AUTHORITY CONTRACT (C-356) — a source-level audit.
+ *
+ * WHY THIS EXISTS. One undefined contract produced two OPPOSITE production
+ * failures on the same shared composable, measured a day apart:
+ *
+ *   KEPT           28 `applyHead({…})` callers OVERWROTE the baked head.
+ *                  93 title/description divergences across 49 routes — 100% of
+ *                  routes served one <title> to a non-JS AI crawler and a
+ *                  different one to Google and every human (C-338 matrix,
+ *                  fixed C-341: 51/51, zero divergent).
+ *   boogie-babies  2 callers, 9 of 11 views that write NOTHING. Hard navigation
+ *                  is correct; the first in-app click leaves the previous
+ *                  route's title/description/canonical in the DOM (measured:
+ *                  /pricing -> /parties still claims canonical /pricing).
+ *   just-posh      17 raw `useHead({title, meta, link})` blocks that never touch
+ *                  the composable at all — 27 divergences, the fleet's second
+ *                  largest. A contract about `applyHead` alone would not see it.
+ *
+ * THE CONTRACT, in one line: `.dcs/seo.yaml` is the ONLY writer of the managed
+ * head fields, and it must be re-asserted on EVERY route, on EVERY navigation.
+ * Full text + reasoning: `.docs/plans/dynamic-site-resolution/README.md`
+ * § "The head-authority contract (C-356)".
+ *
+ * WHAT THIS MODULE PROVES AND WHAT IT DOES NOT.
+ *   - It proves there is exactly ONE WRITER in the source. That is authority.
+ *   - It does NOT prove the writer told the truth. That is P1
+ *     (`headHonesty.ts`), which compares the baked head to the rendered head on
+ *     a real build. Neither replaces the other, and an exemption here buys no
+ *     amnesty there.
+ *
+ * Deliberately framework-free and fs-free: it takes source strings, so the same
+ * function runs in the package's own vitest fixtures, in a site's test script,
+ * and in `cli/head-contract-audit.mjs` against a real repo. There is no second
+ * implementation to drift.
+ */
+
+/** Codes that FAIL the contract. */
+type HeadContractViolationCode = 
+/** `applyHead({…})` — a second writer for a managed field. Never exemptible. */
+'override-argument'
+/** `useSEO('x')` where `.dcs/seo.yaml` has no `pages.x.title`. Never exemptible. */
+ | 'undeclared-slug'
+/** `useHead` / `useSeoMeta` / `document.title =` — a writer outside the factory. */
+ | 'foreign-head-writer'
+/** An exemption whose file no longer violates anything (anti-rot). */
+ | 'stale-exemption'
+/** An exemption with no real reason recorded. */
+ | 'empty-exemption-reason'
+/** An exemption that names a host but cannot be checked against it (C-420). */
+ | 'unprobed-exemption'
+/** A live probe contradicts what the exemption asserts about its host (C-420). */
+ | 'exemption-claim-refuted'
+/** The probe of an exemption's host did not complete — never a pass (C-420). */
+ | 'exemption-probe-failed'
+/** The audit scanned no files — a pass that checked nothing is not a pass. */
+ | 'scan-empty'
+/** No `.dcs/seo.yaml` was supplied, so authority cannot be established. */
+ | 'no-seo-config';
+/** Codes that are REPORTED but do not fail. */
+type HeadContractWarningCode = 
+/** A view that never re-asserts the head; SPA navigation to it is stale. */
+'uncovered-route'
+/** `useSEO(`blog-${slug}`)` — legal, but only P1 can judge it. */
+ | 'dynamic-slug';
+interface HeadContractSourceFile {
+    /** Path as the caller wants it reported (and as exemptions key on). */
+    path: string;
+    source: string;
+}
+/** The slice of `.dcs/seo.yaml` this audit needs. */
+interface HeadContractSeoConfig {
+    global?: {
+        titleTemplate?: string;
+        defaultTitle?: string;
+    } & Record<string, unknown>;
+    pages?: Record<string, {
+        title?: string;
+    } & Record<string, unknown>>;
+}
+/**
+ * WHY EXEMPTIONS CARRY LIVE CLAIMS.
+ *
+ * An exemption used to be a sentence. A sentence is an assertion, and an
+ * assertion nobody re-measures rots into a false premise that the audit then
+ * defends: the measured case declared a host as a "noindex cross-domain
+ * handoff", and every part of that was false in production — the host served
+ * `index, follow`, a SELF-referential canonical, a 200 `robots.txt` that allows
+ * every crawler, a sitemap and a full independent site. The audit was green
+ * BECAUSE of the exemption, so the green was the bug.
+ *
+ * The discriminator is the exempted host's real response, not the bundle hash.
+ * So an exemption that NAMES a host must now say what it expects that host to
+ * do, and the caller must supply what the host actually did. A named host with
+ * nothing checkable, or with nothing measured, is a VIOLATION — not a skip.
+ *
+ * This module still never touches the network: it takes observations. The
+ * fetching lives in the runner (`cli/head-contract-audit.mjs`), the judging
+ * lives here, and `parseHostProbeHtml` below is the shared, testable parser
+ * between them so there is no second implementation to drift.
+ */
+interface HeadContractExemptionExpectation {
+    /** HTTP status, measured WITHOUT following redirects (a 301 is not a 200). */
+    status?: number;
+    /** Substring that must appear in `<meta name="robots">` (case-insensitive). */
+    robots?: string;
+    /** Hostname of `<link rel="canonical">` — the self-vs-cross-domain question. */
+    canonicalHost?: string;
+    /** Substring that must appear in `<title>` (case-insensitive). */
+    titleContains?: string;
+}
+interface HeadContractExemptionRecord {
+    /** Why this file cannot route its head through the factory. */
+    reason: string;
+    /**
+     * `host -> claims`. EVERY host the reason names must appear here, and every
+     * entry must carry at least one claim, or the exemption is unprobed.
+     */
+    hosts?: Record<string, HeadContractExemptionExpectation>;
+}
+/** A bare string is still a legal exemption — it just may not name a host. */
+type HeadContractExemptionValue = string | HeadContractExemptionRecord;
+/** What a caller actually observed at a host. Never produced by this module. */
+interface HeadContractHostProbe {
+    host: string;
+    /** `false` = the probe did not complete. A failed probe is never a pass. */
+    ok: boolean;
+    error?: string;
+    status?: number;
+    robots?: string | null;
+    canonical?: string | null;
+    title?: string | null;
+    observedAt?: string;
+}
+type HeadContractExemptionVerdict = 
+/** Every claim agreed with the live response. */
+'live-true'
+/** The live response contradicts at least one claim. */
+ | 'refuted'
+/** Names a host but nothing checkable reached the judge. */
+ | 'unprobed'
+/** A probe was attempted and did not complete. */
+ | 'probe-failed'
+/** Asserts nothing about any host — nothing to probe. */
+ | 'no-host-claim';
+interface HeadContractExemptionCheck {
+    host: string;
+    claim: keyof HeadContractExemptionExpectation;
+    expected: string;
+    actual: string;
+    pass: boolean;
+}
+interface HeadContractExemptionAudit {
+    file: string;
+    reason: string;
+    /** Hosts the PROSE names — the claim the author made whether or not they meant to. */
+    hostsNamedInReason: string[];
+    /** Hosts the author declared machine-checkable claims for. */
+    hostsDeclared: string[];
+    checks: HeadContractExemptionCheck[];
+    verdict: HeadContractExemptionVerdict;
+}
+interface HeadContractInput {
+    files: HeadContractSourceFile[];
+    seo: HeadContractSeoConfig | undefined;
+    /**
+     * `path -> reason | record`. Declares a KNOWN foreign head writer so it stops
+     * being a surprise. It is a declaration of debt, not a licence: P1 still
+     * measures whether that writer agrees with the baked head, a stale entry is
+     * itself a violation, and (C-420) any host the declaration names is measured
+     * against its live response.
+     */
+    exemptions?: Record<string, HeadContractExemptionValue>;
+    /**
+     * `host -> what that host actually did`, supplied by the caller. An exemption
+     * that names a host and finds no observation here FAILS: "not measured" and
+     * "measured fine" must never render the same.
+     */
+    hostProbes?: Record<string, HeadContractHostProbe>;
+}
+interface HeadContractViolation {
+    code: HeadContractViolationCode;
+    file: string;
+    line: number;
+    detail: string;
+}
+interface HeadContractWarning {
+    code: HeadContractWarningCode;
+    file: string;
+    detail: string;
+}
+interface ForeignWriterSite {
+    file: string;
+    line: number;
+    mechanism: 'useHead' | 'useSeoMeta' | 'document.title';
+    exempted: boolean;
+    reason: string | null;
+}
+interface HeadContractReport {
+    /** Execution counts FIRST — a rail that did not run must not read as green. */
+    scanned: number;
+    applyHeadCalls: number;
+    argumentFreeCalls: number;
+    /** Slugs written as string literals — checked against `.dcs/seo.yaml`. */
+    useSeoSlugs: string[];
+    /** Slugs composed at runtime — legal, UNCHECKED here, judged by P1. */
+    dynamicSlugs: string[];
+    foreignWriters: ForeignWriterSite[];
+    /** `useHead({script})` blocks that ADD JSON-LD without restating a managed field. */
+    additiveHeadCalls: number;
+    /**
+     * EVERY declared exemption with its live verdict — dumped whether or not it
+     * found anything, so "0 refuted" is a measurement of a listed set and not an
+     * empty listing wearing a zero.
+     */
+    exemptionAudit: HeadContractExemptionAudit[];
+    coverage: {
+        /** Files scanned (the caller decides what counts as a routed view). */
+        views: number;
+        /** Files that re-assert the head in some way. */
+        asserting: number;
+        /** Files that write nothing — SPA navigation to them is stale. */
+        silent: string[];
+    };
+    violations: HeadContractViolation[];
+    warnings: HeadContractWarning[];
+    ok: boolean;
+}
+type HeadContractMode = 'error' | 'warn' | 'off';
+declare class HeadContractError extends Error {
+    readonly report: HeadContractReport;
+    constructor(message: string, report: HeadContractReport);
+}
+/** Minimum characters an exemption reason must carry to count as a reason. */
+declare const MIN_EXEMPTION_REASON_LENGTH = 12;
+/**
+ * Blank out COMMENTS ONLY — line, block and HTML — tracking string/template
+ * literals just well enough not to mistake a `https://…` inside a string for a
+ * line comment.
+ *
+ * Replacement preserves LENGTH and NEWLINES (every removed character becomes a
+ * space, newlines survive), so every offset and line number computed on the
+ * result is still valid against the original file.
+ *
+ * WHY COMMENTS ONLY. Two hazards pull in opposite directions and the asymmetry
+ * decides it:
+ *   - boogie-babies' PrivacyView.vue carries a docblock reading "applyHead takes
+ *     NO arguments". Scanning raw source reports it. So comments MUST go.
+ *   - Blanking string BODIES as well would let a regex literal containing a
+ *     quote (`/['"]/`) swallow the following lines and HIDE a real violation.
+ *     A gate that silently misses is worse than one that occasionally shouts:
+ *     a false positive is loud and fixed in a minute; a false negative is
+ *     exactly the class this whole contract exists to kill.
+ * So string bodies are left intact, and an `applyHead(` written inside a string
+ * literal is deliberately reported.
+ */
+declare function blankComments(source: string): string;
+/** A bare string exemption is a record with no host claims. */
+declare function normalizeExemption(value: HeadContractExemptionValue): HeadContractExemptionRecord;
+/** Every host the prose names, deduped and normalised. */
+declare function hostsNamedIn(reason: string): string[];
+/**
+ * Pull the three head fields an exemption can make a claim about out of a live
+ * response body. Shared by the runner and by this module's own tests so the
+ * thing that fetches and the thing that judges cannot disagree about what a
+ * `robots` meta is.
+ */
+declare function parseHostProbeHtml(html: string): {
+    robots: string | null;
+    canonical: string | null;
+    title: string | null;
+};
+/**
+ * Judge every exemption against the live behaviour of the host it names.
+ *
+ * Four ways to fail and only one way to pass, because the failure this exists
+ * to catch is a green:
+ *   - the prose names a host that carries no machine-checkable claim
+ *   - a declared host asserts nothing (a claim block with no claims)
+ *   - a declared host has no observation (nothing was measured)
+ *   - an observation disagrees with a claim, or the probe itself did not run
+ * Pure: it fetches nothing and reads no files.
+ */
+declare function auditExemptionHosts(exemptions: Record<string, HeadContractExemptionValue>, hostProbes: Record<string, HeadContractHostProbe>): {
+    audits: HeadContractExemptionAudit[];
+    violations: HeadContractViolation[];
+};
+/**
+ * Audit a set of source files against the head-authority contract.
+ *
+ * Site-agnostic by construction: there is no site name, no path convention and
+ * no per-shape branch anywhere in this function. The three measured shapes
+ * (KEPT / boogie-babies / bryans) go through the identical call.
+ */
+declare function auditHeadContract(input: HeadContractInput): HeadContractReport;
+/**
+ * Dump the exemption set with a per-entry live verdict.
+ *
+ * Printed on EVERY run, including the empty one. "0 refuted" out of an unlisted
+ * set is indistinguishable from a rail that inspected nothing, so the set is
+ * always enumerated and the empty case says so in words.
+ */
+declare function formatExemptionAudit(report: HeadContractReport): string[];
+/** Human-readable report. Execution counts are printed FIRST, always. */
+declare function formatHeadContractReport(report: HeadContractReport): string;
+/**
+ * Assert the contract. `error` throws; `warn` prints; `off` is a no-op — except
+ * that `scan-empty` and `no-seo-config` are NEVER downgraded, because "the rail
+ * did not run" must not be silenceable by the mode that silences findings.
+ */
+declare function assertHeadContract(input: HeadContractInput, mode?: HeadContractMode, log?: (msg: string) => void): HeadContractReport;
+
+/**
+ * P2 — emitted-URL resolution rail.
+ *
+ * ## The defect this exists for
+ *
+ * The SEO factory publishes URLs on the site's behalf: the `logo` and `image`
+ * IRIs in the `@graph`, `og:image` / `twitter:image`, favicon and touch-icon
+ * links, `<loc>`s in `sitemap.xml`, and the page links in `llms.txt`. Nothing
+ * has ever asserted that any of them resolve.
+ *
+ * Measured on live production (2026-07-27):
+ *
+ * ```
+ * GET /logos/iron-oak-mark-light.svg   200  text/html  67,532 bytes
+ * GET /                                200  text/html  67,532 bytes
+ * sha256(both) = e83f660fc39e3ec2…                 ← byte-identical
+ * ```
+ *
+ * `Organization.logo` and `HomeAndConstructionBusiness.logo` on **every route**
+ * of the fleet's flagship point at a file that does not exist. There is no
+ * `site/public/logos/` directory in the repo at all. The miss is invisible
+ * because Azure Static Web Apps' `navigationFallback` answers any unmatched path
+ * with `index.html` and a 200 — so a knowledge-graph entity's logo is a web
+ * page, no 404 is ever logged, and no console error is ever raised. `dcs-seo`
+ * calls this shape "worse than a 404".
+ *
+ * ## The two checks, and why they are split
+ *
+ * **Same-origin assets are checked against `dist/` — no network at all.** If the
+ * factory emitted `https://site.com/logos/x.svg` and `dist/logos/x.svg` does not
+ * exist, then the host has nothing to serve and its SPA fallback WILL answer
+ * HTML. That inference is exact, deterministic, offline, and instant, so it is a
+ * hard build failure. This is the check that catches the Iron Oak defect.
+ *
+ * **Cross-origin assets need the network, so they are designed not to flake.**
+ * A CDN URL can only be verified by asking. The policy is deliberately
+ * asymmetric:
+ *   - a *definitive* answer that is wrong (HTML where an image was promised, or
+ *     a 4xx/5xx) is a HARD FAILURE — that is the defect, and the answer is not
+ *     in doubt;
+ *   - a *non-answer* (DNS failure, timeout, connection reset, exhausted budget)
+ *     is a WARNING and never fails the build.
+ *
+ * That asymmetry is the whole point. A gate that reds when someone's wifi
+ * hiccups gets disabled within a week and then protects nothing — the exact
+ * vacuous-green failure mode this campaign keeps finding. Results are cached
+ * with a TTL and the whole pass runs under a total time budget, so the marginal
+ * cost on a warm CI run is ~zero.
+ */
+/** What kind of resource a URL is expected to return. */
+type UrlExpectation = 
+/** Must NOT be HTML — an image, icon, font, or text/xml artifact. */
+'asset'
+/** An HTML page (canonical, sitemap entry, llms.txt page link). */
+ | 'page'
+/** An identifier or a third-party profile — never fetched. */
+ | 'skip';
+/** One URL the factory emitted, with where it came from. */
+interface EmittedUrl {
+    /** The URL exactly as emitted. */
+    url: string;
+    /** Human-readable provenance, e.g. `JSON-LD Organization.logo`. */
+    source: string;
+    /** The emitted file this came from (`/services`, `sitemap.xml`, …). */
+    from: string;
+    expectation: UrlExpectation;
+}
+/** A URL that resolved to the wrong thing. */
+interface EmittedUrlViolation {
+    url: string;
+    source: string;
+    from: string;
+    reason: string;
+}
+/** A URL we could not get a definitive answer about. */
+interface EmittedUrlWarning {
+    url: string;
+    source: string;
+    from: string;
+    reason: string;
+}
+/**
+ * Collect every URL an emitted HTML document publishes: OG/Twitter images,
+ * asset and page `<link>`s, and every asset/page IRI inside its JSON-LD blocks.
+ */
+declare function collectUrlsFromHtml(html: string, from: string): EmittedUrl[];
+/** Collect `<loc>` entries from an emitted sitemap. */
+declare function collectUrlsFromSitemap(xml: string, from?: string): EmittedUrl[];
+/** Collect the markdown link targets from an emitted `llms.txt`. */
+declare function collectUrlsFromLlmsTxt(txt: string, from?: string): EmittedUrl[];
+/** De-duplicate by URL+expectation, keeping the first provenance seen. */
+declare function dedupeUrls(urls: EmittedUrl[]): EmittedUrl[];
+/** How a URL relates to the site being built. */
+type UrlLocality = 'same-origin' | 'remote' | 'unfetchable';
+/** The parsed form of an emitted URL. */
+interface ClassifiedUrl extends EmittedUrl {
+    locality: UrlLocality;
+    /** Path portion, for same-origin resolution against `dist/`. */
+    pathname: string;
+}
+/**
+ * Decide whether a URL points back at the site we just built (so it can be
+ * proven against `dist/` offline) or somewhere else (so it needs the network).
+ *
+ * Protocol-relative and root-relative URLs are treated as same-origin, matching
+ * how a browser resolves them from the emitted document.
+ */
+declare function classifyUrl(entry: EmittedUrl, siteUrl: string | undefined): ClassifiedUrl;
+/**
+ * Assert that every same-origin ASSET URL the factory emitted has a real file in
+ * `dist/`.
+ *
+ * This is the check that catches the Iron Oak logo IRI, and it does so with no
+ * network, no browser, and no ambiguity: an emitted `https://site/logos/x.svg`
+ * with no `dist/logos/x.svg` behind it means the host's SPA fallback answers the
+ * crawler with `index.html`.
+ */
+declare function checkSameOriginAssets(params: {
+    urls: ClassifiedUrl[];
+    outDir: string;
+    base?: string;
+    allow?: string[];
+}): EmittedUrlViolation[];
+/** What the same-origin half actually did — the numbers behind its claim. */
+interface SameOriginAuditResult {
+    violations: EmittedUrlViolation[];
+    /** Same-origin ASSET URLs actually resolved against `dist/`. */
+    checked: number;
+    /** Same-origin asset URLs skipped because they are on the allow-list. */
+    exempted: number;
+}
+/**
+ * The counting form of {@link checkSameOriginAssets}.
+ *
+ * C-338: the caller used to report `classified.length` ("N published URL(s)
+ * verified") while this function only ever looks at `expectation === 'asset'`.
+ * Page URLs — every sitemap `<loc>`, every canonical, every llms.txt page link —
+ * were counted as verified without being touched. The claim must never be
+ * broader than the check, so the check now returns its own denominator.
+ */
+declare function auditSameOriginAssets(params: {
+    urls: ClassifiedUrl[];
+    outDir: string;
+    base?: string;
+    allow?: string[];
+}): SameOriginAuditResult;
+/** Options for the network half of the rail. */
+interface RemoteCheckOptions {
+    /** Per-request timeout. Default 5000ms. */
+    timeoutMs?: number;
+    /** Total wall-clock budget for the whole pass. Default 20000ms. */
+    budgetMs?: number;
+    /** Parallel requests. Default 6. */
+    concurrency?: number;
+    /** Cache file path. Default `<projectRoot>/node_modules/.cache/dcs-seo/url-probes.json`. */
+    cacheFile?: string;
+    /** Cache TTL. Default 24h. */
+    cacheTtlMs?: number;
+    /** URLs exempted from the check (still logged). */
+    allow?: string[];
+    /** Injectable for tests — defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    debug?: boolean;
+}
+/** Outcome of the remote pass. */
+interface RemoteCheckResult {
+    violations: EmittedUrlViolation[];
+    warnings: EmittedUrlWarning[];
+    /** How many probes were served from cache (0 network cost). */
+    cached: number;
+    /** How many probes hit the network. */
+    probed: number;
+    /**
+     * Remote ASSET URLs this pass was asked to check (`cached + probed +
+     * unanswered`). The honest denominator for the build log — see
+     * {@link auditSameOriginAssets} for why the count must come from the checker.
+     */
+    checked?: number;
+    /** Remote asset URLs skipped because they are on the allow-list. */
+    exempted?: number;
+}
+/**
+ * Probe every REMOTE asset URL and report only what the network told us
+ * definitively.
+ *
+ * The verdict table is the contract:
+ * | observation                                | outcome  | why |
+ * |--------------------------------------------|----------|-----|
+ * | 2xx, non-HTML content-type                 | pass     | the promise held |
+ * | 2xx, `text/html`                           | **FAIL** | the exact silent-degradation shape |
+ * | 4xx / 5xx                                  | **FAIL** | a definitive "this does not exist" |
+ * | DNS/timeout/reset/abort, budget exhausted  | warn     | we learned nothing; never red on that |
+ */
+declare function checkRemoteAssets(urls: ClassifiedUrl[], options: RemoteCheckOptions & {
+    projectRoot: string;
+}): Promise<RemoteCheckResult>;
+/** Render the failure report — every violation names the URL, where it was
+ * emitted, and what actually came back. */
+declare function formatEmittedUrlReport(violations: EmittedUrlViolation[]): string;
+/**
+ * Exactly what the P2 pass touched — the numbers the build log is allowed to
+ * claim.
+ *
+ * ## The defect this exists for
+ *
+ * C-334's success line printed `${classified.length} published URL(s) verified`
+ * while BOTH checkers filter `expectation !== 'asset'`. Sitemap `<loc>`s,
+ * canonicals and llms.txt page links were counted as verified and never probed —
+ * the claim was broader than the check, which is the same vacuous-green shape
+ * the rail was built to close. The log now reports these fields verbatim:
+ * assets proven / assets probed / pages COLLECTED-BUT-NOT-VERIFIED / unknown.
+ */
+interface EmittedUrlAudit {
+    /** Every distinct URL collected from the emitted artifacts. */
+    collected: number;
+    /** Same-origin asset URLs resolved against `dist/` (offline, exact). */
+    sameOriginAssetsChecked: number;
+    /** Remote asset URLs that got a definitive answer. */
+    remoteAssetsChecked: number;
+    /** Remote asset probes that hit the network / came from cache. */
+    remoteProbed: number;
+    remoteCached: number;
+    /**
+     * Remote asset URLs the pass could NOT get a definitive answer about (DNS,
+     * timeout, budget) plus every remote asset when probing is disabled. Never
+     * counted as verified.
+     */
+    unknown: number;
+    /**
+     * Page URLs collected and classified but NOT verified by this rail. This is
+     * the honest name for what used to be counted as "verified".
+     */
+    pagesUnverified: number;
+    /** URLs that are not fetchable by construction (`data:`, `mailto:`, `tel:`). */
+    unfetchable: number;
+    /** URLs skipped by an explicit allow-list entry (still logged). */
+    exempted: number;
+    /** Violations found (the failures). */
+    failed: number;
+}
+/** Total URLs this pass actually verified. */
+declare function auditCheckedTotal(audit: EmittedUrlAudit): number;
+/**
+ * The success/summary line. It states the denominator of every claim and names
+ * what was NOT checked, so no reader can infer more coverage than exists.
+ */
+declare function formatEmittedUrlAudit(audit: EmittedUrlAudit, routeCount: number): string;
+/** Thrown in `error` mode when the P2 rail collected nothing to check. */
+declare class EmittedUrlNotRunError extends Error {
+    readonly audit: EmittedUrlAudit;
+    constructor(audit: EmittedUrlAudit, detail: string);
+}
+/** Thrown in `error` mode so the build goes red. */
+declare class EmittedUrlError extends Error {
+    readonly violations: EmittedUrlViolation[];
+    constructor(violations: EmittedUrlViolation[]);
+}
+
+/**
+ * P12 — `<meta charset>` head-budget rail.
+ *
+ * ## The defect this exists for
+ *
+ * The HTML spec requires a document's character encoding declaration to appear
+ * **within the first 1024 bytes** of the resource; a parser that has not found
+ * one by then stops looking and falls back to its locale default. The 2026-07-26
+ * Iron Oak review measured the shipped fleet HTML and found:
+ *
+ * ```
+ * <!doctype html>
+ * <html lang="en">
+ *   <head>
+ *     <style data-dcs-motion-tokens="">:root { … 858 bytes of tokens … }</style>
+ *     <meta charset="UTF-8" />     ← byte 910 of a 1024-byte window
+ * ```
+ *
+ * The cms motion-token `<style>` was injected `head-prepend`, i.e. ABOVE the
+ * site's own `<meta charset>`, leaving 90 bytes of headroom past the end of the
+ * declaration. The SWA response also sends `Content-Type: text/html` with **no**
+ * `charset` parameter, so there is no header-level backstop. One more head
+ * injection — or a handful of new motion tokens — silently mojibakes every cms
+ * SPA in the fleet, on every route, with nothing failing.
+ *
+ * That is the exact "a capability silently undone downstream, with nothing
+ * noticing" class this module closes.
+ *
+ * ## The fix + the rail
+ *
+ * - **C-414 fixed the source.** `dcsMotionTokensStyleTag()` now injects `head`
+ *   (append) rather than `head-prepend`, so the site's own declaration stays
+ *   first in `<head>` and the block still lands above the bundled site CSS.
+ *   This is the only fix that reaches VitePress sites, which never run the
+ *   `emitStaticHtml` path below.
+ * - {@link hoistCharsetMeta} moves the encoding declaration to the very top of
+ *   `<head>` (inserting `<meta charset="utf-8" />` when the document has none).
+ *   Pure, idempotent, and cascade-safe: only the charset meta moves, so the
+ *   motion-token `<style>` keeps its position relative to the site's own CSS.
+ *   Since C-414 this is a no-op on a stock cms shell — it stays as the backstop
+ *   for hand-rolled shells and any future head injector.
+ * - {@link checkCharsetBudget} measures the real BYTE offset of the declaration
+ *   in the emitted document and reports headroom, so a regression is caught even
+ *   if the hoist is ever bypassed.
+ *
+ * Everything here is framework-free and `fs`-free so both the Vite plugin path
+ * and the unit tests share one implementation.
+ */
+/**
+ * The spec's encoding-sniffing window. Per HTML Standard §13.2.3.2 ("determining
+ * the character encoding") a prescan examines at most the first 1024 bytes.
+ */
+declare const CHARSET_BUDGET_BYTES = 1024;
+/**
+ * Recommended minimum slack between the declaration and the end of the window.
+ * Below this the document is *technically* conformant but one head injection
+ * away from breaking — the Iron Oak measurement (114 bytes) is precisely this
+ * shape, which is why the rail reports headroom and not just pass/fail.
+ */
+declare const CHARSET_HEADROOM_WARN_BYTES = 256;
+/** The canonical declaration this module inserts when a document has none. */
+declare const CANONICAL_CHARSET_META = "<meta charset=\"utf-8\" />";
+/** The result of measuring a document against the encoding-sniffing window. */
+interface CharsetBudgetResult {
+    /** `true` when a declaration exists AND its last byte is inside the window. */
+    ok: boolean;
+    /** Byte offset of the START of the declaration, or `-1` when absent. */
+    offset: number;
+    /** Byte offset of the END of the declaration, or `-1` when absent. */
+    endOffset: number;
+    /** `limitBytes - endOffset`; negative when the declaration is out of budget. */
+    headroom: number;
+    /** The window used for the measurement (default {@link CHARSET_BUDGET_BYTES}). */
+    limitBytes: number;
+    /** The matched declaration text, for reporting. */
+    declaration: string | null;
+}
+/**
+ * Byte offset (UTF-8) of the character encoding declaration, or `-1`.
+ *
+ * Deliberately measured in BYTES, not characters: the spec's window is a byte
+ * window, and a head containing non-ASCII (a `©` in a `<title>`, an em dash in a
+ * meta description) makes the character index an under-estimate — the exact way
+ * a naive check would report "fine" on a document that is not.
+ */
+declare function findCharsetByteOffset(html: string): number;
+/**
+ * Measure a document against the encoding-sniffing window.
+ *
+ * The declaration must END inside the window to count — a `<meta charset>` that
+ * straddles byte 1024 is not seen by the prescan.
+ */
+declare function checkCharsetBudget(html: string, options?: {
+    limitBytes?: number;
+}): CharsetBudgetResult;
+/**
+ * Move the character encoding declaration to the first position inside `<head>`
+ * — or insert the canonical one when the document has none.
+ *
+ * Guarantees, in order of importance:
+ *   1. **Idempotent.** Re-running on already-hoisted HTML is a no-op (the
+ *      declaration is already the first child of `<head>`), so it is safe to
+ *      apply in `transformIndexHtml` AND again over the emitted per-route files.
+ *   2. **Minimal.** Only the charset meta moves. The motion-token `<style>`, the
+ *      site's CSS links, and the app script keep their relative order, so no
+ *      cascade or execution-order behaviour changes.
+ *   3. **Total.** A document with no `<head>` is returned unchanged rather than
+ *      rewritten — the caller logs and no-ops (never corrupt a non-SPA shell).
+ *
+ * @param html - a full HTML document
+ * @param options.insertIfMissing - insert {@link CANONICAL_CHARSET_META} when
+ *   the document declares no encoding at all (default `true`). A cms SPA shell
+ *   always has one; a hand-rolled template might not, and shipping *no*
+ *   declaration is strictly worse than shipping a late one.
+ */
+declare function hoistCharsetMeta(html: string, options?: {
+    insertIfMissing?: boolean;
+}): string;
+/** Thrown when an emitted document's encoding declaration is out of budget. */
+declare class CharsetBudgetError extends Error {
+    readonly file: string;
+    readonly result: CharsetBudgetResult;
+    constructor(file: string, result: CharsetBudgetResult);
+}
+/**
+ * Human-readable one-liner for the low-headroom (still-passing) case, so a
+ * document creeping toward the cliff is visible in the build log before it falls
+ * off it. Returns `null` when there is nothing worth saying.
+ */
+declare function formatCharsetHeadroomWarning(file: string, result: CharsetBudgetResult, warnBelow?: number): string | null;
+
+export { type BodyPrerenderEnableInput, BodyPrerenderError, CANONICAL_CHARSET_META, CHARSET_BUDGET_BYTES, CHARSET_HEADROOM_WARN_BYTES, CharsetBudgetError, type CharsetBudgetResult, type ClassifiedUrl, type EmittedUrl, type EmittedUrlAudit, EmittedUrlError, EmittedUrlNotRunError, type EmittedUrlViolation, type EmittedUrlWarning, type FilteredRoute, type ForeignWriterSite, HeadContractError, type HeadContractExemptionAudit, type HeadContractExemptionCheck, type HeadContractExemptionExpectation, type HeadContractExemptionRecord, type HeadContractExemptionValue, type HeadContractExemptionVerdict, type HeadContractHostProbe, type HeadContractInput, type HeadContractMode, type HeadContractReport, type HeadContractSeoConfig, type HeadContractSourceFile, type HeadContractViolation, type HeadContractViolationCode, type HeadContractWarning, type HeadContractWarningCode, HeadObservation, MIN_EXEMPTION_REASON_LENGTH, PageRouteEntry, type PrerenderBodiesParams, type PrerenderBodiesResult, type PrerenderFilterReason, type RemoteCheckOptions, type RemoteCheckResult, type RenderedHead, type RenderedRoute, type RouteRenderer, type SameOriginAuditResult, type UrlExpectation, type UrlLocality, assertHeadContract, auditCheckedTotal, auditExemptionHosts, auditHeadContract, auditSameOriginAssets, blankComments, checkCharsetBudget, checkRemoteAssets, checkSameOriginAssets, classifyUrl, collectUrlsFromHtml, collectUrlsFromLlmsTxt, collectUrlsFromSitemap, dedupeUrls, findCharsetByteOffset, formatCharsetHeadroomWarning, formatEmittedUrlAudit, formatEmittedUrlReport, formatExemptionAudit, formatHeadContractReport, hoistCharsetMeta, hostsNamedIn, isBodyPrerenderEnabled, normalizeExemption, parseHostProbeHtml, prerenderBodies, routeToOutputFile, spliceBodyHtml };