Hero-module: ASF golden files verwerkt in het ontwerp (preload als regio-paar, alleen WebP in LCP)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 14:45:28 +01:00
co-authored by Claude Sonnet 5.5
parent 47fcaeb0a1
commit 850f02d5ec
5 changed files with 19 additions and 6 deletions
@@ -13,7 +13,7 @@ Details: [components.md](components.md), [component-methods.md](component-method
| D5 | `#cms-data` is composed by a Core `CmsDataBlockTransform` from `ICmsDataBlockContributor`s; Offerings becomes a contributor with byte-identical output; the Hero adds `hero` | Design Q3 = A |
| D6 | Crop model B: the host cuts `wide` (3:2) and `tall` (4:5) variants around the focus point and zoom. The focus defaults to the centre for all ratios; a separate focus (and zoom) per ratio is optional and falls back on the general one | Design Q6, contract |
| D7 | The admin focus editor is an own light component (draggable point, zoom, live `wide` and `tall` previews using a TypeScript twin of `FocusMath` with shared test vectors) | Design Q5 = A |
| D8 | Public contract: `GET /api/v1/hero` (204 = none), the same shape under `hero` in `#cms-data`; markers `CMS:HERO-HTML` (region with the first slide as `<picture>`) and `CMS:HERO-PRELOAD` (one or two preload links with `media`, byte-equal to the `<source>`/`<img>` attributes); addresses `/media/hero/<setHash>/<ratio>-<width>.<ext>`, immutable | Contract with ASF |
| D8 | Public contract: `GET /api/v1/hero` (204 = none), the same shape under `hero` in `#cms-data`; region pairs `<!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML-->` (first slide as `<picture>`) and `<!--CMS:HERO-PRELOAD-->…<!--/CMS:HERO-PRELOAD-->` in the head (one or two preload links with `media`, byte-equal to the `<source>`/`<img>` attributes); only WebP in the LCP picture and the preload; addresses `/media/hero/<setHash>/<ratio>-<width>.<ext>`, immutable | Contract with ASF |
| D9 | One renderer (`HeroPictureRenderer`) produces both the region attributes and the preload attributes; one read model (`PublicHeroService`) feeds the API, the region, the preload and the data block | LCP requirement |
| D10 | Fail-open for page injection, fail-closed for uploads | Requirements, SECURITY-15 |
| D11 | Language: the hero row carries a `Language` (default `nl`, unique), so adding a language needs no migration of existing rows; only one is exposed and edited now | Q9 |
@@ -6,7 +6,7 @@ Rows depend on columns (X = direct use).
| | Core.Media | Core.Hosting.Website | Core.Texts | Modules.Hero | Modules.Offerings | Frontend admin |
|---|---|---|---|---|---|---|
| **Modules.Hero** | X (store, processor, guard, paths, math) | X (`IHtmlPageTransform`, `IIndexHtmlMarkerProvider`, `ICmsDataBlockContributor`, `IIndexHtmlCache`) | X | n/a | none | none |
| **Modules.Hero** | X (store, processor, guard, paths, math) | X (`IHtmlPageTransform`, `ICmsDataBlockContributor`, `IIndexHtmlCache`) | X | n/a | none | none |
| **Modules.Offerings** | none | X (adds `OfferingsDataContributor`; loses the data block write) | X | none | n/a | none |
| **Core.Media** | n/a | none (endpoint is mapped by the host) | none | none (knows no module) | none | none |
| **Core.Hosting.Website** | none | n/a | none | none | none | none |
@@ -15,8 +15,7 @@ Namespaces follow the existing modules (`SlpModularCms.Core.*`, `SlpModularCms.M
| `HeroController` | Public read `GET /api/v1/hero` (anonymous, `[PublicSiteEndpoint]`, `public, max-age=60`, rate-limit policy `hero-public`, 204 when there is no active hero); management `GET /api/v1/hero/all` (the full hero including inactive slides and the schedule) and `PUT /api/v1/hero` (policy `AdminOnly`). Same convention as `offerings` and `offerings/all`. |
| `HeroImagesController` (admin) | `POST /api/v1/hero/images` (multipart upload, size limit), `PUT /api/v1/hero/images/{id}/focus`, `DELETE /api/v1/hero/images/{id}`. |
| `ButtonTargetValidator` | Pure function: accepts `#anchor`, `/path`, `https://host/...`, rejects everything else. |
| `HeroHtmlTransform` (`IHtmlPageTransform`) | Fills `<!--CMS:HERO-HTML-->` regions: title lines, tagline, buttons and the first active slide as `<picture>`. Fail-open. |
| `HeroPreloadMarkerProvider` (`IIndexHtmlMarkerProvider`) | Writes the one or two `<link rel="preload" as="image">` elements at `<!--CMS:HERO-PRELOAD-->`; shares the `srcset`/`sizes`/`media` generator with the transform so they are byte-for-byte equal. |
| `HeroHtmlTransform` (`IHtmlPageTransform`) | Fills the two regions `<!--CMS:HERO-HTML-->…<!--/CMS:HERO-HTML-->` (title, tagline, buttons and the first active slide as `<picture>`) and `<!--CMS:HERO-PRELOAD-->…<!--/CMS:HERO-PRELOAD-->` in the head (one or two `<link rel="preload" as="image">`), both from the same renderer so `srcset`/`sizes`/`media` are byte-for-byte equal. Fail-open. (Changed after the ASF golden files: the preload is a region pair, not a single marker, so no separate marker provider is needed.) |
| `HeroPictureRenderer` | Pure: one place that produces the `<picture>`/`<img>` attributes and the preload attributes from a `PublicHeroDto`; golden-tested. |
| `HeroDataContributor` (`ICmsDataBlockContributor`) | Adds the key `hero` (the `PublicHeroDto`, or null) to the data block. |
| `HeroTexts` + `Texts/nl.json`, `en.json` | Backend texts (validation messages) per `docs/translation-files.md`. |
@@ -9,7 +9,7 @@
| `PublicHeroService` | Builds the public read model from the stored hero: schedule and `IsActive` applied, inactive slides removed, variants that exist listed, the first-slide choice made once here. | `IHeroRepository`, `TimeProvider` |
| Core `MediaEndpoint` | Serves stored variants; no knowledge of the Hero module. | `IMediaStore` |
| Core `CmsDataBlockTransform` | Composes the `#cms-data` block from all contributors. | `ICmsDataBlockContributor` implementations |
| `HeroHtmlTransform`, `HeroPreloadMarkerProvider` | Write the region and the preload from the same `PublicHeroDto` through `HeroPictureRenderer`. | `IPublicHeroService` |
| `HeroHtmlTransform` | Writes the hero region and the preload region from the same `PublicHeroDto` through `HeroPictureRenderer`. | `IPublicHeroService` |
## Orchestration
@@ -63,7 +63,7 @@ flowchart LR
Req["Next page request"] --> Inj["HtmlMarkerInjector"]
Inj --> T1["CmsDataBlockTransform<br/>(offerings, banners, hero)"]
Inj --> T2["HeroHtmlTransform<br/>(region + first slide)"]
Inj --> T3["HeroPreloadMarkerProvider<br/>(head)"]
Inj --> T3["HeroHtmlTransform<br/>(preload region, head)"]
T1 --> Pub["PublicHeroService"]
T2 --> Pub
T3 --> Pub
@@ -58,3 +58,17 @@ Seed values: title "Andrea Slop", tagline "Lifestyle fotograaf · Huizen", butto
- 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.