@duffcloudservices/cms 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -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.
  */
 
 /**
@@ -427,6 +432,10 @@ interface UseResponsiveImageOptions {
     sizes?: MaybeRefOrGetter<string | undefined>;
     /** Skip variant resolution and use the original URL only. */
     original?: MaybeRefOrGetter<boolean | undefined>;
+    /** Intrinsic width — emitted as a layout-shift hint when paired with `height`. */
+    width?: MaybeRefOrGetter<number | undefined>;
+    /** Intrinsic height — emitted as a layout-shift hint when paired with `width`. */
+    height?: MaybeRefOrGetter<number | undefined>;
 }
 /**
  * Reactively resolves responsive image metadata for a DCS CDN URL.
@@ -473,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 {
@@ -503,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). */
@@ -527,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>;
 }
@@ -536,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 };