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>
8.4 KiB
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.
1. Relationships
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 NavLinks 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.