@caelo-cms/shared 0.10.22 → 0.10.23

package/src/preview-scanner.test.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { applySlotReplacements } from "./preview-scanner.js";
+
+const map = (entries: [string, string][]) => new Map(entries);
+
+describe("applySlotReplacements", () => {
+  it("returns input unchanged when there are no slots", () => {
+    const html = "<html><body><h1>Static</h1></body></html>";
+    const result = applySlotReplacements(html, { contentByName: map([]) });
+    expect(result.html).toBe(html);
+    expect(result.replacedSlots).toEqual([]);
+    expect(result.missingSlots).toEqual([]);
+  });
+
+  it("replaces a single named slot's inner HTML", () => {
+    const html = `<body><caelo-slot name="content">placeholder</caelo-slot></body>`;
+    const result = applySlotReplacements(html, {
+      contentByName: map([["content", "<p>HELLO</p>"]]),
+    });
+    expect(result.html).toBe(`<body><caelo-slot name="content"><p>HELLO</p></caelo-slot></body>`);
+    expect(result.replacedSlots).toEqual(["content"]);
+  });
+
+  it("preserves the slot wrapper so CSS selectors still match", () => {
+    const html = `<caelo-slot name="x"></caelo-slot>`;
+    const result = applySlotReplacements(html, { contentByName: map([["x", "FILLED"]]) });
+    expect(result.html).toBe(`<caelo-slot name="x">FILLED</caelo-slot>`);
+  });
+
+  it("replaces multiple slots in order", () => {
+    const html = `<caelo-slot name="header">_</caelo-slot><caelo-slot name="footer">_</caelo-slot>`;
+    const result = applySlotReplacements(html, {
+      contentByName: map([
+        ["header", "TOP"],
+        ["footer", "BOT"],
+      ]),
+    });
+    expect(result.html).toBe(
+      `<caelo-slot name="header">TOP</caelo-slot><caelo-slot name="footer">BOT</caelo-slot>`,
+    );
+    expect(result.replacedSlots).toEqual(["header", "footer"]);
+  });
+
+  it("records slots without a replacement and preserves their original inner HTML", () => {
+    const html = `<caelo-slot name="missing">DEFAULT</caelo-slot>`;
+    const result = applySlotReplacements(html, { contentByName: map([]) });
+    expect(result.html).toBe(`<caelo-slot name="missing">DEFAULT</caelo-slot>`);
+    expect(result.missingSlots).toEqual(["missing"]);
+  });
+
+  it("handles single-quoted name attributes", () => {
+    const html = `<caelo-slot name='content'>x</caelo-slot>`;
+    const result = applySlotReplacements(html, { contentByName: map([["content", "Y"]]) });
+    expect(result.html).toBe(`<caelo-slot name='content'>Y</caelo-slot>`);
+  });
+
+  it("throws on an unterminated slot opener", () => {
+    expect(() =>
+      applySlotReplacements(`<caelo-slot name="x">no close`, { contentByName: map([]) }),
+    ).toThrow(/unterminated/);
+  });
+
+  it("throws on a nested slot", () => {
+    const html = `<caelo-slot name="a"><caelo-slot name="b">y</caelo-slot></caelo-slot>`;
+    expect(() => applySlotReplacements(html, { contentByName: map([]) })).toThrow(/nested/);
+  });
+
+  it("leaves bytes outside slots unchanged", () => {
+    const before = `<!doctype html><html lang="en"><head><title>T</title></head><body>`;
+    const after = `</body></html>`;
+    const html = `${before}<caelo-slot name="x">_</caelo-slot>${after}`;
+    const result = applySlotReplacements(html, { contentByName: map([["x", "Y"]]) });
+    expect(result.html).toBe(`${before}<caelo-slot name="x">Y</caelo-slot>${after}`);
+  });
+
+  it("ignores caelo-slot inside an HTML comment", () => {
+    // The regex-based version mistakenly treated this as a real slot. The
+    // parser-based version ignores everything inside <!-- … -->.
+    const html = `<!-- <caelo-slot name="ghost">x</caelo-slot> --><caelo-slot name="real">_</caelo-slot>`;
+    const result = applySlotReplacements(html, { contentByName: map([["real", "Y"]]) });
+    expect(result.html).toBe(
+      `<!-- <caelo-slot name="ghost">x</caelo-slot> --><caelo-slot name="real">Y</caelo-slot>`,
+    );
+    expect(result.replacedSlots).toEqual(["real"]);
+    expect(result.missingSlots).toEqual([]);
+  });
+
+  it("ignores caelo-slot mention inside an attribute value", () => {
+    const html = `<div data-doc="example: <caelo-slot name='fake'>"></div><caelo-slot name="real">_</caelo-slot>`;
+    const result = applySlotReplacements(html, { contentByName: map([["real", "Y"]]) });
+    expect(result.html).toContain(`<caelo-slot name="real">Y</caelo-slot>`);
+    expect(result.replacedSlots).toEqual(["real"]);
+  });
+});

