# Business Rules - Unit 2: Display fallbacks Rule ids are scoped to this feature and this unit. "Source" points at a requirement (FR/NFR), a design decision (D1 to D13 in [application-design.md](../../../inception/application-design/application-design.md)) or a unit 1 rule ([business-rules.md](../../start-migration/functional-design/business-rules.md)). Flows and evidence: [business-logic-model.md](business-logic-model.md). Components: [frontend-components.md](frontend-components.md). Data: [domain-entities.md](domain-entities.md). Groups: BR-RVL reveal, BR-IMG images, BR-NAV menu without JavaScript, BR-NJS other fallbacks, BR-PRE first-photo preload, BR-DMS measurement, BR-DTS tests. The choices that belonged to the owner (O1 to O5) were decided on 2026-10-31 and are recorded as final in section 5. Nothing in this unit is provisional. All statements marked "verified" were checked on 2026-10-31 against `web/src`, the built `web/dist/client` and a real Chrome (Playwright, local preview server) without changing any code. ## 1. Decision flowcharts ### 1.1 What `Reveal` does after hydration ```mermaid graph TD Start["Reveal mounted in the browser"] --> Support{"IntersectionObserver available and no reduced motion"} Support -->|"no"| Settled["Settled: visible, nothing to animate"] Support -->|"yes"| Measure["Layout effect: read top edge of the element"] Measure --> Below{"Top edge at or below the viewport bottom"} Below -->|"no"| Settled Below -->|"yes"| Hidden["Hidden: opacity 0, no transition"] Hidden --> Seen{"12 percent visible above the 60 px line"} Seen -->|"yes, once"| Revealed["Revealed: fades in with the delay"] classDef state fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef choice fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; class Settled,Hidden,Revealed state; class Start,Measure step; class Support,Below,Seen choice; ``` Text alternative: after hydration an element that is wholly below the viewport is hidden without a transition and fades in once on scroll; every other element stays visible. ### 1.2 Which markup a deferred photo gets ```mermaid graph TD Img["DeferredImage renders"] --> Pair["Image without src plus a noscript twin with src"] Pair --> Js{"JavaScript on"} Js -->|"yes"| Today["Twin is plain text to the parser: no request, no preload"] Today --> Load["After load and in view the effect sets src"] Js -->|"no"| Hide["CSS hides the empty image, the twin shows the photo"] classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef choice fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; classDef result fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; class Img,Pair step; class Js choice; class Today,Load,Hide result; ``` Text alternative: a deferred photo is rendered as an empty image plus a noscript twin; with JavaScript the twin is ignored, without it the CSS hides the empty image and shows the twin. ### 1.3 How a page gets its first-photo preload ```mermaid graph TD Photo["First photo of a page"] --> Plain{"A plain img with src and high priority"} Plain -->|"yes"| React["React hoists a preload link into the head"] Plain -->|"no, inside picture"| Explicit["Route head adds preloadImage with media"] Photo --> Hidden{"Hidden at some breakpoint"} Hidden -->|"yes"| Lazy["Image is lazy: no fetch, no preload there"] Photo --> Row{"Portfolio tile"} Row -->|"first row at this width"| Eager["Eager: source with media plus media preload"] Row -->|"later rows"| Deferred["Deferred: no preload, loads when near"] classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef choice fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; classDef result fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; class Photo step; class Plain,Hidden,Row choice; class React,Explicit,Lazy,Eager,Deferred result; ``` Text alternative: a plain high-priority photo is preloaded by React, a photo in a picture needs a media-bound link, hidden photos are lazy, and portfolio tiles of the first row are eager. ## 2. Rules ### BR-RVL: Reveal and `useReveal` | Id | Rule | Source | |---|---|---| | BR-RVL-01 | The first render of `Reveal`, on the server and in the browser, is visible: `data-reveal="visible"`, `opacity` 1, no transform, no transition. The prerendered HTML therefore shows all `Reveal` content, with and without JavaScript. | FR-PR-09, FR-PR-11; D7; BR-HYD-01 | | BR-RVL-02 | After hydration each `Reveal` decides in a `useLayoutEffect` whether to hide itself. The effect reads `element.getBoundingClientRect().top` and `window.innerHeight` and hides the element only when `top >= innerHeight`. A layout effect runs after the DOM commit and before the next paint, so hiding a below-the-fold element is never painted as a flash. All `Reveal`s of a commit read before any of them writes (state is set after the effects), so the reads cost one layout. React 19 does not warn for `useLayoutEffect` during prerendering (no such message in `react-dom-server.*.development.js`). | FR-PR-09; D6, D7 | | BR-RVL-03 | "In view at load" means: not wholly below the bottom edge of the viewport. This includes an element that is partly visible, one taller than the screen, and one above the viewport (scroll restoration, `#anchor` jump). The 60 px trigger margin is not part of this test: an element whose top sits in that band was painted from the HTML, and hiding it would make it disappear. | FR-PR-09 | | BR-RVL-04 | The hidden state is `opacity` 0 and `translateY(24px)` with `transition: none`. The change from settled to hidden therefore never animates. | FR-PR-09 | | BR-RVL-05 | The reveal trigger is unchanged: one `IntersectionObserver`, `threshold` 0.12, `rootMargin` `0px 0px -60px 0px`, disconnected after the first intersection. When it fires, the element becomes revealed: `opacity` 1, no transform, `transitionProperty` `opacity, transform`, duration token `reveal` (0.8 s), `smooth`, `transitionDelay` `${delay}s`. | FR-PR-09 ("as it does now") | | BR-RVL-06 | `delay` only matters for an element that was hidden and is revealed. Elements in view at load show at once, so a staggered row (`Pricing` cards, `PhotoMosaic` tiles) that is in view at load appears together. Rows revealed on scroll keep their stagger. | FR-PR-09 | | BR-RVL-07 | With `prefers-reduced-motion: reduce` nothing is hidden and no observer is created. The layout effect reads `window.matchMedia('(prefers-reduced-motion: reduce)').matches` itself: Chakra's `useMediaQuery` still holds its server-safe `false` while the layout effect runs (BR-HYD-07), and a late `true` would first hide and then animate. `useReveal` no longer calls `useMediaQuery`. In addition `Reveal` carries `_motionReduce` `{ opacity: 1, transform: 'none', transition: 'none' }`, so a preference that changes while elements are hidden shows them at once. | FR-PR-10 | | BR-RVL-08 | Without `IntersectionObserver` (old browsers, jsdom) the element stays settled and visible. | FR-PR-09; BR-HYD-05 | | BR-RVL-09 | The transitions are one-way: settled stays settled, hidden becomes revealed, revealed stays revealed. An element never goes back to hidden, also not when it scrolls out of view. The observer is disconnected on unmount. | FR-PR-09 | | BR-RVL-10 | **Decided (O1).** A `Reveal` that mounts after hydration (client navigation, the lazy testimonial and contact content) follows the same rules; there is no `useHydrated` branch. Content in view when the new page mounts appears at once, content below the viewport fades in on scroll. Reason: FR-PR-09 asks that content in view never waits for an animation, and the same rule on both paths is simpler to test and cannot diverge from the first load. Consequence: the entrance fade of the first screen on client navigation, which exists today, is dropped. Edge: the router scrolls to the top after the new page mounts, so on a navigation from a scrolled page, elements that end up below the fold after that scroll may already be settled and not fade. | FR-PR-09 | | BR-RVL-11 | `Reveal` keeps its props (`BoxProps` plus `delay`) and all 21 call sites stay as they are (list in [frontend-components.md § 4](frontend-components.md)). `useReveal()` returns `{ ref, visible, animated }`: `visible` is `false` only while hidden; `animated` is `true` only once revealed. `data-reveal` keeps the values `visible` and `hidden` that tests select on. | FR-PR-09 | | BR-RVL-12 | The decision is pure logic in `src/lib/revealPhase.ts`: `startsHidden(top, viewportHeight)` and `nextRevealPhase(phase, event)`. The hook only reads the DOM and calls them. `src/lib` has a 100 % coverage threshold. | NFR-PR-Q-01, Q-02 | | BR-RVL-13 | The existing trigger cannot reveal an element taller than `(innerHeight - 60) / 0.12` (6358 px at 823 px, 4833 px at 640 px, 4233 px at 568 px): the 12 % threshold is then never reached. Observed 2026-10-31: on `/portfolio` at 412 x 823 the grid wrapper (4537 px high, top at 377 px) stayed `hidden` for good until scrolled, although it was in view; the grid showed as an empty area under the filters. BR-RVL-03 removes this for elements that start in view. For an element that starts below the fold the limit stays. Code generation checks the tallest `Reveal` on every page at 320, 360 and 412 px wide (V-D6). | FR-PR-09 | | BR-RVL-14 | Anchors and scroll restoration are decided at hydration time, as today. `/?pakket=...#contact` and `/#prijzen` jump before hydration (the element exists in the HTML), so the target is in view and settled. Smooth scrolling to `#contact` after hydration passes hidden sections; they fade as they intersect, as now. A scroll position restored after hydration reveals content by scrolling, as now. | FR-PR-07, FR-PR-09 | ### BR-IMG: Images and `DeferredImage` | Id | Rule | Source | |---|---|---| | BR-IMG-01 | `DeferredImage` renders two siblings: the deferred `` exactly as today, and `