The route generator scans that folder and warned about the test file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
67 KiB
Code Generation Plan - Unit 1: Start migration and script step
Feature: prerendering. Unit: 1 "start-migration". 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
React 19 + Vite + TanStack Router + Chakra UI v3 SPA in web/ moves to TanStack Start static prerendering. Every page is written as an HTML file; a post-build step moves Start's inline scripts into files so the strict CSP (script-src 'self' + Umami) stays unchanged. Unit 1 covers: FR-PR-01 to 08, 19, 20, 22; the catch-all route part of FR-PR-14 and 15; NFR-PR-P-03, P-04, S-02, SEC-01 to 04, Q-01 to 05.
Out of scope (do not build, do not "prepare"): Reveal behaviour (the only allowed Reveal change is the temporary, never committed one in Step 34), DeferredImage no-JavaScript image, NoScriptNav, photo preload, nginx/IIS/serverConfig.ts/deploy/, Lighthouse targets in lighthouserc*.cjs (Step 24 may change only notFoundPath), upload order in the CI deploy jobs.
There are no user stories; the unit is traced to requirements. Dependencies on other units: none. Unit 2 and 3 depend on this unit (what it must leave: business-rules.md § 3).
0.2 Files to read (design, all under aidlc-docs/features/prerendering/)
construction/start-migration/functional-design/business-rules.md(rules BR-xxx, § 3 end state, § 4 verification points V1 to V18). Rule ids in this plan refer to it.construction/start-migration/functional-design/business-logic-model.md(algorithms, properties P1 to P17).construction/start-migration/functional-design/domain-entities.md(entities, hydration inventory).construction/start-migration/functional-design/frontend-components.md(per-component contract, test list).inception/application-design/(decisions D1 to D13, spike evidence),inception/requirements/requirements.md.
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. Application code underweb/, CI under.gitea/workflows/, documentation underaidlc-docs/. Never put application code inaidlc-docs/. - Run commands from
web/. Package manager: pnpm (version frompackageManager). Scripts:pnpm lint,pnpm format:check(fix withpnpm exec prettier --write <files>),pnpm test(vitest with coverage and thresholds),pnpm build,pnpm audit:deps. - Targeted tests while working:
pnpm exec vitest run <path>(no coverage). Full suite only at checkpoints. - Shell is Git Bash on Windows (also PowerShell). Use forward slashes in bash. Use plain
rm/cp, nevergit rm/git mv. - Verification outcomes V1 to V18 are recorded in ONE file:
aidlc-docs/features/prerendering/construction/start-migration/code/verification-log.md(created in Step 4: a table with columns V#, 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/start-migration/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, only when the owner approved. Never editaidlc-docs/features/prerendering/audit.mdoraidlc-state.md; the main session does. - Do not install anything except in Steps 1 and 4 (
pnpm install,pnpm add). Do not editpnpm-lock.yamlby hand. - STOP rule. If an unknown (V point) fails, a design rule cannot be implemented as written, a step's "Done when" cannot be reached, or a fix would change a design decision (any BR rule, any decision D1 to D13): 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, and return a report to the main session naming the step, the V 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/but relative imports with explicit.tsextension inconfig/(config files run under Node type stripping: no path aliases, no enums, no parameter properties,import typefor types,erasableSyntaxOnly). Comments explain why, not what; density like the neighbours. Language of new comments, test titles and messages follows the neighbouring files:config/*andsrc/libtests and the pages' older code are partly Dutch; hooks,libimplementations and newer components are English. When a file has Dutch comments, write Dutch; when its neighbours are English, write English. - Existing tests stay valid. Change an existing test only where BR-TST-02 says behaviour changed, and say so in the step's record.
- Automation-friendly code. Every new interactive element gets a stable
data-testidnamed{component}-{role}like the existing ones (footer-email-link,contact-gate-mail). Placeholders are not interactive but get a testid as listed in the steps. - Coverage. Thresholds are 100% for
src/lib/**,src/seo.ts,src/sitemap.ts; every new or changed function and branch insrc/libneeds 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:validEmail,anyEmail,routePath,pathSegment,knownRoutePathand others; new generators go in the new files named in the steps, not inarbitraries.ts), label each property test with its category in the title like the existing ones ((round-trip),(invariant),(idempotent),(oracle)), and keep an example-based test next to it. - Concurrent batches (see § 2): while batches run in parallel, run only targeted
vitest run <file>, neverpnpm build,pnpm test,pnpm installorpnpm add, and only touch the files your batch owns. - 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.
1. Checkpoints
| CP | After | State required |
|---|---|---|
| CP0 | Step 3 | pnpm test green (the unchanged old tests), pnpm exec tsc --noEmit clean |
| CP1 | Step 5 | pnpm build green with Start (prerender writes all pages and 404.html), pnpm test green |
| CP2 | Steps 13, 15 to 23 all done (merge point after the parallel batches) | pnpm test green with coverage thresholds, pnpm lint, pnpm exec tsc --noEmit, pnpm build green (without the runner in build yet) |
| CP3 | Step 24 | pnpm build green including the runner; the runner reports no violation on the real output |
| CP4 | Step 28 | pnpm lint, pnpm format:check, pnpm test, pnpm build, pnpm e2e, pnpm audit:deps all green |
| CP5 | Step 31 | Step 13.5 complete verification green |
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, 2 | H | none (exclusive: port 4173 and CPU) | none in the repo |
| B1 Early proof | 3 to 6 | S | none (sequential; risky unknowns first) | vite.config.ts, package.json, config/sitemapPlugin.ts, src/router.tsx, src/client.tsx, src/routes/__root.tsx, src/routes/$.tsx, src/test/renderApp.tsx, the hooks of Step 3, UmamiAnalytics, NavigationBar (ssr only), ContactSection, TestimonialCarousel |
| B2 Script step | 7 to 13 | S | B3, B4 | config/pageFiles*, config/inlineScripts*, config/externalizeInlineScripts*, src/test/htmlArbitraries.ts |
| B3 Hydration safety | 14 to 21 | S | B2, B4 | src/** except the B1 files and src/test/htmlArbitraries.ts and src/test/requestArbitraries.ts |
| B4 Preview server | 22, 23 | S | B2, B3 | config/previewServer*, src/test/requestArbitraries.ts |
| B5 Integration | 24 to 28 | H for 24 and 28, S for 25 to 27 | none (after CP2) | package.json, tsconfig.json, eslint.config.js, .gitignore, vitest.e2e.config.ts, vite.config.ts (test exclude only), e2e/**, .gitea/workflows/continuous_integration.yaml |
| B6 Finish | 29 to 34 | H for 30, 31, 34 runs; S for 29, 32, 33, 34 report | none (34 is exclusive: port 4173 and CPU) | aidlc-docs/**, comments |
B3 starts with Step 14 (needs nothing from B2 or B4) and may run its sub-steps sequentially. B2, B3 and B4 may run at the same time because their files are disjoint. If you run them one after another, the order B2, B4, B3 is fine. Step 24 and all of B5 wait for CP2.
3. Traceability
3.1 Properties (PBT-01) to steps
| Property | Function | Test step |
|---|---|---|
| P1 to P8 | externalizeInlineScripts, findExecutableInlineScripts |
9 |
| P9 | externalizeInlineScripts (split and join) |
9 |
| P10 | pageFile and pagePath |
10 |
| P11, P12 | planExternalization |
12 |
| P13 | address scan helper | 12 |
| P14, P15 | contactChannels, isEmailAddressValid |
15 |
| P16, P17 | resolveRequest |
23 |
PBT-02 (round-trip): P3, P10. PBT-03 (invariant): P1, P2, P5, P6, P8, P14, P16. PBT-04 (idempotence): P4, P11. PBT-05 (oracle): P7, P12, P13, P15, P17. PBT-06 (stateful): N/A, no stateful logic in this unit. PBT-07 (generators): domain generators in src/test/htmlArbitraries.ts and src/test/requestArbitraries.ts, reuse of arbitraries.ts. PBT-08: global seed, shrinking left on. PBT-10: each property has example-based tests next to it. P9 is the split-and-join variant of PBT-03/05.
3.2 Verification points to steps
| V | Settled in step | Recorded in |
|---|---|---|
| V1 client entry | 4 | verification log |
V2 shellComponent in jsdom |
5 | verification log |
| V3 inline scripts per real page | 4 (first look), 13 (final list) | verification log |
| V4 minimum moved scripts | 13 | verification log |
V5 index.html, crawling |
4 | verification log |
| V6 code splitting, unused router plugin | 4, 30 | verification log |
| V7 sitemap environment | 4 | verification log |
V8 lazy ContactForm in HTML and hydration |
27 | verification log |
| V9 testimonials in HTML, hidden slides | 21, 27 | verification log |
| V10 placeholder sizes, CLS below 0.01 | 17, 34 | verification log, measurement report |
| V11 one title, one noindex meta | 4 (normal pages), 27 (404.html) |
verification log |
| V12 404 hydration with real shell | 27 | verification log |
| V13 timestamps and build paths | 4, 13 | verification log |
| V14 focus on first load, tidy navigation | 27 | verification log |
| V15 Emotion/Chakra flicker | 4 (styles in HTML), 27 (screenshots) | verification log |
V16 Intl price text |
27 | verification log |
V17 no on*= or javascript: |
13, 27 | verification log |
| V18 CI artifact layout | 28 | verification log |
3.3 Requirements to steps
| Requirement | Steps |
|---|---|
| FR-PR-01 to 04 | 4, 7, 11, 13, 24, 27 |
| FR-PR-05 to 07 | 3, 16, 17, 18, 19 to 21, 27 |
| FR-PR-08 | 3, 4, 27 |
| FR-PR-19, 20 | 8, 9, 11, 12, 13, 24 |
| FR-PR-22 | 14, 15, 17, 21, 11, 27 |
| FR-PR-14, 15 (route part) | 4, 16, 20, 27 |
| NFR-PR-P-03, P-04 | 2, 34 |
| NFR-PR-S-02 | 27 |
| NFR-PR-SEC-01 to 04 | 4, 11, 22, 27, 30 |
| NFR-PR-Q-01 to 05 | 1, 5, 9 to 12, 15, 19 to 21, 23, 25 to 28, 29, 31 to 33 |
Part A: Setup and baseline (batch B0, Haiku, exclusive)
Step 1: Install and confirm a green baseline [x]
- Executor: Haiku.
- Implements: NFR-PR-Q-01 (baseline), setup.
- Do:
- In
web/:pnpm install --frozen-lockfile(the worktree has nonode_modules;postinstallrunschakra typegen). - Run
pnpm lint,pnpm format:check,pnpm test,pnpm build, in that order. Note the number of test files and tests passed and the fast-check seed line. - Run
git rev-parse HEADandgit status --short.
- In
- Done when: all four commands succeed on the untouched tree. If any fails, STOP (the baseline must be green before changes) and report the output.
- Record: create
aidlc-docs/features/prerendering/construction/start-migration/code/baseline-checks.mdwith the commit hash, the date, Node and pnpm versions, test counts, seed, and thegit statusoutput (the main session needs the pre-change status, including the untrackedweb/.tanstack/).
Step 2: Baseline measurement (BR-MEA-01) [x]
-
Record (2026-10-31):
code/measurement-baseline.md; the summary script is in the scratch foldersummarize-lhr.mjs(path in the report). Mobile and desktop both ran with no page errors (about 16 min for both). -
Executor: Haiku. Exclusive: nothing else may run during this step.
-
Implements: BR-MEA-01; NFR-PR-P-03.
-
Preconditions: Step 1 done;
web/distis the master build from Step 1. Port 4173 must be free (Get-NetTCPConnection -LocalPort 4173in PowerShell must return nothing) because Lighthouse CI startspnpm preview --port 4173 --strictPortitself. No CPU-heavy work may run during the measurement: no other build, test run, install, editor indexing job or other sub-agent. If the machine is busy, wait. Use the same machine, power plan and Node version for Step 34. -
Do (all in
web/; use a scratch folder outside the repository, for example$env:TEMP\prerendering-measure, for raw results and the helper script; neither is committed):- Delete
.lighthouseciandlighthouse-reportsif present. - Mobile:
pnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=3. Move.lighthousecito<scratch>/baseline/mobile. - Desktop:
pnpm exec lhci collect --config=lighthouserc.desktop.cjs --numberOfRuns=3. Move.lighthousecito<scratch>/baseline/desktop. (collectdoes not assert, so existing targets do not matter. The URL list includes/bestaat-niet, which master answers with 200 through the SPA fallback; keep it.) - Write a small Node script in the scratch folder that reads every
lhr-*.jsonof a folder and prints, per URL, the median over the three runs of:categories.performance.score, FCP, LCP, TBT (audits.*.numericValue), CLS, and the sum oftransferSizeof thenetwork-requestsitems withresourceTypeScript. It takes the folder as an argument. - Compute gzip sizes with Node
zlib.gzipSyncof: every file referenced by<script ... src>and<link rel="modulepreload">inweb/dist/index.html("entry JavaScript"), and of allweb/dist/assets/*.js("all JavaScript").
- Delete
-
Done when: the report exists with a table per device (rows = URL, columns = score, FCP, LCP, TBT, CLS, script transfer) plus the gzip numbers, method line (three runs, median, command lines), commit hash, machine description, Node version.
-
Record:
aidlc-docs/features/prerendering/construction/start-migration/code/measurement-baseline.md. Also keep the scratch script path in the report so Step 34 reuses the identical script.
Part B: Early proof with the real app (batch B1, Sonnet, sequential)
The unknowns that can invalidate the design come first. Steps 3 to 6 prove Start, getRouter, shellComponent, src/client.tsx and the test harness on the real app before the mechanical conversions. If an unknown fails, apply the STOP rule: report to the main session; do not improvise.
Step 3: Remove what makes prerendering throw [x]
- Executor: Sonnet.
- Implements: BR-HYD-02, 03, 04, 05, 07, 08 (media and breakpoint part), 09, 15; BR-MON-03; FR-PR-05, 08.
- Why first: with
{ ssr: false },document.readyState,document.hiddenandwindow.locationevaluated in render, the server render throws, so no page can be prerendered. These edits are small, pure React and covered by the old tests (CP0). The behaviour tests for them come in Step 19. - Files (modify unless "create"):
web/src/hooks/useHydrated.ts(create):useSyncExternalStore(subscribeNoop, () => true, () => false); one-line comment on why (same behaviour as the router's internaluseHydrated).web/src/hooks/usePageLoaded.ts: store-based,subscribeadds aloadlistener ({ once: true }) and returns its removal, snapshotdocument.readyState === 'complete', server snapshotfalse.web/src/hooks/useInView.ts: keep options and return shape.unsupportedfromuseSyncExternalStore(noopSubscribe, () => typeof IntersectionObserver === 'undefined', () => false);inView = skip || intersected || unsupported; the effect returns early when!element || skip || unsupported || intersected. Keep the "counts as in view" comment, adjusted.web/src/hooks/useReveal.ts,web/src/components/Hero/useHeroSlider.ts,web/src/components/home/ContactSection/ContactSection.tsx,web/src/components/home/Testimonials/TestimonialCarousel.tsx: remove{ ssr: false }fromuseMediaQuery; update the comments.web/src/components/Hero/useHeroSlider.ts:hiddenfrom a store (subscribetodocumentvisibilitychange, snapshotdocument.hidden, server snapshotfalse) instead ofuseState(() => document.hidden)plus effect.web/src/components/NavigationBar/NavigationBar.tsx: remove{ ssr: false }fromuseBreakpointValueonly (theactiveOptionschange is Step 16).web/src/components/Analytics/UmamiAnalytics.tsx:hostnameprop optional without a default; the effect useshostname ?? window.location.hostname.
- Done when: no
ssr: falseremains inweb/src(grep -rn "ssr: false" web/srcempty),pnpm exec tsc --noEmitis clean,pnpm lintis clean, and CP0:pnpm testpasses without test changes. If an old test fails because it relied on first-render media values, fix the test per BR-TST-02 (wrap inact/waitFor) and list the changed tests in the Record line. - Record: a line in
code/verification-log.mdis not needed yet; list changed old tests (if any) under the step in this plan. - Record (2026-10-31): CP0 green, 113 files, 888 tests. Changed old tests:
usePageLoaded.test.tsxandDeferredImage.test.tsx(the mockedreadyStatemust becomecompletewhen theloadevent fires, as in a browser, because the hook now reads a store snapshot);useReveal.test.tsx(first render assumes no reduced motion, so an observer starts and is disconnected at once; test expects all observers disconnected instead of none created).
Step 4: Start setup and first prerender of the real app (V1, V3, V5, V6, V7, V11, V13, V15, V17) [x]
- Executor: Sonnet.
- Implements: BR-BLD-02, 03, 05, 06, 07, 08, 09 (plugin part), 10 (n/a here), 11; BR-ENT-01 to 05; BR-404-01, 02; BR-MON-01; D1, D5, D13; FR-PR-01, 02, 03, 04, 08, 14 (route part); NFR-PR-Q-04, SEC-02.
- Do:
- In
web/:pnpm add @tanstack/react-start@1.169.4andpnpm add -D playwright-core@1.55.0(the Playwright version already pinned in CI asPLAYWRIGHT_VERSION; used from Step 26). If pnpm reports a peer conflict with@tanstack/react-router, try@tanstack/react-router@1.170.46(the spike's version); record the resolved versions. Any other conflict: STOP. Check that theserovalandseroval-pluginsoverrides inpnpm-workspace.yamlstill apply (pnpm why seroval). Runpnpm audit:deps; a failure that is not fixable by a patch bump: STOP. - Read Start's type definitions and docs in
node_modules/@tanstack/react-startfor the exact plugin and prerender option names (spike facts in application-design.md: output indist/client,autoSubfolderIndex: false, pages withoutputPath). Do not guess option names. web/vite.config.ts: replacetanstackRouter(...)by the Start plugin with prerender enabled forObject.keys(sitePages)(import from./src/sitePages.ts; the list is derived, never typed twice) plus{ path: '/404', outputPath: '/404.html' }(useNOT_FOUND_PATHandNOT_FOUND_FILEfrom a temporary local constant now; Step 7 createsconfig/pageFiles.tsand Step 24 switches the import),autoSubfolderIndex: false, no link crawling beyond that list (V5), route code splitting kept (V6). The Start plugin is applied only outside Vitest (defineConfig(({ mode }) => ...)withmode !== 'test'; verify that Vitest passesmode: 'test'). Keepreact()andsitemapPlugin(),resolve.tsconfigPaths, theserver.headersandpreview.headersand the wholetestblock. Adddefine: { 'import.meta.env.VITE_BUILD_YEAR': JSON.stringify(String(new Date().getFullYear())) }(BR-HYD-14) and declare the type iftscneeds it.web/config/sitemapPlugin.ts: emitsitemap.xmlonly in the client environment (this.environment.name === 'client', V7); keep the Dutch comments style, extend the comment with why. Verify thatpublic/has nositemap.xml.web/src/router.tsx(create):routerOptions()returning{ routeTree, scrollRestoration: true, defaultErrorComponent: ErrorPage }andgetRouter()callingcreateRouter(routerOptions()); thedeclare module '@tanstack/react-router' { interface Register { router: ReturnType<typeof getRouter> } }moved frommain.tsx. Keep the two Dutch comments ofmain.tsx(scroll restoration, error component).web/src/routes/__root.tsx:shellComponentrendering<html lang="nl">,<head><HeadContent /></head>,<body>withChakraProvider value={system}(keep the Dutch comment "De site is alleen licht...") around{children}, then<Scripts />; the four@fontsourceCSS imports move here;head()returns charset, viewport,rel="icon" type="image/png" href="/favicon.png"andrel="apple-touch-icon"plus the existingsiteHead(siteContent)content;componentstays a layout renderingAppShelland the devtoolsSuspensebut notHeadContent;notFoundComponentanderrorComponentstay (BR-ENT-02, 04, BR-BLD-05, 07).web/src/client.tsx(create):startSentry()first, then hydrate Start's client insideStrictMode, following Start's documented custom client entry (V1). Deleteweb/src/main.tsxandweb/index.htmlwith plainrm. Check that nothing else importsmain.tsxor relies on thedata-fallbacktags.web/src/routes/$.tsx(create):createFileRoute('/$')({ component: NotFound })(BR-404-01). Nohead(), nonotFound().- Add
.tanstacktoweb/.gitignore(generated Start cache;eslint.config.jsalready ignores it). - Create
code/verification-log.mdwith the 18 rows (Status "open") and fill V1, V3 (first look), V5, V6, V7, V11 (normal pages), V13, V15 (styles present:<style data-emotionin the HTML of/over-mij), V17 (grep the HTML foron[a-z]+=andjavascript:). - Run
pnpm exec tsc --noEmit, thenpnpm build. Inspectweb/dist/client: list all files; the HTML set must be exactly the 11 pages plus404.html(index.html,over-mij.html,soorten-fotoshoots.html,soorten-fotoshoots/<5 shoots>.html,contact.html,privacyverklaring.html,portfolio.html,404.html);sitemap.xmlexists once indist/client; for every HTML file list its inline<script>elements (position, attributes, first 80 characters of the body, body length) and whether any contains<!--, hasasync/defer, or is a module with relative imports (BR-SCR-05); check/over-mij.htmlfor exactly one<title>, onedescription, onecanonical, nodata-fallback; grep the wholedist/clientfor the stringinfo@andreaslop.nl(expected to appear until Step 17; note where) and for the repository path (V13).
- In
- Done when: CP1 part 1:
pnpm buildsucceeds (prerender completed for all 12 files) and the verification log rows above are filled with evidence. A prerender error caused by something other than Step 3's list (for example a component that throws on the server) is fixed only if the fix is inside the rules of business-rules.md BR-HYD; otherwise STOP. - Record:
code/verification-log.mdrows V1, V3, V5, V6, V7, V11, V13, V15, V17; add the resolved package versions under the log's header. - Record (2026-10-31): done, see the log (versions, zod override, router bump,
RoutePathexcludes/$,@tanstack/router-pluginremoved).
Step 5: Test harness for the new router (V2) [x]
- Executor: Sonnet.
- Implements: BR-TST-01, 02; D12; NFR-PR-Q-01; V2.
- Do:
web/src/test/renderApp.tsx: build the router withcreateRouter({ ...routerOptions(), history: createMemoryHistory({ initialEntries: [path] }) }), render insideChakraProvider, no<html>. Keep the exports (renderApp,expectShell) and the test names that use them.- Settle V2: does
RouterProviderin jsdom render the root route'sshellComponent(an<html>inside the RTL container)? Test with one page. If it does, make the tests use a root route variant withoutshellComponent(for example build the tree for tests from the samerouteTreebut with the root options overridden, or a test-only root created insrc/test), without changing production code paths; if neither works within the design (D12), STOP. - Make sure the route tree used by tests includes the new
$route (src/routeTree.gen.tsis regenerated by the Start plugin duringpnpm build; commit-worthy; keep it excluded from coverage and lint). Checkgit diff --stat src/routeTree.gen.tsand read the diff: only the$route and Start's declarations may be new. - Run
pnpm test.
- Done when: CP1:
pnpm buildgreen andpnpm testgreen (all pre-existing tests pass; list tests you had to change, with the reason, in the Record line). - Record: verification log V2 (what happened, which variant); changed tests.
- Record (2026-10-31): CP1 green (
pnpm build12 HTML files;pnpm test113 files, 888 tests). V2: test shell variant inrenderApp. Changed in this step:app.test.tsxregister test ignores/$.routeTree.gen.tsdiff: only the/$route and Start'sRegisterdeclaration.
Step 6: Proof report and decision to continue [x]
- Executor: Sonnet.
- Do: write
aidlc-docs/features/prerendering/construction/start-migration/code/proof-report.md(max one page): per V1, V2, V3, V5, V6, V7 the outcome in one or two sentences with evidence; the list of inline scripts per page as found; the resolved dependency versions; any deviation from the design (none expected). - Done when: the report exists. If every one of V1, V2, V5, V6, V7 is OK, continue with the parallel batches. If any is BLOCKED or DEVIATION, STOP and report to the main session; do not start B2 to B4.
Part C: Script step (batch B2, Sonnet; parallel with B3 and B4)
Files are new config/* files and src/test/htmlArbitraries.ts. Config files are Dutch-commented like their neighbours. They run under Node type stripping: relative imports with .ts, no aliases.
Step 7: config/pageFiles.ts [x]
- Executor: Sonnet.
- Implements: BR-BLD-02, 03; domain-entities
config/pageFiles.ts. - Do: create the pure module with
NOT_FOUND_PATH = '/404',NOT_FOUND_FILE = '404.html',pageFile(path: string): string(/givesindex.html; otherwise the path without its leading slash plus.html) andpagePath(file: string): string | undefined(inverse;undefinedfor404.htmland anything that is not a.htmlpage file). Comment on why one mapping servesvite.config.ts, the runner and the preview server. - Done when:
pnpm exec tsc --noEmitclean. (Switchingvite.config.tsto import it happens in Step 24, to keep B2 off B1's files.)
Step 8: config/inlineScripts.ts [x]
- Executor: Sonnet.
- Implements: BR-SCR-01 to 11, 22 (nothing to build for 22); FR-PR-19, 20; D2, D3.
- Do: create the module with the exports of component-methods.md (
MovedScript,ExternalizeResult,externalizeInlineScripts,findExecutableInlineScripts) and no dependency exceptnode:cryptofor SHA-256. Implement one internal scanner (BR-SCR-02) that yields script elements with their range, verbatim attribute text and body; the classification of flowchart 1.1 (BR-SCR-04:srcattribute in any form, empty body, type list,module); the unsupported-form checks that throw (BR-SCR-05:async/deferon a classic script,<!--in the body, relative specifier in a module body; error type or message with the codesUNSUPPORTED_SCRIPTandUNTERMINATED_SCRIPTso the runner can map them); naming (BR-SCR-07, 08; first 12 hex of SHA-256 of the UTF-8 body); the replacement<script+ attribute text +src="/assets/inline-<hash>.js"+></script>(BR-SCR-06). Parse attributes with quote awareness; compare tag and attribute names case-insensitively. A header comment explains why this step exists (NFR-PR-Q-05, BR-BLD-12): the strictscript-src 'self'blocks Start's inline scripts. - Done when:
pnpm exec tsc --noEmitclean; a quick manual call on the worked-example table of business-logic-model.md § 3.1 gives the listed outputs (the real tests come in Step 9).
Step 9: Tests for inlineScripts (P1 to P9) [x]
- Executor: Sonnet.
- Implements: NFR-PR-Q-02; PBT-02 to 05, 07, 08, 10; P1 to P9.
- Files:
web/src/test/htmlArbitraries.ts(create),web/config/inlineScripts.test.ts(create). - Do:
htmlArbitraries.ts: generators for HTML pieces with a model of what each is: executable inline scripts (classic and module, varied attributes, bodies without</script, no<!--, noasync/defer), external scripts, empty scripts, data blocks (application/ld+json,importmap,speculationrules), comments andstylebodies and attribute values that contain script-like text, plain markup. Export an arbitrary of{ html, model }and one of independent fragment lists (for P9). Also decoys that must be skipped (BR-SCR-02). Reuse nothing from the lib that is not needed; keep generators reusable (PBT-07).inlineScripts.test.ts: example-based tests for every row of business-logic-model.md § 3.1 and for each branch of BR-SCR-04 (type list incl.type="", uppercase,module;srcpresent without value), BR-SCR-05 (a, b, c), BR-SCR-03 (unterminated), attribute retention, trailing/in the tag,>inside a quoted attribute, uppercase tag names, duplicate bodies. Property tests with titles carrying the category: P1 (invariant), P2 (invariant), P3 (round-trip), P4 (idempotent), P5 (invariant), P6 (invariant), P7 (oracle,findExecutableInlineScriptsagainst the model), P8 (invariant), P9 (split and join).
- Done when:
pnpm exec vitest run config/inlineScripts.test.tspasses; the shrunk counterexample and seed would be printed on failure (do not catch or disable).
Step 10: Tests for pageFiles (P10) [x]
- Executor: Sonnet.
- Implements: PBT-02, 10; P10.
- Files:
web/config/pageFiles.test.ts(create). - Do: examples for
/,/over-mij,/soorten-fotoshoots/newborn,404.html, a non-page file; property (round-trip):pagePath(pageFile(p)) === pfor every key ofsitePagesand for generated route-like paths (routePathfromarbitraries.ts); invariant: the file never starts with/and ends with.html. - Done when:
pnpm exec vitest run config/pageFiles.test.tspasses.
Step 11: Runner config/externalizeInlineScripts.ts [x]
- Executor: Sonnet.
- Implements: BR-SCR-12 to 21, BR-MAIL-10, BR-SEC-02, 03, BR-BLD-04, 09 (check part); FR-PR-03, 19, 20, 22; NFR-PR-SEC-03, 04.
- Do: create the module with
planExternalization(files, context)(pure; shapes in domain-entities.md:filesis a map of relative path to content for all text files under the client directory;contexthas the expected pages, the address ornull, the sitemap text, the root paths) returning{ writes, violations }. It appliesexternalizeInlineScriptsto every.html, then all checks: NO_HTML, PAGE_MISSING, NOT_FOUND_PAGE_MISSING, UNEXPECTED_HTML, NO_SCRIPTS_MOVED (final HTML references at least one/assets/inline-<12 hex>.js, so running twice is not an error), EXECUTABLE_REMAINS, COLLISION (an existingassets/inline-<hash>.jswith other content), UNSUPPORTED_SCRIPT, UNTERMINATED_SCRIPT, EMAIL_IN_OUTPUT (all listed encodings, case-insensitive, in every text file including moved bodies; export the pure scan helpercontainsAddress(text, address)for P13), SITEMAP_MISSING, SITEMAP_DIFFERS, SOURCE_MAP_PRESENT, BUILD_PATH_LEAK (both slash styles of the root path). Messages<file>: <CODE>: <detail>; never print script bodies or the address (BR-SCR-21).externalizeOutput(clientDir)that reads the directory (.html,.js,.css,.xml,.txt,.json,.webmanifest, and detects.map), builds the context (pageFileof everysitePageskey,emailAddress(siteContent.email),sitemapXml(pageList(sitePages), siteUrl),path.resolve(clientDir, '../..')), calls the plan, and on violations prints them all, sets exit code 1 and writes nothing; otherwise writes script files first, then the changed HTML, then prints one summary line (pages checked, scripts moved, files written).- A guard so that importing the module for tests does not run it, and the CLI entry runs it for
dist/client(default) with an optional directory argument. ImportsitePages,siteContent,emailAddress,sitemapXml,seoconstants with relative.tspaths. A header comment explains why the step exists (BR-BLD-12).
- Done when:
pnpm exec tsc --noEmitclean; runningnode config/externalizeInlineScripts.tson the Step 4 output prints violations (expected at this point: EMAIL_IN_OUTPUT until Step 17) and writes nothing.
Step 12: Tests for the runner core (P11 to P13) [x]
- Executor: Sonnet.
- Implements: NFR-PR-Q-02; PBT-04, 05, 07, 08, 10; P11 to P13.
- Files:
web/config/externalizeInlineScripts.test.ts(create); generators for file maps may extendsrc/test/htmlArbitraries.ts(owned by B2). - Do: example-based test for each violation code and for the success path (including a second run being a no-op and a
404.htmlpresent); useanySiteContent/validEmailfromarbitraries.tsfor addresses; a temp-directory test forexternalizeOutput(writes script files first, writes nothing on violation, exit code via a returned or thrown result you can assert). Properties: P11 (idempotent: apply the plan's writes to the file map, plan again: no writes, no violations), P12 (oracle: violations equal a simple model), P13 (oracle forcontainsAddresswith all encodings and random insertion; clean text never flagged). - Done when:
pnpm exec vitest run config/externalizeInlineScripts.test.tspasses.
Step 13: Run the script step on the real output (V3, V4, V13, V17) [x]
- Executor: Sonnet.
- Implements: FR-PR-19, 20; BR-SCR-17; V3, V4, V13, V17.
- Preconditions: Steps 8 and 11 done. Because B3 and B4 may still be running, do not run
pnpm buildhere; use thedist/clientfrom Step 4 (or copy it to a scratch folder and run the runner on the copy:node config/externalizeInlineScripts.ts <dir>). - Do: run the runner on the copy. Expected violations: only EMAIL_IN_OUTPUT. Any other violation (for example UNSUPPORTED_SCRIPT because Start emits
asyncor<!--, NO_SCRIPTS_MOVED, UNEXPECTED_HTML): analyse; if the cause is in Start's output format, STOP (design BR-SCR-05 and 17 need a decision), do not relax a check. Then temporarily bypass the email check only in the scratch run (for example by running the plan withaddress: nullfrom a throwaway script in the scratch folder) to confirm that otherwise the run is clean and idempotent (second run prints no writes), that every page has the expected number of moved scripts (list the counts; V4 asks whether the minimum of one in BR-SCR-17 is right or two should be demanded), and V3's final list (bootstrap, boundary, scroll restoration, React completion scripts). Grep the moved files and HTML for a build timestamp and a build path (V13) and foron*=attributes andjavascript:(V17). - Done when: the verification log rows V3, V4, V13, V17 are updated with evidence. Report V4's recommendation in the log (keep one or demand two); the design says one unless the log shows a reason; a change to two is a design change: STOP and report instead of editing.
Part D: Hydration safety (batch B3, Sonnet; parallel with B2 and B4)
Disjoint from B2 and B4. Runs only targeted vitest run commands. The editing order inside the batch is the step order.
Step 14: lib changes for the e-mail address [x]
- Executor: Sonnet.
- Implements: BR-MAIL-07, 08; FR-PR-22.
- Files:
web/src/lib/emailAddress.ts,web/src/lib/contactChannels.ts. - Do: add
isEmailAddressValid(parts: EmailAddress): boolean;emailAddressreuses it (same results as today).contactChannels(email, socials, assemble)with the third parameter:assemblefalse and valid parts give{ kind: 'email-pending' }first (nohref, nolabel);assembletrue gives the existing email channel; invalid parts none. Extend theContactChannelunion (andexternal: falsestays on the email kind only). Existing callers are updated in Step 17. Comments in English like the file. - Done when:
pnpm exec tsc --noEmitreports only the call sites to be fixed in Step 17 (note them), nothing else.
Step 15: Tests for the lib changes (P14, P15) [x]
- Executor: Sonnet.
- Implements: NFR-PR-Q-01, Q-02; PBT-03, 05, 10; P14, P15; 100% coverage of
src/lib. - Files:
web/src/lib/emailAddress.test.ts,web/src/lib/contactChannels.test.ts(extend; keep the existing tests, Dutch titles like the file). - Do: examples for each branch of the new parameter and the new function. P15 (oracle):
isEmailAddressValid(p) === (emailAddress(p) !== null)overanyEmail. P14 (invariant): withassemblefalse,JSON.stringify(contactChannels(...))never contains the assembled address, and the channel count equals the count withassembletrue, overanySiteContent/validEmailandsocialLinklists. - Done when:
pnpm exec vitest run src/lib/emailAddress.test.ts src/lib/contactChannels.test.tspasses.
Step 16: Search gating, navigation, not found [x]
- Executor: Sonnet.
- Implements: BR-HYD-10, 11, 12, 13; BR-404-04, 05; FR-PR-06, 07, 15.
- Files:
web/src/routes/index.tsx,web/src/routes/contact.tsx,web/src/routes/portfolio.tsx,web/src/components/NavigationBar/NavigationBar.tsx,web/src/components/NavigationBar/MobileNav.tsx,web/src/components/StatusPage/NotFound.tsx. - Do:
- Routes:
const hydrated = useHydrated()and passhydrated ? search.pakket : undefined(portfolio:search.shoot) on; leavevalidateSearch,head, the tidy effect and the navigation callback otherwise unchanged. - Navigation: all top-level
NavLinks inNavigationBarand the plainRouterLinks inMobileNavgetactiveOptions={{ exact: true, includeSearch: false }}(a shared constant per file likeNavSubmenuhas). NotFound: usehydrated && isShootSectionPath(pathname). Keep the in-body<title>andnoindexmeta.
- Routes:
- Done when:
pnpm exec tsc --noEmitclean; the old tests of these files pass (pnpm exec vitest run src/app.test.tsx src/navSubmenu.test.tsx src/components/NavigationBar src/components/StatusPage); tests that fail because they assumed the first-render search are adapted per BR-TST-02 and listed in the Record line. - Record (2026-10-31): no old test needed a change; new test cases in
NavigationBar.test.tsx,NotFound.test.tsx,src/routes/hydration.test.tsx.
Step 17: Footer and e-mail components [x]
- Executor: Sonnet.
- Implements: BR-HYD-14; BR-MAIL-01 to 06, 09 (placeholders only); FR-PR-22; V10 (first sizing).
- Files:
web/src/hooks/useEmailAddress.ts(create),web/src/components/Footer/Footer.tsx,web/src/components/ContactDetails/ContactDetails.tsx,web/src/components/ContactForm/ContactFormGate.tsx,web/src/components/ContactForm/ContactForm.tsx. - Do:
useEmailAddress(email)returns{ available, address }(BR-MAIL-01) usinguseHydrated,isEmailAddressValid,emailAddress.Footer:yearishydrated ? new Date().getFullYear() : Number(import.meta.env.VITE_BUILD_YEAR); Contact column rendered whenavailable: before hydration one emptyliwitharia-hidden="true",data-email-pending,data-testid="footer-email-pending", sized likeFooterLink(minH{ base: '44px', lg: 'auto' }plus one text line fromlg); after hydration the existing link (footer-email-link). Update the Dutch comment on the year and the email.ContactDetails:contactChannels(email, socials, hydrated); foremail-pendingrender an emptyliwitharia-hidden,data-email-pending,data-testid="contact-details-email-pending",minH="44px"; keep returningnullonly when there are no channels at all (no social andavailablefalse).iconOf/key handling must cope with the new kind.ContactFormGate: per BR-MAIL-05: sentence "Het contactformulier komt binnenkort." alone before hydration; hidden (visibility: hidden,aria-hidden) inline blockncharacters wide (nfromuser.length + 1 + domain.lengthwithout assembling) where " Mail me voor nu op " will come, and a hidden placeholder of the button using the samelinkButtonrecipe and label,data-testid="contact-gate-mail-pending",data-email-pending;mbdepends onavailable; after hydration the existing link andcontact-gate-mailbutton.ContactForm: useuseEmailAddressinstead ofemailAddress(email); the failed-state link unchanged otherwise.shownAtunchanged (BR-HYD-16).- Update the call sites that Step 14 broke.
- Done when:
pnpm exec tsc --noEmitclean;pnpm lintclean;renderToStringofFooter,ContactDetails,ContactFormGatewith the realsiteContentcontains no@andreaslop.nl/info@(quick manual check; the tests come in Step 21). Placeholder sizes are first estimates; they are measured in Steps 27 and 34 (V10). - Record (2026-10-31): placeholder sizes are estimates, see V10 in the verification log.
src/test/hydrate.tsx(new) is the shared hydration test helper.useInView.tsgot a guard in the effect (see Step 19).
Step 18: Testimonials in the HTML [x]
- Executor: Sonnet.
- Implements: BR-LZY-02; FR-PR-01; NFR-PR-S-02; V9 (code part).
- Files:
web/src/components/home/Testimonials/Testimonials.tsx. - Do:
CarouselPlaceholderrenders every visible testimonial as aTestimonialSlide: the longest in normal flow as today (it sets the height), the others in a wrapper that is visually hidden (use Chakra's visually hidden recipe/srOnly-style props used elsewhere in the repo),aria-hidden="true"andinert. Do not change the carousel itself, the single-review path, orinViewlogic. Update the comment. - Done when:
pnpm exec tsc --noEmitclean;renderToStringofTestimonialswith the real testimonials contains every quote text (manual check; test in Step 21).
Step 19: Tests for hooks (hydration phases) [x]
- Executor: Sonnet.
- Implements: BR-HYD-02 to 05, 09; BR-TST-02; NFR-PR-Q-01; PBT: "No PBT properties identified" for hooks (business-logic-model.md § 9), example-based only.
- Files: new or extended
web/src/hooks/useHydrated.test.tsx,usePageLoaded.test.tsx,useInView.test.tsx(new),useReveal.test.tsx,web/src/components/Hero/useHeroSlider.test.tsx. - Do: for each hook test (a)
renderToString(server snapshot value), (b) hydrating a server-rendered markup withhydrateRootshows the server value in the hydrating render and the real value afterwards, (c) a plainrender(client mount) shows the real value at once. Cases:useHydratedfalse/true;usePageLoadedfalse thenloadevent;useInViewwithoutIntersectionObserver(true after hydration,skiprespected) and with a fake observer (src/test/fakeIntersectionObserver.ts);useRevealfirst-renderreducedMotionfalse;useHeroSliderhiddenfromvisibilitychange. Keep all existing tests of these files. - Done when:
pnpm exec vitest run src/hooks src/components/Heropasses. - Record (2026-10-31): found while testing: the effect of the hydrating render still sees
unsupportedfalse and threwReferenceErrorwithoutIntersectionObserver;useInView.tsnow checkstypeof IntersectionObserverin the effect too. No old test changed.
Step 20: Tests for routes, navigation and not found [x]
- Executor: Sonnet.
- Implements: BR-HYD-10 to 13; BR-404-04, 05; FR-PR-06, 07, 15; NFR-PR-Q-01.
- Files: extend
web/src/app.test.tsxor the route/contact/portfolio tests that exist,web/src/components/NavigationBar/activeOptions.test.tsx, a newweb/src/components/StatusPage/NotFound.test.tsxif none exists. PBT: "No PBT properties identified" (markup with small fixed input). - Do: direct load simulation (
renderApp('/contact?pakket=...')) still preselects the package and tidies the address bar;/?pakket=still scrolls/focuses via theContactSectioneffect;/portfolio?shoot=gezinfilters and filter clicks still navigate withreplace;NotFoundshows one button while hydrating and the two extra buttons under/soorten-fotoshoots/after (usehydrateRoot), and on a plain mount at once; no navigation link is current on an unknown sub-path such as/over-mij/x, current on real pages and with a search. - Done when: the touched test files pass with targeted
vitest run.
Step 21: Tests for Footer, e-mail components and Testimonials [x]
- Executor: Sonnet.
- Implements: BR-HYD-14; BR-MAIL-01 to 07; BR-LZY-02; FR-PR-22; V9 (test part); NFR-PR-Q-01.
- Files:
web/src/components/Footer/Footer.test.tsx,ContactDetailstest,ContactFormGate/ContactFormtests,web/src/hooks/useEmailAddress.test.tsx(new),Testimonialstest. PBT: P14 and P15 live in Step 15; components: "No PBT properties identified". - Do:
renderToStringoutput never contains the assembled address normailto:for each component with the real and withvalidEmailcontent; the three states (absent, pending, ready) per component incl. testidsfooter-email-pending,contact-details-email-pending,contact-gate-mail-pending; afterhydrateRootthe link andcontact-gate-mailbutton appear; year equalsVITE_BUILD_YEARwhile hydrating (stub the env) and the real year afterwards; all testimonial texts are in the server HTML and the hidden copies arearia-hidden; axe still passes (src/test/axe.ts) on the page containing the hidden slides. - Done when: touched test files pass. Hand the batch to the merge point: CP2 is reached when B2, B3 and B4 are all done and the main session (or the next executor) runs
pnpm exec tsc --noEmit,pnpm lint,pnpm test(coverage thresholds) andpnpm build, all green. A failure at CP2 is fixed by the batch that owns the file; if unclear, STOP.
Part E: Preview server (batch B4, Sonnet; parallel with B2 and B3)
Step 22: config/previewServer.ts [x]
- Executor: Sonnet.
- Implements: BR-SRV-01 to 08; D10; NFR-PR-SEC-01; FR-PR-14 (preview part).
- Do: create
resolveRequest(path, fileExists)per BR-SRV-01 to 07 (decode once; reject NUL, backslash,..segments;/toindex.html; no-dot last segment throughpageFilewhen the file exists; dot last segment is a file request; else404.htmlwith status 404; trailing slash and/404interim behaviour exactly as BR-SRV-07 says, with a comment "final rule in unit 3 Infrastructure Design"; never returns{ redirect }).startPreviewServer(clientDir, port)with Nodehttp:GET/HEADonly (405 otherwise),securityHeaders('production')on every response,Cache-Control: no-cachefor HTML, content types from the extension, bind127.0.0.1, prints a line containingLocalwith the URL (matchesstartServerReadyPatterninlighthouserc.cjs), CLI entry parses--port(default 4173),--strictPort(fail if taken), and an optional--dir(defaultdist/client). ImportpageFilefrom./pageFiles.ts(Step 7; if B2 has not finished, wait for it) andsecurityHeadersfrom./securityHeaders.ts. Dutch header comment explaining why a own server (D10: real 404 and.htmlmapping, no Node server in production). - Done when:
pnpm exec tsc --noEmitclean; starting it manually on the Step 4 output answerscurl -I http://127.0.0.1:4173/over-mijwith 200 and the CSP header, and/nopewith 404 (stop the server afterwards; skip this check while Lighthouse is running anywhere).
Step 23: Tests for the preview server (P16, P17) [x]
- Executor: Sonnet.
- Implements: PBT-03, 05, 07, 08, 10; P16, P17; SECURITY-11 misuse case.
- Files:
web/src/test/requestArbitraries.ts(create),web/config/previewServer.test.ts(create). - Do: generators for request paths including
..,%2e%2e,%00, backslashes, unicode, double slashes, and for sets of existing files; examples per BR-SRV-02 to 06 and the interim cases of 07; P16 (invariant) and P17 (oracle) as in business-logic-model.md § 9; an HTTP-level test on an ephemeral port with a temp directory (headers on 200 and 404, 405 forPOST,HEADhas no body, content type). - Done when:
pnpm exec vitest run config/previewServer.test.tspasses.
Part F: Integration (batch B5; after CP2)
Step 24: Wire the build, preview and configuration [x]
- Executor: Haiku.
- Implements: BR-BLD-01, 03, 04, 09, 10 (client path); BR-SRV-08; BR-SEC-01; CP3.
- Files:
web/package.json,web/vite.config.ts,web/tsconfig.json,web/eslint.config.js,web/.gitignore. - Do:
package.json:"build": "tsc && vite build && node config/externalizeInlineScripts.ts";"preview": "node config/previewServer.ts";"e2e": "vitest run --config vitest.e2e.config.ts"(config created in Step 26);"check": insertpnpm e2eafterpnpm build.vite.config.ts: importNOT_FOUND_PATH/NOT_FOUND_FILEfrom./config/pageFiles.tsinstead of the temporary constants of Step 4; add'e2e/**'totest.exclude(keep Vitest's default excludes: spreadconfigDefaults.exclude).tsconfig.json: adde2eandvitest.e2e.config.tstoinclude.eslint.config.js: add Node globals forconfig/**/*.ts,e2e/**/*.ts,vitest.e2e.config.ts(the file currently has browser globals only; useglobals.nodefor those paths).- Run
pnpm build. - Check that
pnpm lighthousestill works against the new preview server on a freshdist/clientfor one URL (pnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=1 --url=http://localhost:4173/over-mij). Lighthouse audits for/bestaat-nietmay fail, because the new preview server answers 404 and Lighthouse rejects non-2xx documents; verify with--url=http://localhost:4173/bestaat-niet. If it fails, setnotFoundPathinlighthouserc.cjsto/404.htmland adapt the test that guards that file. Under BR-SRV-04 that URL is a file request with status 200, so Lighthouse audits the same page and its assertions stay in force, while the real 404 status is covered by the e2e tests. This is the onlylighthouserc.cjsedit in unit 1; targets stay as they are. Record the Lighthouse error as evidence in the log.
- Done when: CP3:
pnpm buildsucceeds, the runner prints its success line (this requires Steps 17 and 21 done, otherwise EMAIL_IN_OUTPUT fails the build, which is the check working). Port 4173 and CPU rules of Step 2 apply to item 5. - Record: verification log notes under V5, V7, and the lighthouse finding.
Step 25: Prerender-safety test (BR-TST-07) [x]
- Executor: Sonnet.
- Implements: BR-TST-07; FR-PR-05; NFR-PR-Q-03 (fast feedback).
- Files:
web/src/prerender.test.tsx(create,// @vitest-environment node). - Do: for every key of
sitePagesplus an unknown path, create a router with memory history fromrouterOptions(), awaitrouter.load(), render withreact-dom/serverinsideChakraProvider, and expect no throw and a non-empty string containing the page's<h1>. This catcheswindow/documentuse in render paths. If it cannot be made to work with the shell, drop the shell from the test as in Step 5. Feasibility is the open point: if the Chakra provider or the router cannot render in a Node environment at all, record "not feasible, the build's own prerender is the guard" in the verification log and replace the test by a documented skip-free alternative (a test that scans nothing is not acceptable): in that case STOP and report instead of deleting the step. Add the assertion that the server HTML of/contacthas no assembled address. - Done when:
pnpm exec vitest run src/prerender.test.tsxpasses.
Step 26: e2e harness and smoke test [x]
- Executor: Sonnet.
- Implements: BR-TST-05 (harness); D11; NFR-PR-Q-03; V1 (browser side), V8 early.
- Files:
web/vitest.e2e.config.ts(create),web/e2e/support/server.ts(create),web/e2e/support/browser.ts(create),web/e2e/smoke.e2e.ts(create). - Do:
vitest.e2e.config.ts:environment: 'node',include: ['e2e/**/*.e2e.ts'], longtestTimeout(60 s; the Pi is slow), aglobalSetupthat builds nothing (requires an existingdist/client; fail with a clear message if missing). No coverage.support/server.ts: startsstartPreviewServerfrom../../config/previewServer.tson an ephemeral port and returns{ origin, close }.support/browser.ts: launches Chromium withplaywright-coreusingexecutablePath: process.env.CHROME_PATHwhen set, otherwisechannel: 'chrome'; extra args fromLIGHTHOUSE_CHROME_FLAGS(CI needs--no-sandbox --disable-dev-shm-usage); helperopenPage(url, { javaScript })that collectsconsolemessages of type error/warning,pageerror, andsecuritypolicyviolationevents (viapage.addInitScript/page.exposeFunctionregistered before navigation); closes everything after each test.smoke.e2e.ts:/and/contactand/onbekend: page loads under the production CSP, the heading is visible, zero console errors/warnings and zero CSP violations. This is the first real-browser proof; if it fails with hydration or CSP errors, analyse; failures that need a design change: STOP.
- Done when:
pnpm build && pnpm e2epasses locally (Chrome must be installed orCHROME_PATHset; if no browser is available on this machine, STOP and ask the main session instead of skipping).
Step 27: Full e2e tests (BR-TST-05, BR-TST-06; V8, V9, V10, V11, V12, V14, V15, V16, V17) [x]
- Executor: Sonnet.
- Implements: BR-TST-05, 06; BR-HYD-17, 20, 21; BR-LZY-01, 05; BR-404-03, 04, 05, 07; BR-ENT-06; BR-MAIL-10; FR-PR-05 to 08, 14, 15, 22; NFR-PR-S-02, SEC-01, Q-03, Q-04; PBT: "No PBT properties identified" (browser flows).
- Files:
web/e2e/hydration.e2e.ts,web/e2e/rawHtml.e2e.ts,web/e2e/interaction.e2e.ts(create). - Do:
hydration.e2e.ts: for the eleven pages,/404,/onbekend,/soorten-fotoshoots/onbekend, and the variants/?pakket=gezin#contact,/contact?pakket=gezin,/portfolio?shoot=gezin: zero console errors and warnings, zerosecuritypolicyviolation; for variants the search value is applied after hydration (package preselected, filter active, address bar tidied for pakket);/and the shoot pages show the same price text (V16);404.htmlserved for/soorten-fotoshoots/onbekendshows the two extra buttons after hydration and one button before (check with JavaScript disabled for the "before" part); V12 and V8 (/contact: form fields in the HTML and no hydration error); record the V7-style check that/Over-Mijand/over-mij/behave as BR-404-07 describes (record the observed result in the log; this is an observation for unit 3, not an assertion that fails the suite).rawHtml.e2e.ts(no JavaScript, plainfetchof the preview server): BR-TST-06 for everysitePagespath and404.html:<title>equal topageHeadtitle, exactly one<h1>, at least 40 visible characters inmainoutside theh1, a link to everymainNavandfooterNavtarget, canonical URL, JSON-LD blocks present and parseable, no assembled address, nodata-fallback, exactly one<title>and onedescription(V11),404.htmlwith onenoindexrobots meta; testimonial quote texts in/(V9).interaction.e2e.ts: mobile menu opens and closes (nav-menu-toggle), one client-side navigation works, the e-mail link (footer-email-link) is absent in raw HTML and present after hydration, focus moves tomainafter a client navigation but not on first load (V14), the contact page's tidy navigation still ends at/contactwithout extra history entries (V14),/?pakket=...#contactscrolls to the contact section, JSON-LD blocks cause no CSP violation (BR-SCR-22), styles present in the raw HTML and a screenshot comparison with JavaScript disabled versus enabled for/over-mijat widths 390 and 1280 saved under the scratch folder and reviewed by you (V15: no visible jump; describe in the log).
- Done when:
pnpm build && pnpm e2epasses; verification log rows V8, V9, V11, V12, V14, V15, V16, V17 filled with evidence. Failures that point to the design (for example V12 hydration error on the 404 page) are STOP cases.
Step 28: CI changes [x]
- Executor: Haiku.
- Implements: BR-BLD-10; BR-TST-05 (CI run); NFR-PR-Q-03; V18. No deployment steps are touched or run.
- Files:
.gitea/workflows/continuous_integration.yaml. - Do:
- Job
check, step "Upload build artifact":path: web/dist/client/(artifact root then holdsindex.html; the deploy jobs keep downloading toweb/dist). - Job
lighthouse, step "Download build artifact":path: web/dist/client(the preview server andpnpm e2ereaddist/client). - Job
lighthouse: add a step "Browsertests" after "Install Chromium" and before "Lighthouse": envLIGHTHOUSE_CHROME_FLAGS: '--no-sandbox --headless=new --disable-dev-shm-usage', runpnpm e2e(theCHROME_PATHenv set by the Chromium step is read by the harness). Comment in Dutch like the file. - Leave
deploy-testanddeploy-productionunchanged (upload order and server rules are unit 3). - Verify the layout locally: after
pnpm build,web/dist/client/index.htmlexists andweb/dist/serveris not insidedist/client; emulate the deploy steps'dist/*copy on a scratch copy ofdist/clientto confirmindex.htmllands at the destination root (V18).
- Job
- Done when: CP4:
pnpm lint,pnpm format:check,pnpm test,pnpm build,pnpm e2e,pnpm audit:depsall succeed inweb/; the workflow file diff shows only the three edits above; V18 filled.
Part G: Finish (batch B6)
Step 29: Comments, documentation in code, naming review [x]
- Executor: Sonnet.
- Implements: BR-BLD-12 (code part); NFR-PR-Q-05.
- Do: review every new or changed file for header comments that say why (the strict CSP and Start's inline scripts for
inlineScripts.ts,externalizeInlineScripts.ts,previewServer.ts; whyuseHydratedand the store pattern exist; whyssrdefaults are used), comment language per neighbour, no leftover temporary constants, noTODOwithout owner,data-testidnaming. Runpnpm exec prettier --writeon touched files, thenpnpm lintandpnpm format:check. - Done when: lint and format checks are clean and a
git diff --statshows only files named in this plan (pluspnpm-lock.yaml,src/routeTree.gen.ts).
Step 30: Dependency hygiene (BR-BLD-11, V6) [x]
- Executor: Haiku.
- Implements: BR-BLD-11; NFR-PR-SEC-02; V6 (second part).
- Do: find packages that are now unused (
@tanstack/router-pluginif Start replaced it:grep -rn "router-plugin" web --include=*.ts --include=*.json -l; nothing else imports it) and ask the main session before removing anything whose use is not obvious; if it is clearly unused runpnpm remove <name>(this is the only install action allowed here). Checkpnpm-workspace.yamloverrides are intact. Runpnpm audit:depsandpnpm audit:dev. - Done when: audit passes, lockfile consistent (
pnpm install --frozen-lockfilesucceeds), V6 updated.
Step 31: Unit build and test verification (Step 13.5) [x]
- Executor: Haiku.
- Implements: Code Generation Step 13.5; CP5; NFR-PR-Q-01.
- Do, in
web/:pnpm lint,pnpm format:check,pnpm test(coverage thresholds),pnpm build,pnpm e2e,pnpm audit:deps. Note counts of test files and tests (expected: 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). - Done when: everything is green, or the unresolved failure and its open question are written in the code summary (Step 32).
- Record: counts and outcomes go into the code summary.
Step 32: Code summary [ ]
- Executor: Sonnet.
- Do: write
aidlc-docs/features/prerendering/construction/start-migration/code/code-summary.md: list of created/modified/removed files (fromgit status --shortandgit diff --stat), grouped by component group of components.md, with the rule ids each implements; test inventory (files, counts, which properties P1 to P17 where); the verification log (V1 to V18) condensed; the Step 31 outcome; deviations (should be none); what unit 2 and 3 can rely on (business-rules.md § 3); open points for the owner (including the preview and Lighthouse 404 finding of Step 24, and the BR-404-07 observation). Format likeaidlc-docs/features/shoot-type-pages/construction/content-and-seo-foundation/code/code-summary.md(look at it). - Done when: the file exists and every file of the diff is listed.
Step 33: Shared reverse-engineering delta [ ]
- Executor: Sonnet.
- Implements: NFR-PR-Q-05; team agreement (only this feature's lines are updated).
- Files:
aidlc-docs/_shared/reverse-engineering/code-structure.md,technology-stack.md,dependencies.md,architecture.md,component-inventory.md(and others only where they namemain.tsx,index.html,vite previewor the SPA fallback; usegrepto find them). - Do: minimal, line-level edits: entry (
src/client.tsx,src/router.tsx, document shell in__root.tsx), build output (dist/client, prerendered HTML,dist/servernot deployed), newconfig/files, new hooks andsrc/routes/$.tsx,e2e/, new dependencies, test setup (renderApp,vitest.e2e.config.ts), removal ofmain.tsxandindex.html. Mark each edited line with the feature name in the style the files already use for earlier features (look at how the shoot-type-pages feature did it). Do not rewrite sections. - Done when:
git diff -- aidlc-docs/_shared/reverse-engineeringshows only line-level edits for this feature.
Step 34: Gate measurement (BR-MEA-02, 03, 04, 05; V10) [ ]
- Executor: Haiku for the runs, Sonnet for the report. Exclusive: same conditions as Step 2 (port 4173 free, no other CPU work, same machine, power plan and Node version).
- Implements: BR-MEA-02, 03, 04, 05; NFR-PR-P-03, P-04; NFR-PR-Q-04; V10 (final).
- Do:
- Record
git status --shortto a scratch file (status-before.txt) and the SHA-256 ofweb/src/hooks/useReveal.ts(status-beforeanduseReveal.sha256). Make a scratch copy ofuseReveal.ts. - Measurement A (the unit as it is):
pnpm build; remove.lighthouseci; mobilepnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=3and desktop withlighthouserc.desktop.cjs, collected to<scratch>/after/mobileand<scratch>/after/desktop, with the same URL list as Step 2, except for the not-found URL if Step 24 changed it to/404.html(say so in the report). Run the Step 2 script on both folders; compute gzip entry and all-JavaScript sizes ofdist/clientas in Step 2 (the entry JavaScript = scripts and modulepreload links referenced fromdist/client/index.html, including the movedinline-*.jsfiles, reported separately); count and gzip size of the moved script files per page (BR-MEA-03). - BR-MEA-03 timing: for
/and/over-mijread from one mobile LHR thenetwork-requestsstart/end of the movedinline-*.jsfiles relative to FCP and LCP. - BR-MEA-04: CLS for
/and/contact(mobile and desktop) must stay below 0.01. If not, report which placeholder (footer item, contact card item, gate notice) shifts and STOP the step; the fix belongs to Step 17 (resize), then repeat the measurement. - Measurement B (BR-MEA-05, indication only): temporarily change
web/src/hooks/useReveal.tsso thatvisibleis always true (returnvisible: inView || true, keepingtschappy undernoUnusedLocals).pnpm build; collect mobile and desktop to<scratch>/revealvisible/...; run the script. Restore: copy the scratch copy ofuseReveal.tsback, verify the SHA-256 equals the recorded one andgit status --shortequalsstatus-before.txt; runpnpm buildagain sodistmatches the committed state. Never rungit add,git stashorgit commitduring this step; the temporary change must never be committed. - Report (Sonnet):
aidlc-docs/features/prerendering/construction/start-migration/code/measurement-gate.mdwith side-by-side tables (baseline from Step 2, A, B per page, mobile and desktop), the gzip sizes, the moved-scripts table, the CLS result, the method, and a short neutral reading ("better", "worse", "equal" per metric; no recommendation to continue or stop: the owner decides, NFR-PR-P-03). Label B clearly as an indication withRevealforced visible.
- Record
- Done when: the report exists,
git status --shortis identical to the state before item 5,useReveal.tshas the recorded checksum,distwas rebuilt from the real code.
4. Suggested logical commit boundaries (for the main session; commit only when the owner approves)
- Docs: functional design, this plan, verification log and reports (aidlc-docs only).
- Start setup:
package.json,pnpm-lock.yaml,vite.config.ts,config/sitemapPlugin.ts,src/router.tsx,src/client.tsx,src/routes/__root.tsx,src/routes/$.tsx,src/routeTree.gen.ts,.gitignore, removal ofsrc/main.tsxandindex.html,src/test/renderApp.tsx(Steps 4, 5). - Hydration safety: hooks, routes, navigation,
NotFound,Footer, e-mail components,lib,Testimonialswith their tests (Steps 3, 14 to 21). - Script step:
config/pageFiles*,inlineScripts*,externalizeInlineScripts*,src/test/htmlArbitraries.ts(Steps 7 to 13). - Preview server:
config/previewServer*,src/test/requestArbitraries.ts(Steps 22, 23). - Build wiring and browser tests:
package.jsonscripts,tsconfig.json,eslint.config.js,vitest.e2e.config.ts,e2e/,src/prerender.test.tsx, CI workflow (Steps 24 to 28). - Docs: code summary, reverse-engineering delta, measurement reports (Steps 29 to 34).
5. Open points for the main session (not plannable without a decision)
- Lighthouse and the not-found URL (decided by the main session). The unit changes the preview server to a real 404, and Lighthouse may refuse to audit a document with status 404. Step 24 checks it; if so,
notFoundPathbecomes/404.html, which keeps the page audited. - Start option names and the custom client entry are not known without reading the installed package (Step 4 reads them); the plan avoids guessing them.
- Whether
RouterProviderrendersshellComponentin jsdom (V2) and whether the Node render test is feasible (Step 25) decide the exact shape of the test harness. - Placeholder sizes (V10) are measured, not designed; Step 34 can send work back to Step 17.
- BR-SCR-17 minimum (one moved script per page) may need a design decision if Step 13 shows a reason to demand two.