@duffcloudservices/cms 0.11.0 → 0.13.0

package/README.md

@@ -145,23 +145,57 @@ import { useSEO } from '@duffcloudservices/cms'
 
 const {
   config,         // ComputedRef<ResolvedPageSeo>
-  applyHead,      // (overrides?: HeadOverrides) => void
+  applyHead,      // () => void   <- NO ARGUMENTS. See the head-authority contract.
   getSchema,      // () => object[]
   getCanonical,   // () => string
   hasBuildTimeSeo // boolean
 } = useSEO('home', '/') // pageSlug, optional pagePath
 
-// Apply all meta tags
+// Re-assert the baked head for this route.
 applyHead()
+```
 
-// Or with overrides
-applyHead({
-  title: 'Custom Title',
-  description: 'Custom description',
-  schemas: [...getSchema(), customSchema]
-})
+#### The head-authority contract (C-356)
+
+`.dcs/seo.yaml` is the **only** writer of `<title>`, description, keywords,
+robots, canonical, `og:*`, `twitter:*` and the JSON-LD graph. `applyHead()`
+RE-ASSERTS that head at runtime; it never authors one, so it takes no arguments.
+Need a different value? Change it in `.dcs/seo.yaml` (or the portal SEO editor,
+which writes it).
+
+A hardcoded value that currently *matches* the baked one is still a violation —
+the contract grades authority, not values. Full text, the measured evidence and
+the rejected alternatives: **`.docs/plans/dynamic-site-resolution/README.md`
+§ "The head-authority contract (C-356)"**.
+
+Enforced here, not per-site: the `() => void` type (fails `type-check`),
+`auditHeadContract()` in `src/seo/headContract.ts` (fails the audit), and a
+runtime refusal that drops the override and keeps `seo.yaml` authoritative.
+Audit a real site with:
+
+```bash
+pnpm --filter @duffcloudservices/cms build
+node cli/head-contract-audit.mjs --all --json out.json
 ```
 
+**Exemptions carry live claims (C-420).** An entry in a site's
+`.dcs/head-contract.json` whose reason NAMES a host must also declare what that
+host does, and the audit fetches it (redirects read, never followed):
+
+```jsonc
+"site/src/views/HomeView.vue": {
+  "reason": "…why the seo.yaml factory cannot own this head…",
+  "hosts": { "example.com": { "status": 200, "robots": "noindex",
+                              "canonicalHost": "other.example" } }
+}
+```
+
+A named host with no claim, a claim with no observation, and a claim the live
+host contradicts all FAIL — `--no-probe` silences none of them. The measured
+case: an exemption asserted a host was a noindex cross-domain handoff while that
+host served `index, follow` and a self-canonical from a different SWA, and the
+audit was green *because of* the exemption.
+
 ### useReleaseNotes
 
 Fetches release notes from the DCS Portal API.
@@ -191,6 +225,81 @@ const {
 } = useSiteVersion()
 ```
 
