From b749902f4ac53c14f9f3d1fcf5ef3f560282334e Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Mon, 16 Nov 2026 16:49:32 +0100 Subject: [PATCH] Hero-module: aannames en uitgestelde vragen, script voor de LCP-meting (nog niet gedraaid) Co-Authored-By: Claude Sonnet 5.5 --- .../assumptions-and-open-questions.md | 28 ++++++++++ scripts/Measure-Lcp.ps1 | 51 +++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 aidlc-docs/features/hero-module/assumptions-and-open-questions.md create mode 100644 scripts/Measure-Lcp.ps1 diff --git a/aidlc-docs/features/hero-module/assumptions-and-open-questions.md b/aidlc-docs/features/hero-module/assumptions-and-open-questions.md new file mode 100644 index 0000000..a8a461c --- /dev/null +++ b/aidlc-docs/features/hero-module/assumptions-and-open-questions.md @@ -0,0 +1,28 @@ +# Assumptions and deferred questions: hero-module + +Kept while Bryan was away (2026-11-16): no questions to him, a likely assumption or an easy-to-change placeholder instead. Per item: the question, the assumption made, what changes if Bryan chooses differently, and where in the code. To be put to Bryan by the SLS session. + +| # | Question | Assumption made | If Bryan chooses differently | Where | +|---|---|---|---|---| +| 1 | Does a change of the **focus** of an image that is already live take effect at once? | Yes. Saving is publishing (Q11 = A) and the images are shared, so a new focus re-cuts the variants and the live page shows them within the cache time. | Add a draft step for images (focus applies when the hero is saved), or a confirmation in the focus dialog. | `HeroImageService.SetFocusAsync`; `FocusDialog.tsx` | +| 2 | Is a photo uploaded but never put in a slide cleaned up, and when? | Yes, after the same 7 days as retired files (Bryan decided 7 days for old files; extended to unused uploads). | Another period, or never (then storage grows). | `HeroMediaCleanup` (step 1), `Media:RetentionDays` | +| 3 | Should an uploaded photo that is **identical** to an existing one be a new image? | No: same bytes = same image (and a re-upload repairs lost files). | Always a new image: drop the SHA-256 unique index and the lookup. | `HeroImageService.UploadAsync`, `HeroDbContext` (unique `OriginalSha256`) | +| 4 | Is the **alt text** per slide or per photo? | Per slide (the same photo may carry another description in another place). | Per photo: move `Alt` and `Decorative` from `HeroSlide` to `HeroImage`. | `HeroSlide`, `HeroSaveRequest`, `HeroPage.tsx` | +| 5 | Is the **focus** per photo or per slide? | Per photo (shared by every slide that uses it). | Per slide: move the six focus columns to `HeroSlide`; media sets would then be per slide. | `HeroImage.FocusFor`, `HeroImageService`, `FocusDialog.tsx` | +| 6 | Is a hero with a title but **no slides** live? | Yes (the SLP hero is text only). The ASF region stays empty without a usable slide (their rule), so their baked hero stays. | Require at least one slide: add to `HeroMapping.IsLive` and the validation. | `HeroMapping.IsLive`, `HeroPictureRenderer.Render` | +| 7 | Which **language** does the hero use? | Always `nl` (one language now; the column and the unique index allow more later without migrating rows). It is not tied to `Texts:DefaultLanguage`. | Use the site language, or expose a `?lang=` parameter and a language switch in the admin. | `HeroLanguages.Default`, `HeroService`, `PublicHeroService` | +| 8 | Stored **original** of a photo with metadata. | Stored without metadata (re-encoded at JPEG quality 92 or the source quality when it carried EXIF, XMP or IPTC; HEIC becomes JPEG); a photo without metadata is stored as received. | Keep the exact original bytes (then GPS stays in a file that is never served), or always re-encode. | `MagickImageProcessor.StripMetadata`, `HeroImageService.UploadAsync` | +| 9 | Image quality and widths. | WebP 80, AVIF 50, JPEG 82; wide 640 to 2560 and tall 480 to 1280, never upscaled (approved defaults). Bryan's ASF photos are only 1600 or 2048 wide, so larger variants do not exist. | Other numbers or ladders. | `VariantPlanner` | +| 10 | Is **AVIF** used on the page? | Only for slides 2 and up on the client; the first image and the preload are WebP only (ASF: a preload cannot say AVIF if supported). | Add `` before the WebP source and a second preload per format (costs a double download in some browsers). | `HeroPictureRenderer` | +| 11 | Who may use the Hero screen? | Owner and Administrator, like Offerings. | Owner only: change the route and nav roles. | `router.tsx`, `Sidebar.tsx`, `[Authorize(Policy = "AdminOnly")]` | +| 12 | Upload limits. | 10 MB per file, 64 megapixels, at most 20 uploads per user per hour, 2 images processed at once, 2 GB in total. The proxy allows 15 MB (Bryan). | Other limits via `Media__*` and `RateLimiting__HeroUpload`; a higher file limit also needs the proxy limit. | `MediaOptions`, `ServiceCollectionExtensions` (policy `hero-upload`) | +| 13 | Can the admin **delete an image** itself? | No button: removing it from the hero is enough; unused images go after 7 days. The API (`DELETE /hero/images/{id}`, 409 while in use) exists. | Add a media library screen with delete. | `HeroImagesController.Delete`, `HeroPage.tsx` | +| 14 | Wording of the **messages** (Dutch), for example the focus dialog and the validation texts. | My wording; the admin has nl and en. | Edit the texts. | `frontend/src/i18n/locales/*/translation.json` (`hero.*`), `SlpModularCms.Modules.Hero/Texts/*.json` | +| 15 | The **button target** rules. | The CMS accepts only `#anchor` (letters, digits, `-`, `_`, starting with a letter), `/path` (no `//`, no spaces) or `https://host/...`; the page renderer is a little wider (ASF rules) because it also copes with data it did not check. | Allow `mailto:` or `tel:` (add to both validators and the renderer, and agree it with the sites). | `ButtonTargetValidator`, `schemas/hero.ts`, `HeroPictureRenderer.IsButtonTarget` | +| 16 | Maximum **published** slides. | 50, a safety ceiling (not an administrator limit). | Another number or a hard limit shown in the admin. | `HeroOptions.MaxPublishedSlides` | +| 17 | When the **media directory is missing or restored without files**. | The page keeps the baked hero (checked per page build for the first slide) and uploads are off until the directory works; a re-upload of the same photo repairs the files. | A visible warning in the admin when files are missing. | `HeroPageModel`, `MediaDirectoryCheck`, `HeroImageService.UploadAsync` | +| 18 | **HEIC** input. | Accepted as a capability (the arm64 self-test confirms it); not tested with a real HEIC file yet. | If a real file fails, remove HEIC from `SupportedInput` for the allow-list. | `MagickImageProcessor.DetectInput`, `ImageSignature` | +| 19 | **LCP** measurement and the budget. | Lighthouse (mobile) before and after the markers; the hero must not make LCP worse than the baked page. A script is ready (`scripts/Measure-Lcp.ps1`); it was not run (the tooling refused to install Lighthouse), so there is no baseline yet. | Another budget or tool (WebPageTest, field data). | `scripts/Measure-Lcp.ps1`, `docs/hero-module.md` | +| 20 | **ASF production** hosting (IIS, MijnHostingPartner): can the application pool write a data directory, and is it backed up? | Unknown; Bryan tests with ASF. The storage sits behind `IMediaStore` so a database store can follow. | Build the database store (2 to 3 days). | `IMediaStore`, `FileSystemMediaStore` | +| 21 | **SLS title** on the page. | The CMS delivers one title with line breaks; the SLP site derives the screen-reader title from the lines and adds the brand prefix itself. | Another split (a separate `heading` field) would be a model change. | `HeroSaveRequest.Title`, `HeroPictureRenderer` (`
`), SLS site | +| 22 | **Production seed**. | Not done; only the test hosts, with Bryan's password, after his go. | n/a | `scripts/Seed-Hero.ps1`, `docs/release-checklist-productie.md` section 4b | diff --git a/scripts/Measure-Lcp.ps1 b/scripts/Measure-Lcp.ps1 new file mode 100644 index 0000000..3913c75 --- /dev/null +++ b/scripts/Measure-Lcp.ps1 @@ -0,0 +1,51 @@ +<# +.SYNOPSIS + Measures the Largest Contentful Paint (and layout shift) of a page with Lighthouse, mobile profile, a few runs, and + prints the median. Use it before and after the hero markers are in a website, on the TEST hosts. + +.DESCRIPTION + Runs `npx lighthouse` (performance category only, mobile emulation with the default throttling) -Runs times against + -Url and reports the LCP element, the LCP time, CLS and total blocking time per run and the median LCP. Needs Node + (npx) and Chrome or Edge. Nothing is written to the repository; the JSON reports go to -OutDirectory (default: a + temporary folder). + +.PARAMETER Url + The page, e.g. https://test.andreaslop.nl/ + +.PARAMETER Runs + Number of runs (default 3; the median is what counts, a single run varies). + +.PARAMETER OutDirectory + Where the Lighthouse JSON reports are kept. + +.EXAMPLE + ./scripts/Measure-Lcp.ps1 -Url https://test.andreaslop.nl/ -Runs 5 +#> +[CmdletBinding()] +param( + [Parameter(Mandatory)] [string] $Url, + [int] $Runs = 3, + [string] $OutDirectory = (Join-Path ([IO.Path]::GetTempPath()) 'lcp-measure') +) + +$ErrorActionPreference = 'Stop' +New-Item -ItemType Directory -Force -Path $OutDirectory | Out-Null +$results = @() +for ($i = 1; $i -le $Runs; $i++) { + $file = Join-Path $OutDirectory ("lh-{0}-{1}.json" -f ([uri]$Url).Host, $i) + & npx --yes lighthouse@12 $Url --only-categories=performance --form-factor=mobile --output=json --output-path=$file ` + --chrome-flags="--headless=new --no-sandbox" --quiet | Out-Null + $report = Get-Content -LiteralPath $file -Raw | ConvertFrom-Json + $audits = $report.audits + $element = $audits.'largest-contentful-paint-element'.details.items[0].items[0].node.snippet + $results += [pscustomobject]@{ + Run = $i + LcpMs = [math]::Round($audits.'largest-contentful-paint'.numericValue) + Cls = [math]::Round($audits.'cumulative-layout-shift'.numericValue, 3) + TbtMs = [math]::Round($audits.'total-blocking-time'.numericValue) + Element = $element + } +} +$results | Format-Table -AutoSize +$sorted = $results.LcpMs | Sort-Object +Write-Host ("Median LCP: {0} ms (reports in {1})" -f $sorted[[int][math]::Floor(($sorted.Count - 1) / 2)], $OutDirectory)