Adds the first unit's code summary and updates the shared docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-31 20:28:41 +01:00
co-authored by Claude Opus 5.5
parent d6f8eb6c8e
commit 8dc120e78c
10 changed files with 119 additions and 29 deletions
@@ -472,13 +472,13 @@ Disjoint from B2 and B4. Runs only targeted `vitest run` commands. The editing o
- 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 [ ]
### Step 32: Code summary [x]
- 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 [ ]
### Step 33: Shared reverse-engineering delta [x]
- Executor: Sonnet.
- Implements: NFR-PR-Q-05; team agreement (only this feature's lines are updated).
@@ -0,0 +1,87 @@
# Code Summary - Unit 1: Start migration and script step
Plan: [start-migration-code-generation-plan.md](../../plans/start-migration-code-generation-plan.md). Worktree `AndreaSlopFotografie-prerendering`, from master `c4c2f83`. File list from `git diff c4c2f83 --stat` (104 files) and `git log c4c2f83..HEAD`.
## Status
- Steps 1 to 31 done (checked in the plan); this summary is Step 32, the reverse-engineering delta is Step 33.
- Step 34 (gate measurement) has **not run**. This summary states no performance result, and the feature's goals (NFR-PR-P-03, P-04) are not claimed as met. V10 (placeholder sizes, CLS) is still open until Step 34.
- The build is **not deployable** until unit 3 changes the server rules (see Open points).
## Commits
Ten commits on top of `c4c2f83`, oldest first: `65c850e` docs (requirements, design, baseline), `c1e90f0` Start migration, `1574726` script step, `2c2e27e` first render equals the prerendered HTML, `0b964b5` preview server, `fe1ec5d` build wiring, `0c5d8b8` gzip in the preview server, `8bf0000` browser tests and 404 hydration fix, `8867c78` CI runs the browser tests, `a68e84c` comment cleanup, `d6f8eb6` hydration test moved out of `routes/`.
## Files
### Build and entry (BR-BLD-01 to 12, BR-ENT-01 to 06, BR-404-01, 02, BR-MON-01; FR-PR-01 to 04, 08)
- Created: `web/src/client.tsx` (hydration entry, `startSentry()` first), `web/src/router.tsx` (`routerOptions()`, `getRouter()`), `web/src/routes/$.tsx` (catch-all, `pendingComponent` equals the component)
- Modified: `web/src/routes/__root.tsx` (document shell `shellComponent`, head), `web/vite.config.ts` (Start plugin, page list from `sitePages`, `/404.html`, no Start plugin in test mode), `web/src/routeTree.gen.ts` (regenerated), `web/src/navigation.ts` (`RoutePath` excludes `/$`), `web/config/sitemapPlugin.ts` (client environment only), `web/lighthouserc.cjs` (`notFoundPath` is `/404.html`), `web/package.json`, `web/pnpm-lock.yaml`, `web/pnpm-workspace.yaml`, `web/tsconfig.json`, `web/eslint.config.js`, `web/.gitignore` (`.tanstack`)
- Removed: `web/index.html`, `web/src/main.tsx`
- Created: `web/config/pageFiles.ts` (+ `pageFiles.test.ts`, P10): page path to file name
### Script step (BR-SCR-01 to 21, BR-SEC-02, 03; FR-PR-19, 20; NFR-PR-SEC-03, 04)
- Created: `web/config/inlineScripts.ts` (+ `.test.ts`, P1 to P9), `web/config/externalizeInlineScripts.ts` (+ `.test.ts`, P11 to P13), `web/src/test/htmlArbitraries.ts`
### Preview server (BR-SRV-01 to 08; FR-PR-14 preview part; NFR-PR-SEC-01)
- Created: `web/config/previewServer.ts` (+ `.test.ts`, P16, P17), `web/src/test/requestArbitraries.ts`
### Hydration safety: hooks (BR-HYD-02 to 05, 09)
- Created: `web/src/hooks/useHydrated.ts` (+ test), `web/src/hooks/useEmailAddress.ts` (+ test), `web/src/hooks/useInView.test.tsx`
- Modified: `web/src/hooks/useInView.ts`, `usePageLoaded.ts` (+ test), `useReveal.ts` (+ test), `web/src/components/Hero/useHeroSlider.ts` (+ test)
### Hydration safety: components, routes, lib (BR-HYD-10 to 14, BR-MAIL-01 to 10, BR-LZY-02, BR-404-04, 05; FR-PR-05 to 07, 15, 22)
- Modified: `web/src/components/Footer/Footer.tsx` (+ test), `ContactDetails/ContactDetails.tsx` (+ test), `ContactForm/ContactFormGate.tsx` (+ test), `ContactForm/ContactForm.tsx` (+ test), `NavigationBar/NavigationBar.tsx` (+ test), `NavigationBar/MobileNav.tsx`, `StatusPage/NotFound.tsx` (+ test), `home/Testimonials/Testimonials.tsx` (+ test), `home/Testimonials/TestimonialCarousel.tsx`, `home/ContactSection/ContactSection.tsx`, `Analytics/UmamiAnalytics.tsx`, `web/src/routes/index.tsx`, `contact.tsx`, `portfolio.tsx` (search gating)
- Modified: `web/src/lib/contactChannels.ts` (+ test, P14), `web/src/lib/emailAddress.ts` (+ test, P15)
### Tests and harness (BR-TST-01 to 07; NFR-PR-Q-01 to 04)
- Created: `web/src/hydration.test.tsx`, `web/src/prerender.test.tsx`, `web/src/test/hydrate.tsx` (`hydrateApp`, `hydrateAppAsStart`), `web/vitest.e2e.config.ts`, `web/e2e/{hydration,interaction,rawHtml,smoke}.e2e.ts`, `web/e2e/support/{browser,globalSetup,server}.ts`
- Modified: `web/src/test/renderApp.tsx` (test shell), `web/src/test/setup.ts`, `web/src/app.test.tsx`, `web/src/components/DeferredImage/DeferredImage.test.tsx`
### CI
- Modified: `.gitea/workflows/continuous_integration.yaml` (browser tests on the `dist/client` artifact, BR-BLD-10, BR-TST-05)
### Documentation
- Created under `aidlc-docs/features/prerendering/`: `aidlc-state.md`, `audit.md`, `inception/*` (requirements, application design, plans, execution plan), `construction/plans/*` (three plans), `construction/start-migration/functional-design/*` (four documents), `construction/start-migration/code/{baseline-checks,measurement-baseline,proof-report,verification-log,code-summary}.md`; modified `aidlc-docs/active-features.md`
- Modified in Step 33: `aidlc-docs/_shared/reverse-engineering/{architecture,code-structure,technology-stack,dependencies,component-inventory,business-overview}.md` (feature lines only)
- Corrected in Step 32: `functional-design/business-rules.md` BR-LZY-01 and BR-MAIL-05 (see Deviations)
## Test inventory
- Step 1 baseline: 113 files, 888 tests. After Step 31 (before `src/routes/hydration.test.tsx` moved to `src/hydration.test.tsx`): 123 files, 1179 tests, all passing; fast-check seed 1405857762; coverage thresholds met.
- Browser tests (`pnpm e2e`): 4 files, 77 tests, passing.
- Properties: P1 to P9 `config/inlineScripts.test.ts`; P10 `config/pageFiles.test.ts`; P11 to P13 `config/externalizeInlineScripts.test.ts`; P14 `src/lib/contactChannels.test.ts`; P15 `src/lib/emailAddress.test.ts`; P16, P17 `config/previewServer.test.ts`. Hooks and browser flows have example tests only (no PBT properties identified).
- Old tests changed under BR-TST-02: `usePageLoaded.test.tsx`, `DeferredImage.test.tsx`, `useReveal.test.tsx`, `app.test.tsx` (register test ignores `/$`).
## Verification log (V1 to V18, condensed)
Details: [verification-log.md](verification-log.md).
- OK: V1 (client entry), V2 (shell in jsdom, test shell), V3 (3 moved scripts per page, 5 on `/contact`, 16 files), V4 (keep the minimum of one), V5 (12 pages), V6, V7, V8 (see Deviations), V9, V11, V12, V13, V14, V15, V16, V17, V18.
- Open: V10 (placeholder sizes and CLS; first estimates only, measured in Step 34).
## Step 31 outcome
- Build: 12 pages, 16 scripts moved (28 files written), no violations.
- `pnpm audit:deps` clean. `pnpm audit` severity counts are identical to master: low 2, moderate 10, high 11, critical 0.
- Lint, format, tests, build and e2e green.
## Deviations from the design and plan
1. `zod@4: ^4.6.6` override in `pnpm-workspace.yaml` (GHSA-mrhx-c7xc-m3w5 in Start's tree); patch bump, zod 3 untouched. The main session confirms it.
2. Exact pins for `@tanstack/react-start` 1.169.4 and `@tanstack/react-router` 1.170.46 (was `^1.170.39`, raised to avoid two router copies); `playwright-core` pinned 1.55.0.
3. `RoutePath` in `src/navigation.ts` excludes `/$`.
4. `renderApp` renders with a test shell (`HeadContent` + children) instead of the real `shellComponent` (V2).
5. `pendingComponent` on the catch-all route equals its component (through one shared `CatchAll`). Root cause of React error #418 on `404.html`: the HTML is made for `/404`, the browser is at another URL, so Start's `hydrate()` finds a different match id (`#$#404` against `#$#404.html`) and presents the match as pending with `ssr: false`; without a `pendingComponent` the first browser render is empty and React hydrates the Suspense boundary against the full page (a race, so it depends on width, CPU and network). Detail in the verification log.
6. `notFoundPath` in `lighthouserc.cjs` is `/404.html` (Lighthouse refuses a 404 status).
7. Gzip added to the preview server (commit `0c5d8b8`), as the production server is expected to.
8. Gate placeholder is `38ch` (20 + 18 characters) in `ContactFormGate`; BR-MAIL-05 now says so.
9. Extra guard in `useInView`: the effect of the hydrating render still sees the server's `unsupported` (false), so it also checks `IntersectionObserver` itself.
10. Test helper `hydrateAppAsStart` in `src/test/hydrate.tsx`: reproduces the router state Start's `hydrate()` leaves, which `hydrateApp` hides.
11. BR-LZY-01 corrected: on `/contact` the form is in the HTML only as a hidden streamed Suspense segment (`<div hidden id="S:0">` at the end of the body); the moved React completion script (`$RC`) reveals it (V8). Without JavaScript it is in the HTML but not visible, which FR-PR-13 allows.
## What unit 2 and 3 can rely on (business-rules.md section 3)
- `dist/client` holds 12 HTML files (11 pages and `404.html`), `sitemap.xml`, and all moved scripts as `/assets/inline-<hash>.js`; `dist/server` is a sibling and is not deployed.
- No inline executable script, no `on*=` attribute and no `javascript:` link remain; the CSP (`script-src 'self'` + Umami) is unchanged. The e-mail address is in no output file (the runner checks it).
- Pages are files (`over-mij.html`, no folders); `404.html` is the not-found page. The preview server follows the rules unit 3 must put on nginx and IIS (BR-SRV-01 to 08).
- Unit 2 changes `Reveal`, `DeferredImage` and the hero; the content of `Reveal` is hidden in the HTML until then (V15).
## Open points for the owner
- **FR-PR-23 compression (unit 3):** gzip is on in the preview server only; nginx and IIS need it too. `test.andreaslop.nl` sends no `Content-Encoding` today.
- **BR-404-07 (unit 3):** `/over-mij/` and `/Over-Mij` on a case-sensitive host get `404.html` with status 404 while the router renders the real page; the document then holds two titles and the `noindex` meta. Server and router rules must agree.
- **Deployability:** the build is not deployable until unit 3 changes the server rules.
- **For the measurement (Step 34):** `/contact`'s form is revealed by the moved completion script, one request later than in Start's raw output; the router's scroll restoration script, now external, sits mid-document (last child of `<main>`) and blocks parsing of the footer until fetched. Both can affect CLS, LCP and FCP.
- Step 34 also decides V10 and the Lighthouse targets; its result goes into `measurement-gate.md`, not here.
@@ -118,7 +118,7 @@ Owner decision: the address stays out of the HTML and the serialized data and ap
| 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-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). As built, the block is as wide as the lead text plus the address: `38ch` (20 + 18 characters; V10, to be measured in Step 34). 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 |
@@ -142,7 +142,7 @@ Owner decision: the address stays out of the HTML and the serialized data and ap
| 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-01 | `ContactPanel` / `ContactForm` on `/contact` (`load="eager"`): the form is in the first render on both sides, but the lazy chunk makes it a streamed Suspense segment: the HTML holds the form fields only as a hidden segment (`<div hidden id="S:0">`) at the end of the body, and the gate holds a placeholder box. React's completion script (`$RC`, moved to an external file by the script step) reveals the form inside the gate after the page loads (V8, corrected in Code Generation). 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 |