diff --git a/aidlc-docs/features/prerendering/audit.md b/aidlc-docs/features/prerendering/audit.md index 21e4b63..518497c 100644 --- a/aidlc-docs/features/prerendering/audit.md +++ b/aidlc-docs/features/prerendering/audit.md @@ -263,3 +263,27 @@ **Context**: Functional Design unit 2. Findings: the LCP on / stays at 4280 ms because of the bytes requested early, mainly the 224 KB hero photo, which this unit cannot change. --- + +## Functional Design - Unit 2 Answers + +**Timestamp**: 2026-10-31T23:40:00Z + +**User Input**: "Kan je de vragen hier sturen" (answers through the chat dialog: first question "Zelfde regel"; second question "Eerste rij meteen laden") + +**AI Response**: "Recorded Q1 A and Q2 B in display-fallbacks-fd-questions.md. Asked the design sub-agent to finalise O1 to O5 in the design." + +**Context**: Functional Design unit 2. + +--- + +## Functional Design - Unit 2 Approval Prompt + +**Timestamp**: 2026-10-31T23:55:00Z + +**User Input**: "(none: updated design reviewed by the main session)" + +**AI Response**: "Design finalised with O1 to O5. /portfolio: eager first row by column count with media-bound preloads, compared by measurement with the deferred variant (BR-DMS-05). Asked for approval." + +**Context**: Functional Design unit 2. Awaiting approval. + +--- diff --git a/aidlc-docs/features/prerendering/construction/display-fallbacks/functional-design/business-logic-model.md b/aidlc-docs/features/prerendering/construction/display-fallbacks/functional-design/business-logic-model.md index 008080f..d4dd640 100644 --- a/aidlc-docs/features/prerendering/construction/display-fallbacks/functional-design/business-logic-model.md +++ b/aidlc-docs/features/prerendering/construction/display-fallbacks/functional-design/business-logic-model.md @@ -57,7 +57,7 @@ Measured in Chrome at 412 x 823 on the built page, 2 s after load: the grid wrap ### 1.5 Client navigation -Option specified (provisional, O1): the same rule as on a first load; no `useHydrated` branch. +Option decided (O1): the same rule as on a first load; no `useHydrated` branch. - Why: FR-PR-09's reason is that visible content must never wait for an animation. One rule on both paths has no divergence to test, and the hydration rule (BR-HYD-01) is untouched. - What changes: today a page reached by client navigation fades in its first screen; after this unit its first screen is visible at once and only content below the fold fades on scroll. @@ -106,7 +106,8 @@ Text alternative: DeferredImage renders its deferred image and a noscript twin; |---|---|---| | `Hero` slide 1 | `src` present, `fetchPriority="high"` | Shown. Slides 2 and up are JavaScript only (BR-IMG-07). | | `IntroGallery` (4, `near` from its own observer) | No `src` | Twin shown. The phone row is a CSS scroll-snap list and keeps working. | -| `PortfolioGrid` (`eagerCount={0}`, so all deferred) | No `src` | Twins shown, all load at once. Tiles link to the large photo. | +| `PortfolioGrid` tile 1, and tiles 2 and 3 through `` (first row, BR-PRE-08) | Tile 1 has `src`; tiles 2 and 3 have a `` and no `src` | Tile 1 shown; tiles 2 and 3 shown through the twin (and the source, which loads the same URL). Tiles link to the large photo. | +| `PortfolioGrid` tiles 4 and up (deferred) | No `src` | Twins shown, all load at once. | | `InstagramGrid` | No `src` | Twins shown; tiles link to Instagram. | | `PhotoMosaic`, `PhotoDuo` | No `src` | Twins shown. | | `FramedImage` without `priority` (shoot pages, testimonials, `MediaText`) | No `src` | Twin shown. | @@ -196,7 +197,7 @@ Chrome 2026-10-31, `PerformanceObserver` `largest-contentful-paint`, last entry |---|---|---|---|---| | `/` | h1 text | h1 text | h1 text | Hero photo (React), logos | | `/over-mij` | `andrea-portret` | same | same | `andrea-portret` (React) | -| `/portfolio` | `f41a1916` (first tile) | `f41a1922` | `f41a7883` | None | +| `/portfolio` | `f41a1916` (first tile) | `f41a1922` | `f41a7883` | Today none. After this unit: tile 1 (React), tiles 2 and 3 with `media` 48em and 64em (BR-PRE-08 to 11) | | `/soorten-fotoshoots` | `newborn` | same | same | `newborn` (React) | | `newborn`, `zwangerschap`, `gezin`, `loveshoot`, `portret` | own photo | same | same | Own photo (React) | | `/contact` | intro text | intro text | `contact` (aside photo) | None for the aside; the 72 px portrait is preloaded at every width | @@ -206,7 +207,7 @@ The Lighthouse reports name the same elements (mobile: `/` the h1 span; over-mij ### 5.2 Decision flow -See flowchart 1.3 in the business rules. Result: nothing to add for seven of the eleven pages (React already preloads), one explicit link for `/contact` from `lg`, nothing for `/portfolio` (deferred by decision, different tile per width), nothing for `/privacyverklaring`. Two preloads are avoided by making their images lazy (the light logo off `/`, the contact portrait), because they are `display: none` where they are not used. +See flowchart 1.3 in the business rules. Result: nothing to add for seven of the eleven pages (React already preloads), one explicit link for `/contact` from `lg`, for `/portfolio` the first row of the grid: tile 1 by React, tiles 2 and 3 by two links bound to 48em and 64em (the largest paint is a different tile per width, always one of these), nothing for `/privacyverklaring`. Two preloads are avoided by making their images lazy (the light logo off `/`, the contact portrait), because they are `display: none` where they are not used. ## 6. Largest paint: what the reports show @@ -238,7 +239,7 @@ B shows what this unit achieves: it removes cause 1 (77 to 226 ms better than A, ### 6.3 `/portfolio` 3007 to 3607 ms with `Reveal` visible -In A the grid is hidden (BR-RVL-13 defect, section 1.4), so the largest paint is the intro paragraph at 55 ms, and the photos requested later (two requests at 194 ms, `DeferredImage` after the `load` event) are never candidates. In B the grid is visible, the first photo is the largest paint, and its real LCP is 197 ms. The simulator now includes everything requested up to 197 ms, among it those two photos (54 KB and 144 KB): +600 ms for +198 KB (3.0 ms per KB). The element changed from text to a photo; nothing got slower for the visitor, but the lab number did. This unit's design makes the grid visible (BR-RVL-03), so `/portfolio` is expected near B (score 0.90 against 0.94 in A). See O2. +In A the grid is hidden (BR-RVL-13 defect, section 1.4), so the largest paint is the intro paragraph at 55 ms, and the photos requested later (two requests at 194 ms, `DeferredImage` after the `load` event) are never candidates. In B the grid is visible, the first photo is the largest paint, and its real LCP is 197 ms. The simulator now includes everything requested up to 197 ms, among it those two photos (54 KB and 144 KB): +600 ms for +198 KB (3.0 ms per KB). The element changed from text to a photo; nothing got slower for the visitor, but the lab number did. This unit's design makes the grid visible (BR-RVL-03), so `/portfolio` is expected near B (score 0.90 against 0.94 in A) or, with the eager first row, somewhere else that is not measured yet. B had the photos deferred; the eager row requests tile 1 (54 KB at 412 px) with the scripts instead of at 194 ms, which could move the simulated LCP either way. The owner chose the eager first row (O2); BR-DMS-05 measures it against the deferred variant and reports to the owner if it is below 0.9 or below the deferred variant. ### 6.4 `/` stays at 4280 ms in both @@ -280,6 +281,8 @@ Properties extend the numbering of unit 1 (P1 to P17). fast-check runs in Vitest | P19 | `startsHidden` | Metamorphic (monotonic) | If an element with top `t` is hidden then every element with top `t' >= t` (same viewport) is hidden; shifting top and viewport height by the same amount does not change the result. | | P20 | `nextRevealPhase(phase, event)` | Invariant (state machine) | For any phase and any sequence of events the phase never returns from `revealed` to `hidden` or `settled`, and never goes from `settled` to `revealed` (BR-RVL-09). | | P21 | `nextRevealPhase` | Idempotence | Applying the same event twice gives the same result as once (StrictMode runs effects twice). | +| P24 | `firstRow(index, columns)` | Invariant | For any column map with increasing breakpoints and column counts and any tile index: the result is `'always'` exactly when `index` is smaller than the base column count, `null` exactly when it is not smaller than the largest column count, and otherwise `{ media }` of the first breakpoint whose column count exceeds `index`. | +| P25 | `firstRow` and `firstRowPreloads` | Metamorphic (monotonic) | If a tile is eager at some width it is eager at every wider width (the set of eager tiles only grows with the column count); and the number of tiles eager at a width equals the column count at that width. `firstRowPreloads(items)` has one link per tile with a `media`, none for `'always'` or `null` tiles, `href` equal to the tile thumb's `src`, and never more links than `max columns - base columns` (no duplicates). | | P22 | `preloadImage(image, options)` | Invariant | For any image and options, `href` equals `image.src`, `rel` is `preload`, `as` is `image`, `fetchPriority` is `high`, `media` is present exactly when given and equals it, and no other key exists. | The check that the CSS constant has no `|"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 --> Deferred{"Deliberately deferred"} - Deferred -->|"yes"| None["No preload, see BR-PRE-08"] + 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,Deferred choice; - class React,Explicit,Lazy,None result; + class Plain,Hidden,Row choice; + class React,Explicit,Lazy,Eager,Deferred result; ``` -Text alternative: a plain high-priority photo is preloaded by React itself, a photo in a picture element needs an explicit media-bound link, hidden photos are lazy and deferred photos get no preload. +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 @@ -87,7 +88,7 @@ Text alternative: a plain high-priority photo is preloaded by React itself, a ph | 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 | **Provisional.** 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-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 | @@ -120,7 +121,7 @@ Text alternative: a plain high-priority photo is preloaded by React itself, a ph | BR-NAV-06 | The shoot submenu is expanded without JavaScript: `#mobile-nav [id^="mobile-group-"] { grid-template-rows: 1fr; visibility: visible; transition: none }` always, not only on `:target` (selector weight 1,1,0 beats Emotion's single class). The chevron button of the group carries `data-requires-js` and is hidden. | FR-PR-12 | | BR-NAV-07 | Close link: `` with the existing text "Menu sluiten", as the first child of the panel's content, so it is the first Tab stop after opening. `#site-header` is the fixed `header`, which gets an `id` for this. A fragment navigation to a fixed element does not scroll: verified in Chrome with the page at `scrollY` 300, opening via `#mobile-nav` and closing via `#site-header` both left it at 300 (Firefox and Safari: V-D4). Rejected: `href="#"` (scrolls to the top of the page) and `href="#main"` (scrolls to the content). | FR-PR-12 | | BR-NAV-08 | Focus order without JavaScript: skip link, logo, open link; closed, the panel is `visibility: hidden`, so none of its links is focusable. After activating the open link the browser's sequential focus starting point is `#mobile-nav`, so the next Tab goes to the close link, then Home, Over mij, Portfolio, Soorten fotoshoots, Newborn, Zwangerschap, Gezin, Loveshoot, Portretten, Contact (verified, in that order). Both links get a visible focus ring (`:focus-visible` outline in the CSS). | FR-PR-12; WCAG 2.4.3, 2.4.7 | -| BR-NAV-09 | Desktop (from `lg`): all top-level links are in the header and work. The panel with the five shoot links is `visibility: hidden`, so by keyboard those links are unreachable, and the chevron button does nothing. **Provisional:** `[data-submenu]:focus-within > [data-submenu-panel] { visibility: visible; opacity: 1; transform: none; pointer-events: auto; transition: none }` opens it while focus is on the "Soorten fotoshoots" link or inside the panel, and the chevron is hidden (`data-requires-js`). `transition: none` is needed: the panel's `visibility` transition starts hidden, and a Tab pressed in the same frame skipped the panel (observed); with a 150 ms pause, Tab reached Newborn to Gezin in order. Mouse users click "Soorten fotoshoots", which opens the overview where each shoot has its "Lees meer" link; hover opening is not offered (the 0.75rem gap between link and panel would close it). | FR-PR-12; BR-NAV-21, 27 (earlier feature: no hover opening) | +| BR-NAV-09 | Desktop (from `lg`): all top-level links are in the header and work. The panel with the five shoot links is `visibility: hidden`, so by keyboard those links are unreachable, and the chevron button does nothing. **Decided (O3):** `[data-submenu]:focus-within > [data-submenu-panel] { visibility: visible; opacity: 1; transform: none; pointer-events: auto; transition: none }` opens it while focus is on the "Soorten fotoshoots" link or inside the panel, and the chevron is hidden (`data-requires-js`). `transition: none` is needed: the panel's `visibility` transition starts hidden, and a Tab pressed in the same frame skipped the panel (observed); with a 150 ms pause, Tab reached Newborn to Gezin in order. Mouse users click "Soorten fotoshoots", which opens the overview where each shoot has its "Lees meer" link; hover opening is not offered (the 0.75rem gap between link and panel would close it). | FR-PR-12; BR-NAV-21, 27 (earlier feature: no hover opening) | | BR-NAV-10 | The JavaScript menu stays as it is. The additions are `id="site-header"`, `data-requires-js` on the hamburger and the two chevron buttons, `data-submenu` on the submenu wrapper and `data-submenu-panel` on its panel, and the close link. With JavaScript these attributes do nothing (`noscript` content is not rendered). `useReducer`, ARIA and focus handling are not touched. | FR-PR-12; D9 | | BR-NAV-11 | Opening and closing add history entries (`#mobile-nav`, `#site-header`). Back from a page reached through the menu can return to the home page with the menu open. Accepted. | FR-PR-12 | | BR-NAV-12 | A visitor with JavaScript switched on whose script fails to load gets no `noscript` content, so the hamburger stays inert. That case is not covered by FR-PR-12 ("without JavaScript") and not by this design; the desktop links still work. | FR-PR-12 | @@ -132,7 +133,7 @@ Text alternative: a plain high-priority photo is preloaded by React itself, a ph | BR-NJS-01 | One marker, `data-requires-js`, means "no function without JavaScript". The no-JavaScript CSS hides it: `[data-requires-js] { display: none !important }`. `!important` is needed because style props set `display` on several of these elements, and Emotion's rules are unlayered single-class rules that come later in the document than the `head` CSS. Marked: the hamburger button, the two chevron buttons, `HeroArrows` buttons, `HeroPauseButton`, the hero progress bar, the `FilterBar` root, the testimonial controls spacer, the footer Contact column. | FR-PR-13 | | BR-NJS-02 | `[data-email-pending] { display: none !important }`: the e-mail placeholders (footer, contact card, gate sentence and gate button) stay in the HTML for layout during hydration, and are removed from layout without JavaScript, where the address never comes (FR-PR-22). The footer Contact column gets `data-requires-js` as well, so its title "Contact" does not stand alone (BR-MAIL-09). `FooterColumn` takes an optional prop to put the marker on its root. | FR-PR-22; BR-MAIL-09 | | BR-NJS-03 | Hero: slide 1 with its photo, h1, call to action and social links. The arrows, the pause button and the progress bar are hidden. The progress bar would otherwise run once and stop. The section keeps `aria-roledescription="carousel"`; a screen reader without JavaScript hears a carousel with one slide. Accepted. | FR-PR-13 | -| BR-NJS-04 | Testimonials: the placeholder shows the longest review (not necessarily the first) and keeps the other copies visually hidden, `aria-hidden` and `inert`, as unit 1 decided (BR-LZY-02) and as the browser test V9 asserts. The empty 48 px spacer for the carousel controls is hidden. **Provisional:** a visitor without JavaScript reads one review, not all. | FR-PR-13; BR-LZY-02 | +| BR-NJS-04 | Testimonials: the placeholder shows the longest review (not necessarily the first) and keeps the other copies visually hidden, `aria-hidden` and `inert`, as unit 1 decided (BR-LZY-02) and as the browser test V9 asserts. The empty 48 px spacer for the carousel controls is hidden. **Decided (O5):** a visitor without JavaScript reads one review, not all. | FR-PR-13; BR-LZY-02 | | BR-NJS-05 | Contact form: on `/contact` the form is a hidden streamed segment (`