Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/start-migration/functional-design/domain-entities.md
T
SluijsensandClaude Opus 5.5 65c850e949 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>
2026-10-31 17:41:12 +01:00

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.