npm - @duffcloudservices/cms - Versions diffs - 0.12.0 → 0.13.0 - Mend

@duffcloudservices/cms 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/README.md +244 -8
package/dist/chunk-A5F4C72F.js +500 -0
package/dist/chunk-A5F4C72F.js.map +1 -0
package/dist/{chunk-F3EIWEZD.js → chunk-HVSF23P7.js} +971 -73
package/dist/chunk-HVSF23P7.js.map +1 -0
package/dist/editor/editorBridge.d.ts +13 -1
package/dist/editor/editorBridge.js +75 -5
package/dist/editor/editorBridge.js.map +1 -1
package/dist/headHonesty-OzxvLuwd.d.ts +222 -0
package/dist/index.d.ts +365 -22
package/dist/index.js +421 -21
package/dist/index.js.map +1 -1
package/dist/installSeoHead-kWQwObez.d.ts +627 -0
package/dist/plugins/index.d.ts +90 -6
package/dist/plugins/index.js +530 -49
package/dist/plugins/index.js.map +1 -1
package/dist/seo/index.d.ts +763 -4
package/dist/seo/index.js +2 -2
package/dist/{vitepressTransform-DfmABXmK.d.ts → vitepressTransform-JG_zlaux.d.ts} +99 -6
package/package.json +17 -6
package/src/components/DcsCallButton.test.ts +58 -0
package/src/components/DcsCallButton.vue +19 -4
package/src/components/LiteMediaEmbed.vue +3 -3
package/src/components/ManagedImage.test.ts +34 -0
package/src/components/ManagedImage.vue +5 -0
package/src/components/PreviewRibbon.vue +4 -1
package/src/composables/useConversionTracking.test.ts +492 -0
package/src/composables/useConversionTracking.ts +770 -0
package/src/composables/useReleaseNotes.ts +7 -1
package/src/composables/useSEO.applyHead.test.ts +150 -0
package/src/composables/useSEO.ts +63 -17
package/src/composables/useSiteVersion.ts +4 -1
package/src/composables/useSiteVisitorSession.test.ts +56 -0
package/src/composables/useSiteVisitorSession.ts +39 -3
package/src/composables/useTextContent.ts +9 -1
package/dist/chunk-DAYLLSEE.js +0 -3
package/dist/chunk-DAYLLSEE.js.map +0 -1
package/dist/chunk-F3EIWEZD.js.map +0 -1
package/dist/spliceHeadHtml-CsBEucGy.d.ts +0 -254

package/dist/headHonesty-OzxvLuwd.d.ts ADDED Viewed

