Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/plans/display-fallbacks-code-generation-plan.md
SluijsensandClaude Opus 5.5 b5fd83256d Loads the light logo after the page load
Lazy loading saved its bytes during page load, but left the logo empty for a
moment when navigating to the homepage on a wide screen. Also adds the second
unit's code summary and the shared docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 01:56:13 +01:00

71 KiB

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).
  • 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)

  • 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 [x]

  • 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 [x]

  • 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
src/components/NavigationBar/NavigationBar.test.tsx (new case) and e2e/images.e2e.ts "logo's" The light logo is lazy until the page has loaded, then eager: the e2e expectation "light logo only on /" becomes "requested after load once off /, before load only on /"; a flash check on navigation to / is added V-D7 found a flash on a client navigation to / with a permanently lazy hidden logo; owner decided the fix after B7
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.