Records the agreed host contract for the CMS injection plan

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 15:18:32 +01:00
co-authored by Claude Sonnet 5.5
parent ee973477de
commit 7feebb690c
@@ -52,6 +52,24 @@ Why not exact copies of the styled cards: Chakra/Emotion class names and styles
- **Hero (LCP):** the first slide must be in the first HTML, with the image preloaded. The host injects the slide markup and a `<link rel="preload" as="image">` into a head marker; the client slider starts from the same first slide so nothing swaps. Own plan, because the carousel is interactive.
- **Gallery:** `figure` list with image URLs, sizes and alt texts in a region (crawlable), React adds lazy loading and the lightbox after hydration. Images are served same-origin by the CMS host (CSP `img-src 'self'`).
## Host contract (agreed with SMC, 2026-11-15; built after Bryan's approval)
The host (CMS repo) finds all markers in one pass. A page with no marker and without the written production address is served unchanged as a static file. **Fail open everywhere:** a missing marker does nothing, invalid or missing data leaves the baked page as it is, an unknown slug keeps the baked fallback.
1. **List regions** `<!--CMS:OFFERINGS-HTML-->…<!--/CMS:OFFERINGS-HTML-->`, and for the banners `<!--CMS:BANNER-TOP-HTML-->…<!--/CMS:BANNER-TOP-HTML-->` and `<!--CMS:BANNER-BOTTOM-HTML-->…<!--/CMS:BANNER-BOTTOM-HTML-->`: the host replaces the content between the markers by simple crawlable HTML from the live data (C# template, everything HTML-encoded); the markers stay. No live data or a provider error keeps the baked fallback. Spec and golden files below.
2. **Data** `<!--CMS:DATA-->` directly followed by the baked `<script type="application/json" id="cms-data">…</script>`: the host replaces the pair by the live block `{"siteUrl":"…","offerings":[…],"banners":{"top":…|null,"bottom":…|null}}` (offerings and banners exactly as the public GETs; `<`, `>`, `&`, U+2028 and U+2029 written as `\uXXXX` escapes). Without a block after the marker the live block replaces the marker. `siteUrl` is the effective public base URL (see 5), which the client needs because the JS bundle cannot be rewritten (immutable assets).
3. **JSON-LD price** `<!--CMS:OFFER-JSON-LD slug="newborn"-->` directly before `<script type="application/ld+json">…</script>`: the host parses the block and sets `offers.price` (whole euros, our parsing: "€ 175", "€ 1.250", "175,-") on the node that has `offers`; when the package is gone, switched off, scheduled or has no readable price, `offers` is removed from that node. A database or provider failure is different: the baked block stays (fail open). A block that is not valid JSON stays. The marker comment is removed; property order is kept. Only the shoot pages of newborn, zwangerschap and gezin get this marker; loveshoot, portret ("Prijs op aanvraag"), the overview and the home page get none.
4. **Inline value** `<span data-cms-price="newborn">€ 185</span>`: the host replaces the text by "€" + U+00A0 + whole euros; an unknown slug or an unreadable price leaves the span alone. Only simple, non-nested spans with exactly this attribute. Used in the price block of a shoot page.
5. **Own address** (`Website:AuthoredBaseUrl`): the same injector replaces the written production address in every HTML page, `sitemap.xml` and `robots.txt` by `Website:PublicBaseUrl` when that is set on the host (test: `https://test.andreaslop.nl`; production: equal or empty, nothing to replace). One artifact then serves test and production, and `VITE_SITE_URL` no longer differs per environment. The ASF build is written with `https://andreaslop.nl` (the non-www canonical origin; IIS redirects www to it). The site has no web manifest. The client takes its address from `siteUrl` in the data block (fallback: the production address), not from the bundle, so canonical and `og:` tags stay right after hydration and on navigation.
6. **Caching:** injected pages get `Cache-Control: no-cache`, a strong ETag (hash of the final body), 304 on `If-None-Match` and no Last-Modified, behind the host's 60 s cache with direct invalidation on every CMS change. `/assets/` stays immutable. Pages without markers keep the native static-file headers.
### Neutral HTML spec (draft; golden files follow once Bryan has approved the approach)
- Order: `displayOrder`, then the order given. Skip a package with a slug that is not `[a-z0-9-]+`, a duplicate slug, no title, a price that is not readable as whole euros above zero, or no features (same rules as `mapOfferings`). The baked fallback stays when the host has no live data at all.
- Per package: `<li data-slug="newborn"><h3>Newborn</h3><p>€&nbsp;185</p><ul><li>…</li></ul><a href="/?pakket=newborn#contact">Boek Newborn</a></li>` inside one `<ul>` per region; the price with U+00A0 after the euro sign; the inner list items are the features in order; all text HTML-encoded. A featured package gets `data-featured="true"` on its `<li>`. Description, price note and button label are not rendered.
- Banner regions: `<aside><strong>{title}</strong> <span>{text}</span> <a href="{url}">{label}</a></aside>`; `strong`, `span` and `a` only when the field is present; the link only when label and URL are both present and the URL is `https://` or a path with one leading `/`; nothing at all when there is no banner (204).
- The ASF repo delivers the fixtures (input JSON and expected HTML) and a README with the commit; SMC tests against the same files.
## Order of work (after approval)
1. Marker spec and golden fixtures (ASF repo), agreed with SMC.