Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/construction/start-migration/functional-design/business-rules.md
T

42 KiB

Business Rules - Unit 1: Start migration and script step

Rule ids are scoped to this feature (the code comments of earlier features also use BR-MAIL-01 for the mail subject; here it is the e-mail address protection). "Source" points at a requirement (FR/NFR) or design decision (D1 to D13 in application-design.md). Flows: business-logic-model.md. Components: frontend-components.md. Data: domain-entities.md.

Groups: BR-BLD build, BR-ENT entry and document, BR-HYD hydration, BR-MAIL e-mail address, BR-404 not found, BR-LZY lazy code, BR-MON Sentry and Umami, BR-SCR script step, BR-SEC output hygiene, BR-SRV preview server, BR-TST tests, BR-MEA measurement.

1. Decision flowcharts

1.1 Is an inline script moved

graph TD
    s["Script element found by the scanner"] --> src{"Has a src attribute?"}
    src -->|"yes"| keepExt["Leave as is: external script"]
    src -->|"no"| body{"Body empty after trim?"}
    body -->|"yes"| keepEmpty["Leave as is: no effect"]
    body -->|"no"| typ{"type absent, empty, a JavaScript type or module?"}
    typ -->|"no"| keepData["Leave as is: data block such as ld+json"]
    typ -->|"yes"| bad{"async or defer on a classic script, body contains comment opener, or relative import in a module?"}
    bad -->|"yes"| fail["Error UNSUPPORTED_SCRIPT"]
    bad -->|"no"| move["Replace by external reference, write file"]
    classDef decision fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
    classDef keep fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef act fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef error fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    class src,body,typ,bad decision;
    class keepExt,keepEmpty,keepData keep;
    class s,move act;
    class fail error;

Text alternative: only scripts without src, with a non-empty body and a JavaScript or module type are moved; data blocks, external and empty scripts stay, and three unsupported forms fail the build.

1.2 What a component renders before and after hydration

graph TD
    v["Browser-dependent value"] --> kind{"Kind of value"}
    kind -->|"search, pathname, year, media, visibility, load state"| def["First render uses the server-safe default, same on both sides"]
    kind -->|"e-mail address"| mail["First render uses an empty placeholder with reserved size"]
    kind -->|"observer or measurement"| eff["Set in an effect or external store after mount"]
    def --> after["After hydration the real value replaces the default"]
    mail --> after
    eff --> after
    classDef decision fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
    classDef act fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    class kind decision;
    class v,def,mail,eff act;
    class after ok;

Text alternative: every browser-dependent value starts from a default that equals the prerendered HTML (an empty placeholder for the e-mail address) and is replaced by the real value after hydration.

2. Rules

BR-BLD: Build and output

Id Rule Source
BR-BLD-01 pnpm build runs tsc, vite build, then node config/externalizeInlineScripts.ts, in that order. A failing step fails the build. The deployable output is dist/client; dist/server exists only during the build. FR-PR-17, 19, 20; services.md
BR-BLD-02 The prerendered pages are every key of sitePages plus the catch-all route rendered from path /404 to file 404.html. vite.config.ts derives the list from sitePages.ts; paths are never typed a second time. FR-PR-01, 03; D1, D5
BR-BLD-03 autoSubfolderIndex is false. File mapping is pageFile(path): / gives index.html, any other path gives its path without leading slash plus .html (/over-mij gives over-mij.html, /soorten-fotoshoots/newborn gives soorten-fotoshoots/newborn.html). pageFile lives in config/pageFiles.ts (pure) and is used by vite.config.ts, the runner and the preview server. FR-PR-16; D1
BR-BLD-04 Link crawling must not add pages beyond BR-BLD-02. The runner fails on any other .html file (UNEXPECTED_HTML). FR-PR-03
BR-BLD-05 Each page file has exactly one <title>, one description, one canonical, the Open Graph tags and JSON-LD of its route, and no element with data-fallback. <html lang="nl">, charset, viewport, favicon.png icon and apple-touch-icon links move from index.html to the root route (head() or the shell). index.html and src/main.tsx are removed. FR-PR-02
BR-BLD-06 /privacyverklaring keeps robots noindex through pageHead. 404.html has noindex too. Neither /404 nor /privacyverklaring is in the sitemap. FR-PR-04, 14
BR-BLD-07 The fonts stay imported (@fontsource/jost 300, 400, 500; @fontsource/marcellus 400) so that their CSS is a same-origin stylesheet link in the HTML. Chakra and Emotion styles are in the HTML (inline <style> is allowed by style-src 'unsafe-inline'); the first paint shows no unstyled content. NFR-PR-Q-04
BR-BLD-08 The Start plugin is not part of the Vitest configuration. @tanstack/router-plugin is replaced by Start's own generator; routeTree.gen.ts stays generated, committed and excluded from coverage. Route code splitting stays on. D12; NFR-PR-P-03
BR-BLD-09 sitemap.xml is emitted by sitemapPlugin in the client build only, so that it ends up in dist/client exactly once. The runner checks that the file exists and equals sitemapXml(pageList(sitePages), siteUrl) (SITEMAP_MISSING, SITEMAP_DIFFERS). FR-PR-04
BR-BLD-10 The CI job uploads web/dist/client/ as the build artifact so that later jobs receive index.html at the artifact root as today. Upload order and server rules are unit 3. FR-PR-17; unit boundaries
BR-BLD-11 New packages are in pnpm-lock.yaml and pass pnpm audit:deps. The seroval and seroval-plugins overrides in pnpm-workspace.yaml stay, and a scoped zod@4 override patches an advisory in Start's dependency tree (GHSA-mrhx-c7xc-m3w5). @tanstack/react-start and @tanstack/react-router are pinned to exact versions, because the script step depends on Start's output format. Packages no longer used (for instance @tanstack/router-plugin if Start replaces it) are removed. NFR-PR-SEC-02
BR-BLD-12 Header comments in inlineScripts.ts, externalizeInlineScripts.ts and previewServer.ts explain why the step exists (strict script-src 'self', Start emits inline scripts). The lines of this feature in _shared/reverse-engineering/ are updated (entry, build, output, test setup). NFR-PR-Q-05

