Files

10 KiB

Code Summary - Unit 1: Start migration and script step

Plan: 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.

  • 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.