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>
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
- 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). - A slide is kept when:
idis non-empty;image.srcis a path of our host (starts with one/, not//, no backslash);image.widthandimage.heightare whole numbers above 0; and it has analt(non-empty after trimming) ordecorativeistrue. 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. - A decorative slide writes
alt="". - Variants: kept when
ratio,typeandurlare non-empty,widthis a whole number above 0 andurlis a path of our host. Onlyimage/webpvariants are used here (a preload cannot say "AVIF if supported", so a second format would be fetched twice).widevariants make theimgsrcset,tallvariants thesourcesrcset; sorted by width ascending, writtenURL WIDTHw, joined by,. focus(xandyboth between 0 and 1) is written asstyle="object-position:X% Y%"on theimg(percentages without trailing zeros, at most two decimals); without a valid focus there is nostyle.- Buttons: at most 2 (the first two valid ones). A button is valid with a non-empty
labeland atargetthat is an anchor (#name), a path (one leading/, not//, no backslash) or anhttps://address that parses.leadanddisplayare not written in the HTML. - Escape every text and attribute (
&&,<<,>>,"",''). 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.