package/src/preview-scanner.ts

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * `<caelo-slot name="…">…</caelo-slot>` scanner backed by `htmlparser2`'s
+ * Parser. Replaces the inner HTML of each named slot with caller-supplied
+ * content, leaving every byte outside the slots unchanged.
+ *
+ * Why a real parser: the previous regex-based version mishandled comments
+ * (`<!-- <caelo-slot> -->`), CDATA, and attributes containing `<`, and
+ * required hand-rolled "no nested slots" detection. htmlparser2 is MIT,
+ * tiny, and dependency-free — same parser the larger Cheerio/Jsdom-style
+ * tools use under the hood.
+ *
+ * Invariants preserved from the regex version:
+ *   - Bytes outside `<caelo-slot>` ranges are byte-stable in the output.
+ *   - The `<caelo-slot ...>` opening + closing tags themselves are
+ *     preserved (only inner HTML is replaced) so CSS selectors keep matching.
+ *   - Nested `<caelo-slot>` inside another `<caelo-slot>` is rejected.
+ *   - Unterminated openers are rejected.
+ */
+
+import { Parser } from "htmlparser2";
+
+const SLOT_TAG = "caelo-slot";
+
+/**
+ * P6.7.6 review pass — return the list of `<caelo-slot name="…">` slot
+ * names declared in `html`, in source order. Used by the layout-aware
+ * composer to validate that a layout declares the required `content`
+ * slot before rendering, so misconfigurations error loudly per the
+ * no-fallbacks invariant. Walks the same htmlparser2 Parser as
+ * `applySlotReplacements` so attribute quoting / ordering / whitespace
+ * are handled uniformly.
+ */
+export function listSlotNames(html: string): readonly string[] {
+  const names: string[] = [];
+  const parser = new Parser(
+    {
+      onopentag(name, attrs) {
+        if (name !== SLOT_TAG) return;
+        names.push(attrs.name ?? "");
+      },
+    },
+    { lowerCaseTags: true, recognizeSelfClosing: false },
+  );
+  parser.write(html);
+  parser.end();
+  return names;
+}
+
+/**
+ * P6.7.6 review pass — when a rendered template body is exactly one
+ * top-level `<caelo-slot name="content">…</caelo-slot>` element
+ * (typical of legacy templates whose body wraps the slot directly),
+ * peel the wrapper and return just its inner HTML. Returns `null` when
+ * the body has multiple top-level elements, no top-level content slot,
+ * or any other shape — so the caller can fall back to using the body
+ * as-is.
+ *
+ * Replaces the previous regex-based peel which silently failed on
+ * single-quote attributes, attribute reordering, or whitespace
+ * variations.
+ */
+export function extractInnerOfTopLevelContentSlot(html: string): string | null {
+  let depth = 0;
+  let topLevelOpens = 0;
+  let topLevelTextBetween = false;
+  let contentSlotInnerStart = -1;
+  let contentSlotInnerEnd = -1;
+  let foundContentSlot = false;
+  const parser = new Parser(
+    {
+      onopentag(name, attrs) {
+        if (depth === 0) {
+          topLevelOpens += 1;
+          if (name === SLOT_TAG && attrs.name === "content" && topLevelOpens === 1) {
+            foundContentSlot = true;
+            contentSlotInnerStart = parser.endIndex + 1;
+          }
+        }
+        depth += 1;
+      },
+      onclosetag(name) {
+        depth -= 1;
+        if (depth === 0 && name === SLOT_TAG && foundContentSlot && contentSlotInnerEnd === -1) {
+          contentSlotInnerEnd = parser.startIndex;
+        }
+      },
+      ontext(text) {
+        if (depth === 0 && text.trim().length > 0) topLevelTextBetween = true;
+      },
+    },
+    { lowerCaseTags: true, recognizeSelfClosing: false },
+  );
+  parser.write(html);
+  parser.end();
+  if (
+    !foundContentSlot ||
+    topLevelOpens !== 1 ||
+    topLevelTextBetween ||
+    contentSlotInnerStart === -1 ||
+    contentSlotInnerEnd === -1
+  ) {
+    return null;
+  }
+  return html.slice(contentSlotInnerStart, contentSlotInnerEnd);
+}
+
+export interface SlotReplacement {
+  /** Inner HTML for each `<caelo-slot name="…">`. */
+  readonly contentByName: ReadonlyMap<string, string>;
+}
+
+export interface ScanResult {
+  readonly html: string;
+  readonly replacedSlots: readonly string[];
+  readonly missingSlots: readonly string[];
+}
+
+interface SlotRange {
+  readonly name: string;
+  /** Byte offset just after the opening `>`. */
+  readonly innerStart: number;
+  /** Byte offset of the opening `<` of the closing tag. */
+  readonly innerEnd: number;
+}
+
+/**
+ * Returns a copy of `templateHtml` where each `<caelo-slot name="X">…</caelo-slot>`
+ * has its inner HTML replaced by `replacement.contentByName.get(X)`. Slots
+ * with no entry render with their original inner HTML preserved (so a
+ * template-author placeholder stays visible in the editor preview).
+ *
+ * Throws on nested or unbalanced slot markers — those are template-author
+ * bugs and silently smoothing them over would just defer the discovery.
+ */
+export function applySlotReplacements(
+  templateHtml: string,
+  replacement: SlotReplacement,
+): ScanResult {
+  const ranges: SlotRange[] = [];
+  let openName: string | null = null;
+  let openInnerStart = 0;
+  let openOpenStart = 0;
+
+  const parser = new Parser(
+    {
+      onopentag(name, attrs) {
+        if (name !== SLOT_TAG) return;
+        if (openName !== null) {
+          throw new Error(`nested <caelo-slot> not allowed (at offset ${parser.startIndex})`);
+        }
+        openName = attrs.name ?? "";
+        // `endIndex` of the opening tag points at the closing `>`; the inner
+        // HTML therefore starts one byte later.
+        openOpenStart = parser.startIndex;
+        openInnerStart = parser.endIndex + 1;
+      },
+      onclosetag(name) {
+        if (name !== SLOT_TAG) return;
+        if (openName === null) {
+          throw new Error(`closing </caelo-slot> with no opener (at offset ${parser.startIndex})`);
+        }
+        // htmlparser2 auto-closes unterminated tags at EOF — detect that case
+        // by verifying the source actually contains `</caelo-slot>` at the
+        // reported offset. Auto-closed tags fire onclosetag at EOF without a
+        // matching `</` in the input.
+        const hasExplicitClose = templateHtml
+          .slice(parser.startIndex, parser.startIndex + SLOT_TAG.length + 3)
+          .toLowerCase()
+          .startsWith(`</${SLOT_TAG}`);
+        if (!hasExplicitClose) {
+          throw new Error(
+            `unterminated <caelo-slot name="${openName}"> at offset ${openOpenStart}`,
+          );
+        }
+        ranges.push({
+          name: openName,
+          innerStart: openInnerStart,
+          innerEnd: parser.startIndex,
+        });
+        openName = null;
+      },
+    },
+    // recognizeSelfClosing handles `<caelo-slot name="x" />` style; we still
+    // require an explicit close tag so that case skips replacement (matches
+    // the documented "self-close passes through" limitation).
+    { lowerCaseTags: true, recognizeSelfClosing: false },
+  );
+  parser.write(templateHtml);
+  parser.end();
+
+  if (openName !== null) {
+    throw new Error(`unterminated <caelo-slot name="${openName}"> at offset ${openOpenStart}`);
+  }
+
+  const parts: string[] = [];
+  const replaced: string[] = [];
+  const missing: string[] = [];
+  let cursor = 0;
+  for (const range of ranges) {
+    parts.push(templateHtml.slice(cursor, range.innerStart));
+    if (replacement.contentByName.has(range.name)) {
+      parts.push(replacement.contentByName.get(range.name) ?? "");
+      replaced.push(range.name);
+    } else {
+      missing.push(range.name);
+      parts.push(templateHtml.slice(range.innerStart, range.innerEnd));
+    }
+    cursor = range.innerEnd;
+  }
+  parts.push(templateHtml.slice(cursor));
+  return { html: parts.join(""), replacedSlots: replaced, missingSlots: missing };
+}

