@caelo-cms/shared 0.10.22 → 0.10.24

package/dist/css-var-scan.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MPL-2.0
+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) {
+    const seen = new Map();
+    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) {
+    const out = new Set();
+    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, b) {
+    const prev = new Array(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];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = tmp;
+        }
+    }
+    return prev[b.length];
+}
+/**
+ * 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) {
+    const known = new Set(input.knownVars);
+    for (const def of extractCssVarDefinitions(input.css))
+        known.add(def);
+    const unknown = [];
+    const reported = new Set();
+    for (const ref of extractCssVarReferences(input.css)) {
+        if (known.has(ref.name) || reported.has(ref.name))
+            continue;
+        reported.add(ref.name);
+        let best = 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) {
+    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) {
+    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.");
+}
+//# sourceMappingURL=css-var-scan.js.map

package/dist/css-var-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-var-scan.js","sourceRoot":"","sources":["../src/css-var-scan.ts"],"names":[],"mappings":"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"}

package/dist/design-draft-shell.d.ts

@@ -0,0 +1,21 @@
+import { type ComposeFonts, type ComposeTheme } from "./preview-compose.js";
+export interface DesignDraftShellInput {
+    /** The stored fragment (already script-stripped at the boundary). */
+    readonly fragmentHtml: string;
+    /** Active theme; undefined renders the shell without theme vars
+     *  (loud: the draft's `var(--…)` references fall to browser initial
+     *  values — visibly broken, per CLAUDE.md §2 no-fallbacks). */
+    readonly theme?: ComposeTheme;
+    /** Resolved web fonts; undefined = system stacks only. */
+    readonly fonts?: ComposeFonts;
+    /** Document title shown in the iframe (accessibility). */
+    readonly title: string;
+}
+export interface DesignDraftShellOutput {
+    readonly html: string;
+    /** `theme-asset-unbound:<slot>` markers, mirroring the template
+     *  engine's failure-marker contract. */
+    readonly missingSlots: readonly string[];
+}
+export declare function composeDesignDraftShell(input: DesignDraftShellInput): DesignDraftShellOutput;
+//# sourceMappingURL=design-draft-shell.d.ts.map

package/dist/design-draft-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-draft-shell.d.ts","sourceRoot":"","sources":["../src/design-draft-shell.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAqB,MAAM,sBAAsB,CAAC;AAY/F,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;mEAE+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;4CACwC;IACxC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AA6BD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CAyB5F"}

