@caelo-cms/shared 0.10.22 → 0.10.23

package/src/css-gradient-scan.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #164 (CodeQL follow-up) — linear CSS gradient scanner.
+ *
+ * A `*-gradient\([^;{}]*\)` regex over whole stylesheets is the
+ * polynomial-ReDoS shape (#113): on adversarial input full of unclosed
+ * `conic-gradient(` starts, every attempt rescans to end-of-input.
+ * Gradient arguments legitimately contain nested parens (rgba() stops),
+ * so the class can't simply exclude `(`. This scanner walks the string
+ * once: find the next `-gradient(` head, then match parens with a
+ * depth counter, bounded by a hard argument-length cap.
+ */
+
+/** No real gradient needs more; unclosed heads stop scanning here. */
+const MAX_GRADIENT_LENGTH = 2_000;
+
+const NEEDLE = "-gradient(";
+const BASES = ["linear", "radial", "conic"] as const;
+const REPEATING = "repeating-";
+
+export interface CssGradientMatch {
+  readonly start: number;
+  readonly end: number;
+  readonly literal: string;
+}
+
+/**
+ * All complete gradient literals, in document order. Linear: ONE
+ * indexOf needle per hit (each advancing the cursor), a bounded
+ * backwards check for the base keyword, and a capped paren walk.
+ */
+export function scanCssGradients(text: string): CssGradientMatch[] {
+  const lower = text.toLowerCase();
+  const out: CssGradientMatch[] = [];
+  let from = 0;
+  while (from < lower.length) {
+    const g = lower.indexOf(NEEDLE, from);
+    if (g === -1) break;
+    let headStart = -1;
+    for (const base of BASES) {
+      if (g >= base.length && lower.startsWith(base, g - base.length)) {
+        headStart = g - base.length;
+        break;
+      }
+    }
+    if (headStart === -1) {
+      from = g + NEEDLE.length;
+      continue;
+    }
+    if (
+      headStart >= REPEATING.length &&
+      lower.startsWith(REPEATING, headStart - REPEATING.length)
+    ) {
+      headStart -= REPEATING.length;
+    }
+    let depth = 1;
+    let i = g + NEEDLE.length;
+    const limit = Math.min(lower.length, i + MAX_GRADIENT_LENGTH);
+    while (i < limit && depth > 0) {
+      const ch = lower.charCodeAt(i);
+      if (ch === 40 /* ( */) depth += 1;
+      else if (ch === 41 /* ) */) depth -= 1;
+      i += 1;
+    }
+    if (depth === 0) {
+      out.push({ start: headStart, end: i, literal: text.slice(headStart, i) });
+      from = i;
+    } else {
+      // Unclosed (or over-long) head — advance past it, never rescan.
+      from = g + NEEDLE.length;
+    }
+  }
+  return out;
+}
+
+/** Replace each complete gradient via `cb` (return the literal to keep). */
+export function replaceCssGradients(text: string, cb: (literal: string) => string): string {
+  const matches = scanCssGradients(text);
+  if (matches.length === 0) return text;
+  let out = "";
+  let cursor = 0;
+  for (const m of matches) {
+    out += text.slice(cursor, m.start) + cb(m.literal);
+    cursor = m.end;
+  }
+  return out + text.slice(cursor);
+}

package/src/css-var-scan.test.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #156 — scanner unit coverage: reference/definition extraction
+ * (nested fallbacks, comments-in-values, strings), locally-defined
+ * custom properties, did-you-mean suggestions, warning formatting.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  extractCssVarDefinitions,
+  extractCssVarReferences,
+  formatUnknownCssVarWarning,
+  scanCssVars,
+  unknownCssVarMarker,
+} from "./css-var-scan.js";
+
+const KNOWN = ["--color-primary", "--color-foreground", "--color-background", "--spacing-md"];
+
+describe("extractCssVarReferences", () => {
+  it("finds plain and fallback-carrying references, deduped", () => {
+    const refs = extractCssVarReferences(
+      ".a{color:var(--color-primary)}.b{color:var(--color-primary);background:var( --color-bg , #fff )}",
+    );
+    expect(refs).toEqual([
+      { name: "--color-primary", hasFallback: false },
+      { name: "--color-bg", hasFallback: true },
+    ]);
+  });
+
+  it("handles nested var() fallbacks", () => {
+    const refs = extractCssVarReferences("p{color:var(--a, var(--b, red))}");
+    expect(refs.map((r) => r.name).sort()).toEqual(["--a", "--b"]);
+  });
+});
+
+describe("extractCssVarDefinitions", () => {
+  it("collects custom-property declarations, not references", () => {
+    const defs = extractCssVarDefinitions(
+      ":root{--site-gutter:2rem}.x{--local: 1px; color:var(--other)}",
+    );
+    expect([...defs].sort()).toEqual(["--local", "--site-gutter"]);
+  });
+});
+
+describe("scanCssVars", () => {
+  it("reports unknown refs with a did-you-mean suggestion", () => {
+    const unknown = scanCssVars({ css: "h1{color:var(--color-foregruond)}", knownVars: KNOWN });
+    expect(unknown).toHaveLength(1);
+    expect(unknown[0]?.name).toBe("--color-foregruond");
+    expect(unknown[0]?.suggestion).toBe("--color-foreground");
+  });
+
+  it("treats locally-defined custom properties as known", () => {
+    const unknown = scanCssVars({
+      css: ".hero{--hero-angle:12deg; transform:rotate(var(--hero-angle))}",
+      knownVars: KNOWN,
+    });
+    expect(unknown).toEqual([]);
+  });
+
+  it("suppresses far-fetched suggestions", () => {
+    const unknown = scanCssVars({ css: "p{width:var(--zzz-totally-unrelated)}", knownVars: KNOWN });
+    expect(unknown[0]?.suggestion).toBeNull();
+  });
+
+  it("is silent on clean css", () => {
+    expect(
+      scanCssVars({
+        css: "p{color:var(--color-primary);padding:var(--spacing-md)}",
+        knownVars: KNOWN,
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("formatUnknownCssVarWarning / marker", () => {
+  it("formats an AI-actionable one-liner and distinguishes fallback vs invalid", () => {
+    const msg = formatUnknownCssVarWarning([
+      { name: "--color-bg", hasFallback: true, suggestion: "--color-background" },
+      { name: "--nope", hasFallback: false, suggestion: null },
+    ]);
+    expect(msg).toContain("--color-bg");
+    expect(msg).toContain("did you mean `--color-background`?");
+    expect(msg).toContain("hardcoded fallback");
+    expect(msg).toContain("won't apply");
+  });
+
+  it("returns null when nothing is unknown (no noise)", () => {
+    expect(formatUnknownCssVarWarning([])).toBeNull();
+  });
+
+  it("marker follows the missing-content convention", () => {
+    expect(unknownCssVarMarker("--color-bg")).toBe("unknown-css-var:--color-bg");
+  });
+});

package/src/css-var-scan.ts

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #156 — CSS custom-property reference scanner.
+ *
+ * The silent-fallback trap: module/template/layout CSS referencing a
+ * `var(--…)` the active theme never emits renders the hardcoded
+ * fallback (or nothing), so the page quietly diverges from the theme —
+ * the monochrome regression class documented in theme-render.ts. The
+ * prompt-level var inventory guards the happy path; this scanner is the
+ * mechanical write-time guard (CLAUDE.md §2: misses must be loud).
+ *
+ * Pure string analysis — callers (authoring tools, preview op) supply
+ * the known-var set from `listThemeCssVarNames(activeTheme.tokens)`.
+ * Custom properties DEFINED anywhere in the scanned bundle are treated
+ * as known: a layout may define `--site-gutter` for its modules, and
+ * that is legitimate authoring, not drift.
+ */
+
+/** One `var(--x)` reference found in CSS. */
+export interface CssVarReference {
+  readonly name: string;
+  /** True when the reference carries a literal fallback (`var(--x, #fff)`). */
+  readonly hasFallback: boolean;
+}
+
+const VAR_REFERENCE_RE = /var\(\s*(--[a-zA-Z0-9_-]+)\s*(,)?/g;
+const VAR_DEFINITION_RE = /(?:^|[{;\s])(--[a-zA-Z0-9_-]+)\s*:/g;
+
+/** Extract every `var(--x[, fallback])` reference (deduped by name+fallback). */
+export function extractCssVarReferences(css: string): CssVarReference[] {
+  const seen = new Map<string, CssVarReference>();
+  for (const m of css.matchAll(VAR_REFERENCE_RE)) {
+    const name = m[1] ?? "";
+    const hasFallback = m[2] === ",";
+    const key = `${name}|${hasFallback}`;
+    if (!seen.has(key)) seen.set(key, { name, hasFallback });
+  }
+  return [...seen.values()];
+}
+
+/** Custom properties DEFINED in the CSS (`--x: value;`). */
+export function extractCssVarDefinitions(css: string): Set<string> {
+  const out = new Set<string>();
+  for (const m of css.matchAll(VAR_DEFINITION_RE)) {
+    out.add(m[1] ?? "");
+  }
+  return out;
+}
+
+/** Levenshtein distance, small-string use only (var names). */
+function editDistance(a: string, b: string): number {
+  const prev = new Array<number>(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0] as number;
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j] as number;
+      prev[j] = Math.min(
+        (prev[j] as number) + 1,
+        (prev[j - 1] as number) + 1,
+        diag + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      diag = tmp;
+    }
+  }
+  return prev[b.length] as number;
+}
+
+/** An unknown reference + the closest known name worth suggesting. */
+export interface UnknownCssVar {
+  readonly name: string;
+  readonly hasFallback: boolean;
+  /** Closest known var within edit-distance 40% of length, or null. */
+  readonly suggestion: string | null;
+}
+
+export interface CssVarScanInput {
+  /** The CSS bundle to scan (concatenate layout+template+module parts). */
+  readonly css: string;
+  /** Vars the active theme emits (`listThemeCssVarNames`). */
+  readonly knownVars: readonly string[];
+}
+
+/**
+ * Report `var()` references that neither the theme emits nor the
+ * bundle itself defines, with a nearest-match suggestion so the fix is
+ * one edit, not a research task (CLAUDE.md §11: AI-actionable).
+ */
+export function scanCssVars(input: CssVarScanInput): UnknownCssVar[] {
+  const known = new Set(input.knownVars);
+  for (const def of extractCssVarDefinitions(input.css)) known.add(def);
+
+  const unknown: UnknownCssVar[] = [];
+  const reported = new Set<string>();
+  for (const ref of extractCssVarReferences(input.css)) {
+    if (known.has(ref.name) || reported.has(ref.name)) continue;
+    reported.add(ref.name);
+    let best: string | null = null;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const candidate of known) {
+      const d = editDistance(ref.name, candidate);
+      if (d < bestDist) {
+        bestDist = d;
+        best = candidate;
+      }
+    }
+    const threshold = Math.max(2, Math.floor(ref.name.length * 0.4));
+    unknown.push({
+      name: ref.name,
+      hasFallback: ref.hasFallback,
+      suggestion: best !== null && bestDist <= threshold ? best : null,
+    });
+  }
+  return unknown;
+}
+
+/**
+ * Marker for the preview op's missing-content surface — same
+ * convention as `theme-asset-unbound:<slot>` / `theme-font-unresolvable`.
+ */
+export function unknownCssVarMarker(name: string): string {
+  return `unknown-css-var:${name}`;
+}
+
+/**
+ * One-line, AI-actionable warning for authoring-tool results. Returns
+ * null when nothing is unknown (no noise on clean writes).
+ */
+export function formatUnknownCssVarWarning(unknown: readonly UnknownCssVar[]): string | null {
+  if (unknown.length === 0) return null;
+  const parts = unknown.map((u) => {
+    const hint = u.suggestion !== null ? ` (did you mean \`${u.suggestion}\`?)` : "";
+    const fallback = u.hasFallback
+      ? " — its hardcoded fallback is what visitors will see, detached from the theme"
+      : " — the declaration is invalid and the property won't apply";
+    return `\`${u.name}\`${hint}${fallback}`;
+  });
+  return (
+    `⚠️ Unknown CSS vars (the active theme does not emit them): ${parts.join("; ")}. ` +
+    "Use the exact names from the `## Theme` inventory, or define the custom property in this CSS if it's intentional."
+  );
+}

package/src/derive-module-type.test.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.12.3 (issue #106) — unit guards for the module type/slug helpers.
+ * The load-bearing invariant: a module's stable `type` is the slug base
+ * WITHOUT the uniqueness suffix, so `type` is always a prefix of `slug`
+ * and the two can never drift (which is what the allowedModuleTypes match
+ * relies on).
+ */
+
+import { describe, expect, it } from "bun:test";
+import { deriveModuleType, slugifyModuleName, slugifyModuleSection } from "./content.js";
+
+describe("deriveModuleType", () => {
+  it("lowercases + hyphenates and drops no suffix", () => {
+    expect(deriveModuleType("Primary Button")).toBe("primary-button");
+  });
+
+  it("collapses runs of non-alphanumerics to a single hyphen, trimmed", () => {
+    expect(deriveModuleType("CTA!!  banner $$$")).toBe("cta-banner");
+  });
+
+  it("falls back to 'module' for empty / all-punctuation names", () => {
+    expect(deriveModuleType("!!!")).toBe("module");
+    expect(deriveModuleType("")).toBe("module");
+  });
+
+  it("caps the base at 40 chars", () => {
+    expect(deriveModuleType("a".repeat(80)).length).toBe(40);
+  });
+
+  it("produces NO -<timestamp> suffix (contrast with slugifyModuleName)", () => {
+    const t = deriveModuleType("Button");
+    expect(t).toBe("button");
+    expect(t).not.toMatch(/-[a-z0-9]+$/);
+  });
+
+  // Copilot review (#106 PR): the 40-char cap used to run AFTER the edge-hyphen
+  // trim, so a name whose collapsed hyphen sits at the boundary truncated into a
+  // trailing hyphen — which would double-hyphenate `slug = type + "-" + suffix`.
+  it("never returns a trailing hyphen when the cap lands on one", () => {
+    const name = `${"a".repeat(39)} tail`; // collapses to 39 a's + "-tail"
+    const t = deriveModuleType(name);
+    expect(t).not.toMatch(/-$/);
+    expect(t).toBe("a".repeat(39));
+    // the composed slug stays single-hyphenated
+    expect(slugifyModuleName(name, "s")).toBe(`${"a".repeat(39)}-s`);
+  });
+
+  it("never returns a leading hyphen", () => {
+    expect(deriveModuleType("  !!leading")).toBe("leading");
+    expect(deriveModuleType("!!leading")).not.toMatch(/^-/);
+  });
+});
+
+describe("slugifyModuleName", () => {
+  it("composes as deriveModuleType + '-' + suffix (type is a slug prefix)", () => {
+    expect(slugifyModuleName("Primary Button", "abc123")).toBe("primary-button-abc123");
+    const name = "Hero Banner";
+    expect(slugifyModuleName(name, "x").startsWith(`${deriveModuleType(name)}-`)).toBe(true);
+  });
+
+  it("uses a base36 timestamp suffix when none is given", () => {
+    expect(slugifyModuleName("Button")).toMatch(/^button-[a-z0-9]+$/);
+  });
+});
+
+describe("slugifyModuleSection", () => {
+  it("inserts the section index between the type base and the suffix", () => {
+    expect(slugifyModuleSection("Hero", 2, "zzz")).toBe("hero-2-zzz");
+  });
+
+  it("keeps the type base as a prefix so same-named sections don't collide", () => {
+    const a = slugifyModuleSection("Card", 0, "s");
+    const b = slugifyModuleSection("Card", 1, "s");
+    expect(a).not.toBe(b);
+    expect(a.startsWith("card-")).toBe(true);
+    expect(b.startsWith("card-")).toBe(true);
+  });
+});

package/src/design-manifest.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #165 — the Design Manifest: a generated, versioned description
+ * of THIS site's design system (epic #149, growth-time convergence).
+ *
+ * The operator requirement is asymmetric: pages of the SAME site share
+ * one visual line, while different sites are free to look nothing
+ * alike. A global stylesheet solves the first at the cost of the
+ * second; the per-site manifest solves both — it captures what this
+ * site's tokens/patterns MEAN so the AI converges toward its own
+ * design, not a Caelo default.
+ *
+ * Written at Genesis materialisation (or curated later via chat);
+ * rendered as the `## Design system` system-prompt block.
+ */
+
+import { z } from "zod";
+
+export const designManifestPattern = z
+  .object({
+    /** Pattern name the AI reasons in ("hero", "card grid", "cta band"). */
+    name: z.string().min(1).max(80),
+    /** Stable module `type` implementing it — reuse target (#159 place mode). */
+    moduleType: z.string().max(64).optional(),
+    /** One-line spec: what makes this pattern THIS site's version of it. */
+    spec: z.string().min(1).max(500),
+  })
+  .strict();
+
+export const designManifestSchema = z
+  .object({
+    /** `--color-primary` → "CTAs and links only" — usage semantics per var. */
+    tokenRoles: z.record(z.string().min(3).max(64), z.string().min(1).max(300)).optional(),
+    /** Scale ratio, casing, measure rules. */
+    typography: z.string().min(1).max(1000).optional(),
+    /** Section padding, container width, grid gaps. */
+    rhythm: z.string().min(1).max(1000).optional(),
+    patterns: z.array(designManifestPattern).max(24).optional(),
+    imagery: z.string().min(1).max(500).optional(),
+    avoid: z.string().min(1).max(500).optional(),
+  })
+  .strict();
+export type DesignManifest = z.infer<typeof designManifestSchema>;
+
+/** Render the `## Design system` prompt block. Null when empty. */
+export function formatDesignSystemBlock(manifest: DesignManifest | null): string | null {
+  if (manifest === null) return null;
+  const lines: string[] = [
+    "## Design system",
+    "",
+    "THIS site's own design language — derived from the chosen design. Every module you author or restyle conforms to it unless the operator explicitly asks to break the line. Reuse the pattern's module type (place mode) before minting lookalikes.",
+    "",
+  ];
+  let hasContent = false;
+  const roles = manifest.tokenRoles ?? {};
+  const roleEntries = Object.entries(roles);
+  if (roleEntries.length > 0) {
+    hasContent = true;
+    lines.push("Token roles:");
+    for (const [token, role] of roleEntries.slice(0, 24)) lines.push(`- \`${token}\` — ${role}`);
+    lines.push("");
+  }
+  if (manifest.typography) {
+    hasContent = true;
+    lines.push(`Typography: ${manifest.typography}`, "");
+  }
+  if (manifest.rhythm) {
+    hasContent = true;
+    lines.push(`Rhythm: ${manifest.rhythm}`, "");
+  }
+  if (manifest.patterns && manifest.patterns.length > 0) {
+    hasContent = true;
+    lines.push("Patterns:");
+    for (const p of manifest.patterns) {
+      lines.push(
+        `- **${p.name}**${p.moduleType ? ` (module type \`${p.moduleType}\`)` : ""} — ${p.spec}`,
+      );
+    }
+    lines.push("");
+  }
+  if (manifest.imagery) {
+    hasContent = true;
+    lines.push(`Imagery: ${manifest.imagery}`, "");
+  }
+  if (manifest.avoid) {
+    hasContent = true;
+    lines.push(`Never: ${manifest.avoid}`, "");
+  }
+  if (!hasContent) return null;
+  while (lines[lines.length - 1] === "") lines.pop();
+  return lines.join("\n");
+}

package/src/fonts.test.ts

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #150 — unit coverage for the pure web-font helpers: request
+ * extraction from typography tokens, system-stack classification, css2
+ * payload parsing, self-hosted @font-face emission, preload selection.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  buildFontFaceCss,
+  extractThemeFontRequests,
+  fontUnresolvableMarker,
+  googleFontsCssUrl,
+  isSystemFontFamily,
+  parseFontsCss,
+  type ResolvedFontFace,
+  selectPreloadFaces,
+} from "./fonts.js";
+import type { ThemeDocument } from "./themes.js";
+
+const TOKENS = {
+  typography: {
+    body: { $type: "typography", $value: { fontFamily: '"Inter", sans-serif', fontWeight: 400 } },
+    heading: {
+      $type: "typography",
+      $value: { fontFamily: "Playfair Display, serif", fontWeight: 700 },
+    },
+    emphasis: { $type: "typography", $value: { fontFamily: "Inter", fontWeight: "bold" } },
+    mono: { $type: "typography", $value: { fontFamily: "ui-monospace, Menlo, monospace" } },
+    aliasing: { $type: "typography", $value: "{typography.body}" },
+  },
+} as unknown as ThemeDocument;
+
+describe("extractThemeFontRequests (issue #150)", () => {
+  it("collects web families with merged weights + roles, skips system stacks and aliases", () => {
+    const reqs = extractThemeFontRequests(TOKENS);
+    const byFamily = new Map(reqs.map((r) => [r.family, r]));
+    expect([...byFamily.keys()].sort()).toEqual(["Inter", "Playfair Display"]);
+    // 400 from body + bold→700 from emphasis, merged and sorted.
+    expect(byFamily.get("Inter")?.weights).toEqual([400, 700]);
+    expect(byFamily.get("Inter")?.roles.sort()).toEqual(["body", "emphasis"]);
+    expect(byFamily.get("Playfair Display")?.weights).toEqual([700]);
+  });
+
+  it("defaults weights when the theme declares none", () => {
+    const reqs = extractThemeFontRequests({
+      typography: { body: { $value: { fontFamily: "Poppins" } } },
+    } as unknown as ThemeDocument);
+    expect(reqs[0]?.weights).toEqual([400, 700]);
+  });
+
+  it("returns [] for token documents without typography", () => {
+    expect(extractThemeFontRequests({} as ThemeDocument)).toEqual([]);
+  });
+});
+
+describe("isSystemFontFamily", () => {
+  it("classifies generic keywords and OS staples as system", () => {
+    for (const f of ["system-ui", "sans-serif", "Georgia", "  Menlo ", "SEGOE UI"]) {
+      expect(isSystemFontFamily(f)).toBe(true);
+    }
+  });
+  it("classifies hosted-web staples as web fonts", () => {
+    for (const f of ["Inter", "Poppins", "Playfair Display", "Roboto"]) {
+      expect(isSystemFontFamily(f)).toBe(false);
+    }
+  });
+});
+
+describe("googleFontsCssUrl", () => {
+  it("encodes the family and joins weights", () => {
+    expect(
+      googleFontsCssUrl({ family: "Playfair Display", weights: [400, 700], roles: ["heading"] }),
+    ).toBe("https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;700&display=swap");
+  });
+});
+
+const CSS2_FIXTURE = `
+/* latin-ext */
+@font-face {
+  font-family: 'Poppins';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(https://fonts.gstatic.com/s/poppins/v23/pxiEyp8kv8JHgFVrJJnecmNE.woff2) format('woff2');
+  unicode-range: U+0100-02BA;
+}
+/* latin */
+@font-face {
+  font-family: 'Poppins';
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url(https://fonts.gstatic.com/s/poppins/v23/pxiByp8kv8JHgFVrLCz7Z1xlEA.woff2) format('woff2');
+  unicode-range: U+0000-00FF, U+0131;
+}
+@font-face {
+  font-family: 'Poppins';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(https://fonts.gstatic.com/s/poppins/v23/pxiEyp8kv8JHgFVrJJfecg.woff2) format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153;
+}
+`;
+
+describe("parseFontsCss", () => {
+  it("parses css2 @font-face blocks into face records", () => {
+    const faces = parseFontsCss(CSS2_FIXTURE);
+    expect(faces).toHaveLength(3);
+    expect(faces[0]).toEqual({
+      family: "Poppins",
+      style: "normal",
+      weight: "400",
+      unicodeRange: "U+0100-02BA",
+      srcUrl: "https://fonts.gstatic.com/s/poppins/v23/pxiEyp8kv8JHgFVrJJnecmNE.woff2",
+    });
+  });
+
+  it("returns [] on payloads without woff URLs — the caller's loud-failure signal", () => {
+    expect(parseFontsCss("body{color:red}")).toEqual([]);
+  });
+});
+
+describe("buildFontFaceCss + selectPreloadFaces", () => {
+  const faces: ResolvedFontFace[] = parseFontsCss(CSS2_FIXTURE).map((f, i) => ({
+    family: f.family,
+    style: f.style,
+    weight: f.weight,
+    unicodeRange: f.unicodeRange,
+    publicUrl: `/_assets/fonts/poppins/${i}.woff2`,
+  }));
+
+  it("emits self-hosted @font-face with font-display: swap", () => {
+    const css = buildFontFaceCss(faces);
+    expect(css).toContain('font-family:"Poppins"');
+    expect(css).toContain("font-display:swap");
+    expect(css).toContain("url(/_assets/fonts/poppins/0.woff2) format('woff2')");
+    expect(css).toContain("unicode-range:U+0100-02BA;");
+    expect(css).not.toContain("fonts.gstatic.com");
+  });
+
+  it("preloads one latin normal-style face per family at the lowest weight", () => {
+    const picks = selectPreloadFaces(faces);
+    // Latin faces are weight 700 (index 1) and 400 (index 2) → lowest is 400.
+    expect(picks).toHaveLength(1);
+    expect(picks[0]?.weight).toBe("400");
+    expect(picks[0]?.publicUrl).toBe("/_assets/fonts/poppins/2.woff2");
+  });
+});
+
+describe("fontUnresolvableMarker", () => {
+  it("matches the theme-asset-unbound marker convention", () => {
+    expect(fontUnresolvableMarker("Poppins")).toBe("theme-font-unresolvable:Poppins");
+  });
+});