import { H as HeadMetaTag, l as HeadLinkTag } from '../installSeoHead-CuVdVCis.js';
export { m as HeadScriptTag, o as HeadTagOverrides, I as InstallSeoHeadOptions, R as ResolvedHeadTags, B as SEO_HEAD_ROUTE_HAS_NO_META, q as SeoHeadClientLike, t as SeoHeadEntryLike, u as SeoHeadInput, v as SeoHeadPageRoute, w as SeoHeadPagesManifest, x as SeoHeadResolution, y as SeoHeadResolutionReason, C as SeoHeadRouteHasNoMeta, p as SeoHeadRouteLike, S as SeoHeadRouterLike, b as buildHeadTags, k as buildSeoHeadRouteMap, f as escapeJsonLd, z as findDuplicateNormalizedPaths, A as formatDuplicateNormalizedPaths, g as generateJsonLd, a as generateOpenGraphMeta, c as generateTwitterMeta, j as installSeoHead, h as isManagedLinkRel, i as isManagedMetaTag, n as normalizeSeoHeadPath, d as renderHeadTags, r as resolvePageSeo, s as spliceHeadHtml, e as stripManagedHeadTags } from '../installSeoHead-CuVdVCis.js';
import { Z as PageRouteEntry } from '../vitepressTransform-CZ_IB3dq.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, ag as NormalisedFaq, af as NormalisedReview, ai as PostalAddressGap, ab as REQUIRED_POSTAL_ADDRESS_FIELDS, R as ResolvedPageOverrides, ah 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, ac as deriveSameAs, o as filterRealFaq, n as filterRealReviews, a8 as findBusinessLicense, a6 as findGlobalSchemasOfType, a5 as findLocalBusinessSchema, a9 as findPostalAddressGaps, p as findReviewItemsForPage, aa as formatPostalAddressGapReport, a7 as graphAbsorbs, ad as graphIds, ae as isLocalBusinessType, a0 as isRouteEmitted, i as isRouteIndexable, _ as loadPagesManifest, $ as parsePagesManifest, a1 as routeExclusionReason, s as slugToTitle } from '../vitepressTransform-CZ_IB3dq.js';
import { a as HeadObservation, H as HonestyMode } from '../headHonesty-OzxvLuwd.js';
export { B as BakedHead, g as HeadHonestyError, l as HeadHonestyExecution, k as HeadHonestyNotRunError, p as HeadHonestyOptions, o as HeadHonestyViolation, 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';

/**
 * THE SWEEP-ONCE HALF OF `installSeoHead` — the fix for DEFECT F-A
 * (Q-453 = A, decided 2026-08-11; C-603).
 *
 * THE DEFECT, IN ONE SENTENCE. Unhead removes only the side effects it OWNS.
 * The baked managed tags were written into the served HTML by the build-time
 * emitter before any JavaScript ran, so Unhead never owned them and never
 * removes them — which means a managed tag present in the BAKED head and ABSENT
 * from the runtime entry is left stranded in the DOM for the rest of the
 * session, while every tag the new route DOES declare moves correctly.
 * Measured live across the fleet: a stale `meta keywords` on five sites and a
 * stale `article:published_time` on iron-oak
 * (`.docs/analysis/installseohead-defect-fa-explainer-2026-08-11.md` §2).
 *
 * THE FIX. On the FIRST matched in-app navigation, remove the baked managed
 * tags that the incoming head input does not re-declare. From that moment the
 * runtime is the sole owner of the managed head and Unhead's own reconciliation
 * (proven correct by the C-362 fixture, on both shipped versions) handles every
 * subsequent navigation. One sweep is therefore not a budget — it is
 * SUFFICIENT, and §"WHY ONCE IS ENOUGH" below is the argument.
 *
 * ── THE FOUR REFUSALS ──────────────────────────────────────────────────────
 *
 *   S1  NEVER SWEEP JSON-LD. This is the failure mode Q-453 named explicitly
 *       when it chose option A. `<script type="application/ld+json">` IS in the
 *       emitter's managed set, but the runtime DELIBERATELY never re-asserts it
 *       (the baked graph is built from inputs that do not exist at runtime:
 *       content.yaml reviews, business licence, FAQ pairs, breadcrumb trails).
 *       So a sweep that treated "managed" as "sweepable" would DELETE the graph
 *       outright and leave the page with none — strictly worse than the stale
 *       graph it replaced. Scripts are never snapshotted, so they are
 *       unreachable by this module rather than merely skipped.
 *
 *   S2  NEVER SWEEP A TAG THE RUNTIME IS ABOUT TO DECLARE. The sweep set is the
 *       baked snapshot MINUS the identities in the incoming input. This is not
 *       an optimisation — it is what makes the sweep SAFE. Unhead reconciles
 *       against (and may adopt) a baked element whose identity appears in an
 *       entry; ripping such an element out from under Unhead would desync its
 *       side-effect bookkeeping and could leave the tag permanently missing.
 *       Excluding them means this module only ever touches elements Unhead has
 *       no entry for and therefore can never have adopted. It also means the
 *       swept set IS exactly the strandable set, by construction.
 *
 *   S3  NEVER SWEEP `<title>`. Title is emitted unconditionally by
 *       `buildHeadTags`, so it is always re-asserted and can never strand; and
 *       it is the one managed tag with singleton semantics in the DOM and in
 *       `document.title`. It is excluded from the snapshot for the same reason
 *       as S1 — unreachable beats skipped.
 *
 *   S4  THE SNAPSHOT IS TAKEN AT INSTALL TIME, NOT AT SWEEP TIME. "Baked" means
 *       "present in the document the browser fetched". `installSeoHead` runs at
 *       app entry, after `createHead()` but BEFORE `app.mount()` — and Unhead's
 *       DOM write is debounced to a later task — so `document.head` at that
 *       instant holds the served tags and nothing else. Snapshotting lazily on
 *       the first navigation would instead capture Unhead's own output and let
 *       the sweep delete live runtime tags. The install-time snapshot is what
 *       makes "the ones the static emitter baked" a fact rather than a guess.
 *
 * ── WHY ONCE IS ENOUGH ─────────────────────────────────────────────────────
 * After the sweep, every managed element in the head is either (a) one the
 * runtime just declared — Unhead owns it, and drops it on a later navigation
 * that omits it (the RUNTIME->RUNTIME half, already proven working by ITEM 2b),
 * or (b) gone. There is no third category left for a later navigation to
 * strand, so a second sweep would have an empty set by definition. Sweeping
 * repeatedly would also mean holding DOM references for the life of the
 * session; the snapshot is released as soon as it is spent.
 *
 * ── WHAT CRAWLERS SEE: NOTHING CHANGES ─────────────────────────────────────
 * The sweep can only fire on a MATCHED IN-APP NAVIGATION. `installSeoHead`'s R5
 * already guarantees the fetched document is never written to, and a crawler or
 * social scraper fetches each URL as an isolated page load and never performs an
 * in-app navigation. The prerender path is likewise unaffected: the Playwright
 * renderer loads each route as a fresh document, so no in-app navigation ever
 * occurs and no sweep is reachable. Baked bytes are identical before and after
 * this change — which is also why it cannot disturb the emitter-output pins in
 * `runtimeVsBakedJsonLd.test.ts` (C-418): this module changes neither emitter.
 */

/**
 * A stable identity for a managed head tag, shared by the DOM side and the
 * head-input side so the two can be compared as sets.
 *
 * The shapes mirror how the head libraries dedupe:
 *   - `meta|name|<name>`             — `description`, `keywords`, `twitter:*`
 *   - `meta|property|<property>`     — `og:*`, `article:*`
 *   - `link|canonical`               — the singleton canonical
 *   - `link|alternate|<hreflang>`    — one per hreflang; the hreflang is part of
 *     the identity because a page may legitimately declare several alternates
 *     and they are only interchangeable within a single language.
 */
type ManagedTagIdentity = string;
/**
 * The identities the runtime is ABOUT to assert — the S2 exclusion set.
 *
 * Deliberately typed against {@link HeadMetaTag}/{@link HeadLinkTag}, the exact
 * structures `buildHeadTags` returns, so a future field on either flows through
 * the same identity function the DOM side uses.
 */
declare function headInputIdentities(input: {
    meta?: readonly HeadMetaTag[];
    link?: readonly HeadLinkTag[];
}): Set<ManagedTagIdentity>;
/**
 * Capture the managed tags the BUILD baked into the served document (S4).
 *
 * Call this at INSTALL time. `<title>` (S3) and `ld+json` scripts (S1) are not
 * collected at all, so no later mistake can sweep them.
 *
 * Returns a plain array of live element references. It is empty — and the whole
 * feature inert — when there is no document (SSR / node build context), which is
 * the same defensive posture `readInjectedPages` takes.
 */
declare function snapshotBakedManagedHeadTags(doc?: Document): Element[];
/**
 * Remove the baked managed tags the incoming head input does NOT re-declare.
 *
 * @param snapshot the install-time snapshot from
 *   {@link snapshotBakedManagedHeadTags}
 * @param input the head payload about to be pushed to the head client — the S2
 *   exclusion set is derived from it
 * @returns how many elements were actually removed, so the caller can REPORT
 *   the sweep instead of performing it silently
 *
 * Elements that have already left the document are skipped rather than removed
 * again: a baked element can legitimately disappear between install and the
 * first navigation (a view's own `useSEO` may have caused Unhead to reconcile
 * it away), and "still connected" is the cheap, library-agnostic way to ask
 * whether this module is still looking at the served DOM.
 */
declare function sweepBakedManagedHeadTags(snapshot: readonly Element[], input: {
    meta?: readonly HeadMetaTag[];
    link?: readonly HeadLinkTag[];
}): number;

/**
 * Build-time BODY prerender for the Vue-SPA static-HTML emitter.
 *
 * The companion to `emitStaticSeoHtml` (which bakes per-route `<head>` meta +
 * JSON-LD). Today every SPA route's emitted `<body>` is literally
 * `<div id="app"></div>` — allow-listed AI crawlers see the `@graph` + llms.txt
 * but ZERO body prose (blog copy, service descriptions, GEO-citable content).
 * This module fills the mount container with the REAL rendered DOM so a non-JS
 * crawler sees the page's body content.
 *
 * ── Why a render pass, not a content.yaml dump ────────────────────────────────
 * `.dcs/content.yaml` stores only visual-editor TEXT OVERRIDES — "Vue component
 * `defaults` objects are the source of truth for baseline text" (its own header).
 * Blog-post prose lives entirely in the site's `src/data/*.ts` and renders via
 * `v-html`; it is NOT in content.yaml at all. So the only faithful, generic way
 * to obtain a route's body is to RENDER the built app. This module is therefore
 * renderer-agnostic: it takes a {@link RouteRenderer} (the production default is
 * a headless-Playwright renderer of the just-built `dist/`; tests inject a fake)
 * and is otherwise pure — deterministic, `fs`-only, and unit-testable.
 *
 * ── Fabrication safety (the A-34 scar) ────────────────────────────────────────
 * A prior cms SSR path baked fabricated review defaults into crawler-visible
 * HTML. The default renderer drives the PRODUCTION client bundle, where Vite has
 * statically replaced `import.meta.env.DEV` with `false`, so the dev-only
 * `defaults` honesty gate (`useReviewContent.ts`) resolves to the honest empty
 * state — fabrication is structurally impossible, not merely avoided. Any route
 * that instead CRASHES (uncaught exception, or the app never mounts) surfaces as
 * a {@link BodyPrerenderError} and FAILS THE BUILD LOUD rather than shipping a
 * broken/empty body.
 */

/**
 * Normalise a route path to the on-disk output file the head emitter wrote:
 *   '/'               -> '<outDir>/index.html'
 *   '/services'       -> '<outDir>/services/index.html'
 *   '/blog/my-post'   -> '<outDir>/blog/my-post/index.html'
 *
 * Lives here (the lower-level module) so both this pass and `dcsSeoPlugin`'s
 * 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
     * {@link BodyPrerenderError} so the build fails loud instead of shipping wrong
     * content. Benign offline noise (blocked external asset, expected API 401) is
     * NOT reported here by the default renderer.
     */
    errors: string[];
}
/**
 * A build-time renderer that returns the rendered body for a route path. The
 * production implementation ({@link createPlaywrightRenderer}) drives the built
 * SPA in a headless browser; unit tests pass a deterministic fake.
 */