+### Conversion capture (automatic — no site code)
+
+Measures the money-moment. **Importing this package installs it.** One delegated,
+capture-phase listener on `document` classifies every link and form submit on the site and
+emits a `site_interaction` event.
+
+There is nothing to mount. That is the point: this shipped as an opt-in
+(`useConversionTracking`) and was adopted by *zero* of eleven fleet sites, so on 2026-07-26
+two independent reviews found the same hole — Bryan's Handyman's five `tel:` CTAs, the only
+conversion action the site has, emitting nothing at all. A capability a site must remember
+to switch on is a capability that is off.
+
+**Event schema**
+
+| Property | Value |
+|---|---|
+| `interaction_type` | `booking` · `phone` · `email` · `form_submit` · `social` · `external` · `internal` · `button` |
+| `is_conversion` | `"true"` for the first four. One predicate for owner reports. |
+| `label` | Visible/aria label of the clicked control, truncated to 120 chars |
+| `href` | Destination, query + fragment stripped. **Contact schemes are redacted** to `tel:#<digest>` |
+| `href_scheme` | `tel:` · `sms:` · `mailto:` · `https:` · … |
+| `href_host` | Destination host (`''` for contact schemes and buttons) |
+| `href_hash` | Digest of the contact target — lets a report rank CTAs without storing a number |
+| `page_path`, `host` | Where the interaction happened |
+| `capture_version` | `2` |
+
+No raw phone number or email address is ever emitted. The digest is a normalising
+convenience, **not** anonymisation — a site publishes two or three numbers, so treat it as
+"the contact string never reaches the analytics store", nothing stronger.
+
+**Where the events go.** Two independent transports, and it will use whichever exist:
+
+1. **GA4** — picked up automatically from `window.gtag`, which the deploy workflow injects
+   whenever `.dcs/site.yaml` has a `google_analytics_id`. A site with GA4 configured
+   measures conversions with **no code change whatsoever**.
+2. **App Insights** — attaches through a global, so no package depends on a telemetry SDK:
+
+```typescript
+// After your App Insights instance is live. One line, no import.
+window.__dcsConversionAttach?.((e) => appInsights.trackEvent(e))
+```
+
+`@duffcloudservices/telemetry` already does this inside `initialize()`. Clicks captured
+before a transport exists are buffered (bounded FIFO) and flushed on attach — deferring or
+lazy-loading the App Insights SDK must never silently zero a customer's booking numbers.
+
+**Per-site configuration** — call the installer yourself at app entry; the first call wins:
+
+```typescript
+import { installConversionCapture } from '@duffcloudservices/cms'
+
+installConversionCapture({
+  bookingHosts: ['stridethera.com', 'momence.com'], // on top of the fleet defaults
+  bookingPaths: ['/book'],                          // self-hosted booking routes
+})
+```
+
+**It deliberately does nothing** when there is no `document` (SSR/prerender), inside an
+iframe (the visual editor and preview surfaces — an editor's clicks are not leads), under
+Do Not Track, or when the page sets `window.__dcsConversionOptOut = true` /
+`<html data-dcs-analytics="off">`.
+
+**Double counting is guarded, not hoped for.** Only one delegated listener may bind per
+document — a second `start()` refuses with a console warning rather than doubling every
+conversion — and a click on a form's submit control is dropped so the `submit` event can be
+the single source of truth (a click that fails validation is not a lead). This is the same
+discipline as `trackPageView`'s auto-route refusal: C-288 measured 52% duplicate page views
+on a live site from exactly this class of mistake, and the portal reported them to the owner.
+
+> Do **not** add `"sideEffects": false` to this package. It would let a consumer's bundler
+> drop the auto-install and silently restore the blind spot.
+
+`useConversionTracking` / `createConversionTracker` remain exported for non-cms consumers
+and for tests.
+
 ## Vite Plugins
 
 ### dcsContentPlugin
@@ -224,6 +333,25 @@ dcsSeoPlugin({
 })
 ```
 
+**`noindex` is a predicate over `pages.yaml`, not a standalone directive.**
+Every consumer asks it route-first (`noindexSet.has(route.path) || …has(route.slug)`),
+so an entry naming a page that is not in `pages.yaml` emits **no document at
+all** — the directive silently does nothing and the URL stays `index, follow`.
+Since **C-416** that is a hard build failure (`NoindexOrphanError`, thrown from
+`config()` before a byte is emitted):
+
+```
+[dcs-seo] noindex entries matching NO page in the route manifest: "/homepage-clone-1", "account".
+… Fix it by adding the page to pages.yaml …, or by deleting the stale entry.
+Matchable keys are the manifest's paths and slugs: "/", "/services", "home", "services"
+```
+
+Notes: matching is raw, so `'/services/'` does **not** match a `'/services'`
+route (the emitter would not match it either, so blessing it would certify a
+no-op); matching runs against the **full** manifest, so an entry that is also in
+`exclude` is fine. There is no severity knob — the fix is always "add the page"
+or "delete the row".
+
 #### Body prerender (crawler-visible body content)
 
 When `emitStaticHtml` is on, the plugin also **prerenders each indexable
@@ -248,6 +376,114 @@ unaffected while crawlers get the body.
   prerender for one site, or pass `dcsSeoPlugin({ prerenderBody: false })`.
   Preview builds skip it automatically.
 
+#### SEO emission honesty rails (C-334)
+
+Three build-time asserts against one failure class: **a platform capability that
+exists, is silently undone downstream, and has nothing watching.** All three are
+**ON by default at severity `error`** whenever `emitStaticHtml` is on, so a cms
+bump arms them fleet-wide with no per-site edit.
+
+| Rail | Asserts | Kill-tested against |
+|------|---------|---------------------|
+| **P1 head honesty** | For every emitted route, the **baked** `<title>`/description equals the **rendered** ones after the app mounts | Live Iron Oak, 2026-07-27: baked `Handyman, Carpentry & Home Repairs in SE Michigan \| Iron Oak` vs rendered `Our Services` — 18/18 routes divergent |
+| **P2 emitted-URL honesty** | Every URL the factory publishes (JSON-LD `logo`/`image`, `og:image`, icon links, sitemap `<loc>`s, llms.txt links) resolves to what it promises | Live Iron Oak, 2026-07-27: `Organization.logo` → `200 text/html`, byte-identical to the homepage |
+| **P12 charset budget** | `<meta charset>` lands inside the spec's first-1024-byte encoding-sniffing window — asserted straight out of `dcsContentPlugin` (C-414), with the `emitStaticHtml` hoist as a backstop | Live Iron Oak **and** Bryan's, 2026-07-27: charset at byte 910, 90 bytes of headroom past the declaration, no header-level `charset` backstop |
+
+Why they behave the way they do:
+
+- **P1 rides the prerender browser** — the page is already being loaded, so the
+  marginal cost is one `page.evaluate()` per route. If a site has opted out of
+  body prerender the render still happens in **observe-only** mode (nothing is
+  written to `dist/`), because a gate that quietly does not exist on some sites
+  is worse than no gate.
+  A clean site passes *structurally*: `applyHead()` produces byte-identical tags
+  to the build-time emit. **Since C-356 an override is impossible** — the
+  parameter is gone from the signature and a runtime argument is dropped — which
+  is what makes "structurally clean" the default rather than an achievement.
+  (Historically `applyHead({ title })` used the override *verbatim*, skipping
+  `global.titleTemplate`, so an override that "looked right" still diverged; that
+  was the root cause of 93 divergences on KEPT and 18 more across three sites.)
+  P1 remains the rail that judges the values; the source-side
+  `auditHeadContract()` judges who is allowed to write them.
+- **P2 splits by how certain the answer is.** Same-origin assets are proven
+  against `dist/` with **no network at all**: an emitted `https://site/logos/x.svg`
+  with no `dist/logos/x.svg` behind it means the host's SPA fallback *will*
+  answer HTML, so it is a hard failure. Cross-origin assets are probed under a
+  24h cache, a 5s per-request timeout and a 20s total budget, where a
+  **definitive** wrong answer (HTML where an image was promised, or a 4xx/5xx)
+  fails the build and a **non-answer** (DNS, timeout, reset, budget exhausted)
+  is only a warning. A gate that reds on a network hiccup gets disabled within a
+  week and then protects nothing.
+- **P12 fixes as well as asserts.** The motion-token `<style>` *was* injected
+  `head-prepend`, above the site's own `<meta charset>`; **C-414 fixed that at
+  the source** — it now injects `head` (append), which keeps it above the
+  bundled site CSS (so a per-site `:root` override still wins) while leaving the
+  encoding declaration first in `<head>`. The `emitStaticHtml` path still hoists
+  the declaration in the emitted shell (idempotent, moves nothing else, now a
+  no-op on a stock shell) and then asserts the result — that hoist is the
+  backstop for hand-rolled shells, and it never ran on VitePress sites, which is
+  why the source fix was the one that reached the whole fleet. **Also fix the
+  header** where the site's config lives — SWA currently answers
+  `Content-Type: text/html` with no `charset` parameter, so there is no
+  header-level backstop.
+
+Escape hatches — deliberately impossible to use silently:
+
+```yaml
+# .dcs/seo.yaml (portal-owned, in git, reviewable)
+headHonesty:
+  mode: warn                 # error (default) | warn | off
+  allow: ['/legacy-route']   # every exemption is printed on every build
+  checkDescription: true
+urlHonesty:
+  mode: error
+  allow: ['https://cdn.example.com/known-missing.svg']
+  network: true              # false ⇒ same-origin still enforced
+charsetBudget: error
+```
+
+```bash
+# Per-build override — prints in the build log, so it is never invisible
+DCS_SEO_HEAD_HONESTY=warn DCS_SEO_URL_HONESTY=warn pnpm build
+DCS_SEO_URL_HONESTY_NETWORK=off pnpm build   # offline CI
+```
+
+Verification (needs a browser; not part of `pnpm test`):
+
+```bash
+pnpm --filter @duffcloudservices/cms run verify:honesty-rails
+# and, to see what a LIVE site's build will red on before bumping cms:
+pnpm --filter @duffcloudservices/cms run probe:live-urls https://example.com
+```
+
+#### The served-document pass (C-417)
+
+All three rails above assert against the **candidate build** — the `dist/` on the
+machine that ran the build. Nothing re-asserted them against the document a
+browser receives, and that gap is how C-341's `charset hoisted 913 -> 48` claim
+survived: true of a local build, false in production, where the served document
+has `<meta charset>` at byte 910 (measured 2026-07-31, KEPT re-review F3). The
+KEPT re-review estimated a post-deploy re-run would have caught it in 8 minutes.
+
+Run the same rail primitives over the bytes the origin serves — **after every
+deploy**, and always before citing a rail's number as evidence:
+
+```bash
+# P2 + P12 on the served document (default)
+pnpm --filter @duffcloudservices/cms run verify:served-honesty https://example.com --routes all
+
+# ...and hold the CANDIDATE BUILD's recorded numbers against what shipped.
+# `dist-honesty-report.json` is what DCS_SEO_HONESTY_REPORT wrote during the build.
+DCS_SEO_HONESTY_REPORT=dist-honesty-report.json pnpm build
+pnpm --filter @duffcloudservices/cms run verify:served-honesty https://example.com \
+  --routes all --rails p1,p2,p12 --rendered --compare dist-honesty-report.json
+```
+
+Exit codes: `0` pass · `1` a rail FAILED or the recorded evidence does not
+describe the served document · `3` a requested rail DID NOT RUN. A rail that
+could not run is never folded into a pass — the C-338 execution assertion,
+applied to the served side.
+
 ## Configuration Files
 
 ### .dcs/content.yaml