package/src/proposal-status.test.ts

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Unit guards for the canonical propose/execute status enum. The
+ * load-bearing invariants: the four states never silently change order or
+ * membership when ~14 pending-op schemas migrate to this shared source, and
+ * the *proposal* enum never absorbs the semantically-different `"accepted"`
+ * review-status family (CLAUDE.md §11.A, plan Out-of-scope §3).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import { PROPOSAL_STATUSES, type ProposalStatus, proposalStatus } from "./proposal-status.js";
+
+describe("proposalStatus", () => {
+  it("has exactly the four states, in canonical order", () => {
+    expect(PROPOSAL_STATUSES).toEqual(["pending", "applied", "rejected", "superseded"]);
+    expect(proposalStatus.options).toEqual(["pending", "applied", "rejected", "superseded"]);
+  });
+
+  it("parses every member back to itself", () => {
+    for (const s of PROPOSAL_STATUSES) {
+      expect(proposalStatus.parse(s)).toBe(s);
+    }
+  });
+
+  it("rejects values outside the vocabulary (incl. the review-status family)", () => {
+    // "accepted" is the skill/ai-memory review vocabulary, NOT a proposal
+    // state — this guard is why the two enums must stay separate.
+    expect(proposalStatus.safeParse("accepted").success).toBe(false);
+    expect(proposalStatus.safeParse("draft").success).toBe(false);
+    expect(proposalStatus.safeParse("all").success).toBe(false);
+    expect(proposalStatus.safeParse("").success).toBe(false);
+  });
+
+  it("derives the documented domain variants without re-typing the 4-tuple", () => {
+    // locales list-filter: + "all"
+    expect(z.enum([...PROPOSAL_STATUSES, "all"] as const).options).toEqual([
+      "pending",
+      "applied",
+      "rejected",
+      "superseded",
+      "all",
+    ]);
+    // themes: + "cancelled"
+    expect(z.enum([...PROPOSAL_STATUSES, "cancelled"] as const).options).toEqual([
+      "pending",
+      "applied",
+      "rejected",
+      "superseded",
+      "cancelled",
+    ]);
+    // deploy proposals: no "superseded"
+    expect(proposalStatus.exclude(["superseded"]).options).toEqual([
+      "pending",
+      "applied",
+      "rejected",
+    ]);
+  });
+
+  it("exports a ProposalStatus type that is the union and nothing wider", () => {
+    const ok: ProposalStatus = "pending";
+    expect(ok).toBe("pending");
+    // @ts-expect-error "accepted" is not a ProposalStatus
+    const bad: ProposalStatus = "accepted";
+    // reference `bad` so the binding isn't elided before the ts-expect-error applies
+    expect(typeof bad).toBe("string");
+  });
+});

