Loads the light logo after the page load

Lazy loading saved its bytes during page load, but left the logo empty for a
moment when navigating to the homepage on a wide screen. Also adds the second
unit's code summary and the shared docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-01 01:56:13 +01:00
co-authored by Claude Opus 5.5
parent b965b8a227
commit b5fd83256d
14 changed files with 176 additions and 37 deletions
@@ -150,7 +150,7 @@ Text alternative: a plain high-priority photo is preloaded by React, a photo in
| BR-PRE-02 | Explicit links are only for images React cannot hoist. That is `/contact` from `lg`: the photo is a `<source media="(min-width: 64em)" srcSet>` in a `<picture>` and the `<img>` has a `data:` placeholder, so nothing is preloaded today and it is the largest paint at 1350 x 940. The contact route's `head()` adds `preloadImage(image, { media: ASIDE_MEDIA })`: `rel="preload"`, `as="image"`, `href` the hashed URL, `fetchPriority="high"`, `media="(min-width: 64em)"`. Below `lg` the media query keeps it from downloading. | FR-PR-21 |
| BR-PRE-03 | `preloadImage(image: ContentImage, options?: { media?: string }): HeadLink` is added to `seo.ts` (component-methods.md named it `preloadImage(src)`). It returns a plain object with `rel`, `as`, `href` (= `image.src`), `fetchPriority` and, only when given, `media`. `seo.ts` has a 100 % coverage threshold: examples and property P22 cover it. `pageHead` is not changed: passing every page's first photo to it would write the same preload twice (BR-PRE-04). The application design said pages pass their first photo to `pageHead`; the investigation shows React already does it. | FR-PR-21; D8 |
| BR-PRE-04 | A photo is declared once. A build test over all 12 HTML files asserts: every `preload as="image"` `href` occurs once; every page that has a `priority` photo has its preload; `/contact` has the `media` link and no other link for that file; `/portfolio` has React's link for tile 1 and exactly two `media` links (48em and 64em) for tiles 2 and 3. This also catches a React upgrade that changes the hoisting. | FR-PR-21; NFR-PR-Q-01 |
| BR-PRE-05 | Nothing is preloaded that is not shown. Measured on `dist/client`: every page preloads both logos, `/contact` preloads the 72 px portrait (5 KB) that is `display: none` from `lg`. Fixes, both by `loading="lazy"` (a lazy image is neither fetched while `display: none` nor hoisted by React): the contact page's narrow portrait; the light logo on every page except `/` (on those pages the header is never transparent, so the light logo is never shown). `NavigationBar` knows `isHome` from the pathname in its first render, which is the same on the server and in the browser (the prerendered 404 has `/404`, never `/`). On `/` both logos stay eager, because both are shown in some state (dark below `lg` and after scrolling 150 px, light over the hero from `lg`). The light logo is 25 KB, about 140 ms of simulated LCP at the Lighthouse throttle on ten pages (estimate from the 5.4 ms per KB slope in the business logic model, to be measured). Verified in Chrome on the built `/over-mij`: with `loading="lazy"` on the light logo and its preload link removed, only the dark logo is requested. **Decided (O4);** the effect on score and LCP is measured (BR-DMS-03, V-D7). | FR-PR-21; NFR-PR-P-01 |
| BR-PRE-05 | Nothing is preloaded that is not shown. Measured on `dist/client`: every page preloads both logos, `/contact` preloads the 72 px portrait (5 KB) that is `display: none` from `lg`. Fixes, both by `loading="lazy"` (a lazy image is neither fetched while `display: none` nor hoisted by React): the contact page's narrow portrait; the light logo on every page except `/` (on those pages the header is never transparent, so the light logo is never shown). `NavigationBar` knows `isHome` from the pathname in its first render, which is the same on the server and in the browser (the prerendered 404 has `/404`, never `/`). On `/` both logos stay eager, because both are shown in some state (dark below `lg` and after scrolling 150 px, light over the hero from `lg`). The light logo is 25 KB, about 140 ms of simulated LCP at the Lighthouse throttle on ten pages (estimate from the 5.4 ms per KB slope in the business logic model, to be measured). Verified in Chrome on the built `/over-mij`: with `loading="lazy"` on the light logo and its preload link removed, only the dark logo is requested. **Amended after the measurement (V-D7):** the light logo is lazy only until the page has loaded (`loading` is `lazy` while `!isHome && !pageLoaded`, `usePageLoaded`; the first render still equals the HTML). A lazy `display: none` image is not fetched until it is shown, so it flashed on a client navigation to `/`; after `load` it is fetched, so it is ready. A navigation before `load` may still flash briefly (accepted). **Decided (O4);** the effect on score and LCP is measured (BR-DMS-03, V-D7). | FR-PR-21; NFR-PR-P-01 |
| BR-PRE-06 | Largest paint per page and screen size, measured in Chrome 2026-10-31 at 412 x 823, 768 x 1024 and 1350 x 940 (unthrottled, Reveal forced visible to simulate this unit) and checked against the Lighthouse reports: `/`: the h1 text at every size (the hero photo is never reported, probably because it covers the whole viewport; not confirmed); `/over-mij`, `/soorten-fotoshoots` and the five shoot pages: their `priority` photo at every size; `/contact`: the intro text below `lg`, the aside photo from `lg`; `/portfolio`: a grid photo at every size once the grid is visible (a different tile per width, always one of the first-row tiles); `/privacyverklaring` and the 404 page: text or the footer logo. Table with names: [domain-entities.md § 6](domain-entities.md). | FR-PR-21 |
| BR-PRE-07 | The hero photo on `/` keeps its React-written preload with `fetchPriority="high"` although the largest paint there is text: it is the first thing a visitor sees. No explicit link is added. | FR-PR-21 |
| BR-PRE-08 | **The first row of the portfolio grid is eager and preloaded** (O2, final; FR-PR-21 has no exception for `/portfolio`). "First row" is a number of tiles that depends on the column count, which is CSS only (`base` 1 column, `md` from 48em 2 columns, `lg` from 64em 3 columns, the values `PortfolioGrid` uses for `gridTemplateColumns`; the build does not know the width). The grid places tiles row by row in reading order of the unfiltered list, so tile 1 is in the first row at every width, tile 2 from `md`, tile 3 from `lg` (probe: at 320 to 640 px only tile 1 starts in the first screen, at 768 to 1023 px tiles 1 and 2 form the first row, from 1024 px tiles 1 to 3). Tiles 4 and up stay deferred (`DeferredImage`, loaded after the `load` event when near); on a screen taller than one row, such as 768 x 1024 where tiles 3 and 4 start inside the screen, they are not eager either: "first row" is a column count, not a screen height. The rule is pure logic in `src/lib/firstRow.ts`: `firstRow(index, columns)` returns `'always'`, `{ media }` (the `min-width` query of the first breakpoint whose column count exceeds the index) or `null`. `PortfolioGrid`'s `eagerCount` prop (default 3) is replaced by `eagerFirstRow` (default `true`), and `PortfolioGallery` stops passing 0. History: the shared `PortfolioGrid` has had `eagerCount` (default 3, "the first row on desktop") since commit 18bf031; `PortfolioGallery` set it to 0 in 9efa7fc (2026-10-27) after measuring 0.80 eager against 0.91 deferred on mobile, when the grid faded in and its photos could never be the largest paint. That reason no longer holds for a grid in view (BR-RVL-03), the owner chose FR-PR-21 literally, and BR-DMS-05 re-checks the old result. The comment in `PortfolioGallery` ("No photo loads before the page has: the grid fades in, so its photos are never the largest paint, ... decision 2026-10-27") is replaced by: the first row loads eagerly, with preloads, because it is in view and is the largest paint; later rows wait for the page and for proximity; the 2026-10-27 measurement is repeated in BR-DMS-05. | FR-PR-21; decision 2026-10-27 (superseded) |