Adds the prerendering requirements, design and baseline
Records the requirements, execution plan, application design, the first unit's functional design and code generation plan, and the baseline on master. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
+514
@@ -0,0 +1,514 @@
|
||||
# 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/`)
|
||||
|
||||
1. `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.
|
||||
2. `construction/start-migration/functional-design/business-logic-model.md` (algorithms, properties P1 to P17).
|
||||
3. `construction/start-migration/functional-design/domain-entities.md` (entities, hydration inventory).
|
||||
4. `construction/start-migration/functional-design/frontend-components.md` (per-component contract, test list).
|
||||
5. `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 under `web/`, CI under `.gitea/workflows/`, documentation under `aidlc-docs/`. Never put application code in `aidlc-docs/`.
|
||||
- Run commands from `web/`. Package manager: pnpm (version from `packageManager`). Scripts: `pnpm lint`, `pnpm format:check` (fix with `pnpm 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`, never `git 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
|
||||
|
||||
1. **No git write commands** (`add`, `commit`, `push`, `stash`, `reset`, `checkout --`, `rm`, `mv`, branch operations). `git status`, `git diff`, `git log`, `git rev-parse` are allowed. The main session commits, only when the owner approved. Never edit `aidlc-docs/features/prerendering/audit.md` or `aidlc-state.md`; the main session does.
|
||||
2. **Do not install anything except in Steps 1 and 4** (`pnpm install`, `pnpm add`). Do not edit `pnpm-lock.yaml` by hand.
|
||||
3. **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 --noEmit` still 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.
|
||||
4. **Match the surrounding code.** Open the neighbouring files first and copy their idiom: 4-space indentation, single quotes, trailing commas (Prettier config in `web/.prettierrc`), `@/` alias in `src/` but relative imports with explicit `.ts` extension in `config/` (config files run under Node type stripping: no path aliases, no enums, no parameter properties, `import type` for types, `erasableSyntaxOnly`). Comments explain why, not what; density like the neighbours. Language of new comments, test titles and messages follows the neighbouring files: `config/*` and `src/lib` tests and the pages' older code are partly Dutch; hooks, `lib` implementations and newer components are English. When a file has Dutch comments, write Dutch; when its neighbours are English, write English.
|
||||
5. **Existing tests stay valid.** Change an existing test only where BR-TST-02 says behaviour changed, and say so in the step's record.
|
||||
6. **Automation-friendly code.** Every new interactive element gets a stable `data-testid` named `{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.
|
||||
7. **Coverage.** Thresholds are 100% for `src/lib/**`, `src/seo.ts`, `src/sitemap.ts`; every new or changed function and branch in `src/lib` needs tests in the same batch.
|
||||
8. **Property-based tests** (fast-check, already a dependency): use the global seed from `config/testSeed.ts` (never set a `seed` yourself, never disable shrinking), put domain generators in shared files under `src/test/` (reuse `src/test/arbitraries.ts`: `validEmail`, `anyEmail`, `routePath`, `pathSegment`, `knownRoutePath` and others; new generators go in the new files named in the steps, not in `arbitraries.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.
|
||||
9. **Concurrent batches** (see § 2): while batches run in parallel, run only targeted `vitest run <file>`, never `pnpm build`, `pnpm test`, `pnpm install` or `pnpm add`, and only touch the files your batch owns.
|
||||
10. 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:
|
||||
1. In `web/`: `pnpm install --frozen-lockfile` (the worktree has no `node_modules`; `postinstall` runs `chakra typegen`).
|
||||
2. 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.
|
||||
3. Run `git rev-parse HEAD` and `git status --short`.
|
||||
- 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.md` with the commit hash, the date, Node and pnpm versions, test counts, seed, and the `git status` output (the main session needs the pre-change status, including the untracked `web/.tanstack/`).
|
||||
|
||||
### Step 2: Baseline measurement (BR-MEA-01) [x]
|
||||
|
||||
- Record (2026-10-31): `code/measurement-baseline.md`; the summary script is in the scratch folder `summarize-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/dist` is the master build from Step 1. **Port 4173 must be free** (`Get-NetTCPConnection -LocalPort 4173` in PowerShell must return nothing) because Lighthouse CI starts `pnpm preview --port 4173 --strictPort` itself. **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):
|
||||
1. Delete `.lighthouseci` and `lighthouse-reports` if present.
|
||||
2. Mobile: `pnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=3`. Move `.lighthouseci` to `<scratch>/baseline/mobile`.
|
||||
3. Desktop: `pnpm exec lhci collect --config=lighthouserc.desktop.cjs --numberOfRuns=3`. Move `.lighthouseci` to `<scratch>/baseline/desktop`. (`collect` does 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.)
|
||||
4. Write a small Node script in the scratch folder that reads every `lhr-*.json` of 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 of `transferSize` of the `network-requests` items with `resourceType` `Script`. It takes the folder as an argument.
|
||||
5. Compute gzip sizes with Node `zlib.gzipSync` of: every file referenced by `<script ... src>` and `<link rel="modulepreload">` in `web/dist/index.html` ("entry JavaScript"), and of all `web/dist/assets/*.js` ("all JavaScript").
|
||||
- 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 [ ]
|
||||
|
||||
- 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.hidden` and `window.location` evaluated 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 internal `useHydrated`).
|
||||
- `web/src/hooks/usePageLoaded.ts`: store-based, `subscribe` adds a `load` listener (`{ once: true }`) and returns its removal, snapshot `document.readyState === 'complete'`, server snapshot `false`.
|
||||
- `web/src/hooks/useInView.ts`: keep options and return shape. `unsupported` from `useSyncExternalStore(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 }` from `useMediaQuery`; update the comments.
|
||||
- `web/src/components/Hero/useHeroSlider.ts`: `hidden` from a store (`subscribe` to `document` `visibilitychange`, snapshot `document.hidden`, server snapshot `false`) instead of `useState(() => document.hidden)` plus effect.
|
||||
- `web/src/components/NavigationBar/NavigationBar.tsx`: remove `{ ssr: false }` from `useBreakpointValue` only (the `activeOptions` change is Step 16).
|
||||
- `web/src/components/Analytics/UmamiAnalytics.tsx`: `hostname` prop optional without a default; the effect uses `hostname ?? window.location.hostname`.
|
||||
- Done when: no `ssr: false` remains in `web/src` (`grep -rn "ssr: false" web/src` empty), `pnpm exec tsc --noEmit` is clean, `pnpm lint` is clean, and **CP0**: `pnpm test` passes without test changes. If an old test fails because it relied on first-render media values, fix the test per BR-TST-02 (wrap in `act`/`waitFor`) and list the changed tests in the Record line.
|
||||
- Record: a line in `code/verification-log.md` is not needed yet; list changed old tests (if any) under the step in this plan.
|
||||
|
||||
### Step 4: Start setup and first prerender of the real app (V1, V3, V5, V6, V7, V11, V13, V15, V17) [ ]
|
||||
|
||||
- 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:
|
||||
1. In `web/`: `pnpm add @tanstack/react-start@1.169.4` and `pnpm add -D playwright-core@1.55.0` (the Playwright version already pinned in CI as `PLAYWRIGHT_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 the `seroval` and `seroval-plugins` overrides in `pnpm-workspace.yaml` still apply (`pnpm why seroval`). Run `pnpm audit:deps`; a failure that is not fixable by a patch bump: STOP.
|
||||
2. Read Start's type definitions and docs in `node_modules/@tanstack/react-start` for the exact plugin and prerender option names (spike facts in application-design.md: output in `dist/client`, `autoSubfolderIndex: false`, pages with `outputPath`). Do not guess option names.
|
||||
3. `web/vite.config.ts`: replace `tanstackRouter(...)` by the Start plugin with prerender enabled for `Object.keys(sitePages)` (import from `./src/sitePages.ts`; the list is derived, never typed twice) plus `{ path: '/404', outputPath: '/404.html' }` (use `NOT_FOUND_PATH` and `NOT_FOUND_FILE` from a temporary local constant now; Step 7 creates `config/pageFiles.ts` and 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 }) => ...)` with `mode !== 'test'`; verify that Vitest passes `mode: 'test'`). Keep `react()` and `sitemapPlugin()`, `resolve.tsconfigPaths`, the `server.headers` and `preview.headers` and the whole `test` block. Add `define: { 'import.meta.env.VITE_BUILD_YEAR': JSON.stringify(String(new Date().getFullYear())) }` (BR-HYD-14) and declare the type if `tsc` needs it.
|
||||
4. `web/config/sitemapPlugin.ts`: emit `sitemap.xml` only in the client environment (`this.environment.name === 'client'`, V7); keep the Dutch comments style, extend the comment with why. Verify that `public/` has no `sitemap.xml`.
|
||||
5. `web/src/router.tsx` (create): `routerOptions()` returning `{ routeTree, scrollRestoration: true, defaultErrorComponent: ErrorPage }` and `getRouter()` calling `createRouter(routerOptions())`; the `declare module '@tanstack/react-router' { interface Register { router: ReturnType<typeof getRouter> } }` moved from `main.tsx`. Keep the two Dutch comments of `main.tsx` (scroll restoration, error component).
|
||||
6. `web/src/routes/__root.tsx`: `shellComponent` rendering `<html lang="nl">`, `<head><HeadContent /></head>`, `<body>` with `ChakraProvider value={system}` (keep the Dutch comment "De site is alleen licht...") around `{children}`, then `<Scripts />`; the four `@fontsource` CSS imports move here; `head()` returns charset, viewport, `rel="icon" type="image/png" href="/favicon.png"` and `rel="apple-touch-icon"` plus the existing `siteHead(siteContent)` content; `component` stays a layout rendering `AppShell` and the devtools `Suspense` but not `HeadContent`; `notFoundComponent` and `errorComponent` stay (BR-ENT-02, 04, BR-BLD-05, 07).
|
||||
7. `web/src/client.tsx` (create): `startSentry()` first, then hydrate Start's client inside `StrictMode`, following Start's documented custom client entry (V1). Delete `web/src/main.tsx` and `web/index.html` with plain `rm`. Check that nothing else imports `main.tsx` or relies on the `data-fallback` tags.
|
||||
8. `web/src/routes/$.tsx` (create): `createFileRoute('/$')({ component: NotFound })` (BR-404-01). No `head()`, no `notFound()`.
|
||||
9. Add `.tanstack` to `web/.gitignore` (generated Start cache; `eslint.config.js` already ignores it).
|
||||
10. Create `code/verification-log.md` with the 18 rows (Status "open") and fill V1, V3 (first look), V5, V6, V7, V11 (normal pages), V13, V15 (styles present: `<style data-emotion` in the HTML of `/over-mij`), V17 (grep the HTML for ` on[a-z]+=` and `javascript:`).
|
||||
11. Run `pnpm exec tsc --noEmit`, then `pnpm build`. Inspect `web/dist/client`: list all files; the HTML set must be exactly the 11 pages plus `404.html` (`index.html`, `over-mij.html`, `soorten-fotoshoots.html`, `soorten-fotoshoots/<5 shoots>.html`, `contact.html`, `privacyverklaring.html`, `portfolio.html`, `404.html`); `sitemap.xml` exists once in `dist/client`; for every HTML file list its inline `<script>` elements (position, attributes, first 80 characters of the body, body length) and whether any contains `<!--`, has `async`/`defer`, or is a module with relative imports (BR-SCR-05); check `/over-mij.html` for exactly one `<title>`, one `description`, one `canonical`, no `data-fallback`; grep the whole `dist/client` for the string `info@andreaslop.nl` (expected to appear until Step 17; note where) and for the repository path (V13).
|
||||
- Done when: **CP1 part 1**: `pnpm build` succeeds (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.md` rows V1, V3, V5, V6, V7, V11, V13, V15, V17; add the resolved package versions under the log's header.
|
||||
|
||||
### Step 5: Test harness for the new router (V2) [ ]
|
||||
|
||||
- Executor: Sonnet.
|
||||
- Implements: BR-TST-01, 02; D12; NFR-PR-Q-01; V2.
|
||||
- Do:
|
||||
1. `web/src/test/renderApp.tsx`: build the router with `createRouter({ ...routerOptions(), history: createMemoryHistory({ initialEntries: [path] }) })`, render inside `ChakraProvider`, no `<html>`. Keep the exports (`renderApp`, `expectShell`) and the test names that use them.
|
||||
2. Settle V2: does `RouterProvider` in jsdom render the root route's `shellComponent` (an `<html>` inside the RTL container)? Test with one page. If it does, make the tests use a root route variant without `shellComponent` (for example build the tree for tests from the same `routeTree` but with the root options overridden, or a test-only root created in `src/test`), without changing production code paths; if neither works within the design (D12), STOP.
|
||||
3. Make sure the route tree used by tests includes the new `$` route (`src/routeTree.gen.ts` is regenerated by the Start plugin during `pnpm build`; commit-worthy; keep it excluded from coverage and lint). Check `git diff --stat src/routeTree.gen.ts` and read the diff: only the `$` route and Start's declarations may be new.
|
||||
4. Run `pnpm test`.
|
||||
- Done when: **CP1**: `pnpm build` green and `pnpm test` green (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.
|
||||
|
||||
### Step 6: Proof report and decision to continue [ ]
|
||||
|
||||
- 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` [ ]
|
||||
|
||||
- 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` (`/` gives `index.html`; otherwise the path without its leading slash plus `.html`) and `pagePath(file: string): string | undefined` (inverse; `undefined` for `404.html` and anything that is not a `.html` page file). Comment on why one mapping serves `vite.config.ts`, the runner and the preview server.
|
||||
- Done when: `pnpm exec tsc --noEmit` clean. (Switching `vite.config.ts` to import it happens in Step 24, to keep B2 off B1's files.)
|
||||
|
||||
### Step 8: `config/inlineScripts.ts` [ ]
|
||||
|
||||
- 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 except `node:crypto` for 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: `src` attribute in any form, empty body, type list, `module`); the unsupported-form checks that throw (BR-SCR-05: `async`/`defer` on a classic script, `<!--` in the body, relative specifier in a module body; error type or message with the codes `UNSUPPORTED_SCRIPT` and `UNTERMINATED_SCRIPT` so 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 strict `script-src 'self'` blocks Start's inline scripts.
|
||||
- Done when: `pnpm exec tsc --noEmit` clean; 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) [ ]
|
||||
|
||||
- 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:
|
||||
1. `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 `<!--`, no `async`/`defer`), external scripts, empty scripts, data blocks (`application/ld+json`, `importmap`, `speculationrules`), comments and `style` bodies 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).
|
||||
2. `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`; `src` present 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, `findExecutableInlineScripts` against the model), P8 (invariant), P9 (split and join).
|
||||
- Done when: `pnpm exec vitest run config/inlineScripts.test.ts` passes; the shrunk counterexample and seed would be printed on failure (do not catch or disable).
|
||||
|
||||
### Step 10: Tests for `pageFiles` (P10) [ ]
|
||||
|
||||
- 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)) === p` for every key of `sitePages` and for generated route-like paths (`routePath` from `arbitraries.ts`); invariant: the file never starts with `/` and ends with `.html`.
|
||||
- Done when: `pnpm exec vitest run config/pageFiles.test.ts` passes.
|
||||
|
||||
### Step 11: Runner `config/externalizeInlineScripts.ts` [ ]
|
||||
|
||||
- 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: `files` is a map of relative path to content for all text files under the client directory; `context` has the expected pages, the address or `null`, the sitemap text, the root paths) returning `{ writes, violations }`. It applies `externalizeInlineScripts` to 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 existing `assets/inline-<hash>.js` with 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 helper `containsAddress(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 (`pageFile` of every `sitePages` key, `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.
|
||||
Import `sitePages`, `siteContent`, `emailAddress`, `sitemapXml`, `seo` constants with relative `.ts` paths. A header comment explains why the step exists (BR-BLD-12).
|
||||
- Done when: `pnpm exec tsc --noEmit` clean; running `node config/externalizeInlineScripts.ts` on 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) [ ]
|
||||
|
||||
- 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 extend `src/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.html` present); use `anySiteContent`/`validEmail` from `arbitraries.ts` for addresses; a temp-directory test for `externalizeOutput` (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 for `containsAddress` with all encodings and random insertion; clean text never flagged).
|
||||
- Done when: `pnpm exec vitest run config/externalizeInlineScripts.test.ts` passes.
|
||||
|
||||
### Step 13: Run the script step on the real output (V3, V4, V13, V17) [ ]
|
||||
|
||||
- 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 build` here; use the `dist/client` from 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 `async` or `<!--`, 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 with `address: null` from 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 for `on*=` attributes and `javascript:` (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 [ ]
|
||||
|
||||
- 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`; `emailAddress` reuses it (same results as today). `contactChannels(email, socials, assemble)` with the third parameter: `assemble` false and valid parts give `{ kind: 'email-pending' }` first (no `href`, no `label`); `assemble` true gives the existing email channel; invalid parts none. Extend the `ContactChannel` union (and `external: false` stays on the email kind only). Existing callers are updated in Step 17. Comments in English like the file.
|
||||
- Done when: `pnpm exec tsc --noEmit` reports only the call sites to be fixed in Step 17 (note them), nothing else.
|
||||
|
||||
### Step 15: Tests for the `lib` changes (P14, P15) [ ]
|
||||
|
||||
- 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)` over `anyEmail`. P14 (invariant): with `assemble` false, `JSON.stringify(contactChannels(...))` never contains the assembled address, and the channel count equals the count with `assemble` true, over `anySiteContent`/`validEmail` and `socialLink` lists.
|
||||
- Done when: `pnpm exec vitest run src/lib/emailAddress.test.ts src/lib/contactChannels.test.ts` passes.
|
||||
|
||||
### Step 16: Search gating, navigation, not found [ ]
|
||||
|
||||
- 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 pass `hydrated ? search.pakket : undefined` (portfolio: `search.shoot`) on; leave `validateSearch`, `head`, the tidy effect and the navigation callback otherwise unchanged.
|
||||
- Navigation: all top-level `NavLink`s in `NavigationBar` and the plain `RouterLink`s in `MobileNav` get `activeOptions={{ exact: true, includeSearch: false }}` (a shared constant per file like `NavSubmenu` has).
|
||||
- `NotFound`: use `hydrated && isShootSectionPath(pathname)`. Keep the in-body `<title>` and `noindex` meta.
|
||||
- Done when: `pnpm exec tsc --noEmit` clean; 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.
|
||||
|
||||
### Step 17: Footer and e-mail components [ ]
|
||||
|
||||
- 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) using `useHydrated`, `isEmailAddressValid`, `emailAddress`.
|
||||
- `Footer`: `year` is `hydrated ? new Date().getFullYear() : Number(import.meta.env.VITE_BUILD_YEAR)`; Contact column rendered when `available`: before hydration one empty `li` with `aria-hidden="true"`, `data-email-pending`, `data-testid="footer-email-pending"`, sized like `FooterLink` (`minH` `{ base: '44px', lg: 'auto' }` plus one text line from `lg`); after hydration the existing link (`footer-email-link`). Update the Dutch comment on the year and the email.
|
||||
- `ContactDetails`: `contactChannels(email, socials, hydrated)`; for `email-pending` render an empty `li` with `aria-hidden`, `data-email-pending`, `data-testid="contact-details-email-pending"`, `minH="44px"`; keep returning `null` only when there are no channels at all (no social and `available` false). `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 block `n` characters wide (`n` from `user.length + 1 + domain.length` without assembling) where " Mail me voor nu op <address>" will come, and a hidden placeholder of the button using the same `linkButton` recipe and label, `data-testid="contact-gate-mail-pending"`, `data-email-pending`; `mb` depends on `available`; after hydration the existing link and `contact-gate-mail` button.
|
||||
- `ContactForm`: use `useEmailAddress` instead of `emailAddress(email)`; the failed-state link unchanged otherwise. `shownAt` unchanged (BR-HYD-16).
|
||||
- Update the call sites that Step 14 broke.
|
||||
- Done when: `pnpm exec tsc --noEmit` clean; `pnpm lint` clean; `renderToString` of `Footer`, `ContactDetails`, `ContactFormGate` with the real `siteContent` contains 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).
|
||||
|
||||
### Step 18: Testimonials in the HTML [ ]
|
||||
|
||||
- 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: `CarouselPlaceholder` renders every visible testimonial as a `TestimonialSlide`: 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"` and `inert`. Do not change the carousel itself, the single-review path, or `inView` logic. Update the comment.
|
||||
- Done when: `pnpm exec tsc --noEmit` clean; `renderToString` of `Testimonials` with the real testimonials contains every quote text (manual check; test in Step 21).
|
||||
|
||||
### Step 19: Tests for hooks (hydration phases) [ ]
|
||||
|
||||
- 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 with `hydrateRoot` shows the server value in the hydrating render and the real value afterwards, (c) a plain `render` (client mount) shows the real value at once. Cases: `useHydrated` false/true; `usePageLoaded` false then `load` event; `useInView` without `IntersectionObserver` (true after hydration, `skip` respected) and with a fake observer (`src/test/fakeIntersectionObserver.ts`); `useReveal` first-render `reducedMotion` false; `useHeroSlider` `hidden` from `visibilitychange`. Keep all existing tests of these files.
|
||||
- Done when: `pnpm exec vitest run src/hooks src/components/Hero` passes.
|
||||
|
||||
### Step 20: Tests for routes, navigation and not found [ ]
|
||||
|
||||
- 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.tsx` or the route/contact/portfolio tests that exist, `web/src/components/NavigationBar/activeOptions.test.tsx`, a new `web/src/components/StatusPage/NotFound.test.tsx` if 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 the `ContactSection` effect; `/portfolio?shoot=gezin` filters and filter clicks still navigate with `replace`; `NotFound` shows one button while hydrating and the two extra buttons under `/soorten-fotoshoots/` after (use `hydrateRoot`), 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 [ ]
|
||||
|
||||
- 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`, `ContactDetails` test, `ContactFormGate`/`ContactForm` tests, `web/src/hooks/useEmailAddress.test.tsx` (new), `Testimonials` test. PBT: P14 and P15 live in Step 15; components: "No PBT properties identified".
|
||||
- Do: `renderToString` output never contains the assembled address nor `mailto:` for each component with the real and with `validEmail` content; the three states (absent, pending, ready) per component incl. testids `footer-email-pending`, `contact-details-email-pending`, `contact-gate-mail-pending`; after `hydrateRoot` the link and `contact-gate-mail` button appear; year equals `VITE_BUILD_YEAR` while hydrating (stub the env) and the real year afterwards; all testimonial texts are in the server HTML and the hidden copies are `aria-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) and `pnpm 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` [ ]
|
||||
|
||||
- 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; `/` to `index.html`; no-dot last segment through `pageFile` when the file exists; dot last segment is a file request; else `404.html` with status 404; trailing slash and `/404` interim behaviour exactly as BR-SRV-07 says, with a comment "final rule in unit 3 Infrastructure Design"; never returns `{ redirect }`). `startPreviewServer(clientDir, port)` with Node `http`: `GET`/`HEAD` only (405 otherwise), `securityHeaders('production')` on every response, `Cache-Control: no-cache` for HTML, content types from the extension, bind `127.0.0.1`, prints a line containing `Local` with the URL (matches `startServerReadyPattern` in `lighthouserc.cjs`), CLI entry parses `--port` (default 4173), `--strictPort` (fail if taken), and an optional `--dir` (default `dist/client`). Import `pageFile` from `./pageFiles.ts` (Step 7; if B2 has not finished, wait for it) and `securityHeaders` from `./securityHeaders.ts`. Dutch header comment explaining why a own server (D10: real 404 and `.html` mapping, no Node server in production).
|
||||
- Done when: `pnpm exec tsc --noEmit` clean; starting it manually on the Step 4 output answers `curl -I http://127.0.0.1:4173/over-mij` with 200 and the CSP header, and `/nope` with 404 (stop the server afterwards; skip this check while Lighthouse is running anywhere).
|
||||
|
||||
### Step 23: Tests for the preview server (P16, P17) [ ]
|
||||
|
||||
- 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 for `POST`, `HEAD` has no body, content type).
|
||||
- Done when: `pnpm exec vitest run config/previewServer.test.ts` passes.
|
||||
|
||||
---
|
||||
|
||||
## Part F: Integration (batch B5; after CP2)
|
||||
|
||||
### Step 24: Wire the build, preview and configuration [ ]
|
||||
|
||||
- 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:
|
||||
1. `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"`: insert `pnpm e2e` after `pnpm build`.
|
||||
2. `vite.config.ts`: import `NOT_FOUND_PATH`/`NOT_FOUND_FILE` from `./config/pageFiles.ts` instead of the temporary constants of Step 4; add `'e2e/**'` to `test.exclude` (keep Vitest's default excludes: spread `configDefaults.exclude`).
|
||||
3. `tsconfig.json`: add `e2e` and `vitest.e2e.config.ts` to `include`. `eslint.config.js`: add Node globals for `config/**/*.ts`, `e2e/**/*.ts`, `vitest.e2e.config.ts` (the file currently has browser globals only; use `globals.node` for those paths).
|
||||
4. Run `pnpm build`.
|
||||
5. Check that `pnpm lighthouse` still works against the new preview server on a fresh `dist/client` for one URL (`pnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=1 --url=http://localhost:4173/over-mij`). Lighthouse audits for `/bestaat-niet` may 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, set `notFoundPath` in `lighthouserc.cjs` to `/404.html` and 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 only `lighthouserc.cjs` edit in unit 1; targets stay as they are. Record the Lighthouse error as evidence in the log.
|
||||
- Done when: **CP3**: `pnpm build` succeeds, 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) [ ]
|
||||
|
||||
- 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 `sitePages` plus an unknown path, create a router with memory history from `routerOptions()`, await `router.load()`, render with `react-dom/server` inside `ChakraProvider`, and expect no throw and a non-empty string containing the page's `<h1>`. This catches `window`/`document` use 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 `/contact` has no assembled address.
|
||||
- Done when: `pnpm exec vitest run src/prerender.test.tsx` passes.
|
||||
|
||||
### Step 26: e2e harness and smoke test [ ]
|
||||
|
||||
- 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']`, long `testTimeout` (60 s; the Pi is slow), a `globalSetup` that builds nothing (requires an existing `dist/client`; fail with a clear message if missing). No coverage.
|
||||
- `support/server.ts`: starts `startPreviewServer` from `../../config/previewServer.ts` on an ephemeral port and returns `{ origin, close }`.
|
||||
- `support/browser.ts`: launches Chromium with `playwright-core` using `executablePath: process.env.CHROME_PATH` when set, otherwise `channel: 'chrome'`; extra args from `LIGHTHOUSE_CHROME_FLAGS` (CI needs `--no-sandbox --disable-dev-shm-usage`); helper `openPage(url, { javaScript })` that collects `console` messages of type error/warning, `pageerror`, and `securitypolicyviolation` events (via `page.addInitScript`/`page.exposeFunction` registered before navigation); closes everything after each test.
|
||||
- `smoke.e2e.ts`: `/` and `/contact` and `/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 e2e` passes locally (Chrome must be installed or `CHROME_PATH` set; 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) [ ]
|
||||
|
||||
- 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, zero `securitypolicyviolation`; 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.html` served for `/soorten-fotoshoots/onbekend` shows 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-Mij` and `/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, plain `fetch` of the preview server): BR-TST-06 for every `sitePages` path and `404.html`: `<title>` equal to `pageHead` title, exactly one `<h1>`, at least 40 visible characters in `main` outside the `h1`, a link to every `mainNav` and `footerNav` target, canonical URL, JSON-LD blocks present and parseable, no assembled address, no `data-fallback`, exactly one `<title>` and one `description` (V11), `404.html` with one `noindex` robots 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 to `main` after a client navigation but not on first load (V14), the contact page's tidy navigation still ends at `/contact` without extra history entries (V14), `/?pakket=...#contact` scrolls 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-mij` at 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 e2e` passes; 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 [ ]
|
||||
|
||||
- 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:
|
||||
1. Job `check`, step "Upload build artifact": `path: web/dist/client/` (artifact root then holds `index.html`; the deploy jobs keep downloading to `web/dist`).
|
||||
2. Job `lighthouse`, step "Download build artifact": `path: web/dist/client` (the preview server and `pnpm e2e` read `dist/client`).
|
||||
3. Job `lighthouse`: add a step "Browsertests" after "Install Chromium" and before "Lighthouse": env `LIGHTHOUSE_CHROME_FLAGS: '--no-sandbox --headless=new --disable-dev-shm-usage'`, run `pnpm e2e` (the `CHROME_PATH` env set by the Chromium step is read by the harness). Comment in Dutch like the file.
|
||||
4. Leave `deploy-test` and `deploy-production` unchanged (upload order and server rules are unit 3).
|
||||
5. Verify the layout locally: after `pnpm build`, `web/dist/client/index.html` exists and `web/dist/server` is not inside `dist/client`; emulate the deploy steps' `dist/*` copy on a scratch copy of `dist/client` to confirm `index.html` lands at the destination root (V18).
|
||||
- Done when: **CP4**: `pnpm lint`, `pnpm format:check`, `pnpm test`, `pnpm build`, `pnpm e2e`, `pnpm audit:deps` all succeed in `web/`; 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 [ ]
|
||||
|
||||
- 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`; why `useHydrated` and the store pattern exist; why `ssr` defaults are used), comment language per neighbour, no leftover temporary constants, no `TODO` without owner, `data-testid` naming. Run `pnpm exec prettier --write` on touched files, then `pnpm lint` and `pnpm format:check`.
|
||||
- Done when: lint and format checks are clean and a `git diff --stat` shows only files named in this plan (plus `pnpm-lock.yaml`, `src/routeTree.gen.ts`).
|
||||
|
||||
### Step 30: Dependency hygiene (BR-BLD-11, V6) [ ]
|
||||
|
||||
- Executor: Haiku.
|
||||
- Implements: BR-BLD-11; NFR-PR-SEC-02; V6 (second part).
|
||||
- Do: find packages that are now unused (`@tanstack/router-plugin` if 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 run `pnpm remove <name>` (this is the only install action allowed here). Check `pnpm-workspace.yaml` overrides are intact. Run `pnpm audit:deps` and `pnpm audit:dev`.
|
||||
- Done when: audit passes, lockfile consistent (`pnpm install --frozen-lockfile` succeeds), V6 updated.
|
||||
|
||||
### Step 31: Unit build and test verification (Step 13.5) [ ]
|
||||
|
||||
- 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 with `FC_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 (from `git status --short` and `git 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 like `aidlc-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 name `main.tsx`, `index.html`, `vite preview` or the SPA fallback; use `grep` to 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/server` not deployed), new `config/` files, new hooks and `src/routes/$.tsx`, `e2e/`, new dependencies, test setup (`renderApp`, `vitest.e2e.config.ts`), removal of `main.tsx` and `index.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-engineering` shows 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:
|
||||
1. Record `git status --short` to a scratch file (`status-before.txt`) and the SHA-256 of `web/src/hooks/useReveal.ts` (`status-before` and `useReveal.sha256`). Make a scratch copy of `useReveal.ts`.
|
||||
2. **Measurement A (the unit as it is):** `pnpm build`; remove `.lighthouseci`; mobile `pnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=3` and desktop with `lighthouserc.desktop.cjs`, collected to `<scratch>/after/mobile` and `<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 of `dist/client` as in Step 2 (the entry JavaScript = scripts and modulepreload links referenced from `dist/client/index.html`, including the moved `inline-*.js` files, reported separately); count and gzip size of the moved script files per page (BR-MEA-03).
|
||||
3. BR-MEA-03 timing: for `/` and `/over-mij` read from one mobile LHR the `network-requests` start/end of the moved `inline-*.js` files relative to FCP and LCP.
|
||||
4. 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.
|
||||
5. **Measurement B (BR-MEA-05, indication only):** temporarily change `web/src/hooks/useReveal.ts` so that `visible` is always true (return `visible: inView || true`, keeping `tsc` happy under `noUnusedLocals`). `pnpm build`; collect mobile and desktop to `<scratch>/revealvisible/...`; run the script. **Restore:** copy the scratch copy of `useReveal.ts` back, verify the SHA-256 equals the recorded one and `git status --short` equals `status-before.txt`; run `pnpm build` again so `dist` matches the committed state. Never run `git add`, `git stash` or `git commit` during this step; the temporary change must never be committed.
|
||||
6. Report (Sonnet): `aidlc-docs/features/prerendering/construction/start-migration/code/measurement-gate.md` with 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 with `Reveal` forced visible.
|
||||
- Done when: the report exists, `git status --short` is identical to the state before item 5, `useReveal.ts` has the recorded checksum, `dist` was rebuilt from the real code.
|
||||
|
||||
---
|
||||
|
||||
## 4. Suggested logical commit boundaries (for the main session; commit only when the owner approves)
|
||||
|
||||
1. Docs: functional design, this plan, verification log and reports (aidlc-docs only).
|
||||
2. 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 of `src/main.tsx` and `index.html`, `src/test/renderApp.tsx` (Steps 4, 5).
|
||||
3. Hydration safety: hooks, routes, navigation, `NotFound`, `Footer`, e-mail components, `lib`, `Testimonials` with their tests (Steps 3, 14 to 21).
|
||||
4. Script step: `config/pageFiles*`, `inlineScripts*`, `externalizeInlineScripts*`, `src/test/htmlArbitraries.ts` (Steps 7 to 13).
|
||||
5. Preview server: `config/previewServer*`, `src/test/requestArbitraries.ts` (Steps 22, 23).
|
||||
6. Build wiring and browser tests: `package.json` scripts, `tsconfig.json`, `eslint.config.js`, `vitest.e2e.config.ts`, `e2e/`, `src/prerender.test.tsx`, CI workflow (Steps 24 to 28).
|
||||
7. 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, `notFoundPath` becomes `/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 `RouterProvider` renders `shellComponent` in 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.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Vraag bij Functional Design: start-migration
|
||||
|
||||
## Vraag 1
|
||||
|
||||
Het e-mailadres staat bewust nergens letterlijk op de site: de browser bouwt het pas op, zodat spam-bots het niet uit de pagina kunnen lezen (ook niet uit de JSON-LD). Met prerendering zou het adres in de HTML belanden als we niets veranderen, want `Footer`, `ContactFormGate` en `contactChannels` zetten het in de eerste render. Tegelijk staat in FR-PR-11 en FR-PR-13 dat zonder JavaScript alle links werken en de mailto-route beschikbaar blijft. Dat kan niet allebei. Wat weegt zwaarder?
|
||||
|
||||
- A) Het adres blijft uit de HTML: het verschijnt pas na hydration. Zonder JavaScript is er dan geen e-maillink; de socials en de overige inhoud werken wel. FR-PR-11 en FR-PR-13 krijgen hiervoor een uitzondering. Aanbevolen: dit behoudt je bestaande bescherming tegen spam, en crawlers en vrijwel alle bezoekers merken er niets van.
|
||||
- B) Het adres komt gewoon in de HTML, als leesbare tekst en mailto-link. Dan werkt alles zonder JavaScript, maar bots kunnen het adres oogsten en de bestaande bescherming vervalt.
|
||||
- C) Het adres komt versluierd in de HTML, bijvoorbeeld met HTML-entities. Dan werkt de link zonder JavaScript, maar de meeste bots ontcijferen dit eenvoudig, dus de bescherming is zwak.
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
# Functional Design Plan - Unit 1: Start migration and script step
|
||||
|
||||
Feature: prerendering. Unit: 1 "Start migration and script step" (see [execution-plan.md](../../inception/plans/execution-plan.md) § Units of Work). Owner decision on the e-mail address: [start-migration-fd-questions.md](start-migration-fd-questions.md) (Q1 = A). Artifacts: [functional-design/](../start-migration/functional-design/).
|
||||
|
||||
## Steps
|
||||
|
||||
- [x] Step 1: Analyse unit context (requirements, execution plan, application design, spike evidence, owner answer on the e-mail address)
|
||||
- [x] Step 2: Verify in `web/src` and `web/config` every component a rule is written for (hooks, routes, Footer, contact components, `lib/`, Sentry and Umami, sitemap plugin, test setup) and in `node_modules` how Chakra's `useMediaQuery` and `useBreakpointValue` behave
|
||||
- [x] Step 3: Search `web/src` for further differences between prerender and first browser render (browser globals in render, time and random values, `useId`, `window` or `document` in initialisers)
|
||||
- [x] Step 4: Create this plan
|
||||
- [x] Step 5: `business-logic-model.md` (build flow, page load phases, script step algorithm, runner, e-mail, search, 404, preview server, measurement, testable properties)
|
||||
- [x] Step 6: `business-rules.md` (numbered rules BR-BLD, BR-ENT, BR-HYD, BR-MAIL, BR-404, BR-LZY, BR-MON, BR-SCR, BR-SEC, BR-SRV, BR-TST, BR-MEA; to verify in code generation)
|
||||
- [x] Step 7: `domain-entities.md` (script step entities, hydration inventory, e-mail slot, request resolution)
|
||||
- [x] Step 8: `frontend-components.md` (component hierarchy, first-render contract per component, new hooks, document shell)
|
||||
- [x] Step 9: Check diagrams against the Mermaid standards and the content validation rules
|
||||
- [x] Step 10: Report to the orchestrator (no questions needed; the open choices are listed in the report)
|
||||
@@ -0,0 +1,29 @@
|
||||
# Baseline checks (Step 1)
|
||||
|
||||
- Commit: `c4c2f83d6ccab433ecef2c5d0e019de286897a27` (master, untouched tree)
|
||||
- Date: 2026-10-31 (install started 17:14, checks finished 17:23 local)
|
||||
- Node: v24.16.0. pnpm: 12.11.2 (from `packageManager`)
|
||||
- Machine: Windows 11 Pro 10.0.26200, Git Bash for commands
|
||||
|
||||
## Commands (in `web/`)
|
||||
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `pnpm install --frozen-lockfile` | exit 0, 6m 19s (postinstall `chakra typegen` ran) |
|
||||
| `pnpm lint` | exit 0 |
|
||||
| `pnpm format:check` | exit 0 ("All matched files use Prettier code style!") |
|
||||
| `pnpm test` | exit 0. Test files 113 passed (113), tests 888 passed (888). Coverage: all files lines 96.81%, statements 96.5%, branches 93.94%, functions 95.61% |
|
||||
| `pnpm build` | exit 0, `built in 3.63s`, output in `web/dist` (flat, master SPA build) |
|
||||
|
||||
fast-check seed line from the test run: `fast-check seed: 110425578 (opnieuw: FC_SEED=110425578 pnpm test)`
|
||||
|
||||
Logs (scratch, not committed): `C:\Users\Bryan\AppData\Local\Temp\claude\k--Development-SlpSoftware-Projects-AndreaSlopFotografie\bb0a550e-5427-462f-b99b-f9db012a172a\scratch\b0-test.log` and `b0-build.log`.
|
||||
|
||||
## git status --short (before any change of this unit, after install and build)
|
||||
|
||||
```
|
||||
M aidlc-docs/active-features.md
|
||||
?? aidlc-docs/features/prerendering/
|
||||
```
|
||||
|
||||
Note: `web/.tanstack/` (listed as untracked in the main checkout) does not exist in this worktree; it is not created by the master build. `git rev-parse HEAD`: `c4c2f83d6ccab433ecef2c5d0e019de286897a27`.
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
# Baseline measurement (Step 2, BR-MEA-01)
|
||||
|
||||
Master build before any change of this unit. Numbers are as measured, medians of three runs, not rounded by hand.
|
||||
|
||||
## Method and environment
|
||||
|
||||
- Commit: `c4c2f83d6ccab433ecef2c5d0e019de286897a27` (master, untouched tree; `web/dist` is the Step 1 build)
|
||||
- Date: 2026-10-31, measurement 17:23 to 17:40 local (mobile and desktop back to back, no other CPU load)
|
||||
- Machine: Windows 11 Pro 10.0.26200, Git Bash. Node v24.16.0, pnpm 12.11.2. Port 4173 checked free before the run.
|
||||
- Commands (in `web/`):
|
||||
- Mobile: `pnpm exec lhci collect --config=lighthouserc.cjs --numberOfRuns=3`
|
||||
- Desktop: `pnpm exec lhci collect --config=lighthouserc.desktop.cjs --numberOfRuns=3`
|
||||
- Lighthouse CI starts `pnpm preview --port 4173 --strictPort` itself. Both runs exited 0, no page errored.
|
||||
- Each URL has 3 runs (36 runs per device). Values are the median over the 3 runs.
|
||||
- Raw results (not committed): `C:\Users\Bryan\AppData\Local\Temp\claude\k--Development-SlpSoftware-Projects-AndreaSlopFotografie\bb0a550e-5427-462f-b99b-f9db012a172a\scratch\baseline\mobile` and `...\baseline\desktop`. Logs: `scratch\b2-mobile.log`, `scratch\b2-desktop.log`.
|
||||
- Summary script (reused unchanged in Step 34): `C:\Users\Bryan\AppData\Local\Temp\claude\k--Development-SlpSoftware-Projects-AndreaSlopFotografie\bb0a550e-5427-462f-b99b-f9db012a172a\scratch\summarize-lhr.mjs`, run as `node summarize-lhr.mjs <lhr folder> [dist folder]`.
|
||||
- Units: FCP, LCP, TBT in ms; CLS unitless; script transfer in bytes (sum of `transferSize` of `Script` requests).
|
||||
|
||||
## Mobile
|
||||
|
||||
| URL | score | FCP ms | LCP ms | TBT ms | CLS | script transfer bytes |
|
||||
|---|---|---|---|---|---|---|
|
||||
| / | 0.75 | 2594.5737999999997 | 4293.0984 | 293 | 0.001108080702545967 | 213978 |
|
||||
| /over-mij | 0.86 | 2597.2801499999996 | 3535.0401999999995 | 132.2600500000001 | 0.0001732130305034394 | 201997 |
|
||||
| /portfolio | 0.9 | 2517.36575 | 2926.0389 | 126 | 0.001150312056335732 | 203625 |
|
||||
| /soorten-fotoshoots | 0.85 | 2592.42555 | 3750.006 | 126.5 | 0.006983738601554676 | 204057 |
|
||||
| /soorten-fotoshoots/newborn | 0.85 | 2590.9919 | 3524.9892 | 151.48644999999988 | 0.0205200074358323 | 213493 |
|
||||
| /soorten-fotoshoots/zwangerschap | 0.84 | 2591.3577 | 3676.1436000000003 | 141.77514999999994 | 0.005577664601176807 | 212974 |
|
||||
| /soorten-fotoshoots/gezin | 0.84 | 2592.4778499999998 | 3678.3037999999997 | 148.16325000000006 | 0.002289700816830679 | 212873 |
|
||||
| /soorten-fotoshoots/loveshoot | 0.82 | 2589.8177499999997 | 3767.5646999999994 | 187.87850000000026 | 0.002134925383380898 | 212895 |
|
||||
| /soorten-fotoshoots/portret | 0.84 | 2589.6709 | 3672.5612 | 139.89030000000002 | 0.002416543144046087 | 212837 |
|
||||
| /contact | 0.87 | 2725.4323499999996 | 3344.9097999999994 | 114.44650000000001 | 0.0008627741882531824 | 215296 |
|
||||
| /privacyverklaring | 0.9 | 2512.8540000000003 | 2844.0248 | 163.5 | 0.001133837301994053 | 194867 |
|
||||
| /bestaat-niet | 0.91 | 2406.4337 | 2602.6549999999997 | 171 | 0.001423652125853798 | 191365 |
|
||||
|
||||
## Desktop
|
||||
|
||||
| URL | score | FCP ms | LCP ms | TBT ms | CLS | script transfer bytes |
|
||||
|---|---|---|---|---|---|---|
|
||||
| / | 0.99 | 579.06635 | 915.0427500000001 | 0 | 0.0009738624031996818 | 213978 |
|
||||
| /over-mij | 0.99 | 578.91705 | 769.8894 | 0 | 0.001533534639717924 | 201997 |
|
||||
| /portfolio | 0.99 | 557.012625 | 868.0176749999999 | 0 | 0.001542572749652821 | 203625 |
|
||||
| /soorten-fotoshoots | 0.99 | 578.4956500000001 | 769.9610000000002 | 0 | 0.01247492033475965 | 204057 |
|
||||
| /soorten-fotoshoots/newborn | 0.99 | 577.4793500000001 | 747.9366 | 0 | 0.002339627163392162 | 213493 |
|
||||
| /soorten-fotoshoots/zwangerschap | 0.99 | 577.4309499999999 | 768.5745999999999 | 0 | 0.002032811463333396 | 212974 |
|
||||
| /soorten-fotoshoots/gezin | 0.99 | 577.3627 | 768.4836 | 0 | 0.002010979460514782 | 212873 |
|
||||
| /soorten-fotoshoots/loveshoot | 0.99 | 576.5336000000001 | 767.0448 | 0 | 0.00202968568268567 | 212895 |
|
||||
| /soorten-fotoshoots/portret | 0.99 | 576.5879 | 767.1171999999999 | 0 | 0.002029152603815515 | 212837 |
|
||||
| /contact | 0.99 | 592.22135 | 782.9032 | 0 | 0.001945459221201206 | 215296 |
|
||||
| /privacyverklaring | 1 | 553.115375 | 641.33845 | 0 | 0.001969938089192423 | 194867 |
|
||||
| /bestaat-niet | 1 | 525.0777 | 576.7572 | 0 | 0.001434198762148674 | 191365 |
|
||||
|
||||
## Gzip sizes (`web/dist`, master build)
|
||||
|
||||
- Entry JavaScript (files referenced by `<script src>` and modulepreload in `dist/index.html`): 11 files, gzip total **181161 bytes**. Largest: `assets/index-C65n6UdK.js` at 151138 bytes gzip.
|
||||
- All JavaScript (`dist/assets/*.js`): 42 files, gzip total **284705 bytes**.
|
||||
|
||||
## Notes
|
||||
|
||||
- Mobile targets in `lighthouserc.cjs` are not changed by this measurement (collect does not assert). Against those targets, these URLs are below: `/` (0.75, target 0.8); `/soorten-fotoshoots/zwangerschap` (0.84), `/gezin` (0.84), `/loveshoot` (0.82), `/portret` (0.84), target 0.85; `/contact` (0.87, target 0.9). This is recorded only; the targets are not judged here.
|
||||
- No page errored in Lighthouse.
|
||||
+285
@@ -0,0 +1,285 @@
|
||||
# Business Logic Model - Unit 1: Start migration and script step
|
||||
|
||||
Inputs: [requirements.md](../../../inception/requirements/requirements.md) (FR-PR-01 to 08, 19, 20, 22; the catch-all part of 14 and 15; NFR-PR-P-03, P-04, S-02, SEC-01 to 04, Q-01 to 05), [application-design.md](../../../inception/application-design/application-design.md) and its component files, the owner answer in [start-migration-fd-questions.md](../../plans/start-migration-fd-questions.md), the spike facts, and the real code in `web/src`, `web/config` and `node_modules` (Chakra `useMediaQuery` and `useBreakpointValue`, TanStack Router `Link` and `useHydrated`). Rules: [business-rules.md](business-rules.md). Data: [domain-entities.md](domain-entities.md). Components: [frontend-components.md](frontend-components.md).
|
||||
|
||||
Scope: unit 1 only. Reveal, DeferredImage's no-JavaScript image, NoScriptNav and photo preload are unit 2; server configuration is unit 3. For those the unit-1 end state is in business-rules.md § 3.
|
||||
|
||||
## 1. Build flow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
tsc["tsc"] --> vb["vite build with Start: client and server bundles"]
|
||||
vb --> pre["Start prerender: one HTML file per page and 404.html"]
|
||||
pre --> plan["Runner reads dist/client and plans in memory"]
|
||||
plan --> chk{"Any violation?"}
|
||||
chk -->|"yes"| stop["Print all violations, exit 1, write nothing"]
|
||||
chk -->|"no"| wr["Write inline-hash.js files, then the changed HTML"]
|
||||
wr --> out["dist/client is the deployable output"]
|
||||
pre -.-> srv["dist/server: build only, never deployed"]
|
||||
classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef check fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef output fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef excluded fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
|
||||
class tsc,vb,pre,plan,wr build;
|
||||
class chk,stop check;
|
||||
class out output;
|
||||
class srv excluded;
|
||||
```
|
||||
|
||||
Text alternative: after type checking and the Start build, the runner plans the rewrite in memory, stops on any violation without writing, and otherwise writes the moved scripts and HTML into dist/client; dist/server is never deployed.
|
||||
|
||||
The pages are `Object.keys(sitePages)` plus `/404` rendered to `404.html`. File names follow `pageFile(path)`: `/` gives `index.html`, `/x` gives `x.html`.
|
||||
|
||||
## 2. Page lifetime: prerender, hydrating render, hydrated
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(99,179,237,0.4) Build machine
|
||||
participant S as Start prerender
|
||||
end
|
||||
box rgba(246,224,94,0.4) Browser
|
||||
participant B as First browser render
|
||||
participant H as After hydration
|
||||
end
|
||||
S->>S: Render with search none, hydrated false, defaults for media and load state
|
||||
S-->>B: HTML with moved scripts
|
||||
B->>B: Hydrate with the same defaults, hydrated false
|
||||
B->>H: useSyncExternalStore and effects run
|
||||
H->>H: Apply search, real media values, year, e-mail address, observers
|
||||
```
|
||||
|
||||
Text alternative: the build and the first browser render use the same defaults, and only after hydration are the real search, media values, year and e-mail address applied.
|
||||
|
||||
Browser-dependent values and their first-render contract are listed in [domain-entities.md § 3](domain-entities.md). The principle is BR-HYD-01: the first browser render equals the HTML.
|
||||
|
||||
Hooks that read the browser use the pattern of BR-HYD-03, `useSyncExternalStore(subscribe, clientSnapshot, serverSnapshot)`, with the server snapshot equal to what the HTML shows. This gives the HTML value while hydrating and the real value at once for components that mount later (client navigation, tests).
|
||||
|
||||
| Hook | Server and hydrating render | After hydration |
|
||||
|---|---|---|
|
||||
| `useHydrated` | `false` | `true` |
|
||||
| `usePageLoaded` | `false` | `document.readyState === 'complete'`, then the `load` event |
|
||||
| `useInView` | `inView = skip` | `skip`, or observed, or `true` without `IntersectionObserver` |
|
||||
| `useHeroSlider.hidden` | `false` | `document.hidden`, `visibilitychange` |
|
||||
| `useMediaQuery` (Chakra, default `ssr`) | `false` per query | real matches, set in Chakra's effect |
|
||||
| `useBreakpointValue` (Chakra, default `ssr`) | value of key `base` | value of the real breakpoint |
|
||||
|
||||
## 3. Script step
|
||||
|
||||
### 3.1 Scanner and classification
|
||||
|
||||
The scanner (BR-SCR-02) walks the HTML once and yields script elements with their start-tag attribute text, body and byte range. Comments, `style`, `textarea`, `title`, `noscript`, `xmp`, `iframe`, `noembed`, `noframes` bodies and attribute values are skipped, so their text never matches. The classification is flowchart 1.1 of the business rules.
|
||||
|
||||
`externalizeInlineScripts(html)`:
|
||||
|
||||
1. Scan. Throw UNTERMINATED_SCRIPT for a script without end tag.
|
||||
2. For each executable script, check the unsupported forms (BR-SCR-05); throw UNSUPPORTED_SCRIPT on a hit.
|
||||
3. Compute `hash` (BR-SCR-07) and the file name `inline-<hash>.js`; add `{ fileName, body }` to `moved` once per file name.
|
||||
4. Build the output by copying every byte outside the replaced ranges and writing `<script` + attribute text + ` src="/assets/inline-<hash>.js"` + `></script>` for each replaced one.
|
||||
|
||||
`findExecutableInlineScripts(html)` runs steps 1 and the classification only and returns the bodies in document order.
|
||||
|
||||
Worked example (shape only; the real bodies are Start's):
|
||||
|
||||
| Input fragment | Output fragment | `moved` |
|
||||
|---|---|---|
|
||||
| `<script data-tsr-stream-part="">A</script>` | `<script data-tsr-stream-part="" src="/assets/inline-<h(A)>.js"></script>` | one entry for A |
|
||||
| `<script type="module" async src="/assets/x.js"></script>` | unchanged (external) | none |
|
||||
| `<script>document.currentScript.remove()</script>` | `<script src="/assets/inline-<h>.js"></script>` | one entry |
|
||||
| `<script type="application/ld+json">{...}</script>` | unchanged (data) | none |
|
||||
| `<style>.a::before{content:"<script>x</script>"}</style>` | unchanged (skipped) | none |
|
||||
| `<!-- <script>x</script> -->` | unchanged (comment) | none |
|
||||
|
||||
### 3.2 Runner
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
r1["Read all .html under clientDir"] --> r2["Compute expected set: pageFile of each sitePages path, plus 404.html"]
|
||||
r2 --> r3["Per file: externalize, then find on the result"]
|
||||
r3 --> r4["Scan text files: e-mail address, source maps, build paths"]
|
||||
r4 --> r5["Check sitemap.xml equals sitemapXml of the register"]
|
||||
r5 --> r6{"Violations?"}
|
||||
r6 -->|"yes"| r7["Print file, code, detail for each; exit 1"]
|
||||
r6 -->|"no"| r8["Write script files, then HTML, print one summary line"]
|
||||
classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef done fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class r1,r2,r3,r4,r5 step;
|
||||
class r6 decision;
|
||||
class r7,r8 done;
|
||||
```
|
||||
|
||||
Text alternative: the runner computes everything in memory, collects every violation, and writes files only when there are none.
|
||||
|
||||
Violation codes (all in business-rules.md, BR-SCR-13 to 21):
|
||||
|
||||
| Code | Raised when |
|
||||
|---|---|
|
||||
| NO_HTML | no `.html` file under `clientDir` |
|
||||
| PAGE_MISSING | a `sitePages` path has no `pageFile(path)` |
|
||||
| NOT_FOUND_PAGE_MISSING | no `404.html` |
|
||||
| UNEXPECTED_HTML | an `.html` file outside the expected set |
|
||||
| NO_SCRIPTS_MOVED | a page or `404.html` references no `/assets/inline-<12 hex>.js` after processing |
|
||||
| EXECUTABLE_REMAINS | an executable inline script survives the rewrite |
|
||||
| UNSUPPORTED_SCRIPT, UNTERMINATED_SCRIPT | forms the rewrite cannot move safely |
|
||||
| COLLISION | `inline-<hash>.js` exists with other content |
|
||||
| EMAIL_IN_OUTPUT | the assembled address occurs in a text file |
|
||||
| SITEMAP_MISSING, SITEMAP_DIFFERS | `sitemap.xml` absent or different from the register |
|
||||
| SOURCE_MAP_PRESENT, BUILD_PATH_LEAK | a `.map` file, or the repository root path in a text file |
|
||||
|
||||
The pure core is `planExternalization(files, context)`, which takes a map of relative path to content plus the expected paths, the address and the sitemap text, and returns `{ writes, violations }`. The runner reads the directory into that map, calls it, and writes the result. This keeps all decisions testable without a file system.
|
||||
|
||||
## 4. The e-mail address
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
p["Parts user and domain in siteContent"] --> a{"isEmailAddressValid?"}
|
||||
a -->|"no"| none["No column, item or link: nothing rendered"]
|
||||
a -->|"yes"| h{"hydrated?"}
|
||||
h -->|"no"| ph["Placeholder: empty, aria-hidden, reserved size"]
|
||||
h -->|"yes"| real["emailAddress assembles it: text and mailto link"]
|
||||
ph -->|"after hydration"| real
|
||||
ph --> guard["Build check: assembled address in any text file fails the build"]
|
||||
real -.-> only["Exists only in the browser"]
|
||||
classDef data fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef ui fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef check fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000;
|
||||
class p data;
|
||||
class a,h decision;
|
||||
class none,ph,real,only ui;
|
||||
class guard check;
|
||||
```
|
||||
|
||||
Text alternative: valid parts give an empty placeholder before hydration and the assembled address after it; invalid parts render nothing; a build check keeps the address out of every output file.
|
||||
|
||||
Four call sites use it (verified in code): `Footer` (Contact column), `ContactDetails` through `contactChannels` (contact page, twice), `ContactFormGate` (sentence, link, button), `ContactForm` (failed state only). The slot per site is in [frontend-components.md](frontend-components.md).
|
||||
|
||||
## 5. Search parameters
|
||||
|
||||
| Page | Search | First render (HTML and browser) | After hydration |
|
||||
|---|---|---|---|
|
||||
| `/` | `pakket` | no package chosen | `ContactPanel` takes the package (`pakket !== seenPakket`), loads the form, `ContactSection` tidies the URL (`navigate` to `/` with hash `contact`, smooth scroll, focus on the heading) |
|
||||
| `/contact` | `pakket` | no package chosen | same panel behaviour; the tidy effect `navigate({ to: '/contact', search: {}, replace: true })` runs when `pakket` becomes defined |
|
||||
| `/portfolio` | `shoot` | filter "Alles", all photos | filter and photo list follow `shoot`; `onShootChange` keeps `replace` and `resetScroll: false` |
|
||||
|
||||
On client navigation to these URLs `hydrated` is already `true`, so the value applies in the first render of the new page, exactly as today.
|
||||
|
||||
## 6. Not found
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
u["Unknown URL"] --> srv["Web server returns 404.html with status 404 (unit 3)"]
|
||||
srv --> html["HTML prerendered from /404: shell, title, noindex, one home button"]
|
||||
html --> hy["Hydration: router pathname is the real URL, NotFound ignores it while hydrated is false"]
|
||||
hy --> sec{"Path under /soorten-fotoshoots/?"}
|
||||
sec -->|"yes"| two["Two extra buttons appear"]
|
||||
sec -->|"no"| one["Stays with the home button"]
|
||||
nav["Client navigation to an unknown path"] --> hy2["Catch-all route renders NotFound with hydrated true"]
|
||||
hy2 --> sec
|
||||
classDef host fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef page fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef ui fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class u,nav page;
|
||||
class srv host;
|
||||
class html,hy,hy2 page;
|
||||
class sec decision;
|
||||
class two,one ui;
|
||||
```
|
||||
|
||||
Text alternative: an unknown URL gets the prerendered 404 page, and after hydration `NotFound` adds the two shoot buttons under `/soorten-fotoshoots/`; client navigation to an unknown path renders the same route.
|
||||
|
||||
## 7. Preview server (unit 1 part)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
q["Request path"] --> dec{"Decodes once, no NUL, no backslash, no dot-dot segment?"}
|
||||
dec -->|"no"| nf["404.html, status 404"]
|
||||
dec -->|"yes"| root{"Path is /?"}
|
||||
root -->|"yes"| idx["index.html, 200"]
|
||||
root -->|"no"| dot{"Last segment has a dot?"}
|
||||
dot -->|"yes"| fe{"File exists?"}
|
||||
fe -->|"yes"| file["That file, 200"]
|
||||
fe -->|"no"| nf
|
||||
dot -->|"no"| pg{"pageFile exists?"}
|
||||
pg -->|"yes"| page["x.html, 200"]
|
||||
pg -->|"no"| nf
|
||||
classDef decision fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef bad fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef in fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
class dec,root,dot,fe,pg decision;
|
||||
class idx,file,page ok;
|
||||
class nf bad;
|
||||
class q in;
|
||||
```
|
||||
|
||||
Text alternative: a safe path maps to index.html, an existing file, or its page file with status 200, and everything else, including unsafe paths, gets 404.html with status 404.
|
||||
|
||||
Trailing slash and `/404` are final in unit 3 Infrastructure Design (BR-SRV-07).
|
||||
|
||||
## 8. Measurement and decision gate
|
||||
|
||||
Before the first code change and after unit 1, on the same machine: entry and total JavaScript (gzip), mobile and desktop Lighthouse for every page, plus the moved scripts' count, size and timing (BR-MEA-01 to 03). The owner sees both sets; if any is worse, the owner decides before units 2 and 3 (NFR-PR-P-03).
|
||||
|
||||
## 9. Testable Properties (PBT-01)
|
||||
|
||||
fast-check properties use the existing seed handling. Generators build HTML from known pieces (executable scripts, external scripts, data blocks, comments and style bodies containing script-like text, plain markup) and keep a model of what each piece is.
|
||||
|
||||
| Id | Function | Category | Property |
|
||||
|---|---|---|---|
|
||||
| P1 | `externalizeInlineScripts` | Invariant | Removing the replaced script elements from the input and the output leaves identical text; everything else is byte-identical (BR-SCR-09) |
|
||||
| P2 | `externalizeInlineScripts` | Invariant | The references in the output appear in the same order as the executable scripts in the input (BR-SCR-06) |
|
||||
| P3 | `externalizeInlineScripts` | Round-trip | Replacing each moved reference by its body (looked up by file name) restores the input exactly, because attribute text is kept verbatim and only ` src="..."` was added |
|
||||
| P4 | `externalizeInlineScripts` | Idempotence | Applying it to its own output returns the same HTML and no moved files (BR-SCR-10) |
|
||||
| P5 | `externalizeInlineScripts` | Invariant | Data blocks, external scripts, empty scripts, comments and style bodies appear unchanged in the output |
|
||||
| P6 | both | Invariant | `findExecutableInlineScripts` of the output is empty (BR-SCR-11) |
|
||||
| P7 | `findExecutableInlineScripts` | Oracle | It returns exactly the bodies of the executable pieces of the generator model, in order, whatever decoys surround them |
|
||||
| P8 | `externalizeInlineScripts` | Invariant | The same body gives the same file name; different bodies give different names; names match `inline-[0-9a-f]{12}.js`; `moved` has no duplicate names |
|
||||
| P9 | `externalizeInlineScripts` | Commutativity (split and join) | For a list of independent fragments (each a complete element, comment or text), externalizing the concatenation equals concatenating the externalized fragments |
|
||||
| P10 | `pageFile` and its inverse | Round-trip | The path recovered from `pageFile(path)` equals `path`, for every `sitePages` path and generated route-like paths; the file never starts with `/` |
|
||||
| P11 | `planExternalization` | Idempotence | Applying a plan's writes to the file map and planning again gives no writes and no violations |
|
||||
| P12 | `planExternalization` | Oracle | Violations equal a simple model: missing pages, unexpected files, pages without references, address occurrences |
|
||||
| P13 | address scan (pure helper) | Oracle | For text built by inserting the address in any listed encoding at random positions, the scan finds it; text without it is never flagged |
|
||||
| P14 | `contactChannels` | Invariant | With `assemble` false the serialized result never contains the assembled address, and has the same number of channels as with `assemble` true |
|
||||
| P15 | `isEmailAddressValid` and `emailAddress` | Oracle | `isEmailAddressValid(p)` equals `emailAddress(p) !== null` for any parts |
|
||||
| P16 | `resolveRequest` | Invariant | For any path (including `..`, `%2e%2e`, `%00`, backslashes, unicode) the returned `file` has no `..` segment, is not absolute and has no backslash; status 404 comes only with `404.html` |
|
||||
| P17 | `resolveRequest` | Oracle | Against a small model over a generated set of existing files, `/`, `/x` and `/file.ext` resolve as BR-SRV-02 to 05 say |
|
||||
|
||||
Components with no properties:
|
||||
|
||||
| Component | Result |
|
||||
|---|---|
|
||||
| `startPreviewServer` | No PBT properties identified: thin HTTP wrapper around `resolveRequest`; example tests for headers and methods |
|
||||
| `externalizeOutput` (file system part) | No PBT properties identified: reading and writing files; its decisions are covered by P11 and P12 |
|
||||
| `useHydrated`, `usePageLoaded`, `useInView`, `useHeroSlider`, `useEmailAddress` | No PBT properties identified: React hooks with small state spaces and no pure transformation; example tests per phase (server snapshot, hydrated) |
|
||||
| `getRouter`, `client.tsx`, `__root.tsx` shell, `$` route | No PBT properties identified: configuration and wiring; covered by build, e2e and example tests |
|
||||
| Display and route components changed for hydration (Section 2 of frontend-components.md) | No PBT properties identified: markup with fixed small inputs; covered by example tests, axe and the e2e hydration checks |
|
||||
|
||||
## 10. Requirement coverage
|
||||
|
||||
| Requirement | Where |
|
||||
|---|---|
|
||||
| FR-PR-01 to 04 | BR-BLD-02 to 06, 09; BR-SCR-14 to 16 |
|
||||
| FR-PR-05 to 07 | BR-HYD-01 to 21, BR-ENT-06 |
|
||||
| FR-PR-08 | BR-MON-01 to 04 |
|
||||
| FR-PR-19, 20 | BR-SCR-01 to 23 |
|
||||
| FR-PR-22 | BR-MAIL-01 to 11 |
|
||||
| FR-PR-14, 15 (route part) | BR-404-01 to 07 |
|
||||
| NFR-PR-P-03, P-04 | BR-MEA-01 to 04 |
|
||||
| NFR-PR-S-02 | BR-TST-06 |
|
||||
| NFR-PR-SEC-01 to 04 | BR-SEC-01 to 06, BR-BLD-11, BR-SRV-06 |
|
||||
| NFR-PR-Q-01 to 05 | BR-TST-01 to 07, BR-BLD-07, 12 |
|
||||
|
||||
## 11. Security Baseline and PBT compliance (unit 1)
|
||||
|
||||
| Rule | Status | Note |
|
||||
|---|---|---|
|
||||
| SECURITY-04 | Compliant | CSP unchanged (BR-SEC-01); JSON-LD escaping kept (BR-SEC-06) |
|
||||
| SECURITY-09 | Compliant | No source maps, build paths or server output in `dist/client` (BR-SEC-02, 03, BLD-01) |
|
||||
| SECURITY-10 | Compliant | Lockfile, audit, overrides kept (BR-BLD-11) |
|
||||
| SECURITY-11 | Compliant | Path traversal is a tested property (P16) |
|
||||
| SECURITY-13 | Compliant | No external scripts added; moved scripts are same-origin files |
|
||||
| SECURITY-15 | Compliant | The runner fails closed and writes nothing on a violation (BR-SCR-12) |
|
||||
| PBT-01 | Compliant | Section 9 |
|
||||
| PBT-09 | Compliant | fast-check already in the project |
|
||||
+272
@@ -0,0 +1,272 @@
|
||||
# Business Rules - Unit 1: Start migration and script step
|
||||
|
||||
Rule ids are scoped to this feature (the code comments of earlier features also use `BR-MAIL-01` for the mail subject; here it is the e-mail address protection). "Source" points at a requirement (FR/NFR) or design decision (D1 to D13 in [application-design.md](../../../inception/application-design/application-design.md)). Flows: [business-logic-model.md](business-logic-model.md). Components: [frontend-components.md](frontend-components.md). Data: [domain-entities.md](domain-entities.md).
|
||||
|
||||
Groups: BR-BLD build, BR-ENT entry and document, BR-HYD hydration, BR-MAIL e-mail address, BR-404 not found, BR-LZY lazy code, BR-MON Sentry and Umami, BR-SCR script step, BR-SEC output hygiene, BR-SRV preview server, BR-TST tests, BR-MEA measurement.
|
||||
|
||||
## 1. Decision flowcharts
|
||||
|
||||
### 1.1 Is an inline script moved
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
s["Script element found by the scanner"] --> src{"Has a src attribute?"}
|
||||
src -->|"yes"| keepExt["Leave as is: external script"]
|
||||
src -->|"no"| body{"Body empty after trim?"}
|
||||
body -->|"yes"| keepEmpty["Leave as is: no effect"]
|
||||
body -->|"no"| typ{"type absent, empty, a JavaScript type or module?"}
|
||||
typ -->|"no"| keepData["Leave as is: data block such as ld+json"]
|
||||
typ -->|"yes"| bad{"async or defer on a classic script, body contains comment opener, or relative import in a module?"}
|
||||
bad -->|"yes"| fail["Error UNSUPPORTED_SCRIPT"]
|
||||
bad -->|"no"| move["Replace by external reference, write file"]
|
||||
classDef decision fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef keep fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef act fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef error fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class src,body,typ,bad decision;
|
||||
class keepExt,keepEmpty,keepData keep;
|
||||
class s,move act;
|
||||
class fail error;
|
||||
```
|
||||
|
||||
Text alternative: only scripts without src, with a non-empty body and a JavaScript or module type are moved; data blocks, external and empty scripts stay, and three unsupported forms fail the build.
|
||||
|
||||
### 1.2 What a component renders before and after hydration
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
v["Browser-dependent value"] --> kind{"Kind of value"}
|
||||
kind -->|"search, pathname, year, media, visibility, load state"| def["First render uses the server-safe default, same on both sides"]
|
||||
kind -->|"e-mail address"| mail["First render uses an empty placeholder with reserved size"]
|
||||
kind -->|"observer or measurement"| eff["Set in an effect or external store after mount"]
|
||||
def --> after["After hydration the real value replaces the default"]
|
||||
mail --> after
|
||||
eff --> after
|
||||
classDef decision fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef act fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class kind decision;
|
||||
class v,def,mail,eff act;
|
||||
class after ok;
|
||||
```
|
||||
|
||||
Text alternative: every browser-dependent value starts from a default that equals the prerendered HTML (an empty placeholder for the e-mail address) and is replaced by the real value after hydration.
|
||||
|
||||
## 2. Rules
|
||||
|
||||
### BR-BLD: Build and output
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-BLD-01 | `pnpm build` runs `tsc`, `vite build`, then `node config/externalizeInlineScripts.ts`, in that order. A failing step fails the build. The deployable output is `dist/client`; `dist/server` exists only during the build. | FR-PR-17, 19, 20; services.md |
|
||||
| BR-BLD-02 | The prerendered pages are every key of `sitePages` plus the catch-all route rendered from path `/404` to file `404.html`. `vite.config.ts` derives the list from `sitePages.ts`; paths are never typed a second time. | FR-PR-01, 03; D1, D5 |
|
||||
| BR-BLD-03 | `autoSubfolderIndex` is `false`. File mapping is `pageFile(path)`: `/` gives `index.html`, any other path gives its path without leading slash plus `.html` (`/over-mij` gives `over-mij.html`, `/soorten-fotoshoots/newborn` gives `soorten-fotoshoots/newborn.html`). `pageFile` lives in `config/pageFiles.ts` (pure) and is used by `vite.config.ts`, the runner and the preview server. | FR-PR-16; D1 |
|
||||
| BR-BLD-04 | Link crawling must not add pages beyond BR-BLD-02. The runner fails on any other `.html` file (UNEXPECTED_HTML). | FR-PR-03 |
|
||||
| BR-BLD-05 | Each page file has exactly one `<title>`, one `description`, one `canonical`, the Open Graph tags and JSON-LD of its route, and no element with `data-fallback`. `<html lang="nl">`, charset, viewport, `favicon.png` icon and `apple-touch-icon` links move from `index.html` to the root route (`head()` or the shell). `index.html` and `src/main.tsx` are removed. | FR-PR-02 |
|
||||
| BR-BLD-06 | `/privacyverklaring` keeps `robots` `noindex` through `pageHead`. `404.html` has `noindex` too. Neither `/404` nor `/privacyverklaring` is in the sitemap. | FR-PR-04, 14 |
|
||||
| BR-BLD-07 | The fonts stay imported (`@fontsource/jost` 300, 400, 500; `@fontsource/marcellus` 400) so that their CSS is a same-origin stylesheet link in the HTML. Chakra and Emotion styles are in the HTML (inline `<style>` is allowed by `style-src 'unsafe-inline'`); the first paint shows no unstyled content. | NFR-PR-Q-04 |
|
||||
| BR-BLD-08 | The Start plugin is not part of the Vitest configuration. `@tanstack/router-plugin` is replaced by Start's own generator; `routeTree.gen.ts` stays generated, committed and excluded from coverage. Route code splitting stays on. | D12; NFR-PR-P-03 |
|
||||
| BR-BLD-09 | `sitemap.xml` is emitted by `sitemapPlugin` in the client build only, so that it ends up in `dist/client` exactly once. The runner checks that the file exists and equals `sitemapXml(pageList(sitePages), siteUrl)` (SITEMAP_MISSING, SITEMAP_DIFFERS). | FR-PR-04 |
|
||||
| BR-BLD-10 | The CI job uploads `web/dist/client/` as the build artifact so that later jobs receive `index.html` at the artifact root as today. Upload order and server rules are unit 3. | FR-PR-17; unit boundaries |
|
||||
| BR-BLD-11 | New packages are in `pnpm-lock.yaml` and pass `pnpm audit:deps`. The `seroval` and `seroval-plugins` overrides in `pnpm-workspace.yaml` stay. Packages no longer used (for instance `@tanstack/router-plugin` if Start replaces it) are removed. | NFR-PR-SEC-02 |
|
||||
| BR-BLD-12 | Header comments in `inlineScripts.ts`, `externalizeInlineScripts.ts` and `previewServer.ts` explain why the step exists (strict `script-src 'self'`, Start emits inline scripts). The lines of this feature in `_shared/reverse-engineering/` are updated (entry, build, output, test setup). | NFR-PR-Q-05 |
|
||||
|
||||
### BR-ENT: Entry, router and document
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-ENT-01 | `getRouter()` in `src/router.tsx` returns a new router per call with the options of `main.tsx` today: `routeTree`, `scrollRestoration: true`, `defaultErrorComponent: ErrorPage`. The options come from one shared function that `renderApp` also uses. | FR-PR-07; D12 |
|
||||
| BR-ENT-02 | The root route renders the document through `shellComponent`: `<html lang="nl">`, `<head>` with `HeadContent`, `<body>` with `ChakraProvider value={system}` around the children and `Scripts` last. The site stays light only. | D6; main.tsx comment |
|
||||
| BR-ENT-03 | `src/client.tsx` calls `startSentry()` first and hydrates second, inside `StrictMode` as `main.tsx` does today. The server never imports it. | FR-PR-08; D13 |
|
||||
| BR-ENT-04 | Root `notFoundComponent` and `errorComponent` stay. `ErrorPage` shows no error text (BR-ERR-02/03 of the shell feature stay). | FR-PR-07; NFR-PR-SEC-03 |
|
||||
| BR-ENT-05 | A prerender error fails the build. No page is ever written from an error render. | SECURITY-15 |
|
||||
| BR-ENT-06 | Client navigation, scroll restoration, focus move on route change (`useRouteFocus`, not on first load and not on query or hash change) and `/?pakket=...#contact` anchors behave as today; the e2e tests cover each. | FR-PR-07 |
|
||||
|
||||
### BR-HYD: Hydration
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-HYD-01 | Principle: the first browser render produces the same markup as the prerendered HTML. Anything that depends on `window`, `document`, the URL search, hash or pathname, media queries, time, storage, observers or random values is applied after hydration. `suppressHydrationWarning` and `typeof window` branches in render are not used. | FR-PR-05; D6 |
|
||||
| BR-HYD-02 | `useHydrated()` is `useSyncExternalStore(subscribeNoop, () => true, () => false)`. It returns `false` during prerender and during the hydrating render, `true` in the next render, and `true` from the first render of any component that mounts later (client navigation, tests with `createRoot`). | D6 |
|
||||
| BR-HYD-03 | Browser capabilities read by our own hooks go through `useSyncExternalStore` with a server snapshot equal to what the HTML shows. This keeps behaviour for components that mount after hydration (no extra render, existing tests unchanged) and needs no `setState` in an effect. | D6 |
|
||||
| BR-HYD-04 | `usePageLoaded`: store snapshot `document.readyState === 'complete'`, subscribed to the window `load` event, server snapshot `false`. | FR-PR-05 |
|
||||
| BR-HYD-05 | `useInView`: the contract "without `IntersectionObserver` the element counts as in view" stays. `unsupported` is a store value (`typeof IntersectionObserver === 'undefined'`, server snapshot `false`). `inView = skip \|\| intersected \|\| unsupported`. First render therefore returns `skip` on both sides; the observer is created in the effect as today. | FR-PR-05 |
|
||||
| BR-HYD-06 | `useScrolledPast` needs no change: it reads `window` only in its effect and starts at `false`. | verified |
|
||||
| BR-HYD-07 | Chakra `useMediaQuery` and `useBreakpointValue` are called with the default `ssr` (true) everywhere. With `ssr: false` Chakra reads `window.matchMedia` in the `useState` initialiser, which throws during prerender and returns the real value in the first browser render. With the default, the first render returns `fallback` (none given, so `false`) for each query on both sides and an effect then sets the real values. Applies to `useReveal`, `useHeroSlider`, `ContactSection`, `TestimonialCarousel` and `NavigationBar`. No `{ ssr: false }` remains in `src`. | FR-PR-05 |
|
||||
| BR-HYD-08 | First-render values: `useMediaQuery(['(prefers-reduced-motion: reduce)'])` gives `false`. `NavigationBar` `useBreakpointValue({ base: false, lg: true })` gives `false` (its existing `viewport` dispatch in an effect applies the real value; the mobile and desktop layouts are CSS only). `IntroGallery` `useBreakpointValue({ base: true, sm: false })` gives `true` (the `base` value), so the list carries `tabIndex={0}` in the HTML and loses it after hydration from `sm` up. | FR-PR-05 |
|
||||
| BR-HYD-09 | `useHeroSlider`: `hidden` is a store value (`document.hidden`, event `visibilitychange`, server snapshot `false`). `document.hidden` is no longer read in a `useState` initialiser. | FR-PR-05 |
|
||||
| BR-HYD-10 | `routes/index.tsx`, `routes/contact.tsx` and `routes/portfolio.tsx`: the search value passed to the page is `hydrated ? search.pakket : undefined` (portfolio: `search.shoot`). `validateSearch` is unchanged. Prerender and first browser render therefore both use "no search". | FR-PR-06; D6 |
|
||||
| BR-HYD-11 | After the search value takes effect the existing behaviour is unchanged. Contact page: the tidy effect (`navigate({ to: '/contact', search: {}, replace: true })`) runs when `pakket` becomes defined, so one render later than today on a direct load and at once on client navigation (`hydrated` is already `true`). Home: the `ContactSection` effect behaves the same, with the smooth scroll to `#contact`. Portfolio: `onShootChange` navigation (`replace`, `resetScroll: false`) is only reachable after hydration. | FR-PR-06, 07 |
|
||||
| BR-HYD-12 | On a direct load of `/portfolio?shoot=gezin` the HTML and first paint show all photos with filter "Alles"; the filter applies right after hydration (accepted consequence in the application design). `PortfolioGallery` closes the lightbox when the list changes (its `listFor` adjustment) and needs no change. | FR-PR-06 |
|
||||
| BR-HYD-13 | `NotFound` shows the two shoot-section buttons only when `hydrated && isShootSectionPath(pathname)`. See BR-404. | FR-PR-15 |
|
||||
| BR-HYD-14 | `Footer` year: the first render uses `BUILD_YEAR`, a constant that `vite.config.ts` defines once per build (`import.meta.env.VITE_BUILD_YEAR`, the year of the build machine at build start) so that server and client bundles agree. After hydration the line uses `new Date().getFullYear()`. A page built in December therefore stays valid after new year without a rebuild. In tests (`createRoot`) the real year shows at once. | FR-PR-05 |
|
||||
| BR-HYD-15 | `UmamiAnalytics` reads its default hostname inside its effect, not in a default parameter evaluated during render. It renders `null`. | FR-PR-08 |
|
||||
| BR-HYD-16 | `ContactForm` `shownAt = useState(() => Date.now())` is not rendered, and React state is not carried from server to client. The timer starts when the component first renders in the browser, which is when the form can first be used. A prerendered time can therefore never shorten the minimum fill time (`MIN_FILL_MS`). No change. | FR-PR-05; BR-SPAM-01 |
|
||||
| BR-HYD-17 | Prices come from `formatPrice` (`Intl.NumberFormat('nl-NL')`, whitespace replaced by a non-breaking space). Node and browser must produce identical text; the e2e hydration test on `/` and the shoot pages fails on a difference. | FR-PR-05 |
|
||||
| BR-HYD-18 | No render path uses `Math.random`, `Date.now`, `new Date`, counters or `crypto` for ids or text (verified: only BR-HYD-14 and BR-HYD-16). `useId` is not called in `src`; Chakra and Ark call it internally and are stable as long as both sides render the same tree, which BR-HYD-01 to 17 guarantee. | FR-PR-05 |
|
||||
| BR-HYD-19 | Effects that touch `window` or `document` (`BackToTop`, `MobileNav`, `NavSubmenu`, `useDismiss`, `useRouteFocus`, `Hero`, `Lightbox`, `ContactForm`) are safe and stay. `Lightbox` mounts only after a request, so its `Portal` is not part of the HTML. | verified |
|
||||
| BR-HYD-20 | A hydration error is a defect. The e2e tests fail on any console error or warning (React error #418, #423, #425 and the like) on every page and variant listed in BR-TST-05. | FR-PR-05; NFR-PR-Q-03 |
|
||||
| BR-HYD-21 | Router `Link` computes its active state from the browser location in its first render. On `/?pakket=gezin` the book link of that package card (`PriceCard`: `to="/" search={{ pakket }}`) is active in the browser but not in the HTML, which differs only in attributes (`aria-current`, `data-status`, class). React's production build does not report attribute differences and the tidy navigation of `ContactSection` removes the search at once, so this is accepted; the link keeps its `href` with the search (it must work without JavaScript). The e2e tests run against the production build. If a React or Router upgrade starts reporting it, the card link must render without depending on the location. | FR-PR-05, 06 |
|
||||
|
||||
### BR-MAIL: The e-mail address
|
||||
|
||||
Owner decision: the address stays out of the HTML and the serialized data and appears after hydration.
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-MAIL-01 | The assembled address (`user@domain`) and any `mailto:` link to it exist only in the browser after hydration. No component outputs it in the first render. Components get it through `useEmailAddress(email)`, which returns `{ available, address }`: `available` is `isEmailAddressValid(email)` (same on both sides, no assembly); `address` is `emailAddress(email)` when `hydrated && available`, else `null`. | FR-PR-22 |
|
||||
| BR-MAIL-02 | Three states per slot. `!available`: nothing is rendered, as today (BR-EMAIL-02). `available && address === null` (before hydration): an empty placeholder that has the size of the real element, is `aria-hidden="true"`, has no text, no `href` and no `mailto`, and carries `data-email-pending`. `address !== null`: the real element. | FR-PR-22; NFR-PR-Q-04 |
|
||||
| BR-MAIL-03 | `Footer`: the Contact column (title and list) is rendered before hydration whenever `available`, with one placeholder list item sized like `FooterLink` (`minH` 44 px below `lg`, one text line from `lg`). After hydration the item holds the link. Without the column the footer would grow at screen widths below `lg`, where the column wraps under the others. | FR-PR-22 |
|
||||
| BR-MAIL-04 | `ContactDetails` (contact page, twice): with `available`, the e-mail item is the first list item before hydration as a placeholder of `minH` 44 px, so the social items below it do not move. The card is only omitted when there is no channel at all (`available` false and no social). | FR-PR-22 |
|
||||
| BR-MAIL-05 | `ContactFormGate`: the notice sentence is "Het contactformulier komt binnenkort." before hydration. The part " Mail me voor nu op" with the address link and the button "Stuur een e-mail" appear after hydration. Before it, the notice reserves their space: the button is an `aria-hidden`, `visibility: hidden` placeholder with the button's own recipe and label, and the inline part is an `aria-hidden`, `visibility: hidden` inline block `n` characters wide (`n` = length of the address, computed from the parts without assembling it). The bottom margin depends on `available`, not on the address. | FR-PR-22 |
|
||||
| BR-MAIL-06 | `ContactForm` shows the address only in the failed state after a user action, so it is never in the first render. It also reads `useEmailAddress` so the address is not assembled during prerender at all. | FR-PR-22 |
|
||||
| BR-MAIL-07 | `contactChannels(email, socials, assemble)` gets a third parameter. With `assemble` false and valid parts the first channel is `{ kind: 'email-pending' }` (no `href`, no `label`); with `assemble` true it is the existing email channel; with invalid parts there is none. `ContactDetails` passes `hydrated`. Social channels do not depend on it. | FR-PR-22 |
|
||||
| BR-MAIL-08 | `lib/emailAddress.ts` gets `isEmailAddressValid(parts)`; `emailAddress` reuses it, so both agree. `lib/` keeps its 100% thresholds: every new or changed function and branch in `lib/` has tests. | NFR-PR-Q-01 |
|
||||
| BR-MAIL-09 | Without JavaScript the address never appears (FR-PR-11 exception). Unit 1 leaves the placeholders in a harmless state: nothing readable, nothing clickable. Unit 2 hides the bare "Contact" footer title without JavaScript (for instance by a `<noscript>` style on `[data-email-pending]` parents). | FR-PR-11, 22 |
|
||||
| BR-MAIL-10 | Build check (runner, code EMAIL_IN_OUTPUT): the assembled address, built from `siteContent.email` by `emailAddress`, must not occur in any text file in `dist/client` (HTML, JavaScript, CSS, XML, TXT, JSON), compared case-insensitively in these forms: plain, `%40`, `@`, `\x40`, `@`, `@`, `@`. This is stricter than FR-PR-22 (HTML only): the moved scripts hold the serialized data, and the bundle must stay free of it as today. If the parts are invalid there is no address and the check passes. | FR-PR-22; NFR-PR-SEC-04 |
|
||||
| BR-MAIL-11 | JSON-LD never contains the address (`seo.ts` comments already say so); the scan of BR-MAIL-10 covers it. | NFR-PR-SEC-04 |
|
||||
|
||||
### BR-404: Not found
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-404-01 | `src/routes/$.tsx` is a catch-all route whose component is `NotFound`. It renders normally; it never throws `notFound()` and never sets a status other than OK, because Start fails the build on a non-OK prerender. | FR-PR-14; D5 |
|
||||
| BR-404-02 | Start prerenders it from path `/404` to `404.html`. `/404` is not in `sitePages` and not in the sitemap. | FR-PR-14; BR-BLD-02 |
|
||||
| BR-404-03 | `404.html` contains exactly one `<title>` ("Pagina niet gevonden \| Andrea Slop Fotografie") and one `<meta name="robots" content="noindex">`. `NotFound` keeps rendering them itself (React 19 hoists them into `<head>`); the root `head()` has no title. | FR-PR-14 |
|
||||
| BR-404-04 | The page is rendered in the normal shell (navigation and footer) as today. Before hydration it shows one button, "Terug naar home". The two extra buttons under `/soorten-fotoshoots/` appear after hydration. | FR-PR-15; BR-HYD-13 |
|
||||
| BR-404-05 | The first browser render on an unknown URL has the router pathname of the real URL, while the prerendered HTML was made for `/404`. Only `NotFound` renders from the pathname. The navigation compares exact, normalised strings with registered paths (`isItemCurrent`, `isSectionCurrent`, `pathname === '/'`), which are false for both. The router's `Link` is different: the desktop `NavLink`s and the `MobileNav` links use the default fuzzy matching, so on an unknown URL such as `/over-mij/x` the client would mark "Over mij" as current (`aria-current`, `data-status`, class) while the HTML has none. Therefore every navigation link (`NavigationBar`, `MobileNav`) gets `activeOptions={{ exact: true, includeSearch: false }}`, like `NavSubmenu` and `MobileNavGroup` already have. For real pages nothing changes, as no page has sub-paths except the shoot pages, which the submenu already handles exactly. No other component may render from the pathname on the catch-all page. | FR-PR-15 |
|
||||
| BR-404-06 | Client-side navigation to an unknown path renders the same catch-all route (no server round trip). | FR-PR-07 |
|
||||
| BR-404-07 | Known limit, for unit 3: a URL that the web server does not map but the client router does match (different letter case such as `/Over-Mij`, or a trailing slash) gets `404.html` with a real page rendered in the browser. React recovers by client rendering and reports a hydration error. Unit 3 decides the URL rules (trailing slash, case) so that server and router agree. | FR-PR-14, 16 |
|
||||
|
||||
### BR-LZY: Lazy code and what the HTML contains
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-LZY-01 | `ContactPanel` / `ContactForm` on `/contact` (`load="eager"`): the form is in the first render on both sides, so the HTML contains the form fields inside the gate. On `/` (`load="lazy"`) the first render shows the placeholder box (`inView` is `false`); the form is not in the HTML and loads when near or when `?pakket=` applies. | FR-PR-01, 05 |
|
||||
| BR-LZY-02 | `Testimonials`: all visible testimonial texts and names are in the HTML for SEO. The carousel itself loads only after hydration and when near, as today. `CarouselPlaceholder` therefore renders every visible testimonial as a `TestimonialSlide`: the longest in the normal flow (it sets the height, as today), the others visually hidden with `aria-hidden="true"` and `inert` so assistive technology reads each review once, in the carousel. A single review has no placeholder and is in the HTML already. Alternative if the owner prefers one copy of the text: render the carousel in the first render (costs the lazy chunk, see BR-MEA). | FR-PR-01; NFR-PR-S-02 |
|
||||
| BR-LZY-03 | `PortfolioGallery` / `Lightbox`: `lightboxRequested` starts `false`, so the HTML has no lightbox. No change. | FR-PR-05 |
|
||||
| BR-LZY-04 | `__root.tsx` `RouterDevtools`: `import.meta.env.DEV` is `false` in the build, so it is `() => null` in both bundles and nothing reaches the HTML. In `pnpm dev` the lazy devtools under `Suspense` must not break server rendering. | FR-PR-05 |
|
||||
| BR-LZY-05 | A lazy component whose chunk is missing when React hydrates keeps the server HTML and hydrates later; it must not cause a mismatch. This is checked in the e2e test for `/contact` (BR-TST-05). | FR-PR-05 |
|
||||
|
||||
### BR-MON: Sentry and Umami
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-MON-01 | `startSentry()` runs only in `client.tsx`, before hydration. Shared modules have no import-time side effects (`monitoring/sentry.ts` has none; `reportError` is a no-op in state `off`). | FR-PR-08; D13 |
|
||||
| BR-MON-02 | Sentry starts only on the test and production hostnames (`monitoringFor`, unchanged). The build machine and the preview server on `localhost` start nothing. | FR-PR-08 |
|
||||
| BR-MON-03 | `UmamiAnalytics` adds its script in an effect, only on those hostnames, renders no markup and adds no script to the HTML. See BR-HYD-15. | FR-PR-08 |
|
||||
| BR-MON-04 | `import.meta.env.VITE_RELEASE` is set for the whole `vite build` (client bundle). The server bundle never initialises Sentry. | FR-PR-08 |
|
||||
|
||||
### BR-SCR: Script step
|
||||
|
||||
Pure functions in `config/inlineScripts.ts`, runner in `config/externalizeInlineScripts.ts`.
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-SCR-01 | `externalizeInlineScripts(html)` and `findExecutableInlineScripts(html)` use one scanner and one classification (flowchart 1.1), so the guard cannot disagree with the rewrite. No HTML parser dependency. | FR-PR-19; D2 |
|
||||
| BR-SCR-02 | Scanner. It reads the text left to right and recognises: comments (from `<!--` to the first `-->`, or to the end if unterminated); `<!...>` and `<?...>` up to `>`; end tags up to `>`; start tags (name case-insensitive, attributes read with quotes so a `>` inside a quoted value does not end the tag). After the start tag of `style`, `textarea`, `title`, `noscript`, `xmp`, `iframe`, `noembed` or `noframes` the text up to the matching end tag (name followed by whitespace, `/` or `>`; or the end of the text) is skipped. A `<` not followed by a letter, `/`, `!` or `?` is text. Text in comments, style bodies and attribute values therefore never matches. | FR-PR-19 |
|
||||
| BR-SCR-03 | The body of a script element runs from the `>` of the start tag to the first `</script` followed by whitespace, `/` or `>` (case-insensitive); the end tag runs to its `>`. A script start tag without such an end tag is an error (UNTERMINATED_SCRIPT) in `externalizeInlineScripts`; `findExecutableInlineScripts` reports the rest of the text as its body. | FR-PR-19; D2 |
|
||||
| BR-SCR-04 | Executable means all of: no `src` attribute (present in any form, also empty or without value); a body that is not empty after trimming whitespace; `type` absent, empty, or after trimming and lower-casing one of `application/javascript`, `application/ecmascript`, `application/x-ecmascript`, `application/x-javascript`, `text/javascript`, `text/javascript1.0` to `text/javascript1.5`, `text/ecmascript`, `text/jscript`, `text/livescript`, `text/x-ecmascript`, `text/x-javascript`, or `module`. Every other type (`application/ld+json`, `application/json`, `importmap`, `speculationrules`, unknown) is a data block and stays. The `language` attribute is ignored. | FR-PR-19 |
|
||||
| BR-SCR-05 | Unsupported executable forms throw (UNSUPPORTED_SCRIPT), so a Start change is noticed rather than silently changing behaviour: (a) a classic script with `async` or `defer` (an external file would run in another order); (b) a body containing `<!--` (the browser's script-data escape states make the end of the script ambiguous); (c) a `module` body with a relative import specifier (`from './...'`, `import('../...')`), which would resolve against `/assets/` instead of the page. | FR-PR-19, 20 |
|
||||
| BR-SCR-06 | An executable script is replaced by `<script` + its original attribute text verbatim + ` src="/assets/inline-<hash>.js"` + `></script>`. All its attributes stay (`type`, `data-*`, `id`, `class`, `nonce`, and so on); only `src` is added. The element keeps its position, so the execution order (also relative to external scripts) is preserved. Scripts stay where Start puts them, at the end of the body. | FR-PR-19; D4 |
|
||||
| BR-SCR-07 | `<hash>` is the first 12 lowercase hex characters of the SHA-256 of the body, as UTF-8 bytes exactly as written in the document (no trimming, no newline or entity changes). The file content is that body in UTF-8, without BOM and without an added newline. | D3 |
|
||||
| BR-SCR-08 | The same body gives the same file name. `moved` lists each file once, in order of first appearance; file names in one result are unique. | D3 |
|
||||
| BR-SCR-09 | Everything outside the replaced script elements stays byte-identical, including comments, style bodies, data blocks, external scripts, whitespace and line endings. | FR-PR-19 |
|
||||
| BR-SCR-10 | Idempotence: `externalizeInlineScripts(result.html).html` equals `result.html`, with an empty `moved`. | NFR-PR-Q-02 |
|
||||
| BR-SCR-11 | `findExecutableInlineScripts(externalizeInlineScripts(html).html)` is empty. | FR-PR-20 |
|
||||
| BR-SCR-12 | Runner order: (1) read every `.html` file under `clientDir` (recursive, sorted); (2) plan in memory with no writes; (3) if the plan has violations, print them all and exit 1 without writing anything; (4) otherwise write the script files first and then the changed HTML files. `planExternalization(files, context)` is pure and exported for tests; the runner only reads and writes. | FR-PR-20; SECURITY-15 |
|
||||
| BR-SCR-13 | Runner violation NO_HTML: no `.html` file under `clientDir`. | FR-PR-20 |
|
||||
| BR-SCR-14 | Runner violation PAGE_MISSING: a path in `sitePages` has no file `pageFile(path)`. All missing pages are listed. | FR-PR-03 |
|
||||
| BR-SCR-15 | Runner violation NOT_FOUND_PAGE_MISSING: `404.html` is absent. | FR-PR-14 |
|
||||
| BR-SCR-16 | Runner violation UNEXPECTED_HTML: an `.html` file that is neither a page of BR-SCR-14 nor `404.html`. | BR-BLD-04 |
|
||||
| BR-SCR-17 | Runner violation NO_SCRIPTS_MOVED: a page or `404.html` whose final HTML references no `/assets/inline-<12 hex>.js` file. A file that was already processed counts, so running the runner twice is not an error. The minimum is one reference per page (the spike saw two: the bootstrap and the boundary script). | FR-PR-20 |
|
||||
| BR-SCR-18 | Runner violation EXECUTABLE_REMAINS: after the rewrite `findExecutableInlineScripts` still returns a body. Defence in depth; BR-SCR-11 says it cannot happen. | FR-PR-20 |
|
||||
| BR-SCR-19 | Runner violation COLLISION: `assets/inline-<hash>.js` exists with other content than the body. | D3 |
|
||||
| BR-SCR-20 | Runner violations from the other rules: UNTERMINATED_SCRIPT and UNSUPPORTED_SCRIPT (BR-SCR-03, 05), EMAIL_IN_OUTPUT (BR-MAIL-10), SITEMAP_MISSING and SITEMAP_DIFFERS (BR-BLD-09), SOURCE_MAP_PRESENT and BUILD_PATH_LEAK (BR-SEC). | see rules |
|
||||
| BR-SCR-21 | Messages have the form `<file>: <CODE>: <detail>`. They name a file and a position, never print script bodies, and never print the assembled address. Success prints one line: pages checked, scripts moved, files written. Exit code 0 on success, 1 on any violation. | NFR-PR-SEC-04 |
|
||||
| BR-SCR-22 | Data blocks (JSON-LD from `StructuredData` and the route `head()` scripts) stay inline. The e2e test under the production CSP must show no violation for them; if one appears, FR-PR-19 is to be revisited, not worked around. | FR-PR-19 |
|
||||
| BR-SCR-23 | No `preload` or other hint is added for the moved scripts in unit 1; where they load is measured first (BR-MEA-03). | NFR-PR-P-04; D4 |
|
||||
|
||||
### BR-SEC: Output hygiene
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-SEC-01 | `config/securityHeaders.ts` is not changed in unit 1; its test keeps passing. The e2e tests and the preview server use `securityHeaders('production')`. | NFR-PR-SEC-01 |
|
||||
| BR-SEC-02 | No `.map` file in `dist/client` (SOURCE_MAP_PRESENT). | NFR-PR-SEC-03 |
|
||||
| BR-SEC-03 | No text file in `dist/client` contains the absolute path of the repository root in either slash style (BUILD_PATH_LEAK). | NFR-PR-SEC-03 |
|
||||
| BR-SEC-04 | Serialized data is public page data only. No loader, route context or server function is added in unit 1; the moved bootstrap scripts are scanned by BR-MAIL-10 and BR-SEC-03. | NFR-PR-SEC-04 |
|
||||
| BR-SEC-05 | Error pages show no internal details (BR-ENT-04). A failing prerender shows Start's message in the CI log only. | NFR-PR-SEC-03 |
|
||||
| BR-SEC-06 | `StructuredData` and `structuredDataScript` keep escaping `<`, `>` and `&` (`jsonLdScript`), so content can never close the script element. | SECURITY-04, 11 |
|
||||
|
||||
### BR-SRV: Preview server (unit 1 part)
|
||||
|
||||
Only what Lighthouse and the browser tests need. Trailing slash and `/404` are final in unit 3 Infrastructure Design.
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-SRV-01 | `resolveRequest(path, fileExists)` takes the URL path without query or hash and returns `{ file, status }` (`file` relative to `clientDir`, forward slashes, no leading slash). `fileExists` takes the same relative form. | D10 |
|
||||
| BR-SRV-02 | `/` gives `index.html`, status 200. | FR-PR-16 |
|
||||
| BR-SRV-03 | `/x` (last segment without a dot) gives `pageFile('/x')` with status 200 when that file exists. | FR-PR-16 |
|
||||
| BR-SRV-04 | A last segment with a dot is a file request: the file itself with 200 when it exists. | D10 |
|
||||
| BR-SRV-05 | Anything else gives `404.html` with status 404. | FR-PR-14 |
|
||||
| BR-SRV-06 | The path is percent-decoded once. A path that fails to decode, contains a NUL or a backslash, or has a `..` segment gives `404.html` with 404. The returned `file` never contains `..` and is never absolute, so it cannot leave `clientDir` (SECURITY-11 misuse case). | NFR-PR-SEC-01 |
|
||||
| BR-SRV-07 | Marked "final rule in unit 3 Infrastructure Design": a path with a trailing slash (interim: `404.html` with 404, no redirect in unit 1, so `{ redirect }` is not produced); the path `/404` (interim: `404.html` with status 404, not 200); `/index` and `/index.html`. | FR-PR-16 |
|
||||
| BR-SRV-08 | `startPreviewServer(clientDir, port)` answers `GET` and `HEAD`; other methods get 405. Every response, also 404, carries `securityHeaders('production')`. HTML responses send `Cache-Control: no-cache`. The content type comes from the file extension (html, js, css, svg, png, jpg, webp, woff2, ico, xml, txt, json). It binds to `127.0.0.1`. `pnpm preview` runs it with default port 4173, accepts the `--port` and `--strictPort` arguments that `lighthouserc.cjs` passes (or that command changes with it), and prints a line matching its `startServerReadyPattern`. | NFR-PR-SEC-01; D10 |
|
||||
|
||||
### BR-TST: Tests
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-TST-01 | `renderApp` builds its router from the shared options of BR-ENT-01, with a memory history, and renders `RouterProvider` inside `ChakraProvider` without `<html>`. The root route renders only its `component` in tests. Whether Router renders `shellComponent` itself is verified in code generation (see section 4). | D12 |
|
||||
| BR-TST-02 | The existing test files keep running. Changes are only where behaviour changed: first-render values after `ssr` removal are `false` until effects have run (wrap in `act` or `waitFor`); the footer year, `usePageLoaded`, `useInView` and `useHeroSlider` tests keep passing because components mounted by `createRoot` see the real value at once (BR-HYD-03). | NFR-PR-Q-01 |
|
||||
| BR-TST-03 | Vitest coverage thresholds stay as they are (100% for `src/lib/**`, `src/seo.ts`, `src/sitemap.ts`). `config/**` is reported, not thresholded, as today. | NFR-PR-Q-01 |
|
||||
| BR-TST-04 | Pure logic gets example-based tests and fast-check properties (section 3 of the business logic model), with the existing seed handling (`testSeed.ts`). | NFR-PR-Q-02 |
|
||||
| BR-TST-05 | `e2e/` runs `playwright-core` with the Chromium of the Lighthouse job against the preview server on the built `dist/client`, in CI. Pages: all eleven, `/404`, `/soorten-fotoshoots/onbekend`, `/onbekend`, and the variants `/?pakket=gezin#contact`, `/contact?pakket=gezin`, `/portfolio?shoot=gezin`. Each must show: no console error or warning, no `securitypolicyviolation`, and for the variants the search value applied after hydration. Interaction checks: the mobile menu opens and closes, one client-side navigation works, the e-mail link appears only after hydration, focus moves to `main` after a client navigation but not on first load. | NFR-PR-Q-03, SEC-01; FR-PR-05 to 08 |
|
||||
| BR-TST-06 | A second set of checks needs no JavaScript: `fetch` of each page of `sitePages` and `404.html` returns, in the raw HTML, the `<title>` of `pageHead`, exactly one `<h1>`, at least 40 visible characters in `main` outside the `h1`, a link to every `mainNav` and `footerNav` target, the canonical URL, the JSON-LD blocks, and no assembled e-mail address. The 40 characters is a floor that code generation may tune. | NFR-PR-S-02; FR-PR-02, 22 |
|
||||
| BR-TST-07 | A fast prerender-safety test with `@vitest-environment node` renders each route with `react-dom/server` and expects no throw, to catch `window` or `document` in a render path before a full build. The build's own prerender stays the authoritative check. Feasibility is verified in code generation. | FR-PR-05 |
|
||||
|
||||
### BR-MEA: Measurement and decision gate
|
||||
|
||||
| Id | Rule | Source |
|
||||
|---|---|---|
|
||||
| BR-MEA-01 | Before the first code change, on master c4c2f83: gzip size of the entry JavaScript and of all JavaScript on `/`, and mobile and desktop Lighthouse (performance, FCP, LCP, TBT, CLS) for every page of `sitePages`, median of three runs, with the same method and machine class as `pnpm lighthouse`. | NFR-PR-P-03 |
|
||||
| BR-MEA-02 | The same after unit 1, on the same machine. Both sets are shown to the owner side by side. If any entry is worse, the owner decides whether to continue before units 2 and 3 start. | NFR-PR-P-03 |
|
||||
| BR-MEA-03 | For NFR-PR-P-04 the report adds, per page, the number and gzip size of the moved script files and, for `/` and `/over-mij`, their request start and end relative to FCP and LCP. FCP or LCP later than the baseline goes to the same owner decision. | NFR-PR-P-04 |
|
||||
| BR-MEA-04 | CLS on `/` and `/contact` must not rise noticeably through the e-mail placeholders of BR-MAIL: it stays below 0.01 on both, mobile and desktop (the baseline on master is 0.0011 and 0.0009 on mobile, not exactly 0). A higher value is fixed with a better reserved size, not accepted. | NFR-PR-Q-04 |
|
||||
| BR-MEA-05 | Unit 1 leaves `Reveal` hidden in the HTML and has no photo preload, so its scores understate what units 2 and 3 can reach on pages whose largest paint sits inside `Reveal`. The report therefore adds a second measurement with `Reveal` temporarily visible by default, in an uncommitted local change, labelled as an indication. The owner decides with both in view. | NFR-PR-P-03 |
|
||||
|
||||
## 3. What unit 1 leaves in a working state
|
||||
|
||||
| Belongs to | What unit 1 must leave |
|
||||
|---|---|
|
||||
| Unit 2 `Reveal` / `useReveal` | Hydrates without mismatch. In the HTML, content is in its hidden state (`data-reveal="hidden"`, as `inView` is `false`) and becomes visible after hydration, as in the SPA today. Text is in the HTML and in the raw-HTML test regardless of opacity. Unit 2 flips the default to visible (FR-PR-09). |
|
||||
| Unit 2 `DeferredImage` | Hydrates without mismatch: first render has no `src` on either side (`pageLoaded` and `inView` start `false`), photos load after hydration as today. The no-JavaScript image is unit 2. |
|
||||
| Unit 2 `NoScriptNav` | Not started. The mobile menu works with JavaScript as today. |
|
||||
| Unit 2 photo preload | Not started. `pageHead` stays as it is. |
|
||||
| Unit 2 hero, carousel, form fallbacks | The HTML contains the first hero slide image (the hero's `loaded` list starts with the active slide, which renders in the first render); testimonials per BR-LZY-02; the form per BR-LZY-01. Autoplay is on in the first render and stops after hydration for visitors with reduced motion. |
|
||||
| Unit 3 servers | `dist/client` is complete and correct for a server that maps `/x` to `x.html` and unknown URLs to `404.html` with 404; the preview server proves it. nginx, IIS, upload order and Lighthouse targets are untouched. |
|
||||
|
||||
## 4. To verify in code generation
|
||||
|
||||
Neither the code nor the spike settles these.
|
||||
|
||||
| # | Point | Where it matters |
|
||||
|---|---|---|
|
||||
| V1 | How the custom `src/client.tsx` hydrates with Start (entry API and file naming), and that `startSentry()` before hydration works. | BR-ENT-03 |
|
||||
| V2 | Whether `RouterProvider` in jsdom renders `shellComponent` (`<html>` cannot sit in the test container). If it does, `renderApp` creates the router from a variant of the root route without the shell. | BR-TST-01 |
|
||||
| V3 | The exact set of inline scripts per real page: Start's bootstrap and boundary, and any from router scroll restoration or from React for lazy boundaries (`$RC`-type completion scripts). They are moved like any other; check there is no `<!--`, no `async`/`defer`, no `module` with relative imports (BR-SCR-05). | BR-SCR |
|
||||
| V4 | Whether the first real page keeps the minimum of one moved script (BR-SCR-17) or the runner should demand the two seen in the spike. | BR-SCR-17 |
|
||||
| V5 | That prerender of `/` really writes `index.html` with `autoSubfolderIndex: false`, and that link crawling is off or limited. | BR-BLD-02, 04 |
|
||||
| V6 | Start's plugin options for route code splitting (`autoCodeSplitting` equivalent) and whether `@tanstack/router-plugin` becomes unused. | BR-BLD-08, 11 |
|
||||
| V7 | Whether Vite's `this.environment.name` identifies the client build in `sitemapPlugin.generateBundle` (Vite 8), and that no `sitemap.xml` is left in `public/`. | BR-BLD-09 |
|
||||
| V8 | Lazy components in the HTML: that prerender waits for `ContactForm` on `/contact` (form fields in the HTML) and that React hydrates the boundary without a mismatch when the chunk arrives later. What the spike did not test. | BR-LZY-01, 05 |
|
||||
| V9 | Testimonials: that all review texts are in the HTML and that the visually hidden slides do not disturb layout, reading order or the axe test. | BR-LZY-02 |
|
||||
| V10 | Placeholder sizes for the footer item, contact card item and the gate notice: measured per breakpoint until CLS stays below 0.01. | BR-MAIL-03 to 05, BR-MEA-04 |
|
||||
| V11 | Exactly one `<title>` and one `noindex` robots meta in `404.html`, and no duplicates on the normal pages, with React 19 hoisting inside Start's `HeadContent`. | BR-404-03, BR-BLD-05 |
|
||||
| V12 | No hydration error from the 404 page when its HTML (made for `/404`) is served for other URLs, with the real shell (navigation, footer) and not only the spike's simple pages. | BR-404-05 |
|
||||
| V13 | Whether Start's dehydrated state or any inline script contains a build timestamp (affects only the hash names, not correctness) or any build path (BR-SEC-03). | BR-SEC |
|
||||
| V14 | `useRouteFocus` does not move focus on the first load with Start's router, and the contact page's tidy navigation keeps its scroll-to-top behaviour now that it runs one render later on a direct load. | BR-ENT-06, BR-HYD-11 |
|
||||
| V15 | Emotion/Chakra: no style flicker on real pages and no duplicate style insertion after hydration. | BR-BLD-07 |
|
||||
| V16 | Node and browser `Intl.NumberFormat('nl-NL')` give the same price text. | BR-HYD-17 |
|
||||
| V17 | No inline event-handler attributes (`on*=`) or `javascript:` URLs in Start's output (they are not scripts for the runner but the CSP blocks them). The e2e CSP check covers this. | BR-SEC-01 |
|
||||
| V18 | The CI artifact upload of `web/dist/client/` keeps `index.html` at the artifact root for the existing deploy steps. | BR-BLD-10 |
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
# Domain Entities - Unit 1: Start migration and script step
|
||||
|
||||
The site has no runtime data model and unit 1 adds none. The entities are build-time data of the script step and the preview server, the e-mail slot, and the inventory of browser-dependent values. Existing entities (`SitePage`, `SiteContent`, `EmailAddress`) are unchanged. Rules: [business-rules.md](business-rules.md).
|
||||
|
||||
## 1. Relationships
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Reg["SitePage register sitePages"]
|
||||
Exp["ExpectedFileSet"]
|
||||
Html["HtmlFile"]
|
||||
Scr["ScriptElement"]
|
||||
Mov["MovedScript"]
|
||||
Res["ExternalizeResult"]
|
||||
Plan["OutputPlan"]
|
||||
Vio["Violation"]
|
||||
Mail["EmailAddress parts"]
|
||||
Slot["EmailSlot"]
|
||||
Req["RequestResolution"]
|
||||
Reg -->|"yields"| Exp
|
||||
Exp -->|"is compared with"| Html
|
||||
Html -->|"contains zero or more"| Scr
|
||||
Scr -->|"executable ones become"| Mov
|
||||
Html -->|"is rewritten into"| Res
|
||||
Res -->|"lists"| Mov
|
||||
Plan -->|"holds writes and"| Vio
|
||||
Html -->|"is input of"| Plan
|
||||
Mail -->|"gives"| Slot
|
||||
Mail -->|"scanned for in"| Plan
|
||||
Exp -->|"is the file set of"| Req
|
||||
classDef source fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
classDef data fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef result fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef problem fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class Reg,Mail source;
|
||||
class Exp,Html,Scr,Req,Slot data;
|
||||
class Mov,Res,Plan result;
|
||||
class Vio problem;
|
||||
```
|
||||
|
||||
Text alternative: the page register yields the expected files, which are compared with the HTML files; scripts in an HTML file become moved scripts in a result, and the plan holds the writes and violations, including the e-mail scan; the e-mail parts give the render slot.
|
||||
|
||||
## 2. Entities
|
||||
|
||||
### Script step (pure, `config/`)
|
||||
|
||||
| Entity | Fields | Notes |
|
||||
|---|---|---|
|
||||
| `ScriptElement` (internal) | `start`, `end` (byte range), `attributeText` (verbatim between the tag name and `>`), `body`, `kind` | `kind` is `external`, `empty`, `data` or `executable` (flowchart 1.1). Not exported. |
|
||||
| `MovedScript` | `fileName: string`, `body: string` | `fileName` is `inline-<12 hex>.js`; the file lives at `/assets/<fileName>`. |
|
||||
| `ExternalizeResult` | `html: string`, `moved: MovedScript[]` | `moved` has unique file names in order of first appearance. |
|
||||
| `ExpectedFileSet` | `pages: Map<path, file>`, `notFound: '404.html'` | From `sitePages` keys through `pageFile`. `404.html` is not a `sitePages` path. |
|
||||
| `Violation` | `file: string`, `code: ViolationCode`, `detail: string` | Codes in business-logic-model.md § 3.2. `detail` never holds a script body or the address. |
|
||||
| `OutputPlan` | `writes: Map<relativePath, string>`, `violations: Violation[]` | Result of `planExternalization`. Violations empty means the writes may be applied. |
|
||||
| `PlanContext` | `expected: ExpectedFileSet`, `address: string \| null`, `sitemap: string`, `rootPaths: string[]` | `address` is `emailAddress(siteContent.email)`; `rootPaths` are the repository root in both slash styles. |
|
||||
|
||||
Constants: `ASSETS_DIR = 'assets'`, `HASH_LENGTH = 12`, `NOT_FOUND_FILE = '404.html'`, `NOT_FOUND_PATH = '/404'`, the JavaScript type list of BR-SCR-04, the raw-text element list of BR-SCR-02.
|
||||
|
||||
`config/pageFiles.ts` (new, pure): `pageFile(path): string`, `pagePath(file): string | undefined` (inverse, `undefined` for `404.html` and unknown files).
|
||||
|
||||
### E-mail slot
|
||||
|
||||
| Entity | Fields | Notes |
|
||||
|---|---|---|
|
||||
| `EmailAddress` (existing) | `user`, `domain` | Unchanged. Parts only; never joined during prerender. |
|
||||
| `EmailSlot` | `available: boolean`, `address: string \| null` | Result of `useEmailAddress`. `available` is `isEmailAddressValid(parts)`; `address` is non-null only when hydrated and available. |
|
||||
| `ContactChannel` (existing, extended) | adds `{ kind: 'email-pending' }` | Produced by `contactChannels(email, socials, assemble)` when `assemble` is false and the parts are valid. No `href`, no `label`. |
|
||||
|
||||
| `available` | `address` | State | Renders |
|
||||
|---|---|---|---|
|
||||
| false | null | absent | nothing |
|
||||
| true | null | pending (prerender, hydrating render) | placeholder, `aria-hidden`, reserved size |
|
||||
| true | string | ready | text and `mailto` link |
|
||||
|
||||
### Preview server
|
||||
|
||||
| Entity | Fields | Notes |
|
||||
|---|---|---|
|
||||
| `RequestResolution` | `{ file: string; status: 200 \| 404 }` (unit 1 never returns `{ redirect }`) | `file` relative to `clientDir`, forward slashes. |
|
||||
| `PreviewHeaders` | `securityHeaders('production')` plus `Content-Type`, and `Cache-Control: no-cache` for HTML | Same set on every response. |
|
||||
|
||||
## 3. Hydration inventory
|
||||
|
||||
Every value found in `web/src` that differs between the prerender and the first browser render, with the contract that removes the difference. "Today" is the code at master c4c2f83.
|
||||
|
||||
| # | Source (file) | Today | First render, server and browser | After hydration | Rule |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | `hooks/usePageLoaded.ts` | `useState(() => document.readyState === 'complete')`: throws on the server | `false` | readyState and `load` event | BR-HYD-04 |
|
||||
| 2 | `hooks/useInView.ts` | `typeof IntersectionObserver` in render: `inView` true on the server, false in the browser | `inView = skip` | observed, or `true` without observer | BR-HYD-05 |
|
||||
| 3 | `hooks/useReveal.ts`, `Hero/useHeroSlider.ts`, `home/ContactSection`, `home/Testimonials/TestimonialCarousel` | `useMediaQuery(..., { ssr: false })`: reads `window.matchMedia` in the initialiser, throws on the server, real value in the browser | `false` | real value from Chakra's effect | BR-HYD-07, 08 |
|
||||
| 4 | `NavigationBar/NavigationBar.tsx` | `useBreakpointValue({ base: false, lg: true }, { ssr: false })`: same | `false` (value of `base`) | `viewport` dispatch with the real value; layout is CSS only | BR-HYD-07, 08 |
|
||||
| 5 | `home/IntroGallery` | `useBreakpointValue({ base: true, sm: false })` with default `ssr`: already safe | `true` (value of `base`) | real value; `tabIndex` leaves from `sm` | BR-HYD-08 |
|
||||
| 6 | `Hero/useHeroSlider.ts` | `useState(() => document.hidden)`: throws on the server, differs in a background tab | `false` | `document.hidden`, `visibilitychange` | BR-HYD-09 |
|
||||
| 7 | `routes/index.tsx`, `routes/contact.tsx`, `routes/portfolio.tsx` | `Route.useSearch()` in the first render: error #418 (spike) | search not applied | search applied | BR-HYD-10 to 12 |
|
||||
| 8 | `StatusPage/NotFound.tsx` | `isShootSectionPath(pathname)` in the first render | one home button | extra buttons under `/soorten-fotoshoots/` | BR-HYD-13, BR-404 |
|
||||
| 9 | `Footer/Footer.tsx` | `new Date().getFullYear()` in render | `BUILD_YEAR` | current year | BR-HYD-14 |
|
||||
| 10 | `Footer`, `ContactDetails` (through `contactChannels`), `ContactFormGate`, `ContactForm` | `emailAddress(...)` in render | placeholder or nothing | address and link | BR-MAIL-01 to 09 |
|
||||
| 11 | `Analytics/UmamiAnalytics.tsx` | default parameter `window.location.hostname` evaluated in render: throws on the server | `hostname` read in the effect | script added on known hosts | BR-HYD-15, BR-MON-03 |
|
||||
| 12 | `NavigationBar` `NavLink`s and `MobileNav` links (router `Link`) | default fuzzy active matching against the browser location: `aria-current` differs on an unknown URL such as `/over-mij/x` | exact matching, never current there | unchanged | BR-404-05 |
|
||||
| 13 | `home/Pricing/PriceCard.tsx` (router `Link`) | link to `/?pakket=...` is active on `/?pakket=...` in the browser only (attributes) | differs in attributes only | tidy navigation clears it | BR-HYD-21 |
|
||||
| 14 | `ContactForm.tsx` `shownAt` | `Date.now()` in an initialiser, not rendered | same | form timer starts in the browser | BR-HYD-16 |
|
||||
| 15 | `lib/formatPrice.ts` | `Intl.NumberFormat('nl-NL')`: Node and browser ICU could differ | identical text expected | none | BR-HYD-17, V16 |
|
||||
| 16 | `home/Testimonials`, `ContactPanel` (`lazy`) | placeholder until near the viewport | placeholder; all reviews in the HTML | component loads | BR-LZY-01, 02 |
|
||||
|
||||
Checked and safe, no rule beyond BR-HYD-19: `hooks/useScrolledPast.tsx` (effect only, starts `false`), `BackToTop` (`window` only in the scroll handler and effect), `MobileNav`, `NavSubmenu`, `useDismiss`, `useRouteFocus`, `Hero` (`requestAnimationFrame` in an event handler), `Lightbox` (lazy, after a request), `PortfolioGrid` (`masonryRowSpan` is pure, no measuring), `routes/__root.tsx` devtools (`import.meta.env.DEV`, a build-time constant). Not present in `src`: `Math.random`, `crypto`, `localStorage`, `sessionStorage`, `useId`, `navigator`, `innerWidth` in render, `ResizeObserver`, `dangerouslySetInnerHTML` other than JSON-LD.
|
||||
+147
@@ -0,0 +1,147 @@
|
||||
# Frontend Components - Unit 1: Start migration and script step
|
||||
|
||||
All paths are under `web/`. Interfaces for new files follow [component-methods.md](../../../inception/application-design/component-methods.md); this document fixes the details and records the additions (marked **new**). Rules: [business-rules.md](business-rules.md). Logic: [business-logic-model.md](business-logic-model.md). First-render values: [domain-entities.md § 3](domain-entities.md).
|
||||
|
||||
## 1. Component hierarchy
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Vite["vite.config.ts with Start plugin"] --> Router["src/router.tsx getRouter"]
|
||||
Client["src/client.tsx: Sentry, then hydrate"] --> Router
|
||||
Router --> Root["routes/__root.tsx shellComponent"]
|
||||
Root --> Html["html, HeadContent, ChakraProvider, Scripts"]
|
||||
Html --> App["AppShell"]
|
||||
App --> Nav["NavigationBar and MobileNav"]
|
||||
App --> Out["Outlet: page routes and catch-all"]
|
||||
App --> Foot["Footer"]
|
||||
App --> Top["BackToTop"]
|
||||
App --> Umami["UmamiAnalytics"]
|
||||
Out --> Pages["index, contact, portfolio, other pages"]
|
||||
Out --> NF["routes/$.tsx NotFound"]
|
||||
Pages --> Panel["ContactPanel and ContactFormGate"]
|
||||
Pages --> Details["ContactDetails"]
|
||||
Pages --> Tests["Testimonials"]
|
||||
Nav --> Hyd["useHydrated"]
|
||||
Foot --> Mail["useEmailAddress"]
|
||||
Details --> Mail
|
||||
Panel --> Mail
|
||||
NF --> Hyd
|
||||
Pages --> Hyd
|
||||
Mail --> Hyd
|
||||
Cfg["config: pageFiles, inlineScripts, externalizeInlineScripts, previewServer"] -.-> Vite
|
||||
classDef build fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef app fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef hook fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef infra fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
|
||||
class Vite,Router,Client,Root,Html build;
|
||||
class App,Nav,Out,Foot,Top,Umami,Pages,NF,Panel,Details,Tests app;
|
||||
class Hyd,Mail hook;
|
||||
class Cfg infra;
|
||||
```
|
||||
|
||||
Text alternative: the Start build and the browser entry both use getRouter; the root shell renders the document around AppShell, whose navigation, pages, footer and monitoring components use the hydration hooks (green = app components, yellow = hooks, blue = build and entry, orange = config tools).
|
||||
|
||||
## 2. Changed components
|
||||
|
||||
"Contract" is what the component renders in the first render, on the server and in the browser (BR-HYD-01).
|
||||
|
||||
### Build, entry and document
|
||||
|
||||
| Component | Status | Contract and behaviour |
|
||||
|---|---|---|
|
||||
| `vite.config.ts` | Changed | `tanstackStart` with prerender: pages from `sitePages` plus `/404` to `/404.html`, `autoSubfolderIndex: false`, no extra crawling. Start plugin only outside Vitest. `define` of `VITE_BUILD_YEAR`. `sitemapPlugin` emits in the client environment only. CSP headers for `server` and `preview` stay from `securityHeaders`. |
|
||||
| `src/router.tsx` | **new** | `getRouter()` and a shared options function (routeTree, `scrollRestoration: true`, `defaultErrorComponent: ErrorPage`). |
|
||||
| `src/routes/__root.tsx` | Changed | `shellComponent` renders `<html lang="nl">`, `HeadContent`, `ChakraProvider value={system}` around children, `Scripts` last. `head()` adds charset, viewport, `favicon.png` icon and `apple-touch-icon` besides `siteHead`. Fonts imported here. `component` stays `RootLayout` (without `HeadContent`, which moves to the shell). `notFoundComponent` and `errorComponent` stay. |
|
||||
| `src/client.tsx` | **new** | `startSentry()`, then hydrate inside `StrictMode`. Replaces `main.tsx`; `index.html` is removed. |
|
||||
| `src/routes/$.tsx` | **new** | Catch-all route, component `NotFound`. No `head()`. |
|
||||
| `config/inlineScripts.ts` | **new** | `externalizeInlineScripts`, `findExecutableInlineScripts` (signatures as in component-methods.md). |
|
||||
| `config/externalizeInlineScripts.ts` | **new** | `externalizeOutput(clientDir)`, plus exported `planExternalization(files, context)` (**new**, pure core). Runs as a script with Node type stripping like `writeServerConfig.ts`. |
|
||||
| `config/pageFiles.ts` | **new** | `pageFile`, `pagePath`, `NOT_FOUND_FILE`, `NOT_FOUND_PATH`. |
|
||||
| `config/previewServer.ts` | **new** | `resolveRequest`, `startPreviewServer`. `package.json` `preview` runs it. |
|
||||
| `config/sitemapPlugin.ts` | Changed | Emits `sitemap.xml` only when `this.environment.name` is the client environment (to verify V7). |
|
||||
| `src/test/renderApp.tsx` | Changed | Router from the shared options with memory history; no `<html>` shell (V2). |
|
||||
| `e2e/` | **new** | Playwright tests of BR-TST-05 and BR-TST-06. |
|
||||
|
||||
### Hooks
|
||||
|
||||
| Hook | Status | Interface and contract |
|
||||
|---|---|---|
|
||||
| `hooks/useHydrated.ts` | **new** | `useHydrated(): boolean`. `useSyncExternalStore(subscribeNoop, () => true, () => false)`. Same behaviour as the `useHydrated` that `@tanstack/react-router` exports (marked internal there), so the project owns its copy. |
|
||||
| `hooks/useEmailAddress.ts` | **new** | `useEmailAddress(email: EmailAddress): { available: boolean; address: string \| null }` (BR-MAIL-01). |
|
||||
| `hooks/usePageLoaded.ts` | Changed | Store-based (BR-HYD-04). Returns `false` while hydrating. |
|
||||
| `hooks/useInView.ts` | Changed | Same options and return `{ ref, inView }`. `inView = skip \|\| intersected \|\| unsupported` (BR-HYD-05). The "no observer counts as in view" contract is applied after the first render. |
|
||||
| `hooks/useReveal.ts` | Changed | `useMediaQuery` without `ssr: false`; first render `reducedMotion` is `false`. Returns `{ ref, visible }` as before; the visible-by-default rule is unit 2. |
|
||||
| `hooks/useScrolledPast.tsx` | Unchanged | Verified safe (BR-HYD-06). The application design lists it as changed; it needs no change. |
|
||||
| `Hero/useHeroSlider.ts` | Changed | `hidden` from a store, `useMediaQuery` without `ssr: false`; first render `autoplay` is `count > 1`. |
|
||||
|
||||
### Pages and components
|
||||
|
||||
| Component | Status | Contract |
|
||||
|---|---|---|
|
||||
| `routes/index.tsx` | Changed | `pakket` passed to `ContactSection` is `hydrated ? search.pakket : undefined`. |
|
||||
| `routes/contact.tsx` | Changed | Same for `ContactPanel`; the tidy effect depends on the gated value. |
|
||||
| `routes/portfolio.tsx` | Changed | `shoot` passed to `PortfolioGallery` is `hydrated ? search.shoot : undefined`; navigation callback unchanged. |
|
||||
| `NavigationBar` | Changed | `useBreakpointValue` without `ssr: false` (first render `false`); all `NavLink`s get `activeOptions={{ exact: true, includeSearch: false }}`. Layout stays CSS-driven, so no visible jump. |
|
||||
| `MobileNav` | Changed | Top-level links get the same `activeOptions`. |
|
||||
| `IntroGallery` | Unchanged | `useBreakpointValue` already uses the default; first render `scrollable` is `true` (BR-HYD-08). |
|
||||
| `ContactSection` | Changed | `useMediaQuery` without `ssr: false`; effect unchanged. |
|
||||
| `TestimonialCarousel` | Changed | `useMediaQuery` without `ssr: false`. Only renders after hydration. |
|
||||
| `Testimonials` | Changed | `CarouselPlaceholder` renders every visible review (longest in flow, others `aria-hidden`, visually hidden, `inert`) so the texts are in the HTML (BR-LZY-02). |
|
||||
| `NotFound` | Changed | `hydrated && isShootSectionPath(pathname)` picks the buttons. Renders its own `<title>` and `noindex` meta as today. |
|
||||
| `Footer` | Changed | Year: `hydrated ? new Date().getFullYear() : BUILD_YEAR`. Contact column per `useEmailAddress`: absent, placeholder item, or link (BR-MAIL-03). |
|
||||
| `ContactDetails` | Changed | `contactChannels(email, socials, hydrated)`; renders an empty `aria-hidden` item with `minH` 44 px for `email-pending` (BR-MAIL-04). Returns `null` only when there is no channel at all. |
|
||||
| `ContactFormGate` | Changed | Notice per BR-MAIL-05: sentence only plus hidden placeholders before hydration; address text, link and button after. `mb` depends on `available`. |
|
||||
| `ContactForm` | Changed | Reads `useEmailAddress`; the mail link in the failed state uses its `address`. `shownAt` unchanged (BR-HYD-16). |
|
||||
| `ContactPanel` | Unchanged | Props and behaviour as today; lazy form per BR-LZY-01. |
|
||||
| `PriceCard` | Unchanged | Accepted attribute difference (BR-HYD-21). |
|
||||
| `UmamiAnalytics` | Changed | `hostname` default read in the effect. |
|
||||
| `AppShell`, `BackToTop`, `Hero`, `PortfolioGallery`, `Lightbox` | Unchanged | Verified safe (BR-HYD-19). `useRouteFocus` unchanged (V14). |
|
||||
| `lib/emailAddress.ts` | Changed | Adds `isEmailAddressValid`; `emailAddress` reuses it. |
|
||||
| `lib/contactChannels.ts` | Changed | Third parameter `assemble`; new kind `email-pending` (BR-MAIL-07). |
|
||||
|
||||
## 3. Placeholder specification
|
||||
|
||||
| Place | Before hydration (available) | After hydration |
|
||||
|---|---|---|
|
||||
| Footer Contact column | Title "Contact" and one empty `li`, `aria-hidden`, `data-email-pending`, `minH` 44 px below `lg` | `li` with the `FooterLink` mailto |
|
||||
| Contact card (twice) | First `li` empty, `aria-hidden`, `data-email-pending`, `minH` 44 px | `li` with the mailto link and icon |
|
||||
| Gate notice | Sentence only. Hidden inline block `n` characters wide where " Mail me voor nu op <address>" will come; hidden button placeholder with the button's recipe and label | Sentence extended, address link, "Stuur een e-mail" button |
|
||||
|
||||
All placeholders carry no text a reader needs, no `href`, no address and no `mailto`. Measured sizes (V10) must give CLS below 0.01 (BR-MEA-04).
|
||||
|
||||
## 4. Interaction flows that must keep working
|
||||
|
||||
| Flow | Behaviour after the change |
|
||||
|---|---|
|
||||
| Direct load of `/?pakket=gezin#contact` | HTML paints; after hydration the panel takes the package, the form loads, the address bar is tidied to `/#contact`, smooth scroll and focus on the contact heading |
|
||||
| Direct load of `/contact?pakket=gezin` | HTML paints; the package is preselected after hydration; the URL becomes `/contact` without a history entry |
|
||||
| Direct load of `/portfolio?shoot=gezin` | All photos first, then the filtered list; filter clicks navigate with `replace` and keep the scroll position |
|
||||
| Click "Boek" on a price card (client navigation) | Search applies in the first render of the next state; same as today |
|
||||
| Mobile menu | Opens, closes with button and Escape, sets `body` overflow; closes at `lg` and on route change |
|
||||
| Unknown URL | 404 page in the shell; extra buttons under `/soorten-fotoshoots/` after hydration |
|
||||
|
||||
## 5. Accessibility and layout notes
|
||||
|
||||
- Placeholders are `aria-hidden` and empty; they add no stops for keyboard or screen reader users.
|
||||
- Visually hidden testimonial copies are `aria-hidden` and `inert`, so each review is read once, in the carousel.
|
||||
- The footer "Contact" title stands alone without JavaScript until unit 2 decides (BR-MAIL-09).
|
||||
- `IntroGallery`'s list has `tabIndex={0}` in the HTML at every width until hydration; it is removed from `sm` up afterwards (BR-HYD-08).
|
||||
- Lighthouse accessibility, best practices and SEO targets stay 1.0 (NFR-PR-S-01); the check at the end of unit 1 is informative, the final targets are unit 3.
|
||||
|
||||
## 6. Testable properties
|
||||
|
||||
Component-level properties: none, see "No PBT properties identified" in [business-logic-model.md § 9](business-logic-model.md). The pure functions (`inlineScripts`, `pageFile`, `planExternalization`, `contactChannels`, `isEmailAddressValid`, `resolveRequest`) have properties P1 to P17 there.
|
||||
|
||||
## 7. Example-based test list (code generation input)
|
||||
|
||||
| Area | Test |
|
||||
|---|---|
|
||||
| Hooks | `useHydrated`, `usePageLoaded`, `useInView`, `useHeroSlider.hidden`: server snapshot value while hydrating (`hydrateRoot` into server-rendered markup), real value after |
|
||||
| Routes | Contact, home and portfolio: no search in the first render, search applied after; tidy navigation still fires; filter navigation still works |
|
||||
| Footer | Year equals build year while hydrating, current year after; Contact column states absent, pending, ready |
|
||||
| Contact components | `ContactDetails`, `ContactFormGate`, `ContactForm`: no address in `renderToString` output; address after hydration |
|
||||
| NotFound | One button while hydrating; two extra under `/soorten-fotoshoots/` after |
|
||||
| Navigation | No link current on an unknown sub-path; current on real pages and with a search |
|
||||
| Script step | Worked examples of business-logic-model.md § 3.1; each violation code; unsupported forms; unterminated script |
|
||||
| Preview server | Status, headers, methods, content types for `/`, `/x`, `/file.ext`, unknown, traversal |
|
||||
| Build and e2e | BR-TST-05 and BR-TST-06 |
|
||||
Reference in New Issue
Block a user