@duffcloudservices/cms 0.13.0 → 0.13.2

package/dist/{installSeoHead-kWQwObez.d.ts → installSeoHead-EE0Z7UmK.d.ts}

@@ -1,4 +1,4 @@
-import { H as SeoConfiguration, x as BreadcrumbCrumb, z as ReviewSource, F as FaqSource, y as BlogMeta, T as ResolvedPageSeo, N as SeoSchemaConfig, G as GlobalSeoConfig, L as SeoOpenGraphConfig, M as SeoTwitterConfig } from './vitepressTransform-JG_zlaux.js';
+import { H as SeoConfiguration, x as BreadcrumbCrumb, z as ReviewSource, F as FaqSource, y as BlogMeta, T as ResolvedPageSeo, N as SeoSchemaConfig, G as GlobalSeoConfig, L as SeoOpenGraphConfig, M as SeoTwitterConfig } from './vitepressTransform-Ds5Hff8t.js';
 
 /**
  * Framework-agnostic SEO head-tag resolution.
@@ -229,6 +229,31 @@ declare function buildHeadTags(pageSlug: string, pagePath: string | undefined, s
  * VitePress `transformPageData` head emit) share one guard.
  */
 declare function escapeJsonLd(json: string): string;
+/**
+ * IS THIS META TAG OURS? — the SINGLE definition of the managed meta set.
+ *
+ * WHY THIS IS EXPORTED AND WHY IT MUST STAY THE ONLY COPY (C-603 / Q-453=A).
+ * `installSeoHead`'s DOM sweep removes the baked managed tags on the first
+ * matched in-app navigation, and "managed" there has to mean EXACTLY what it
+ * means here — this function is the build-time emitter's own answer, and the
+ * runtime sweep is its DOM twin. The named failure mode of the sweep-once
+ * design is precisely these two lists drifting: a tag the emitter starts baking
+ * later would strand again, quietly, because the sweep would not recognise it.
+ * A shared predicate makes that drift unrepresentable rather than merely
+ * discouraged.
+ *
+ * Both arguments are accepted (rather than one "identity" string) because a
+ * `<meta>` is keyed by `name` OR `property` and the two namespaces overlap:
+ * `og:*` is a property, `twitter:*` is a name.
+ */
+declare function isManagedMetaTag(name: string | null | undefined, property: string | null | undefined): boolean;
+/**
+ * IS THIS LINK OURS? — the SINGLE definition of the managed link set.
+ *
+ * `canonical` and `alternate` only. Stylesheets, preloads, icons and manifests
+ * belong to the app shell and are never touched by either sink.
+ */
+declare function isManagedLinkRel(rel: string | null | undefined): boolean;
 /**
  * Render the resolved head tags to a deterministic HTML fragment.
  * Order: title, meta (in the order produced by buildHeadTags), link, script.
@@ -325,7 +350,12 @@ declare function spliceHeadHtml(html: string, tags: ResolvedHeadTags): string;
  *       structurally (`name` unset, `matched` empty, path `/`) and skips at most
  *       ONE write, ever.
  *
- * MEASURED DEFECT F-A — **OPEN, AND IT BLOCKS FLEET ADOPTION** (C-362).
+ *   S6  THE BAKED MANAGED TAGS ARE SWEPT ONCE, ON THE FIRST MATCH. See DEFECT
+ *       F-A immediately below and `sweepBakedHeadTags.ts` for the four refusals
+ *       that make the sweep safe (JSON-LD and `<title>` unreachable; never
+ *       sweep a tag the runtime is about to declare; snapshot at install time).
+ *
+ * MEASURED DEFECT F-A — **CLOSED 2026-08-11 by SWEEP ONCE** (Q-453 = A, C-603).
  * The production-shaped fixture (`installSeoHead.integration.test.ts`) put a
  * REAL Unhead client (both 1.11.20 and 2.0.19) on a REAL baked document and
  * counted `document.head`. Two facts came out of it:
@@ -352,12 +382,23 @@ declare function spliceHeadHtml(html: string, tags: ResolvedHeadTags): string;
  *   was written by a PREVIOUS re-assert, Unhead owns it and drops it correctly,
  *   which is all a recording fake can ever model.
  *
- *   NO WORKAROUND IS APPLIED HERE ON PURPOSE. Every candidate fix — sweep the
- *   baked managed set once on first match, always emit every optional tag, or
- *   stop baking optional tags — changes the adoption contract, so this is an
- *   owner decision and not a patch. The fixture PINS the current behaviour with
- *   assertions named `DEFECT F-A`; flipping those two assertions is the
- *   acceptance test for whichever fix is chosen.
+ *   THE FIX, DECIDED BY THE OWNER RATHER THAN INVENTED HERE. Q-453 chose A —
+ *   SWEEP ONCE — over "always emit" (which structurally cannot fix hreflang or
+ *   `article:*`, and forks the shared `buildHeadTags` path) and "stop baking
+ *   optional tags" (the only crawler-VISIBLE option, and it changes them by
+ *   deletion). On the first MATCHED in-app navigation this module now removes
+ *   the baked managed tags the incoming input does not re-declare, so the
+ *   runtime owns the managed head from then on. The sweep lives in
+ *   `sweepBakedHeadTags.ts` and reuses the EMITTER'S OWN managed-set predicates
+ *   (`isManagedMetaTag` / `isManagedLinkRel` in `spliceHeadHtml.ts`) rather
+ *   than a second list, because the named residual of option A was those two
+ *   lists drifting apart.
+ *
+ *   Crawler-visible bytes are UNCHANGED: the sweep is reachable only from a
+ *   matched in-app navigation, and R5 already refuses to write for the fetched
+ *   document. The fixture's `DEFECT F-A` assertions (ITEM 2a / 2d, plus the
+ *   third instance in ITEM 8a) are flipped to the swept expectation, which was
+ *   the acceptance test this docstring named.
  *
  * WHAT IT RE-ASSERTS, AND WHAT IT DELIBERATELY DOES NOT.
  *   - `title`, `meta`, `link` — the managed fields P1 (`headHonesty.ts`) grades
@@ -508,6 +549,16 @@ interface SeoHeadResolution {
     reason: SeoHeadResolutionReason;
     /** The resolved `<title>`, or `null` when nothing was written. */
     title: string | null;