package/src/proposal-status.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Canonical status vocabulary for the propose/execute pattern (CLAUDE.md
+ * §11.A, `docs/propose-execute-pattern.md`). Every gated domain's
+ * `<domain>_pending_actions` row moves through these four states:
+ *
+ *   pending    — AI/Owner queued the proposal; awaiting a human click.
+ *   applied    — Owner approved; `execute_proposal` ran the real op.
+ *   rejected   — Owner declined (with an optional reason).
+ *   superseded — a newer proposal for the same target replaced this one
+ *                (dedup/GC), so it can never be approved.
+ *
+ * Lives in `@caelo-cms/shared` so the ~14 pending-op Zod schemas import one
+ * source instead of re-typing the literal — which is how the four states
+ * stay value-identical across every domain that adopted the pattern.
+ *
+ * Domains that need extra states extend this rather than re-typing it:
+ *   - list-filter ops add `"all"`:  `z.enum([...PROPOSAL_STATUSES, "all"] as const)`
+ *   - themes adds `"cancelled"`:    `z.enum([...PROPOSAL_STATUSES, "cancelled"] as const)`
+ *   - deploy proposals never get `"superseded"`: `proposalStatus.exclude(["superseded"])`
+ * Keep the `as const` on any spread so `z.enum` infers the literal union,
+ * not `string[]`.
+ *
+ * NOTE: this is NOT the vocabulary for skill/AI-memory *review* status
+ * (`accepted`/`rejected`) nor for deploy/translation *run* status
+ * (`running`/`succeeded`/…) — those are different value sets and must not
+ * be collapsed into this enum.
+ */
+
+import { z } from "zod";
+
+/** The four propose/execute states, in canonical order. */
+export const PROPOSAL_STATUSES = ["pending", "applied", "rejected", "superseded"] as const;
+
+/** Zod enum over {@link PROPOSAL_STATUSES} — the single source for every gated-domain `status` schema. */
+export const proposalStatus = z.enum(PROPOSAL_STATUSES);
+
+/** Union of the four propose/execute states. */
+export type ProposalStatus = z.infer<typeof proposalStatus>;

