@sarimarcus/content-sites-core 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.22.0 (2026-10-04)
+
+- New `./affiliate`: `createGygCmp(siteKey)` (the GYG `cmp=` tagger and `tagGygLinksInHtml`), `gygProductId` (one `-t<digits>` pattern for every site), `cmpSegment`, `amazonProductUrl`, `bookingSearchUrl` and `travelpayoutsWidgetSrc`. Sites pass their partner ids and destinations in; output is byte-identical to the per-site builders it replaces. `./url` now exports `pageTypeOf` (SLA-2919).
+
+## 0.21.0 (2026-10-02)
+
+- New `./images`: one width ladder (`IMAGE_LADDER`, `ladderWidths`, `snapWidth`, `variantRungs`) and `./images/service`, an Astro image service that never encodes. It serves committed WebP variants from the site's `image-variants/` and the source bytes at the native width, so production srcsets point at real files of the width they claim; previously every width resolved to one file under the noop service. `./images/variants` and the `content-sites-image-variants` bin generate, prune and check the variants (`sharp` is an optional peer). `defineSiteConfig` installs the service on every build in place of noop/sharp (SLA-2912).
+
 ## 0.20.0 (2026-10-02)
 
 - New `./interludes`: `createInterludeSchema(z, config)` builds the 14-member article interlude union from a site's entity taxonomy (`relatedCardTypes`, `featureTypes`) with the site's own zod; `INTERLUDE_TYPES` and `INTERLUDE_MAX_PER_SECTION` for factory gates. Replaces the per-site generated `interludes.schema.ts` (SLA-2740).

package/README.md

