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

@duffcloudservices/cms 0.12.0 → 0.13.1

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 (40) 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 +25 -6
package/src/components/raw-source-imports.test.ts +44 -0
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/installSeoHead-kWQwObez.d.ts ADDED Viewed

@@ -0,0 +1,627 @@
+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';
+/**
+ * Framework-agnostic SEO head-tag resolution.
+ *
+ * This module is the single source of truth for turning a
+ * (`pageSlug`, `pagePath`, `SeoConfiguration`) triple into a plain,
+ * serialisable description of the `<head>` tags a page should carry:
+ * resolved title, meta[], link[], and JSON-LD script[].
+ *
+ * It is consumed by:
+ *   - `useSEO` (runtime, via `@unhead/vue`) — see `../composables/useSEO.ts`
+ *   - `dcsSeoPlugin`'s build-time static-HTML emitter — see
+ *     `../plugins/dcsSeoPlugin.ts`
+ *
+ * Keeping the resolution here (rather than inside the Vue composable) means
+ * the runtime and the build-time emitter produce byte-identical tags from the
+ * same `seo.yaml`, with no Vue/unhead dependency required at build time.
+ *
+ * Runtime behaviour is intentionally identical to the previous in-composable
+ * logic **except** for one corrected bug: `og:title` now falls back to the
+ * fully-resolved (template-applied) page title instead of the raw, untemplated
+ * `page.title`. Previously `og:title` could diverge from the `<title>` element
+ * (e.g. `<title>Iron Oak Contractors | Our Services</title>` but
+ * `og:title = "Our Services"`).
+ */
+/** A `<meta>` tag — either a `name=`/`content=` or `property=`/`content=` pair. */
+interface HeadMetaTag {
+    name?: string;
+    property?: string;
+    content: string;
+}
+/** A `<link>` tag (canonical, alternate, etc.). */
+interface HeadLinkTag {
+    rel: string;
+    href: string;
+    hreflang?: string;
+}
+/** A `<script type="application/ld+json">` tag carrying serialised JSON-LD. */
+interface HeadScriptTag {
+    type: string;
+    /** Pre-serialised JSON-LD string (already `JSON.stringify`-ed). */
+    children: string;
+}
+/**
+ * The complete, framework-agnostic set of resolved `<head>` tags for a page.
+ *
+ * - `title` is the final, template-applied title (what goes in `<title>`).
+ * - `meta` covers description, keywords, robots, verification, OG, Twitter.
+ * - `link` covers canonical + hreflang alternates.
+ * - `script` covers JSON-LD (global + page schemas).
+ * - `jsonLd` is the same JSON-LD as parsed objects, for callers that want the
+ *   structured form (e.g. `useSEO().getSchema()`).
+ */
+interface ResolvedHeadTags {
+    title: string;
+    meta: HeadMetaTag[];
+    link: HeadLinkTag[];
+    script: HeadScriptTag[];
+    jsonLd: object[];
+    /** The fully-resolved page SEO (merged global + page) used to build tags. */
+    resolved: ResolvedPageSeo;
+}
+/** Optional overrides applied on top of the resolved config when building tags. */
+interface HeadTagOverrides {
+    /** Override the resolved `<title>`. */
+    title?: string;
+    /**
+     * Page-specific title fallback used when `seo.yaml` has no `title` for this
+     * page (e.g. the route `title` from `pages.yaml`). Unlike `global.defaultTitle`
+     * this IS run through `titleTemplate`, so un-configured routes (blog posts,
+     * etc.) get unique titles rather than the global default.
+     */
+    fallbackTitle?: string;
+    /** Override the resolved meta description. */
+    description?: string;
+    /** Override the meta keywords value. */
+    keywords?: string;
+    /**
+     * Force the robots directive (e.g. `'noindex, nofollow'`). When supplied this
+     * wins over both page- and global-level robots.
+     */
+    robots?: string;
+    /** Replace the JSON-LD schema objects entirely (already-built objects). */
+    schemas?: object[];
+    /** Extra meta tags appended after the generated ones. */
+    meta?: HeadMetaTag[];
+    /**
+     * Emit a `<meta name="keywords">` tag from the page's `keywords` field.
+     *
+     * Defaults to `false` so the `useSEO` runtime path stays byte-identical to
+     * its historical output (which never emitted keywords). The static-HTML
+     * emitter opts in (`true`) to surface page keywords in the baked `<head>`.
+     */
+    includeKeywords?: boolean;
+    /**
+     * Emit the global `@graph` spine (Organization + WebSite + the promoted
+     * LocalBusiness node, cross-linked by `@id`) PREPENDED before the per-schema
+     * JSON-LD. When true, the LocalBusiness subtype already present in
+     * `global.schemas` is ABSORBED into the graph (not emitted a second time).
+     * Default `false`.
+     */
+    emitGraph?: boolean;
+    /**
+     * Ordered Home → … → current breadcrumb trail (absolute item URLs). When it
+     * has more than one hop a `BreadcrumbList` is emitted; the home page (≤ 1 hop)
+     * emits none.
+     */
+    breadcrumbTrail?: BreadcrumbCrumb[];
+    /**
+     * REAL review items (from `.dcs/content.yaml`) for the LocalBusiness node.
+     * Honest Review[] + aggregateRating are emitted ONLY for items with a numeric
+     * rating + non-empty text + authorName; empty/missing ⇒ nothing.
+     */
+    reviews?: ReviewSource[];
+    /**
+     * Free-text trade/occupational license (from the `business.license`
+     * content.yaml key). When non-empty a `hasCredential`
+     * (`EducationalOccupationalCredential`, `credentialCategory: "license"`) is
+     * added to the LocalBusiness node in the `@graph`; empty/missing ⇒ nothing.
+     * Only consulted when `emitGraph` is true.
+     */
+    license?: string;
+    /**
+     * Structured FAQ pairs (frontmatter `faq:` / `.dcs/faq.yaml`). A `FAQPage` is
+     * emitted ONLY when at least one entry has a non-empty question AND answer.
+     */
+    faq?: FaqSource[];
+    /**
+     * Blog-post metadata. When `headline` is present a `BlogPosting` is emitted —
+     * UNLESS the page's own schemas already hand-author a `BlogPosting` (then the
+     * builder defers to the authored copy to avoid duplication).
+     */
+    blogMeta?: BlogMeta;
+}
+/**
+ * Generate Open Graph meta tags from config.
+ *
+ * @param resolvedTitle - the final, template-applied page title. Used as the
+ *   `og:title` fallback so OG stays consistent with `<title>`.
+ */
+declare function generateOpenGraphMeta(og: SeoOpenGraphConfig, global: GlobalSeoConfig, resolvedTitle: string, pageDescription: string, canonical: string): Array<{
+    property: string;
+    content: string;
+}>;
+/**
+ * Generate Twitter Card meta tags from config.
+ *
+ * @param resolvedTitle - the final, template-applied page title (Twitter title
+ *   fallback), mirroring the OG behaviour.
+ */
+declare function generateTwitterMeta(twitter: SeoTwitterConfig, global: GlobalSeoConfig, resolvedTitle: string, pageDescription: string): Array<{
+    name: string;
+    content: string;
+}>;
+/**
+ * Generate JSON-LD schema objects from schema configs, auto-populating common
+ * WebSite properties from global config.
+ */
+declare function generateJsonLd(schemas: SeoSchemaConfig[], global: GlobalSeoConfig): object[];
+/**
+ * Resolve page SEO by merging global defaults with page-specific config.
+ *
+ * Behavioural changes from the historical in-composable version (both bug
+ * fixes):
+ *   1. `openGraph.title` falls back to the **template-applied** page title, not
+ *      the raw `page.title`, so `og:title` matches `<title>`.
+ *   2. The `titleTemplate` is applied **only** to a page-specific title
+ *      (`page.title`, or the `fallbackTitle` arg). It is no longer applied to
+ *      `global.defaultTitle`, which is already the complete brand title —
+ *      templating it produced `"Brand | Default Title | Brand"` doubling on any
+ *      page without its own `seo.yaml` entry.
+ *
+ * @param fallbackTitle - a page-specific title to use when `seo.yaml` has no
+ *   `title` for this page (e.g. the route `title` from `pages.yaml`). It IS run
+ *   through `titleTemplate`; `global.defaultTitle` is the last resort and is not.
+ */
+declare function resolvePageSeo(pageSlug: string, pagePath: string | undefined, seoConfig: SeoConfiguration | undefined, fallbackTitle?: string): ResolvedPageSeo;
+/**
+ * Build the complete, framework-agnostic set of `<head>` tags for a page.
+ *
+ * This is the function both the `useSEO` runtime and the build-time emitter
+ * call, guaranteeing identical output. Pass `overrides` to mirror the
+ * composable's `applyHead(overrides)` behaviour, or to force `robots` (used by
+ * the emitter's `noindex` option).
+ */
+declare function buildHeadTags(pageSlug: string, pagePath: string | undefined, seoConfig: SeoConfiguration | undefined, overrides?: HeadTagOverrides): ResolvedHeadTags;
+/**
+ * Pure, framework-free `<head>` splicing for the build-time SEO emitter.
+ *
+ * Given a built `index.html` shell and a set of resolved head tags (from
+ * `buildHeadTags`), this produces a new HTML string where the SEO-managed
+ * tags — `<title>`, `description`, `keywords`, `robots`, `canonical`,
+ * verification, all `og:*` / `article:*` properties, all `twitter:*` names,
+ * and `application/ld+json` scripts — have been **replaced** (not duplicated)
+ * with the resolved set.
+ *
+ * Design goals:
+ *   - **Idempotent**: running it twice yields the same output (it strips the
+ *     managed tags first, then re-inserts the canonical set).
+ *   - **Deterministic**: tag order is fixed by `renderHeadTags`.
+ *   - **Conservative**: only tags we own are touched. Charset, viewport, CSP,
+ *     theme-color, favicons, stylesheets, and the app script are left intact.
+ *
+ * This is intentionally regex-based (no DOM dependency) to mirror the existing
+ * `dcsCdnImagePlugin` post-build HTML rewriting and to keep the emitter free of
+ * heavy parser deps at build time.
+ */
+/**
+ * Escape a JSON-LD string for safe inclusion inside an HTML `<script>` element.
+ *
+ * A `<script type="application/ld+json">` is a DATA block, but the HTML parser
+ * still scans its raw text for `</script` (and `<!--`) — so untrusted CMS free
+ * text (review bodies, FAQ Q&A, blog descriptions) carrying `</script>` could
+ * break out of the script and inject markup (stored XSS).
+ *
+ * Per OWASP "JSON in an HTML context", we escape the three HTML-significant
+ * characters as their `\uXXXX` JSON escapes. Because these characters only ever
+ * appear INSIDE JSON string literals (never as JSON structure), the result is
+ * still byte-for-byte valid JSON that `JSON.parse` round-trips:
+ *   `<` → `<`  (defeats `</script>` and `<!--` breakout)
+ *   `>` → `>`
+ *   `&` → `&`
+ *
+ * Exported so BOTH static-SEO sinks (the SPA `spliceHeadHtml` path AND the
+ * VitePress `transformPageData` head emit) share one guard.
+ */
+declare function escapeJsonLd(json: string): string;
+/**
+ * Render the resolved head tags to a deterministic HTML fragment.
+ * Order: title, meta (in the order produced by buildHeadTags), link, script.
+ */
+declare function renderHeadTags(tags: ResolvedHeadTags, indent?: string): string;
+/**
+ * Strip the SEO-managed tags from a `<head>` block so they can be re-inserted
+ * without duplication. Operates only within `<head>...</head>` to avoid
+ * touching body content.
+ */
+declare function stripManagedHeadTags(html: string): string;
+/**
+ * Splice resolved SEO head tags into an HTML document.
+ *
+ * Strips the existing managed tags, then inserts the rendered canonical set
+ * immediately before `</head>`. If no `<head>` is present the HTML is returned
+ * unchanged (defensive — the emitter logs and no-ops in that case).
+ *
+ * Idempotent: applying twice produces identical output.
+ */
+declare function spliceHeadHtml(html: string, tags: ResolvedHeadTags): string;
+/**
+ * ROUTER-LEVEL HEAD RE-ASSERT (C-357 clause 4 — the COVERAGE half of the
+ * head-authority contract).
+ *
+ * WHAT PROBLEM THIS CLOSES. C-356 proved there is exactly ONE WRITER of the
+ * managed head fields (`.dcs/seo.yaml`). It did NOT prove every route re-asserts
+ * it. A view that writes no head at all is "silent": on a hard navigation it is
+ * CORRECT (the baked `<head>` of the fetched document is the approved one and
+ * nothing overwrites it), but on the first in-app click it leaves the PREVIOUS
+ * route's title/description/canonical in the DOM. Measured on boogie-babies:
+ * `/pricing` -> `/parties` still claims `canonical=/pricing`. The audit reports
+ * this as `uncovered-route` and deliberately does not fail on it, because the
+ * fix is one router hook in the platform, not eleven views remembering.
+ *
+ * WHY THIS FILE IS FULL OF REFUSALS. Turning silence from "safe" into "asserts
+ * whatever the lookup returns" is a LOADED CHANGE: on every route whose baked
+ * head is already correct, a wrong lookup is a live regression on a paying
+ * customer. A fleet sweep on 2026-07-28 measured three ways the obvious
+ * implementation breaks, and each one is encoded here as a hard rule.
+ *
+ *   R1  DRIVE THE LOOKUP FROM `.dcs/pages.yaml`, NEVER FROM `to.meta.pageSlug`.
+ *       KEPT carries `meta.pageSlug` on every route, which makes the meta-driven
+ *       version look like the obvious choice. It is a trap: KEPT's two DYNAMIC
+ *       routes carry the PLACEHOLDER keys `blog-post` and `topic`, and neither
+ *       key exists in its `seo.yaml`. A meta-driven build therefore collapses
+ *       21 blog posts + 3 topic pages to `global.defaultTitle` ON THE TOP PAYER.
+ *       The pages.yaml path->slug map resolves all 24 correctly, because it is
+ *       the SAME map the build-time emitter walked to bake them.
+ *       There is no read of `meta` anywhere in this file. That is the fix.
+ *
+ *   R2  NO MATCH => TOUCH NOTHING. Not `global.defaultTitle`, not a clear, not
+ *       a "best effort" — nothing. boogie-babies' catch-all is
+ *       `/:pathMatch(.*)*` and its runtime path is the URL the visitor
+ *       MISTYPED (`/nope-xyz`), never the pages.yaml path `/404`; that repo
+ *       carries no `meta.pageSlug` at all. So a no-match is the NORMAL case
+ *       there, and any fallback write would clobber a correct baked head on
+ *       every 404 the site serves. No `seo.yaml` entry can fix it — the lookup
+ *       KEY is the wrong thing, not the value.
+ *
+ *   R3  NORMALIZE TRAILING SLASHES ON BOTH SIDES. KEPT declares `/blog/` in
+ *       pages.yaml and `/blog` in router.ts. Naive path equality misses it and
+ *       the blog index silently joins the no-match set. The root path `/` must
+ *       NOT normalize to the empty string. A manifest that declares BOTH forms
+ *       is rejected at BUILD time (see `findDuplicateNormalizedPaths`), because
+ *       the emitter's last-write wins the output file while a lookup map's
+ *       first-write wins the runtime — a duplicate therefore guarantees
+ *       divergence whichever side you pick, so neither side may pick.
+ *
+ *   R4  A FAILED NAVIGATION IS NOT A NAVIGATION. Vue Router calls
+ *       `afterEach(to, from, failure)` for ABORTED, CANCELLED and DUPLICATED
+ *       navigations, and when it fails the visible route stays `from`. A hook
+ *       that reads only `to` therefore asserts the head of a page the visitor is
+ *       NOT on: an auth guard rejecting `/pricing -> /account` leaves them on
+ *       pricing under the ACCOUNT head, `noindex` included. Verified at source
+ *       on vue-router 4.6.3 (`triggerAfterEach(toLocation, from, failure)` runs
+ *       unconditionally; `finalizeNavigation` — the only assignment to
+ *       `currentRoute` — is skipped when a failure is present) and empirically:
+ *       a `beforeEach` returning `false` produced `afterEach(to=/account,
+ *       from=/pricing, failure.type=4)` with `currentRoute` still `/pricing`.
+ *       So: `failure` truthy => write NOTHING. This rule exists because the
+ *       obvious version of THIS FIX invents its own divergence class.
+ *
+ *   R5  THE INITIAL DOCUMENT IS NOT RE-ASSERTED. Its head is the baked,
+ *       owner-approved one and is correct exactly once — on that document.
+ *       Re-asserting buys nothing and puts the one head that is already right on
+ *       the same code path as the one that can be wrong. This is ENFORCED, not
+ *       assumed: `afterEach` alone does not guarantee it, because the generated
+ *       app entry installs the router BEFORE awaiting `router.isReady()`
+ *       (`packages/create-dcs-site/templates/vue-spa/src/main.ts`), so a hook
+ *       registered on the adoption line can and does observe the initial
+ *       navigation. The guard recognises vue-router's START location
+ *       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).
+ * 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:
+ *
+ *   GOOD — Unhead RECONCILES against the baked static head. It does not add
+ *   alongside it. `<title>`, description, canonical, robots, og:* and twitter:*
+ *   all stayed at EXACTLY ONE element through six navigations, with the new
+ *   route's value. The feared "two titles, two canonicals" outcome does not
+ *   happen on either version, and is in fact unreachable: Unhead dedupes by tag
+ *   identity even across separate entries.
+ *
+ *   BAD — Unhead only REMOVES side effects it OWNS, and it never owned the
+ *   baked tags. So a managed tag that is present in the BAKED head and ABSENT
+ *   from the runtime entry is left stranded in the DOM. Concretely: land on
+ *   baked `/blog/post-a` (which bakes `<meta name="keywords">`), click through
+ *   to `/blog/post-b` (whose seo.yaml declares none) and post A's keywords are
+ *   still there while title, description and canonical have all moved. This is
+ *   C-361 F4 — the divergence `includeKeywords: true` was added to close —
+ *   surviving in its baked->runtime half. The class is EVERY OPTIONAL managed
+ *   tag, not just keywords: the fixture reproduces it for `link[rel=alternate]`
+ *   hreflang too, and `robots`/`article:*` are exposed the same way.
+ *
+ *   It is invisible to the 610 fake-driven tests by construction: when the tag
+ *   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.
+ *
+ * WHAT IT RE-ASSERTS, AND WHAT IT DELIBERATELY DOES NOT.
+ *   - `title`, `meta`, `link` — the managed fields P1 (`headHonesty.ts`) grades
+ *     and the ones that go stale on SPA navigation. `meta[name=keywords]` is
+ *     among them: the emitter passes `includeKeywords: true`, so a re-assert
+ *     that omitted it would leave post A's baked keywords in the DOM on
+ *     post A -> post B while every other managed field moved (C-361 F4).
+ *   - NOT `script` (JSON-LD). The baked graph is built with inputs that do not
+ *     exist at runtime (`content.yaml` reviews, business license, FAQ pairs,
+ *     breadcrumb trails). Re-asserting a POORER graph would not correct the
+ *     baked one, it would add a second, conflicting set of nodes — a new
+ *     divergence class invented by the fix. Leaving it alone is the same
+ *     judgement as R2: do not overwrite what you cannot faithfully reproduce.
+ *     Named residual: after an in-app navigation the JSON-LD still describes the
+ *     first document. Crawlers read the fetched document, where it is correct.
+ *
+ * IT RESOLVES THROUGH THE SHIPPED EMITTER (`buildHeadTags`) AND CARRIES THE TWO
+ * BUILD-TIME-ONLY INPUTS. A second head-building code path would be its own
+ * divergence source, so this calls the exact function the build calls. Two
+ * inputs the plain runtime composable does NOT carry are threaded through here
+ * because C-357 measured both as live divergences:
+ *   - `fallbackTitle` (the pages.yaml route title). The emitter resolves
+ *     `page.title || <route title>`; the runtime had no fallback and collapsed
+ *     to `global.defaultTitle`. mi-handyman had FOUR such routes.
+ *   - the `noindex` force. `dcsSeoPlugin({ noindex: [...] })` is a BUILD-TIME
+ *     force; the runtime `__DCS_SEO__` global is the raw seo.yaml, so a re-assert
+ *     without it republishes `index, follow` over a baked `noindex` — measured
+ *     live on iron-oak `/account` and `/projects`. Re-asserting without carrying
+ *     the list would ship that known regression by construction.
+ *
+ * NO vue-router IMPORT. The router is accepted structurally (anything with an
+ * `afterEach`), so this package gains no dependency and the tests need no router
+ * instance to prove the rules.
+ */
+/**
+ * What this module reads off a resolved route.
+ *
+ * `path` is the ONLY field consulted for the lookup. `name` and `matched` are
+ * read off `from` ALONE, and only to recognise vue-router's START location for
+ * R5; nothing about the head is ever derived from them.
+ */
+interface SeoHeadRouteLike {
+    path: string;
+    /** `from` only, R5: START location has no name. Never used for the lookup. */
+    name?: unknown;
+    /** `from` only, R5: START location matched nothing. Never used for the lookup. */
+    matched?: readonly unknown[];
+}
+/**
+ * The slice of a vue-router instance this needs.
+ *
+ * The hook takes the FULL vue-router `afterEach` arity. `failure` is not
+ * optional decoration — see R4: dropping it is what makes an aborted navigation
+ * assert the head of a page nobody is on.
+ *
+ * NOTE THE ABSENCE: there is no `meta` on {@link SeoHeadRouteLike}, and that
+ * absence is PINNED at compile time by {@link SEO_HEAD_ROUTE_HAS_NO_META}
+ * below rather than left as friction.
+ */
+interface SeoHeadRouterLike {
+    afterEach(hook: (to: SeoHeadRouteLike, from?: SeoHeadRouteLike, failure?: unknown) => void): unknown;
+}
+/**
+ * COMPILE-TIME PIN: the route type this module accepts must carry NO `meta`.
+ *
+ * WHY A PIN AND NOT JUST AN ABSENCE. The absent property was described as
+ * "friction, not a gate", and the cross-model review proved it: a future edit
+ * adding `meta.pageSlug` as a NO-MATCH FALLBACK keeps every existing test green,
+ * because the matched-route tests supply POISONED meta (so a fallback never
+ * fires there) and the no-match tests supply NONE (so a fallback finds nothing).
+ * Widening the interface is the mechanical prerequisite for reading `meta`, so
+ * this is where R1 gets a real gate.
+ *
+ * Modelled on `APPLY_HEAD_TAKES_NO_ARGUMENTS` in `headContract.ts`, and it lives
+ * in a CHECKED SOURCE FILE for the same reason: `packages/cms/tsconfig.json`
+ * excludes `**\/*.test.ts`, so a `@ts-expect-error` in the test file would be a
+ * comment wearing a gate's clothes. Add `meta` to {@link SeoHeadRouteLike} and
+ * the assignment below stops compiling — red in this package's `type-check`,
+ * and through the published `.d.ts` in every site that runs one.
+ *
+ * HONEST LIMIT, stated rather than implied: this pins the TYPE SURFACE. It
+ * cannot stop `(to as any).meta`, exactly as `APPLY_HEAD_TAKES_NO_ARGUMENTS`
+ * cannot stop an `as any` argument. The behavioural half is the no-match test
+ * that navigates with a poisoned meta pointing at a REAL seo.yaml slug — the
+ * case the review found missing.
+ */
+type SeoHeadRouteHasNoMeta = 'meta' extends keyof SeoHeadRouteLike ? false : true;
+declare const SEO_HEAD_ROUTE_HAS_NO_META: SeoHeadRouteHasNoMeta;
+/** A live unhead entry (`head.push(...)` result) — only `patch` is used. */
+interface SeoHeadEntryLike {
+    patch(input: SeoHeadInput): void;
+}
+/** The unhead client (`createHead()`), passed in explicitly — see below. */
+interface SeoHeadClientLike {
+    push(input: SeoHeadInput, options?: Record<string, unknown>): SeoHeadEntryLike;
+}
+/** The head payload handed to unhead. Managed fields only. */
+interface SeoHeadInput {
+    title: string;
+    meta: HeadMetaTag[];
+    link: HeadLinkTag[];
+}
+/** One route from `.dcs/pages.yaml`, as the emitter reads it. */
+interface SeoHeadPageRoute {
+    slug: string;
+    path: string;
+    title?: string;
+}
+/**
+ * The runtime manifest injected by `dcsSeoPlugin` as `__DCS_PAGES__`.
+ *
+ * It carries the `noindex` list alongside the routes because that list is a
+ * plugin OPTION, not a file — without it here the runtime cannot know that a
+ * route was baked `noindex, nofollow`.
+ */
+interface SeoHeadPagesManifest {
+    routes: SeoHeadPageRoute[];
+    noindex?: string[];
+}
+/** Why a navigation did or did not result in a head write. */
+type SeoHeadResolutionReason =
+/** Matched a manifest route; the head was re-asserted. */
+'applied'
+/** No manifest reached the runtime — the module is inert (never a fallback). */
+ | 'no-manifest'
+/** The path is not a manifest route — R2: the baked head is left alone. */
+ | 'no-match'
+/**
+ * R4 — the navigation FAILED (aborted / cancelled / duplicated), so the
+ * visitor is still on `from` and `to` is a page they never reached. Reported
+ * rather than silent: "the guard rejected it" and "the hook never ran" must
+ * not look the same from the outside.
+ */
+ | 'navigation-failed'
+/**
+ * R5 — the initial document. Its baked head is the approved one; the hook
+ * observed the navigation (installation raced `router.isReady()`) and
+ * deliberately declined to write.
+ */
+ | 'initial-navigation';
+interface SeoHeadResolution {
+    /** The path as the router reported it. */
+    path: string;
+    /** The path after R3 normalization — what the lookup actually used. */
+    normalizedPath: string;
+    matched: SeoHeadPageRoute | null;
+    reason: SeoHeadResolutionReason;
+    /** The resolved `<title>`, or `null` when nothing was written. */
+    title: string | null;
+}
+interface InstallSeoHeadOptions {
+    /**
+     * The unhead client the app already created (`const head = createHead()`).
+     *
+     * REQUIRED, and it cannot be discovered instead. `injectHead()` calls Vue's
+     * `inject`, which throws outside a component `setup()` — and a router
+     * `afterEach` hook is exactly that. Passing it is the honest API; guessing at
+     * a global would fail at runtime on the first navigation.
+     */
+    head: SeoHeadClientLike;
+    /** Route manifest. Defaults to the injected `__DCS_PAGES__.routes`. */
+    pages?: SeoHeadPageRoute[];
+    /** SEO config. Defaults to the injected `__DCS_SEO__`. */
+    seo?: SeoConfiguration;
+    /** Build-time noindex list. Defaults to the injected `__DCS_PAGES__.noindex`. */
+    noindex?: string[];
+    /**
+     * Observability hook, called once per navigation with the resolution —
+     * INCLUDING the no-match case. Exists so "it did nothing" is distinguishable
+     * from "it never ran", which is the vacuous-green shape this estate keeps
+     * counting. Never affects behaviour.
+     */
+    onResolve?: (resolution: SeoHeadResolution) => void;
+}
+/**
+ * Normalize a path for comparison. Applied to BOTH sides — the manifest path and
+ * the router path — because normalizing only one side is how `/blog/` and
+ * `/blog` stayed unequal.
+ *
+ * - drops `?query` and `#hash` (a router path should not carry them; a caller's
+ *   `fullPath` might, and silently no-matching on a query string would be a
+ *   surprise no one would ever debug)
+ * - strips trailing slashes
+ * - PRESERVES the root: `/` and `''` both normalize to `/`, never to `''`.
+ *   Collapsing root to the empty string makes the home route unmatchable, which
+ *   is the highest-traffic route on every site in the fleet.
+ */
+declare function normalizeSeoHeadPath(input: string): string;
+/**
+ * Find manifest paths that COLLIDE after R3 normalization.
+ *
+ * WHY THIS IS A BUILD ERROR AND NOT A TIEBREAK (C-361 F6, verified). A manifest
+ * carrying both `/blog` and `/blog/` resolves OPPOSITE ways on the two sides of
+ * the contract:
+ *
+ *   - the EMITTER walks the manifest in order and writes one file per route, so
+ *     for colliding paths the LAST write is the one left on disk;
+ *   - a lookup Map keyed on the normalized path takes the FIRST entry, because
+ *     that is what "don't clobber" means for a map.
+ *
+ * Whichever side is "fixed", the other is then wrong — the duplicate does not
+ * merely risk divergence, it GUARANTEES it. There is no correct pick, so the
+ * build must refuse instead of picking. The two entries have different slugs and
+ * therefore different seo.yaml identities; only the site owner knows which page
+ * that URL is.
+ *
+ * @returns the normalized paths that appear more than once, each with the
+ *   colliding raw entries, in first-seen order. Empty array = clean.
+ */
+declare function findDuplicateNormalizedPaths(routes: readonly SeoHeadPageRoute[]): Array<{
+    normalizedPath: string;
+    routes: SeoHeadPageRoute[];
+}>;
+/** Human-readable duplicate report, shared by the build throw and the runtime log. */
+declare function formatDuplicateNormalizedPaths(dupes: ReadonlyArray<{
+    normalizedPath: string;
+    routes: SeoHeadPageRoute[];
+}>): string;
+/**
+ * Build the normalized path -> route lookup.
+ *
+ * On a duplicate normalized path the FIRST entry wins. That is a LAST-RESORT
+ * DETERMINISM RULE, not the contract: duplicates are rejected at build time by
+ * `findDuplicateNormalizedPaths` (R3), and this branch only ever runs for a
+ * manifest that reached a browser without passing that gate. It is deliberately
+ * not "clever" — an arbitrary-but-stable pick is the least bad thing to do once
+ * the loud failure has already been missed.
+ */
+declare function buildSeoHeadRouteMap(routes: readonly SeoHeadPageRoute[]): Map<string, SeoHeadPageRoute>;
+/**
+ * Re-assert the `.dcs/seo.yaml` head on every in-app navigation.
+ *
+ * Adoption is one line at app entry, after the head client exists:
+ *
+ * ```ts
+ * const head = createHead()
+ * app.use(head)
+ * installSeoHead(router, { head })
+ * ```
+ *
+ * DOES NOT WRITE FOR THE INITIAL DOCUMENT (R5) — and that is now IMPLEMENTED
+ * rather than asserted. The previous version of this docstring claimed
+ * `afterEach` "is registered for SUBSEQUENT navigations only"; there was no such
+ * guard, and the claim is false whenever the hook is installed while the initial
+ * navigation is still in flight — which is precisely what the adoption snippet
+ * above does in the generated app entry, where `app.use(router)` runs BEFORE
+ * `router.isReady()` is awaited. The head of the document the browser actually
+ * fetched is the baked, owner-approved one and is correct exactly once, on that
+ * document; re-asserting it buys nothing and puts the one head that is already
+ * right on the same code path as the one that can be wrong. Installing AFTER
+ * `await router.isReady()` reaches the same outcome by a different route (the
+ * hook simply never sees that navigation) and is equally supported — the guard
+ * exists so the outcome does not depend on remembering which.
+ *
+ * NAMED RESIDUAL (R5, dev only): under `vite dev` there is no baked per-route
+ * `<head>` — the shell's is generic — so the skipped initial write leaves the
+ * generic head in place until the first in-app navigation. Production is
+ * unaffected because production HAS a baked head. The skip is reported through
+ * {@link InstallSeoHeadOptions.onResolve} as `initial-navigation`, so it is
+ * observable rather than mysterious.
+ *
+ * @returns the hook's own removal function, as vue-router's `afterEach` returns.
+ */
+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 };