70 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:
Revealis 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).DeferredImagegets a<noscript>twin so photos show without JavaScript, with the empty image hidden by CSS (BR-IMG).- The mobile menu works without JavaScript through
<noscript>links and:targetCSS, 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>. - First-photo preload: React already writes the preload for plain high-priority photos; unit 2 adds the explicit
medialinks 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). - 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/)
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.construction/display-fallbacks/functional-design/business-logic-model.md(flows, evidence, properties P18 to P25).construction/display-fallbacks/functional-design/domain-entities.md(reveal phases, markers, ids, preload link, first row).construction/display-fallbacks/functional-design/frontend-components.md(per-component contract, call sites, test list).construction/start-migration/functional-design/business-rules.md(BR-HYD, BR-MAIL, BR-LZY, BR-TST, BR-SCR) andconstruction/start-migration/code/code-summary.md,verification-log.md,measurement-gate.md.inception/requirements/requirements.md(FR-PR-09 to 13, 21, 22) andinception/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, branchfeature/prerendering. It already hasnode_modules. Application code underweb/, documentation underaidlc-docs/. Never put application code inaidlc-docs/. - Run commands from
web/. Package manager: pnpm. Scripts:pnpm lint,pnpm format:check(fix withpnpm exec prettier --write <files>),pnpm test(vitest with coverage and thresholds),pnpm build(tsc, Start build with prerender, script step),pnpm e2e(browser tests againstdist/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; setMSYS_NO_PATHCONV=1before commands that take URL paths such as/portfolio. Use plainrm/cp, nevergit rm/git mv. - Browser probes (Steps 2 to 4, 24 to 26) are scratch
.mjsscripts kept outside the repository, in a scratch folder (for example$env:TEMP\prerendering-display). They loadplaywright-corethroughcreateRequire('<web>/package.json'), startstartPreviewServer(<web>/dist/client, 0)fromconfig/previewServer.ts(import it byfile://URL; Node 24 strips types), and launch Chrome withexecutablePath: process.env.CHROME_PATHorchannel: 'chrome', ase2e/support/browser.tsdoes. - 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
- No git write commands (
add,commit,push,stash,reset,checkout --,rm,mv, branch operations).git status,git diff,git log,git rev-parseare allowed. The main session commits and pushes, only when the owner approved. Never editaidlc-docs/features/prerendering/audit.md,aidlc-state.mdorinception/requirements/requirements.md; the main session does. - Install nothing. This unit adds no dependency: no
pnpm install,pnpm add,pnpm remove. Do not editpnpm-lock.yamlorpnpm-workspace.yaml. - 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 --noEmitstill 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. - 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 insrc/, relative imports with explicit.tsextension inconfig/only. Comments explain why, not what; density like the neighbours. Language of new comments, test titles and messages follows the neighbouring files (hooks,libimplementations 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 asBR-RVL-03are allowed, as in neighbouring code. - 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.
- Automation-friendly code. Every new interactive element gets a stable
data-testidnamed{component}-{role}like the existing ones. New testids in this unit:nav-noscript-open,nav-noscript-close. - 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. - Property-based tests (fast-check, already a dependency): use the global seed from
config/testSeed.ts(never set aseedyourself, never disable shrinking), put domain generators in shared files undersrc/test/(reusesrc/test/arbitraries.ts:contentImage,galleryItem,galleryItems,portfolioPhotosand 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. - Hydration tests (lesson from unit 1): a test that hydrates a page must let Router's own
hydrate()run, throughhydrateAppAsStartfromsrc/test/hydrate.tsx.hydrateApploads the client router first and hides mismatches Start would show. Component-level hydration of a single element may usehydrate()from the same file; page-level never. - Tests never go in
src/routes/. The route generator reads every file there and treats a test as a route. Page-level tests live insrc/root (src/displayHydration.test.tsx,src/displayPrerender.test.tsx). distmust be a current build wheneverpnpm e2eor a browser probe runs. Runpnpm build && pnpm e2ein one command line after any source change, and before a probe runpnpm buildyourself. A staledistgives false passes and false failures (it did in unit 1). Never runpnpm e2eafter editing only tests without checkingdistis newer than the last source edit (ls -l --time-style=full-iso dist/client/index.htmlagainstgit status).- Concurrent batches (§ 2): while batches run in parallel, run only targeted
vitest run <file>andtsc --noEmit, neverpnpm build,pnpm test,pnpm e2eor a probe, and only touch the files your batch owns. - 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. - Measurement conditions (Steps 24 to 27): port 4173 must be free (
Get-NetTCPConnection -LocalPort 4173returns 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. - 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 [ ]
- Executor: Haiku.
- Implements: NFR-PR-Q-01 (baseline), setup.
- Do (in
web/; do not install anything):git rev-parse HEAD,git branch --show-current(must befeature/prerendering),git status --short(expected: clean apart from untrackedweb/.tanstack/and possibly docs; write what you see).- Run
pnpm lint,pnpm format:check,pnpm test,pnpm build && pnpm e2ein that order. Note test files and tests passed, the fast-check seed line, the e2e file and test counts. - Create
aidlc-docs/features/prerendering/construction/display-fallbacks/code/verification-log.mdwith 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, Statusopen).
- 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.mdwith commit hash, date, Node and pnpm versions, counts, seed, and thegit status --shortoutput.
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) [ ]
- 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; changeweb/src/hooks/useReveal.ts,web/src/components/Reveal/Reveal.tsx; createweb/src/displayHydration.test.tsx(first test only). - Do:
revealPhase.ts:export type RevealPhase = 'settled' | 'hidden' | 'revealed';startsHidden(top: number, viewportHeight: number): booleanreturnstop >= viewportHeight;nextRevealPhase(phase: RevealPhase, event: 'belowViewport' | 'inView' | 'intersected'): RevealPhaseper domain-entities.md § 2:settled+belowViewportbecomeshidden;hidden+intersectedbecomesrevealed; every other combination returns the phase unchanged. Pure, no DOM, no React.useReveal.ts: keep the signatureuseReveal<T extends Element>(), return{ ref, visible, animated }. Statephasestarts'settled'. AuseLayoutEffectwith an empty dependency list readsref.current; iftypeof IntersectionObserver === 'undefined', orwindow.matchMedia('(prefers-reduced-motion: reduce)').matches, it returns; otherwise ifstartsHidden(element.getBoundingClientRect().top, window.innerHeight)it sets the phase throughnextRevealPhase(..., 'belowViewport'). While the phase ishidden, observe withuseInView<T>({ threshold: 0.12, rootMargin: '0px 0px -60px 0px', skip: phase !== 'hidden' })(reuse itsref; do not create a second observer implementation); the effective phase isrevealedwhen the phase ishiddenandinViewis true.visibleis the effective phase not beinghidden;animatedis it beingrevealed. RemoveuseMediaQueryfrom this hook (the comment says why: the layout effect runs before Chakra's media-query effect).Reveal.tsx: props unchanged (BoxPropsplusdelay).data-revealisvisibleorhidden. Styles per phase as in domain-entities.md § 2: settled and revealedopacity1,transformnone; hiddenopacity0,transformtranslateY(24px); thetransitionProperty,transitionDuration(tokenreveal),transitionTimingFunction(smooth) andtransitionDelay(${delay}s) props only whenanimated, otherwisetransition="none". Add_motionReduce={{ opacity: 1, transform: 'none', transition: 'none' }}before{...rest}.displayHydration.test.tsx: one test that hydrates<Reveal>content insideChakraProviderunderReact.StrictModewithgetBoundingClientRectstubbed to a top above and a top belowinnerHeight, usinghydrate()from@/test/hydrate: no recoverable error; the in-view one never leavesdata-reveal="visible"; the below-the-fold one becomeshiddenafter hydration andvisibleafter the fake observer fires.- Real-browser proof:
pnpm build; write a scratch probe that, for/over-mij,/soorten-fotoshoots,/portfolioat 412 x 823 and/and/over-mijat 1350 x 940, installs throughaddInitScriptarequestAnimationFrameloop samplinggetComputedStyle(el).opacityof every[data-reveal]from the first frame for 2.5 s. Expected: elements whose top is belowinnerHeightat 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 withreducedMotion: 'reduce': all stay 1.
- Done when: the probe shows the expected behaviour;
pnpm exec tsc --noEmit,pnpm lintclean;pnpm exec vitest run src/displayHydration.test.tsxgreen. The existinguseReveal.test.tsxcases 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) [ ]
- 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; changeweb/src/components/DeferredImage/DeferredImage.tsx,web/src/routes/__root.tsx. - Do:
noScriptCss.ts:export const NO_SCRIPT_CSSa string with, for now,noscript{display:contents}andimg[data-deferred]:not([src]){display:none!important}. No</, nourl(, no@import.NoScriptStyles.tsx:export default function NoScriptStyles()returns<noscript><style>{NO_SCRIPT_CSS}</style></noscript>. In__root.tsx, render<NoScriptStyles />directly after<HeadContent />inside<head>.DeferredImage.tsx: props unchanged. Return a fragment: the existingImageplusdata-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 thesrclogic stay on the first image only; the twin has noloadingand noref.- Real-browser proof (
pnpm build, scratch probe):- JavaScript on,
/soorten-fotoshootsand/portfolioat 1350 x 940: the set of image URLs requested up to theloadevent 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 thecurrentSrcvalues of the displayedimgelements plus the preloaded photos and logos. No console error or warning, no hydration error. view-sourcecheck:document.headcontains thenoscriptwith thestyle;document.querySelectorAll('noscript').lengthin the browser equals the count in the raw HTML file (readdist/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 displayedimghascompleteandnaturalWidth> 0, everyimg[data-deferred]has computeddisplay: none, no broken-image box (screenshot looked at).
- JavaScript on,
- Done when: V-D2 and V-D3 are OK;
tsc, lint clean;src/components/DeferredImage/DeferredImage.test.tsxstill passes unchanged (client render shows nonoscriptcontent). - 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) [ ]
- 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; changeweb/src/seo.ts,web/src/components/PortfolioGrid/PortfolioGrid.tsx,web/src/components/portfolio/PortfolioGallery/PortfolioGallery.tsx,web/src/routes/portfolio.tsx. - Do:
- 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/portfolioat 320 x 568, 412 x 823, 768 x 1024, 1023 x 768, 1024 x 768 and 1350 x 940. seo.ts: addexport type HeadLinkandexport function preloadImage(image: ContentImage, options?: { media?: string }): HeadLinkreturning{ rel: 'preload', as: 'image', href: image.src, fetchPriority: 'high', ...(options?.media ? { media: options.media } : {}) }and nothing else.pageHeadstays unchanged.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'whenindexis smaller than the base column count;{ media }of the first breakpoint whose column count exceedsindex;nullwhen no breakpoint does), andexport function firstRowPreloads(items: readonly { thumb: ContentImage }[], columns = GRID_COLUMNS): HeadLink[]returningpreloadImage(item.thumb, { media })for each item whosefirstRowhas amedia, in order. ImportspreloadImagefrom@/seo.PortfolioGrid.tsx: replace theeagerCountprop (default 3) byeagerFirstRow?: boolean(defaulttrue). Per tile (index in the list):firstRow(index)wheneagerFirstRow, otherwisenull.'always': the existing eagerImagewithsrc,fetchPriority="high",decoding="async".{ media }:<chakra.picture display="contents">with<source media={media} srcSet={item.thumb.src} />and theDeferredImageas itsimg, passingloading="eager"andfetchPriority="high"after the image style (these overrideDeferredImage's defaults, which spreadrestlast).null: theDeferredImageas today. The tile link, size, hover zoom and focus styles are untouched. The columns ofgridTemplateColumnsstay as they are.PortfolioGallery.tsx: stop passingeagerCount={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.routes/portfolio.tsx:head()returns{ ...base, links: [...base.links, ...firstRowPreloads(items)] }wherebase = pageHead('/portfolio')anditemsis the unfiltered list the page renders (toGalleryItems(filterPhotos(portfolioContent.photos, undefined), shootTypes)from@/lib/portfolioFilters; keep the existingscripts).tscmust accept themediaandfetchPrioritylink attributes; if the router's link type rejects them, STOP.- Proof (
pnpm build, scratch probe): (a)dist/client/portfolio.htmlhead holds React's preload for tile 1 and exactly two links withmedia="(min-width: 48em)"andmedia="(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 theloadevent 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 (transformon the tile image after hover) and keyboard focus ring still work on tiles 2 and 3; (f) the number of distinct tilexpositions in the first row at each width equals the column count ofGRID_COLUMNS(1 at 320 to 767, 2 at 768 to 1023, 3 from 1024).
- Before editing, with the existing
- Done when: V-D13 is OK;
tsc, lint clean;pnpm buildgreen.PortfolioGrid.test.tsxis 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 [ ]
- 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). Runpnpm exec tsc --noEmit,pnpm lint,pnpm build,pnpm testand list which tests fail (expected: theuseReveal.test.tsxcases andPortfolioGrid.test.tsxnamed 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 [ ]
- 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_CSSas one string built from named parts (one constant per group, joined) so each group is readable and testable. ExportMOBILE_NAV_ID = 'mobile-nav'andHEADER_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 ofspanchildren attop15, 21, 27 px,left10 px, 24 x 2 px,background:currentColor, colour inherited), hidden withdisplay:nonefrom@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 setdisplay)#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 exceptcurrentColor. 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 [ ]
- 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; changeNavigationBar.tsx,MobileNav.tsx,MobileNavGroup.tsx,NavSubmenu.tsxin the same folder. - Do:
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 insidenoscript). Both strings already exist asaria-labeltext in the navigation.NavigationBar.tsx:id={HEADER_ID}on thechakra.header;data-requires-json the hamburgerchakra.button;<NoScriptMenuOpen />in the right-handdivbefore the button;loading="lazy"on the light logoImagewhen!isHome(isHomeis already computed from the pathname). No change to the reducer, ARIA or focus code.MobileNav.tsx:<NoScriptMenuClose />as the first child of the contentBox(before thenav).idstaysmobile-nav(useMOBILE_NAV_IDwhere the id is passed inNavigationBar).MobileNavGroup.tsx:data-requires-json the chevron button.NavSubmenu.tsx:data-submenuon the wrapperBox(the one with therefandonBlur),data-submenu-panelon the panelBox,data-requires-json 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 nonoscriptcontent);renderToStringof the navigation contains both links.
Step 8: Tests for the menu and the CSS [ ]
- 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 arenderToStringofNavigationBarandMobileNavinside the memory router: idssite-headerandmobile-navexist,data-submenu,data-submenu-panelanddata-requires-jsare present on the right elements); no e-mail address (emailAddress(siteContent.email)as a string is not in the CSS). Links:renderToStringofNoScriptMenuOpenandNoScriptMenuClosegives anoscriptwith oneaeach, the righthref,aria-labeland text, nostyleelement inside; the light logo hasloading="lazy"on/over-mijand not on/in server markup. - Done when:
pnpm exec vitest run src/components/NoScript src/components/NavigationBargreen.
Part D: Markers and preload hygiene (batch B3, Sonnet; parallel with B2 and B4)
Step 9: data-requires-js and the footer column [ ]
- 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-json each arrowArrowButton, on the pause button, on the hero progress barBox, on theFilterBarrootdiv, on the 48 px controls spacerBoxinCarouselPlaceholder.FooterColumntakes an optionalrequiresJs?: booleanprop that setsdata-requires-json its rootBox; the Contact column inFooter.tsxpassesrequiresJs. Thedata-email-pendingplaceholders already exist (unit 1); do not change them. Nothing else changes: the review copies stay hidden,aria-hiddenandinert(BR-NJS-04). - Done when:
tsc, lint clean; the existing tests of these folders pass unchanged.
Step 10: Preload hygiene for the contact page [ ]
- 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 portraitImageofContactDetails(it isdisplay: nonefromlg; a lazy image is neither fetched while hidden nor hoisted by React).routes/contact.tsx: importASIDE_MEDIAfrom../components/contact/ContactAside/ContactAsideandpreloadImagefrom../seo;head()returnslinks: [...base.links, preloadImage(contactContent.image, { media: ASIDE_MEDIA })]withbase = pageHead('/contact'), keeping the existingscripts. - Done when:
tsc, lint clean;ContactDetails.test.tsxand the contact route tests pass unchanged;pnpm exec vitest run src/seo.test.tsstill green.
Step 11: Tests for markers and preload hygiene [ ]
- Executor: Sonnet.
- Implements: BR-DTS-02; PBT: "No PBT properties identified" (attribute additions).
- Files: create
web/src/components/Hero/hero.noscript.test.tsxand add cases to the existingFilterBar.test.tsx,Testimonials.test.tsx,Footer.test.tsx,ContactDetails.test.tsx(newitblocks only). - Do: through
renderToString/serverHtml(not client render, which dropsnoscriptbut keeps attributes): hero arrows, pause button and progress bar carrydata-requires-js; theFilterBarroot does; the testimonial controls spacer does while the hidden review copies keeparia-hiddenandinert; the footer Contact column hasdata-requires-jsand no other column has; the contact portrait hasloading="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 [ ]
- 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 agalleryItemsWithThumbsbuilt fromgalleryItemsinarbitraries.ts. Do not add anything toarbitraries.ts. - Done when:
tscclean; the files are used by Step 13 (check withgrep).
Step 13: Properties P18 to P25 [ ]
- 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 toweb/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 >= viewportHeightgives true, smaller gives false, for any finite numbers; equal gives true. - P19
startsHidden(metamorphic): if hidden attopthen hidden at every largertop; adding the same offset totopandviewportHeightdoes not change the result. - P20
nextRevealPhase(invariant, state machine): over any event sequence fromsettledorhidden, the phase never goes fromrevealedtohiddenorsettled, and never fromsettledtorevealed. - P21
nextRevealPhase(idempotent): applying the same event twice equals applying it once, for any phase and event. - P22
preloadImage(invariant): for anycontentImageand options,hrefequalsimage.src,relispreload,asisimage,fetchPriorityishigh,mediapresent exactly when given and equal, and the key set is exactly those. - P24
firstRow(invariant):'always'exactly whenindexis smaller than the base column count;nullexactly when it is not smaller than the largest column count; otherwise{ media }of the first breakpoint whose column count exceedsindex. - P25
firstRowandfirstRowPreloads(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;firstRowPreloadsyields one link per tile with amedia, none for'always'ornull,hrefequal to that tile'sthumb.src, never more links than largest minus base column count. - Example tests for every branch of
revealPhase.ts,firstRow.ts(the realGRID_COLUMNS: tile 1 always, tile 248em, tile 364em, tile 4 null) andpreloadImagewith and withoutmedia, sosrc/lib/**andsrc/seo.tsstay at 100 %.
- P18
- Done when:
pnpm exec vitest run src/lib/revealPhase.test.ts src/lib/firstRow.test.ts src/seo.test.tsgreen; a coverage run of those files shows 100 % forrevealPhase.ts,firstRow.tsand the newseo.tscode.
Step 14: Component, hydration and prerender tests [ ]
- 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); extendweb/src/displayHydration.test.tsx; createweb/src/displayPrerender.test.tsx. - Do:
useReveal.test.tsx: rewrite the cases § 6 names. jsdom has no layout, so stubgetBoundingClientRectto returntopabove and belowwindow.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 andanimatedis true; reduced motion hides nothing and creates no observer; noIntersectionObserverstays 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 hasdata-reveal="hidden",opacity0 and no transition; revealed element has the transition anddelay.DeferredImage.test.tsx: keep all cases; addrenderToStringcases: twin exactly once withsrc,alt,width,height, noloading, noref/id/data-testid; first image hasdata-deferredand nosrc; no<link rel="preload"appears for the twin when rendered in a document context throughprerenderfromreact-dom/static; hydrating the pair reports no error (hydrate()).PortfolioGrid.test.tsx: replaceeagerCount={3}by the new prop; assertions: server markup has tile 1 as a plainimgwithsrc, tiles 2 and 3 insidepicturewithsource[media]of 48em and 64em, tile 4 and updata-deferredwithoutsrc;eagerFirstRow={false}makes all tiles deferred; the media of tiles agree withGRID_COLUMNS.PortfolioGallery.test.tsx: change only an assertion that expects the first photos to have nosrcbefore load, and say which.displayHydration.test.tsx: withhydrateAppAsStart(neverhydrateApp):/portfolio,/,/over-mij,/contactand/soorten-fotoshoots/loveshoothydrate without recoverable error; on/portfoliothe first-row picture tiles hydrate and the filter?shoot=gezinapplies 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 ofsrc/prerender.test.tsx): for everysitePagespath, the prerendered HTML contains one noscript twin perdata-deferredimage and nodata-reveal="hidden".
- Done when: CP2 (after B2 and B3 are also done):
pnpm testgreen with coverage thresholds,pnpm lint,pnpm format:check,pnpm exec tsc --noEmit,pnpm buildgreen. - Record: list every existing test changed, with the reason.
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) [ ]
- 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
fetchof the preview server for the eleven pages and/404.html: in<head>exactly onenoscriptholding onestyle, with none of</,url(,@import; the assembled e-mail address (all forms used inrawHtml.e2e.ts) occurs nowhere; everylink[rel=preload][as=image]href occurs once per file; every page with apriorityphoto (/,/over-mij,/soorten-fotoshoots, five shoot pages) has the preload withfetchpriority="high"for it;/contacthas a link withmedia="(min-width: 64em)"for the aside photo and no other link for that file;/portfoliohas React's link for tile 1 and exactly twomedialinks (48em, 64em) for two different photos; the light logo preload is absent on every page except/; the contact portrait preload is absent; everyimg[data-deferred]is followed by anoscriptcontaining animgwith the samealt; 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) [ ]
- 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, afternetworkidle: no visiblebuttonelement; every[data-reveal]has computed opacity 1; every displayedimgiscompletewithnaturalWidth> 0; everyimg[data-deferred]has computeddisplay: none; the number of displayedimgwith non-emptyaltequals the numbergetByRole('img')finds (each photo once in the accessibility tree); no element matching[data-email-pending]or[data-requires-js]is displayed; noa[href^="mailto:"]; the footer has no heading named "Contact" and no empty column (checked withgetByRole('contentinfo')); on/: nohero-prev-button,hero-next-button,hero-pause-buttonorhero-progressdisplayed and the first slide's photo displayed; on/portfolio: nofilter-bardisplayed, every tile link'shrefends in an image file; the testimonials block shows one review (unit-1 V9 stays as is). Screenshots of every page and width are saved whenE2E_SCREENSHOT_DIRis 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) [ ]
- 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-opendisplayed, 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
scrollY300; clicknav-noscript-open;location.hashis#mobile-nav, the panel is visible, the five shoot links (Newborn, Zwangerschap, Gezin, Loveshoot, Portretten) are visible without any click on a chevron,scrollYis still 300; clicknav-noscript-close; the panel hidden again, hash#site-header,scrollYstill 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 (readdocument.activeElementafter each key, without any pause, which also provestransition: nonewhere 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-openis not displayed, and loading/over-mij#mobile-navshows 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.
- 390 x 800: hamburger (
- 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) [ ]
- 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,/contactand one shoot page at 390 x 823 and 1350 x 940, an init script samplesgetComputedStyle(el).opacityof every[data-reveal]on every animation frame from the first frame to 2 s after hydration. Elements whose top is aboveinnerHeightat 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 aredata-reveal="hidden"after hydration. - On scroll: scroll a hidden element into view; within 1.5 s its opacity reaches 1 and
data-revealisvisible; a staggered row (/pricing cards at 1350) reveals with increasing delays when below the fold. /portfolioat 412 x 823: the grid wrapper (the[data-reveal]containingportfolio-grid) isvisibleat load (regression for the old empty-grid defect).- Reduced motion (
reducedMotion: 'reduce'context): every[data-reveal]isvisiblewith 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 ishiddenafter hydration has a height of at most(innerHeight - 60) / 0.12; list the tallest per page in the Record.
- No flash: for
- Done when: green in Step 21; V-D6 filled.
Step 19: Images and preloads per width (FR-PR-11, 21; V-D13, V-D15) [ ]
- 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')andperformance.getEntriesByType('resource')):- Twin not fetched: on
/soorten-fotoshootsand/portfolioat 1350 x 940, up to theloadevent plus 500 ms, only photos that are in the first row, preloaded orsrc-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 eachlink[rel=preload][as=image]of the loaded document; logos excluded by name):/portfoliohas 1, 2 and 3 matching photo preloads at 390, 768 and 1350 px;/contacthas 0 at 390 and 768 and 1 at 1350;/and/over-mijand the shoot pages have exactly 1 at every width. - Used and not duplicated: at each width every matching photo preload URL is the
currentSrcof a displayedimgand 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
xof 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 beforeload(V-D13); tile size is unchanged against the values recorded in Step 4. - V-D15: load
/portfolio?shoot=gezinat 1350: after the filter applies and the page is scrolled to the bottom, no image URL was requested more than once.
- Twin not fetched: on
- Done when: green in Step 21; V-D13 and V-D15 filled.
Step 20: Existing browser tests whose expectations change [ ]
- Executor: Sonnet.
- Implements: BR-DTS-04; V-D8.
- Files:
web/e2e/interaction.e2e.ts,web/e2e/rawHtml.e2e.ts(andhydration.e2e.tsonly 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:
interaction.e2e.tsV15 block ("stijlen zonder en met JavaScript"): its comment saysRevealand 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 andmainequal with and without JavaScript) stay exactly as they are.rawHtml.e2e.tslink and image counts (V-D8):DOMParserparsesnoscriptcontent as markup, soa[href]now also finds the two#mobile-nav/#site-headerlinks andimgfinds twins. Restrict a count or an "every link" check to links and images outsidenoscript(for example by removingnoscriptelements from the clone first, asbodyTextalready does formain), 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 [ ]
- 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 [ ]
- 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 >= innerHeighttest, why the CSS lives in<head>insidenoscript, whydisplay: contentsonnoscript, whytransition: noneon 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; noTODOwithout owner;data-testidnaming; thePortfolioGallerycomment as BR-PRE-08 says. Runpnpm exec prettier --writeon touched files, thenpnpm lintandpnpm format:check. - Done when: lint and format checks are clean and
git diff --statshows only files named in this plan (plussrc/routeTree.gen.tsonly if a route file changed, which it should not).
Step 23: Full verification (Code Generation Step 13.5) [ ]
- 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 withFC_SEED=<seed>; a failure that passes on a different seed is a real finding, report it, do not retry until green). Do not runpnpm 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) [ ]
- 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:
- Write (Sonnet) a Node script in the scratch folder that reads every
lhr-*.jsonof a folder and prints, per URL, the median over the runs of:categories.performance.score, FCP, LCP, TBT, CLS, the sum oftransferSizeofScriptrequests; plus from the median-LCP run: the LCP element (selector and snippet),observedLargestContentfulPaintand the transfer sizes of images requested before it (names and KB). Reuse it in Steps 25 and 26. - Remove
.lighthouseci. Mobile:pnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=3then move.lighthousecito<scratch>/u2/mobile; desktop likewise withlighthouserc.desktop.cjsto<scratch>/u2/desktop. Same URL list as unit 1 (the configs are not edited; the not-found URL is/404.html). - Compare with
aidlc-docs/features/prerendering/construction/start-migration/code/measurement-gate.md(master baseline, unit 1 "A" and "B") andmeasurement-baseline.md. - 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 oflighthouserc.cjsand the Chrome flags it uses, againstpnpm preview --port 4173 --strictPortstarted and stopped by you). Ifpnpm exec lighthousedoes not exist or gather mode fails, write "trace not obtained" with the error in the report; this is not a STOP.
- Write (Sonnet) a Node script in the scratch folder that reads every
- 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) [ ]
- 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
PerformanceObserverforlargest-contentful-paintregistered byaddInitScript; 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/portfoliostate 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>/u2and the unit-1 numbers,imgKBbefore 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-mijand 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 movedinline-*.jsfiles 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) [ ]
- 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:
- Record
git status --short(status-before.txt), the SHA-256 ofweb/src/components/portfolio/PortfolioGallery/PortfolioGallery.tsxandweb/src/routes/portfolio.tsx, and scratch copies of both files. - 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--urlon 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 editlighthouserc.cjs), then the same withlighthouserc.desktop.cjs. Move results to<scratch>/portfolio/E/{mobile,desktop}. - Build D (temporary, never committed): in
PortfolioGallery.tsxpasseagerFirstRow={false}; inroutes/portfolio.tsxmakefirstRowPreloads(items)contribute no links (an empty array); nothing else.pnpm build; collect the same way to<scratch>/portfolio/D/{mobile,desktop}. - Drift check: restore both files, verify the SHA-256 and
git status --shortequal the recorded values,pnpm build, and collect E once more to<scratch>/portfolio/E2/{mobile,desktop}. Never rungit add,git stash,git checkoutorgit commitduring this step. - 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).
- 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.
- Record
- Done when: the three result sets exist, the files are restored (checksum equal,
git status --shortequal to the recorded one),distwas rebuilt from the real code, and the tables and the decision-rule outcome are ready for Step 27.
Step 27: Measurement report [ ]
- 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.mdin the format ofconstruction/start-migration/code/code-summary.md: status; commits (leave "to be filled by the main session"); files created, modified and removed (fromgit status --shortandgit 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 wheregrepfindsReveal,DeferredImage,NavigationBar,eagerCountor "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,preloadImageinseo.ts,data-requires-jsand the other markers, theuseRevealbehaviour (visible by default, layout effect), theDeferredImagetwin, thePortfolioGrideagerFirstRowprop, new e2e files and test files. Do not rewrite sections. - Done when:
git diff -- aidlc-docs/_shared/reverse-engineeringshows only line-level edits for this feature.
4. Suggested logical commit boundaries (for the main session; commit and push only when the owner approves)
- Docs: this plan and the verification log (aidlc-docs only).
RevealanduseRevealwithlib/revealPhase.ts, their tests and generators (Steps 2, 12, 13 in part, 14 in part).- Images:
DeferredImagetwin,NoScriptStyles,__root.tsx, the complete CSS and its tests (Steps 3, 6, 8, 14 in part). - Menu without JavaScript:
NoScriptNav.tsxand the navigation attributes, markers in Hero, FilterBar, Testimonials, Footer, with tests (Steps 7, 9, 11). - First photo:
seo.tspreloadImage,lib/firstRow.ts,PortfolioGrid,PortfolioGallery, the two route heads,ContactDetails, with tests (Steps 4, 10, 13, 14). - Browser tests:
e2e/(Steps 15 to 20). - 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
mediaandfetchPriorityin routehead()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 |
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.