+    /**
+     * How many BAKED managed tags this navigation swept out of the DOM (S6).
+     *
+     * Non-zero on AT MOST ONE navigation per session — the first match, which
+     * spends the sweep latch — and `0` on every other, including every
+     * no-match / failed / initial resolution. Reported for the same reason
+     * `no-match` is: "it swept nothing" and "it never swept" must not look the
+     * same from the outside.
+     */
+    sweptBakedTags: number;
 }
 interface InstallSeoHeadOptions {
     /**
@@ -624,4 +675,4 @@ declare function buildSeoHeadRouteMap(routes: readonly SeoHeadPageRoute[]): Map<
  */
 declare function installSeoHead(router: SeoHeadRouterLike, options: InstallSeoHeadOptions): unknown;
 
-export { type SeoHeadRouteHasNoMeta as A, type HeadMetaTag as H, type InstallSeoHeadOptions as I, type ResolvedHeadTags as R, type SeoHeadRouterLike as S, generateOpenGraphMeta as a, buildHeadTags as b, generateTwitterMeta as c, renderHeadTags as d, stripManagedHeadTags as e, escapeJsonLd as f, generateJsonLd as g, buildSeoHeadRouteMap as h, installSeoHead as i, type HeadLinkTag as j, type HeadScriptTag as k, type HeadTagOverrides as l, type SeoHeadRouteLike as m, normalizeSeoHeadPath as n, type SeoHeadClientLike as o, type SeoHeadEntryLike as p, type SeoHeadInput as q, resolvePageSeo as r, spliceHeadHtml as s, type SeoHeadPageRoute as t, type SeoHeadPagesManifest as u, type SeoHeadResolution as v, type SeoHeadResolutionReason as w, findDuplicateNormalizedPaths as x, formatDuplicateNormalizedPaths as y, SEO_HEAD_ROUTE_HAS_NO_META as z };
+export { formatDuplicateNormalizedPaths as A, SEO_HEAD_ROUTE_HAS_NO_META as B, type SeoHeadRouteHasNoMeta as C, type HeadMetaTag as H, type InstallSeoHeadOptions as I, type ResolvedHeadTags as R, type SeoHeadRouterLike as S, generateOpenGraphMeta as a, buildHeadTags as b, generateTwitterMeta as c, renderHeadTags as d, stripManagedHeadTags as e, escapeJsonLd as f, generateJsonLd as g, isManagedLinkRel as h, isManagedMetaTag as i, installSeoHead as j, buildSeoHeadRouteMap as k, type HeadLinkTag as l, type HeadScriptTag as m, normalizeSeoHeadPath as n, type HeadTagOverrides as o, type SeoHeadRouteLike as p, type SeoHeadClientLike as q, resolvePageSeo as r, spliceHeadHtml as s, type SeoHeadEntryLike as t, type SeoHeadInput as u, type SeoHeadPageRoute as v, type SeoHeadPagesManifest as w, type SeoHeadResolution as x, type SeoHeadResolutionReason as y, findDuplicateNormalizedPaths as z };

package/dist/plugins/index.d.ts

@@ -1,6 +1,6 @@
 import { Plugin, HtmlTagDescriptor } from 'vite';
-import { D as DcsRobotsOptions, Y as SeoHonestyBlock, Z as PageRouteEntry, H as SeoConfiguration, E as ContentConfig } from '../vitepressTransform-JG_zlaux.js';
-export { C as CreateSeoTransformPageDataOptions, R as ResolvedPageOverrides, S as SeoPageContext, r as SeoPageTypeRule, t as VitePressHeadConfig, V as VitePressPageData, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute } from '../vitepressTransform-JG_zlaux.js';
+import { D as DcsRobotsOptions, Y as SeoHonestyBlock, Z as PageRouteEntry, H as SeoConfiguration, E as ContentConfig } from '../vitepressTransform-Ds5Hff8t.js';
+export { C as CreateSeoTransformPageDataOptions, R as ResolvedPageOverrides, S as SeoPageContext, r as SeoPageTypeRule, t as VitePressHeadConfig, V as VitePressPageData, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute } from '../vitepressTransform-Ds5Hff8t.js';
 import { H as HonestyMode } from '../headHonesty-OzxvLuwd.js';
 import { Component, Plugin as Plugin$1 } from 'vue';
 import MarkdownIt from 'markdown-it';

package/dist/plugins/index.js

@@ -1,5 +1,5 @@
-import { buildSitemapXml, isHandAuthoredRobotsAcceptable, buildRobotsTxt, buildLlmsTxt, routeExclusionReason, breadcrumbTrailFromRoute, findReviewItemsForPage, findBusinessLicense, buildHeadTags, spliceHeadHtml, routeToOutputFile, loadPagesManifest, hoistCharsetMeta, checkCharsetBudget, isBodyPrerenderEnabled, resolveHonestyMode, assertHeadHonestyExecuted, findHeadHonestyViolations, assertHeadHonesty, isRouteEmitted, findDuplicateNormalizedPaths, formatDuplicateNormalizedPaths, prerenderBodies, CharsetBudgetError, formatCharsetHeadroomWarning, dedupeUrls, collectEmittedUrlsFromFiles, classifyUrl, auditSameOriginAssets, checkRemoteAssets, auditCheckedTotal, EmittedUrlNotRunError, formatEmittedUrlAudit, formatEmittedUrlReport, EmittedUrlError } from '../chunk-HVSF23P7.js';
-export { buildVitePressSeoHead, createSeoTransformPageData, defaultRelativePathToRoute } from '../chunk-HVSF23P7.js';
+import { buildSitemapXml, isHandAuthoredRobotsAcceptable, buildRobotsTxt, buildLlmsTxt, routeExclusionReason, breadcrumbTrailFromRoute, findReviewItemsForPage, findBusinessLicense, buildHeadTags, spliceHeadHtml, routeToOutputFile, loadPagesManifest, hoistCharsetMeta, checkCharsetBudget, isBodyPrerenderEnabled, resolveHonestyMode, assertHeadHonestyExecuted, findHeadHonestyViolations, assertHeadHonesty, isRouteEmitted, findDuplicateNormalizedPaths, formatDuplicateNormalizedPaths, prerenderBodies, CharsetBudgetError, formatCharsetHeadroomWarning, dedupeUrls, collectEmittedUrlsFromFiles, classifyUrl, auditSameOriginAssets, checkRemoteAssets, auditCheckedTotal, EmittedUrlNotRunError, formatEmittedUrlAudit, formatEmittedUrlReport, EmittedUrlError } from '../chunk-64BUBTW7.js';
+export { buildVitePressSeoHead, createSeoTransformPageData, defaultRelativePathToRoute } from '../chunk-64BUBTW7.js';
 import fs5 from 'fs';
 import path5 from 'path';
 import yaml4 from 'js-yaml';

package/dist/seo/index.d.ts

@@ -1,10 +1,145 @@
-export { j as HeadLinkTag, H as HeadMetaTag, k as HeadScriptTag, l as HeadTagOverrides, I as InstallSeoHeadOptions, R as ResolvedHeadTags, z as SEO_HEAD_ROUTE_HAS_NO_META, o as SeoHeadClientLike, p as SeoHeadEntryLike, q as SeoHeadInput, t as SeoHeadPageRoute, u as SeoHeadPagesManifest, v as SeoHeadResolution, w as SeoHeadResolutionReason, A as SeoHeadRouteHasNoMeta, m as SeoHeadRouteLike, S as SeoHeadRouterLike, b as buildHeadTags, h as buildSeoHeadRouteMap, f as escapeJsonLd, x as findDuplicateNormalizedPaths, y as formatDuplicateNormalizedPaths, g as generateJsonLd, a as generateOpenGraphMeta, c as generateTwitterMeta, i as installSeoHead, n as normalizeSeoHeadPath, d as renderHeadTags, r as resolvePageSeo, s as spliceHeadHtml, e as stripManagedHeadTags } from '../installSeoHead-kWQwObez.js';
-import { Z as PageRouteEntry } from '../vitepressTransform-JG_zlaux.js';
-export { A as AI_BOTS, y as BlogMeta, x as BreadcrumbCrumb, v as BuildLlmsParams, u as BuildRobotsParams, B as BuildSitemapParams, E as ContentConfig, C as CreateSeoTransformPageDataOptions, D as DcsRobotsOptions, F as FaqSource, ac as NormalisedFaq, ab as NormalisedReview, R as ResolvedPageOverrides, ad as ReviewSchemaParts, z as ReviewSource, a2 as RouteEmissionRules, a3 as RouteExclusionReason, w as SchemaObject, S as SeoPageContext, r as SeoPageTypeRule, t as VitePressHeadConfig, V as VitePressPageData, q as absolutizeUrl, j as breadcrumbTrailFromRoute, k as buildBlogPosting, h as buildBreadcrumbList, l as buildFaqPage, g as buildGlobalGraph, a4 as buildHasCredential, f as buildLlmsTxt, m as buildReviewSchemaParts, e as buildRobotsTxt, a as buildSitemapXml, b as buildVitePressSeoHead, c as createSeoTransformPageData, d as defaultRelativePathToRoute, a8 as deriveSameAs, o as filterRealFaq, n as filterRealReviews, a7 as findBusinessLicense, a5 as findLocalBusinessSchema, p as findReviewItemsForPage, a6 as graphAbsorbs, a9 as graphIds, aa as isLocalBusinessType, a0 as isRouteEmitted, i as isRouteIndexable, _ as loadPagesManifest, $ as parsePagesManifest, a1 as routeExclusionReason, s as slugToTitle } from '../vitepressTransform-JG_zlaux.js';
+import { H as HeadMetaTag, l as HeadLinkTag } from '../installSeoHead-EE0Z7UmK.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-EE0Z7UmK.js';
+import { Z as PageRouteEntry } from '../vitepressTransform-Ds5Hff8t.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, ad as NormalisedFaq, ac as NormalisedReview, R as ResolvedPageOverrides, ae 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, a9 as deriveSameAs, o as filterRealFaq, n as filterRealReviews, a8 as findBusinessLicense, a6 as findGlobalSchemasOfType, a5 as findLocalBusinessSchema, p as findReviewItemsForPage, a7 as graphAbsorbs, aa as graphIds, ab as isLocalBusinessType, a0 as isRouteEmitted, i as isRouteIndexable, _ as loadPagesManifest, $ as parsePagesManifest, a1 as routeExclusionReason, s as slugToTitle } from '../vitepressTransform-Ds5Hff8t.js';
 import { a as HeadObservation } from '../headHonesty-OzxvLuwd.js';
 export { B as BakedHead, g as HeadHonestyError, l as HeadHonestyExecution, k as HeadHonestyNotRunError, p as HeadHonestyOptions, o as HeadHonestyViolation, H as HonestyMode, m as HonestyModeInput, b as assertHeadHonesty, h as assertHeadHonestyExecuted, d as decodeHtmlEntities, e as extractBakedHead, i as findHeadHonestyExecutionFaults, f as findHeadHonestyViolations, j as formatHeadHonestyExecutionReport, c as formatHeadHonestyReport, n as normalizeHeadText, r as resolveHonestyMode } from '../headHonesty-OzxvLuwd.js';
 import 'vue';
 
+/**
+ * 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.
  *
@@ -910,4 +1045,4 @@ declare class CharsetBudgetError extends Error {
  */
 declare function formatCharsetHeadroomWarning(file: string, result: CharsetBudgetResult, warnBelow?: number): string | null;
 
-export { type BodyPrerenderEnableInput, BodyPrerenderError, CANONICAL_CHARSET_META, CHARSET_BUDGET_BYTES, CHARSET_HEADROOM_WARN_BYTES, CharsetBudgetError, type CharsetBudgetResult, type ClassifiedUrl, type EmittedUrl, type EmittedUrlAudit, EmittedUrlError, EmittedUrlNotRunError, type EmittedUrlViolation, type EmittedUrlWarning, type FilteredRoute, type ForeignWriterSite, HeadContractError, type HeadContractExemptionAudit, type HeadContractExemptionCheck, type HeadContractExemptionExpectation, type HeadContractExemptionRecord, type HeadContractExemptionValue, type HeadContractExemptionVerdict, type HeadContractHostProbe, type HeadContractInput, type HeadContractMode, type HeadContractReport, type HeadContractSeoConfig, type HeadContractSourceFile, type HeadContractViolation, type HeadContractViolationCode, type HeadContractWarning, type HeadContractWarningCode, HeadObservation, MIN_EXEMPTION_REASON_LENGTH, PageRouteEntry, type PrerenderBodiesParams, type PrerenderBodiesResult, type PrerenderFilterReason, type RemoteCheckOptions, type RemoteCheckResult, type RenderedHead, type RenderedRoute, type RouteRenderer, type SameOriginAuditResult, type UrlExpectation, type UrlLocality, assertHeadContract, auditCheckedTotal, auditExemptionHosts, auditHeadContract, auditSameOriginAssets, blankComments, checkCharsetBudget, checkRemoteAssets, checkSameOriginAssets, classifyUrl, collectUrlsFromHtml, collectUrlsFromLlmsTxt, collectUrlsFromSitemap, dedupeUrls, findCharsetByteOffset, formatCharsetHeadroomWarning, formatEmittedUrlAudit, formatEmittedUrlReport, formatExemptionAudit, formatHeadContractReport, hoistCharsetMeta, hostsNamedIn, isBodyPrerenderEnabled, normalizeExemption, parseHostProbeHtml, prerenderBodies, routeToOutputFile, spliceBodyHtml };
+export { type BodyPrerenderEnableInput, BodyPrerenderError, CANONICAL_CHARSET_META, CHARSET_BUDGET_BYTES, CHARSET_HEADROOM_WARN_BYTES, CharsetBudgetError, type CharsetBudgetResult, type ClassifiedUrl, type EmittedUrl, type EmittedUrlAudit, EmittedUrlError, EmittedUrlNotRunError, type EmittedUrlViolation, type EmittedUrlWarning, type FilteredRoute, type ForeignWriterSite, HeadContractError, type HeadContractExemptionAudit, type HeadContractExemptionCheck, type HeadContractExemptionExpectation, type HeadContractExemptionRecord, type HeadContractExemptionValue, type HeadContractExemptionVerdict, type HeadContractHostProbe, type HeadContractInput, type HeadContractMode, type HeadContractReport, type HeadContractSeoConfig, type HeadContractSourceFile, type HeadContractViolation, type HeadContractViolationCode, type HeadContractWarning, type HeadContractWarningCode, HeadLinkTag, HeadMetaTag, HeadObservation, MIN_EXEMPTION_REASON_LENGTH, PageRouteEntry, type PrerenderBodiesParams, type PrerenderBodiesResult, type PrerenderFilterReason, type RemoteCheckOptions, type RemoteCheckResult, type RenderedHead, type RenderedRoute, type RouteRenderer, type SameOriginAuditResult, type UrlExpectation, type UrlLocality, assertHeadContract, auditCheckedTotal, auditExemptionHosts, auditHeadContract, auditSameOriginAssets, blankComments, checkCharsetBudget, checkRemoteAssets, checkSameOriginAssets, classifyUrl, collectUrlsFromHtml, collectUrlsFromLlmsTxt, collectUrlsFromSitemap, dedupeUrls, findCharsetByteOffset, formatCharsetHeadroomWarning, formatEmittedUrlAudit, formatEmittedUrlReport, formatExemptionAudit, formatHeadContractReport, headInputIdentities, hoistCharsetMeta, hostsNamedIn, isBodyPrerenderEnabled, normalizeExemption, parseHostProbeHtml, prerenderBodies, routeToOutputFile, snapshotBakedManagedHeadTags, spliceBodyHtml, sweepBakedManagedHeadTags };

package/dist/seo/index.js

@@ -1,4 +1,4 @@
-export { HeadContractError, MIN_EXEMPTION_REASON_LENGTH, assertHeadContract, auditExemptionHosts, auditHeadContract, blankComments, formatExemptionAudit, formatHeadContractReport, hostsNamedIn, normalizeExemption, parseHostProbeHtml } from '../chunk-A5F4C72F.js';
-export { AI_BOTS, BodyPrerenderError, CANONICAL_CHARSET_META, CHARSET_BUDGET_BYTES, CHARSET_HEADROOM_WARN_BYTES, CharsetBudgetError, EmittedUrlError, EmittedUrlNotRunError, HeadHonestyError, HeadHonestyNotRunError, SEO_HEAD_ROUTE_HAS_NO_META, absolutizeUrl, assertHeadHonesty, assertHeadHonestyExecuted, auditCheckedTotal, auditSameOriginAssets, breadcrumbTrailFromRoute, buildBlogPosting, buildBreadcrumbList, buildFaqPage, buildGlobalGraph, buildHasCredential, buildHeadTags, buildLlmsTxt, buildReviewSchemaParts, buildRobotsTxt, buildSeoHeadRouteMap, buildSitemapXml, buildVitePressSeoHead, checkCharsetBudget, checkRemoteAssets, checkSameOriginAssets, classifyUrl, collectUrlsFromHtml, collectUrlsFromLlmsTxt, collectUrlsFromSitemap, createSeoTransformPageData, decodeHtmlEntities, dedupeUrls, defaultRelativePathToRoute, deriveSameAs, escapeJsonLd, extractBakedHead, filterRealFaq, filterRealReviews, findBusinessLicense, findCharsetByteOffset, findDuplicateNormalizedPaths, findHeadHonestyExecutionFaults, findHeadHonestyViolations, findLocalBusinessSchema, findReviewItemsForPage, formatCharsetHeadroomWarning, formatDuplicateNormalizedPaths, formatEmittedUrlAudit, formatEmittedUrlReport, formatHeadHonestyExecutionReport, formatHeadHonestyReport, generateJsonLd, generateOpenGraphMeta, generateTwitterMeta, graphAbsorbs, graphIds, hoistCharsetMeta, installSeoHead, isBodyPrerenderEnabled, isLocalBusinessType, isRouteEmitted, isRouteIndexable, loadPagesManifest, normalizeHeadText, normalizeSeoHeadPath, parsePagesManifest, prerenderBodies, renderHeadTags, resolveHonestyMode, resolvePageSeo, routeExclusionReason, routeToOutputFile, slugToTitle, spliceBodyHtml, spliceHeadHtml, stripManagedHeadTags } from '../chunk-HVSF23P7.js';
+export { HeadContractError, MIN_EXEMPTION_REASON_LENGTH, assertHeadContract, auditExemptionHosts, auditHeadContract, blankComments, formatExemptionAudit, formatHeadContractReport, hostsNamedIn, normalizeExemption, parseHostProbeHtml } from '../chunk-OGAJX4KM.js';
+export { AI_BOTS, BodyPrerenderError, CANONICAL_CHARSET_META, CHARSET_BUDGET_BYTES, CHARSET_HEADROOM_WARN_BYTES, CharsetBudgetError, EmittedUrlError, EmittedUrlNotRunError, HeadHonestyError, HeadHonestyNotRunError, SEO_HEAD_ROUTE_HAS_NO_META, absolutizeUrl, assertHeadHonesty, assertHeadHonestyExecuted, auditCheckedTotal, auditSameOriginAssets, breadcrumbTrailFromRoute, buildBlogPosting, buildBreadcrumbList, buildFaqPage, buildGlobalGraph, buildHasCredential, buildHeadTags, buildLlmsTxt, buildReviewSchemaParts, buildRobotsTxt, buildSeoHeadRouteMap, buildSitemapXml, buildVitePressSeoHead, checkCharsetBudget, checkRemoteAssets, checkSameOriginAssets, classifyUrl, collectUrlsFromHtml, collectUrlsFromLlmsTxt, collectUrlsFromSitemap, createSeoTransformPageData, decodeHtmlEntities, dedupeUrls, defaultRelativePathToRoute, deriveSameAs, escapeJsonLd, extractBakedHead, filterRealFaq, filterRealReviews, findBusinessLicense, findCharsetByteOffset, findDuplicateNormalizedPaths, findGlobalSchemasOfType, findHeadHonestyExecutionFaults, findHeadHonestyViolations, findLocalBusinessSchema, findReviewItemsForPage, formatCharsetHeadroomWarning, formatDuplicateNormalizedPaths, formatEmittedUrlAudit, formatEmittedUrlReport, formatHeadHonestyExecutionReport, formatHeadHonestyReport, generateJsonLd, generateOpenGraphMeta, generateTwitterMeta, graphAbsorbs, graphIds, headInputIdentities, hoistCharsetMeta, installSeoHead, isBodyPrerenderEnabled, isLocalBusinessType, isManagedLinkRel, isManagedMetaTag, isRouteEmitted, isRouteIndexable, loadPagesManifest, normalizeHeadText, normalizeSeoHeadPath, parsePagesManifest, prerenderBodies, renderHeadTags, resolveHonestyMode, resolvePageSeo, routeExclusionReason, routeToOutputFile, slugToTitle, snapshotBakedManagedHeadTags, spliceBodyHtml, spliceHeadHtml, stripManagedHeadTags, sweepBakedManagedHeadTags } from '../chunk-64BUBTW7.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{vitepressTransform-JG_zlaux.d.ts → vitepressTransform-Ds5Hff8t.d.ts}

@@ -426,8 +426,20 @@ declare function findLocalBusinessSchema(global: GlobalSeoConfig): {
  * `Organization` / `WebSite` (the graph emits cross-linked versions of both).
  *
  * Shared by both emit paths so the de-dup rule is identical.
+ *
+ * INVARIANT (C-609): every schema this returns `true` for must be ABSORBED by
+ * `buildGlobalGraph` — its hand-authored properties merged into the corresponding
+ * `@graph` node. Absorbing here without merging there is silent data loss: the
+ * node is stripped from the per-schema emission and its properties never reach
+ * the crawler (the C-418 defect this pairing now prevents).
  */
 declare function graphAbsorbs(schema: SeoSchemaConfig, global: GlobalSeoConfig): boolean;
+/**
+ * All hand-authored `global.schemas` entries of an exact `@type`, in document
+ * order. Plural because `graphAbsorbs` absorbs EVERY `Organization` / `WebSite`
+ * entry — so the graph must merge every one of them or the extras vanish.
+ */
+declare function findGlobalSchemasOfType(global: GlobalSeoConfig, type: string): SeoSchemaConfig[];
 /** One normalised, REAL review (passed the honesty gate). */
 interface NormalisedReview {
     rating: number;
@@ -489,10 +501,22 @@ declare function buildHasCredential(license: string | undefined): SchemaObject |
  * `global.siteName` / `global.siteUrl` / `global.images.logo` / `global.social`.
  * Requires NO new YAML.
  *
- * The LocalBusiness node ABSORBS the existing `global.schemas[*]` LocalBusiness
- * subtype (its NAP/geo/hours/offers are preserved verbatim) and is promoted with
- * an `@id`; honest `review` + `aggregateRating` and a `hasCredential` license are
- * merged in when supplied.
+ * ALL THREE nodes ABSORB their hand-authored `global.schemas[*]` counterpart
+ * (C-609) — the properties are merged onto the derived node rather than
+ * discarded, which is what makes the baked `@graph` a true SUPERSET of the
+ * runtime per-schema emission that `graphAbsorbs` suppresses:
+ *
+ *   • LocalBusiness — its NAP/geo/hours/offers are preserved verbatim and the
+ *     node is promoted with an `@id`; honest `review` + `aggregateRating` and a
+ *     `hasCredential` license are merged in when supplied.
+ *   • Organization — e.g. the fleet default's hand-authored `logo`, which
+ *     `global.images.logo` does not set.
+ *   • WebSite — e.g. a `description` or a `potentialAction` SearchAction.
+ *
+ * Precedence is uniform: hand-authored properties OVERRIDE the derived value for
+ * the same key and ADD any key the graph does not derive, except the identity
+ * keys (`@type`, `@id`) and the spine's cross-links (`publisher`,
+ * `parentOrganization`), which the graph always owns so the `@id` refs resolve.
  *
  * Returns `[]` when there is no `siteUrl` (no stable `@id` anchor possible), so
  * the existing per-schema emission is left untouched for un-configured sites.
@@ -1120,4 +1144,4 @@ declare function buildVitePressSeoHead(pageData: VitePressPageData, options: Cre
  */
 declare function createSeoTransformPageData(options: CreateSeoTransformPageDataOptions): (pageData: VitePressPageData) => void;
 
-export { parsePagesManifest as $, AI_BOTS as A, type BuildSitemapParams as B, type CreateSeoTransformPageDataOptions as C, type DcsRobotsOptions as D, type ContentConfig as E, type FaqSource as F, type GlobalSeoConfig as G, type SeoConfiguration as H, type SeoAuthorConfig as I, type SeoSocialConfig as J, type SeoImagesConfig as K, type SeoOpenGraphConfig as L, type SeoTwitterConfig as M, type SeoSchemaConfig as N, type SeoAlternateConfig as O, type PageSeoConfig as P, type SeoVerificationConfig as Q, type ResolvedPageOverrides as R, type SeoPageContext as S, type ResolvedPageSeo as T, type UseSeoReturn as U, type VitePressPageData as V, type UseSeoConfig as W, type HeadOverrides as X, type SeoHonestyBlock as Y, type PageRouteEntry as Z, loadPagesManifest as _, buildSitemapXml as a, isRouteEmitted as a0, routeExclusionReason as a1, type RouteEmissionRules as a2, type RouteExclusionReason as a3, buildHasCredential as a4, findLocalBusinessSchema as a5, graphAbsorbs as a6, findBusinessLicense as a7, deriveSameAs as a8, graphIds as a9, isLocalBusinessType as aa, type NormalisedReview as ab, type NormalisedFaq as ac, type ReviewSchemaParts as ad, buildVitePressSeoHead as b, createSeoTransformPageData as c, defaultRelativePathToRoute as d, buildRobotsTxt as e, buildLlmsTxt as f, buildGlobalGraph as g, buildBreadcrumbList as h, isRouteIndexable as i, breadcrumbTrailFromRoute as j, buildBlogPosting as k, buildFaqPage as l, buildReviewSchemaParts as m, filterRealReviews as n, filterRealFaq as o, findReviewItemsForPage as p, absolutizeUrl as q, type SeoPageTypeRule as r, slugToTitle as s, type VitePressHeadConfig as t, type BuildRobotsParams as u, type BuildLlmsParams as v, type SchemaObject as w, type BreadcrumbCrumb as x, type BlogMeta as y, type ReviewSource as z };
+export { parsePagesManifest as $, AI_BOTS as A, type BuildSitemapParams as B, type CreateSeoTransformPageDataOptions as C, type DcsRobotsOptions as D, type ContentConfig as E, type FaqSource as F, type GlobalSeoConfig as G, type SeoConfiguration as H, type SeoAuthorConfig as I, type SeoSocialConfig as J, type SeoImagesConfig as K, type SeoOpenGraphConfig as L, type SeoTwitterConfig as M, type SeoSchemaConfig as N, type SeoAlternateConfig as O, type PageSeoConfig as P, type SeoVerificationConfig as Q, type ResolvedPageOverrides as R, type SeoPageContext as S, type ResolvedPageSeo as T, type UseSeoReturn as U, type VitePressPageData as V, type UseSeoConfig as W, type HeadOverrides as X, type SeoHonestyBlock as Y, type PageRouteEntry as Z, loadPagesManifest as _, buildSitemapXml as a, isRouteEmitted as a0, routeExclusionReason as a1, type RouteEmissionRules as a2, type RouteExclusionReason as a3, buildHasCredential as a4, findLocalBusinessSchema as a5, findGlobalSchemasOfType as a6, graphAbsorbs as a7, findBusinessLicense as a8, deriveSameAs as a9, graphIds as aa, isLocalBusinessType as ab, type NormalisedReview as ac, type NormalisedFaq as ad, type ReviewSchemaParts as ae, buildVitePressSeoHead as b, createSeoTransformPageData as c, defaultRelativePathToRoute as d, buildRobotsTxt as e, buildLlmsTxt as f, buildGlobalGraph as g, buildBreadcrumbList as h, isRouteIndexable as i, breadcrumbTrailFromRoute as j, buildBlogPosting as k, buildFaqPage as l, buildReviewSchemaParts as m, filterRealReviews as n, filterRealFaq as o, findReviewItemsForPage as p, absolutizeUrl as q, type SeoPageTypeRule as r, slugToTitle as s, type VitePressHeadConfig as t, type BuildRobotsParams as u, type BuildLlmsParams as v, type SchemaObject as w, type BreadcrumbCrumb as x, type BlogMeta as y, type ReviewSource as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duffcloudservices/cms",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Vue 3 composables and Vite plugins for DCS CMS integration",
   "type": "module",
   "exports": {
@@ -58,7 +58,7 @@
   },
   "dependencies": {
     "js-yaml": "^4.1.0",
-    "@duffcloudservices/cms-core": "0.8.0"
+    "@duffcloudservices/cms-core": "0.8.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/components/PreviewRibbon.vue

@@ -84,9 +84,18 @@
 </template>
 
 <script setup lang="ts">
-import { platformFetch } from '@duffcloudservices/cms-core'
 import { ref, computed, onMounted, onBeforeUnmount, watch } from 'vue'
 
+/*
+ * NO cms-core VALUE imports in this file. The `./components` export ships RAW SFC
+ * source (tsup builds no .vue), so consumer sites type-check this file directly —
+ * and cms-core is a transitive dep pnpm's strict layout never exposes to them.
+ * A value import here is TS2307 in every fleet site's type-check gate (measured on
+ * the 0.13.0 canary, 2026-08-10; kept/boogie-babies/bryans/mi-handyman all red).
+ * `import type` is erased and safe. The C-298 layer-2 guard this file needs from
+ * platformFetch is inlined below at its single call site instead.
+ */
+
 /* ------------------------------------------------------------------ */
 /*  Props                                                              */
 /* ------------------------------------------------------------------ */
@@ -235,15 +244,22 @@ onMounted(async () => {
     const base =
       (import.meta.env as Record<string, string | undefined>)
         .VITE_API_BASE_URL ?? 'https://portal.duffcloudservices.com'
-    // C-298 layer 2: the `catch { /* non-critical */ }` below is a swallow site; the
-    // wrapper's console error is what makes an HTML body visible at all here.
-    const res = await platformFetch(
-      `${base}/api/v1/release-notes/latest`,
-      { headers: { Accept: 'application/json' } },
-    )
+    // C-298 layer 2, INLINED (see the no-cms-core-value-imports note at the top of
+    // this <script>): the `catch { /* non-critical */ }` below is a swallow site, so
+    // a non-JSON (HTML-shell) body must go LOUD here before it can be swallowed.
+    const url = `${base}/api/v1/release-notes/latest`
+    const res = await fetch(url, { headers: { Accept: 'application/json' } })
     if (res.ok) {
-      const data = await res.json()
-      if (data.version) resolvedVersion.value = data.version
+      const ct = res.headers?.get?.('content-type') ?? ''
+      if (!/\bjson\b/i.test(ct)) {
+        console.error(
+          `[dcs-cms] PreviewRibbon: ${url} returned content-type "${ct}" — ` +
+            'an HTML body here means a platform misroute (C-298); refusing to parse it.',
+        )
+      } else {
+        const data = await res.json()
+        if (data.version) resolvedVersion.value = data.version
+      }
     }
   } catch {
     /* non-critical */

package/src/components/ResponsiveImage.test.ts

@@ -45,3 +45,48 @@ describe('ResponsiveImage self-healing fallback', () => {
     expect(wrapper.find('img').attributes('src')).toBe(ORIGINAL)
   })
 })
+
+describe('ResponsiveImage source-fit variants (C-804 / Q-561=A)', () => {
+  it('omits variants wider than the source once width/height are supplied', () => {
+    // The iron-oak banner shape: a 1024x212 source must stop advertising 1920w.
+    const wrapper = mount(ResponsiveImage, {
+      props: { src: ORIGINAL, alt: 'Banner', context: 'hero', width: 1024, height: 212 },
+    })
+
+    const srcset = wrapper.find('source').attributes('srcset')!
+    expect(srcset).toContain('abc-123-sm.webp 640w')
+    expect(srcset).toContain('abc-123-md.webp 1024w')
+    expect(srcset).not.toContain('-lg.webp')
+    expect(srcset).not.toContain('1920w')
+
+    const img = wrapper.find('img')
+    expect(img.attributes('src')).toContain('abc-123-md.webp')
+    // The same props also feed the pre-existing CLS hint, which this component
+    // could not emit at all before it grew width/height.
+    expect(img.attributes('width')).toBe('1024')
+    expect(img.attributes('height')).toBe('212')
+  })
+
+  it('re-points the <img> fallback when the source is narrower than -md', () => {
+    const wrapper = mount(ResponsiveImage, {
+      props: { src: ORIGINAL, alt: 'Narrow', context: 'content', width: 800 },
+    })
+
+    expect(wrapper.find('source').attributes('srcset')).toBe(
+      'https://files.duffcloudservices.com/kept/assets/hero/abc-123-sm.webp 640w'
+    )
+    expect(wrapper.find('img').attributes('src')).toContain('abc-123-sm.webp')
+  })
+
+  it('is byte-for-byte unchanged when no width is supplied', () => {
+    const wrapper = mount(ResponsiveImage, {
+      props: { src: ORIGINAL, alt: 'Hero', context: 'hero' },
+    })
+
+    expect(wrapper.find('source').attributes('srcset')).toBe(
+      'https://files.duffcloudservices.com/kept/assets/hero/abc-123-sm.webp 640w, ' +
+        'https://files.duffcloudservices.com/kept/assets/hero/abc-123-md.webp 1024w, ' +
+        'https://files.duffcloudservices.com/kept/assets/hero/abc-123-lg.webp 1920w'
+    )
+  })
+})

package/src/components/ResponsiveImage.vue

@@ -32,6 +32,16 @@ const props = defineProps<{
   sizes?: string
   /** Skip responsive variants and use the original URL only. */
   original?: boolean
+  /**
+   * Intrinsic pixel width of the SOURCE image. Two effects (both opt-in — with
+   * no `width` the rendered markup is unchanged):
+   *  - C-804 source-fit srcset: variants wider than the source are omitted, so
+   *    a narrow banner stops advertising a width it cannot deliver.
+   *  - paired with `height`, emits the `<img width>/<img height>` CLS hint.
+   */
+  width?: number
+  /** Intrinsic pixel height of the source image. See `width`. */
+  height?: number
 }>()
 
 const image = useResponsiveImage({
@@ -40,6 +50,8 @@ const image = useResponsiveImage({
   context: () => props.context ?? 'content',
   sizes: () => props.sizes,
   original: () => props.original,
+  width: () => props.width,
+  height: () => props.height,
 })
 
 // Self-heal: when the rendered fit-variant (`-md`/`-lg`) 404s — legitimately

package/src/components/raw-source-imports.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The `./components` export ships RAW SFC source (tsup builds no .vue), so every
+ * consumer site type-checks these files directly — against a dependency tree where
+ * cms-core is TRANSITIVE and pnpm's strict layout never exposes it. A VALUE import
+ * of cms-core in any raw-shipped .vue is therefore TS2307 in every fleet site's
+ * type-check gate, invisible to this package's own checks (cms-core resolves fine
+ * HERE — that is exactly why only a consumer-shaped gate or this test can see it).
+ *
+ * Measured on the 0.13.0 canary (2026-08-10): one value import in PreviewRibbon.vue
+ * would have redded CI on kept (the payer), boogie-babies, bryans and mi-handyman.
+ * `import type` is erased at compile time and stays allowed.
+ */
+describe('raw-source .vue exports must not value-import cms-core', () => {
+  const dir = __dirname
+  const vueFiles = readdirSync(dir).filter((f) => f.endsWith('.vue'))
+
+  it('finds the raw-shipped component set (non-vacuity)', () => {
+    expect(vueFiles.length).toBeGreaterThan(0)
+    expect(vueFiles).toContain('PreviewRibbon.vue')
+  })
+
+  for (const file of vueFiles) {
+    it(`${file} has no cms-core value import`, () => {
+      const src = readFileSync(join(dir, file), 'utf8')
+      const valueImports = Array.from(src.matchAll(/^\s*import\s+(?!type\b)[^;'"]*['"]@duffcloudservices\/cms-core['"]/gm))
+      expect(
+        valueImports.map((m) => m[0].trim()),
+        `${file} value-imports cms-core — this ships as raw source and breaks every consumer site's type-check (see header comment)`,
+      ).toEqual([])
+    })
+  }
+
+  it('kill-test: the guard regex catches the 0.13.0 defect shape', () => {
+    const bad = "import { platformFetch } from '@duffcloudservices/cms-core'"
+    const good = "import type { PlatformFetchOptions } from '@duffcloudservices/cms-core'"
+    const re = /^\s*import\s+(?!type\b)[^;'"]*['"]@duffcloudservices\/cms-core['"]/gm
+    expect(Array.from(bad.matchAll(re)).length).toBe(1)
+    expect(Array.from(good.matchAll(re)).length).toBe(0)
+  })
+})