53 lines
14 KiB
Markdown
53 lines
14 KiB
Markdown
# 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? | **Decided by Bryan (2026-11-16): no, only when the hero is saved.** The admin keeps it locally (Apply in the focus dialog), sends it with the save (`imageFocus`), the host then cuts the variants again into new files and saves hero and images together; leaving the page drops it. | n/a | `HeroSaveRequest.ImageFocus`, `HeroService.SaveAsync`, `HeroImageService.StageFocusAsync`, `FocusDialog.tsx`, `HeroPage.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 `<source type="image/avif">` 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 100 uploads per user per hour (was 20; raised 2026-11-16 so a batch of 8-10 photos does not use it up), 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? | **Decided: no button**; replacing the image of a slide or removing the slide is enough; unused photos 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` (`<br>`), 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 |
|
|
| 23 | What does the host write for a hero **without any slide** (SLP Software)? | A text-only region in the first HTML (so a CMS change is visible without JavaScript, LCP is the text): `h1.cms-hero-title` with an optional `span.cms-hero-tagline` and `span.cms-hero-title-lines` (title lines separated by `<br>`, no brand prefix), then `p.cms-hero-lead` (lead, line breaks as `<br>`) and `p.cms-hero-buttons` with `a.cms-hero-button`. Nothing to preload, and the preload region is left as built. A hero WITH slides but none usable stays empty (ASF unchanged). This is a per-site switch, `Hero:TextOnlyRegion`: on in the committed settings of the SLP site, off by default (so ASF keeps its baked hero when its CMS hero has no slide, as ASF asked). | A separate marker for the text region instead of a switch. | `HeroOptions.TextOnlyRegion`, `HeroPictureRenderer.Render` and `TextOnlyRegion`, `HeroHtmlTransform.ApplyAsync`, `Api.SlpSoftware/appsettings.json`, `HeroTextOnlyTests` |
|
|
| 24 | Does the data block carry the hero when it has no slides? | Yes (intended): the site reads the hero from the data block, the baked block is `{}`. | n/a | `HeroPageModel`, `HeroDataContributor` |
|
|
| 25 | **Variants are cut in the background**, not inside the upload or save request (2026-11-16, found on the ASF test host: saving 8 photos took 60 s+ on the Pi and the proxy cut it with a 504). | Upload and save return at once; `HeroRenderService` cuts one image at a time and switches an image to its new set when it is complete (old set stays live meanwhile); an image without a set is not published; a failing image is tried 3 times, then left until the next restart. Measured on a 20-core PC: upload 3.5-8.8 s and save of 8 changed focus points 39.6 s before, 0.1 s and 0.1 s after (the 37.5 s of cutting moved to the background, 4.7 s per photo). On the Pi: about 25-30 s per photo, 4 minutes for 8. | A longer proxy time-out is then not needed; if cutting should be faster, reduce the variant set or the AVIF effort. | `HeroImageService.RenderNextPendingAsync`, `HeroRenderService`, `HeroSaveTimingTests` |
|
|
| 26 | **A large photo never finished** (ASF test, 4.4 MB): every variant decoded the whole photo again and each ran under the 20 s decode limit, so on the Pi a variant timed out, the whole set was retried 3 times and the image was given up silently. | One decode for the whole set, a width is resized once for both formats and from the previous width; a job limit of 600 s for the set (the image library clock is set above it); a failing image waits for the next round instead of blocking the queue; progress per variant in the admin and the log; retry button. Measured on a 6000x4000 JPEG (3.1 MB): 21.1 s per set before, 6.4 s after, on a fast PC (thread limit made no difference). On the Pi roughly 6x: about 40 s. | Other limits via `Media__*`; skipping AVIF would save about half of the time again. | `MagickImageProcessor.RenderSet`, `HeroRenderService`, `HeroBigPhotoTimingTests` |
|
|
| 27 | The admin page must have **no inline script** (CSP `script-src 'self'`). | The theme script is `/theme-init.js`; a test and the smoke test check it. | n/a | `frontend/public/theme-init.js`, `frontend/src/csp.test.ts`, `scripts/smoke-site.sh` |
|
|
| 28 | **The focus dialog showed a stretched photo** for any photo that is not 3:2: it used the published wide crop (`image.src`) as if it were the whole photo. | Every set now also holds a full-frame preview (`full-<width>.webp`, the whole picture at its own shape, at most 1280 wide); the admin API gives it as `previewSrc`, it is not in `variants` and not published to websites. Sets made before it existed get only that file added by the background renderer (not shown as processing, no address changes). | Without a preview yet the dialog says so instead of showing a wrong picture. | `VariantPlanner.Preview`, `HeroMapping.PreviewSrc`, `FocusDialog` |
|
|
| 29 | **A photo could stay "processing" for ever** in the admin: a photo that was uploaded but not saved yet only had the state of the upload response. | The page now asks the server for those photos one by one (`GET /api/v1/hero/images/{id}`, every 5 s while processing, also in a background tab); each photo shows its own state and, when done, a short "Processing finished" note on that photo (no toast). A photo that was already in the CMS (`reused`, internal only) looks the same and is ready at once. | n/a | `heroImageQuery`, `DoneStatus` |
|
|
|
|
| 30 | **Planning (from/to) and the hero-wide on/off are gone** (Bryan, 2026-11-17): the hero is part of the design and always on; a planning per slide became too much trouble. | Removed from model, API (PUT/GET, OpenAPI), validation, host logic (`IsLive` = has a title), admin (fields, nl/en texts) and tests; migration `RemoveHeroScheduleAndSwitch` drops `StartsAt`, `EndsAt` and `IsActive` of the hero (the per-slide `IsActive` stays). The public JSON, golden files and both sites did not depend on them. Without hero data the host writes nothing. | Planning can be added later, probably per slide; a hero-wide switch likewise. | `HeroMapping.IsLive`, migration `RemoveHeroScheduleAndSwitch` |
|
|
|
|
## Decisions of 2026-11-17 (Bryan, via SLP Software - SLS - Main)
|
|
|
|
| # | Assumption | Decision | Follow-up |
|
|
|---|------------|----------|-----------|
|
|
| 12, 16 | Upload limits and the 50 published slides | Keep as they are (10 MB, 64 megapixels, 100 uploads per hour, 2 GB total, 50 slides). | None. |
|
|
| 10 | AVIF only for slides 2 and up | Bryan asks why the first slide cannot be AVIF only (WebP as fallback). To be evaluated with the ASF session **after the merges** (not in the Hero PR): first slide `<picture>` with `<source type="image/avif">` first and WebP as fallback, preload with `type="image/avif"` and `imagesrcset`; check in Chromium, Firefox and WebKit (Playwright) that there is no double download and that a browser without AVIF falls back to WebP; measure bytes and LCP (the LCP element is the hero text, the photo counts little). Golden files change with it, so agree with the ASF session; only adopt when it is not worse, and Bryan checks it later. | Open, after the merges. |
|
|
| ASF 11 | Slider markup for the first slide | Bryan chooses the full slider render (first photo with zoom-in); the ASF session does it as a follow-up. | Watch whether the host markup (preload/picture) must change for it. |
|
|
| 20 | ASF production hosting (write access, back-up) | Unchanged: Bryan tests with ASF later. | Open. |
|
|
| HEIC | iPhone HEIC upload | Still to be tested by Bryan with a real iPhone file (the build cannot write HEIC; only the library self-test ran). | Open. |
|
|
| other | Assumptions 2, 3, 6, 7, 9, 14, 17, 18, 20, 22 to 30 | Stay as documented. | None. |
|
|
|
|
## Change of 2026-11-17: a new crop applies at once
|
|
|
|
Assumption 1 above (a changed focus only takes effect when the hero is saved) is **replaced by Bryan's later wish**: a new crop must not need another click on Save. The focus dialog now sends the crop at once and the new variants are cut in the background; see assumption 38 of `features/media-library/assumptions-and-open-questions.md`.
|