@@ -4,7 +4,7 @@ Non-visual code shared by the content sites: generic utilities, Astro config bui
 and the type contracts `ui` and `tourism` build on (for example the card item and tag-link shapes that
 today's ui components import from tourism code).
 
-Named entry points: `url`, `dates`, `geo`, `dom`, `text`, `config`, `types` and `schema` (`src/internal` is never exported). No `.astro`
+Named entry points: `url`, `affiliate`, `dates`, `geo`, `dom`, `text`, `config`, `types`, `schema`, `interludes` and `images` (`src/internal` is never exported). No `.astro`
 files. Lowest layer: imports nothing from the other packages; its one runtime dependency is `marked` (`readingTime`). Ownership per path is in
 `.planning/platform/catalogue.json` (owner `core`).
 
@@ -23,3 +23,11 @@ Builders are factories whose options carry each site's differences, so a site re
 for byte, key order included. It also holds the opening-hours model (`generateOpeningHours`, `parseHoursString`,
 `assertedOpenDays`, `hoursStringOpenDays`) that `scripts/validate-opening-hours.mjs` imports. The factory scripts
 load `dist/`; `scripts/lib/core-dist.mjs` rebuilds it when it is missing or older than `src/`.
+
+`images` holds the one responsive width ladder (`IMAGE_LADDER`: 320, 480, 640, 960, 1280; WebP only) and the image
+service `defineSiteConfig` installs. The service never encodes: it serves committed variants from the site's
+`image-variants/` (keyed by the source's content hash, listed in `manifest.json`) and the source bytes for the native
+width, and caps each srcset at the source width. A call site asks for a responsive image with
+`widths={IMAGE_LADDER}` plus `sizes`; images without variants (galleries) get a single `src` and no srcset.
+`content-sites-image-variants` (bin, `npm run images:variants` in a site) writes missing variants with sharp, an
+optional peer, and prunes unused ones; `--check` is the local form of the push gate `scripts/validate-image-variants.mjs`.

package/dist/affiliate/gyg.d.ts

@@ -0,0 +1,28 @@
+/** GetYourGuide product id: the `-t<digits>` segment of a tour URL. */
+export declare function gygProductId(url: string): string;
+/**
+ * cmp segments are lowercased and non-alphanumerics collapse to a single hyphen.
+ *
+ * Exported so a component can stamp the SAME normalised string into its data-track-*-placement attributes.
+ */
+export declare function cmpSegment(raw: string): string;
+export interface GygCmp {
+    /** Append `cmp=<siteKey>__<pageType>__<placement>` to a GetYourGuide affiliate URL. */
+    withGygCmp(href: string, pathname: string, placement: string): string;
+    /** Tag every GetYourGuide partner link inside already-rendered HTML. */
+    tagGygLinksInHtml(html: string, pathname: string, placement?: string): string;
+}
+/**
+ * The GYG campaign tagger for one site. `siteKey` is the first cmp segment; scripts/validate-gyg-cmp.mjs enforces
+ * the `<siteKey>__<pageType>__<placement>` shape against the built dist.
+ *
+ * Three deliberate no-ops, each a wrong-attribution bug if dropped:
+ *   - non-GYG hosts pass through (cmp is a GYG parameter, meaningless elsewhere);
+ *   - GYG URLs with no partner id pass through: those are editorial citations, not monetized CTAs;
+ *   - an existing `cmp` is left alone, so tagging is idempotent. That is not an escape hatch for a hand-set
+ *     campaign value: the gate refuses any other shape.
+ *
+ * The cmp is appended textually rather than via `searchParams.set` + `toString()`, because that round-trip
+ * re-serializes the whole query string (`extra=a%20b` becomes `extra=a+b`).
+ */
+export declare function createGygCmp(siteKey: string): GygCmp;

package/dist/affiliate/gyg.js

@@ -0,0 +1,60 @@
+import { pageTypeOf } from "../url/pageType.js";
+const GYG_HOST = /(^|\.)getyourguide\.com$/;
+/** GetYourGuide product id: the `-t<digits>` segment of a tour URL. */
+export function gygProductId(url) {
+    return url.match(/-t(\d+)/)?.[1] ?? '';
+}
+/**
+ * cmp segments are lowercased and non-alphanumerics collapse to a single hyphen.
+ *
+ * Exported so a component can stamp the SAME normalised string into its data-track-*-placement attributes.
+ */
+export function cmpSegment(raw) {
+    return raw.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+/**
+ * The GYG campaign tagger for one site. `siteKey` is the first cmp segment; scripts/validate-gyg-cmp.mjs enforces
+ * the `<siteKey>__<pageType>__<placement>` shape against the built dist.
+ *
+ * Three deliberate no-ops, each a wrong-attribution bug if dropped:
+ *   - non-GYG hosts pass through (cmp is a GYG parameter, meaningless elsewhere);
+ *   - GYG URLs with no partner id pass through: those are editorial citations, not monetized CTAs;
+ *   - an existing `cmp` is left alone, so tagging is idempotent. That is not an escape hatch for a hand-set
+ *     campaign value: the gate refuses any other shape.
+ *
+ * The cmp is appended textually rather than via `searchParams.set` + `toString()`, because that round-trip
+ * re-serializes the whole query string (`extra=a%20b` becomes `extra=a+b`).
+ */
+export function createGygCmp(siteKey) {
+    function withGygCmp(href, pathname, placement) {
+        let u;
+        try {
+            u = new URL(href);
+        }
+        catch {
+            return href;
+        }
+        if (!GYG_HOST.test(u.hostname.replace(/^www\./, '')))
+            return href;
+        if (!u.searchParams.has('partner_id'))
+            return href;
+        if (u.searchParams.has('cmp'))
+            return href;
+        const type = cmpSegment(pageTypeOf(pathname));
+        const place = cmpSegment(placement);
+        if (!type || !place)
+            return href;
+        // cmp is [a-z0-9-] segments joined by `__`, so it needs no percent-encoding.
+        const hashAt = href.indexOf('#');
+        const base = hashAt === -1 ? href : href.slice(0, hashAt);
+        const frag = hashAt === -1 ? '' : href.slice(hashAt);
+        return `${base}${base.includes('?') ? '&' : '?'}cmp=${siteKey}__${type}__${place}${frag}`;
+    }
+    function tagGygLinksInHtml(html, pathname, placement = 'prose') {
+        return html.replace(/href="(https?:\/\/[^"]*getyourguide\.com[^"]*)"/g, 
+        // `&amp;` is the standard encoding inside an attribute; without decoding it first, new URL() reads the key
+        // as `amp;partner_id` and the link ships untagged.
+        (_m, href) => `href="${withGygCmp(href.replace(/&amp;/g, '&'), pathname, placement).replace(/&(?!amp;|lt;|gt;|quot;|apos;|#\d)/g, '&amp;')}"`);
+    }
+    return { withGygCmp, tagGygLinksInHtml };
+}

package/dist/affiliate/index.d.ts

@@ -0,0 +1,6 @@
+export { gygProductId, cmpSegment, createGygCmp } from './gyg.ts';
+export type { GygCmp } from './gyg.ts';
+export { amazonProductUrl, bookingSearchUrl } from './links.ts';
+export type { BookingSearch } from './links.ts';
+export { travelpayoutsWidgetSrc } from './travelpayouts.ts';
+export type { WidgetLoader, WidgetAccount, WidgetOptions } from './travelpayouts.ts';

package/dist/affiliate/index.js

@@ -0,0 +1,4 @@
+// Public surface of @sarimarcus/content-sites-core/affiliate.
+export { gygProductId, cmpSegment, createGygCmp } from "./gyg.js";
+export { amazonProductUrl, bookingSearchUrl } from "./links.js";
+export { travelpayoutsWidgetSrc } from "./travelpayouts.js";

package/dist/affiliate/links.d.ts

@@ -0,0 +1,17 @@
+/** Amazon product page. With a tag (even an empty one) the path gains a trailing slash before the query; without one it has none. */
+export declare function amazonProductUrl(asin: string, tag?: string): string;
+export interface BookingSearch {
+    /** Free text. Alone it resolves to a property; with `destId` the destination wins. */
+    ss: string;
+    destId?: string;
+    destType?: string;
+    checkin?: string;
+    checkout?: string;
+}
+/**
+ * A Booking.com search for two adults in one room.
+ *
+ * Carries no affiliate parameter: Travelpayouts' Emerald Link Switcher rewrites raw booking.com hrefs into tracked
+ * redirects at click time. Parameter order is fixed (ss, dest_id, dest_type, checkin, checkout, then the party).
+ */
+export declare function bookingSearchUrl({ ss, destId, destType, checkin, checkout }: BookingSearch): string;

package/dist/affiliate/links.js

@@ -0,0 +1,27 @@
+/** Amazon product page. With a tag (even an empty one) the path gains a trailing slash before the query; without one it has none. */
+export function amazonProductUrl(asin, tag) {
+    const base = `https://www.amazon.com/dp/${asin}`;
+    return tag === undefined ? base : `${base}/?${new URLSearchParams({ tag })}`;
+}
+/**
+ * A Booking.com search for two adults in one room.
+ *
+ * Carries no affiliate parameter: Travelpayouts' Emerald Link Switcher rewrites raw booking.com hrefs into tracked
+ * redirects at click time. Parameter order is fixed (ss, dest_id, dest_type, checkin, checkout, then the party).
+ */
+export function bookingSearchUrl({ ss, destId, destType = 'city', checkin, checkout }) {
+    const params = new URLSearchParams({ ss });
+    if (destId) {
+        params.set('dest_id', destId);
+        params.set('dest_type', destType);
+    }
+    if (checkin)
+        params.set('checkin', checkin);
+    if (checkout)
+        params.set('checkout', checkout);
+    params.set('group_adults', '2');
+    params.set('group_children', '0');
+    params.set('no_rooms', '1');
+    params.set('lang', 'en-gb');
+    return `https://www.booking.com/searchresults.html?${params.toString()}`;
+}

package/dist/affiliate/travelpayouts.d.ts

@@ -0,0 +1,38 @@
+/** Where a Travelpayouts widget kind loads from and the ids it reports under. Declared in ui affiliate/resources.ts. */
+export interface WidgetLoader {
+    /** The loader script URL without its query, e.g. `https://<host>/content`. */
+    url: string;
+    promoId: string;
+    campaignId?: string;
+}
+export interface WidgetAccount {
+    /** The site's traffic source, which splits revenue per site. */
+    trs: string;
+    /** The Travelpayouts marker. */
+    marker: string;
+}
+export type WidgetOptions = {
+    kind: 'hotel';
+    direction: string;
+} | {
+    kind: 'activity';
+    place: string;
+} | {
+    kind: 'train';
+} | {
+    kind: 'car';
+    country: string;
+    city: string;
+    colors: {
+        background: string;
+        font: string;
+        button: string;
+        buttonFont: string;
+    };
+    buttonText?: string;
+};
+/**
+ * A Travelpayouts widget loader URL. Each kind keeps the parameter order Travelpayouts issued, which differs per kind
+ * (hotel puts promo_id before campaign_id, activity and car after).
+ */
+export declare function travelpayoutsWidgetSrc(loader: WidgetLoader, account: WidgetAccount, options: WidgetOptions): string;

package/dist/affiliate/travelpayouts.js

@@ -0,0 +1,33 @@
+/**
+ * A Travelpayouts widget loader URL. Each kind keeps the parameter order Travelpayouts issued, which differs per kind
+ * (hotel puts promo_id before campaign_id, activity and car after).
+ */
+export function travelpayoutsWidgetSrc(loader, account, options) {
+    const ids = (order) => {
+        const promo = ['promo_id', loader.promoId];
+        const campaign = loader.campaignId ? [['campaign_id', loader.campaignId]] : [];
+        return order === 'promo-first' ? [promo, ...campaign] : [...campaign, promo];
+    };
+    const who = [['trs', account.trs], ['shmarker', account.marker]];
+    let pairs;
+    switch (options.kind) {
+        case 'hotel':
+            pairs = [...who, ['locale', 'en'], ['default_direction', options.direction], ['sustainable', 'false'], ['deals', 'false'],
+                ['border_radius', '5'], ['plain', 'true'], ['powered_by', 'true'], ...ids('promo-first')];
+            break;
+        case 'activity':
+            pairs = [...who, ['place', options.place], ['items', '3'], ['locale', 'en-US'], ['powered_by', 'true'], ...ids('campaign-first')];
+            break;
+        case 'train':
+            pairs = [['currency', 'USD'], ...who, ['powered_by', 'true'], ['locale', 'en'], ['mode', 'default'], ['theme', 'white'],
+                ['layout', 'fluid'], ...ids('promo-first')];
+            break;
+        case 'car':
+            pairs = [['currency', 'usd'], ...who, ['country', options.country], ['city', options.city], ['locale', 'en'], ['powered_by', 'true'],
+                ['bg_color', options.colors.background], ['font_color', options.colors.font], ['button_color', options.colors.button],
+                ['button_font_color', options.colors.buttonFont], ['button_text', options.buttonText ?? 'Search'], ['rounded_corners', 'true'],
+                ['benefits', 'true'], ['dc_powered_by', 'false'], ['supplier_logos', 'false'], ...ids('campaign-first')];
+            break;
+    }
+    return `${loader.url}?${pairs.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')}`;
+}

package/dist/config/siteConfig.js

@@ -6,6 +6,7 @@ import sitemap, {} from '@astrojs/sitemap';
 import { outboundLinkRel } from "./outboundLinkRel.js";
 import { guideDateMap } from "./guideDates.js";
 import { EPOCH } from "../dates/lastmod.js";
+import { VARIANTS_DIR } from "../images/index.js";
 /** What Pagefind leaves out of the index on every site: site chrome, breadcrumbs and anything marked ignore. */
 export const PAGEFIND_EXCLUDE_SELECTORS = ['nav', 'footer', '.breadcrumb', '[data-pagefind-ignore]'];
 // A date-only value is stamped at noon UTC, except today's at midnight: never in the future, and the same on every
@@ -116,14 +117,10 @@ export function defineSiteConfig(opts) {
         trailingSlash: 'never',
         compressHTML: true,
         image: {
+            // Never encodes: serves the committed variants in image-variants/ (npm run images:variants writes them).
             service: {
-                entrypoint: process.env.CI ? 'astro/assets/services/noop' : 'astro/assets/services/sharp',
-                config: {
-                    limitInputPixels: false,
-                    avif: { quality: 65, effort: 6, chromaSubsampling: '4:2:0' },
-                    // Astro re-encodes from decoded pixels, so the delivered quality is set here, not by the source file.
-                    webp: { quality: 65, effort: 6 },
-                },
+                entrypoint: '@sarimarcus/content-sites-core/images/service',
+                config: { variantsDir: path.join(rootDir, VARIANTS_DIR) },
             },
         },
         build: {

package/dist/images/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/images/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// content-sites-image-variants [--check] [--root=<site dir>]
+//   (default)  write missing variants, prune unused ones, rewrite the manifest
+//   --check    the pre-push gate: exit 1 when any eligible source lacks a variant
+import { resolve } from 'node:path';
+import { VARIANTS_DIR } from "./index.js";
+import { checkVariants, generateVariants, workingTree } from "./variants.js";
+const args = process.argv.slice(2);
+const unknown = args.filter((a) => a !== '--check' && !a.startsWith('--root='));
+if (unknown.length) {
+    console.error(`unknown argument(s): ${unknown.join(' ')}\nUsage: content-sites-image-variants [--check] [--root=<site dir>]`);
+    process.exit(2);
+}
+const root = resolve(args.find((a) => a.startsWith('--root='))?.slice('--root='.length) ?? process.cwd());
+try {
+    if (args.includes('--check')) {
+        const r = checkVariants(workingTree(root));
+        if (!r.sources) {
+            console.error(`✗ no eligible images under ${root}/src/assets — nothing examined, not a pass`);
+            process.exit(1);
+        }
+        if (r.orphans.length)
+            console.warn(`⚠ ${r.orphans.length} unused variant file(s) in ${VARIANTS_DIR}/ — npm run images:variants prunes them`);
+        if (r.problems.length) {
+            for (const p of r.problems.slice(0, 50))
+                console.error(`  ${p}`);
+            if (r.problems.length > 50)
+                console.error(`  … and ${r.problems.length - 50} more`);
+            console.error(`✗ ${r.problems.length} image variant problem(s) across ${r.sources} source(s) — run \`npm run images:variants\` and commit ${VARIANTS_DIR}/`);
+            process.exit(1);
+        }
+        console.log(`✓ ${r.sources} source image(s) checked, ${r.variants} committed variant(s) present`);
+    }
+    else {
+        const r = await generateVariants(root, (line) => console.log(line));
+        console.log(`✓ ${r.sources} source image(s): ${r.written} variant(s) written, ${r.kept} already present, ${r.pruned} pruned`);
+    }
+}
+catch (err) {
+    console.error(`✗ ${err.message}`);
+    process.exit(1);
+}

package/dist/images/index.d.ts

@@ -0,0 +1,24 @@
+/** The one width ladder every responsive image uses. WebP only. Not frozen: Astro sorts `widths` in place. */
+export declare const IMAGE_LADDER: number[];
+/** Where a site keeps its committed variants, relative to the site root. */
+export declare const VARIANTS_DIR = "image-variants";
+export declare const MANIFEST_FILE = "manifest.json";
+/** Directories under src/assets whose images get no variants (galleries). */
+export declare const EXCLUDED_DIR: RegExp;
+export interface VariantEntry {
+    w: number;
+    h: number;
+    fmt: string;
+    /** Widths with a committed file. */
+    rungs: number[];
+    /** Paths relative to src/assets that share these bytes. */
+    src: string[];
+}
+export type VariantManifest = Record<string, VariantEntry>;
+/** The srcset widths for an image `native` px wide: the rungs below it, then the native width. */
+export declare function ladderWidths(native: number): number[];
+/** The width actually delivered for a requested width: the smallest srcset entry at least that wide. */
+export declare function snapWidth(requested: number, native: number): number;
+/** The widths that need a committed file; the native entry is served from the source bytes when it is WebP. */
+export declare function variantRungs(native: number, format: string): number[];
+export declare function variantFileName(sha: string, width: number): string;

package/dist/images/index.js

@@ -0,0 +1,23 @@
+/** The one width ladder every responsive image uses. WebP only. Not frozen: Astro sorts `widths` in place. */
+export const IMAGE_LADDER = [320, 480, 640, 960, 1280];
+/** Where a site keeps its committed variants, relative to the site root. */
+export const VARIANTS_DIR = 'image-variants';
+export const MANIFEST_FILE = 'manifest.json';
+/** Directories under src/assets whose images get no variants (galleries). */
+export const EXCLUDED_DIR = /(^|\/)([^/]*-)?gallery(\/|$)/;
+/** The srcset widths for an image `native` px wide: the rungs below it, then the native width. */
+export function ladderWidths(native) {
+    return [...IMAGE_LADDER.filter((w) => w < native), native];
+}
+/** The width actually delivered for a requested width: the smallest srcset entry at least that wide. */
+export function snapWidth(requested, native) {
+    return ladderWidths(native).find((w) => w >= requested) ?? native;
+}
+/** The widths that need a committed file; the native entry is served from the source bytes when it is WebP. */
+export function variantRungs(native, format) {
+    const widths = ladderWidths(native);
+    return format === 'webp' ? widths.slice(0, -1) : widths;
+}
+export function variantFileName(sha, width) {
+    return `${sha}-${width}.webp`;
+}

package/dist/images/service.d.ts

@@ -0,0 +1,7 @@
+import type { LocalImageService } from 'astro';
+export interface VariantServiceConfig {
+    /** Absolute path to the site's committed variants. */
+    variantsDir: string;
+}
+declare const service: LocalImageService<VariantServiceConfig>;
+export default service;

package/dist/images/service.js

@@ -0,0 +1,85 @@
+// Astro image service for production builds: never encodes. It returns the committed variants the
+// generator wrote (variants.ts) and the source bytes for the native width, so CI stays as fast as noop
+// while srcset entries point at genuinely different files.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { baseService } from 'astro/assets';
+import { MANIFEST_FILE, ladderWidths, snapWidth, variantFileName } from "./index.js";
+import { parseManifest, sourceSha } from "./variants.js";
+const manifests = new Map();
+function manifestFor(dir) {
+    let manifest = manifests.get(dir);
+    if (!manifest) {
+        const file = join(dir, MANIFEST_FILE);
+        manifest = parseManifest(existsSync(file) ? readFileSync(file, 'utf-8') : null, file);
+        manifests.set(dir, manifest);
+    }
+    return manifest;
+}
+// getImage hands getSrcSet a clone of the import without its fsPath, so coverage is matched on file stem + size.
+const coverKey = (stem, w, h) => `${stem}|${w}x${h}`;
+const covered = new Map();
+function isCovered(dir, src) {
+    let set = covered.get(dir);
+    if (!set) {
+        set = new Set(Object.values(manifestFor(dir)).flatMap((e) => e.src.map((rel) => coverKey(basename(rel).replace(/\.[^.]+$/, ''), e.w, e.h))));
+        covered.set(dir, set);
+    }
+    // Built: /_astro/<stem>.<hash>.webp; dev: /@fs/…/<stem>.webp?origWidth=…
+    const file = basename(src.src.split('?')[0]).replace(/\.[^.]+$/, '');
+    return set.has(coverKey(file, src.width, src.height)) || set.has(coverKey(file.replace(/\.[^.]+$/, ''), src.width, src.height));
+}
+const isImported = (src) => typeof src === 'object' && src !== null;
+const service = {
+    ...baseService,
+    propertiesToHash: ['src', 'width', 'format'],
+    async validateOptions(options, imageConfig, logger) {
+        if (isImported(options.src) && options.src.format === 'svg') {
+            options.format = 'svg';
+            return options;
+        }
+        if (options.format && options.format !== 'webp') {
+            throw new Error(`Image format "${options.format}" is not served: the variant service delivers WebP only (src: ${isImported(options.src) ? options.src.src : options.src}).`);
+        }
+        options.format = 'webp';
+        return baseService.validateOptions(options, imageConfig, logger);
+    },
+    // Passing `widths` (always IMAGE_LADDER) asks for a responsive image; the entries come from the ladder, capped at the source.
+    // An image with no variants (a gallery) gets no srcset rather than one that repeats a single file.
+    getSrcSet(options, imageConfig) {
+        if (!options.widths?.length || !isImported(options.src))
+            return [];
+        if (!isCovered(imageConfig.service.config.variantsDir, options.src))
+            return [];
+        const { width: native, height } = options.src;
+        const { width: _w, height: _h, widths: _ws, densities: _d, ...rest } = options;
+        return ladderWidths(native).map((width) => ({
+            transform: { ...rest, width, height: Math.round((width * height) / native) },
+            descriptor: `${width}w`,
+            attributes: { type: 'image/webp' },
+        }));
+    },
+    async transform(inputBuffer, transform, imageConfig, logger) {
+        const format = transform.format;
+        if (format === 'svg')
+            return { data: inputBuffer, format };
+        const dir = imageConfig.service.config.variantsDir;
+        const sha = sourceSha(inputBuffer);
+        const entry = manifestFor(dir)[sha];
+        if (!entry) {
+            // A gallery (excluded by design), or an image nobody ran images:variants for; the push gate refuses the latter.
+            logger.warn(`no variants for ${transform.src}; serving the source bytes`);
+            return { data: inputBuffer, format };
+        }
+        // An off-ladder width (an avatar's width={64}) keeps its HTML attributes and gets the next file up.
+        const width = snapWidth(Number(transform.width) || entry.w, entry.w);
+        if (width >= entry.w && entry.fmt === 'webp')
+            return { data: inputBuffer, format };
+        const file = join(dir, variantFileName(sha, width));
+        if (!existsSync(file)) {
+            throw new Error(`Missing image variant ${variantFileName(sha, width)} for ${entry.src.join(', ')} — run \`npm run images:variants\` and commit ${dir}.`);
+        }
+        return { data: readFileSync(file), format };
+    },
+};
+export default service;

package/dist/images/variants.d.ts

@@ -0,0 +1,45 @@
+import { type VariantManifest } from './index.ts';
+/** Matches the WebP settings the sharp service used, so variants look like what the site served before noop. */
+export declare const VARIANT_WEBP: {
+    readonly quality: 65;
+    readonly effort: 6;
+};
+export interface SourceImage {
+    /** Path relative to src/assets, always with forward slashes. */
+    rel: string;
+    sha: string;
+    bytes: Buffer;
+}
+/** Whether a path under src/assets gets variants: a raster image outside any gallery directory. */
+export declare function isEligibleSource(rel: string): boolean;
+export declare function listSources(siteRoot: string): string[];
+export declare const sourceSha: (bytes: Uint8Array) => string;
+export declare function readSource(siteRoot: string, rel: string): SourceImage;
+export declare function parseManifest(text: string | null, where: string): VariantManifest;
+export declare function readManifest(siteRoot: string): VariantManifest;
+/** What the gate reads: the working tree (the CLI) or a pushed commit (the site pre-push hook). */
+export interface VariantTree {
+    /** Eligible source paths relative to src/assets. */
+    sources(): string[];
+    sourceBytes(rel: string): Uint8Array;
+    manifestText(): string | null;
+    /** File names present in the variants directory. */
+    variantFiles(): string[];
+}
+export declare function workingTree(siteRoot: string): VariantTree;
+export interface GenerateResult {
+    sources: number;
+    written: number;
+    kept: number;
+    pruned: number;
+}
+/** Write every missing variant, rebuild the manifest, and delete variants no source needs any more. */
+export declare function generateVariants(siteRoot: string, log?: (line: string) => void): Promise<GenerateResult>;
+export interface CheckResult {
+    sources: number;
+    variants: number;
+    problems: string[];
+    orphans: string[];
+}
+/** The gate: every eligible source is in the manifest and every rung it needs has a committed file. */
+export declare function checkVariants(tree: VariantTree): CheckResult;