@sarimarcus/content-sites-core 0.20.0 → 0.22.0

package/dist/images/variants.js

@@ -0,0 +1,145 @@
+// The local generator and the gate for committed image variants. sharp is loaded only here, from the
+// site's own install (Astro ships it), so CI never needs it.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { availableParallelism } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { EXCLUDED_DIR, MANIFEST_FILE, VARIANTS_DIR, variantFileName, variantRungs, } from "./index.js";
+const SOURCE_EXT = /\.(webp|jpe?g|png|avif|tiff?)$/i;
+/** Matches the WebP settings the sharp service used, so variants look like what the site served before noop. */
+export const VARIANT_WEBP = { quality: 65, effort: 6 };
+/** Whether a path under src/assets gets variants: a raster image outside any gallery directory. */
+export function isEligibleSource(rel) {
+    return SOURCE_EXT.test(rel) && !EXCLUDED_DIR.test(rel) && !rel.split('/').some((seg) => seg.startsWith('.'));
+}
+export function listSources(siteRoot) {
+    const assets = join(siteRoot, 'src', 'assets');
+    if (!existsSync(assets))
+        throw new Error(`no src/assets directory under ${siteRoot}`);
+    const out = [];
+    const walk = (dir) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const abs = join(dir, e.name);
+            if (e.isDirectory())
+                walk(abs);
+            else
+                out.push(relative(assets, abs).split(sep).join('/'));
+        }
+    };
+    walk(assets);
+    return out.filter(isEligibleSource).sort();
+}
+export const sourceSha = (bytes) => createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+export function readSource(siteRoot, rel) {
+    const bytes = readFileSync(join(siteRoot, 'src', 'assets', rel));
+    return { rel, bytes, sha: sourceSha(bytes) };
+}
+export function parseManifest(text, where) {
+    if (text === null)
+        return {};
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error(`${where} is not a variant manifest object`);
+    return parsed;
+}
+export function readManifest(siteRoot) {
+    return parseManifest(workingTree(siteRoot).manifestText(), join(siteRoot, VARIANTS_DIR, MANIFEST_FILE));
+}
+export function workingTree(siteRoot) {
+    const dir = join(siteRoot, VARIANTS_DIR);
+    return {
+        sources: () => listSources(siteRoot),
+        sourceBytes: (rel) => readFileSync(join(siteRoot, 'src', 'assets', rel)),
+        manifestText: () => (existsSync(join(dir, MANIFEST_FILE)) ? readFileSync(join(dir, MANIFEST_FILE), 'utf-8') : null),
+        variantFiles: () => (existsSync(dir) ? readdirSync(dir) : []),
+    };
+}
+async function pool(items, fn) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length)
+            await fn(items[next++]);
+    };
+    await Promise.all(Array.from({ length: Math.min(items.length, availableParallelism()) }, worker));
+}
+/** Write every missing variant, rebuild the manifest, and delete variants no source needs any more. */
+export async function generateVariants(siteRoot, log = () => { }) {
+    const { default: sharp } = (await import('sharp'));
+    const dir = join(siteRoot, VARIANTS_DIR);
+    mkdirSync(dir, { recursive: true });
+    const previous = readManifest(siteRoot);
+    const manifest = {};
+    const rels = listSources(siteRoot);
+    let written = 0;
+    let kept = 0;
+    await pool(rels, async (rel) => {
+        const source = readSource(siteRoot, rel);
+        const shared = manifest[source.sha];
+        if (shared) {
+            shared.src.push(rel);
+            return;
+        }
+        // Reserve the sha before any await, so a duplicate file in another worker joins this entry.
+        const entry = { w: 0, h: 0, fmt: '', rungs: [], src: [rel] };
+        manifest[source.sha] = entry;
+        const known = previous[source.sha];
+        if (known) {
+            Object.assign(entry, { w: known.w, h: known.h, fmt: known.fmt, rungs: variantRungs(known.w, known.fmt) });
+        }
+        else {
+            const meta = await sharp(source.bytes).metadata();
+            Object.assign(entry, { w: meta.width, h: meta.height, fmt: meta.format, rungs: variantRungs(meta.width, meta.format) });
+        }
+        for (const width of entry.rungs) {
+            const file = join(dir, variantFileName(source.sha, width));
+            if (existsSync(file)) {
+                kept++;
+                continue;
+            }
+            writeFileSync(file, await sharp(source.bytes).resize({ width }).webp(VARIANT_WEBP).toBuffer());
+            written++;
+            log(`+ ${variantFileName(source.sha, width)}  ${rel}`);
+        }
+    });
+    const wanted = new Set(Object.entries(manifest).flatMap(([sha, e]) => e.rungs.map((w) => variantFileName(sha, w))));
+    let pruned = 0;
+    for (const name of readdirSync(dir)) {
+        if (name === MANIFEST_FILE || wanted.has(name))
+            continue;
+        rmSync(join(dir, name));
+        pruned++;
+        log(`- ${name}`);
+    }
+    const sorted = {};
+    for (const sha of Object.keys(manifest).sort())
+        sorted[sha] = { ...manifest[sha], src: manifest[sha].src.sort() };
+    writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(sorted, null, 2)}\n`);
+    return { sources: rels.length, written, kept, pruned };
+}
+/** The gate: every eligible source is in the manifest and every rung it needs has a committed file. */
+export function checkVariants(tree) {
+    const manifest = parseManifest(tree.manifestText(), `${VARIANTS_DIR}/${MANIFEST_FILE}`);
+    const present = new Set(tree.variantFiles());
+    const rels = tree.sources();
+    const problems = [];
+    const needed = new Set();
+    let variants = 0;
+    for (const rel of rels) {
+        const sha = sourceSha(tree.sourceBytes(rel));
+        const entry = manifest[sha];
+        if (!entry) {
+            problems.push(`${rel}: not in ${VARIANTS_DIR}/${MANIFEST_FILE} (new or changed image)`);
+            continue;
+        }
+        for (const width of variantRungs(entry.w, entry.fmt)) {
+            const name = variantFileName(sha, width);
+            needed.add(name);
+            if (present.has(name))
+                variants++;
+            else
+                problems.push(`${rel}: missing ${VARIANTS_DIR}/${name}`);
+        }
+    }
+    const orphans = [...present].filter((n) => n !== MANIFEST_FILE && !needed.has(n));
+    return { sources: rels.length, variants, problems, orphans };
+}

package/dist/interludes/index.d.ts

@@ -28,8 +28,8 @@ type ZodBuilders = Pick<typeof Zod, 'discriminatedUnion' | 'object' | 'literal'
 export declare function createInterludeSchema(z: ZodBuilders, config: InterludeSchemaConfig): Zod.ZodDiscriminatedUnion<[Zod.ZodObject<{
     type: Zod.ZodLiteral<"quote">;
     variant: Zod.ZodEnum<{
-        pull: "pull";
         external: "external";
+        pull: "pull";
     }>;
     content: Zod.ZodString;
     attribution: Zod.ZodOptional<Zod.ZodObject<{

package/dist/url/index.d.ts

@@ -4,3 +4,4 @@ export { normalizeHref, extractProseHrefs, dedupRelated } from './relatedDedup.t
 export { buildImageMap, keyBySlug } from './imageMap.ts';
 export { articleFeedItem } from './feed.ts';
 export type { FeedArticle, FeedItem } from './feed.ts';
+export { pageTypeOf } from './pageType.ts';

package/dist/url/index.js

@@ -4,3 +4,4 @@ export { getOgImagePath } from "./ogImage.js";
 export { normalizeHref, extractProseHrefs, dedupRelated } from "./relatedDedup.js";
 export { buildImageMap, keyBySlug } from "./imageMap.js";
 export { articleFeedItem } from "./feed.js";
+export { pageTypeOf } from "./pageType.js";

package/dist/url/pageType.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Page type: the first path segment, 'home' at the root.
+ *
+ * The single definition behind both the GA4 `page_type` param (runtime pathname, '/plan/x') and a site's GYG `cmp`
+ * segment (BUILD-time `Astro.url.pathname`, '/index.html' under build.format 'file'). The `.html`/`index`
+ * normalisation is what makes the two agree.
+ */
+export declare function pageTypeOf(pathname: string): string;

package/dist/url/pageType.js

@@ -0,0 +1,14 @@
+/**
+ * Page type: the first path segment, 'home' at the root.
+ *
+ * The single definition behind both the GA4 `page_type` param (runtime pathname, '/plan/x') and a site's GYG `cmp`
+ * segment (BUILD-time `Astro.url.pathname`, '/index.html' under build.format 'file'). The `.html`/`index`
+ * normalisation is what makes the two agree.
+ */
+export function pageTypeOf(pathname) {
+    const first = pathname.split('/').filter(Boolean)[0];
+    if (!first)
+        return 'home';
+    const bare = first.replace(/\.html$/, '');
+    return bare === 'index' || bare === '' ? 'home' : bare;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-core",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,10 @@
       "types": "./dist/url/index.d.ts",
       "default": "./dist/url/index.js"
     },
+    "./affiliate": {
+      "types": "./dist/affiliate/index.d.ts",
+      "default": "./dist/affiliate/index.js"
+    },
     "./dates": {
       "types": "./dist/dates/index.d.ts",
       "default": "./dist/dates/index.js"
@@ -65,14 +69,35 @@
     "./interludes": {
       "types": "./dist/interludes/index.d.ts",
       "default": "./dist/interludes/index.js"
+    },
+    "./images": {
+      "types": "./dist/images/index.d.ts",
+      "default": "./dist/images/index.js"
+    },
+    "./images/service": {
+      "types": "./dist/images/service.d.ts",
+      "default": "./dist/images/service.js"
+    },
+    "./images/variants": {
+      "types": "./dist/images/variants.d.ts",
+      "default": "./dist/images/variants.js"
     }
   },
+  "bin": {
+    "content-sites-image-variants": "./dist/images/cli.js"
+  },
   "dependencies": {
     "marked": "^18.0.14"
   },
   "peerDependencies": {
     "astro": "^7.0.6",
     "@astrojs/sitemap": "^3.7.4",
-    "@tailwindcss/vite": "~4.3.3"
+    "@tailwindcss/vite": "~4.3.3",
+    "sharp": ">=0.34.0"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
   }
 }

package/src/affiliate/gyg.ts

@@ -0,0 +1,66 @@
+import { pageTypeOf } from '../url/pageType.ts';
+
+const GYG_HOST = /(^|\.)getyourguide\.com$/;
+
+/** GetYourGuide product id: the `-t<digits>` segment of a tour URL. */
+export function gygProductId(url: string): string {
+  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: string): string {
+  return raw.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+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 function createGygCmp(siteKey: string): GygCmp {
+  function withGygCmp(href: string, pathname: string, placement: string): string {
+    let u: URL;
+    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: string, pathname: string, placement = 'prose'): string {
+    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: string) => `href="${withGygCmp(href.replace(/&amp;/g, '&'), pathname, placement).replace(/&(?!amp;|lt;|gt;|quot;|apos;|#\d)/g, '&amp;')}"`,
+    );
+  }
+
+  return { withGygCmp, tagGygLinksInHtml };
+}

package/src/affiliate/index.ts

@@ -0,0 +1,7 @@
+// Public surface of @sarimarcus/content-sites-core/affiliate.
+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/src/affiliate/links.ts

@@ -0,0 +1,35 @@
+/** 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: string, tag?: string): string {
+  const base = `https://www.amazon.com/dp/${asin}`;
+  return tag === undefined ? base : `${base}/?${new URLSearchParams({ tag })}`;
+}
+
+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 function bookingSearchUrl({ ss, destId, destType = 'city', checkin, checkout }: BookingSearch): string {
+  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/src/affiliate/travelpayouts.ts

@@ -0,0 +1,62 @@
+/** 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;
+    };
+
+type Pair = [string, 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 function travelpayoutsWidgetSrc(loader: WidgetLoader, account: WidgetAccount, options: WidgetOptions): string {
+  const ids = (order: 'promo-first' | 'campaign-first'): Pair[] => {
+    const promo: Pair = ['promo_id', loader.promoId];
+    const campaign: Pair[] = loader.campaignId ? [['campaign_id', loader.campaignId]] : [];
+    return order === 'promo-first' ? [promo, ...campaign] : [...campaign, promo];
+  };
+  const who: Pair[] = [['trs', account.trs], ['shmarker', account.marker]];
+  let pairs: Pair[];
+  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/src/config/siteConfig.ts

@@ -8,6 +8,7 @@ import { outboundLinkRel } from './outboundLinkRel.ts';
 import { guideDateMap } from './guideDates.ts';
 
 import { EPOCH } from '../dates/lastmod.ts';
+import { VARIANTS_DIR } from '../images/index.ts';
 
 export interface SitemapRule {
   match: (parts: string[]) => boolean;
@@ -148,14 +149,10 @@ export function defineSiteConfig(opts: SiteConfigOptions): AstroUserConfig {
     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/src/images/cli.ts

@@ -0,0 +1,39 @@
+#!/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.ts';
+import { checkVariants, generateVariants, workingTree } from './variants.ts';
+
+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 as Error).message}`);
+  process.exit(1);
+}

package/src/images/index.ts

@@ -0,0 +1,41 @@
+/** The one width ladder every responsive image uses. WebP only. Not frozen: Astro sorts `widths` in place. */
+export const IMAGE_LADDER: number[] = [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(\/|$)/;
+
+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 function ladderWidths(native: number): number[] {
+  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: number, native: number): number {
+  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: number, format: string): number[] {
+  const widths = ladderWidths(native);
+  return format === 'webp' ? widths.slice(0, -1) : widths;
+}
+
+export function variantFileName(sha: string, width: number): string {
+  return `${sha}-${width}.webp`;
+}

package/src/images/service.ts

@@ -0,0 +1,95 @@
+// 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 type { ImageMetadata, ImageOutputFormat, LocalImageService } from 'astro';
+import { MANIFEST_FILE, ladderWidths, snapWidth, variantFileName, type VariantManifest } from './index.ts';
+import { parseManifest, sourceSha } from './variants.ts';
+
+export interface VariantServiceConfig {
+  /** Absolute path to the site's committed variants. */
+  variantsDir: string;
+}
+
+const manifests = new Map<string, VariantManifest>();
+function manifestFor(dir: string): VariantManifest {
+  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: string, w: number, h: number) => `${stem}|${w}x${h}`;
+const covered = new Map<string, Set<string>>();
+function isCovered(dir: string, src: ImageMetadata): boolean {
+  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: unknown): src is ImageMetadata => typeof src === 'object' && src !== null;
+
+const service: LocalImageService<VariantServiceConfig> = {
+  ...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 as ImageOutputFormat;
+    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;