package/dist/design-draft-shell.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * issue #375 — theme shell for growth-time design-draft previews.
+ *
+ * Page/module-scope drafts are stored as FRAGMENTS bound to the site's
+ * `var(--…)` tokens; this composer wraps one in the site's real
+ * compiled theme at view time: web fonts (#150), theme CSS variables,
+ * and the invisible technical baseline (#151) — in the exact head
+ * order `composePagePreview` uses, so a draft previews in the same
+ * cascade it will materialise into. Pure / sync / no IO: the caller
+ * (the `genesis.render_draft` op) loads the theme row and resolves
+ * fonts, mirroring `pages.render_preview`.
+ */
+import { BASE_TECHNICAL_CSS } from "./base-css.js";
+import { fontsHeadFragment } from "./preview-compose.js";
+import { caeloMissingComment } from "./template-engine.js";
+import { renderThemeCss } from "./theme-render.js";
+/** Same four placeholders the template engine resolves (v0.11.1, #76). */
+const THEME_ASSET_KEY_TO_SLOT = {
+    theme_logo_url: "logo",
+    theme_logo_dark_url: "logoDark",
+    theme_favicon_url: "favicon",
+    theme_social_share_url: "socialShare",
+};
+/**
+ * Resolve `{{theme_*_url}}` placeholders in a draft fragment. Bound
+ * slots substitute their URL; a placeholder on an unbound slot stays
+ * loud-raw IN PLACE (placeholders usually sit inside attribute values,
+ * where an appended comment would corrupt the URL string — PR-378
+ * review) and lands in `missingSlots`; the caller appends the real
+ * `caelo:missing` comment nodes at the end of the body so the marker
+ * tooling still sees them. Other `{{…}}` sequences are left untouched:
+ * a draft is not a fielded module.
+ */
+function substituteThemeAssetUrls(html, theme, missing) {
+    return html.replace(/\{\{\s*(theme_[a-z_]+)\s*\}\}/g, (match, key) => {
+        const slot = THEME_ASSET_KEY_TO_SLOT[key];
+        if (slot === undefined)
+            return match;
+        const url = theme?.assets[slot]?.url;
+        if (url === undefined) {
+            missing.push(`theme-asset-unbound:${slot}`);
+            return match;
+        }
+        return url;
+    });
+}
+export function composeDesignDraftShell(input) {
+    const missing = [];
+    const substituted = substituteThemeAssetUrls(input.fragmentHtml, input.theme, missing);
+    // Real comment NODES, after the fragment — never inside an attribute.
+    const markers = [...new Set(missing)].map((m) => caeloMissingComment(m)).join("");
+    const body = substituted + markers;
+    // Head order mirrors composePagePreview: fonts first (URL discovery),
+    // then theme vars (so fragment CSS can `var(--color-primary)`), then
+    // the technical baseline.
+    const head = [
+        `<meta charset="utf-8">`,
+        `<meta name="viewport" content="width=device-width, initial-scale=1">`,
+        `<title>${escapeHtml(input.title)}</title>`,
+    ];
+    const fonts = fontsHeadFragment(input.fonts);
+    if (fonts !== null)
+        head.push(fonts);
+    const themeCss = input.theme !== undefined ? renderThemeCss(input.theme.tokens) : null;
+    if (themeCss !== null)
+        head.push(`<style data-source="theme">${themeCss}</style>`);
+    head.push(`<style data-source="base">${BASE_TECHNICAL_CSS}</style>`);
+    return {
+        html: `<!doctype html>\n<html><head>${head.join("")}</head><body>${body}</body></html>`,
+        missingSlots: missing,
+    };
+}
+function escapeHtml(s) {
+    return s
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+//# sourceMappingURL=design-draft-shell.js.map

package/dist/design-draft-shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-draft-shell.js","sourceRoot":"","sources":["../src/design-draft-shell.ts"],"names":[],"mappings":"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"}

package/dist/design-manifest.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare const designManifestPattern: z.ZodObject<{
+    name: z.ZodString;
+    moduleType: z.ZodOptional<z.ZodString>;
+    spec: z.ZodString;
+}, z.core.$strict>;
+export declare const designManifestSchema: z.ZodObject<{
+    tokenRoles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    typography: z.ZodOptional<z.ZodString>;
+    rhythm: z.ZodOptional<z.ZodString>;
+    patterns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        moduleType: z.ZodOptional<z.ZodString>;
+        spec: z.ZodString;
+    }, z.core.$strict>>>;
+    imagery: z.ZodOptional<z.ZodString>;
+    avoid: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type DesignManifest = z.infer<typeof designManifestSchema>;
+/** Render the `## Design system` prompt block. Null when empty. */
+export declare function formatDesignSystemBlock(manifest: DesignManifest | null): string | null;
+//# sourceMappingURL=design-manifest.d.ts.map

package/dist/design-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-manifest.d.ts","sourceRoot":"","sources":["../src/design-manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,qBAAqB;;;;kBASvB,CAAC;AAEZ,eAAO,MAAM,oBAAoB;;;;;;;;;;;kBAYtB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,mEAAmE;AACnE,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CA8CtF"}

package/dist/design-manifest.js

@@ -0,0 +1,90 @@
+// 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();
+/** Render the `## Design system` prompt block. Null when empty. */
+export function formatDesignSystemBlock(manifest) {
+    if (manifest === null)
+        return null;
+    const lines = [
+        "## 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");
+}
+//# sourceMappingURL=design-manifest.js.map

package/dist/design-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"design-manifest.js","sourceRoot":"","sources":["../src/design-manifest.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,wEAAwE;IACxE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IAC/B,6EAA6E;IAC7E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACzC,wEAAwE;IACxE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;CACjC,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,2EAA2E;IAC3E,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE;IACtF,0CAA0C;IAC1C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAClD,mDAAmD;IACnD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAC9C,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC3D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC9C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC;KACD,MAAM,EAAE,CAAC;AAGZ,mEAAmE;AACnE,MAAM,UAAU,uBAAuB,CAAC,QAA+B;IACrE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,KAAK,GAAa;QACtB,kBAAkB;QAClB,EAAE;QACF,oPAAoP;QACpP,EAAE;KACH,CAAC;IACF,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC;IACxC,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,UAAU,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3B,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,EAAE,CAAC,CAAC;QAC7F,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;QACxB,UAAU,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,eAAe,QAAQ,CAAC,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpB,UAAU,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,WAAW,QAAQ,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,UAAU,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACxB,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YAClC,KAAK,CAAC,IAAI,CACR,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CACzF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,UAAU,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,YAAY,QAAQ,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,UAAU,GAAG,IAAI,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,UAAU,QAAQ,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,CAAC;IACnD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/fonts.d.ts

@@ -0,0 +1,89 @@
+/**
+ * issue #150 — web-font resolution primitives.
+ *
+ * Theme typography tokens name font families (`--font-heading:
+ * "Poppins"`), but until #150 nothing delivered the font files to
+ * rendered pages — every site silently fell back to system fonts, the
+ * exact silent-degradation CLAUDE.md §2 forbids. These pure helpers are
+ * the shared half of the fix: extract the families a theme actually
+ * uses, classify system stacks (nothing to deliver) vs web fonts
+ * (self-hosted at deploy — hotlinking fonts.googleapis.com is both a
+ * GDPR liability, LG München I 3 O 17493/20, and a third-party request
+ * on the critical path), and build/parse the CSS involved.
+ *
+ * Network + disk live in `@caelo-cms/admin-core`'s font resolver; the
+ * static generator and the preview op share that resolver so preview
+ * and production render the same `@font-face` set (parity contract,
+ * apps/static-generator/src/generate.ts).
+ */
+import type { ThemeDocument } from "./themes.js";
+/** One family the theme needs delivered, with the weights it uses. */
+export interface FontRequest {
+    /** Primary family name, unquoted (`Poppins`), first entry of the stack. */
+    readonly family: string;
+    /** Distinct numeric weights, ascending. Always non-empty. */
+    readonly weights: readonly number[];
+    /** Typography token names that reference the family (`body`, `heading`). */
+    readonly roles: readonly string[];
+}
+/** A single @font-face declaration parsed from a fonts-CSS payload. */
+export interface ParsedFontFace {
+    readonly family: string;
+    readonly style: string;
+    readonly weight: string;
+    readonly unicodeRange: string | null;
+    /** Remote woff2 URL as served by the fonts source. */
+    readonly srcUrl: string;
+}
+/** A parsed face whose bytes now live at a self-hosted public URL. */
+export interface ResolvedFontFace extends Omit<ParsedFontFace, "srcUrl"> {
+    readonly publicUrl: string;
+}
+/** True when the family resolves locally on visitors' machines. */
+export declare function isSystemFontFamily(family: string): boolean;
+/**
+ * Walk `typography.*` composites and collect every non-system family
+ * with the weights the theme declares for it. Alias entries (`$value`
+ * as `{other.token}` string) are skipped — they point at a concrete
+ * composite that is collected on its own.
+ *
+ * Only the FIRST family of a declared stack is requested: the rest of
+ * the stack is the author's fallback chain, which by definition is not
+ * delivered.
+ */
+export declare function extractThemeFontRequests(tokens: ThemeDocument): FontRequest[];
+/** css2 request URL for one family (woff2 negotiated via the UA header). */
+export declare function googleFontsCssUrl(request: FontRequest): string;
+/**
+ * Parse a fonts-CSS payload (css2 response shape) into face records.
+ * Faces without a woff2/woff URL are dropped; a payload yielding zero
+ * faces is the caller's loud-failure signal, not a silent empty set.
+ * Oversized payloads short-circuit to [] for the same loud path —
+ * a legitimate css2 response is orders of magnitude smaller.
+ */
+export declare function parseFontsCss(cssText: string): ParsedFontFace[];
+/**
+ * Emit self-hosted @font-face CSS. `font-display: swap` always — text
+ * must render in the fallback while the woff2 loads.
+ */
+export declare function buildFontFaceCss(faces: readonly ResolvedFontFace[]): string;
+/**
+ * Pick the faces worth a `<link rel="preload">`: one per family — the
+ * latin, normal-style face at the lowest declared weight (the body-copy
+ * face; heavier display cuts arrive via normal loading). Capped at two
+ * families so the preload budget stays sane on multi-family themes.
+ */
+export declare function selectPreloadFaces(faces: readonly ResolvedFontFace[]): ResolvedFontFace[];
+/**
+ * Structured marker for a family that could not be resolved. Lands in
+ * `missingSlots` (preview, soft) or a thrown deploy error (hard) — the
+ * same loud-signal convention as `theme-asset-unbound:<slot>`.
+ */
+export declare function fontUnresolvableMarker(family: string): string;
+/**
+ * Filesystem/URL-safe slug for a family name. Shared between the font
+ * resolver (writes `<cacheDir>/<slug>/…`) and the admin serve route
+ * (reads the same path from the URL) so the two can't drift.
+ */
+export declare function fontFamilySlug(family: string): string;
+//# sourceMappingURL=fonts.d.ts.map

package/dist/fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../src/fonts.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAqDD,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,aAAa,GAAG,WAAW,EAAE,CAiC7E;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAI9D;AAmBD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAyB/D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAW3E;AAOD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAezF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAUrD"}