@smi-digital/create-smi-app 2.14.1 → 2.15.0

package/templates/integrations/strapi-astro/docs/performance-why.md.template

@@ -0,0 +1,780 @@
+# Performance rules
+
+Rules for every SMI website project (Astro + Strapi). Written for both humans and
+agents. Ordered by **decision point** — the question you are actually facing —
+rather than by topic.
+
+**This is the long form — every rule with the reason it exists and the mistake it
+prevents.** The rules themselves, one line each, are in
+**[PERFORMANCE.md](./PERFORMANCE.md)**. Read that one every session; come here when a
+rule bites, when you want to argue with one, or when you need to apply one to a case it
+does not literally cover. Rule numbers match exactly in both directions.
+
+Enforcement tags: `[scaffold]` `[web-kit]` `[eslint]` `[ci]` `[review]`
+A rule tagged `[review]` is currently unenforced and depends on a human noticing.
+
+**The summary:** weight is almost all of it, and almost every fix below already
+exists somewhere in the codebase. The knowledge is rarely missing. It just is not
+the default.
+
+---
+
+## 0. Budgets
+
+Numbers, so the rules can be checked rather than argued about. Measured on a
+mobile Lighthouse run, per page.
+
+| Budget | Limit |
+|---|---|
+| Total page weight | **≤ 1 MB** |
+| All fonts on one page | **≤ 400 KB** |
+| Any single font file | **≤ 100 KB** |
+| Any single image | **≤ 200 KB** |
+| JS on a marketing page | **0 framework bytes** |
+| CSS per page | **≤ 15 KB** |
+| `priority` images per page | **exactly 1** |
+| LCP · TBT · CLS | **< 2.5 s · < 200 ms · < 0.1** |
+
+---
+
+## 1. Images
+
+### The decision: "I need to put an image on the page"
+
+There are three answers, and the third needs a reason in writing.
+
+| Where the image comes from | What you use |
+|---|---|
+| **Strapi** (any CMS media object) | `<CmsImage media sizes />` `[web-kit]` |
+| **Strapi + a local fallback** | `<CmsImage media fallback sizes />` `[web-kit]` |
+| **A local file you `import`** | `<Image />` from `astro:assets` |
+| An icon or vector shape | inline SVG — not an image at all |
+| CMS rich-text content | the renderer maps `img` → `<CmsImage>` |
+| **Genuinely none of the above** | raw `<img>` **+ a comment saying why** |
+
+**1.1 Every CMS image goes through `<CmsImage>`. Every local image goes through
+`<Image>`.** `[web-kit]` `[eslint]`
+
+Not "should", and not "unless the props are awkward". These two components are the
+only places where the eight things an image needs are correct by construction:
+format negotiation, a complete derivative ladder, `sizes`, `width`/`height`,
+loading strategy, decoding, priority, and the CMS origin.
+
+If `<CmsImage>`'s props do not fit a call site, that is a signal to **extend the
+shared component** (§7), not to write your own. A second implementation of image
+selection inside a site repo is a defect even when it is correct today, because it
+will diverge.
+
+**1.2 A raw `<img>` requires a comment explaining why nothing else was possible.**
+`[eslint]` `[review]`
+
+The comment is the point. It makes the exception reviewable, and it forces you to
+articulate a reason — which is usually where you discover there is not one.
+
+```astro
+<!-- Raw <img>: <reason nothing else works> -->
+<img src={…} width={…} height={…} sizes={…} srcset={…} loading="lazy" decoding="async" />
+```
+
+A raw `<img>` is banned not because it is wrong but because it is **incomplete by
+default**. It renders perfectly with zero attributes and never fails loudly, so it
+is only ever correct if someone remembers everything, every time.
+
+**1.3 `<Image src={x} />`, never `<img src={x.src} />`.** `[eslint]`
+
+These look nearly identical. The first is Astro's optimiser: resize, modern format,
+`width`/`height`, hashed filename. The second is the raw file with a hashed name and
+no processing at all.
+
+**1.4 `sizes` is required, and it describes the CSS box — not the image.**
+`[web-kit]`
+
+The browser chooses which file to download *before* it has laid out the page, so it
+cannot measure the box. You measure it for it. Omit `sizes` and the browser assumes
+`100vw` and takes the largest candidate — a perfect `srcset`, silently defeated.
+
+**1.5 Always emit `width` and `height`** from the media metadata. `[web-kit]`
+Free layout-shift protection; the numbers are already in the object.
+
+**1.6 Lazy by default. Exactly one `priority` image per page, and it must be the
+LCP.** `[web-kit]` `[review]`
+
+`loading="lazy"` + `decoding="async"` are the defaults. The single exception gets
+`priority`, which sets `loading="eager"` + `fetchpriority="high"`. One prop, so it is
+greppable and countable. Three separate attributes are not.
+
+The budget is on `priority`, not on eagerness: eager loading and high fetch priority
+are separate decisions, and 1.8 is the case for taking one without the other.
+
+**1.7 `fetchpriority="high"` is for the LCP element only. Never a logo.** `[review]`
+Prioritising the wrong image actively delays the right one.
+
+**1.8 There is a third state: eager but not urgent.** `[review]`
+
+An image that must be ready before the visitor reaches it, but must not compete with
+the LCP, is `loading="eager"` + `fetchpriority="low"`. The usual case is the first
+frame of a sticky or morphing section: pre-loaded so it never starts blank, explicitly
+deprioritised so it does not race the hero.
+
+This is not `priority` and does not spend the budget in 1.6. Eager answers *when* the
+fetch starts; fetch priority answers *what it is worth* once started. There is exactly
+one image on the page worth more than the LCP — none.
+
+**1.9 `loading="lazy"` is about layout position, not visibility.** `[review]`
+
+**Any layout that shows one of N things in the same box owns its own loading
+schedule.** Carousels, sliders, tabs, before/after comparisons, morphing sections.
+Hide an element with `clip-path`, `opacity` or `visibility` and it has not moved —
+the browser still counts it as on-screen and fetches it. Several full-screen images
+stacked in one sticky box all download at once, however they are marked.
+
+Load them yourself, one step ahead of when each becomes visible, from the scroll
+handler you already have.
+
+**1.10 Never upscale.** `[review]`
+If the display size exceeds the source, get a bigger source — or ask whether it
+should be a raster image at all. A "curve background" is an SVG or a CSS shape.
+
+**1.11 Optimise before committing. Source files are not build artifacts.** `[ci]`
+
+**1.12 Rich-text renderers must map `img` → `<CmsImage>`.** `[review]`
+CMS-authored markup arrives at runtime, so `[eslint]` cannot see it. `react-markdown`
+takes a `components` override. `set:html` has no such hook — know that gap exists
+rather than assuming lint covers it.
+
+### `<picture>` selection semantics
+
+**1.13 A browser commits to the first `<source>` type it supports and never falls
+through.** `[web-kit]`
+
+There is no "try AVIF, fall back to WebP if the file is missing". The browser picks a
+*format group* on the first supported `type`, then selects a width **within that
+group only**. The `<img>` is reached solely by browsers that support none of the
+sources.
+
+Three consequences:
+
+- **Every format needs a COMPLETE width ladder.** A partial AVIF ladder hands a phone
+  a desktop-sized file rather than falling through to a small WebP.
+- **Every ladder needs a rung at source resolution** (a `full` rung). Without it, a
+  browser that committed to AVIF can never reach full quality however large the
+  original is, while the original sits unread on the `<img>`.
+- **`sizes` goes on every `<source>`, not just the `<img>`.** A `<source>` without it
+  ignores its own srcset widths.
+
+**1.14 Group derivatives by their `mime`, not by key name.** `[web-kit]`
+Strapi stores a mime per derivative. Grouping on it means the upload pipeline can name
+its keys however it likes, and stock-Strapi media and pipeline media resolve through
+one code path with no branching.
+
+**1.15 `picture { display: contents }` in the global reset.** `[scaffold]`
+Wrapping an `<img>` in a `<picture>` inserts a box into layouts that expected the
+`<img>` to be the direct child — absolutely-positioned images, flex and grid children.
+`display: contents` keeps the wrapper out of layout entirely.
+
+### Strapi upload pipeline
+
+**1.16 The derivative ladder must reach your largest display size.** `[scaffold]`
+
+Stock Strapi tops out at **1000px**. A full-bleed hero on a 1440px 2× screen needs
+~2880px. With no rung that high the only candidate is the untouched original, which is
+how camera JPEGs end up in hero slots.
+
+```ts
+// backend/config/plugins.ts
+upload: {
+  config: {
+    breakpoints: { xsmall: 320, small: 640, medium: 1024, large: 1600, xlarge: 2400 },
+  },
+},
+```
+
+**1.17 Convert format at upload, not at request.** `[scaffold]`
+
+Strapi resizes but does **not** convert — JPEG in, JPEG out. Without a conversion step
+the delivered format is decided by whatever the editor happened to drag in.
+
+Add a sharp-based override on the upload plugin's `image-manipulation` service that
+emits a complete AVIF + WebP ladder (1.13) and caps the stored original. Never ask a
+client to export WebP.
+
+**1.18 Re-processing existing media is a required step, not a caveat.**
+`[scaffold]` `[review]`
+
+Strapi only runs the pipeline **on upload**. Adding it improves nothing already in the
+library; until existing media is re-processed the change is inert.
+
+Ship the pipeline together with a re-processing script, and make that script **walk
+the whole library by default**. Requiring the caller to advance an `offset` is a trap:
+a re-run over already-processed files reports them as `skipped` and exits
+successfully, so a partial conversion is indistinguishable from a complete one.
+
+The script must be dry-run by default, idempotent, batched (image encoding is
+CPU-heavy and runs inside the live container), and preceded by a database **and**
+uploads backup.
+
+**1.19 Do not compensate in the frontend for media the pipeline has not processed.**
+`[review]`
+
+The temptation is to withhold an oversized original from the srcset so the browser
+picks a smaller derivative. It buys nothing and costs quality:
+
+- On a **processed** image, modern-format sources exist, so the original is never
+  downloaded anyway (1.13) — withholding it changes nothing.
+- On an **unprocessed** image, the original is the only path to full resolution.
+  Withholding it caps the image at the stock 1000px ladder, visibly soft on any
+  screen wider than that.
+
+Dead weight in the good case, a regression in the bad one. Process the image.
+
+### Format guide
+
+| Format | Use for |
+|---|---|
+| **AVIF** | photos, gradients (~50% under JPEG) |
+| **WebP** | same, safer fallback (~30% under JPEG) |
+| **JPEG** | photos, no transparency |
+| **PNG** | flat-colour graphics only — often *larger* than JPEG for photos |
+| **SVG** | shapes, logos, icons |
+
+---
+
+## 2. Fonts
+
+**2.1 No icon fonts. Ever. Inline SVG.** `[scaffold]` `[review]`
+
+This single rule is worth more than everything else in this document. A full icon
+font runs from hundreds of KB to several MB; the handful of glyphs a site actually
+uses are ~2 KB as inline SVG.
+
+Icon fonts also fail visibly, not just slowly. Ligature-based sets render the
+**literal ligature text** while the font is pending under `font-display: swap`, so
+visitors see the words "download" or "expand_more" at icon size for the whole load.
+
+If you find a workaround mapping icon names to literal glyphs, that is the symptom.
+Remove the font.
+
+**2.2 Never download a font file by hand when Fontsource has it.** `[scaffold]`
+
+```
+npm i @fontsource-variable/<family>
+```
+
+Self-hosting is correct — it is the GDPR position and it does not change. But Google
+Fonts was never only a CDN; it was also a **subsetting service**. Take the source file
+from a repo and you inherit every script on earth: a full-charset weight is ~60 KB
+where the Latin slice is ~16 KB, and that multiplies by every weight you declare.
+
+Fontsource files install into `node_modules`, are bundled by Vite, and are served from
+your own domain. Renovate version-manages them. Nothing reaches Google.
+
+**2.3 Import font CSS in `Layout.astro` frontmatter, not in SCSS.** `[review]`
+Sass runs before Vite and cannot resolve bare package names.
+
+**2.4 Subsetting: prefer `unicode-range` slices.** `[review]`
+
+`unicode-range` is the safe default because content is editor-controlled: the extended
+slice is fetched only when such a character appears, so a pasted Polish name or a `€`
+still renders. A single hard-subset file renders tofu instead.
+
+Hard-subsetting a licensed face that ships far more than the site needs is legitimate,
+but it has a procedure and it is one-way — see **Appendix B**.
+
+**Check the licence first.** Many commercial EULAs forbid modification, and subsetting
+*is* modification.
+
+**2.5 Declare only the weights you use.** `[review]`
+A declared-but-unused `@font-face` does not download, but it is a standing invitation
+— and it is weight in git, slowing every clone and Docker build.
+
+**2.6 Five or more weights → variable font. Two or three → statics.** `[review]`
+Pick one strategy per family.
+
+**2.7 Preload only the weights that render above the fold — verified by looking.**
+`[review]`
+Preloading a weight you do not use above the fold is strictly negative: it competes
+with the ones you do. A variable font dissolves this problem — one file covers every
+weight, so there is exactly one thing to preload and it is always right.
+
+**2.8 woff2 only. `font-display: swap` always.**
+
+**2.9 `font-display: swap` protects rendering, not bandwidth.** `[review]`
+
+This is why fonts go unnoticed. `swap` stops a font blocking first paint — it does
+**not** stop the download competing for the connection. A healthy FCP alongside a
+terrible LCP is the signature: the font never blocked the paint, it ate the pipe, and
+the images behind it arrived late.
+
+**2.10 A custom or licensed face has failure modes a Fontsource package does not.**
+`[review]`
+
+If you are subsetting one, trimming baselines against its metrics, or rasterising its
+text into a canvas, read **Appendix B** before starting. Each of those has a way to
+look correct and be silently wrong, and none of them is reachable by lint.
+
+---
+
+## 3. JavaScript & hydration
+
+### Before creating an island
+
+**3.1 Prefer the platform.** `[review]`
+`<details>`/`<summary>` for accordions. `<dialog>` for modals. CSS `:hover` /
+`:focus-within` for dropdowns. CSS transitions for reveals. Platform features work
+*before* hydration, are keyboard-accessible by default, and cost nothing.
+
+**3.2 Never re-implement in JavaScript what CSS does natively.** `[review]`
+Especially breakpoints. It duplicates a media query, adds a resize listener, and causes
+a flash — the server renders one state and JS corrects it after hydration.
+
+**3.3 The three-question test.** `[review]`
+- Does it need state that survives across interactions?
+- Does it need to re-render from changing data?
+- Would writing it without a framework genuinely be worse?
+
+**All three "no" means it is not an island.**
+
+### Where a framework is allowed
+
+**3.4 Marketing pages target zero islands.** `[review]`
+Astro ships framework JS **per page**. A page with no islands ships no framework at
+all — so the first trivial island is the most expensive thing on a marketing page: the
+entire client runtime arrives before a line of your own code does. A menu toggle is
+enough to pay it in full.
+
+**The number, and what it is attached to.** ~184 KB raw / ~67 KB brotli is
+`react` + `react-dom` **19.2** via `@astrojs/react` **6** on **Astro 7** — the fleet
+default as of August 2026.
+
+That figure is not portable. It does not hold for Preact, Svelte or Solid, it will not
+hold across a React major, and quoting it after either has changed is how a true rule
+acquires a false number. Re-measure in the project you are actually in:
+
+```bash
+npm run build
+ls -lS dist/_astro/*.js | head    # the framework chunks are the large ones
+```
+
+What survives the re-measure is the shape of the rule, which does not depend on the
+figure: **the first island pays a fixed runtime cost that the second one does not.**
+
+**3.5 Tool and app pages may use a framework freely.**
+Multi-step forms, generators, anything where the page *is* the application.
+
+**3.6 Adding an island to a page that had none is a bigger change than it looks.**
+Say so in the PR description. `[review]`
+
+### How it hydrates
+
+**3.7 `client:visible` is the default. `client:load` needs a written justification.**
+`[review]`
+
+**3.8 Use `client:media` for anything that exists at only one breakpoint or
+capability.** `[review]`
+`client:media="(max-width: 767px)"` is never downloaded, parsed or executed on desktop.
+The same applies to capability: an effect requiring `(hover: hover) and (pointer: fine)`
+should be gated on it rather than hydrating on a phone to discover it has nothing to do.
+
+**3.9 `client:only` is a last resort, and never above the fold.** `[review]`
+It skips server rendering entirely: a hole in the HTML, a jump when it fills, nothing
+for crawlers.
+
+**3.10 An island can only be as lazy as its most urgent job.** `[review]`
+One island holding several pieces of state doing several jobs must hydrate for the most
+urgent of them, and everything else ships as collateral.
+
+### Shape
+
+**3.11 Islands are leaves, not trunks.** `[review]`
+If an island wraps a large subtree, *all of it* becomes JavaScript — including the
+static text. Keep the section as `.astro`; make the interactive control the island.
+
+**3.12 One island, one job.** A component that needs splitting to be lazy was always
+two components.
+
+### Never
+
+**3.13 Never gate visible content behind an async operation.** `[review]`
+Server-render the markup; let JavaScript decide only whether to *show* it. An element
+that cannot paint until a promise resolves cannot be the LCP, so something else — often
+something you did not want — becomes it instead.
+
+**3.14 Never duplicate a decision already made server-side or in an inline script.**
+`[review]`
+The later copy loses a race it should not be running.
+
+### Dependencies
+
+**3.15 No unused or duplicate dependencies.** `[ci]`
+Two markdown renderers, or a component library imported in zero files, are both common
+and both invisible without a check.
+
+**3.16 Delete dead islands.** `[ci]`
+
+---
+
+## 4. CSS
+
+### What ships
+
+**4.1 A dynamic block renderer must import blocks dynamically.** `[review]`
+CSS follows the **import graph**, not the render output. A static import bundles the
+styles whether or not the component renders, so a page rendering three sections
+downloads the CSS for all of them.
+
+**4.2 Adding a section type must not make every existing page heavier.** `[review]`
+If it does, the architecture is wrong regardless of today's numbers.
+
+**4.3 Co-located CSS modules only pay off if the imports are per-page.** `[review]`
+
+### Delivery
+
+**4.4 Below-the-fold CSS must never block the first paint.** `[review]`
+
+**4.5 Choose the inlining threshold deliberately. `"auto"` is a default, not a
+decision.** `[scaffold]`
+Astro's `"auto"` inlines under 4 KB. Most real stylesheets clear it, so `"auto"` quietly
+resolves to *"inline nothing"* — extra round trips before paint.
+
+**4.6 Shrink before you inline.** `[review]`
+Inlining CSS you have not first made small moves the waste out of a cacheable file into
+every HTML response. Worse for anyone who visits a second page.
+
+**4.7 Match the strategy to the visit pattern, and measure it.** `[review]`
+Small CSS + single-page arrivals → inline. Large CSS + multi-page → external.
+
+Measure both through **brotli**, counting bytes *and* requests *and* render-blocking
+resources; localhost serves uncompressed and will mislead you. Inlined CSS compresses
+better than an external file because it shares a dictionary with the HTML, but it is
+only cheaper on the *first* page — the same measurement will show a multi-page session
+getting worse. Record the numbers in the commit message so the trade is not
+re-litigated blind.
+
+**4.8 If CSS is too big to inline, make it smaller — do not load it more cleverly.**
+Critical-CSS extraction is for codebases you cannot restructure. You can: see 4.1.
+
+### Tooling
+
+**4.9 PurgeCSS is a safety net, not a fix.** `[review]`
+Find where the dead CSS comes from first. "Unused CSS" is usually 4.1, and PurgeCSS
+would hide that rather than solve it.
+
+**4.10 If you run PurgeCSS, the safelist must cover every class name the scanner cannot
+see as a literal string.** `[review]`
+Runtime-constructed names (`` `btn-${variant}` ``), `classList.add()`, and
+framework-generated names all vanish silently — no error, no warning, missing styles in
+production. Hashed CSS-module names need a `greedy` pattern; data-attribute state
+selectors need explicit entries.
+
+**4.11 Verify against the built output, never the dev server.** `[review]`
+Code splitting, inlining thresholds and PurgeCSS only take effect at build. None of this
+section is visible in `astro dev`.
+
+**4.12 Every site runs the same CSS pipeline.** `[scaffold]`
+
+---
+
+## 5. Animation & the main thread
+
+Every rule here follows from one fact. To draw a frame the browser does:
+
+```
+Style  →  Layout  →  Paint  →  Composite
+```
+
+Each frame has 16 ms. What matters is **how far back your animated property reaches**:
+
+| Property | Reaches | Cost |
+|---|---|---|
+| `transform`, `opacity` | Composite only | GPU. Main thread free. |
+| `filter`, `box-shadow`, `background`, `border-radius` | Paint | Repaint every frame |
+| `width`, `height`, `top`, `left`, `margin` | Layout | Recompute geometry every frame |
+
+**5.1 Animate `transform` and `opacity`. Nothing else.** `[review]`
+
+**5.2 For a shadow, glow or colour transition, move it to a pseudo-element and
+transition that element's `opacity`.** `[review]`
+Visually identical, compositor-only.
+
+**5.3 Never transition a layout property.** Use `transform: scale()` / `translate()`.
+
+**5.4 In any scroll or resize handler: all reads first, then all writes.** `[review]`
+
+Reading a geometric property after a write forces the browser to compute layout
+*immediately*. Interleave them and every read forces a layout the next write
+invalidates — one handler can cost several forced layouts per scroll frame.
+
+```js
+// read phase — no writes
+const h = el.offsetHeight, rect = el.getBoundingClientRect();
+// compute phase — no DOM access
+// write phase — no reads
+el.style.setProperty("--p", …);
+```
+
+**5.5 Nothing above the fold may depend on JavaScript to become visible.** `[review]`
+Reveal animations start below the fold. The first screen renders from HTML and CSS
+alone. A hero that starts at `opacity: 0` is disqualified from being the LCP element,
+so something further down the page becomes it instead.
+
+**5.6 Nothing may animate *into position* on load.** `[review]`
+
+A scroll-linked effect must **place** on its first reading, not ease into it. Easing
+exists to smooth *scrolling*; on load there is nothing to smooth, because the element
+has never been anywhere else.
+
+An eased follow that starts at `0` and converges on a scroll-derived target runs for
+`ln(threshold) / ln(1 − factor)` frames — with a typical 0.12 factor and a 0.0004
+threshold that is **≈61 frames**, about a second. Every one of those frames mutates a
+transform, forcing layer updates and raster work **while the browser is still trying to
+produce its first paint**. The result is dropped frames and a first paint that slips by
+one to two seconds, intermittently.
+
+This is hard to find because it presents as Speed Index varying between runs with no
+code change, and the cause is usually below the fold in a component nobody suspects.
+
+The fix is a `primed` flag: snap on the first reading, animate on every one after.
+
+**5.7 `will-change` is temporary.** Add before, remove after. A permanent `will-change`
+is a permanent GPU layer, and too many layers cost more than compositing saves.
+`[review]`
+
+**5.8 One animation system per site.** `[review]`
+An animation library alongside a hand-written IntersectionObserver system means every
+future component picks the wrong one half the time.
+
+**5.9 Every animation has a `prefers-reduced-motion` path.**
+
+---
+
+## 6. Delivery
+
+Cache headers, compression config and TLS live in **`webhosting-infra`**. What follows
+is the per-repo slice — and the two ways a correct edge config gets silently defeated
+by the site itself.
+
+**6.1 Every site's router must include `compress@file`.** `[scaffold]`
+
+```yaml
+# docker-compose.yml
+- "traefik.http.routers.<app>-astro.middlewares=secure-headers@file,rate-limit@file,compress@file"
+```
+
+Traefik's compress middleware provides **Brotli** and sets `Vary: Accept-Encoding`.
+
+**6.2 The site's own nginx must not compress.** `[scaffold]`
+
+```nginx
+gzip off;   # compression is Traefik's job
+```
+
+This is the other half of 6.1 and neither works alone. The compress middleware **skips
+any response that already carries a `Content-Encoding`**, so a gzipping origin disables
+Brotli at the edge entirely — for every asset and every document, with no error
+anywhere. Brotli is worth roughly 20% over gzip on HTML.
+
+**6.3 `add_header` appends; it does not replace.** `[scaffold]`
+
+```nginx
+location /uploads/ {
+    proxy_hide_header Cache-Control;                       # required
+    add_header Cache-Control "public, max-age=31536000, immutable";
+}
+```
+
+`proxy_ignore_headers` governs only what **nginx itself caches**; the upstream header
+still reaches the client. Without `proxy_hide_header` the response carries two
+contradictory `Cache-Control` values, browsers resolve conservatively, and every upload
+is re-fetched on every visit. This is entirely invisible in Lighthouse, which only ever
+measures a cold load.
+
+Strapi hashes upload filenames, so uploads are genuinely immutable — `max-age` should be
+a year, with `immutable`.
+
+**6.4 Preconnect to the CMS origin in the base layout.** `[scaffold]`
+
+```astro
+<link rel="preconnect" href={new URL(import.meta.env.PUBLIC_STRAPI_URL).origin} />
+```
+
+Must sit in `<head>` **before** the stylesheets — a preconnect after 15 KB of CSS links
+has already lost its head start. Maximum four preconnects; an unused socket is dropped
+after ~10 s.
+
+**6.5 Preload the LCP image — once per page, and only if it is late-discovered.**
+`[review]`
+
+Both conditions must hold: it **is** the LCP element, **and** the preload scanner cannot
+find it early (CSS `background-image`, JS-injected, deep in the document). A plain
+`<img>` near the top of the HTML is already found.
+
+With a responsive image use `imagesrcset` / `imagesizes` and match the `<img>`
+**exactly** — a plain `href` hardcodes one candidate and you download two files.
+
+**Preload fixes discovery, never weight.** If a resource is late because the page is
+heavy, preloading it just reorders the queue.
+
+---
+
+## 7. Shared code
+
+Image selection, icons and other cross-site primitives live in
+**`@smi-digital/web-kit`**.
+
+**7.1 Never copy code out of web-kit into a site.** `[review]`
+
+A copy is correct exactly once. It has no version, nothing points at it, and the first
+local tweak forks the fleet silently — two behaviours, one name, and no way to tell
+which site has which.
+
+If the shared version does not do what you need, that is the signal to change the shared
+version.
+
+**7.2 Extend upstream with an optional parameter that defaults to current behaviour.**
+`[review]`
+
+A new option that is `undefined` by default cannot change any existing consumer, so the
+change is safe to land before anyone has adopted it. Add the tests in web-kit, where
+every site inherits them.
+
+**7.3 A site may use the helper instead of the component — but never its own copy of
+the logic.** `[review]`
+
+`<CmsImage>` is the default (1.1). Where a site genuinely needs its own wrapper, it
+imports the shared selection function and wraps *that*. The distinction that matters is
+not component-vs-helper; it is **shared-vs-forked**.
+
+**7.4 web-kit ships source, not a build.** `[scaffold]`
+
+```js
+// astro.config.mjs
+vite: { ssr: { noExternal: ['@smi-digital/web-kit'] } }
+```
+
+Without this the build fails in a way that does not mention the cause.
+
+---
+
+## 8. Verification
+
+Rules you cannot test are rules people guess at.
+
+| Check | How | Expect |
+|---|---|---|
+| Fonts | DevTools → Network, filter `font` | **1** file on a German page |
+| Font metrics *(custom faces only)* | read the binary — Appendix B.2 | table matches what the browser uses |
+| Brotli | `curl -sI -H "Accept-Encoding: br" <url>` | `content-encoding: br` |
+| Cache headers | `curl -sI <cms>/uploads/<file>` | **one** `Cache-Control`, `immutable` |
+| Preconnect | Lighthouse → "Preconnected origins" | your CMS origin listed |
+| Modern formats | page HTML | `<source type="image/avif">` before `image/webp` before `<img>` |
+| Image sizing | Lighthouse → "Improve image delivery" | no entries |
+| `priority` images | grep `priority` per page | **1**, and it is the LCP |
+| Eager, low-priority images | grep `fetchpriority="low"` | each one justified by 1.8 |
+| Render-blocking | Lighthouse | 0 stylesheets |
+| Forced reflow | DevTools → Performance, 4× CPU throttle | no purple layout bars in scroll |
+| Layout-defeated lazy | Network tab while **not** scrolling | only above-fold images |
+| Load-time animation | trace → count `DroppedFrame` before first paint | **0** |
+
+### How to measure
+
+**8.1 Verify on the built output, not `astro dev`.** Splitting, inlining, PurgeCSS and
+asset optimisation only exist at build.
+
+**8.2 Verify on a throttled device profile.** Every cost in this document is invisible on
+a laptop and dominates on a low-end phone.
+
+**8.3 Speed Index is bimodal. Take the median of five runs.** `[review]`
+A single run cannot distinguish noise from a regression, and two runs cannot either.
+Expect a wide spread whenever anything animates on load (5.6).
+
+**8.4 Measure the rendered output, not the intended arithmetic.** `[review]`
+The most expensive debugging mistake available is to recompute what the code *should*
+produce from live values, find it correct, and conclude the code is correct. That
+verifies the formula, not the pixels. Screenshot it, read the actual pixels, or overlay
+a reference — then compare.
+
+**8.5 When first paint is late, check whether anything was still loading.** `[review]`
+
+```
+observedLoad         370 ms
+observedFirstPaint  2300 ms   ← everything had finished; this is not network
+```
+
+If load completes and paint does not follow, it is not bandwidth — it is the main thread
+or the compositor. Save the trace and count `DroppedFrame`, `UpdateLayer` and `Commit` in
+the pre-paint window. Dropped frames before first paint mean something is animating that
+should not be.
+
+---
+
+## Appendix A — the sentences worth remembering
+
+1. **Weight is 95% of the problem.** Fonts and images.
+2. **Icons are graphics, not typography.**
+3. **A raw `<img>` is banned because it is incomplete by default**, not because it is
+   wrong. `<CmsImage>` for CMS media, `<Image>` for local files, a written reason for
+   anything else.
+4. **The first island costs a whole framework runtime** (§3.4 — measure it, do not
+   quote it). Astro will happily sell you zero.
+5. **`transform` and `opacity` are the only two free properties** — and nothing should be
+   using them at all during the first paint.
+6. **`<picture>` never falls through.** Every format needs a complete ladder.
+7. **A shared component copied into a site is a fork**, however correct the copy is.
+8. **Measure the pixels, not the formula**, and take the median of five.
+
+---
+
+## Appendix B — Custom font work
+
+Only relevant when a site uses a licensed face rather than a Fontsource package. Skip
+this unless you are subsetting a font, using baseline trimming, or drawing text into a
+canvas.
+
+### B.1 Hard-subsetting
+
+A full-charset face is typically 3–4× the size a European-language site needs.
+Subsetting one is legitimate, but only with all four of these:
+
+1. **A script in the repo**, so it is reproducible when the font is next rebuilt.
+2. **A coverage check against real content** — extract every distinct character from
+   the rendered pages and assert none is missing. Do not eyeball the range; the
+   characters that get dropped are the ones nobody thinks of, like an arrow
+   affordance or a close control.
+3. **Metrics verified unchanged** before and after (B.2).
+4. **A note that the operation is one-way**: a subset cannot be widened from its own
+   output, so pre-subset binaries must stay recoverable from git history.
+
+### B.2 Verify metrics against the binary, and check `USE_TYPO_METRICS`
+
+Any baseline-trimming system (Capsize and equivalents) does arithmetic from a table of
+the font's ascent, descent, line gap and cap height. If that table does not match what
+the **browser** uses, every trimmed element is silently offset.
+
+The trap: metric tables are usually transcribed from `hhea`. But if the font sets
+`OS/2.fsSelection` bit 7 — `USE_TYPO_METRICS` — browsers build the line box from
+**`sTypo`** instead. Foundry spec sheets and font-info sites will not tell you which
+applies.
+
+```
+# read the binary, not the spec sheet
+hhea.ascent / hhea.descent / hhea.lineGap
+OS/2.sTypoAscender / sTypoDescender / sTypoLineGap
+OS/2.sCapHeight
+OS/2.fsSelection bit 7   ← if set, sTypo wins
+```
+
+The error is a fraction of an em, so it scales with font size: invisible in body copy,
+and tens of pixels in display type, where it reads as text sitting in the wrong place.
+
+### B.3 Rasterising text into a canvas
+
+If an effect draws text into a `<canvas>` and swaps it in for the DOM text:
+
+- **Wait for `document.fonts.ready` before drawing.** Rasterise early and you bake in
+  the fallback face, then repaint when the real font arrives — a visible jump.
+- **Measure the baseline; do not derive it.** A zero-height inline-block with
+  `vertical-align: baseline` reports where the baseline actually is, whatever the
+  metric tables say (B.2).
+- **Accept that it will never be pixel-identical.** GPU resampling, alpha blending and
+  a fractional `devicePixelRatio` all differ from native text rendering. If the swap
+  must be invisible, do not swap at rest.