# 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 (`