BR-ENT: Entry, router and document

Id Rule Source
BR-ENT-01 getRouter() in src/router.tsx returns a new router per call with the options of main.tsx today: routeTree, scrollRestoration: true, defaultErrorComponent: ErrorPage. The options come from one shared function that renderApp also uses. FR-PR-07; D12
BR-ENT-02 The root route renders the document through shellComponent: <html lang="nl">, <head> with HeadContent, <body> with ChakraProvider value={system} around the children and Scripts last. The site stays light only. D6; main.tsx comment
BR-ENT-03 src/client.tsx calls startSentry() first and hydrates second, inside StrictMode as main.tsx does today. The server never imports it. FR-PR-08; D13
BR-ENT-04 Root notFoundComponent and errorComponent stay. ErrorPage shows no error text (BR-ERR-02/03 of the shell feature stay). FR-PR-07; NFR-PR-SEC-03
BR-ENT-05 A prerender error fails the build. No page is ever written from an error render. SECURITY-15
BR-ENT-06 Client navigation, scroll restoration, focus move on route change (useRouteFocus, not on first load and not on query or hash change) and /?pakket=...#contact anchors behave as today; the e2e tests cover each. FR-PR-07

BR-HYD: Hydration

Id Rule Source
BR-HYD-01 Principle: the first browser render produces the same markup as the prerendered HTML. Anything that depends on window, document, the URL search, hash or pathname, media queries, time, storage, observers or random values is applied after hydration. suppressHydrationWarning and typeof window branches in render are not used. FR-PR-05; D6
BR-HYD-02 useHydrated() is useSyncExternalStore(subscribeNoop, () => true, () => false). It returns false during prerender and during the hydrating render, true in the next render, and true from the first render of any component that mounts later (client navigation, tests with createRoot). D6
BR-HYD-03 Browser capabilities read by our own hooks go through useSyncExternalStore with a server snapshot equal to what the HTML shows. This keeps behaviour for components that mount after hydration (no extra render, existing tests unchanged) and needs no setState in an effect. D6
BR-HYD-04 usePageLoaded: store snapshot document.readyState === 'complete', subscribed to the window load event, server snapshot false. FR-PR-05
BR-HYD-05 useInView: the contract "without IntersectionObserver the element counts as in view" stays. unsupported is a store value (typeof IntersectionObserver === 'undefined', server snapshot false). inView = skip || intersected || unsupported. First render therefore returns skip on both sides; the observer is created in the effect as today. FR-PR-05
BR-HYD-06 useScrolledPast needs no change: it reads window only in its effect and starts at false. verified
BR-HYD-07 Chakra useMediaQuery and useBreakpointValue are called with the default ssr (true) everywhere. With ssr: false Chakra reads window.matchMedia in the useState initialiser, which throws during prerender and returns the real value in the first browser render. With the default, the first render returns fallback (none given, so false) for each query on both sides and an effect then sets the real values. Applies to useReveal, useHeroSlider, ContactSection, TestimonialCarousel and NavigationBar. No { ssr: false } remains in src. FR-PR-05
BR-HYD-08 First-render values: useMediaQuery(['(prefers-reduced-motion: reduce)']) gives false. NavigationBar useBreakpointValue({ base: false, lg: true }) gives false (its existing viewport dispatch in an effect applies the real value; the mobile and desktop layouts are CSS only). IntroGallery useBreakpointValue({ base: true, sm: false }) gives true (the base value), so the list carries tabIndex={0} in the HTML and loses it after hydration from sm up. FR-PR-05
BR-HYD-09 useHeroSlider: hidden is a store value (document.hidden, event visibilitychange, server snapshot false). document.hidden is no longer read in a useState initialiser. FR-PR-05
BR-HYD-10 routes/index.tsx, routes/contact.tsx and routes/portfolio.tsx: the search value passed to the page is hydrated ? search.pakket : undefined (portfolio: search.shoot). validateSearch is unchanged. Prerender and first browser render therefore both use "no search". FR-PR-06; D6
BR-HYD-11 After the search value takes effect the existing behaviour is unchanged. Contact page: the tidy effect (navigate({ to: '/contact', search: {}, replace: true })) runs when pakket becomes defined, so one render later than today on a direct load and at once on client navigation (hydrated is already true). Home: the ContactSection effect behaves the same, with the smooth scroll to #contact. Portfolio: onShootChange navigation (replace, resetScroll: false) is only reachable after hydration. FR-PR-06, 07
BR-HYD-12 On a direct load of /portfolio?shoot=gezin the HTML and first paint show all photos with filter "Alles"; the filter applies right after hydration (accepted consequence in the application design). PortfolioGallery closes the lightbox when the list changes (its listFor adjustment) and needs no change. FR-PR-06
BR-HYD-13 NotFound shows the two shoot-section buttons only when hydrated && isShootSectionPath(pathname). See BR-404. FR-PR-15
BR-HYD-14 Footer year: the first render uses BUILD_YEAR, a constant that vite.config.ts defines once per build (import.meta.env.VITE_BUILD_YEAR, the year of the build machine at build start) so that server and client bundles agree. After hydration the line uses new Date().getFullYear(). A page built in December therefore stays valid after new year without a rebuild. In tests (createRoot) the real year shows at once. FR-PR-05
BR-HYD-15 UmamiAnalytics reads its default hostname inside its effect, not in a default parameter evaluated during render. It renders null. FR-PR-08
BR-HYD-16 ContactForm shownAt = useState(() => Date.now()) is not rendered, and React state is not carried from server to client. The timer starts when the component first renders in the browser, which is when the form can first be used. A prerendered time can therefore never shorten the minimum fill time (MIN_FILL_MS). No change. FR-PR-05; BR-SPAM-01
BR-HYD-17 Prices come from formatPrice (Intl.NumberFormat('nl-NL'), whitespace replaced by a non-breaking space). Node and browser must produce identical text; the e2e hydration test on / and the shoot pages fails on a difference. FR-PR-05
BR-HYD-18 No render path uses Math.random, Date.now, new Date, counters or crypto for ids or text (verified: only BR-HYD-14 and BR-HYD-16). useId is not called in src; Chakra and Ark call it internally and are stable as long as both sides render the same tree, which BR-HYD-01 to 17 guarantee. FR-PR-05
BR-HYD-19 Effects that touch window or document (BackToTop, MobileNav, NavSubmenu, useDismiss, useRouteFocus, Hero, Lightbox, ContactForm) are safe and stay. Lightbox mounts only after a request, so its Portal is not part of the HTML. verified
BR-HYD-20 A hydration error is a defect. The e2e tests fail on any console error or warning (React error #418, #423, #425 and the like) on every page and variant listed in BR-TST-05. FR-PR-05; NFR-PR-Q-03
BR-HYD-21 Router Link computes its active state from the browser location in its first render. On /?pakket=gezin the book link of that package card (PriceCard: to="/" search={{ pakket }}) is active in the browser but not in the HTML, which differs only in attributes (aria-current, data-status, class). React's production build does not report attribute differences and the tidy navigation of ContactSection removes the search at once, so this is accepted; the link keeps its href with the search (it must work without JavaScript). The e2e tests run against the production build. If a React or Router upgrade starts reporting it, the card link must render without depending on the location. FR-PR-05, 06

BR-MAIL: The e-mail address

Owner decision: the address stays out of the HTML and the serialized data and appears after hydration.

Id Rule Source
BR-MAIL-01 The assembled address (user@domain) and any mailto: link to it exist only in the browser after hydration. No component outputs it in the first render. Components get it through useEmailAddress(email), which returns { available, address }: available is isEmailAddressValid(email) (same on both sides, no assembly); address is emailAddress(email) when hydrated && available, else null. FR-PR-22
BR-MAIL-02 Three states per slot. !available: nothing is rendered, as today (BR-EMAIL-02). available && address === null (before hydration): an empty placeholder that has the size of the real element, is aria-hidden="true", has no text, no href and no mailto, and carries data-email-pending. address !== null: the real element. FR-PR-22; NFR-PR-Q-04
BR-MAIL-03 Footer: the Contact column (title and list) is rendered before hydration whenever available, with one placeholder list item sized like FooterLink (minH 44 px below lg, one text line from lg). After hydration the item holds the link. Without the column the footer would grow at screen widths below lg, where the column wraps under the others. FR-PR-22
BR-MAIL-04 ContactDetails (contact page, twice): with available, the e-mail item is the first list item before hydration as a placeholder of minH 44 px, so the social items below it do not move. The card is only omitted when there is no channel at all (available false and no social). FR-PR-22
BR-MAIL-05 ContactFormGate: the notice sentence is "Het contactformulier komt binnenkort." before hydration. The part " Mail me voor nu op" with the address link and the button "Stuur een e-mail" appear after hydration. Before it, the notice reserves their space: the button is an aria-hidden, visibility: hidden placeholder with the button's own recipe and label, and the inline part is an aria-hidden, visibility: hidden inline block n characters wide (n = length of the address, computed from the parts without assembling it). As built, the block is as wide as the lead text plus the address: 38ch (20 + 18 characters; V10, to be measured in Step 34). The bottom margin depends on available, not on the address. FR-PR-22
BR-MAIL-06 ContactForm shows the address only in the failed state after a user action, so it is never in the first render. It also reads useEmailAddress so the address is not assembled during prerender at all. FR-PR-22
BR-MAIL-07 contactChannels(email, socials, assemble) gets a third parameter. With assemble false and valid parts the first channel is { kind: 'email-pending' } (no href, no label); with assemble true it is the existing email channel; with invalid parts there is none. ContactDetails passes hydrated. Social channels do not depend on it. FR-PR-22
BR-MAIL-08 lib/emailAddress.ts gets isEmailAddressValid(parts); emailAddress reuses it, so both agree. lib/ keeps its 100% thresholds: every new or changed function and branch in lib/ has tests. NFR-PR-Q-01
BR-MAIL-09 Without JavaScript the address never appears (FR-PR-11 exception). Unit 1 leaves the placeholders in a harmless state: nothing readable, nothing clickable. Unit 2 hides the bare "Contact" footer title without JavaScript (for instance by a <noscript> style on [data-email-pending] parents). FR-PR-11, 22
BR-MAIL-10 Build check (runner, code EMAIL_IN_OUTPUT): the assembled address, built from siteContent.email by emailAddress, must not occur in any text file in dist/client (HTML, JavaScript, CSS, XML, TXT, JSON), compared case-insensitively in these forms: plain, %40, @, \x40, &#64;, &#x40;, &commat;. This is stricter than FR-PR-22 (HTML only): the moved scripts hold the serialized data, and the bundle must stay free of it as today. If the parts are invalid there is no address and the check passes. FR-PR-22; NFR-PR-SEC-04
BR-MAIL-11 JSON-LD never contains the address (seo.ts comments already say so); the scan of BR-MAIL-10 covers it. NFR-PR-SEC-04

BR-404: Not found

Id Rule Source
BR-404-01 src/routes/$.tsx is a catch-all route whose component is NotFound. It renders normally; it never throws notFound() and never sets a status other than OK, because Start fails the build on a non-OK prerender. FR-PR-14; D5
BR-404-02 Start prerenders it from path /404 to 404.html. /404 is not in sitePages and not in the sitemap. FR-PR-14; BR-BLD-02
BR-404-03 404.html contains exactly one <title> ("Pagina niet gevonden | Andrea Slop Fotografie") and one <meta name="robots" content="noindex">. NotFound keeps rendering them itself (React 19 hoists them into <head>); the root head() has no title. FR-PR-14
BR-404-04 The page is rendered in the normal shell (navigation and footer) as today. Before hydration it shows one button, "Terug naar home". The two extra buttons under /soorten-fotoshoots/ appear after hydration. FR-PR-15; BR-HYD-13
BR-404-05 The first browser render on an unknown URL has the router pathname of the real URL, while the prerendered HTML was made for /404. Only NotFound renders from the pathname. The navigation compares exact, normalised strings with registered paths (isItemCurrent, isSectionCurrent, pathname === '/'), which are false for both. The router's Link is different: the desktop NavLinks and the MobileNav links use the default fuzzy matching, so on an unknown URL such as /over-mij/x the client would mark "Over mij" as current (aria-current, data-status, class) while the HTML has none. Therefore every navigation link (NavigationBar, MobileNav) gets activeOptions={{ exact: true, includeSearch: false }}, like NavSubmenu and MobileNavGroup already have. For real pages nothing changes, as no page has sub-paths except the shoot pages, which the submenu already handles exactly. No other component may render from the pathname on the catch-all page. FR-PR-15
BR-404-06 Client-side navigation to an unknown path renders the same catch-all route (no server round trip). FR-PR-07
BR-404-07 Known limit, for unit 3: a URL that the web server does not map but the client router does match (different letter case such as /Over-Mij, or a trailing slash) gets 404.html with a real page rendered in the browser. React recovers by client rendering and reports a hydration error. Unit 3 decides the URL rules (trailing slash, case) so that server and router agree. FR-PR-14, 16

BR-LZY: Lazy code and what the HTML contains

Id Rule Source
BR-LZY-01 ContactPanel / ContactForm on /contact (load="eager"): the form is in the first render on both sides, but the lazy chunk makes it a streamed Suspense segment: the HTML holds the form fields only as a hidden segment (<div hidden id="S:0">) at the end of the body, and the gate holds a placeholder box. React's completion script ($RC, moved to an external file by the script step) reveals the form inside the gate after the page loads (V8, corrected in Code Generation). On / (load="lazy") the first render shows the placeholder box (inView is false); the form is not in the HTML and loads when near or when ?pakket= applies. FR-PR-01, 05
BR-LZY-02 Testimonials: all visible testimonial texts and names are in the HTML for SEO. The carousel itself loads only after hydration and when near, as today. CarouselPlaceholder therefore renders every visible testimonial as a TestimonialSlide: the longest in the normal flow (it sets the height, as today), the others visually hidden with aria-hidden="true" and inert so assistive technology reads each review once, in the carousel. A single review has no placeholder and is in the HTML already. Alternative if the owner prefers one copy of the text: render the carousel in the first render (costs the lazy chunk, see BR-MEA). FR-PR-01; NFR-PR-S-02
BR-LZY-03 PortfolioGallery / Lightbox: lightboxRequested starts false, so the HTML has no lightbox. No change. FR-PR-05
BR-LZY-04 __root.tsx RouterDevtools: import.meta.env.DEV is false in the build, so it is () => null in both bundles and nothing reaches the HTML. In pnpm dev the lazy devtools under Suspense must not break server rendering. FR-PR-05
BR-LZY-05 A lazy component whose chunk is missing when React hydrates keeps the server HTML and hydrates later; it must not cause a mismatch. This is checked in the e2e test for /contact (BR-TST-05). FR-PR-05

BR-MON: Sentry and Umami

Id Rule Source
BR-MON-01 startSentry() runs only in client.tsx, before hydration. Shared modules have no import-time side effects (monitoring/sentry.ts has none; reportError is a no-op in state off). FR-PR-08; D13
BR-MON-02 Sentry starts only on the test and production hostnames (monitoringFor, unchanged). The build machine and the preview server on localhost start nothing. FR-PR-08
BR-MON-03 UmamiAnalytics adds its script in an effect, only on those hostnames, renders no markup and adds no script to the HTML. See BR-HYD-15. FR-PR-08
BR-MON-04 import.meta.env.VITE_RELEASE is set for the whole vite build (client bundle). The server bundle never initialises Sentry. FR-PR-08

BR-SCR: Script step

Pure functions in config/inlineScripts.ts, runner in config/externalizeInlineScripts.ts.

Id Rule Source
BR-SCR-01 externalizeInlineScripts(html) and findExecutableInlineScripts(html) use one scanner and one classification (flowchart 1.1), so the guard cannot disagree with the rewrite. No HTML parser dependency. FR-PR-19; D2
BR-SCR-02 Scanner. It reads the text left to right and recognises: comments (from <!-- to the first -->, or to the end if unterminated); <!...> and <?...> up to >; end tags up to >; start tags (name case-insensitive, attributes read with quotes so a > inside a quoted value does not end the tag). After the start tag of style, textarea, title, noscript, xmp, iframe, noembed or noframes the text up to the matching end tag (name followed by whitespace, / or >; or the end of the text) is skipped. A < not followed by a letter, /, ! or ? is text. Text in comments, style bodies and attribute values therefore never matches. FR-PR-19
BR-SCR-03 The body of a script element runs from the > of the start tag to the first </script followed by whitespace, / or > (case-insensitive); the end tag runs to its >. A script start tag without such an end tag is an error (UNTERMINATED_SCRIPT) in externalizeInlineScripts; findExecutableInlineScripts reports the rest of the text as its body. FR-PR-19; D2
BR-SCR-04 Executable means all of: no src attribute (present in any form, also empty or without value); a body that is not empty after trimming whitespace; type absent, empty, or after trimming and lower-casing one of application/javascript, application/ecmascript, application/x-ecmascript, application/x-javascript, text/javascript, text/javascript1.0 to text/javascript1.5, text/ecmascript, text/jscript, text/livescript, text/x-ecmascript, text/x-javascript, or module. Every other type (application/ld+json, application/json, importmap, speculationrules, unknown) is a data block and stays. The language attribute is ignored. FR-PR-19
BR-SCR-05 Unsupported executable forms throw (UNSUPPORTED_SCRIPT), so a Start change is noticed rather than silently changing behaviour: (a) a classic script with async or defer (an external file would run in another order); (b) a body containing <!-- (the browser's script-data escape states make the end of the script ambiguous); (c) a module body with a relative import specifier (from './...', import('../...')), which would resolve against /assets/ instead of the page. FR-PR-19, 20
BR-SCR-06 An executable script is replaced by <script + its original attribute text verbatim + src="/assets/inline-<hash>.js" + ></script>. All its attributes stay (type, data-*, id, class, nonce, and so on); only src is added. The element keeps its position, so the execution order (also relative to external scripts) is preserved. Scripts stay where Start puts them, at the end of the body. FR-PR-19; D4
BR-SCR-07 <hash> is the first 12 lowercase hex characters of the SHA-256 of the body, as UTF-8 bytes exactly as written in the document (no trimming, no newline or entity changes). The file content is that body in UTF-8, without BOM and without an added newline. D3
BR-SCR-08 The same body gives the same file name. moved lists each file once, in order of first appearance; file names in one result are unique. D3
BR-SCR-09 Everything outside the replaced script elements stays byte-identical, including comments, style bodies, data blocks, external scripts, whitespace and line endings. FR-PR-19
BR-SCR-10 Idempotence: externalizeInlineScripts(result.html).html equals result.html, with an empty moved. NFR-PR-Q-02
BR-SCR-11 findExecutableInlineScripts(externalizeInlineScripts(html).html) is empty. FR-PR-20
BR-SCR-12 Runner order: (1) read every .html file under clientDir (recursive, sorted); (2) plan in memory with no writes; (3) if the plan has violations, print them all and exit 1 without writing anything; (4) otherwise write the script files first and then the changed HTML files. planExternalization(files, context) is pure and exported for tests; the runner only reads and writes. FR-PR-20; SECURITY-15
BR-SCR-13 Runner violation NO_HTML: no .html file under clientDir. FR-PR-20
BR-SCR-14 Runner violation PAGE_MISSING: a path in sitePages has no file pageFile(path). All missing pages are listed. FR-PR-03
BR-SCR-15 Runner violation NOT_FOUND_PAGE_MISSING: 404.html is absent. FR-PR-14
BR-SCR-16 Runner violation UNEXPECTED_HTML: an .html file that is neither a page of BR-SCR-14 nor 404.html. BR-BLD-04
BR-SCR-17 Runner violation NO_SCRIPTS_MOVED: a page or 404.html whose final HTML references no /assets/inline-<12 hex>.js file. A file that was already processed counts, so running the runner twice is not an error. The minimum is one reference per page (the spike saw two: the bootstrap and the boundary script). FR-PR-20
BR-SCR-18 Runner violation EXECUTABLE_REMAINS: after the rewrite findExecutableInlineScripts still returns a body. Defence in depth; BR-SCR-11 says it cannot happen. FR-PR-20
BR-SCR-19 Runner violation COLLISION: assets/inline-<hash>.js exists with other content than the body. D3
BR-SCR-20 Runner violations from the other rules: UNTERMINATED_SCRIPT and UNSUPPORTED_SCRIPT (BR-SCR-03, 05), EMAIL_IN_OUTPUT (BR-MAIL-10), SITEMAP_MISSING and SITEMAP_DIFFERS (BR-BLD-09), SOURCE_MAP_PRESENT and BUILD_PATH_LEAK (BR-SEC). see rules
BR-SCR-21 Messages have the form <file>: <CODE>: <detail>. They name a file and a position, never print script bodies, and never print the assembled address. Success prints one line: pages checked, scripts moved, files written. Exit code 0 on success, 1 on any violation. NFR-PR-SEC-04
BR-SCR-22 Data blocks (JSON-LD from StructuredData and the route head() scripts) stay inline. The e2e test under the production CSP must show no violation for them; if one appears, FR-PR-19 is to be revisited, not worked around. FR-PR-19
BR-SCR-23 No preload or other hint is added for the moved scripts in unit 1; where they load is measured first (BR-MEA-03). NFR-PR-P-04; D4

BR-SEC: Output hygiene

Id Rule Source
BR-SEC-01 config/securityHeaders.ts is not changed in unit 1; its test keeps passing. The e2e tests and the preview server use securityHeaders('production'). NFR-PR-SEC-01
BR-SEC-02 No .map file in dist/client (SOURCE_MAP_PRESENT). NFR-PR-SEC-03
BR-SEC-03 No text file in dist/client contains the absolute path of the repository root in either slash style (BUILD_PATH_LEAK). NFR-PR-SEC-03
BR-SEC-04 Serialized data is public page data only. No loader, route context or server function is added in unit 1; the moved bootstrap scripts are scanned by BR-MAIL-10 and BR-SEC-03. NFR-PR-SEC-04
BR-SEC-05 Error pages show no internal details (BR-ENT-04). A failing prerender shows Start's message in the CI log only. NFR-PR-SEC-03
BR-SEC-06 StructuredData and structuredDataScript keep escaping <, > and & (jsonLdScript), so content can never close the script element. SECURITY-04, 11

BR-SRV: Preview server (unit 1 part)

Only what Lighthouse and the browser tests need. Trailing slash and /404 are final in unit 3 Infrastructure Design.

Id Rule Source
BR-SRV-01 resolveRequest(path, fileExists) takes the URL path without query or hash and returns { file, status } (file relative to clientDir, forward slashes, no leading slash). fileExists takes the same relative form. D10
BR-SRV-02 / gives index.html, status 200. FR-PR-16
BR-SRV-03 /x (last segment without a dot) gives pageFile('/x') with status 200 when that file exists. FR-PR-16
BR-SRV-04 A last segment with a dot is a file request: the file itself with 200 when it exists. D10
BR-SRV-05 Anything else gives 404.html with status 404. FR-PR-14
BR-SRV-06 The path is percent-decoded once. A path that fails to decode, contains a NUL or a backslash, or has a .. segment gives 404.html with 404. The returned file never contains .. and is never absolute, so it cannot leave clientDir (SECURITY-11 misuse case). NFR-PR-SEC-01
BR-SRV-07 Marked "final rule in unit 3 Infrastructure Design": a path with a trailing slash (interim: 404.html with 404, no redirect in unit 1, so { redirect } is not produced); the path /404 (interim: 404.html with status 404, not 200); /index and /index.html. FR-PR-16
BR-SRV-08 startPreviewServer(clientDir, port) answers GET and HEAD; other methods get 405. Every response, also 404, carries securityHeaders('production'). HTML responses send Cache-Control: no-cache. Text responses (HTML, JavaScript, CSS, SVG, JSON, XML, TXT) are gzip-compressed when the request accepts gzip, with Vary: Accept-Encoding, because the baseline ran on vite preview, which compresses; without this the measurements cannot be compared (found in Step 24: script transfer 667 kB versus 202 kB). The content type comes from the file extension (html, js, css, svg, png, jpg, webp, woff2, ico, xml, txt, json). It binds to 127.0.0.1. pnpm preview runs it with default port 4173, accepts the --port and --strictPort arguments that lighthouserc.cjs passes (or that command changes with it), and prints a line matching its startServerReadyPattern. NFR-PR-SEC-01; D10

BR-TST: Tests

Id Rule Source
BR-TST-01 renderApp builds its router from the shared options of BR-ENT-01, with a memory history, and renders RouterProvider inside ChakraProvider without <html>. The root route renders only its component in tests. Whether Router renders shellComponent itself is verified in code generation (see section 4). D12
BR-TST-02 The existing test files keep running. Changes are only where behaviour changed: first-render values after ssr removal are false until effects have run (wrap in act or waitFor); the footer year, usePageLoaded, useInView and useHeroSlider tests keep passing because components mounted by createRoot see the real value at once (BR-HYD-03). NFR-PR-Q-01
BR-TST-03 Vitest coverage thresholds stay as they are (100% for src/lib/**, src/seo.ts, src/sitemap.ts). config/** is reported, not thresholded, as today. NFR-PR-Q-01
BR-TST-04 Pure logic gets example-based tests and fast-check properties (section 3 of the business logic model), with the existing seed handling (testSeed.ts). NFR-PR-Q-02
BR-TST-05 e2e/ runs playwright-core with the Chromium of the Lighthouse job against the preview server on the built dist/client, in CI. Pages: all eleven, /404, /soorten-fotoshoots/onbekend, /onbekend, and the variants /?pakket=gezin#contact, /contact?pakket=gezin, /portfolio?shoot=gezin. Each must show: no console error or warning, no securitypolicyviolation, and for the variants the search value applied after hydration. Interaction checks: the mobile menu opens and closes, one client-side navigation works, the e-mail link appears only after hydration, focus moves to main after a client navigation but not on first load. NFR-PR-Q-03, SEC-01; FR-PR-05 to 08
BR-TST-06 A second set of checks needs no JavaScript: fetch of each page of sitePages and 404.html returns, in the raw HTML, the <title> of pageHead, exactly one <h1>, at least 40 visible characters in main outside the h1, a link to every mainNav and footerNav target, the canonical URL, the JSON-LD blocks, and no assembled e-mail address. The 40 characters is a floor that code generation may tune. NFR-PR-S-02; FR-PR-02, 22
BR-TST-07 A fast prerender-safety test with @vitest-environment node renders each route with react-dom/server and expects no throw, to catch window or document in a render path before a full build. The build's own prerender stays the authoritative check. Feasibility is verified in code generation. FR-PR-05

BR-MEA: Measurement and decision gate

Id Rule Source
BR-MEA-01 Before the first code change, on master c4c2f83: gzip size of the entry JavaScript and of all JavaScript on /, and mobile and desktop Lighthouse (performance, FCP, LCP, TBT, CLS) for every page of sitePages, median of three runs, with the same method and machine class as pnpm lighthouse. NFR-PR-P-03
BR-MEA-02 The same after unit 1, on the same machine. Both sets are shown to the owner side by side. If any entry is worse, the owner decides whether to continue before units 2 and 3 start. NFR-PR-P-03
BR-MEA-03 For NFR-PR-P-04 the report adds, per page, the number and gzip size of the moved script files and, for / and /over-mij, their request start and end relative to FCP and LCP. FCP or LCP later than the baseline goes to the same owner decision. NFR-PR-P-04
BR-MEA-04 CLS on / and /contact must not rise noticeably through the e-mail placeholders of BR-MAIL: it stays below 0.01 on both, mobile and desktop (the baseline on master is 0.0011 and 0.0009 on mobile, not exactly 0). A higher value is fixed with a better reserved size, not accepted. NFR-PR-Q-04
BR-MEA-05 Unit 1 leaves Reveal hidden in the HTML and has no photo preload, so its scores understate what units 2 and 3 can reach on pages whose largest paint sits inside Reveal. The report therefore adds a second measurement with Reveal temporarily visible by default, in an uncommitted local change, labelled as an indication. The owner decides with both in view. NFR-PR-P-03

3. What unit 1 leaves in a working state

Belongs to What unit 1 must leave
Unit 2 Reveal / useReveal Hydrates without mismatch. In the HTML, content is in its hidden state (data-reveal="hidden", as inView is false) and becomes visible after hydration, as in the SPA today. Text is in the HTML and in the raw-HTML test regardless of opacity. Unit 2 flips the default to visible (FR-PR-09).
Unit 2 DeferredImage Hydrates without mismatch: first render has no src on either side (pageLoaded and inView start false), photos load after hydration as today. The no-JavaScript image is unit 2.
Unit 2 NoScriptNav Not started. The mobile menu works with JavaScript as today.
Unit 2 photo preload Not started. pageHead stays as it is.
Unit 2 hero, carousel, form fallbacks The HTML contains the first hero slide image (the hero's loaded list starts with the active slide, which renders in the first render); testimonials per BR-LZY-02; the form per BR-LZY-01. Autoplay is on in the first render and stops after hydration for visitors with reduced motion.
Unit 3 servers dist/client is complete and correct for a server that maps /x to x.html and unknown URLs to 404.html with 404; the preview server proves it. nginx, IIS, upload order and Lighthouse targets are untouched.

4. To verify in code generation

Neither the code nor the spike settles these.

# Point Where it matters
V1 How the custom src/client.tsx hydrates with Start (entry API and file naming), and that startSentry() before hydration works. BR-ENT-03
V2 Whether RouterProvider in jsdom renders shellComponent (<html> cannot sit in the test container). If it does, renderApp creates the router from a variant of the root route without the shell. BR-TST-01
V3 The exact set of inline scripts per real page: Start's bootstrap and boundary, and any from router scroll restoration or from React for lazy boundaries ($RC-type completion scripts). They are moved like any other; check there is no <!--, no async/defer, no module with relative imports (BR-SCR-05). BR-SCR
V4 Whether the first real page keeps the minimum of one moved script (BR-SCR-17) or the runner should demand the two seen in the spike. BR-SCR-17
V5 That prerender of / really writes index.html with autoSubfolderIndex: false, and that link crawling is off or limited. BR-BLD-02, 04
V6 Start's plugin options for route code splitting (autoCodeSplitting equivalent) and whether @tanstack/router-plugin becomes unused. BR-BLD-08, 11
V7 Whether Vite's this.environment.name identifies the client build in sitemapPlugin.generateBundle (Vite 8), and that no sitemap.xml is left in public/. BR-BLD-09
V8 Lazy components in the HTML: that prerender waits for ContactForm on /contact (form fields in the HTML) and that React hydrates the boundary without a mismatch when the chunk arrives later. What the spike did not test. BR-LZY-01, 05
V9 Testimonials: that all review texts are in the HTML and that the visually hidden slides do not disturb layout, reading order or the axe test. BR-LZY-02
V10 Placeholder sizes for the footer item, contact card item and the gate notice: measured per breakpoint until CLS stays below 0.01. BR-MAIL-03 to 05, BR-MEA-04
V11 Exactly one <title> and one noindex robots meta in 404.html, and no duplicates on the normal pages, with React 19 hoisting inside Start's HeadContent. BR-404-03, BR-BLD-05
V12 No hydration error from the 404 page when its HTML (made for /404) is served for other URLs, with the real shell (navigation, footer) and not only the spike's simple pages. BR-404-05
V13 Whether Start's dehydrated state or any inline script contains a build timestamp (affects only the hash names, not correctness) or any build path (BR-SEC-03). BR-SEC
V14 useRouteFocus does not move focus on the first load with Start's router, and the contact page's tidy navigation keeps its scroll-to-top behaviour now that it runs one render later on a direct load. BR-ENT-06, BR-HYD-11
V15 Emotion/Chakra: no style flicker on real pages and no duplicate style insertion after hydration. BR-BLD-07
V16 Node and browser Intl.NumberFormat('nl-NL') give the same price text. BR-HYD-17
V17 No inline event-handler attributes (on*=) or javascript: URLs in Start's output (they are not scripts for the runner but the CSP blocks them). The e2e CSP check covers this. BR-SEC-01
V18 The CI artifact upload of web/dist/client/ keeps index.html at the artifact root for the existing deploy steps. BR-BLD-10