@@ -0,0 +1,222 @@
+/**
+ * P1 — baked-vs-rendered `<head>` honesty rail.
+ *
+ * ## The defect this exists for
+ *
+ * `.dcs/seo.yaml` is the owner-approved, portal-managed source of truth for a
+ * page's `<title>` and description, and {@link buildHeadTags} bakes it into the
+ * per-route static HTML. But the SAME resolver is also reachable at runtime via
+ * `useSEO().applyHead(overrides)`, and an `overrides.title` is used VERBATIM —
+ * it does not go through `titleTemplate`. So a view that hardcodes
+ * `applyHead({ title: 'Our Services' })` silently replaces the approved title
+ * the instant the app boots.
+ *
+ * Measured on live production (2026-07-27, before the site-local fix):
+ *
+ * ```
+ * route      baked (non-JS crawler)                                   runtime (Google + humans)
+ * /          Rochester Hills Handyman, Repairs & Carpentry | Iron Oak  Iron Oak Contractors | Crafted Repairs …
+ * /services  Handyman, Carpentry & Home Repairs in SE Michigan | …     Our Services
+ * ```
+ *
+ * Two crawlers, two different sites. Nothing failed. Nothing logged. The
+ * approved SEO decision (C-147 / Q-141=B) was live for AI crawlers and reverted
+ * for Google — for the whole time since it shipped.
+ *
+ * ## What the rail asserts
+ *
+ * After the build, for every route the emitter wrote, the prerender browser is
+ * already loading the page. This rail reads `document.title` and the effective
+ * `meta[name=description]` from that SAME render and compares them to the values
+ * baked into the file on disk. Any divergence names the route and BOTH values.
+ *
+ * ## Why the pass condition is stable (not a moving target)
+ *
+ * A site whose views call `applyHead()` with no title/description overrides
+ * produces byte-identical tags at runtime and at build time — same
+ * {@link buildHeadTags}, same `seo.yaml` (the plugin bakes it into
+ * `__DCS_SEO__`). Zero divergence is therefore the *structural* outcome of
+ * seo.yaml being the only writer, not a threshold someone has to keep tuning.
+ *
+ * ## Escape hatches (visible by construction)
+ *
+ * `mode` can be lowered to `warn`/`off` and individual routes can be listed in
+ * `allow`, but both live in `.dcs/seo.yaml` (portal-owned, in git, reviewable)
+ * or in an env var that prints in the build log — there is no silent way to
+ * switch this off. Every allowed route is still logged.
+ */
+/** How a divergence is reported. */
+type HonestyMode = 'error' | 'warn' | 'off';
+/** One route's baked and rendered head values. */
+interface HeadObservation {
+    /** Route path as it appears in `pages.yaml` (e.g. `/services`). */
+    route: string;
+    /** `<title>` as written into the emitted file (still HTML-escaped). */
+    bakedTitle: string | null;
+    /** `document.title` after the app mounted. */
+    runtimeTitle: string | null;
+    /** `meta[name=description]@content` as written into the emitted file. */
+    bakedDescription: string | null;
+    /** The EFFECTIVE `meta[name=description]` in the rendered DOM (the last one). */
+    runtimeDescription: string | null;
+    /** How many `meta[name=description]` tags the rendered DOM carried. */
+    runtimeDescriptionCount?: number;
+}
+/** A single baked≠rendered divergence. */
+interface HeadHonestyViolation {
+    route: string;
+    field: 'title' | 'description';
+    baked: string | null;
+    runtime: string | null;
+}
+/** Configuration for the rail. */
+interface HeadHonestyOptions {
+    /** `error` (default) fails the build, `warn` logs, `off` skips entirely. */
+    mode?: HonestyMode;
+    /** Also compare the meta description (default `true`). */
+    checkDescription?: boolean;
+    /**
+     * Route paths exempted from the comparison. An exemption is still LOGGED, so
+     * "who turned this off for which route" is answerable from the build output.
+     */
+    allow?: string[];
+}
+/**
+ * Decode the HTML character references the emitter can produce.
+ *
+ * This is NOT a general-purpose entity decoder — it covers the set
+ * `spliceHeadHtml`'s `escapeAttr` emits (`& " < >`) plus numeric references and
+ * the handful of named ones that appear in real CMS copy. Anything unrecognised
+ * is left verbatim, which is the safe direction: an unknown entity can only ever
+ * cause a *reported* divergence to be investigated, never a real one to be
+ * silently swallowed.
+ */
+declare function decodeHtmlEntities(value: string): string;
+/**
+ * Put a baked (HTML-source) value and a rendered (DOM) value on the same
+ * footing before comparing them.
+ *
+ * The three transforms exist because of three MEASURED false-positive
+ * mechanisms, not from caution:
+ *   - **entity decode** — the baked side carries `Repairs &amp; Carpentry`
+ *     while `document.title` yields `Repairs & Carpentry`. Identical strings.
+ *   - **whitespace collapse** — `document.title` is specified to strip and
+ *     collapse ASCII whitespace; the emitted `<title>` keeps the author's.
+ *   - **Unicode NFC** — a composed `é` and a decomposed `é` render identically
+ *     and mean the same thing; only the byte sequence differs.
+ *
+ * Deliberately NOT normalised: case, punctuation, and typographic look-alikes
+ * (`-` vs `—`, `'` vs `’`). Those are real content differences and a rail that
+ * hides them is the vacuous-green shape this whole class of work exists to kill.
+ */
+declare function normalizeHeadText(value: string | null | undefined): string | null;
+/** The baked `<title>` / description of an emitted document. */
+interface BakedHead {
+    title: string | null;
+    description: string | null;
+}
+/**
+ * Read the baked `<title>` and `meta[name=description]` out of an emitted file.
+ *
+ * Regex-based on purpose — it mirrors `spliceHeadHtml`, runs over the emitter's
+ * own deterministic output, and keeps a heavy HTML parser out of the build.
+ */
+declare function extractBakedHead(html: string): BakedHead;
+/**
+ * Compare every observation and return the divergences.
+ *
+ * A `null` on either side is meaningful and reported: a runtime that DELETES the
+ * baked description is the same class of silent undoing as one that rewrites it.
+ * The one exception is a route where BOTH sides are absent — nothing was claimed,
+ * so nothing was undone.
+ */
+declare function findHeadHonestyViolations(observations: HeadObservation[], options?: HeadHonestyOptions): HeadHonestyViolation[];
+/**
+ * Render the full report. Every violation names the ROUTE and BOTH values, so
+ * the operator never has to reproduce the divergence to act on it — which is the
+ * difference between a rail people fix and a rail people mute.
+ */
+declare function formatHeadHonestyReport(violations: HeadHonestyViolation[]): string;
+/** Thrown in `error` mode so the build goes red on a divergence. */
+declare class HeadHonestyError extends Error {
+    readonly violations: HeadHonestyViolation[];
+    constructor(violations: HeadHonestyViolation[]);
+}
+/** Inputs that can set the rail's severity, in increasing precedence. */
+interface HonestyModeInput {
+    /** Compiled-in default. */
+    fallback?: HonestyMode;
+    /** The plugin option in `vite.config.ts`. */
+    option?: HonestyMode | boolean;
+    /** The per-site escape hatch in `.dcs/seo.yaml`. */
+    seoYaml?: HonestyMode | boolean;
+    /** The env override (e.g. `DCS_SEO_HEAD_HONESTY=warn`) — highest precedence. */
+    env?: string | undefined;
+}
+/**
+ * Resolve the effective severity.
+ *
+ * Precedence is env > seo.yaml > plugin option > default, i.e. the MOST
+ * operator-visible signal wins. An unrecognised value is ignored rather than
+ * treated as "off" — a typo'd escape hatch must never silently disable a gate.
+ */
+declare function resolveHonestyMode(input: HonestyModeInput): HonestyMode;
+/**
+ * What the render pass was able to observe, so the rail can prove it RAN.
+ *
+ * ## The defect this exists for
+ *
+ * C-334 shipped P1 with an environment-dependent silent skip: when
+ * `createPlaywrightRenderer` found no playwright/browser it warned and returned
+ * no observations, and the caller then *skipped the assert entirely* — so an
+ * `error`-severity rail let the build pass having checked nothing. That is the
+ * same shape as C-322 (the snapshot rail was vacuous for months because `gh` was
+ * missing on the runner) and the exact class this campaign exists to close.
+ *
+ * A rail is only a gate if "it did not run" is itself a failure. In `error`
+ * mode the three non-execution shapes below are hard failures; in `warn` mode
+ * they are warnings that name exactly what was not checked.
+ */
+interface HeadHonestyExecution {
+    /** Did the build have a headless renderer at all? */
+    rendererAvailable: boolean;
+    /** Routes that reached the renderer (the denominator). */
+    eligibleRoutes: string[];
+    /** Routes that produced a baked-vs-rendered observation (the numerator). */
+    observedRoutes: string[];
+    /** Routes that never reached the renderer, with why. */
+    filteredRoutes: Array<{
+        route: string;
+        reason: string;
+    }>;
+    /** Every route in the manifest, for the "0 of N" arithmetic. */
+    totalRoutes: number;
+}
+/** Why the rail did not run (empty ⇒ it ran). */
+declare function findHeadHonestyExecutionFaults(ex: HeadHonestyExecution): string[];
+/** Render the "this rail did not run" report — it names what went unchecked. */
+declare function formatHeadHonestyExecutionReport(ex: HeadHonestyExecution, faults: string[]): string;
+/** Thrown in `error` mode when the P1 rail could not run. */
+declare class HeadHonestyNotRunError extends Error {
+    readonly execution: HeadHonestyExecution;
+    readonly faults: string[];
+    constructor(execution: HeadHonestyExecution, faults: string[]);
+}
+/**
+ * Assert the rail RAN. Throws {@link HeadHonestyNotRunError} in `error` mode,
+ * warns in `warn` mode. Returns `true` when the comparison is worth running
+ * (i.e. there is at least one observation to compare).
+ */
+declare function assertHeadHonestyExecuted(execution: HeadHonestyExecution, options: {
+    mode: HonestyMode;
+}): boolean;
+/**
+ * Apply the rail: throw in `error` mode, log in `warn` mode, do nothing in
+ * `off`. Returns the violations so callers can report counts.
+ */
+declare function assertHeadHonesty(observations: HeadObservation[], options: HeadHonestyOptions & {
+    mode: HonestyMode;
+    debug?: boolean;
+}): HeadHonestyViolation[];
+export { type BakedHead as B, type HonestyMode as H, type HeadObservation as a, assertHeadHonesty as b, formatHeadHonestyReport as c, decodeHtmlEntities as d, extractBakedHead as e, findHeadHonestyViolations as f, HeadHonestyError as g, assertHeadHonestyExecuted as h, findHeadHonestyExecutionFaults as i, formatHeadHonestyExecutionReport as j, HeadHonestyNotRunError as k, type HeadHonestyExecution as l, type HonestyModeInput as m, normalizeHeadText as n, type HeadHonestyViolation as o, type HeadHonestyOptions as p, resolveHonestyMode as r };