interface RouteRenderer {
    renderRoute(routePath: string): Promise<RenderedRoute>;
}
/**
 * Thrown when a route's render produced FATAL errors (a crash or a mount
 * failure). Deliberately escapes the plugin's never-break-the-build try/catch so
 * a component that would crash or emit wrong content FAILS THE BUILD (hard
 * requirement: never ship fabricated/broken body content).
 */
declare class BodyPrerenderError extends Error {
    readonly route: string;
    readonly errors: string[];
    constructor(route: string, errors: string[]);
}
/**
 * Replace the inner content of the FIRST `<div id="app">…</div>` mount container
 * with `bodyInnerHtml`, leaving `<head>`, the app `<script>`, and everything
 * else untouched. Free of a DOM dependency (mirrors `spliceHeadHtml`), and
 * robust to nested `<div>`s via depth counting so it also works when re-run over
 * an already-filled container (idempotent given a deterministic renderer).
 *
 * Returns the HTML unchanged when there is no `#app` container (defensive — the
 * caller logs + skips), so a non-SPA shell can never be corrupted.
 */
declare function spliceBodyHtml(html: string, bodyInnerHtml: string): string;
/** Inputs for {@link prerenderBodies}. */
interface PrerenderBodiesParams {
    /** Absolute path to the built SPA output directory (`dist`). */
    outDir: string;
    /** The SAME route set the head emitter used (from `.dcs/pages.yaml`). */
    routes: PageRouteEntry[];
    /** The renderer that returns each route's rendered body. */
    renderer: RouteRenderer;
    /** Routes to skip entirely — matched against route `path` OR `slug`. */
    exclude?: string[];
    /**
     * Routes that received `robots: noindex,nofollow` (auth-gated / private). These
     * are NOT body-prerendered — a noindex/auth route must never leak rendered body
     * content into `dist/` (hard requirement). Matched against `path` OR `slug`.
     */
    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. */
    prerendered: number;
    /** Number of routes skipped (excluded / noindex / missing head file / empty). */
    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
 * `dist/<path>/index.html` the head emitter already wrote. Reuses the exact same
 * exclude/excluded-glob filters as `emitStaticSeoHtml`, and ADDITIONALLY skips
 * every `noindex` route (auth-gated/private pages get a head-only file, never a
 * prerendered body).
 *
 * FAILS LOUD (throws {@link BodyPrerenderError}) when a route's render reports
 * fatal errors — better a red build than fabricated/broken crawler content.
 * Pure aside from `fs` reads/writes; the browser lives behind `renderer`.
 */
declare function prerenderBodies(params: PrerenderBodiesParams): Promise<PrerenderBodiesResult>;
/** Inputs for {@link isBodyPrerenderEnabled}. */
interface BodyPrerenderEnableInput {
    /** Whether the per-route static-HTML emitter is on (body prerender rides it). */
    emitStaticHtml: boolean;
    /** The plugin option `prerenderBody` (undefined ⇒ default ON when emitting). */
    prerenderBodyOption?: boolean;
    /** Preview/staging build — body prerender is skipped (kept minimal + fast). */
    preview?: boolean;
    /**
     * The per-site escape hatch read from `.dcs/seo.yaml` (`prerenderBody: false`).
     * Lets an operator disable body prerender for one site with NO code change and
     * NO cms republish — the portal owns seo.yaml. `undefined`/`true` ⇒ enabled.
     */
    seoPrerenderBody?: boolean;
}
/**
 * Resolve whether body prerender runs for this build. ON by default whenever the
 * static-HTML emitter is on; turned OFF by the plugin option `prerenderBody:
 * false`, by the seo.yaml `prerenderBody: false` escape hatch, in preview mode,
 * or when the emitter itself is off. Either OFF signal wins.
 */
declare function isBodyPrerenderEnabled(input: BodyPrerenderEnableInput): boolean;

/**
 * FAQ body-honesty rail — a `FAQPage` node must describe copy the page RENDERS.
 *
 * ## The defect class
 *
 * `buildFaqPage` (`./schemaGraph.ts`) emits a `FAQPage` from any well-formed
 * `{q,a}` pair it finds in `.dcs/content.yaml`. That gate enforces the SHAPE of
 * the honesty rule (no invented Q&A) but it cannot enforce its SUBSTANCE: the
 * builder is pure and has no idea whether the page it decorates renders those
 * questions anywhere a human — or a crawler — can see them. Seeding
 * `pages.<slug>.faq` without also rendering a visible FAQ section therefore
 * ships structured data for content that does not exist on the page. Google's
 * FAQPage guidance requires the Q&A be visible to the user; markup for invisible
 * content is a spam signal, and it is the exact fabrication class the rest of
 * this module tree exists to prevent.
 *
 * Measured origin: the 2026-08-30 Iron Oak drafting pass
 * (`.docs/analysis/iron-oak-seo-drafts-2026-08-30.md` §3, "The honesty condition
 * on all of the above") — Iron Oak has Q&A-shaped copy and no FAQ section, so
 * applying the FAQPage finding as a one-step content seed would have produced
 * exactly this defect on a live customer site.
 *
 * ## The rail
 *
 * Given an emitted document, take every `Question.name` out of every `FAQPage`
 * JSON-LD node and require each one to appear in the PRERENDERED BODY TEXT.
 *
 * ## The vacuity trap this rail is built around
 *
 * The question text is, by construction, already present in the document — it is
 * sitting in the `<script type="application/ld+json">` block being audited.
 * `dcsSeoPlugin` bakes that block into `<head>`, which `extractPrerenderedBodyText`
 * never reads, but not every emitter does (vite-ssg and hand-rolled prerenders
 * put JSON-LD in the body), and a body extractor that keeps `<script>` content
 * would then find every question in every document — green against a site with
 * no FAQ section at all. `extractPrerenderedBodyText` therefore strips
 * `<script>`, `<style>`, `<noscript>` and comments CONTENT-AND-ALL, and
 * `faqBodyHonesty.test.ts` exercises the body-placed case explicitly.
 */

/** One emitted document to audit. */
interface FaqBodyObservation {
    /** Route path as it appears in `pages.yaml` (e.g. `/` or `/services`). */
    route: string;
    /** The emitted HTML for that route, exactly as written to `dist/`. */
    html: string;
}
/** A `FAQPage` question with no counterpart in the rendered body. */
interface FaqBodyViolation {
    route: string;
    /** The `Question.name` verbatim, as authored in the JSON-LD. */
    question: string;
    /** How many questions that document's FAQPage node(s) declared in total. */
    questionCount: number;
}
/** Configuration for the rail. */
interface FaqBodyHonestyOptions {
    /**
     * Route paths exempted from the comparison. An exemption is still the caller's
     * to LOG — same contract as `HeadHonestyOptions.allow`.
     */
    allow?: string[];
}
/**
 * Normalise a string for PRESENCE comparison (is this text on the page?), which
 * is a weaker question than head honesty's IDENTITY comparison and so normalises
 * more:
 *   - HTML entities decoded (`&amp;` ⇒ `&`) — the two sides are escaped
 *     differently: JSON-LD escapes for JSON, body copy escapes for HTML.
 *   - typographic look-alikes folded to ASCII (`’ ‘ “ ” — –` ⇒ `' ' " " - -`) —
 *     the schema string and the rendered string come from the SAME content key
 *     but the rendered one may pass through a typography transform. A rail that
 *     reds because a renderer curled an apostrophe is an accusation, not a find.
 *   - whitespace collapsed — rendered copy is wrapped and indented.
 *   - lowercased — a question rendered as a title-cased heading is still visible.
 *
 * Deliberately NOT normalised: words. Nothing is stemmed, dropped or fuzzy-
 * matched, so a "close enough" body text does not satisfy the rail.
 */
declare function normalizeForPresence(value: string): string;
/**
 * Collect every `Question.name` declared by every `FAQPage` node in a document.
 *
 * Unparseable JSON-LD is SKIPPED, not reported — `cli/seo-coverage-audit.mjs`
 * already fails a route for unparseable structured data, and this rail must not
 * double-report someone else's finding as an FAQ defect.
 */
declare function extractFaqQuestions(html: string): string[];
/**
 * The visible text of the PRERENDERED BODY — what a non-JS crawler receives.
 *
 * `<script>`, `<style>`, `<noscript>` and HTML comments are removed CONTENT AND
 * ALL before tags are stripped. That is not tidiness: the JSON-LD under audit
 * lives in a `<script>`, so leaving script content in would make every question
 * trivially "present" and the rail vacuous (see the module header).
 *
 * Returns `''` when there is no `<body>` — an SPA shell with no prerendered body
 * has no visible copy, which is the honest answer, not a parse failure.
 */
declare function extractPrerenderedBodyText(html: string): string;
/**
 * Report every `FAQPage` question that the route's prerendered body does not
 * render. A document with no `FAQPage` node yields nothing — the rail is about
 * schema that over-claims, never about pages that decline to have an FAQ.
 */
declare function findFaqBodyHonestyViolations(observations: FaqBodyObservation[], options?: FaqBodyHonestyOptions): FaqBodyViolation[];
/**
 * Render the full report. Names the route, the question, and the fix — both
 * halves of the fix, because deleting the schema and rendering the section are
 * both valid resolutions and the operator picks.
 */
declare function formatFaqBodyHonestyReport(violations: FaqBodyViolation[]): string;
/** Thrown in `error` mode so the build goes red on invisible FAQ markup. */
declare class FaqBodyHonestyError extends Error {
    readonly violations: FaqBodyViolation[];
    constructor(violations: FaqBodyViolation[]);
}
/**
 * Enforce the rail. `error` throws, `warn` logs, `off` does nothing.
 * Mirrors `assertHeadHonesty` so the three-mode contract is uniform across rails.
 */
declare function assertFaqBodyHonesty(observations: FaqBodyObservation[], options?: FaqBodyHonestyOptions & {
    mode?: HonestyMode;
}): FaqBodyViolation[];

/**
 * 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, FaqBodyHonestyError, type FaqBodyHonestyOptions, type FaqBodyObservation, type FaqBodyViolation, 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, HeadLinkTag, HeadMetaTag, HeadObservation, HonestyMode, 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, assertFaqBodyHonesty, assertHeadContract, auditCheckedTotal, auditExemptionHosts, auditHeadContract, auditSameOriginAssets, blankComments, checkCharsetBudget, checkRemoteAssets, checkSameOriginAssets, classifyUrl, collectUrlsFromHtml, collectUrlsFromLlmsTxt, collectUrlsFromSitemap, dedupeUrls, extractFaqQuestions, extractPrerenderedBodyText, findCharsetByteOffset, findFaqBodyHonestyViolations, formatCharsetHeadroomWarning, formatEmittedUrlAudit, formatEmittedUrlReport, formatExemptionAudit, formatFaqBodyHonestyReport, formatHeadContractReport, headInputIdentities, hoistCharsetMeta, hostsNamedIn, isBodyPrerenderEnabled, normalizeExemption, normalizeForPresence, parseHostProbeHtml, prerenderBodies, routeToOutputFile, snapshotBakedManagedHeadTags, spliceBodyHtml, sweepBakedManagedHeadTags };