package/src/responsive-images.test.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #162 — shared responsive-image enrichment: production shape
+ * (src rewritten to _assets) vs preview shape (src kept on the admin
+ * media route), author precedence, and the two-entry ladder rule.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  enrichResponsiveImages,
+  type ImageVariantInfo,
+  pickAiImageVariant,
+} from "./responsive-images.js";
+
+const ASSET = "12345678-1234-4123-8123-123456789abc";
+const VARIANTS: ImageVariantInfo[] = [
+  { variant: "webp-400", format: "webp" },
+  { variant: "webp-800", format: "webp" },
+  { variant: "webp-1200", format: "webp" },
+  { variant: "orig", format: "jpeg" },
+];
+const byAsset = new Map([[ASSET, VARIANTS]]);
+const IMG = `<img src="/_caelo/media/${ASSET}/webp-800" alt="Team">`;
+
+describe("enrichResponsiveImages (issue #162)", () => {
+  it("production mode rewrites src and builds the _assets ladder", () => {
+    const out = enrichResponsiveImages(IMG, byAsset, {
+      rewriteSrc: true,
+      urlFor: (id, v, f) => `/_assets/${id}/${v}.${f === "webp" ? "webp" : "jpg"}`,
+    });
+    expect(out).toContain(`src="/_assets/${ASSET}/webp-800.webp"`);
+    expect(out).toContain(`/_assets/${ASSET}/webp-400.webp 400w`);
+    expect(out).toContain('loading="lazy"');
+    expect(out).toContain('decoding="async"');
+    expect(out).toContain('alt="Team"');
+  });
+
+  it("preview mode keeps the admin src but emits the SAME attribute shape", () => {
+    const out = enrichResponsiveImages(IMG, byAsset, {
+      rewriteSrc: false,
+      urlFor: (id, v) => `/_caelo/media/${id}/${v}`,
+    });
+    expect(out).toContain(`src="/_caelo/media/${ASSET}/webp-800"`);
+    expect(out).toContain(`/_caelo/media/${ASSET}/webp-400 400w`);
+    expect(out).toContain(`sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 800px"`);
+    expect(out).toContain('loading="lazy"');
+  });
+
+  it("author-supplied attributes keep precedence", () => {
+    const authored = `<img loading="eager" srcset="x 1w" src="/_caelo/media/${ASSET}/webp-800">`;
+    const out = enrichResponsiveImages(authored, byAsset, {
+      rewriteSrc: false,
+      urlFor: (id, v) => `/_caelo/media/${id}/${v}`,
+    });
+    expect(out).toContain('loading="eager"');
+    expect(out).toContain('srcset="x 1w"');
+    expect(out.match(/srcset=/g)).toHaveLength(1);
+  });
+
+  it("skips srcset for sub-two-entry ladders and non-media images", () => {
+    const single = new Map([[ASSET, [{ variant: "webp-800", format: "webp" }]]]);
+    const out = enrichResponsiveImages(IMG, single, {
+      rewriteSrc: false,
+      urlFor: (id, v) => `/_caelo/media/${id}/${v}`,
+    });
+    expect(out).not.toContain("srcset=");
+    const external = '<img src="https://example.com/x.png">';
+    expect(
+      enrichResponsiveImages(external, byAsset, {
+        rewriteSrc: false,
+        urlFor: (id, v) => `/${id}/${v}`,
+      }),
+    ).toBe(external);
+  });
+});
+
+/**
+ * Run #10 D4 — AI-facing surfaces must advertise a variant that EXISTS.
+ * The pipeline never emits webp-800 for sub-800px sources or animated
+ * GIFs; advertising it anyway blocked the whole staging build.
+ */
+describe("pickAiImageVariant", () => {
+  it("prefers webp-800 when present", () => {
+    expect(pickAiImageVariant(["orig", "webp-400", "webp-800", "webp-1200"])).toBe("webp-800");
+  });
+
+  it("falls back to the largest webp below 800 (small source, no upscaling)", () => {
+    expect(pickAiImageVariant(["orig", "webp-400"])).toBe("webp-400");
+  });
+
+  it("falls back to the smallest webp above 800 when nothing smaller exists", () => {
+    expect(pickAiImageVariant(["orig", "webp-1200", "webp-1600"])).toBe("webp-1200");
+  });
+
+  it("returns orig when no webp exists (animated GIF, SVG, PDF, pipeline gap)", () => {
+    expect(pickAiImageVariant(["orig"])).toBe("orig");
+    expect(pickAiImageVariant([])).toBe("orig");
+  });
+
+  it("ignores crop-family variants when picking", () => {
+    expect(pickAiImageVariant(["orig", "square-800", "webp-400"])).toBe("webp-400");
+  });
+});

