Files
AndreaSlopFotografie/aidlc-docs/features/asf-cms-host-injection/plan.md
T
SluijsensandClaude Sonnet 5.5 db86332c1f
Continuous Integration / check (pull_request) Successful in 2m25s
Continuous Integration / build-test (pull_request) Skipped
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / lighthouse (pull_request) Successful in 9m2s
Continuous Integration / deploy-production (pull_request) Skipped
Opens the contact form through a build switch instead of the TEST ONLY commit; closes the AI-DLC records
The form is closed unless the build sets VITE_CONTACT_FORM_ENABLED=true (only
the test build does), so d449e76 no longer has to be undone before the merge.
Status files of contact-form-cms, asf-packages-cms, asf-cms-host-injection and
asf-translation-files are closed; Build and Test summary added.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 12:01:29 +01:00

13 KiB

Plan (approach agreed, waiting for the start): the CMS host injects CMS data into the prerendered ASF pages

Status (2026-11-16): ASF side built and closed (see aidlc-state.md); host side by SMC. Original status: plan, approach agreed 2026-11-15.

Decisions of Bryan (via SLS-Main, 2026-11-15):

  • (a) A short change of look of the cards on first paint (neutral HTML first, then the styled cards after hydration) is ACCEPTED.
  • (b) The host MAY write the list HTML (C# template; this repo delivers the spec and the golden files): YES.

It starts as a separate feature after the current merges (contact-form-cms, then asf-packages-cms), not through them. To be built together with SLP Modular CMS - SMC - Main, who owns the host side.

Why

Hosting decision (2026-11-15): the CMS host is the one entry of the website and serves the prerendered pages, /admin and /api/v1/*; IIS passes everything to it. A CMS change (packages, banners, later gallery and hero) must then be visible to search engines at once, with no rebuild. The host injects the current data into the prerendered HTML through markers (as on SLP, 60 s cache).

What is CMS data on the pages today

Packages: the price cards (home), the shoot list and shoot blocks, the "welke shoot" choices of the contact form, the ?pakket= check, the offer price in the JSON-LD of the shoot pages. Banners: the slim top bar and the band under the cards. See docs/cms-integration.md.

Proposal

1. Three kinds of markers (built into the page by the ASF build, filled by the host)

  • Data block, one per page: <script type="application/json" id="cms-data">…</script> holding the raw answers of GET /api/v1/offerings and both banners. The host replaces its content with the current answers (JSON-escaped: <, >, &, U+2028/2029). It is a non-executable block, so the CSP stays as it is and the build step that moves inline scripts treats it as data (as it does for ld+json).
  • Region, for lists that differ in length (the cards, the banners): a wrapper <div data-cms-region="offerings"> whose content is the neutral HTML. The host replaces everything between <!--cms:offerings--> and <!--/cms:offerings--> (written into the wrapper by the build; React cannot emit comments, so the build writes them through dangerouslySetInnerHTML).
  • Inline value, for a single price or name inside a sentence: <span data-cms-price="newborn">€ 185</span>. The host replaces the text.
  • JSON-LD price of a shoot page: the ld+json block gets data-cms-offer="newborn"; the host sets offers.price from the live package (or removes offers when the package is gone or has no readable price).
  • The same marker format as SLP, if SLP already has one (to be confirmed by SMC).

2. Neutral HTML in the markers

The build puts crawlable, simple semantic HTML between the markers (package name, price, features, a plain link to /?pakket=<slug>#contact; the banner as an aside), written from the baked data by one pure function (web/src/lib/neutralHtml.ts, all text escaped). The host produces the same markup from live data (template in C#; the ASF repo delivers the spec and golden files, SMC implements, a contract test in each repo checks both sides against the same fixtures). Light static CSS in the page makes it look acceptable (the section is below the fold). Why not exact copies of the styled cards: Chakra/Emotion class names and styles are generated at build time, a C# template cannot reproduce them.

3. Hydration: read the JSON, do not fetch

  • PackagesProvider takes its initial state from the data block (reusing mapOfferings, mapBanner, mapTopBanner), not from the baked import and not from a fetch after hydration. Without a block (preview, tests, a host that does not inject) it falls back to the baked data plus the live fetch it has today, so nothing is lost.
  • Regions are not hydrated by React (dangerouslySetInnerHTML with suppressHydrationWarning, so React keeps the server DOM). After hydration (useHydrated) the styled React components render into the region and replace the neutral HTML. So the first paint is the neutral HTML, and a brief change of look follows; the cards are below the fold, and the region keeps a minimum height to avoid a layout shift.
  • Inline values hydrate directly from the same data (suppressHydrationWarning for the formatting difference).
  • The contact form choices and ?pakket= read the same state, so they agree with what the host injected.

4. Hydration and contract tests (per marker, before anything ships)

  • Build test: every expected marker exists exactly once per page, in the final dist/ (after the script-moving step), and the neutral HTML equals what the pure function gives.
  • E2E in real Chrome with a stand-in injector in the preview server (same algorithm as the host, fixtures with more, fewer and different packages, with and without banners, an unreadable price, a hostile text such as <script>): no hydration or console error, the final DOM shows the injected data, the layout shift stays under the CLS limit.
  • Fail-safe tests: marker missing, data block empty or invalid, host injection off: the page shows the baked data.
  • Contract tests with golden fixtures shared with the CMS repo (marker format, escaping, the neutral HTML, the JSON-LD price edit).
  • Security: all CMS text is HTML-escaped by the host; the data block is escaped as above; no executable inline script appears.

5. Build and deploy consequences

  • The build no longer needs the CMS: the baked data is only the fallback, so build-test with OFFERINGS_URL and the nightly content build can go. One artifact can serve test and production.
  • Optional: the test address (VITE_SITE_URL) could become a host replacement like SLP's Website:AuthoredBaseUrl, which would make the artifact identical for test and production. Needs the injector on ASF's prerendered-pages host; to ask SMC.
  • Production deploy changes with the hosting: dist/ goes to the CMS host's prerendered-pages folder (as on test). The generated IIS config reduces to redirects and pass-through. See the Hosting section of the CMS integration doc.
  • The safety net of AI-DLC: a pipeline option (debounced rebuild after a CMS change) stays possible for build-processed gallery images later.
  • 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. The block the build bakes carries "source":"build" (the host replaces the whole block, so the live one has no source); the site treats a block with that source as "no host data" and asks the API itself, as before the injection existed. 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.
  2. Pure neutral-HTML function, build writes the markers, build tests.
  3. PackagesProvider reads the data block, regions, inline values, JSON-LD price; stand-in injector in the preview server; e2e and fail-safe tests.
  4. SMC implements the injector with the same fixtures; test on ASF test.
  5. Hosting switch for production (separate), then remove the nightly content build.

Open questions

  • For SMC: the marker format SLP uses today; how the injector reads and edits JSON and ld+json; behaviour when data or a marker is missing (must fail open: serve the baked page); caching and ETag; whether AuthoredBaseUrl can also run on the prerendered-pages host.
  • For Bryan: (answered, see the decisions at the top) accept a brief look change of the cards on first paint, and let the host write the list HTML? Both yes. The alternative that was not chosen: one set of cards styled by plain CSS and owned by the host, with no React in those regions.