Files
SluijsensandClaude Sonnet 5.5 13f78c48cd Adds the hero contract: golden files for the picture and the preload links, mapping and seed
Model B (wide 3:2 and tall 4:5 variants, focus point), agreed with the CMS
session. Pure functions mapHero, heroHtml and heroPreloadHtml, golden files in
web/contract/host-injection/hero with a README, and a seed with a first focus
estimate per photo. No site change yet.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 14:44:30 +01:00
..

Hero contract (ASF site and CMS host)

Golden files for the hero regions that the CMS host fills, model B (decided 2026-11-16): the host cuts a wide (3:2) and a tall (4:5) variant per photo around the focus point, and the site uses <picture>. Same idea as the packages (../README.md): for every NAME.input.json the host's template must give exactly NAME.expected.html (between <!--CMS:HERO-HTML--> and <!--/CMS:HERO-HTML-->) and NAME.expected-preload.html (between <!--CMS:HERO-PRELOAD--> and <!--/CMS:HERO-PRELOAD--> in the head). The file ends with one newline that is not part of the HTML. The ASF repo tests its own implementation (src/lib/hero.ts, src/lib/heroHtml.ts) against the same files; to change the contract, change the code and run UPDATE_GOLDEN=1 pnpm test src/lib/heroHtml.test.ts, then send the new files to the CMS session. The ASF commit is in git log -1 -- web/contract/host-injection/hero.

Input

The answer of GET /api/v1/hero (an object). A 204 (no hero) is null: the output is empty and the baked hero stays.

Rules

  1. Usable hero: an object with a non-empty title (trimmed) and at least one usable slide; otherwise both outputs are empty strings (fail open: the baked page stays).
  2. A slide is kept when: id is non-empty; image.src is a path of our host (starts with one /, not //, no backslash); image.width and image.height are whole numbers above 0; and it has an alt (non-empty after trimming) or decorative is true. Other slides are skipped. Order is the given order. Only the FIRST kept slide is written; the client takes the rest from the data block.
  3. A decorative slide writes alt="".
  4. Variants: kept when ratio, type and url are non-empty, width is a whole number above 0 and url is a path of our host. Only image/webp variants are used here (a preload cannot say "AVIF if supported", so a second format would be fetched twice). wide variants make the img srcset, tall variants the source srcset; sorted by width ascending, written URL WIDTHw, joined by , .
  5. focus (x and y both between 0 and 1) is written as style="object-position:X% Y%" on the img (percentages without trailing zeros, at most two decimals); without a valid focus there is no style.
  6. Buttons: at most 2 (the first two valid ones). A button is valid with a non-empty label and a target that is an anchor (#name), a path (one leading /, not //, no backslash) or an https:// address that parses. lead and display are not written in the HTML.
  7. Escape every text and attribute (& &amp;, < &lt;, > &gt;, " &quot;, ' &#39;). A new line in the title becomes <br> (after escaping).

Output, HERO-HTML

<picture class="cms-hero-picture"> + (when a tall webp variant exists: <source media="(orientation: portrait)" srcset="TALL" sizes="100vw" type="image/webp">) + <img class="cms-hero-image" src="SRC" + (when a wide webp variant exists: srcset="WIDE" sizes="100vw") + width="W" height="H" alt="ALT" + (focus: style="object-position:X% Y%") + fetchpriority="high"> + </picture> + <h1 class="cms-hero-title"> + (tagline: <span class="cms-hero-tagline">TAGLINE</span> ) + <span class="cms-hero-name">TITLE</span></h1> + (when there are buttons: <p class="cms-hero-buttons"> + <a class="cms-hero-button" href="TARGET">LABEL</a>... + </p>).

src is image.src; W and H are image.width and image.height. Selection is by orientation, not width, because the hero is as high as the screen.

Output, HERO-PRELOAD

With a tall variant: <link rel="preload" as="image" imagesrcset="TALL" imagesizes="100vw" media="(orientation: portrait)" fetchpriority="high"> followed by the landscape link with media="(orientation: landscape)". The landscape link has imagesrcset="WIDE" imagesizes="100vw", or href="SRC" when there is no wide set. Without a tall variant there is one link without media. The srcset, sizes and media values are byte for byte the same as in the picture; the golden files check this.

Files

hero-standard (two slides, wide and tall, AVIF ignored), hero-minimal (no variants, no tagline, no button), hero-two-lines (line break, anchor, https and a third button that is cut, decorative slide), hero-hostile (escaping, unsafe buttons, unusable slides skipped), hero-no-alt and hero-none (empty). seed.json holds the seed for the ASF test CMS with a first focus estimate per photo.

URL scheme suggestion for the variants (the CMS decides): /media/hero/<hash>/wide-1600.webp, /media/hero/<hash>/tall-960.avif.