From 358fca0855307c5ce5b24ff884d198d0b4a9de12 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Tue, 17 Nov 2026 09:25:45 +0100 Subject: [PATCH] Hero module: closing docs (state, build and test summary, assumptions, go-live checklist) Co-Authored-By: Claude Sonnet 5.5 --- aidlc-docs/active-features.md | 2 +- .../features/hero-module/aidlc-state.md | 30 +++++++++++++++ .../assumptions-and-open-questions.md | 37 ++++++++++++------- .../build-and-test/build-and-test-summary.md | 22 +++++++++++ docs/go-live-checklist.md | 6 +++ 5 files changed, 83 insertions(+), 14 deletions(-) create mode 100644 aidlc-docs/features/hero-module/aidlc-state.md create mode 100644 aidlc-docs/features/hero-module/construction/build-and-test/build-and-test-summary.md diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index 1c67f21..056637d 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -17,4 +17,4 @@ | Feature | asf-packages-cms | ✅ Complete (closed 2026-11-16; PR to master after the CMS PR; no production release) | feature/asf-packages-cms (worktree ../AndreaSlopFotografie-packages, based on feature/contact-form-cms) | web/config (offerings, fetchOfferings), web/src/content (packages, snapshot, types), Pricing + PriceBanner + PriceTopBar (two banners, centred card rows), PackagesProvider (live refresh), CI build-test job and nightly test build, docs/ (CMS integration, deploy and CI, go-live checklist) | 2026-11-12 | | Feature | asf-cms-host-injection | ✅ Complete on the ASF side (2026-11-16, delivered with asf-packages-cms; host side by SMC) | feature/asf-packages-cms | web (PackagesProvider, build markers, neutral HTML), preview server stand-in injector, e2e/contract tests; host side in the SlpModularCms repo | 2026-11-15 | | Feature | asf-translation-files | ✅ Complete on the ASF side (2026-11-16, delivered with asf-packages-cms) | feature/asf-packages-cms | web/src/i18n (nl.json, helpers), content modules, components, ESLint rules, baseline tool, docs/translations.md | 2026-11-15 | -| Feature | hero-module | 🟡 Construction (ASF side built; waiting for the CMS test run) | feature/hero-module | Hero as a manageable CMS module (SMC builds the module, ASF consumes it); LCP in the first HTML via host injection or prerender; static hero texts move into it | 2026-11-16 | +| Feature | hero-module | ✅ Complete on the ASF side (2026-11-17; branch ready to merge, no production) | feature/hero-module | Hero as a manageable CMS module (SMC builds the module, ASF consumes it); LCP in the first HTML via host injection or prerender; static hero texts move into it | 2026-11-16 | diff --git a/aidlc-docs/features/hero-module/aidlc-state.md b/aidlc-docs/features/hero-module/aidlc-state.md new file mode 100644 index 0000000..cc7ce35 --- /dev/null +++ b/aidlc-docs/features/hero-module/aidlc-state.md @@ -0,0 +1,30 @@ +# AI-DLC State Tracking + +## Project Information + +- **Feature Name**: Hero as a manageable CMS module (ASF side) +- **Feature Slug**: hero-module +- **Project Type**: Brownfield (cross-repo: SMC builds the module and the host injection of the hero; this repo consumes it, supplies markers, contract and golden files) +- **Start Date**: 2026-11-16 +- **Current Stage**: COMPLETE on the ASF side (closed 2026-11-17); branch feature/hero-module, to be merged to master by SLS-Main. No production deploy. + +## Language Configuration + +- **Documentation Language**: English +- **Conversation Language**: User Language (Dutch) + +## Stage Progress + +- [x] INCEPTION - requirements and contract agreed with SMC (`web/contract/host-injection/hero/README.md`, model B: wide 3:2 and tall 4:5 variants, ``, preload per orientation) +- [x] CONSTRUCTION - Code Generation: markers HERO-HTML and HERO-PRELOAD, `hero` key in `#cms-data`, `useHero` with baked fallback, plain-HTML first photo that survives hydration, slider on top, hero texts in `nl.json`, stand-in host and preview server, e2e tests, docs +- [x] CONSTRUCTION - Build and Test: [build-and-test-summary.md](construction/build-and-test/build-and-test-summary.md) +- [x] OPERATIONS - part of the joint production checklist ([docs/go-live-checklist.md](../../../docs/go-live-checklist.md), section "Hero"); production follows via the IIS pipeline, later + +## Scope decisions + +- **Planning (from/to dates) and a hero-wide on/off switch are deliberately not built.** The hero is always there; a hero without usable slides leaves the baked hero in place (for ASF the host setting `Hero:TextOnlyRegion` is off). Adding them later is a CMS change plus a `204`, which the site already handles. +- The ASF test seed holds the 8 existing hero photos with focus estimates (`web/contract/host-injection/hero/seed.json`); Bryan runs the seed himself (admin password). + +## Assumptions + +[assumptions-and-open-questions.md](assumptions-and-open-questions.md): what Bryan has to check later. diff --git a/aidlc-docs/features/hero-module/assumptions-and-open-questions.md b/aidlc-docs/features/hero-module/assumptions-and-open-questions.md index fac271b..15e1105 100644 --- a/aidlc-docs/features/hero-module/assumptions-and-open-questions.md +++ b/aidlc-docs/features/hero-module/assumptions-and-open-questions.md @@ -2,16 +2,27 @@ Written while Bryan was away; he decides later. Each point: question, assumption, what changes with another answer, where in the code. -| # | Question | Assumption | If the answer differs | Where | -|---|----------|------------|-----------------------|-------| -| 1 | Focus points of the 8 photos | Estimates from the seed (e.g. hero-8 0.50/0.55) | Change x/y in the seed (CMS) and in the baked values | `web/src/content/heroContent.ts`, `web/contract/host-injection/hero/seed.json` | -| 2 | Is the baked hero cropped around the focus point too? | Yes: object-position from the estimates, so baked and live look the same | Pass `focus: null` for the baked slides to get plain centre crop | `heroContent.ts` | -| 3 | Button target `#anchor` and https: plain link, `/path`: router link | As said | Make all plain links | `web/src/components/Hero/HeroButton.tsx` | -| 4 | Single display (one photo) or slideshow with one slide | No arrows, pause or progress bar for one slide | Show controls anyway | `Hero.tsx` (`shown.length > 1`) | -| 5 | Title with a new line | `
` in the plain HTML, `pre-line` in the slider | One line only | `heroHtml.ts`, `Hero.tsx` | -| 6 | Where does the head preload marker come from | Build step adds it to the finished HTML (React cannot write a head comment) | Host adds the head region itself | `web/config/heroPreload.ts` | -| 7 | Hero texts (aria, baked title, alts) | In `nl.json`, block `hero` | Other wording: edit the file | `web/src/i18n/nl.json` | -| 8 | Without a host block the site asks `/api/v1/hero` (8 s time-out) | Yes, like packages and banners | Remove the call: baked only | `web/src/components/Hero/useHero.ts` | -| 9 | Style of the plain hero before hydration | Matches the slider's first frame (checked by screenshot at 1280 and 390 px) | Adjust CSS | `.cms-hero-*` in `web/src/theme.ts` | -| 10 | AVIF for slides 2..n only | As agreed with the CMS session | Add AVIF to the first photo and its preload (then two fetches) | `Hero.tsx` (`SlidePicture`) | -| 11 | The first photo, title and buttons stay the plain HTML after hydration (never replaced); the slider adds the other photos on top | Yes: replacing the nodes at hydration risks a late LCP. Side effect: the first photo has no slow zoom and is not in a role=group slide | Go back to a full slider render (one component), accepting the DOM replacement | `Hero.tsx` (`HeroFrame`), `useHero.ts` (`regionHero`) | +| # | Question | Assumption | If the answer differs | Where | +| --- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| 1 | Focus points of the 8 photos | Estimates from the seed (e.g. hero-8 0.50/0.55) | Change x/y in the seed (CMS) and in the baked values | `web/src/content/heroContent.ts`, `web/contract/host-injection/hero/seed.json` | +| 2 | Is the baked hero cropped around the focus point too? | Yes: object-position from the estimates, so baked and live look the same | Pass `focus: null` for the baked slides to get plain centre crop | `heroContent.ts` | +| 3 | Button target `#anchor` and https: plain link, `/path`: router link | As said | Make all plain links | `web/src/components/Hero/HeroButton.tsx` | +| 4 | Single display (one photo) or slideshow with one slide | No arrows, pause or progress bar for one slide | Show controls anyway | `Hero.tsx` (`shown.length > 1`) | +| 5 | Title with a new line | `
` in the plain HTML, `pre-line` in the slider | One line only | `heroHtml.ts`, `Hero.tsx` | +| 6 | Where does the head preload marker come from | Build step adds it to the finished HTML (React cannot write a head comment) | Host adds the head region itself | `web/config/heroPreload.ts` | +| 7 | Hero texts (aria, baked title, alts) | In `nl.json`, block `hero` | Other wording: edit the file | `web/src/i18n/nl.json` | +| 8 | Without a host block the site asks `/api/v1/hero` (8 s time-out) | Yes, like packages and banners | Remove the call: baked only | `web/src/components/Hero/useHero.ts` | +| 9 | Style of the plain hero before hydration | Matches the slider's first frame (checked by screenshot at 1280 and 390 px) | Adjust CSS | `.cms-hero-*` in `web/src/theme.ts` | +| 10 | AVIF for slides 2..n only | As agreed with the CMS session | Add AVIF to the first photo and its preload (then two fetches) | `Hero.tsx` (`SlidePicture`) | +| 11 | The first photo, title and buttons stay the plain HTML after hydration (never replaced); the slider adds the other photos on top | Yes: replacing the nodes at hydration risks a late LCP. Side effect: the first photo has no slow zoom and is not in a role=group slide | Go back to a full slider render (one component), accepting the DOM replacement | `Hero.tsx` (`HeroFrame`), `useHero.ts` (`regionHero`) | +| 12 | Planning (from/to dates) and a hero-wide on/off switch | Deliberately not built: the hero is always there, a hero without usable slides keeps the baked one | Add in the CMS; the site already handles a 204 and an empty hero | CMS (module), `useHero.ts` | +| 13 | Content of the ASF test seed | The 8 existing photos with focus estimates (#1), texts like the baked ones | Edit in the CMS admin; update `heroContent.ts` if the baked fallback should match | `web/contract/host-injection/hero/seed.json` | +| 14 | Baked hero after a CMS change | The baked hero is only a fallback and is not rebuilt from the CMS any more (no nightly build) | Re-bake by hand in `heroContent.ts` when the real hero changes for good | `heroContent.ts` | + +## What Bryan has to check later + +- Look at the home page on ASF-test after the seed, on phone and desktop: crop around the focus points (#1, #2), the first frame before the slider starts (#9, #11), the title and buttons (#3, #5). +- Does the first photo without slow zoom (#11) bother you? Then choose the full slider render and accept the later LCP. +- Wording of the hero texts in `nl.json` (#7). +- Whether planning and an on/off switch are wanted (#12). +- Keep an eye on the LCP of `/` in the Lighthouse run on test (the host measures it after the seed). diff --git a/aidlc-docs/features/hero-module/construction/build-and-test/build-and-test-summary.md b/aidlc-docs/features/hero-module/construction/build-and-test/build-and-test-summary.md new file mode 100644 index 0000000..f31ccdd --- /dev/null +++ b/aidlc-docs/features/hero-module/construction/build-and-test/build-and-test-summary.md @@ -0,0 +1,22 @@ +# Build and Test summary: hero-module (ASF side) + +## What was built + +- `src/lib/hero.ts` (mapping and validation of `/api/v1/hero`), `src/lib/heroHtml.ts` (HTML between the markers and the preload links), golden files shared with SMC in `web/contract/host-injection/hero/`. +- `config/heroPreload.ts` adds the HERO-PRELOAD region to the head of the finished HTML; `config/hostInjector.ts`, `normalizeInjected.ts` and `previewServer.ts` know the hero (stand-in host, `/api/v1/hero` answers 204). +- `src/components/Hero/`: `useHero` (host block, else `/api/v1/hero`, else baked), `Hero.tsx` (the region div is never replaced; the slider adds slides 2..n, scrim, arrows, pause, progress and announcement after hydration), `HeroButton`, `HeroArrows`, `HeroPauseButton`. +- Baked hero in `src/content/heroContent.ts` (8 photos, real sizes, focus estimates); texts in `nl.json` block `hero`. + +## Verification + +- Unit and property tests: 100% thresholds on `src/lib/**`, `src/i18n/**`, `seo.ts`, `sitemap.ts` hold; golden files match for all hero inputs. +- e2e (`pnpm e2e`): host injection with the hero (3 tests), no-JS, display HTML (priority image), reveal. The two frame-sampling reveal tests got retries (2 on CI, 1 locally) after a flaky failure in run #110 on a page without a hero. +- Lighthouse (local, noisy machine): the LCP element of the home page is the h1 on master and on this branch; master 0.71, branch 0.69-0.70. Keeping the region after hydration (commit 3d7bb2d) removed the late LCP the first design had. +- Visual check against the slider at 1280 and 390 px. +- Final run before merge: see the audit trail of the closing commit; lint, format, tests, build and e2e were run as CI runs them. + +## Not verified here (needs the CMS or Bryan) + +- The real host output on ASF-test after the seed (SMC verified it byte-equal to the golden files locally). +- LCP measurement on ASF-test (SMC, after the seed). +- IIS pass-through and a production CMS for ASF: later, separate feature. diff --git a/docs/go-live-checklist.md b/docs/go-live-checklist.md index da76795..e97b7a9 100644 --- a/docs/go-live-checklist.md +++ b/docs/go-live-checklist.md @@ -13,6 +13,12 @@ What must be true before the CMS-driven parts of the site go to production. Brya - [ ] `web/src/content/offerings.snapshot.json` holds the real, current packages (production builds use it). - [ ] The production CMS holds the real packages. The test CMS prices must never end up in the production artifact (it is built without `OFFERINGS_URL`). +## Hero + +- [ ] The hero module is on `master` and the CMS host of the target environment has the hero module and the injection (`HERO-HTML`, `HERO-PRELOAD`, `hero` in the data block). +- [ ] ASF-test: the hero is seeded (Bryan runs the seed, admin password) and the home page checked on phone and desktop; the assumption list `aidlc-docs/features/hero-module/assumptions-and-open-questions.md` is read. +- [ ] Production: ASF-production is served by the CMS host (the IIS pipeline, later) and holds the real hero. Until then production shows the baked hero in `src/content/heroContent.ts`; check that it is the one you want. + ## Contact form - [ ] All conditions in the contact-form production readiness checklist (server module, recipient, sender, retention 1 year / 30 days spam, proxies, CSP `frame-src`, a real mail from the production host).