package/src/responsive-images.ts

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #162 — responsive-image markup, ONE implementation for both
+ * render surfaces. Production (the static generator's media pass) and
+ * the editor preview must emit the same `srcset`/`sizes`/`loading`/
+ * `decoding` shape — the operator tunes visuals against the preview,
+ * and the #155 self-review loop makes design decisions from preview
+ * screenshots, so markup drift there means optimizing the wrong
+ * artifact. Only the URL form differs (parameterized `urlFor`):
+ * `/_assets/<id>/<variant>.<ext>` in builds, `/_caelo/media/<id>/<variant>`
+ * in the admin preview.
+ *
+ * Extracted from apps/static-generator/src/media-pass.ts verbatim in
+ * behaviour: author-supplied srcset/sizes/loading/decoding always keep
+ * precedence; ladders under two entries add no srcset.
+ */
+
+export interface ImageVariantInfo {
+  readonly variant: string;
+  readonly format: string;
+}
+
+/** Extract `webp-800` → 800; `square-400` → 400; `orig` → null. */
+export function parseVariantWidth(variant: string): number | null {
+  const m = variant.match(/-(\d+)$/);
+  return m?.[1] ? Number.parseInt(m[1], 10) : null;
+}
+
+/** `webp-800` → 'webp'; `square-800` → 'square'; `orig` → 'orig'. */
+export function variantFamily(variant: string): string {
+  const m = variant.match(/^([a-z][a-z0-9-]*?)-\d+$/);
+  return m?.[1] ? m[1] : variant;
+}
+
+/**
+ * Pick the variant tag AI-facing surfaces should hand out for an
+ * asset, given the variant tags that ACTUALLY exist on it.
+ *
+ * Run #10 D4: `find_media` and the `## Media` system-prompt block
+ * advertised `webp-800` for every raster mime, but the pipeline never
+ * emits `webp-800` for sources narrower than 800px (no upscaling) or
+ * for animated GIFs — the AI wrote those URLs into module HTML and the
+ * static generator's media pass failed the whole staging build on
+ * "asset/variant pairs missing". Advertising must be grounded in the
+ * `media_variants` rows, not in the mime.
+ *
+ * Preference order: `webp-800` when present; else the LARGEST webp at
+ * or below 800 (best quality that exists without shipping a hero-sized
+ * file); else the smallest webp above 800; else `orig` (always exists).
+ *
+ * @param existingVariants variant tags present in `media_variants` for the asset.
+ */
+export function pickAiImageVariant(existingVariants: readonly string[]): string {
+  const webps = existingVariants
+    .map((v) => ({ variant: v, width: parseVariantWidth(v) }))
+    .filter(
+      (v): v is { variant: string; width: number } =>
+        variantFamily(v.variant) === "webp" && v.width !== null,
+    );
+  const exact = webps.find((v) => v.width === 800);
+  if (exact) return exact.variant;
+  const below = webps.filter((v) => v.width < 800).sort((a, b) => b.width - a.width)[0];
+  if (below) return below.variant;
+  const above = webps.filter((v) => v.width > 800).sort((a, b) => a.width - b.width)[0];
+  if (above) return above.variant;
+  return "orig";
+}
+
+export interface EnrichResponsiveImagesOptions {
+  /**
+   * Build the URL an enriched attribute should reference for
+   * (ref, variant, format), where `ref` is the asset SLUG (current form)
+   * or a legacy UUID id. Return null to leave `src` untouched (the preview
+   * keeps its admin-served URLs).
+   */
+  readonly urlFor: (ref: string, variant: string, format: string) => string;
+  /** Rewrite the `src` attribute itself (production) or keep it (preview). */
+  readonly rewriteSrc: boolean;
+  /** Format lookup per (ref, variant); defaults to webp. */
+  readonly formatFor?: (ref: string, variant: string) => string;
+}
+
+const ENRICH_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/**
+ * Walk every `<img …>` whose src points at `/_caelo/media/<slug>` (or the
+ * legacy `/_caelo/media/<uuid>/<variant>`) and append the responsive
+ * attributes. `variantsByAsset` is keyed by the same `ref` the caller uses
+ * in `urlFor` (slug for current embeds, id for legacy). String-level
+ * rewrite; existing attributes always win.
+ */
+export function enrichResponsiveImages(
+  html: string,
+  variantsByAsset: ReadonlyMap<string, readonly ImageVariantInfo[]>,
+  options: EnrichResponsiveImagesOptions,
+): string {
+  return html.replace(/<img\b[^>]*>/g, (tag) => {
+    const srcMatch = tag.match(
+      /\bsrc=("|')\/_caelo\/media\/([a-z0-9][a-z0-9-]{0,63})(?:\/([a-z][a-z0-9-]{0,63}))?\1/,
+    );
+    if (!srcMatch) return tag;
+    const seg1 = srcMatch[2] as string;
+    const seg2 = srcMatch[3];
+    // Legacy id form only when a full uuid is followed by an explicit
+    // variant; otherwise `ref` is the slug and orig is implied.
+    const isLegacyId = ENRICH_UUID_RE.test(seg1) && seg2 !== undefined;
+    const ref = seg1;
+    const variant = isLegacyId ? (seg2 as string) : (seg2 ?? "orig");
+    const assetId = ref;
+    const variants = variantsByAsset.get(ref) ?? [];
+
+    const family = variantFamily(variant);
+    const familyVariants = variants
+      .filter((v) => variantFamily(v.variant) === family && v.format === "webp")
+      .map((v) => ({ variant: v.variant, width: parseVariantWidth(v.variant) }))
+      .filter((v): v is { variant: string; width: number } => v.width !== null)
+      .sort((a, b) => a.width - b.width);
+
+    const requestedWidth = parseVariantWidth(variant);
+    const requestedFormat = options.formatFor?.(assetId, variant) ?? "webp";
+
+    let out = tag;
+    if (options.rewriteSrc) {
+      out = out.replace(srcMatch[0], `src="${options.urlFor(assetId, variant, requestedFormat)}"`);
+    }
+
+    if (familyVariants.length >= 2 && !/\bsrcset=/i.test(out)) {
+      const srcset = familyVariants
+        .map((v) => `${options.urlFor(assetId, v.variant, "webp")} ${v.width}w`)
+        .join(", ");
+      const sizes =
+        requestedWidth !== null
+          ? `(max-width: 600px) 400px, (max-width: 1200px) 800px, ${requestedWidth}px`
+          : "100vw";
+      out = out.replace(
+        /<img\b/,
+        `<img srcset="${srcset}" sizes="${/\bsizes=/i.test(out) ? "" : sizes}"`,
+      );
+      out = out.replace(/\bsizes=""\s*/g, "");
+    }
+
+    if (!/\bloading=/i.test(out)) {
+      out = out.replace(/<img\b/, '<img loading="lazy"');
+    }
+    if (!/\bdecoding=/i.test(out)) {
+      out = out.replace(/<img\b/, '<img decoding="async"');
+    }
+    return out;
+  });
+}