@sarimarcus/content-sites-core 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 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`, `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/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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-core",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -65,14 +65,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/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;

package/src/images/variants.ts

@@ -0,0 +1,179 @@
+// 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,
+  type VariantEntry, type VariantManifest,
+} from './index.ts';
+
+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 } as const;
+
+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 function isEligibleSource(rel: string): boolean {
+  return SOURCE_EXT.test(rel) && !EXCLUDED_DIR.test(rel) && !rel.split('/').some((seg) => seg.startsWith('.'));
+}
+
+export function listSources(siteRoot: string): string[] {
+  const assets = join(siteRoot, 'src', 'assets');
+  if (!existsSync(assets)) throw new Error(`no src/assets directory under ${siteRoot}`);
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    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: Uint8Array): string => createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+
+export function readSource(siteRoot: string, rel: string): SourceImage {
+  const bytes = readFileSync(join(siteRoot, 'src', 'assets', rel));
+  return { rel, bytes, sha: sourceSha(bytes) };
+}
+
+export function parseManifest(text: string | null, where: string): VariantManifest {
+  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 as VariantManifest;
+}
+
+export function readManifest(siteRoot: string): VariantManifest {
+  return parseManifest(workingTree(siteRoot).manifestText(), join(siteRoot, VARIANTS_DIR, MANIFEST_FILE));
+}
+
+/** 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 function workingTree(siteRoot: string): VariantTree {
+  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<T>(items: T[], fn: (item: T) => Promise<void>): Promise<void> {
+  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));
+}
+
+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 async function generateVariants(siteRoot: string, log: (line: string) => void = () => {}): Promise<GenerateResult> {
+  const { default: sharp } = (await import('sharp')) as { default: any };
+  const dir = join(siteRoot, VARIANTS_DIR);
+  mkdirSync(dir, { recursive: true });
+  const previous = readManifest(siteRoot);
+  const manifest: VariantManifest = {};
+  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: VariantEntry = { 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: VariantManifest = {};
+  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 };
+}
+
+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 function checkVariants(tree: VariantTree): CheckResult {
+  const manifest = parseManifest(tree.manifestText(), `${VARIANTS_DIR}/${MANIFEST_FILE}`);
+  const present = new Set(tree.variantFiles());
+  const rels = tree.sources();
+  const problems: string[] = [];
+  const needed = new Set<string>();
+  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 };
+}