Files
slp-modular-cms/aidlc-docs/features/hero-module/inception/requirements/site-contract-agreed-with-asf.md
T

7.3 KiB

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 <picture> 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 / schedule / 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/<hash>/…, immutable; the CSP img-src does not change.
Markers <!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML--> (title, tagline, button(s), the FIRST slide as <picture>), <!--CMS:HERO-PRELOAD--> 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 <img> without <picture>) 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 <picture> 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 <source media="(orientation: portrait)">
  • 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 <source>/<img> 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 <picture> 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: <source media="(orientation: portrait)" … type="image/webp"> for tall plus the img for wide inside <picture class="cms-hero-picture">; 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 <!--CMS:HERO-PRELOAD-->…<!--/CMS:HERO-PRELOAD--> 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 <br> after escaping.
  6. Variant names /media/hero/<hash>/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.