19 KiB
Requirements: Hero module (hero-module)
- Feature slug: hero-module
- Status: Draft for approval by Bryan (via SLP Software - SLS - Main); answers of 2026-11-16 processed; SDA reuse question answered (nothing to reuse)
- Depth: Standard (comprehensive for the image upload, which is security relevant)
- Documentation Language: English; Conversation Language: Dutch
- Inputs:
hero-comparison.md(SLS vs ASF),requirement-verification-questions.md(19 questions, answered by Bryan 2026-11-16), decisions relayed by SLP Software - SLS - Main, facts from Andrea Slop Fotografie - ASF - Main, NFR-10 of the SLS requirements
1. Intent analysis
| Item | Value |
|---|---|
| User request | Make the hero of both websites (SLP Software and Andrea Slop Fotografie) manageable from the CMS (texts, buttons, images), immediately visible (NFR-10), with the LCP in the first HTML |
| Request type | New feature (a new module) plus a small CI change |
| Scope | Multiple components: new module SlpModularCms.Modules.Hero, Core (host injection, media serving), admin frontend, CI workflow, scripts, docs; the websites change on their side |
| Complexity | Moderate to complex (image processing and upload security, host injection contract with two sites) |
| Reverse engineering | Targeted review only (Offerings banners/packages, HtmlMarkerEditor/HtmlMarkerInjector, CmsHost website modes) |
2. Principles decided by Bryan
- Content only. Like packages and forms: the CMS delivers content; every site keeps its own layout and presentation (ASF Chakra, SLS Tailwind). No layouts or sketch choice in the CMS or in the react package. A sketch choice may come with a third site.
- All hero content from the CMS: title, tagline, lead, buttons, slides (0..n), plus a "display" field each site renders as it supports.
- LCP in the first HTML: the host injects the hero into the HTML (SLS: text; ASF: first slide
<img>plus preload); the baked hero stays the fallback when the CMS delivers nothing (fail-open, NFR-10). - Stays in the sites: screen-reader and control texts ("Photo n of N", "Slideshow paused"), the slider timing and animation, reduced-motion behaviour, socials, the SLS code line.
3. Answers (traceability)
| Q | Answer | Decision |
|---|---|---|
| 1 | A | One hero per site |
| 2 | One title text with line breaks | Title is one text; a new line in the field is a visual line break. The SLS site derives the screen-reader/SEO text from the lines |
| 3 | Tagline and lead; no code line | The code line stays fixed text in the SLS website |
| 4 | A, with validated target | 0 to 2 buttons: label and target; target is #anchor, /path or https://…, validated by the CMS |
| 5 | A | Field display: single or slideshow |
| 6 | A | Slide: image, required alt text (or explicitly decorative), order, on/off |
| 7 | A + extra | Upload; host keeps the original, reads the size, makes variants for srcset (WebP/AVIF); the administrator can set a focus point and/or crop per image and per use/ratio, with a preview in the admin |
| 8 | A + extra, widened by Bryan (design answer Q2) | Input: as many formats as possible, mainly the common ones (jpg/jpeg, png, webp and, where the library can, gif, bmp, tiff, heic/avif), up to 10 MB, with a real file type check and metadata stripping (GPS). Output: the system chooses what is best per platform (WebP required, AVIF when it can). The CMS resizes, compresses and optimises for the intended size; the Decks/SDA session has nothing to reuse |
| 9 | C | One language now; the data model allows more languages later without migrating existing data |
| 10 | A | As banners and packages: 60 s cache, invalidated directly on every CMS change |
| 11 | A | Saving is publishing (no draft) |
| 12 | B | Schedule (from/to); outside the period the site falls back on the baked hero |
| 13 | A | Administrator and higher |
| 14 | A | Own module SlpModularCms.Modules.Hero with tests, on/off per site |
| 15 | B | Bryan reviews/rewrites the hero and the other sections of the landing page in this feature; only the hero goes to the CMS, the rest stays fixed text in nl.json (the SLS session delivers the list of texts per section) |
| 16 | A | A seed script puts the current hero of SLP and ASF (including the 8 photos) in the CMS of the test environment; production only at the release with Bryan's go |
| 17 | A | Security rules enforced (blocking) |
| 18 | B | Property-based testing partial: pure functions and round-trips |
| 19 | B | No Operations phase; hero points go into the joint production checklist |
4. Functional requirements
4.1 Content model (sketch; refined in Application Design)
| ID | Requirement |
|---|---|
| FR-01 | One hero per site (a single record). If none exists, or none is active, the public endpoint answers 204 and the site uses its baked hero. |
| FR-02 | Fields: title (required, one text, new lines allowed, max 200 chars), tagline (optional, max 120), lead (optional, max 600), display (single or slideshow, default single). Plain text only; the host and the sites encode it. |
| FR-03 | 0 to 2 buttons, each with label (max 50) and target (max 500). Both required per button. Target must match exactly one of: #anchor (letters, digits, -, _), a site path starting with a single / (no //, no scheme, no backslash, no control characters), or an absolute https:// address with a host and no credentials. Anything else is rejected with a clear message. |
| FR-04 | 0 to n slides, each with: stable id, one image, alt text (required, max 300, or an explicit decorative flag instead), order, isActive. Inactive slides are not published. A reasonable maximum (for example 12) protects the page weight. |
| FR-05 | Schedule: optional startsAt / endsAt for the hero as a whole (as banners). Outside the period the hero counts as not available (204). |
| FR-06 | Text fields and slide data are stored so that a language can be added later without migrating existing rows (for example a language key or a translations structure with the current language as the default); only one language is exposed and edited now. |
| FR-07 | Management needs role Administrator or higher (policy AdminOnly); the public read endpoint is anonymous and reachable through the availability gate (like the banner). |
4.2 Images
| ID | Requirement |
|---|---|
| FR-10 | Upload in the admin, max 10 MB, of the common image formats: JPEG, PNG and WebP always, and where the chosen library supports them GIF, BMP, TIFF, HEIC and AVIF (the supported list is fixed in NFR Requirements and shown in the admin). The type is decided from the file content (signature and a successful decode), never from the file name or the Content-Type. Anything else, including SVG, is rejected. An animated input (GIF, WebP) is reduced to its first frame. |
| FR-11 | All metadata (EXIF including GPS, ICC beyond what is needed for colour, XMP) is removed from every stored and published file. |
| FR-12 | The host keeps the original (after validation) and reads its pixel size. It generates optimised variants: several widths and WebP and AVIF (the format set is settled in Application Design with the image library; if AVIF is not feasible on every platform, WebP plus the original format is the minimum). Variants are resized, compressed and sized for the intended use, not the full upload. |
| FR-13 | Focus point and crop. Per image the administrator can set a focus point (the subject that must not be cut off) and/or a crop rectangle (move and zoom), per use or aspect ratio (for example wide desktop hero and tall mobile hero), with a live preview of the result in the admin. The default focus is the centre for every ratio; per ratio (tall, wide) a separate focus point (and zoom) can optionally be set, otherwise the general point (the centre) applies (Bryan, design answer Q6). The public data contains the general focus point and the ratio variants so that a site can use it (for example as object-position) and the generated variants respect the per-ratio settings. |
| FR-14 | Images are served by the host from the site's own address (same origin, no change in CSP img-src), at an address that contains the content hash, so they can be cached for a long time (Cache-Control: public, max-age=31536000, immutable). Uploading a new image gives a new address. |
| FR-15 | The preload address for the LCP image is exactly the address used in the img (or the same srcset/sizes pair in the preload), so the browser does not download it twice. |
| FR-16 | Deleting a slide or replacing its image removes files that nothing references any more (no orphans). |
| FR-17 | Reuse check done (Decks/SDA session, 2026-11-16): SimpleDeckApp has no reusable server-side image processing (only an avatar upload: browser createImageBitmap and canvas at 640 px JPEG 0.85, server checks only the Content-Type header, no magic bytes, no EXIF stripping, no crop or focus point, no srcset or AVIF). Nothing to reuse or duplicate; the hero module chooses and owns its library. The client-side idea (decode through the browser, re-encode to drop EXIF) is not enough here: the server must validate and strip itself (FR-10, FR-11). |
4.3 Public contract and host injection
| ID | Requirement |
|---|---|
| FR-20 | GET /api/v1/hero (anonymous, public, max-age=60, rate limited like the other public Offerings endpoints) returns { display, title, tagline, lead, buttons[], slides[{ id, alt, decorative, image{ width, height, focus{x,y}, src, srcset, variants[…] } }] }, 204 when there is no active hero. The exact shape is agreed with the ASF and SLS sessions (ASF proposes hero {title, tagline, cta{label,url}, slides[{id, imageUrl, width, height, alt, srcset?}]}, delivered as golden files after approval). |
| FR-21 | Host injection into the first HTML for both modes (SpaFallback for SLS, PrerenderedPages for ASF), following the existing marker contract: a region marker for the hero HTML (SLS: title lines, tagline, lead, buttons; ASF: title, tagline, button, first slide img), a marker in the head for the preload link, and a hero key in the #cms-data block with the complete data for the client. Everything is HTML-encoded; script content is escaped like the existing data block. |
| FR-22 | Only the first active slide is injected into the HTML (LCP); the other slides come from the data block and load later in the site. |
| FR-23 | Fail-open: no marker, no hero, an invalid hero or a failing provider leaves the baked page unchanged. The hero follows the same 60 s cache, direct invalidation, ETag/304 and 256-entry cap as the other injected parts. |
| FR-24 | The scheduled hero (FR-05) and inactive slides take effect without a rebuild: outside the period the injected region falls back on the baked content. |
| FR-25 | The admin shows the hero form (texts, display, buttons with validation messages, schedule), the slide list (order, on/off, alt text), the image upload with focus/crop and preview, and a clear indication when the hero is not live. |
4.4 Seed, texts and pipeline
| ID | Requirement |
|---|---|
| FR-30 | A seed script (like scripts/Seed-Offerings.ps1) puts the current SLP hero and the ASF hero with its 8 photos into the CMS of the test environment; it needs the owner's credentials as the offerings seed does. Production is seeded only at the release with Bryan's explicit go. |
| FR-31 | Static texts: Bryan reviews and may rewrite the hero and the other sections of the landing page. Only the hero goes into the CMS; the other sections stay fixed text (nl.json on the SLS site). The SLS session delivers the list of texts per section; the rewritten hero text becomes the seed content. |
| FR-32 | CI: publish-sls-production and deploy-sls-production only run for a workflow_dispatch on a release/* branch (startsWith(github.ref, 'refs/heads/release/')), like ASF. A dispatch from another branch does nothing. A push never deploys production. Documented in docs/deploy-en-testomgevingen.md and docs/release-checklist-productie.md. |
| FR-33 | The backend texts of the module (validation messages, injection texts) go in the module's language files (Texts/nl.json, en.json) per docs/translation-files.md. |
5. Non-functional requirements
| ID | Requirement |
|---|---|
| NFR-01 (LCP) | The LCP element (SLS: heading text; ASF: first slide image) is in the first HTML response, with fetchpriority="high" and width/height for the image and no layout shift; the LCP must not regress against the baked version. Measured on test-ASF and test-SLP with Lighthouse or equivalent before and after. |
| NFR-02 (live) | A change in the CMS is visible within about a minute at most (NFR-10), and directly for the host cache. |
| NFR-03 (page weight) | The first slide delivered to a phone is a small variant (target: well below the 220 to 440 KB JPG of today at the same visual quality); the exact budgets are set in NFR Requirements. |
| NFR-04 (upload safety) | The decode is bounded: maximum pixel count and maximum memory per upload (decompression-bomb protection), a timeout, at most a few uploads processed in parallel, an upload rate limit per user, a body size limit of 10 MB at the framework level. A corrupt or oversized image never takes the host down. |
| NFR-05 (platforms) | The chosen library works on win-x64 self-contained (IIS production) and linux-arm64 (the Pi test hosts) and in the CI (linux x64), with a licence that suits a commercial site. This is verified, not assumed. |
| NFR-06 (storage) | Decided (design answer Q1): the images live in a directory outside the release, behind an own storage interface so that database storage can follow if the hosting demands it. The directory survives a deploy (Pi: releases/current/shared; IIS: a data directory), is part of the backup, and the host account has write permission there. Write permission on the ASF production hosting (MijnHostingPartner, IIS) is not known and is tested by Bryan with ASF; Bryan is asked again if that test fails. |
| NFR-07 (accessibility) | The CMS requires alt text or an explicit decorative flag; the sites keep their slider accessibility (pause, reduced motion, screen-reader texts). |
| NFR-08 (compatibility) | The public shapes of packages, banners and the injection markers do not change; existing golden files stay green. |
| NFR-09 (resilience) | A failing CMS never produces an empty or broken hero: the baked hero stays. |
6. Security (extension: Security Baseline, enabled, blocking)
Applicable rules and where the design must show compliance. Final compliance is checked at each stage.
| Rule | Application to this feature |
|---|---|
| SECURITY-03 | Upload, processing failures and publish events logged with request id, no file contents, no personal data. |
| SECURITY-04 | The media endpoint and the injected HTML keep the existing security headers; X-Content-Type-Options: nosniff on media. |
| SECURITY-05 | Every field has type, length and format validation (FR-02, FR-03, FR-04); button targets are allow-listed; images validated by content (FR-10); no string concatenation into SQL; user text is HTML-encoded on injection. |
| SECURITY-08 | Management endpoints require AdminOnly server-side; object-level checks on slide and image ids; the public endpoints expose no ids beyond the stable slide id and no management data. |
| SECURITY-09 | Generic error messages; no stack traces; no directory listing for the media path. |
| SECURITY-10 | The new image library is a vetted, pinned dependency, covered by the vulnerability scan; unused packages are not added. |
| SECURITY-11 | Rate limiting on the public hero and media endpoints and on uploads; abuse cases (decompression bomb, polyglot files, path tricks in names, repeated uploads filling storage) are covered in the design. |
| SECURITY-13 | Critical changes (who changed the hero or an image, when) are traceable; no unsafe deserialization of untrusted data; the CMS never stores or uses the client's file name for a path. |
| SECURITY-15 | External calls and image processing have explicit error handling; fail closed on a bad upload, fail open on a bad injection (page served unchanged) — documented as deliberate; the global handler stays. |
| SECURITY-01, 02, 06, 07, 12, 14 | N/A for this feature (no new infrastructure or authentication; existing mechanisms apply). Re-checked in Infrastructure/Operations only if Operations is added. |
7. Property-based testing (extension: partial)
Properties for pure functions and round-trips only: focus/crop rectangle arithmetic (always inside the image, the focus point stays inside the crop where possible), choice and ordering of variants (monotonic widths, the preload address equals the image address), button target validation (anything accepted is one of the three forms and round-trips through encoding), HTML/JSON encoding of hero text in the injection (decoding returns the original text), slide ordering and the first-active-slide selection. Other behaviour uses example-based tests.
8. Out of scope
Layouts or sketch choice; the code line of SLS; socials; the timing, animation, aria texts and reduced-motion handling of a site; several languages in the UI; draft/preview workflow; several heroes or a carousel of whole heroes; a general "blocks" module for the other landing-page texts; the IIS publish pipeline for ASF production (separate later idea); production deploys and production variables.
9. Assumptions and open items (to settle in design)
| # | Item | Owner |
|---|---|---|
| A1 | Image library and AVIF feasibility on win-x64 and linux-arm64; licence. The SDA session has nothing to reuse (see FR-17). Candidates to compare in design: ImageSharp, SkiaSharp, NetVips, Magick.NET | CMS session |
| A2 | Bryan with ASF | |
| A3 | Exact crop/focus model: focus point only, crop per ratio, or both; which ratios (for example 16:9 and 3:4); who applies the crop (host-generated variants vs site object-position) |
Application Design with ASF and SLS sessions |
| A4 | Public JSON shape and marker names: agree with ASF (their proposal and golden files) and SLS | CMS, ASF and SLS sessions |
| A5 | SLS renders the title lines and derives the screen-reader text from them; Bryan wants to see the result on SLP Software | SLS session |
| A6 | Limits: maximum slides, maximum pixels, maximum stored bytes per site | NFR Requirements |
| A7 | Performance budgets and the measuring method for NFR-01 and NFR-03 | NFR Requirements |
| A8 | Seed of the 8 ASF photos needs the files from the ASF repository and an owner login | ASF session, Bryan |
| A9 | release/* naming: free after release/ (for example release/2026-11-20) |
Agreed |
10. Operations
Not run as separate stages (Bryan, Q19 = B). Hero points go into docs/release-checklist-productie.md: seed on production at the release, Website variables unchanged, media path reachable, a check of the LCP after the release, the release/* rule for the SLP production deploy.