# Hero contract with the websites (FINAL, 2026-11-16) **Status**: final. Bryan chose crop/focus model **B** on 2026-11-16 (relayed by SLP Software - SLS - Main). The 8 current ASF exports are the seed sources (no larger originals now; a later upload through the admin is always possible). The ASF session proposes a first-guess focus point per photo (recorded in the seed data); Bryan adjusts them in the admin. The ASF session delivers the golden files for `` and the preload. Input for Application Design. Source: message of "Andrea Slop Fotografie - ASF - Main" (technical answer; the crop/focus model stays Bryan's choice). The SLS side is delivered by the SLS session (three title lines with screen-reader text derived from the lines). ## Agreed | Topic | Agreement | |---|---| | Buttons | `buttons[]` of `{label, target}`, 0 to 2. ASF shows one (the first, style "light"); a second would be "outline"; 0 buttons = no button. | | Title | One text; a new line is a line break (ASF title is one line today). `tagline` stays the label above the title in the same `h1`. | | Lead | ASF does not render it; if present the site ignores it. | | Decorative | `decorative: true` renders `alt=""` and is not read aloud. | | Display | `single`: no arrows, pause button or progress bar (ASF already does that for one slide). | | 204 / no hero data / error | The baked hero stays (fail-open). ASF shows the baked hero on 204, not nothing. If the host ever means "no hero at all", that must be said explicitly (not planned). | | Image addresses | Same origin `/media/hero//…`, immutable; the CSP `img-src` does not change. | | Markers | `…` (title, tagline, button(s), the FIRST slide as ``), `` in the head, key `hero` in `#cms-data` with all slides. Fail-open: no marker, 204 or an error leaves the baked page. | | Hydration | The region holds neutral HTML (fixed classes, no Chakra classes); React takes over with the same source after hydration; slides 2..n load afterwards. The first slide of the data block must equal the first slide the host wrote into the HTML (same source, same cache rule). | | Golden files | ASF delivers input JSON, expected HTML region and expected preload, with a README and the commit, in `web/contract/host-injection/hero/` on a new ASF branch `feature/hero-module`. They start once Bryan chose the crop model. An A/B-neutral subset (title, tagline, button, first slide `` without ``) can be delivered earlier. | ## Crop/focus model: B (decided) The host cuts variants per named ratio around the focus point (or an administrator-set crop) and also delivers the focus point; sites use `` per ratio and may use the focus point as `object-position` for in-between shapes. (Option A, a focus point only, was not chosen.) Ratios and widths (ASF proposal, accepted): | Ratio | Name | Widths | Notes | |---|---|---|---| | 3:2 | `wide` | 960, 1600, 2560 (the host may choose its own steps, but never upscale) | the `img` itself | | 4:5 | `tall` | 640, 960, 1280 | `` | - `sizes="100vw"`. Selection is by orientation, not by width, because the hero height comes from the screen (100svh with object-fit cover). The focus point stays as `object-position` for in-between shapes (tablet, narrow window). - Two preload links: `tall` with `media="(orientation: portrait)"` and `wide` with `media="(orientation: landscape)"`, each with `imagesrcset`, `imagesizes="100vw"`, `fetchpriority="high"`. `srcset`, `sizes` and `media` in the preload must be byte-for-byte equal to those in ``/`` in HERO-HTML (the golden files check this). ## Source images for the seed The 8 ASF photos are already resized exports, not camera originals: all landscape 3:2, 1600x1067 (five), 2048x1362 (two) and 2560x1702 (one). The host must never upscale: for the five 1600-wide photos a variant wider than 1600 does not exist. Bryan may supply better originals (needed for good AVIF variants and a true portrait crop); the focus point per photo is Bryan's choice, set in the CMS after the seed. Order, with the current alt texts (path `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie\web\src\assets\hero-N.jpg`): | # | File | Size | Alt | |---|---|---|---| | 1 | hero-8 | 1600x1067 | Zwangerschapsfoto in de duinen | | 2 | hero-7 | 1600x1067 | Knusse newbornfoto met de familie | | 3 | hero-1 | 2560x1702 | Lifestyle fotografie | | 4 | hero-2 | 1600x1067 | Zwangerschapsshoot in de buitenlucht | | 5 | hero-3 | 1600x1067 | Newbornshoot van een pasgeboren baby | | 6 | hero-4 | 2048x1362 | Spontaan portret buiten | | 7 | hero-5 | 1600x1067 | Natuurlijke lifestylefoto | | 8 | hero-6 | 2048x1362 | Portret in de natuur | Seed values: title "Andrea Slop", tagline "Lifestyle fotograaf · Huizen", button "Lees meer" to `/over-mij`, display `slideshow`. ## Consequences for the design - A `` region needs a stable, deterministic rendering of `srcset`/`sizes`/`media` shared by the HERO-HTML and the preload (one generator, golden-tested). - Variants are limited by the source size (no upscaling); the public data lists only variants that exist. - Two preload links (portrait, landscape) are needed when a `tall` ratio exists. - The first-slide data in `#cms-data` and in the HTML must come from the same computation. ## Golden files delivered (ASF commit 13f78c4, branch feature/hero-module of the ASF repository) Folder `web/contract/host-injection/hero/` (README with all rules, `seed.json`, six inputs: standard, minimal, two-lines, hostile, no-alt, none; per input `NAME.expected.html` and `NAME.expected-preload.html`). The CMS host template must produce exactly these files (Build and Test unit H4). Choices accepted by the CMS session: 1. Only WebP in the LCP picture and the preload (a preload cannot say "AVIF if supported"); AVIF variants may exist for slides 2..n on the client. 2. Selection by orientation: `` for `tall` plus the `img` for `wide` inside ``; two preloads with `media` portrait and landscape; without `tall` one preload without `media`; without `wide` an `img src` and a preload `href`. 3. Focus as `style="object-position:X% Y%"` on the `img` (no trailing zeros, at most two decimals; no style without a valid focus). `width` and `height` on the `img` are the original image size from the data. 4. The preload is a region pair `…` in the head, like `CMS:HERO-HTML` (this replaces the earlier single-marker idea). 5. A slide without alt (and not decorative), with a foreign or unsafe path or without a size is skipped; no usable slide or no title gives empty regions (the baked hero stays). At most 2 buttons; targets are `#anchor`, `/path` or `https://`. New lines in the title become `
` after escaping. 6. Variant names `/media/hero//wide-1600.webp` and `tall-960.avif`. 7. Seed (first focus estimates by looking at the photos, (x,y) from the top left): hero-8 (0.50,0.55), hero-7 (0.45,0.50), hero-1 (0.55,0.60), hero-2 (0.45,0.45), hero-3 (0.45,0.40), hero-4 (0.45,0.35), hero-5 (0.50,0.55), hero-6 (0.50,0.35). Bryan adjusts them in the admin. Not yet built on the ASF side (after this design): hydration and slider from the data block, marker injection in the build, e2e against a stand-in host, the baked fallback from the CMS-driven format. ## Text-only hero (SLP Software), added 2026-11-16 A hero **without any slide** is written as text, **only on a site that asks for it** with the setting `Hero:TextOnlyRegion=true` (SLP Software: no images; it reads the same hero from the data block). The setting is off by default and off for ASF, so for ASF a hero without a slide changes nothing in the page (the baked hero stays, also in the preload region): `

` + (tagline: `TAGLINE `) + `LINE
LINE

` + (lead: `

LEAD

`, line breaks as `
`) + (buttons: `

LABEL...

`, at most two). An optional per-site setting `Hero:TitlePrefix` (default empty; SLP Software: `"SLP Software: "`) writes `SLP Software: ` (encoded) as the **first child of the h1**, before tagline and title lines, so crawlers and screen readers read "SLP Software: Websites, apps & meer."; the site styles that class visually hidden (sr-only). The visible title lines stay in `span.cms-hero-title-lines`. The prefix is only used in the text-only region (never for a hero with slides; ASF leaves it empty, so its golden files are unchanged). There is nothing to preload, so `CMS:HERO-PRELOAD` is left as the build made it. Everything is HTML-encoded. A hero with slides of which none is usable is still empty (the ASF golden files are unchanged).