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:
2026-10-31 17:41:12 +01:00
co-authored by Claude Opus 5.5
parent c4c2f83d6c
commit 65c850e949
22 changed files with 2569 additions and 0 deletions
@@ -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.