package/dist/index.d.ts CHANGED Viewed

@@ -1,8 +1,8 @@
 import * as vue from 'vue';
 import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
-import { U as UseSeoReturn, G as GlobalSeoConfig } 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, X as HeadOverrides, P as PageSeoConfig, R as ResolvedPageOverrides, T as ResolvedPageSeo, z as ReviewSource, w as SchemaObject, O as SeoAlternateConfig, I as SeoAuthorConfig, H as SeoConfiguration, K as SeoImagesConfig, L as SeoOpenGraphConfig, S as SeoPageContext, r as SeoPageTypeRule, N as SeoSchemaConfig, J as SeoSocialConfig, M as SeoTwitterConfig, Q as SeoVerificationConfig, W as UseSeoConfig, t as VitePressHeadConfig, V as VitePressPageData, q as absolutizeUrl, j as breadcrumbTrailFromRoute, k as buildBlogPosting, h as buildBreadcrumbList, l as buildFaqPage, g as buildGlobalGraph, f as buildLlmsTxt, m as buildReviewSchemaParts, e as buildRobotsTxt, a as buildSitemapXml, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute, o as filterRealFaq, n as filterRealReviews, p as findReviewItemsForPage, i as isRouteIndexable, s as slugToTitle } from './vitepressTransform-DfmABXmK.js';
-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 { U as UseSeoReturn, G as GlobalSeoConfig } 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, X as HeadOverrides, P as PageSeoConfig, R as ResolvedPageOverrides, T as ResolvedPageSeo, z as ReviewSource, w as SchemaObject, O as SeoAlternateConfig, I as SeoAuthorConfig, H as SeoConfiguration, K as SeoImagesConfig, L as SeoOpenGraphConfig, S as SeoPageContext, r as SeoPageTypeRule, N as SeoSchemaConfig, J as SeoSocialConfig, M as SeoTwitterConfig, Q as SeoVerificationConfig, W as UseSeoConfig, t as VitePressHeadConfig, V as VitePressPageData, q as absolutizeUrl, j as breadcrumbTrailFromRoute, k as buildBlogPosting, h as buildBreadcrumbList, l as buildFaqPage, g as buildGlobalGraph, f as buildLlmsTxt, m as buildReviewSchemaParts, e as buildRobotsTxt, a as buildSitemapXml, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute, o as filterRealFaq, n as filterRealReviews, p as findReviewItemsForPage, i as isRouteIndexable, s as slugToTitle } from './vitepressTransform-JG_zlaux.js';
+export { j as HeadLinkTag, H as HeadMetaTag, k as HeadScriptTag, l as HeadTagOverrides, I as InstallSeoHeadOptions, R as ResolvedHeadTags, o as SeoHeadClientLike, p as SeoHeadEntryLike, q as SeoHeadInput, t as SeoHeadPageRoute, u as SeoHeadPagesManifest, v as SeoHeadResolution, w as SeoHeadResolutionReason, m as SeoHeadRouteLike, S as SeoHeadRouterLike, b as buildHeadTags, h as buildSeoHeadRouteMap, f as escapeJsonLd, 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 { ImageContext, ResponsiveImageResult } from '@duffcloudservices/cms-core';
 export { ImageContext, ResponsiveImageOptions, ResponsiveImageResult, ResponsiveSource, isCdnAssetUrl, resolveResponsiveImage } from '@duffcloudservices/cms-core';
@@ -119,6 +119,12 @@ declare function useTextContent(config: TextContentConfig): TextContentReturn;
  * module so that the build-time static-HTML emitter (`dcsSeoPlugin`) produces
  * byte-identical output. This composable is a thin Vue/unhead wrapper over it.
  *
+ * THE HEAD-AUTHORITY CONTRACT (C-356). `.dcs/seo.yaml` is the ONLY writer of
+ * the managed head fields. `applyHead()` RE-ASSERTS the baked head at runtime;
+ * it never AUTHORS one, so it takes no arguments. Full text + reasoning:
+ * `.docs/plans/dynamic-site-resolution/README.md` § "The head-authority
+ * contract (C-356)".
+ *
  * @example
  * ```vue
  * <script setup lang="ts">
@@ -126,16 +132,15 @@ declare function useTextContent(config: TextContentConfig): TextContentReturn;
  *
  * const { applyHead, getSchema, config } = useSEO('home')
  *
- * // Apply all meta tags
+ * // Re-assert the baked head for this route. No arguments — ever.
  * applyHead()
- *
- * // Or customize before applying
- * applyHead({
- *   title: 'Custom Override Title',
- *   schemas: [...getSchema(), customSchema]
- * })
  * </script>
  * ```
+ *
+ * Need a different title? Change it in `.dcs/seo.yaml` (or in the portal SEO
+ * editor, which writes it). A value hardcoded here is a SECOND writer, and a
+ * second writer is a divergence by construction — whether or not today's two
+ * values happen to agree.
  */
 /**
@@ -477,22 +482,347 @@ interface UseReviewContentReturn {
 }
 declare function useReviewContent(config: UseReviewContentConfig): UseReviewContentReturn;
+/** How a clicked element was classified. */
+type ConversionInteractionType = 'booking' | 'phone' | 'email' | 'form_submit' | 'social' | 'external' | 'internal' | 'button';
+/**
+ * The interaction types that ARE the money moment — the ones an owner report counts.
+ *
+ * Everything else (`social`, `external`, `internal`, `button`) is navigation telemetry and
+ * is still captured, but it must never be summed into "conversions". Keeping the set here,
+ * rather than in each report's query, means one edit changes every consumer.
+ */
+declare const CONVERSION_INTERACTION_TYPES: readonly ConversionInteractionType[];
+/** Whether an interaction type counts as a conversion. */
+declare function isConversionType(type: ConversionInteractionType): boolean;
+/** A captured conversion event, in App Insights `trackEvent` shape. */
+interface ConversionEvent {
+    /** Event name — `site_interaction` by default (see {@link ConversionTrackingOptions.eventName}). */
+    name: string;
+    /** Flat string properties; App Insights `customDimensions`. */
+    properties: {
+        interaction_type: ConversionInteractionType;
+        /**
+         * `'true'` when {@link isConversionType} holds. A string, not a boolean, because App
+         * Insights `customDimensions` and GA4 event params are both string maps — so the
+         * owner-report query is one predicate (`is_conversion == "true"`) instead of an
+         * interaction-type IN-list that every new report has to remember to keep in sync.
+         */
+        is_conversion: string;
+        /** Visible label / aria-label of the clicked element, truncated. */
+        label: string;
+        /**
+         * Destination, query string and fragment stripped, and REDACTED for contact schemes:
+         * a `tel:` / `sms:` / `mailto:` href becomes `tel:#<digest>` — never the raw number or
+         * address. See {@link redactHref}. Empty for buttons and form submits.
+         */
+        href: string;
+        /** URL scheme of the destination including the colon (`tel:`, `https:`), or `''`. */
+        href_scheme: string;
+        /** Host of the destination, or `''` for buttons, form submits and contact schemes. */
+        href_host: string;
+        /**
+         * Short digest of the contact target (the phone number / email address), or `''` for
+         * everything else. Lets a report say "CTA A got 12 taps, CTA B got 3" without ever
+         * storing the contact string itself.
+         */
+        href_hash: string;
+        /** Path of the page the click happened on. */
+        page_path: string;
+        /** Host of the page the click happened on. */
+        host: string;
+        /** Schema version, so a report can tell old rows from new ones. */
+        capture_version: string;
+    };
+}
+/** A telemetry transport. Typically `(e) => telemetry.trackEvent(e)`. */
+type ConversionSink = (event: ConversionEvent) => void;
+interface ConversionTrackingOptions {
+    /**
+     * Where to send events. Optional on purpose — omit it when the telemetry SDK is
+     * deferred, and call {@link attachConversionSink} once it has loaded. Events captured
+     * in the meantime are buffered, not dropped.
+     */
+    sink?: ConversionSink;
+    /**
+     * Fire-and-forget transports that receive every event AS WELL AS `sink`, and that do NOT
+     * count as "a sink exists" for buffering purposes.
+     *
+     * This distinction is load-bearing. GA4's `gtag` is a mirror: the deploy injects it as a
+     * synchronous inline snippet, so it is either there when the click happens or the hit is
+     * genuinely unavailable — there is nothing to wait for. App Insights is a `sink`: it boots
+     * on an idle callback minutes later, which is exactly what the buffer exists to survive.
+     * Treating GA4 as a `sink` would have satisfied the "do we have somewhere to send this?"
+     * test on every site and quietly disabled the deferred-SDK interlock.
+     */
+    mirrors?: ConversionSink[];
+    /**
+     * Custom event name. Defaults to `site_interaction` — the name Just Posh has been
+     * emitting since 2026-04, so its history stays one continuous series. Pass
+     * `'dcs_conversion'` on a site with no existing history if you prefer the canonical name.
+     */
+    eventName?: string;
+    /**
+     * Extra hostnames to treat as booking destinations, on top of {@link DEFAULT_BOOKING_HOSTS}.
+     * Matched on host suffix, so `vagaro.com` also matches `www.vagaro.com`.
+     */
+    bookingHosts?: string[];
+    /**
+     * Same-origin paths that mean "booking" (e.g. a self-hosted `/book`). Matched as a
+     * prefix on the pathname.
+     */
+    bookingPaths?: string[];
+    /** Extra social hostnames on top of {@link DEFAULT_SOCIAL_HOSTS}. */
+    socialHosts?: string[];
+    /** Max events held while no sink is attached. Default 50 — bounded so a bot cannot grow it. */
+    bufferLimit?: number;
+    /** Drop untrusted (script-dispatched) clicks. Default `false`. */
+    requireTrusted?: boolean;
+    /** Document to bind to. Defaults to the ambient `document`. Injected in tests. */
+    target?: Document;
+    /**
+     * Also capture managed-form submissions as `form_submit`. Default `true`.
+     *
+     * A form submit is a conversion on every DCS site that has a form, and it is the one
+     * affordance a click listener alone cannot see honestly: clicking "Send" on a form that
+     * then fails validation is not a lead. So the `submit` event — not the click — is
+     * authoritative, and clicks on submit controls are deliberately dropped to keep the two
+     * from counting the same action twice.
+     */
+    captureFormSubmits?: boolean;
+    /**
+     * Honour the visitor's Do Not Track signal. Default `true`.
+     *
+     * With DNT on, `start()` binds nothing at all — no listener, no buffer, no event. This
+     * is a measurement rail, not a consent platform: if a site ever grows a real consent
+     * banner, gate {@link installConversionCapture} on it rather than weakening this.
+     */
+    respectDoNotTrack?: boolean;
+    /**
+     * Bind a second delegated listener even though one is already live on this document.
+     *
+     * Off by default and it should stay off. Two delegated listeners on one document count
+     * every click twice — the same defect class C-288 measured as 52% duplicate page views
+     * on a live customer site, which the portal then reported to the owner as traffic. If
+     * you are reaching for this, you almost certainly want `stop()` on the existing tracker.
+     */
+    force?: boolean;
+}
+/**
+ * Schema version stamped on every captured event. Bump on a breaking property change.
+ *
+ * `2` (C-326): `href` is redacted for `tel:`/`sms:`/`mailto:`, and `is_conversion`,
+ * `href_scheme` + `href_hash` were added. Version `1` rows carry raw contact hrefs and no
+ * conversion flag, so a report spanning the boundary must branch on this.
+ */
+declare const CONVERSION_CAPTURE_VERSION = "2";
+/**
+ * Booking/scheduling vendors seen across the DCS fleet plus the common SMB schedulers.
+ * Host-suffix matched. Add per-site extras via `bookingHosts` rather than editing this.
+ */
+declare const DEFAULT_BOOKING_HOSTS: readonly string[];
+/** Social destinations. Host-suffix matched. */
+declare const DEFAULT_SOCIAL_HOSTS: readonly string[];
+/**
+ * FNV-1a (32-bit), base36. Synchronous on purpose: this runs inside a click handler, where
+ * `crypto.subtle` — the only real hash a browser offers — is async and would force the
+ * event to be built after the navigation has already started.
+ *
+ * BE HONEST ABOUT WHAT THIS IS. It is not anonymisation. A site publishes two or three
+ * phone numbers, so anybody holding the site could brute-force the digest back in
+ * milliseconds. What it buys is real but narrow: the contact string never lands in an
+ * analytics store (GA4 forbids PII in event params outright), a support screenshot of the
+ * events table cannot leak a customer's mailbox, and the value is still stable enough to
+ * answer "which CTA did they tap". Do not describe it as anything more than that.
+ */
+declare function hashTarget(value: string): string;
+/** The scheme of an href, including the colon (`tel:`, `https:`), or `''`. */
+declare function hrefScheme(href: string, pageHost: string): string;
+/**
+ * Split an href into the parts that are safe to emit.
+ *
+ * For `tel:` / `sms:` / `mailto:` the target is a person's or business's contact string, so
+ * it is replaced by `<scheme>#<digest>` and the digest is also surfaced on its own. For
+ * everything else the href passes through {@link sanitizeUrl} unchanged — a booking URL's
+ * path is the useful part and its query (which CAN carry a name or email) is already gone.
+ */
+declare function redactHref(href: string, pageHost: string): {
+    href: string;
+    scheme: string;
+    hash: string;
+};
+/**
+ * Whether this element is the control that submits a form.
+ *
+ * Clicks on these are dropped so the `submit` event can be the single source of truth —
+ * see {@link ConversionTrackingOptions.captureFormSubmits}. Note the HTML default: a
+ * `<button>` inside a form with no `type` IS a submit button, which is exactly how every
+ * `<DcsForm>` renders its action.
+ */
+declare function isSubmitControl(el: Element): boolean;
+/** Read the visitor's Do Not Track signal across the three places browsers have put it. */
+declare function doNotTrackEnabled(): boolean;
+/**
+ * Classify a link.
+ *
+ * ORDER IS LOAD-BEARING and is asserted by tests. Protocol wins first (a `tel:` href has
+ * no host to match on), then booking — *before* the same-origin and social checks — so a
+ * self-hosted `/book` path and a booking vendor that also runs a social profile are both
+ * attributed to revenue rather than to `internal` / `social`.
+ */
+declare function classifyHref(href: string, opts: {
+    pageHost: string;
+    bookingHosts: readonly string[];
+    bookingPaths: readonly string[];
+    socialHosts: readonly string[];
+}): ConversionInteractionType;
+/** The object returned by {@link createConversionTracker}. */
+interface ConversionTracker {
+    /** Bind the capture-phase click listener. Idempotent. */
+    start(): void;
+    /** Unbind and clear the buffer. Idempotent. */
+    stop(): void;
+    /** Attach (or replace) the sink and immediately drain anything buffered. */
+    attachSink(sink: ConversionSink): void;
+    /** Events currently held because no sink is attached. Read-only copy. */
+    buffered(): ConversionEvent[];
+    /** Capture a click target directly. Exposed for tests and manual instrumentation. */
+    capture(element: Element): ConversionEvent | null;
+}
+/**
+ * Attach a sink to every live tracker and drain their buffers.
+ *
+ * Call this from a deferred/lazy App Insights loader once the SDK is ready:
+ *
+ * ```ts
+ * const { ApplicationInsights } = await import('@microsoft/applicationinsights-web')
+ * const ai = new ApplicationInsights({ config })
+ * ai.loadAppInsights()
+ * attachConversionSink((e) => ai.trackEvent({ name: e.name, properties: e.properties }))
+ * ```
+ *
+ * @returns how many trackers received the sink.
+ */
+declare function attachConversionSink(sink: ConversionSink): number;
+/**
+ * Framework-free conversion tracker. Vue callers usually want
+ * {@link useConversionTracking} instead.
+ */
+declare function createConversionTracker(options?: ConversionTrackingOptions): ConversionTracker;
+/**
+ * Vue composable: start conversion capture for the lifetime of the calling component.
+ *
+ * YOU PROBABLY DO NOT NEED THIS ANY MORE. Since C-326, importing `@duffcloudservices/cms`
+ * auto-installs a tracker (`installConversionCapture`), so every fleet site captures
+ * conversions with no site-repo code at all. Calling this on top of that is a no-op with a
+ * loud console warning — `start()` refuses to bind a second listener to a document that
+ * already has one, because two listeners double every conversion count.
+ *
+ * It remains exported for the cases the auto-install deliberately does not cover: a site
+ * that needs per-site `bookingHosts`/`bookingPaths`, or a non-cms consumer wiring capture
+ * by hand. In the first case, prefer configuring the auto-installer:
+ *
+ * ```ts
+ * import { installConversionCapture } from '@duffcloudservices/cms'
+ * installConversionCapture({ bookingHosts: ['stridethera.com'], bookingPaths: ['/book'] })
+ * ```
+ *
+ * Returns the tracker so a caller can attach a sink or inspect the buffer. Safe on the
+ * server: with no `document`, `start()` is a no-op.
+ */
+declare function useConversionTracking(options?: ConversionTrackingOptions): ConversionTracker;
+/**
+ * Fleet-wide conversion capture, installed without asking the site.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * `useConversionTracking` shipped in @duffcloudservices/cms, was exported from the package
+ * index, was documented with an example, and was adopted by ZERO of the eleven fleet sites.
+ * Two independent reviews on 2026-07-26 measured what that cost (C-326):
+ *
+ *   - Bryan's Handyman Solutions exists to generate phone calls. It ships five `tel:` CTAs
+ *     — hero, header, mobile icon, sticky call bar, footer — and every one of them fires
+ *     nothing. `trackEvent` appears in the bundle exactly once: as the composable's own
+ *     unused export. Its GA4 property was never created either, so the site has no
+ *     measurement of any kind for the only action it is built to produce.
+ *   - Kim Duff Homes, a flagship account, has 6 pageViews in App Insights across 365 days.
+ *
+ * The lesson is not "write better docs". A capability the site must remember to switch on
+ * is a capability that is off. So capture is a SIDE EFFECT of importing the package every
+ * fleet site already depends on, and it finds its own transport.
+ *
+ * HOW A SITE'S EVENTS GET OUT — three sinks, in the order they are usually available
+ * ---------------------------------------------------------------------------------
+ *  1. GA4 (`window.gtag`). The deploy workflow injects the gtag snippet into every built
+ *     HTML file when `.dcs/site.yaml` carries a `google_analytics_id`. That means a site
+ *     with GA4 configured captures conversions with LITERALLY no code change — which is
+ *     precisely why the empty-`google_analytics_id` launch gate is the other half of C-326.
+ *  2. `window.__dcsConversionAttach(sink)` — a one-line, import-free contract published by
+ *     this module for any telemetry transport that boots later. `@duffcloudservices/telemetry`
+ *     calls it automatically inside `initialize()`; a site with a bespoke App Insights boot
+ *     adds the single line. Events captured before that arrive are buffered, not lost.
+ *  3. `attachConversionSink(sink)` — the direct API, for callers holding the import.
+ *
+ * WHERE IT DELIBERATELY DOES NOTHING
+ * ----------------------------------
+ *  - No `document` (SSR, VitePress build, the Playwright prerender pass).
+ *  - Inside an iframe — the DCS visual editor and preview surfaces frame the site, and
+ *     an editor clicking around a customer's page is not a lead.
+ *  - Do Not Track is on.
+ *  - The page opted out via `window.__dcsConversionOptOut = true` or
+ *    `<html data-dcs-analytics="off">`.
+ *
+ * In every one of those cases it binds no listener and buffers nothing.
+ */
+/** Options for {@link installConversionCapture}. */
+interface InstallConversionCaptureOptions extends Omit<ConversionTrackingOptions, 'sink' | 'mirrors' | 'force'> {
+    /**
+     * Emit through GA4's `window.gtag` when it is present. Default `true`.
+     *
+     * Looked up at emit time, not install time: the gtag snippet is `async`, so on a fast
+     * connection the site's JS can install this before Google's script has defined `gtag`.
+     */
+    gtag?: boolean;
+}
+/** Whether the page has explicitly asked not to be measured. */
+declare function conversionOptedOut(): boolean;
 /**
- * Site-visitor session probe client.
+ * Whether this document is being rendered inside a frame.
  *
- * Customer sites poll "who is signed in?" on load to render the right auth UI.
- * Signed-out is the EXPECTED state for the vast majority of visits, so this
- * client treats it as normal and never logs:
+ * The DCS portal embeds customer sites in an iframe for the visual editor and preview
+ * (`dcsEditorPlugin` keys off the same `window.parent !== window` test). Counting an
+ * editor's clicks as customer conversions would inflate exactly the number the owner
+ * report is supposed to make trustworthy.
+ */
+declare function inFrame(): boolean;
+/** Reason the installer declined, or `null` when it installed. */
+type ConversionInstallSkipReason = 'no-document' | 'already-installed' | 'in-frame' | 'do-not-track' | 'opted-out';
+/** Result of an {@link installConversionCapture} call. */
+interface ConversionInstallResult {
+    installed: boolean;
+    reason: ConversionInstallSkipReason | null;
+    tracker: ConversionTracker | null;
+}
+/**
+ * Install fleet conversion capture. Idempotent; safe to call from anywhere, any number of
+ * times, on the server or in a frame.
  *
- *  - New servers answer an anonymous probe with `200 { "visitor": null }`.
- *  - Old servers (pre-fix) answer an anonymous probe with `401`.
+ * Called for its side effect from the package index, so a site gets this by importing
+ * `@duffcloudservices/cms` at all. Call it directly only to pass per-site configuration
+ * (extra `bookingHosts`, a self-hosted `bookingPaths`) — do that BEFORE the first click,
+ * i.e. at app entry, since the first call wins.
+ */
+declare function installConversionCapture(options?: InstallConversionCaptureOptions): ConversionInstallResult;
+/** The installed tracker, or `null`. Exposed for tests and diagnostics. */
+declare function installedConversionTracker(): ConversionTracker | null;
+/**
+ * Tear the auto-installed tracker down and clear the global flags.
  *
- * Sites bump `@duffcloudservices/cms` independently of server deploys, so this
- * client must accept BOTH shapes and stay silent on the anonymous path — a
- * `console.error`/`console.warn` on every signed-out page load is exactly the
- * console-noise this fixes. A genuine signed-in visitor is returned as a
- * normalized `SiteVisitor`; anything else resolves to `null`.
+ * Exists for tests and for a site that genuinely needs to re-install with different
+ * options. Not part of the normal runtime path.
  */
+declare function resetConversionCapture(): void;
 /** A signed-in site visitor. */
 interface SiteVisitor {
@@ -507,6 +837,14 @@ interface SiteVisitorSessionResult {
     visitor: SiteVisitor | null;
     /** Convenience flag — `true` iff a visitor is present. */
     authenticated: boolean;
+    /**
+     * `true` when the probe did not reach the platform API at all — the response carried a
+     * non-JSON body (C-298 layer 2), i.e. this host does not route `/api/v1/*` to the API.
+     * Distinct from an ordinary signed-out visit: a site can render "sign-in temporarily
+     * unavailable" instead of a login button that cannot possibly work. Absent/`false` on
+     * every normal path, so existing consumers are unaffected.
+     */
+    apiUnreachable?: boolean;
 }
 interface FetchSiteVisitorSessionOptions {
     /** API base (default `/api/v1`, same-origin via Front Door). */
@@ -531,6 +869,11 @@ interface UseSiteVisitorSessionReturn {
     isAuthenticated: ComputedRef<boolean>;
     /** `true` while a probe is in flight. */
     isLoading: Ref<boolean>;
+    /**
+     * `true` when the last probe did not reach the platform API (non-JSON body — C-298
+     * layer 2). Render "sign-in unavailable" rather than a login button that cannot work.
+     */
+    apiUnreachable: Ref<boolean>;
     /** Re-run the probe. */
     refresh: () => Promise<void>;
 }
@@ -540,4 +883,4 @@ interface UseSiteVisitorSessionReturn {
  */
 declare function useSiteVisitorSession(options?: UseSiteVisitorSessionOptions): UseSiteVisitorSessionReturn;
-export { type DcsContentFile, type FetchSiteVisitorSessionOptions, GlobalSeoConfig, type MediaCarouselItem, type ReleaseNote, type ReleaseNotesReturn, type ReviewItem, type SiteVersionReturn, type SiteVisitor, type SiteVisitorSessionResult, type TextContentConfig, type TextContentReturn, type UseMediaCarouselConfig, type UseMediaCarouselReturn, type UseReviewContentConfig, type UseReviewContentReturn, UseSeoReturn, type UseSiteVisitorSessionOptions, type UseSiteVisitorSessionReturn, createSiteSEO, fetchSiteVisitorSession, useMediaCarousel, useReleaseNotes, useResponsiveImage, useReviewContent, useSEO, useSiteVersion, useSiteVisitorSession, useTextContent };
+export { CONVERSION_CAPTURE_VERSION, CONVERSION_INTERACTION_TYPES, type ConversionEvent, type ConversionInstallResult, type ConversionInstallSkipReason, type ConversionInteractionType, type ConversionSink, type ConversionTracker, type ConversionTrackingOptions, DEFAULT_BOOKING_HOSTS, DEFAULT_SOCIAL_HOSTS, type DcsContentFile, type FetchSiteVisitorSessionOptions, GlobalSeoConfig, type InstallConversionCaptureOptions, type MediaCarouselItem, type ReleaseNote, type ReleaseNotesReturn, type ReviewItem, type SiteVersionReturn, type SiteVisitor, type SiteVisitorSessionResult, type TextContentConfig, type TextContentReturn, type UseMediaCarouselConfig, type UseMediaCarouselReturn, type UseReviewContentConfig, type UseReviewContentReturn, UseSeoReturn, type UseSiteVisitorSessionOptions, type UseSiteVisitorSessionReturn, attachConversionSink, classifyHref, conversionOptedOut, createConversionTracker, createSiteSEO, doNotTrackEnabled, fetchSiteVisitorSession, hashTarget, hrefScheme, inFrame, installConversionCapture, installedConversionTracker, isConversionType, isSubmitControl, redactHref, resetConversionCapture, useConversionTracking, useMediaCarousel, useReleaseNotes, useResponsiveImage, useReviewContent, useSEO, useSiteVersion, useSiteVisitorSession, useTextContent };