Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/plans/display-fallbacks-code-generation-plan.md
T
2026-11-01 01:46:30 +01:00

530 lines
70 KiB
Markdown

# Code Generation Plan - Unit 2: Display fallbacks
Feature: prerendering. Unit: 2 "display-fallbacks" (fade-in, no JavaScript, first photo). This plan is the single source of truth for Code Generation (Part 2). Execute the steps in order, mark each checkbox `[x]` as soon as its "Done when" is met, and do not deviate from the plan.
## 0. Context an executor needs
### 0.1 What is built
The site is React 19.3 + TanStack Start static prerendering + Chakra UI v3 in `web/`, hosted statically (nginx on test, IIS on production) with a strict CSP (`script-src 'self'` + Umami; `style-src 'self' 'unsafe-inline'`). Unit 1 is built: every page is a prerendered HTML file, inline scripts are moved to files by a build step that fails on violations, and the hydration rule holds: the first browser render equals the HTML; browser-only values apply afterwards (`useHydrated`, server-safe defaults).
Unit 2 covers FR-PR-09 to 13, FR-PR-21 and the no-JavaScript side of FR-PR-22, plus NFR-PR-P-01 and P-03 (measurement), NFR-PR-Q-01 and Q-03 (tests), NFR-PR-SEC-01. It does five things:
1. `Reveal` is visible in the HTML and in the first browser render; after hydration only an element wholly below the viewport is hidden (without transition) and fades in on scroll (BR-RVL).
2. `DeferredImage` gets a `<noscript>` twin so photos show without JavaScript, with the empty image hidden by CSS (BR-IMG).
3. The mobile menu works without JavaScript through `<noscript>` links and `:target` CSS, the desktop shoot submenu opens on keyboard focus, and controls that do nothing are hidden (BR-NAV, BR-NJS). All no-JavaScript CSS lives in one `<noscript><style>` in the document `<head>`.
4. First-photo preload: React already writes the preload for plain high-priority photos; unit 2 adds the explicit `media` links for `/contact` (aside photo) and `/portfolio` (first row of the grid, tiles 2 and 3), avoids useless preloads, and makes the first row of the portfolio grid eager (BR-PRE).
5. Measurement of the result, including the explicit comparison for `/portfolio` (BR-DMS).
Out of scope (do not build, do not "prepare"): nginx, IIS, `config/serverConfig.ts`, `deploy/`, the CI deploy jobs, Lighthouse targets in `lighthouserc.cjs` and `lighthouserc.desktop.cjs` (never edit them), responsive photos (`srcset`, resizing the 500 x 500 logos), the Contact form back-end, any new dependency. If a step seems to need one of these, STOP.
There are no user stories; the unit is traced to requirements. Dependencies on other units: unit 1 (done). Unit 3 depends on this unit.
### 0.2 Files to read (design, all under `aidlc-docs/features/prerendering/`)
1. `construction/display-fallbacks/functional-design/business-rules.md` (rules BR-RVL, BR-IMG, BR-NAV, BR-NJS, BR-PRE, BR-DMS, BR-DTS; § 4 verification points V-D1 to V-D15; § 5 final owner decisions). Rule ids in this plan refer to it.
2. `construction/display-fallbacks/functional-design/business-logic-model.md` (flows, evidence, properties P18 to P25).
3. `construction/display-fallbacks/functional-design/domain-entities.md` (reveal phases, markers, ids, preload link, first row).
4. `construction/display-fallbacks/functional-design/frontend-components.md` (per-component contract, call sites, test list).
5. `construction/start-migration/functional-design/business-rules.md` (BR-HYD, BR-MAIL, BR-LZY, BR-TST, BR-SCR) and `construction/start-migration/code/code-summary.md`, `verification-log.md`, `measurement-gate.md`.
6. `inception/requirements/requirements.md` (FR-PR-09 to 13, 21, 22) and `inception/application-design/application-design.md` (D6 to D9).
Read 1 to 4 completely before the first step of your batch.
### 0.3 Locations and commands
- Worktree (work only here): `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-prerendering`, branch `feature/prerendering`. It already has `node_modules`. Application code under `web/`, documentation under `aidlc-docs/`. Never put application code in `aidlc-docs/`.
- Run commands from `web/`. Package manager: pnpm. Scripts: `pnpm lint`, `pnpm format:check` (fix with `pnpm exec prettier --write <files>`), `pnpm test` (vitest with coverage and thresholds), `pnpm build` (tsc, Start build with prerender, script step), `pnpm e2e` (browser tests against `dist/client`), `pnpm audit:deps`, `pnpm audit:dev`.
- Targeted tests while working: `pnpm exec vitest run <path>` (no coverage). Full suite only at checkpoints. Browser tests: `pnpm exec vitest run --config vitest.e2e.config.ts <file>`.
- Shell is Git Bash on Windows (also PowerShell). In Git Bash a path argument starting with `/` is rewritten; set `MSYS_NO_PATHCONV=1` before commands that take URL paths such as `/portfolio`. Use plain `rm`/`cp`, never `git rm`/`git mv`.
- Browser probes (Steps 2 to 4, 24 to 26) are scratch `.mjs` scripts kept outside the repository, in a scratch folder (for example `$env:TEMP\prerendering-display`). They load `playwright-core` through `createRequire('<web>/package.json')`, start `startPreviewServer(<web>/dist/client, 0)` from `config/previewServer.ts` (import it by `file://` URL; Node 24 strips types), and launch Chrome with `executablePath: process.env.CHROME_PATH` or `channel: 'chrome'`, as `e2e/support/browser.ts` does.
- Verification points V-D1 to V-D15 are recorded in ONE file: `aidlc-docs/features/prerendering/construction/display-fallbacks/code/verification-log.md` (created in Step 1: a table with columns V-D#, Point, Step, Outcome, Evidence, Status OK/BLOCKED/DEVIATION). Update the row in the step that settles it.
- Reports and summaries are markdown only, in `aidlc-docs/features/prerendering/construction/display-fallbacks/code/`.
### 0.4 Rules for every executor
1. **No git write commands** (`add`, `commit`, `push`, `stash`, `reset`, `checkout --`, `rm`, `mv`, branch operations). `git status`, `git diff`, `git log`, `git rev-parse` are allowed. The main session commits and pushes, only when the owner approved. Never edit `aidlc-docs/features/prerendering/audit.md`, `aidlc-state.md` or `inception/requirements/requirements.md`; the main session does.
2. **Install nothing.** This unit adds no dependency: no `pnpm install`, `pnpm add`, `pnpm remove`. Do not edit `pnpm-lock.yaml` or `pnpm-workspace.yaml`.
3. **STOP rule.** If a verification point (V-D) fails, a design rule cannot be implemented as written, a step's "Done when" cannot be reached, a fix would change a design decision (any BR rule, any owner decision O1 to O5, any decision D1 to D13), or **a tool call is denied**: stop at once. Write the finding in the verification log (Status BLOCKED or DEVIATION, with the exact error output and what you tried), leave the tree in a state where `pnpm exec tsc --noEmit` still runs (revert only your own unfinished edits of that step), do not continue with later steps, do not get the same result another way, and return a report to the main session naming the step, the V-D point or rule, the evidence and the options you see. Never improvise around a design decision, never weaken a check, never delete or skip a test to get green.
4. **Match the surrounding code.** Open the neighbouring files first and copy their idiom: 4-space indentation, single quotes, trailing commas (Prettier config in `web/.prettierrc`), `@/` alias in `src/`, relative imports with explicit `.ts` extension in `config/` only. Comments explain why, not what; density like the neighbours. Language of new comments, test titles and messages follows the neighbouring files (hooks, `lib` implementations and newer components are English; `e2e/` and parts of the older code are Dutch). **No comment may name a plan step or this plan** ("Step 7", "see the plan"); rule ids such as `BR-RVL-03` are allowed, as in neighbouring code.
5. **Existing tests stay valid.** Change an existing test only where § 6 names it, and say so in the step's Record. Never loosen an assertion to get green.
6. **Automation-friendly code.** Every new interactive element gets a stable `data-testid` named `{component}-{role}` like the existing ones. New testids in this unit: `nav-noscript-open`, `nav-noscript-close`.
7. **Coverage.** Thresholds are 100 % for `src/lib/**`, `src/seo.ts`, `src/sitemap.ts`; every new or changed function and branch there needs tests in the same batch.
8. **Property-based tests** (fast-check, already a dependency): use the global seed from `config/testSeed.ts` (never set a `seed` yourself, never disable shrinking), put domain generators in shared files under `src/test/` (reuse `src/test/arbitraries.ts`: `contentImage`, `galleryItem`, `galleryItems`, `portfolioPhotos` and others; new generators go in the new files named in the steps), label each property test with its category in the title like the existing ones (`(invariant)`, `(idempotent)`, `(metamorphic)`, `(oracle)`, `(round-trip)`), and keep an example-based test next to it.
9. **Hydration tests** (lesson from unit 1): a test that hydrates a page must let Router's own `hydrate()` run, through `hydrateAppAsStart` from `src/test/hydrate.tsx`. `hydrateApp` loads the client router first and hides mismatches Start would show. Component-level hydration of a single element may use `hydrate()` from the same file; page-level never.
10. **Tests never go in `src/routes/`.** The route generator reads every file there and treats a test as a route. Page-level tests live in `src/` root (`src/displayHydration.test.tsx`, `src/displayPrerender.test.tsx`).
11. **`dist` must be a current build whenever `pnpm e2e` or a browser probe runs.** Run `pnpm build && pnpm e2e` in one command line after any source change, and before a probe run `pnpm build` yourself. A stale `dist` gives false passes and false failures (it did in unit 1). Never run `pnpm e2e` after editing only tests without checking `dist` is newer than the last source edit (`ls -l --time-style=full-iso dist/client/index.html` against `git status`).
12. **Concurrent batches** (§ 2): while batches run in parallel, run only targeted `vitest run <file>` and `tsc --noEmit`, never `pnpm build`, `pnpm test`, `pnpm e2e` or a probe, and only touch the files your batch owns.
13. **Background jobs.** Lighthouse, builds and e2e runs may be started in the background, but an executor must wait for every job it started (poll the output file with an until-loop; do not `sleep`-chain) before reporting. If you must report earlier, say clearly in the first line that the report is **interim**, name the job and its output path.
14. **Measurement conditions** (Steps 24 to 27): port 4173 must be free (`Get-NetTCPConnection -LocalPort 4173` returns nothing); the main session claims and releases the port with peer sessions, an executor never kills a process on it and never claims it for itself; if it is busy, STOP and say so. No CPU-heavy work during a measurement: no build, test run, probe, install, editor indexing or other sub-agent. Same machine, power plan and Node version for all runs of the unit.
15. Mark the step `[x]` in this file when done and add one line under "Record" if the step asks for it. Keep the tree compiling after each step (`pnpm exec tsc --noEmit`).
## 1. Checkpoints
| CP | After | State required |
|---|---|---|
| CP0 | Step 1 | Baseline green: lint, format, test, build, e2e on the untouched tree; verification log created |
| CP1 | Step 5 | V-D1, V-D2, V-D3, V-D13 settled OK (or STOP); `pnpm exec tsc --noEmit`, `pnpm lint`, `pnpm build` green; `pnpm test` green except the tests named in Step 5 |
| CP2 | Steps 6 to 14 all done (merge point after the parallel batches) | `pnpm test` fully green with coverage thresholds, `pnpm lint`, `pnpm format:check`, `pnpm exec tsc --noEmit`, `pnpm build` |
| CP3 | Step 21 | `pnpm build && pnpm e2e` green with the new and the adjusted browser tests |
| CP4 | Step 23 | Full verification green: lint, format, test, build, e2e, audit:deps, audit:dev |
| CP5 | Step 27 | Measurement done, temporary D change restored (checksum equal, `git status` equal to before), `dist` rebuilt from the real code |
## 2. Batches, executors and parallelism
One sub-agent takes one batch. Haiku (H) does mechanical work, running checks, measurements and log keeping; Sonnet (S) does code, tests and documents that need judgement. The executor per step is repeated in the step.
| Batch | Steps | Executor | Parallel with | Files owned (disjoint from the parallel batches) |
|---|---|---|---|---|
| B0 Setup and baseline | 1 | H | none (exclusive: CPU) | verification log, baseline file |
| B1 Early proofs | 2 to 5 | S | none (sequential; risky unknowns first) | `src/lib/revealPhase.ts`, `src/hooks/useReveal.ts`, `src/components/Reveal/Reveal.tsx`, `src/components/DeferredImage/DeferredImage.tsx`, `src/components/NoScript/noScriptCss.ts` (first version), `src/components/NoScript/NoScriptStyles.tsx`, `src/routes/__root.tsx`, `src/lib/firstRow.ts`, `src/seo.ts`, `src/components/PortfolioGrid/PortfolioGrid.tsx`, `src/components/portfolio/PortfolioGallery/PortfolioGallery.tsx`, `src/routes/portfolio.tsx`, `src/displayHydration.test.tsx` (first test) |
| B2 No-JavaScript menu | 6 to 8 | S | B3, B4 | `src/components/NoScript/noScriptCss.ts` (extend), `src/components/NoScript/noScriptCss.test.ts`, `src/components/NavigationBar/**` |
| B3 Markers and preload hygiene | 9 to 11 | S | B2, B4 | `src/components/Hero/**`, `src/components/FilterBar/**`, `src/components/home/Testimonials/**`, `src/components/Footer/**`, `src/components/ContactDetails/**`, `src/routes/contact.tsx` |
| B4 Reveal, image and first-row tests | 12 to 14 | S | B2, B3 | `src/test/revealArbitraries.ts`, `src/test/firstRowArbitraries.ts`, `src/lib/*.test.ts` (revealPhase, firstRow), `src/seo.test.ts`, `src/hooks/useReveal.test.tsx`, `src/components/Reveal/Reveal.test.tsx`, `src/components/DeferredImage/DeferredImage.test.tsx`, `src/components/PortfolioGrid/PortfolioGrid.test.tsx`, `src/components/portfolio/PortfolioGallery/PortfolioGallery.test.tsx`, `src/displayHydration.test.tsx`, `src/displayPrerender.test.tsx` |
| B5 Browser tests | 15 to 21 | S for 15 to 20, H for 21 | none (after CP2) | `e2e/**` |
| B6 Finish | 22, 23 | S for 22, H for 23 | none | comments in changed files; no new files |
| B7 Measurement | 24 to 27 | H for runs, S for the report | none (exclusive: port 4173 and CPU) | scratch folder, `measurement-display.md`, the temporary D change |
| B8 Documents | 28, 29 | S | none | `aidlc-docs/**` |
B2, B3 and B4 may run at the same time because their files are disjoint (B4 only reads the components B2 and B3 change, and its component tests do not depend on their markers). If you run them one after another, the order B4, B3, B2 is fine. In B5 the files of Steps 15 to 20 are disjoint and may be *written* in parallel by separate agents, but they are *run* only one process at a time and only against a current `dist` (rule 11); Step 21 runs them. B6 and later wait for CP3.
## 3. Traceability
### 3.1 Properties (PBT-01) to steps
| Property | Function | Category | Test step |
|---|---|---|---|
| P18 | `startsHidden` | Invariant | 13 |
| P19 | `startsHidden` | Metamorphic (monotonic, translation) | 13 |
| P20 | `nextRevealPhase` | Invariant (state machine) | 13 |
| P21 | `nextRevealPhase` | Idempotence | 13 |
| P22 | `preloadImage` | Invariant | 13 |
| P24 | `firstRow` | Invariant | 13 |
| P25 | `firstRow`, `firstRowPreloads` | Metamorphic (monotonic) | 13 |
P23 of the design is an example test on one constant, not a property: Step 8 (BR-NAV-02). PBT-06 (stateful): `nextRevealPhase` is a three-state machine tested by P20 over generated event sequences. PBT-07 (generators): `src/test/revealArbitraries.ts`, `src/test/firstRowArbitraries.ts`, reuse of `arbitraries.ts` (`contentImage`, `galleryItems`). PBT-08: global seed, shrinking left on. PBT-10: each property test has its category label and an example-based sibling. Components with no properties are listed in business-logic-model.md § 7.
### 3.2 Verification points to steps
| V-D | Settled in step | Recorded in |
|---|---|---|
| V-D1 `useLayoutEffect` in `Reveal`: prerender, hydrate, StrictMode | 2 | verification log |
| V-D2 twin never requested with JavaScript on; one Emotion class | 3 | verification log |
| V-D3 `noscript` in head, header and panel hydrate cleanly; head CSS stays in head | 3 (head, twin), 7 (header and panel) | verification log |
| V-D4 fragment navigation to a fixed element in Firefox, Safari, Android Chrome | not plannable (see § 5); Chrome part in 18 | verification log |
| V-D5 portfolio comparison E against D | 26 | measurement-display.md, verification log |
| V-D6 height of every `Reveal` against the limit | 18 | verification log |
| V-D7 lazy logos and contact portrait effect; no logo flash | 24, 25 | measurement-display.md |
| V-D8 raw-HTML tests with `noscript` content | 20 | verification log |
| V-D9 visible focus ring of the two menu links | 17 | verification log |
| V-D10 hero photo and LCP in a trace | 25 (only if a trace exists) | measurement-display.md |
| V-D11 React hoisting facts | 15 | verification log |
| V-D12 visual check without JavaScript at 390 and 1280 px | 16 | verification log |
| V-D13 `<picture>` first-row tiles: size, zoom, focus, one request, hydration | 4 (proof), 14 (test), 19 (e2e) | verification log |
| V-D14 largest-paint tile per width after the change | 25 | measurement-display.md |
| V-D15 `?shoot=` with first-row preloads: no URL twice | 19 | verification log |
### 3.3 Requirements and rules to steps
| Requirement | Rules | Steps |
|---|---|---|
| FR-PR-09 | BR-RVL-01 to 14 | 2, 12 to 14, 18 |
| FR-PR-10 | BR-RVL-07 | 2, 14, 18 |
| FR-PR-11 | BR-IMG-01 to 10; BR-RVL-01 | 3, 14, 16, 19 |
| FR-PR-12 | BR-NAV-01 to 12 | 3, 6 to 8, 17 |
| FR-PR-13 | BR-NJS-01 to 11; BR-IMG-07, 08 | 9, 11, 16 |
| FR-PR-21 | BR-PRE-01 to 12 | 4, 7, 10, 11, 15, 19 |
| FR-PR-22 (no-JS side) | BR-NJS-02 | 9, 16 |
| NFR-PR-P-01, P-03 | BR-DMS-01 to 05 | 24 to 27 |
| NFR-PR-Q-01, Q-03 | BR-DTS-01 to 05 | 8, 11, 13 to 21, 23 |
| NFR-PR-SEC-01 | BR-NAV-02 | 8, 15 |
| NFR-PR-S-01 | accessibility notes | 8, 17 |
---
## Part A: Setup and baseline (batch B0, Haiku, exclusive)
### Step 1: Confirm a green baseline and create the log [x]
- Executor: Haiku.
- Implements: NFR-PR-Q-01 (baseline), setup.
- Do (in `web/`; do not install anything):
1. `git rev-parse HEAD`, `git branch --show-current` (must be `feature/prerendering`), `git status --short` (expected: clean apart from untracked `web/.tanstack/` and possibly docs; write what you see).
2. Run `pnpm lint`, `pnpm format:check`, `pnpm test`, `pnpm build && pnpm e2e` in that order. Note test files and tests passed, the fast-check seed line, the e2e file and test counts.
3. Create `aidlc-docs/features/prerendering/construction/display-fallbacks/code/verification-log.md` with the table header of § 0.3 and one row per V-D1 to V-D15 (Point text copied from business-rules.md § 4, Outcome and Evidence empty, Status `open`).
- Done when: **CP0**: all commands succeed on the untouched tree, otherwise STOP (the baseline must be green before changes) and report the output.
- Record: create `aidlc-docs/features/prerendering/construction/display-fallbacks/code/baseline-checks.md` with commit hash, date, Node and pnpm versions, counts, seed, and the `git status --short` output.
---
## Part B: Early proofs with the real app (batch B1, Sonnet, sequential)
The three riskiest mechanisms are built in their real form and proven in a real browser first. If a proof fails, STOP: the design needs a decision before mechanical work starts.
### Step 2: `Reveal` with a layout effect (V-D1) [x]
- Executor: Sonnet.
- Implements: BR-RVL-01 to 09, 11, 12; FR-PR-09, FR-PR-10; V-D1.
- Files: create `web/src/lib/revealPhase.ts`; change `web/src/hooks/useReveal.ts`, `web/src/components/Reveal/Reveal.tsx`; create `web/src/displayHydration.test.tsx` (first test only).
- Do:
1. `revealPhase.ts`: `export type RevealPhase = 'settled' | 'hidden' | 'revealed'`; `startsHidden(top: number, viewportHeight: number): boolean` returns `top >= viewportHeight`; `nextRevealPhase(phase: RevealPhase, event: 'belowViewport' | 'inView' | 'intersected'): RevealPhase` per domain-entities.md § 2: `settled` + `belowViewport` becomes `hidden`; `hidden` + `intersected` becomes `revealed`; every other combination returns the phase unchanged. Pure, no DOM, no React.
2. `useReveal.ts`: keep the signature `useReveal<T extends Element>()`, return `{ ref, visible, animated }`. State `phase` starts `'settled'`. A `useLayoutEffect` with an empty dependency list reads `ref.current`; if `typeof IntersectionObserver === 'undefined'`, or `window.matchMedia('(prefers-reduced-motion: reduce)').matches`, it returns; otherwise if `startsHidden(element.getBoundingClientRect().top, window.innerHeight)` it sets the phase through `nextRevealPhase(..., 'belowViewport')`. While the phase is `hidden`, observe with `useInView<T>({ threshold: 0.12, rootMargin: '0px 0px -60px 0px', skip: phase !== 'hidden' })` (reuse its `ref`; do not create a second observer implementation); the effective phase is `revealed` when the phase is `hidden` and `inView` is true. `visible` is the effective phase not being `hidden`; `animated` is it being `revealed`. Remove `useMediaQuery` from this hook (the comment says why: the layout effect runs before Chakra's media-query effect).
3. `Reveal.tsx`: props unchanged (`BoxProps` plus `delay`). `data-reveal` is `visible` or `hidden`. Styles per phase as in domain-entities.md § 2: settled and revealed `opacity` 1, `transform` none; hidden `opacity` 0, `transform` `translateY(24px)`; the `transitionProperty`, `transitionDuration` (token `reveal`), `transitionTimingFunction` (`smooth`) and `transitionDelay` (`${delay}s`) props only when `animated`, otherwise `transition="none"`. Add `_motionReduce={{ opacity: 1, transform: 'none', transition: 'none' }}` before `{...rest}`.
4. `displayHydration.test.tsx`: one test that hydrates `<Reveal>` content inside `ChakraProvider` under `React.StrictMode` with `getBoundingClientRect` stubbed to a top above and a top below `innerHeight`, using `hydrate()` from `@/test/hydrate`: no recoverable error; the in-view one never leaves `data-reveal="visible"`; the below-the-fold one becomes `hidden` after hydration and `visible` after the fake observer fires.
5. Real-browser proof: `pnpm build`; write a scratch probe that, for `/over-mij`, `/soorten-fotoshoots`, `/portfolio` at 412 x 823 and `/` and `/over-mij` at 1350 x 940, installs through `addInitScript` a `requestAnimationFrame` loop sampling `getComputedStyle(el).opacity` of every `[data-reveal]` from the first frame for 2.5 s. Expected: elements whose top is below `innerHeight` at the first sample go to opacity 0 after hydration and never animate to 0 (the first sample after hydration is 0, no intermediate value); elements in view stay at 1 in every sample. Also one run with `reducedMotion: 'reduce'`: all stay 1.
- Done when: the probe shows the expected behaviour; `pnpm exec tsc --noEmit`, `pnpm lint` clean; `pnpm exec vitest run src/displayHydration.test.tsx` green. The existing `useReveal.test.tsx` cases listed in § 6 fail as expected (they are rewritten in Step 14); no other test fails.
- Record: verification log V-D1 with the probe output summary. If hydration reports an error, a flash is sampled, or React warns about `useLayoutEffect`, STOP.
### Step 3: `DeferredImage` twin and the head CSS (V-D2, V-D3) [x]
- Executor: Sonnet.
- Implements: BR-IMG-01 to 04, 10; BR-NAV-01, 02 (head placement); V-D2, V-D3.
- Files: create `web/src/components/NoScript/noScriptCss.ts` (first version), `web/src/components/NoScript/NoScriptStyles.tsx`; change `web/src/components/DeferredImage/DeferredImage.tsx`, `web/src/routes/__root.tsx`.
- Do:
1. `noScriptCss.ts`: `export const NO_SCRIPT_CSS` a string with, for now, `noscript{display:contents}` and `img[data-deferred]:not([src]){display:none!important}`. No `</`, no `url(`, no `@import`.
2. `NoScriptStyles.tsx`: `export default function NoScriptStyles()` returns `<noscript><style>{NO_SCRIPT_CSS}</style></noscript>`. In `__root.tsx`, render `<NoScriptStyles />` directly after `<HeadContent />` inside `<head>`.
3. `DeferredImage.tsx`: props unchanged. Return a fragment: the existing `Image` plus `data-deferred`, then `<noscript><Image src={image.src} alt={image.alt} htmlWidth={image.width} htmlHeight={image.height} decoding="async" {...rest without id, data-testid} /></noscript>`. `ref`, `loading="lazy"` and the `src` logic stay on the first image only; the twin has no `loading` and no `ref`.
4. Real-browser proof (`pnpm build`, scratch probe):
- JavaScript on, `/soorten-fotoshoots` and `/portfolio` at 1350 x 940: the set of image URLs requested up to the `load` event plus 500 ms contains no URL that is only a twin; after scrolling the whole page each requested image URL was requested exactly once, and the set equals the `currentSrc` values of the displayed `img` elements plus the preloaded photos and logos. No console error or warning, no hydration error.
- `view-source` check: `document.head` contains the `noscript` with the `style`; `document.querySelectorAll('noscript').length` in the browser equals the count in the raw HTML file (read `dist/client/soorten-fotoshoots.html`).
- Count `<style data-emotion>` blocks in the raw HTML for one deferred image's class: the class is defined once (grep the class name of the first image: exactly one definition).
- JavaScript off (`javaScriptEnabled: false`), same pages: every displayed `img` has `complete` and `naturalWidth` > 0, every `img[data-deferred]` has computed `display: none`, no broken-image box (screenshot looked at).
- Done when: V-D2 and V-D3 are OK; `tsc`, lint clean; `src/components/DeferredImage/DeferredImage.test.tsx` still passes unchanged (client render shows no `noscript` content).
- Record: verification log V-D2, V-D3 with evidence. A hydration error caused by the head `noscript`, a request for a twin with JavaScript on, or the CSS leaving the head: STOP.
### Step 4: First row of the portfolio grid (V-D13) [x]
- Executor: Sonnet.
- Implements: BR-PRE-03, 08, 10, 11, 12; BR-IMG-10; FR-PR-21; V-D13.
- Files: create `web/src/lib/firstRow.ts`; change `web/src/seo.ts`, `web/src/components/PortfolioGrid/PortfolioGrid.tsx`, `web/src/components/portfolio/PortfolioGallery/PortfolioGallery.tsx`, `web/src/routes/portfolio.tsx`.
- Do:
1. **Before editing**, with the existing `dist/client` (the unit-1 build), record in the scratch folder, with a probe, the bounding box (`x`, `y`, `width`, `height`) of every `[data-testid^="portfolio-tile-"]` of `/portfolio` at 320 x 568, 412 x 823, 768 x 1024, 1023 x 768, 1024 x 768 and 1350 x 940.
2. `seo.ts`: add `export type HeadLink` and `export function preloadImage(image: ContentImage, options?: { media?: string }): HeadLink` returning `{ rel: 'preload', as: 'image', href: image.src, fetchPriority: 'high', ...(options?.media ? { media: options.media } : {}) }` and nothing else. `pageHead` stays unchanged.
3. `firstRow.ts`: `export const GRID_COLUMNS` (ordered by breakpoint: `{ media: null, columns: 1 }`, `{ media: '(min-width: 48em)', columns: 2 }`, `{ media: '(min-width: 64em)', columns: 3 }`), `export type FirstRow = 'always' | { media: string } | null`, `export function firstRow(index: number, columns = GRID_COLUMNS): FirstRow` (`'always'` when `index` is smaller than the base column count; `{ media }` of the first breakpoint whose column count exceeds `index`; `null` when no breakpoint does), and `export function firstRowPreloads(items: readonly { thumb: ContentImage }[], columns = GRID_COLUMNS): HeadLink[]` returning `preloadImage(item.thumb, { media })` for each item whose `firstRow` has a `media`, in order. Imports `preloadImage` from `@/seo`.
4. `PortfolioGrid.tsx`: replace the `eagerCount` prop (default 3) by `eagerFirstRow?: boolean` (default `true`). Per tile (index in the list): `firstRow(index)` when `eagerFirstRow`, otherwise `null`. `'always'`: the existing eager `Image` with `src`, `fetchPriority="high"`, `decoding="async"`. `{ media }`: `<chakra.picture display="contents">` with `<source media={media} srcSet={item.thumb.src} />` and the `DeferredImage` as its `img`, passing `loading="eager"` and `fetchPriority="high"` after the image style (these override `DeferredImage`'s defaults, which spread `rest` last). `null`: the `DeferredImage` as today. The tile link, size, hover zoom and focus styles are untouched. The columns of `gridTemplateColumns` stay as they are.
5. `PortfolioGallery.tsx`: stop passing `eagerCount={0}`; replace the comment above it with the one from BR-PRE-08 (the first row loads eagerly with preloads because it is in view and is the largest paint; later rows wait for the page and for proximity; the 2026-10-27 measurement is repeated before this is final). No plan or step names in it.
6. `routes/portfolio.tsx`: `head()` returns `{ ...base, links: [...base.links, ...firstRowPreloads(items)] }` where `base = pageHead('/portfolio')` and `items` is the unfiltered list the page renders (`toGalleryItems(filterPhotos(portfolioContent.photos, undefined), shootTypes)` from `@/lib/portfolioFilters`; keep the existing `scripts`). `tsc` must accept the `media` and `fetchPriority` link attributes; if the router's link type rejects them, STOP.
7. Proof (`pnpm build`, scratch probe): (a) `dist/client/portfolio.html` head holds React's preload for tile 1 and exactly two links with `media="(min-width: 48em)"` and `media="(min-width: 64em)"`, each a different hashed photo, no other photo preload; (b) at 390, 768 and 1350 px wide (JavaScript on), the photo requests before the `load` event are exactly 1, 2 and 3 grid photos, each URL once, none for tiles 4 and up; (c) after load and a scroll to the bottom every grid photo was requested exactly once in total; (d) no hydration error or console message; (e) compare the tile boxes with Step 4.1 at the six widths: equal to the pixel, hover zoom (`transform` on the tile image after hover) and keyboard focus ring still work on tiles 2 and 3; (f) the number of distinct tile `x` positions in the first row at each width equals the column count of `GRID_COLUMNS` (1 at 320 to 767, 2 at 768 to 1023, 3 from 1024).
- Done when: V-D13 is OK; `tsc`, lint clean; `pnpm build` green. `PortfolioGrid.test.tsx` is expected to fail on the removed prop only (Step 14).
- Record: verification log V-D13 with evidence (request counts per width, box comparison). A `<picture>` that changes a tile's box, a double request, a request below the media query, or a hydration error: STOP.
### Step 5: Proof report and decision to continue [x]
- Executor: Sonnet.
- Do: write `aidlc-docs/features/prerendering/construction/display-fallbacks/code/proof-report.md` (max one page): per V-D1, V-D2, V-D3, V-D13 the outcome in one or two sentences with evidence; the list of files changed so far; deviations from the design (none expected). Run `pnpm exec tsc --noEmit`, `pnpm lint`, `pnpm build`, `pnpm test` and list which tests fail (expected: the `useReveal.test.tsx` cases and `PortfolioGrid.test.tsx` named in § 6, nothing else).
- Done when: **CP1**. If any of the four is BLOCKED or DEVIATION, or an unexpected test fails, STOP and report to the main session; do not start B2 to B4.
---
## Part C: No-JavaScript menu and CSS (batch B2, Sonnet; parallel with B3 and B4)
### Step 6: The complete no-JavaScript CSS [x]
- Executor: Sonnet.
- Implements: BR-NAV-03 to 06, 08, 09; BR-NJS-01, 02, 09; BR-IMG-02, 04.
- Files: `web/src/components/NoScript/noScriptCss.ts`.
- Do: keep `NO_SCRIPT_CSS` as one string built from named parts (one constant per group, joined) so each group is readable and testable. Export `MOBILE_NAV_ID = 'mobile-nav'` and `HEADER_ID = 'site-header'`. Add, per the rules and the CSS table in business-logic-model.md § 3.2:
- `[data-requires-js],[data-email-pending]{display:none!important}`
- the open link `.ns-menu-open` (44 x 44, three bars made of `span` children at `top` 15, 21, 27 px, `left` 10 px, 24 x 2 px, `background:currentColor`, colour inherited), hidden with `display:none` from `@media (min-width:64rem)`; the close link `.ns-menu-close` (a normal text link: padding, `display:inline-block`, `min-height:44px`, colour and font inherited from the panel); focus rings `.ns-menu-open:focus-visible,.ns-menu-close:focus-visible{outline:2px solid currentColor;outline-offset:2px}`
- `#mobile-nav:target{clip-path:inset(0);visibility:visible}` (do not set `display`)
- `#mobile-nav [id^="mobile-group-"]{grid-template-rows:1fr;visibility:visible;transition:none}`
- `[data-submenu]:focus-within>[data-submenu-panel]{visibility:visible;opacity:1;transform:none;pointer-events:auto;transition:none}`
Use the Chakra CSS variables the site already uses where a token is needed (`var(--slp-...)`), no hard-coded colours except `currentColor`. Build the ids in the selectors from the exported constants.
- Done when: `tsc`, lint clean; the CSS has no `</`, `url(` or `@import`, balanced braces (Step 8 tests it).
### Step 7: The two menu links and the attributes [x]
- Executor: Sonnet.
- Implements: BR-NAV-03, 04, 06, 07, 09, 10; BR-PRE-05 (light logo); V-D3 (header and panel).
- Files: create `web/src/components/NavigationBar/NoScriptNav.tsx`; change `NavigationBar.tsx`, `MobileNav.tsx`, `MobileNavGroup.tsx`, `NavSubmenu.tsx` in the same folder.
- Do:
1. `NoScriptNav.tsx`: `export function NoScriptMenuOpen()` renders `<noscript><a className="ns-menu-open" href={`#${MOBILE_NAV_ID}`} aria-label="Menu openen" data-testid="nav-noscript-open"><span aria-hidden="true" /><span aria-hidden="true" /><span aria-hidden="true" /></a></noscript>`; `export function NoScriptMenuClose()` renders `<noscript><a className="ns-menu-close" href={`#${HEADER_ID}`} data-testid="nav-noscript-close">Menu sluiten</a></noscript>`. Plain elements, no Emotion (no style tags inside `noscript`). Both strings already exist as `aria-label` text in the navigation.
2. `NavigationBar.tsx`: `id={HEADER_ID}` on the `chakra.header`; `data-requires-js` on the hamburger `chakra.button`; `<NoScriptMenuOpen />` in the right-hand `div` before the button; `loading="lazy"` on the light logo `Image` when `!isHome` (`isHome` is already computed from the pathname). No change to the reducer, ARIA or focus code.
3. `MobileNav.tsx`: `<NoScriptMenuClose />` as the first child of the content `Box` (before the `nav`). `id` stays `mobile-nav` (use `MOBILE_NAV_ID` where the id is passed in `NavigationBar`).
4. `MobileNavGroup.tsx`: `data-requires-js` on the chevron button. `NavSubmenu.tsx`: `data-submenu` on the wrapper `Box` (the one with the `ref` and `onBlur`), `data-submenu-panel` on the panel `Box`, `data-requires-js` on the chevron button.
- Done when: `tsc`, lint clean; the existing tests of the folder (`NavigationBar.test`, `MobileNav.test`, `NavSubmenu.test`, `NavLink.test`, `activeOptions.test`, `src/navSubmenu.test.tsx`) pass unchanged (client render shows no `noscript` content); `renderToString` of the navigation contains both links.
### Step 8: Tests for the menu and the CSS [x]
- Executor: Sonnet.
- Implements: BR-DTS-02; BR-NAV-02; NFR-PR-SEC-01, S-01; PBT: "No PBT properties identified" (constant markup).
- Files: create `web/src/components/NoScript/noScriptCss.test.ts`, `web/src/components/NavigationBar/NoScriptNav.test.tsx`.
- Do: example-based tests. CSS: contains none of `</`, `url(`, `@import`; braces balance; every group of business-logic-model.md § 3.2 is present; names `#mobile-nav`, `#mobile-group`-prefix selector and the data attributes that the components render (read from a `renderToString` of `NavigationBar` and `MobileNav` inside the memory router: ids `site-header` and `mobile-nav` exist, `data-submenu`, `data-submenu-panel` and `data-requires-js` are present on the right elements); no e-mail address (`emailAddress(siteContent.email)` as a string is not in the CSS). Links: `renderToString` of `NoScriptMenuOpen` and `NoScriptMenuClose` gives a `noscript` with one `a` each, the right `href`, `aria-label` and text, no `style` element inside; the light logo has `loading="lazy"` on `/over-mij` and not on `/` in server markup.
- Done when: `pnpm exec vitest run src/components/NoScript src/components/NavigationBar` green.
---
## Part D: Markers and preload hygiene (batch B3, Sonnet; parallel with B2 and B4)
### Step 9: `data-requires-js` and the footer column [x]
- Executor: Sonnet.
- Implements: BR-NJS-01 to 04, 06; BR-NJS-02 (footer); FR-PR-13, FR-PR-22.
- Files: `web/src/components/Hero/Hero.tsx`, `HeroArrows.tsx`, `HeroPauseButton.tsx`; `web/src/components/FilterBar/FilterBar.tsx`; `web/src/components/home/Testimonials/Testimonials.tsx`; `web/src/components/Footer/Footer.tsx`, `FooterColumn.tsx`.
- Do: `data-requires-js` on each arrow `ArrowButton`, on the pause button, on the hero progress bar `Box`, on the `FilterBar` root `div`, on the 48 px controls spacer `Box` in `CarouselPlaceholder`. `FooterColumn` takes an optional `requiresJs?: boolean` prop that sets `data-requires-js` on its root `Box`; the Contact column in `Footer.tsx` passes `requiresJs`. The `data-email-pending` placeholders already exist (unit 1); do not change them. Nothing else changes: the review copies stay hidden, `aria-hidden` and `inert` (BR-NJS-04).
- Done when: `tsc`, lint clean; the existing tests of these folders pass unchanged.
### Step 10: Preload hygiene for the contact page [x]
- Executor: Sonnet.
- Implements: BR-PRE-02, 05; V-D11.
- Files: `web/src/components/ContactDetails/ContactDetails.tsx`, `web/src/routes/contact.tsx`.
- Do: `loading="lazy"` on the portrait `Image` of `ContactDetails` (it is `display: none` from `lg`; a lazy image is neither fetched while hidden nor hoisted by React). `routes/contact.tsx`: import `ASIDE_MEDIA` from `../components/contact/ContactAside/ContactAside` and `preloadImage` from `../seo`; `head()` returns `links: [...base.links, preloadImage(contactContent.image, { media: ASIDE_MEDIA })]` with `base = pageHead('/contact')`, keeping the existing `scripts`.
- Done when: `tsc`, lint clean; `ContactDetails.test.tsx` and the contact route tests pass unchanged; `pnpm exec vitest run src/seo.test.ts` still green.
### Step 11: Tests for markers and preload hygiene [x]
- Executor: Sonnet.
- Implements: BR-DTS-02; PBT: "No PBT properties identified" (attribute additions).
- Files: create `web/src/components/Hero/hero.noscript.test.tsx` and add cases to the existing `FilterBar.test.tsx`, `Testimonials.test.tsx`, `Footer.test.tsx`, `ContactDetails.test.tsx` (new `it` blocks only).
- Do: through `renderToString`/`serverHtml` (not client render, which drops `noscript` but keeps attributes): hero arrows, pause button and progress bar carry `data-requires-js`; the `FilterBar` root does; the testimonial controls spacer does while the hidden review copies keep `aria-hidden` and `inert`; the footer Contact column has `data-requires-js` and no other column has; the contact portrait has `loading="lazy"`.
- Done when: the touched test files are green.
---
## Part E: Reveal, image and first-row tests (batch B4, Sonnet; parallel with B2 and B3)
### Step 12: Generators [x]
- Executor: Sonnet.
- Implements: PBT-07; BR-DTS-05.
- Files: create `web/src/test/revealArbitraries.ts`, `web/src/test/firstRowArbitraries.ts`.
- Do: `revealArbitraries.ts`: `viewportHeight` (finite positive floats, integers and a few phone and desktop heights mixed), `elementTop` (finite floats and integers, negative, zero, equal to the viewport height, far below), `revealPhase`, `revealEvent` (`belowViewport`, `inView`, `intersected`), `revealEvents` (arrays up to 20). `firstRowArbitraries.ts`: `columnMap` (1 to 4 breakpoints, strictly increasing column counts starting at the base, media strings of the form `(min-width: Nem)` with strictly increasing N), `tileIndex` (0 to 12), and a `galleryItemsWithThumbs` built from `galleryItems` in `arbitraries.ts`. Do not add anything to `arbitraries.ts`.
- Done when: `tsc` clean; the files are used by Step 13 (check with `grep`).
### Step 13: Properties P18 to P25 [x]
- Executor: Sonnet.
- Implements: BR-RVL-12; BR-PRE-03, 08, 11; BR-DTS-05; PBT-01 to 10.
- Files: create `web/src/lib/revealPhase.test.ts`, `web/src/lib/firstRow.test.ts`; add to `web/src/seo.test.ts`.
- Do (each property titled with its category, each with an example-based sibling; global seed; shrinking on):
- P18 `startsHidden` (invariant): `top >= viewportHeight` gives true, smaller gives false, for any finite numbers; equal gives true.
- P19 `startsHidden` (metamorphic): if hidden at `top` then hidden at every larger `top`; adding the same offset to `top` and `viewportHeight` does not change the result.
- P20 `nextRevealPhase` (invariant, state machine): over any event sequence from `settled` or `hidden`, the phase never goes from `revealed` to `hidden` or `settled`, and never from `settled` to `revealed`.
- P21 `nextRevealPhase` (idempotent): applying the same event twice equals applying it once, for any phase and event.
- P22 `preloadImage` (invariant): for any `contentImage` and options, `href` equals `image.src`, `rel` is `preload`, `as` is `image`, `fetchPriority` is `high`, `media` present exactly when given and equal, and the key set is exactly those.
- P24 `firstRow` (invariant): `'always'` exactly when `index` is smaller than the base column count; `null` exactly when it is not smaller than the largest column count; otherwise `{ media }` of the first breakpoint whose column count exceeds `index`.
- P25 `firstRow` and `firstRowPreloads` (metamorphic): a tile eager at some width is eager at every wider width; the number of tiles eager at a width equals the column count at that width; `firstRowPreloads` yields one link per tile with a `media`, none for `'always'` or `null`, `href` equal to that tile's `thumb.src`, never more links than largest minus base column count.
- Example tests for every branch of `revealPhase.ts`, `firstRow.ts` (the real `GRID_COLUMNS`: tile 1 always, tile 2 `48em`, tile 3 `64em`, tile 4 null) and `preloadImage` with and without `media`, so `src/lib/**` and `src/seo.ts` stay at 100 %.
- Done when: `pnpm exec vitest run src/lib/revealPhase.test.ts src/lib/firstRow.test.ts src/seo.test.ts` green; a coverage run of those files shows 100 % for `revealPhase.ts`, `firstRow.ts` and the new `seo.ts` code.
### Step 14: Component, hydration and prerender tests [x]
- Executor: Sonnet.
- Implements: BR-DTS-01, 02, 05; BR-RVL-01 to 09; BR-IMG-01, 03, 10; BR-PRE-08, 10; V-D1, V-D13 (test); PBT: "No PBT properties identified" for components (decisions are in P18 to P25).
- Files: change `web/src/hooks/useReveal.test.tsx`, `web/src/components/Reveal/Reveal.test.tsx`, `web/src/components/DeferredImage/DeferredImage.test.tsx`, `web/src/components/PortfolioGrid/PortfolioGrid.test.tsx`, `web/src/components/portfolio/PortfolioGallery/PortfolioGallery.test.tsx` (only where § 6 says); extend `web/src/displayHydration.test.tsx`; create `web/src/displayPrerender.test.tsx`.
- Do:
- `useReveal.test.tsx`: rewrite the cases § 6 names. jsdom has no layout, so stub `getBoundingClientRect` to return `top` above and below `window.innerHeight`. Cases: server render is visible; in view at hydration stays visible and creates no observer; below the fold becomes hidden then visible after the fake observer fires and `animated` is true; reduced motion hides nothing and creates no observer; no `IntersectionObserver` stays visible; disconnects on unmount; StrictMode runs the effect twice without a second observer or a different result.
- `Reveal.test.tsx`: keep both cases; add: hidden element has `data-reveal="hidden"`, `opacity` 0 and no transition; revealed element has the transition and `delay`.
- `DeferredImage.test.tsx`: keep all cases; add `renderToString` cases: twin exactly once with `src`, `alt`, `width`, `height`, no `loading`, no `ref`/`id`/`data-testid`; first image has `data-deferred` and no `src`; no `<link rel="preload"` appears for the twin when rendered in a document context through `prerender` from `react-dom/static`; hydrating the pair reports no error (`hydrate()`).
- `PortfolioGrid.test.tsx`: replace `eagerCount={3}` by the new prop; assertions: server markup has tile 1 as a plain `img` with `src`, tiles 2 and 3 inside `picture` with `source[media]` of 48em and 64em, tile 4 and up `data-deferred` without `src`; `eagerFirstRow={false}` makes all tiles deferred; the media of tiles agree with `GRID_COLUMNS`.
- `PortfolioGallery.test.tsx`: change only an assertion that expects the first photos to have no `src` before load, and say which.
- `displayHydration.test.tsx`: with `hydrateAppAsStart` (never `hydrateApp`): `/portfolio`, `/`, `/over-mij`, `/contact` and `/soorten-fotoshoots/loveshoot` hydrate without recoverable error; on `/portfolio` the first-row picture tiles hydrate and the filter `?shoot=gezin` applies afterwards with the new first row remounting; Reveals in view stay visible through hydration (stubbed rect).
- `displayPrerender.test.tsx` (`// @vitest-environment node`, in the style of `src/prerender.test.tsx`): for every `sitePages` path, the prerendered HTML contains one noscript twin per `data-deferred` image and no `data-reveal="hidden"`.
- Done when: **CP2** (after B2 and B3 are also done): `pnpm test` green with coverage thresholds, `pnpm lint`, `pnpm format:check`, `pnpm exec tsc --noEmit`, `pnpm build` green.
- Record: list every existing test changed, with the reason.
- Record (B4): changed existing tests, all named in section 6. `useReveal.test.tsx`: the six cases rewritten (server render visible; stubbed rectangle for the hidden, observing and disconnecting cases; reduced motion creates no observer; hydration case follows the new layout effect). `PortfolioGrid.test.tsx`: `eagerCount={3}` test replaced by the first-row test (`eagerFirstRow`), plus server-markup, hydration and column tests. `PortfolioGallery.test.tsx`: only the loop that expected no eager photo ("none eager") now expects tile 1 plain and high priority, tiles 2 and 3 eager, the rest lazy.
---
## Part F: Browser tests (batch B5, after CP2)
All files in `web/e2e/`, Dutch titles and comments like the neighbours, using the helpers in `e2e/support/` (`openPage`, `waitForHydration`, `eventually`, the preview server). Each test file ends with the checks named; failures that point at the design are STOP cases.
### Step 15: Raw HTML checks (BR-PRE-04, BR-NAV-02, V-D11) [x]
- Executor: Sonnet.
- Implements: BR-PRE-01 to 04, 09; BR-NAV-01, 02; NFR-PR-SEC-01; V-D11.
- Files: create `web/e2e/displayHtml.e2e.ts`.
- Do: plain `fetch` of the preview server for the eleven pages and `/404.html`: in `<head>` exactly one `noscript` holding one `style`, with none of `</`, `url(`, `@import`; the assembled e-mail address (all forms used in `rawHtml.e2e.ts`) occurs nowhere; every `link[rel=preload][as=image]` href occurs once per file; every page with a `priority` photo (`/`, `/over-mij`, `/soorten-fotoshoots`, five shoot pages) has the preload with `fetchpriority="high"` for it; `/contact` has a link with `media="(min-width: 64em)"` for the aside photo and no other link for that file; `/portfolio` has React's link for tile 1 and exactly two `media` links (48em, 64em) for two different photos; the light logo preload is absent on every page except `/`; the contact portrait preload is absent; every `img[data-deferred]` is followed by a `noscript` containing an `img` with the same `alt`; no `<link rel="preload">` for a twin; `data-reveal="hidden"` occurs nowhere.
- Done when: the file passes against a current build (run in Step 21; at authoring time use `pnpm build && pnpm exec vitest run --config vitest.e2e.config.ts e2e/displayHtml.e2e.ts`).
### Step 16: No JavaScript on every page (FR-PR-11, 13) [x]
- Executor: Sonnet.
- Implements: BR-IMG-01, 02, 05; BR-NJS-01 to 08; BR-RVL-01; FR-PR-11, 13, 22; V-D12.
- Files: create `web/e2e/noJs.e2e.ts`.
- Do: for the eleven pages and the 404 page (`/onbekend`, `expectNotFound`), at 390 and 1280 px, `javaScript: false`, after `networkidle`: no visible `button` element; every `[data-reveal]` has computed opacity 1; every displayed `img` is `complete` with `naturalWidth` > 0; every `img[data-deferred]` has computed `display: none`; the number of displayed `img` with non-empty `alt` equals the number `getByRole('img')` finds (each photo once in the accessibility tree); no element matching `[data-email-pending]` or `[data-requires-js]` is displayed; no `a[href^="mailto:"]`; the footer has no heading named "Contact" and no empty column (checked with `getByRole('contentinfo')`); on `/`: no `hero-prev-button`, `hero-next-button`, `hero-pause-button` or `hero-progress` displayed and the first slide's photo displayed; on `/portfolio`: no `filter-bar` displayed, every tile link's `href` ends in an image file; the testimonials block shows one review (unit-1 V9 stays as is). Screenshots of every page and width are saved when `E2E_SCREENSHOT_DIR` is set and **looked at** by you (V-D12): list in the Record what looks wrong (empty areas, spacing left by hidden controls such as the filter bar margin or the gate's margin) without fixing design-level issues.
- Done when: green in Step 21; V-D12 filled with the findings.
### Step 17: Menu without JavaScript, by keyboard and pointer (FR-PR-12) [x]
- Executor: Sonnet.
- Implements: BR-NAV-03 to 09; FR-PR-12; V-D4 (Chrome part), V-D9; NFR-PR-S-01.
- Files: create `web/e2e/noJsMenu.e2e.ts`.
- Do (`javaScript: false`, `/over-mij`, plus `/` for the home variant):
- 390 x 800: hamburger (`nav-menu-toggle`) not displayed; `nav-noscript-open` displayed, 44 x 44; the panel (`#mobile-nav`) hidden (`visibility: hidden`) and none of its links focusable (Tab from the open link never reaches Home inside the panel before the page content).
- Pointer: scroll to `scrollY` 300; click `nav-noscript-open`; `location.hash` is `#mobile-nav`, the panel is visible, the five shoot links (Newborn, Zwangerschap, Gezin, Loveshoot, Portretten) are visible without any click on a chevron, `scrollY` is still 300; click `nav-noscript-close`; the panel hidden again, hash `#site-header`, `scrollY` still 300.
- Keyboard: focus the open link, press Enter; the next Tab lands on `nav-noscript-close`, then Tab visits, in order, Home, Over mij, Portfolio, Soorten fotoshoots, Newborn, Zwangerschap, Gezin, Loveshoot, Portretten, Contact (read `document.activeElement` after each key, **without any pause**, which also proves `transition: none` where it matters); Enter on the close link closes the panel.
- Focus visibility (V-D9): the focused open and close links have a computed outline width of at least 2 px.
- Opening on a wide screen: at 1280 x 800 `nav-noscript-open` is not displayed, and loading `/over-mij#mobile-nav` shows no panel.
- Desktop submenu at 1280 x 800: chevron buttons not displayed; Tab (immediately after each key) from the "Soorten fotoshoots" link reaches Newborn to Portretten in order and then Contact; the panel is visible while focus is inside it and hidden after focus leaves.
- Done when: green in Step 21; V-D4 (Chrome only) and V-D9 filled; Firefox and Safari are recorded as not verifiable by agents (§ 5).
### Step 18: `Reveal` at load and on scroll (FR-PR-09, 10; V-D6) [x]
- Executor: Sonnet.
- Implements: BR-RVL-01 to 10, 13, 14; FR-PR-09, 10; V-D6.
- Files: create `web/e2e/reveal.e2e.ts`.
- Do (JavaScript on):
- No flash: for `/`, `/over-mij`, `/portfolio`, `/soorten-fotoshoots`, `/contact` and one shoot page at 390 x 823 and 1350 x 940, an init script samples `getComputedStyle(el).opacity` of every `[data-reveal]` on every animation frame from the first frame to 2 s after hydration. Elements whose top is above `innerHeight` at the first frame (recorded) are sampled at 1 in every frame. Elements below it are sampled at 1 until hydration and at 0 afterwards, with no value strictly between (the hide is instant); they are `data-reveal="hidden"` after hydration.
- On scroll: scroll a hidden element into view; within 1.5 s its opacity reaches 1 and `data-reveal` is `visible`; a staggered row (`/` pricing cards at 1350) reveals with increasing delays when below the fold.
- `/portfolio` at 412 x 823: the grid wrapper (the `[data-reveal]` containing `portfolio-grid`) is `visible` at load (regression for the old empty-grid defect).
- Reduced motion (`reducedMotion: 'reduce'` context): every `[data-reveal]` is `visible` with opacity 1 at all times, at both widths.
- Client navigation (O1): from `/` click the "Over mij" link; after the new page mounts, every `[data-reveal]` in view stays at opacity 1 on every frame.
- V-D6: at 320 x 568, 360 x 640, 412 x 823, 768 x 1024 and 1350 x 940, every `[data-reveal]` that is `hidden` after hydration has a height of at most `(innerHeight - 60) / 0.12`; list the tallest per page in the Record.
- Done when: green in Step 21; V-D6 filled.
### Step 19: Images and preloads per width (FR-PR-11, 21; V-D13, V-D15) [x]
- Executor: Sonnet.
- Implements: BR-IMG-03; BR-PRE-01 to 12; BR-DTS-03; V-D13, V-D15.
- Files: create `web/e2e/images.e2e.ts`.
- Do (JavaScript on, request log through `page.on('request')` and `performance.getEntriesByType('resource')`):
- Twin not fetched: on `/soorten-fotoshoots` and `/portfolio` at 1350 x 940, up to the `load` event plus 500 ms, only photos that are in the first row, preloaded or `src`-bearing are requested; after scrolling the whole page every photo URL was requested exactly once in total.
- Preload counts per width (use `matchMedia(link.media)` on each `link[rel=preload][as=image]` of the loaded document; logos excluded by name): `/portfolio` has 1, 2 and 3 matching photo preloads at 390, 768 and 1350 px; `/contact` has 0 at 390 and 768 and 1 at 1350; `/` and `/over-mij` and the shoot pages have exactly 1 at every width.
- Used and not duplicated: at each width every matching photo preload URL is the `currentSrc` of a displayed `img` and was requested exactly once; allowed exception: on `/` the second logo may be preloaded without being displayed (BR-PRE-05).
- `/contact`: at 1350 the aside photo is requested once; at 390 not at all; the contact portrait (72 px) is not requested at 1350.
- Logos: the light logo is requested on `/` and on no other page.
- First row: the number of distinct `x` of tiles in the first row (`getBoundingClientRect().left`) at 390, 768 and 1350 is 1, 2 and 3, equal to the number of eager grid photos requested before `load` (V-D13); tile size is unchanged against the values recorded in Step 4.
- V-D15: load `/portfolio?shoot=gezin` at 1350: after the filter applies and the page is scrolled to the bottom, no image URL was requested more than once.
- Done when: green in Step 21; V-D13 and V-D15 filled.
### Step 20: Existing browser tests whose expectations change [x]
- Executor: Sonnet.
- Implements: BR-DTS-04; V-D8.
- Files: `web/e2e/interaction.e2e.ts`, `web/e2e/rawHtml.e2e.ts` (and `hydration.e2e.ts` only if a run shows it must).
- Do: run the existing e2e files against the current build and review each failure; the following are the only expected, legitimate changes, and each must be recorded with its reason:
1. `interaction.e2e.ts` V15 block ("stijlen zonder en met JavaScript"): its comment says `Reveal` and the photos change appearance after hydration "bewust (eenheid 2)" and the no-JavaScript screenshot used to show an empty area under the h1. Update the comment to say the JavaScript-off page now shows its content; the position assertions (h1 and `main` equal with and without JavaScript) stay exactly as they are.
2. `rawHtml.e2e.ts` link and image counts (V-D8): `DOMParser` parses `noscript` content as markup, so `a[href]` now also finds the two `#mobile-nav`/`#site-header` links and `img` finds twins. Restrict a count or an "every link" check to links and images outside `noscript` (for example by removing `noscript` elements from the clone first, as `bodyText` already does for `main`), keeping the intended meaning of each assertion.
Everything else (V9: one review and the rest 1 px, `aria-hidden`, `inert`; V8; BR-HYD-20 no console error; price text; address absent) must pass unchanged. A failure outside this list is a STOP case.
- Done when: both files pass in Step 21; the Record lists each changed assertion with its reason, and V-D8 is filled.
### Step 21: Run all browser tests on a current build [x]
- Executor: Haiku.
- Implements: NFR-PR-Q-03; CP3.
- Do: in `web/`, one command line: `pnpm build && pnpm e2e` (rule 11). Note files and tests passed. If a test fails, do not edit tests; report the failure to the main session with the output, unless it is a plain typo in a file written in this part (then the Sonnet executor of B5 fixes it).
- Done when: **CP3**: green. Counts recorded.
---
## Part G: Finish (batch B6)
### Step 22: Comments, naming, formatting review [x]
- Executor: Sonnet.
- Implements: NFR-PR-Q-05; BR-DTS-04.
- Do: review every new or changed file for header comments that say why (why the layout effect and the `top >= innerHeight` test, why the CSS lives in `<head>` inside `noscript`, why `display: contents` on `noscript`, why `transition: none` on the submenu rule, why `<picture>` tiles and media-bound preloads, why the light logo is lazy off `/`); comment language per neighbour; **no comment names a plan step or this plan**; no temporary constants; no `TODO` without owner; `data-testid` naming; the `PortfolioGallery` comment as BR-PRE-08 says. Run `pnpm exec prettier --write` on touched files, then `pnpm lint` and `pnpm format:check`.
- Done when: lint and format checks are clean and `git diff --stat` shows only files named in this plan (plus `src/routeTree.gen.ts` only if a route file changed, which it should not).
### Step 23: Full verification (Code Generation Step 13.5) [x]
- Executor: Haiku.
- Implements: Code Generation Step 13.5; CP4; NFR-PR-Q-01.
- Do, in `web/`: `pnpm lint`, `pnpm format:check`, `pnpm test`, `pnpm build && pnpm e2e` (one line), `pnpm audit:deps`, `pnpm audit:dev`. Note counts of test files and tests (more than the Step 1 baseline), the fast-check seed, and whether any test is flaky (rerun a failing property test once with `FC_SEED=<seed>`; a failure that passes on a different seed is a real finding, report it, do not retry until green). Do not run `pnpm lighthouse` (measurement is Part H).
- Done when: **CP4**, or the unresolved failure and its open question are written down for the code summary.
- Record: counts and outcomes (input to Step 28).
---
## Part H: Measurement (batch B7; exclusive: rules 13 and 14)
Preconditions for all of Part H: Step 23 green; the main session has confirmed that it holds port 4173 for this work; `git status --short` recorded to `<scratch>/status-before.txt`; `pnpm build` just run. The method is the one of unit 1: `lhci collect`, 3 runs per URL, median, same machine. Lighthouse runs may be backgrounded; wait for them (rule 13).
### Step 24: Measurement U2 and the moved-scripts check (BR-DMS-02, 03) [x]
- Executor: Haiku for the runs, Sonnet for the script and the report.
- Implements: BR-DMS-02, 03; NFR-PR-P-01, P-03; V-D7 (first part).
- Do:
1. Write (Sonnet) a Node script in the scratch folder that reads every `lhr-*.json` of a folder and prints, per URL, the median over the runs of: `categories.performance.score`, FCP, LCP, TBT, CLS, the sum of `transferSize` of `Script` requests; plus from the median-LCP run: the LCP element (selector and snippet), `observedLargestContentfulPaint` and the transfer sizes of images requested before it (names and KB). Reuse it in Steps 25 and 26.
2. Remove `.lighthouseci`. Mobile: `pnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=3` then move `.lighthouseci` to `<scratch>/u2/mobile`; desktop likewise with `lighthouserc.desktop.cjs` to `<scratch>/u2/desktop`. Same URL list as unit 1 (the configs are not edited; the not-found URL is `/404.html`).
3. Compare with `aidlc-docs/features/prerendering/construction/start-migration/code/measurement-gate.md` (master baseline, unit 1 "A" and "B") and `measurement-baseline.md`.
4. Trace (BR-DMS-02): for each of the 12 URLs keep the trace of one mobile run through Lighthouse gather mode (`pnpm exec lighthouse <url> -G --output-path=<scratch>/trace/<slug>` with the mobile defaults of `lighthouserc.cjs` and the Chrome flags it uses, against `pnpm preview --port 4173 --strictPort` started and stopped by you). If `pnpm exec lighthouse` does not exist or gather mode fails, write "trace not obtained" with the error in the report; this is not a STOP.
- Done when: the folders and the script output exist; the comparison table is ready for Step 27.
### Step 25: Largest-paint probe, logo effect and moved scripts (V-D7, V-D10, V-D14) [x]
- Executor: Haiku runs, Sonnet reads.
- Implements: BR-PRE-05, 06; V-D7, V-D10, V-D14.
- Do: (a) probe (scratch, unthrottled Chrome) of the largest-contentful-paint element per page at 412 x 823, 768 x 1024 and 1350 x 940 (a `PerformanceObserver` for `largest-contentful-paint` registered by `addInitScript`; last entry after 2.5 s; record tag, `url`, `size`, alt text) for the eleven pages; check against business-rules.md BR-PRE-06 and the domain-entities.md § 6 table, and for `/portfolio` state which tile it is at each width (V-D14, expected: a first-row tile). (b) Effect of the lazy logo and contact portrait (V-D7): from `<scratch>/u2` and the unit-1 numbers, `imgKB` before the real LCP on non-home pages should be about 25 KB lower; report the score and LCP change per page, and confirm by a probe on `/` after a client navigation to `/over-mij` and back that the logo does not flash (take frames). (c) If a trace was obtained (Step 24.4), state whether the hero photo is the LCP candidate on `/` (V-D10). (d) Time of the moved `inline-*.js` files against FCP and LCP for `/` and `/over-mij`, as unit 1 did.
- Done when: results written for Step 27. A first-row tile that is not the largest paint, or a logo flash, is a finding for the report, not a STOP.
### Step 26: Portfolio comparison, build E against build D (BR-DMS-05, V-D5) [x]
- Executor: Haiku for the runs, Sonnet for the temporary change and the report. Exclusive.
- Implements: BR-DMS-05; NFR-PR-P-01; V-D5.
- Do:
1. Record `git status --short` (`status-before.txt`), the SHA-256 of `web/src/components/portfolio/PortfolioGallery/PortfolioGallery.tsx` and `web/src/routes/portfolio.tsx`, and scratch copies of both files.
2. **Build E** is the committed design (current tree). `pnpm build`; remove `.lighthouseci`; `pnpm exec lhci collect --config=lighthouserc.cjs --url=http://localhost:4173/portfolio --numberOfRuns=3` (a `--url` on the command line replaces the config's URL list; check that the report has only `/portfolio`; if the flag does not replace the list, use a temporary copy of the config in the scratch folder with only that URL, never edit `lighthouserc.cjs`), then the same with `lighthouserc.desktop.cjs`. Move results to `<scratch>/portfolio/E/{mobile,desktop}`.
3. **Build D** (temporary, never committed): in `PortfolioGallery.tsx` pass `eagerFirstRow={false}`; in `routes/portfolio.tsx` make `firstRowPreloads(items)` contribute no links (an empty array); nothing else. `pnpm build`; collect the same way to `<scratch>/portfolio/D/{mobile,desktop}`.
4. **Drift check:** restore both files, verify the SHA-256 and `git status --short` equal the recorded values, `pnpm build`, and collect E once more to `<scratch>/portfolio/E2/{mobile,desktop}`. Never run `git add`, `git stash`, `git checkout` or `git commit` during this step.
5. Run the Step 24 script on all folders. Report, for mobile and desktop: score, FCP, LCP, LCP element, TBT, CLS and images requested before the real LCP for E, D and E2; the earlier figures (2026-10-27: eager 0.80, deferred 0.91 on mobile; unit-1 run "B": 0.90 with the grid visible and deferred).
6. **Decision rule (BR-DMS-05):** if the median mobile score of E is below 0.9, or below that of D, or if E and E2 differ by more than 0.02 (noise; then repeat with 5 runs and say so), the result goes to the owner with both tables before anything else is built on it. Do not switch to D, do not edit `lighthouserc*.cjs`, do not "fix" the score. Desktop must stay at 0.9 or better; below that is also reported.
- Done when: the three result sets exist, the files are restored (checksum equal, `git status --short` equal to the recorded one), `dist` was rebuilt from the real code, and the tables and the decision-rule outcome are ready for Step 27.
### Step 27: Measurement report [x]
- Executor: Sonnet.
- Implements: BR-DMS-01 to 05; NFR-PR-P-01, P-03; CP5.
- Do: write `aidlc-docs/features/prerendering/construction/display-fallbacks/code/measurement-display.md`: method, commit hash, machine, Node version; side-by-side mobile and desktop tables (master baseline, unit 1 A, unit 2) per URL for score, FCP, LCP, TBT, CLS, entry and all JavaScript gzip sizes; LCP elements and real versus simulated LCP per URL; the answers to BR-DMS-03 (what improved as expected, what did not); BR-DMS-04 items still open (`/` about 0.85, the four shoot pages below 0.9 if so); V-D5 with the E, D, E2 tables and the decision-rule outcome in the first lines if it triggers; V-D7, V-D10, V-D14; the trace result. Neutral reading only ("better", "worse", "equal"), no recommendation to change targets: the owner decides (NFR-PR-P-01).
- Done when: **CP5**: the report exists, restored state verified again with `git status --short`, verification log rows V-D5, V-D7, V-D10, V-D14 filled.
---
## Part I: Documents (batch B8)
### Step 28: Code summary [ ]
- Executor: Sonnet.
- Do: write `aidlc-docs/features/prerendering/construction/display-fallbacks/code/code-summary.md` in the format of `construction/start-migration/code/code-summary.md`: status; commits (leave "to be filled by the main session"); files created, modified and removed (from `git status --short` and `git diff --stat`), grouped by the component groups of frontend-components.md, with the rule ids each implements; test inventory (files, counts, which properties P18 to P25 where, which existing tests changed and why: § 6 and the Step 14 and 20 records); the verification log V-D1 to V-D15 condensed; the Step 23 outcome; deviations (should be none); what unit 3 can rely on; open points for the owner (the BR-DMS-05 outcome if it triggered, V-D4 browsers, `/` and shoot-page scores).
- Done when: the file exists and every file of the diff is listed.
### Step 29: Shared reverse-engineering delta [ ]
- Executor: Sonnet.
- Implements: NFR-PR-Q-05.
- Files: `aidlc-docs/_shared/reverse-engineering/code-structure.md`, `component-inventory.md`, `architecture.md`, `business-overview.md` (and others only where `grep` finds `Reveal`, `DeferredImage`, `NavigationBar`, `eagerCount` or "fade-in" described).
- Do: minimal, line-level edits for this feature, marked in the style earlier edits of this feature use: new `lib/revealPhase.ts`, `lib/firstRow.ts`, `components/NoScript/`, `NoScriptNav.tsx`, `preloadImage` in `seo.ts`, `data-requires-js` and the other markers, the `useReveal` behaviour (visible by default, layout effect), the `DeferredImage` twin, the `PortfolioGrid` `eagerFirstRow` prop, new e2e files and test files. Do not rewrite sections.
- Done when: `git diff -- aidlc-docs/_shared/reverse-engineering` shows only line-level edits for this feature.
---
## 4. Suggested logical commit boundaries (for the main session; commit and push only when the owner approves)
1. Docs: this plan and the verification log (aidlc-docs only).
2. `Reveal` and `useReveal` with `lib/revealPhase.ts`, their tests and generators (Steps 2, 12, 13 in part, 14 in part).
3. Images: `DeferredImage` twin, `NoScriptStyles`, `__root.tsx`, the complete CSS and its tests (Steps 3, 6, 8, 14 in part).
4. Menu without JavaScript: `NoScriptNav.tsx` and the navigation attributes, markers in Hero, FilterBar, Testimonials, Footer, with tests (Steps 7, 9, 11).
5. First photo: `seo.ts` `preloadImage`, `lib/firstRow.ts`, `PortfolioGrid`, `PortfolioGallery`, the two route heads, `ContactDetails`, with tests (Steps 4, 10, 13, 14).
6. Browser tests: `e2e/` (Steps 15 to 20).
7. Docs: proof report, measurement, code summary, reverse-engineering delta (Steps 5, 27 to 29).
## 5. Open points for the main session (not plannable without a decision)
- **V-D4 in Firefox, Safari and Chrome on Android.** Agents only have desktop Chrome through Playwright. The fragment-to-fixed-element behaviour in the other browsers must be checked by a person; if one scrolls, the design says the target moves to a zero-size fixed element (BR-NAV-07), which is then a change request.
- **The outcome of BR-DMS-05.** The owner chose the eager first row; if it measures below 0.9 or below the deferred variant, the owner decides. The plan stops at reporting.
- **Lighthouse CLI gather mode** for the traces (Step 24.4) may not be available through `pnpm exec lighthouse`; then the trace is not obtained and V-D10 stays open.
- **Router link types** for `media` and `fetchPriority` in route `head()` links (Step 4.6, Step 10): if the types reject them, the design needs a decision (a typed helper or another place for the preload).
- **Which tile is the largest paint** at each width after the change (V-D14) can only be known by measuring; the plan records it and does not act on it.
- **Port 4173 and the CPU** are shared with peer sessions; the main session claims and releases them around Part H.
## 6. Existing tests that legitimately change (all others must pass unchanged)
| Test | Change | Reason | Step |
|---|---|---|---|
| `src/hooks/useReveal.test.tsx`: "is hidden in the server render" | Now expects visible | BR-RVL-01: the first render is visible | 14 |
| `useReveal.test.tsx`: "stays hidden until the element scrolls into view, then stops observing" | Needs a stubbed rectangle below `innerHeight`; hidden only after the layout effect | BR-RVL-02, jsdom has no layout | 14 |
| `useReveal.test.tsx`: "stays hidden after hydrating until the element scrolls into view" | Same stub | BR-RVL-02 | 14 |
| `useReveal.test.tsx`: "disconnects when the element unmounts before it was seen" | Needs the stub, otherwise no observer is created for an in-view element | BR-RVL-03 | 14 |
| `useReveal.test.tsx`: "is visible right away when the visitor prefers reduced motion" | No observer at all is created (before: created and disconnected) | BR-RVL-07 | 14 |
| `useReveal.test.tsx`: "assumes no reduced motion in the hydrating render, then follows the preference" | Reduced motion is read in the layout effect, not through Chakra's hook | BR-RVL-07 | 14 |
| `src/components/PortfolioGrid/PortfolioGrid.test.tsx` | `eagerCount={3}` becomes the new prop; eager tile assertions follow BR-PRE-08 | The prop is replaced | 14 |
| `src/components/portfolio/PortfolioGallery/PortfolioGallery.test.tsx` | Only an assertion that the first photos have no `src` before load, if there is one | `eagerCount={0}` is gone | 14 |
| `src/components/NoScript/noScriptCss.test.tsx` "group expanded" rule | Exact string split in two: the group keeps `grid-template-rows:1fr;transition:none`, `visibility:visible` moves to `#mobile-nav:target [id^="mobile-group-"]` | BR-NAV-06 against BR-NAV-08: a visible child of a hidden parent is focusable; owner ratified | 17 |
| `e2e/interaction.e2e.ts` V15 block | Comment only | The no-JavaScript page now shows content | 20 |
| `e2e/rawHtml.e2e.ts` link and image counts | Exclude `noscript` content from the counts | `DOMParser` parses `noscript` as markup | 20 |
Not changed (named so nobody loosens them): V9 (`interaction.e2e.ts`), V8 and BR-HYD-20 (`hydration.e2e.ts`), `Reveal.test.tsx` existing cases, `DeferredImage.test.tsx` existing cases, all navigation tests, `src/prerender.test.tsx`.