@caelo-cms/shared 0.10.23 → 0.10.26

package/src/base-css.ts

@@ -19,6 +19,17 @@
  *     drafts assume it);
  *   - form controls inherit the page's font instead of UA chrome.
  *
+ * Amendment (issue #410): one rule consumes a design token — the body
+ * font-family reads `var(--font-body)`. This does NOT reintroduce a
+ * global look: the token is declared per site by the theme renderer
+ * (#164), and applying the site's OWN chosen token is the mechanism
+ * that makes that choice take effect at all. Without a consumer the
+ * variable is declared but dead, and every fresh site renders the UA
+ * serif despite its theme's stack. The `system-ui,sans-serif` fallback
+ * is a declared default in the CSS cascade for themeless installs, not
+ * a hidden recovery path (CLAUDE.md §2 — nothing is silently
+ * substituted at read time; the cascade default is stated here, once).
+ *
  * Injected as `<style data-source="base">` between the theme vars and
  * the aggregated module CSS, so any module rule overrides it trivially.
  */
@@ -27,4 +38,5 @@ export const BASE_TECHNICAL_CSS =
   "*,*::before,*::after{box-sizing:border-box}" +
   "body{margin:0}" +
   "img,picture,video,canvas,svg{display:block;max-width:100%}" +
-  "input,button,textarea,select{font:inherit}";
+  "input,button,textarea,select{font:inherit}" +
+  "body{font-family:var(--font-body,system-ui,sans-serif)}";

package/src/build-page.ts

@@ -22,7 +22,6 @@
 import { z } from "zod";
 import {
   contentInstanceCreateSchema,
-  localeSchema,
   MODULE_CSS_MAX,
   MODULE_HTML_MAX,
   MODULE_JS_MAX,
@@ -194,7 +193,6 @@ export const buildPageTargetSchema = z
     slug: slugSchema.optional(),
     title: z.string().min(1).max(256).optional(),
     name: z.string().min(1).max(256).optional(),
-    locale: localeSchema.optional(),
     templateId: z.string().uuid().optional(),
     status: pageStatusSchema.optional(),
     /**
@@ -210,9 +208,9 @@ export const buildPageTargetSchema = z
   })
   .strict()
   .superRefine((page, ctx) => {
-    const createKeys = (
-      ["slug", "title", "name", "locale", "templateId", "status"] as const
-    ).filter((k) => page[k] !== undefined);
+    const createKeys = (["slug", "title", "name", "templateId", "status"] as const).filter(
+      (k) => page[k] !== undefined,
+    );
     if (page.pageId !== undefined) {
       if (createKeys.length > 0) {
         ctx.addIssue({

package/src/content.test.ts

@@ -2,9 +2,9 @@
 
 import { describe, expect, it } from "bun:test";
 import {
-  localeSchema,
   MODULE_HTML_MAX,
   moduleCreateSchema,
+  moduleUpdateSchema,
   pageCreateSchema,
   pageSetModulesSchema,
   pageUpdateSchema,
@@ -29,21 +29,6 @@ describe("slugSchema", () => {
   });
 });
 
-describe("localeSchema", () => {
-  it("accepts language and language-region", () => {
-    expect(localeSchema.safeParse("en").success).toBe(true);
-    expect(localeSchema.safeParse("de").success).toBe(true);
-    expect(localeSchema.safeParse("de-AT").success).toBe(true);
-  });
-
-  it("rejects malformed locales", () => {
-    expect(localeSchema.safeParse("EN").success).toBe(false);
-    expect(localeSchema.safeParse("en-us").success).toBe(false);
-    expect(localeSchema.safeParse("eng").success).toBe(false);
-    expect(localeSchema.safeParse("").success).toBe(false);
-  });
-});
-
 describe("moduleCreateSchema", () => {
   it("accepts a minimal module", () => {
     const r = moduleCreateSchema.safeParse({
@@ -73,6 +58,104 @@ describe("moduleCreateSchema", () => {
     });
     expect(r.success).toBe(false);
   });
+
+  // issue #432 — CDATA wrappers stored verbatim broke rendering and sent the
+  // AI into a ~20-loop visual repair spiral; the write boundary now rejects
+  // them with an actionable message.
+  it("rejects XML CDATA wrappers in css and js, with an actionable message", () => {
+    const base = { slug: "site-header", displayName: "Site header", html: "<header></header>" };
+    const css = moduleCreateSchema.safeParse({
+      ...base,
+      css: "/*<![CDATA[*/ .x { color: red } /*]]>*/",
+    });
+    expect(css.success).toBe(false);
+    if (!css.success) {
+      expect(css.error.issues.map((i) => i.message).join(" ")).toContain("CDATA");
+    }
+    const js = moduleCreateSchema.safeParse({
+      ...base,
+      js: "//<![CDATA[\nconsole.log('hi');\n//]]>",
+    });
+    expect(js.success).toBe(false);
+  });
+
+  it("accepts plain css/js (and js merely mentioning ']]>' in a string)", () => {
+    const base = { slug: "site-header", displayName: "Site header", html: "<header></header>" };
+    expect(
+      moduleCreateSchema.safeParse({ ...base, css: ".x { color: red }", js: "console.log(1);" })
+        .success,
+    ).toBe(true);
+    // Only the OPENING marker is the corruption signature; a bare "]]>"
+    // inside a string literal is legitimate (e.g. code emitting XML).
+    expect(moduleCreateSchema.safeParse({ ...base, js: 'xml += "]]>";' }).success).toBe(true);
+  });
+
+  it("rejects CDATA on the update path too (edit_module / edit_content funnel)", () => {
+    const r = moduleUpdateSchema.safeParse({
+      moduleId: "8c2f2f2a-0000-4000-8000-000000000432",
+      css: "/*<![CDATA[*/ .x{} /*]]>*/",
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+// CLAUDE.md §1A / issue #417 — repeating content is a list field, never
+// numbered scalars. Threshold is 3: a pair (col1/col2) is a legitimate
+// layout split; three-or-more numbered siblings is a list.
+describe("moduleFields numbered-scalar fanout guard (§1A)", () => {
+  const mod = (fields: unknown) =>
+    moduleCreateSchema.safeParse({
+      slug: "cards",
+      displayName: "Cards",
+      html: "<div></div>",
+      fields,
+    });
+  const text = (name: string) => ({ name, kind: "text", label: name });
+
+  it("rejects a bare base + numbered siblings (label, label2, label3)", () => {
+    const r = mod([text("label"), text("label2"), text("label3")]);
+    expect(r.success).toBe(false);
+    if (!r.success) {
+      const msg = r.error.issues[0]?.message ?? "";
+      expect(msg).toContain("numbered-scalar fanout");
+      expect(msg).toContain('"label", "label2", "label3"');
+      // AI-actionable: the error names every list-kind fix.
+      expect(msg).toContain("text-list");
+      expect(msg).toContain("link-list");
+      expect(msg).toContain("module-list");
+      expect(msg).toContain("§1A");
+    }
+  });
+
+  it("rejects underscore-separated runs (quote_1..quote_3) and mixed separators", () => {
+    expect(mod([text("quote_1"), text("quote_2"), text("quote_3")]).success).toBe(false);
+    expect(mod([text("logo1"), text("logo_2"), text("logo_3")]).success).toBe(false);
+  });
+
+  it("rejects fanout on moduleUpdateSchema too (same shared fields array)", () => {
+    const r = moduleUpdateSchema.safeParse({
+      moduleId: "6f9619ff-8b86-4d01-b42d-00cf4fc964ff",
+      fields: [text("card1"), text("card2"), text("card3")],
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("allows a two-field split (col1/col2) — threshold is 3", () => {
+    expect(mod([text("col1"), text("col2")]).success).toBe(true);
+    expect(mod([text("label"), text("label2")]).success).toBe(true);
+    expect(mod([text("address_line1"), text("address_line2")]).success).toBe(true);
+  });
+
+  it("allows unrelated numbered fields that never form a run of 3", () => {
+    expect(mod([text("hero_title"), text("cta_2024"), text("step_1")]).success).toBe(true);
+    // Same suffix, different bases — no shared run.
+    expect(mod([text("left_col1"), text("right_col1"), text("mid_col1")]).success).toBe(true);
+  });
+
+  it("scopes to scalar kinds — numbered list fields are a modelling question, not fanout", () => {
+    const linkList = (name: string) => ({ name, kind: "link-list", label: name });
+    expect(mod([linkList("links1"), linkList("links2"), linkList("links3")]).success).toBe(true);
+  });
 });
 
 describe("pageCreateSchema (no raw HTML invariant)", () => {
@@ -84,7 +167,6 @@ describe("pageCreateSchema (no raw HTML invariant)", () => {
     });
     expect(r.success).toBe(true);
     if (!r.success) return;
-    expect(r.data.locale).toBe("en");
     // status is intentionally OPTIONAL (no schema default): pages.create
     // resolves it at write time — published on a bootstrap site, else draft.
     // Omitting it here leaves it undefined for the handler to resolve.

package/src/content.ts

@@ -84,11 +84,6 @@ export function slugifyModuleSection(
   return `${deriveModuleType(displayName)}-${idx}-${suffix}`;
 }
 
-/** BCP-47 shape: 2-letter language with optional 2-letter region. P9 widens this. */
-export const localeSchema = z
-  .string()
-  .regex(/^[a-z]{2}(-[A-Z]{2})?$/, "locale must be 'xx' or 'xx-YY' (BCP-47 shape)");
-
 const displayNameSchema = z.string().min(1).max(128);
 
 /** Caps are arbitrary but cheap — paste-of-binary mistakes get caught. */
@@ -99,8 +94,39 @@ export const TEMPLATE_HTML_MAX = 512 * 1024;
 export const TEMPLATE_CSS_MAX = 128 * 1024;
 
 const moduleHtml = z.string().max(MODULE_HTML_MAX, `html exceeds ${MODULE_HTML_MAX} bytes`);
-const moduleCss = z.string().max(MODULE_CSS_MAX, `css exceeds ${MODULE_CSS_MAX} bytes`);
-const moduleJs = z.string().max(MODULE_JS_MAX, `js exceeds ${MODULE_JS_MAX} bytes`);
+
+/**
+ * issue #432 root-cause guard — reject XML CDATA wrappers in module css/js.
+ *
+ * Module css/js is stored and served VERBATIM, so a `<![CDATA[ … ]]>`
+ * wrapper (an XHTML-era idiom the AI occasionally reaches for when
+ * "protecting" inline code) reaches the browser unparsed: the stylesheet
+ * fails to apply and the script throws `SyntaxError: Unexpected token '<'`.
+ * On e2e runs 31000584991 / 31000699422 (2026-08-05) exactly this landed
+ * silently, the page rendered broken, and the model burned ~15–20 extra
+ * loops (~+1.2M input tokens) discovering and repairing it via
+ * screenshot/inspect/edit cycles. Rejecting at the write boundary with an
+ * actionable message turns that repair spiral into a single corrected call
+ * (CLAUDE.md §11 — failure surfaces are AI-actionable; §2 — fail loudly).
+ *
+ * css/js only: CDATA is never valid CSS or JS, while an html body may
+ * legitimately carry CDATA inside inline `<svg>`/`<math>` foreign content.
+ */
+const CDATA_OPEN = "<![CDATA[";
+const noCdata = (value: string): boolean => !value.includes(CDATA_OPEN);
+const cdataMessage = (field: "css" | "js"): string =>
+  `${field} contains an XML CDATA marker (${CDATA_OPEN}) — module ${field} is stored and served ` +
+  `verbatim, so CDATA wrappers reach the browser unparsed and break rendering. ` +
+  `Remove the wrapper and resend plain ${field === "css" ? "CSS" : "JavaScript"}.`;
+
+const moduleCss = z
+  .string()
+  .max(MODULE_CSS_MAX, `css exceeds ${MODULE_CSS_MAX} bytes`)
+  .refine(noCdata, cdataMessage("css"));
+const moduleJs = z
+  .string()
+  .max(MODULE_JS_MAX, `js exceeds ${MODULE_JS_MAX} bytes`)
+  .refine(noCdata, cdataMessage("js"));
 
 /**
  * v0.4.0 — module field schema. Each field declares one substitution slot in
@@ -283,6 +309,54 @@ export const moduleRefSchema = z
   .strict();
 export type ModuleRef = z.infer<typeof moduleRefSchema>;
 
+/**
+ * CLAUDE.md §1A — "repeating content is a list field, never numbered
+ * scalars". This guard rejects the mechanically detectable half of that
+ * rule: a RUN of 3+ sibling scalar fields sharing a base name plus a
+ * numeric suffix (`label`, `label2`, `label3` / `quote_1`…`quote_3`).
+ *
+ * Threshold is 3 (issue #417): a two-field split (`col1`/`col2` for a
+ * two-column layout) is routinely a genuine layout role, so a pair stays
+ * legal; three-or-more numbered siblings is repeating content that must
+ * be ONE list field. The bare base name counts as an implicit member of
+ * its run — `label` next to `label2`/`label3` is item 1 in disguise.
+ *
+ * Deliberately out of scope (guidance-only, per the issue): content-
+ * derived names (`quote_justamazing`) and mid-name numbering
+ * (`step1_title`) — neither is detectable without false positives.
+ * Nested/list kinds are excluded too: a numbered run of lists is
+ * already a modelling question, not scalar fanout. The server-side
+ * extractor fallback (`extract-module-structure.ts`) is also
+ * unguarded on purpose: it numbers repeated tags in messy HUMAN-
+ * authored HTML, runs only when the caller declared no fields, and its
+ * output never re-enters this schema — the guard polices the boundary
+ * where the AI (or a human) AUTHORS `fields[]` explicitly.
+ */
+const NUMBERED_SCALAR_FANOUT_THRESHOLD = 3;
+const numberedFieldName = /^([a-z][a-z0-9_]*?)_?\d+$/;
+
+function findNumberedScalarFanoutRuns(
+  fields: readonly { name: string; kind: string }[],
+): string[][] {
+  const scalarKinds = new Set<string>(MODULE_FIELD_PRIMITIVE_KINDS);
+  const scalarNames = fields.filter((f) => scalarKinds.has(f.kind)).map((f) => f.name);
+  const byBase = new Map<string, string[]>();
+  for (const name of scalarNames) {
+    const m = numberedFieldName.exec(name);
+    const base = m?.[1];
+    if (base === undefined) continue;
+    const members = byBase.get(base);
+    if (members) members.push(name);
+    else byBase.set(base, [name]);
+  }
+  const runs: string[][] = [];
+  for (const [base, members] of byBase) {
+    const run = scalarNames.includes(base) ? [base, ...members] : members;
+    if (run.length >= NUMBERED_SCALAR_FANOUT_THRESHOLD) runs.push(run);
+  }
+  return runs;
+}
+
 const moduleFieldsArray = z
   .array(moduleFieldSchema)
   .max(64, "modules may declare at most 64 fields")
@@ -295,6 +369,20 @@ const moduleFieldsArray = z
       }
       seen.add(f.name);
     }
+    for (const run of findNumberedScalarFanoutRuns(arr)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          `numbered-scalar fanout: ${run.map((n) => `"${n}"`).join(", ")} repeat one role as ` +
+          "numbered scalar fields — repeating content is ONE list field, never numbered scalars " +
+          '(CLAUDE.md §1A). Replace the run with a single field: kind "text-list" (list of ' +
+          'strings, inner template iterates {{.}}), "link-list" (list of {label, href}), or ' +
+          '"module-list" (rich per-item structure: mint a card sub-module and reference it per ' +
+          "item — in build_page, author the card detached with `ref` and pass " +
+          '[{"$ref": "<ref>"}, …] as the field value). A two-field split like col1/col2 is fine; ' +
+          `${NUMBERED_SCALAR_FANOUT_THRESHOLD}+ numbered siblings is a list.`,
+      });
+    }
   });
 
 /**
@@ -457,7 +545,6 @@ export const pageStatusSchema = z.enum(["draft", "published"]);
 export const pageCreateSchema = z
   .object({
     slug: slugSchema,
-    locale: localeSchema.default("en"),
     /** P6.7.5 — internal editor label. Defaults to title if omitted. */
     name: z.string().min(1).max(256).optional(),
     title: z.string().min(1).max(256),

package/src/context.ts

@@ -31,6 +31,12 @@ export interface ExecutionContext {
    * fold consecutive AI actions into one entry.
    */
   readonly chatTaskId?: string;
+  /**
+   * For a plugin installed as an external artifact: the digest of the
+   * artifact this call runs. Private storage operations accept the call
+   * only while exactly this artifact is the active, granted one.
+   */
+  readonly pluginArtifactDigest?: string;
   /**
    * P10.5: parent attribution for subagent invocations. When the
    * `spawn_subagent` tool calls runChatTurn for the child, it carries

package/src/design-draft-shell.test.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #375 — theme-shell composition for growth-time design drafts:
+ * head order (fonts → theme vars → base), theme-asset placeholder
+ * resolution incl. the loud unbound path, and the no-theme degradation.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { composeDesignDraftShell } from "./design-draft-shell.js";
+import type { ComposeTheme } from "./preview-compose.js";
+import type { ThemeDocument } from "./themes.js";
+
+const TOKENS = {
+  color: {
+    background: { $type: "color", $value: "#ffffff" },
+    primary: { $type: "color", $value: "#4f46e5" },
+  },
+} as ThemeDocument;
+
+const THEME: ComposeTheme = {
+  tokens: TOKENS,
+  assets: {
+    logo: { mediaId: "11111111-1111-4111-8111-111111111111", url: "/_caelo/media/logo/orig" },
+    logoDark: null,
+    favicon: null,
+    socialShare: null,
+  },
+};
+
+const FRAGMENT = `<section class="hero"><h1>Real headline</h1><style>.hero{color:var(--color-primary)}</style></section>`;
+
+describe("composeDesignDraftShell (issue #375)", () => {
+  it("wraps the fragment in fonts → theme vars → base head order", () => {
+    const out = composeDesignDraftShell({
+      fragmentHtml: FRAGMENT,
+      theme: THEME,
+      fonts: { css: "@font-face{font-family:Inter}", preloads: ["/_caelo/fonts/inter/aa.woff2"] },
+      title: "Draft — bold",
+    });
+    expect(out.html).toStartWith("<!doctype html>");
+    expect(out.html).toContain('<style data-source="fonts">@font-face{font-family:Inter}');
+    expect(out.html).toContain('rel="preload" as="font"');
+    expect(out.html).toContain('<style data-source="theme">');
+    expect(out.html).toContain("--color-primary:#4f46e5");
+    expect(out.html).toContain('<style data-source="base">');
+    expect(out.html).toContain(FRAGMENT);
+    expect(out.missingSlots).toEqual([]);
+    const fontsAt = out.html.indexOf('data-source="fonts"');
+    const themeAt = out.html.indexOf('data-source="theme"');
+    const baseAt = out.html.indexOf('data-source="base"');
+    expect(fontsAt).toBeLessThan(themeAt);
+    expect(themeAt).toBeLessThan(baseAt);
+  });
+
+  it("substitutes bound theme-asset placeholders and flags unbound ones loudly", () => {
+    const out = composeDesignDraftShell({
+      fragmentHtml: `<img src="{{theme_logo_url}}"><img src="{{theme_favicon_url}}">`,
+      theme: THEME,
+      title: "assets",
+    });
+    expect(out.html).toContain('src="/_caelo/media/logo/orig"');
+    // Unbound slot: placeholder survives raw IN PLACE (§2 no-fallbacks;
+    // the attribute value must not be corrupted by an inline marker) …
+    expect(out.html).toContain('src="{{theme_favicon_url}}"');
+    // … and the marker rides as a real comment node at the body's end.
+    expect(out.html).toContain("<!-- caelo:missing reason=theme-asset-unbound:favicon --></body>");
+    expect(out.missingSlots).toEqual(["theme-asset-unbound:favicon"]);
+  });
+
+  it("renders without theme vars when no theme exists (visibly broken on purpose)", () => {
+    const out = composeDesignDraftShell({ fragmentHtml: FRAGMENT, title: "no theme" });
+    expect(out.html).not.toContain('data-source="theme"');
+    expect(out.html).not.toContain('data-source="fonts"');
+    expect(out.html).toContain('data-source="base"');
+  });
+
+  it("escapes the document title", () => {
+    const out = composeDesignDraftShell({
+      fragmentHtml: FRAGMENT,
+      title: `<script>"x"</script>`,
+    });
+    expect(out.html).toContain("<title>&lt;script&gt;&quot;x&quot;&lt;/script&gt;</title>");
+  });
+});

package/src/design-draft-shell.ts

@@ -0,0 +1,109 @@
+// 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 { type ComposeFonts, type ComposeTheme, 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",
+} as const;
+
+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[];
+}
+
+/**
+ * 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: string,
+  theme: ComposeTheme | undefined,
+  missing: string[],
+): string {
+  return html.replace(/\{\{\s*(theme_[a-z_]+)\s*\}\}/g, (match, key: string) => {
+    const slot = THEME_ASSET_KEY_TO_SLOT[key as keyof typeof THEME_ASSET_KEY_TO_SLOT];
+    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: DesignDraftShellInput): DesignDraftShellOutput {
+  const missing: string[] = [];
+  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: string[] = [
+    `<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: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/src/font-assets.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MPL-2.0
+import { z } from "zod";
+
+export const fontRef = z
+  .object({ id: z.string().uuid(), sha256: z.string().regex(/^[a-f0-9]{64}$/) })
+  .strict();
+export const fontLicense = z
+  .object({
+    name: z.string().min(1).max(200),
+    text: z.string().min(1).max(100_000),
+    webEmbedding: z.boolean(),
+    documentEmbedding: z.boolean(),
+  })
+  .strict();
+export const fontMetadata = fontRef.extend({
+  family: z.string(),
+  subfamily: z.string(),
+  postscriptName: z.string(),
+  cssFamily: z.string(),
+  format: z.enum(["ttf", "otf", "woff", "woff2"]),
+  weight: z.number(),
+  style: z.enum(["normal", "italic"]),
+  axes: z.record(z.string(), z.object({ min: z.number(), max: z.number(), default: z.number() })),
+  sizeBytes: z.number(),
+  glyphCount: z.number(),
+  embedding: z.object({
+    web: z.boolean(),
+    document: z.boolean(),
+    subset: z.boolean(),
+    restriction: z.string().nullable(),
+  }),
+  license: fontLicense,
+  source: z.string(),
+  createdAt: z.string(),
+});
+export type FontRef = z.infer<typeof fontRef>;
+export type FontMetadata = z.infer<typeof fontMetadata>;
+export const fontImportInput = z
+  .object({
+    dataBase64: z.string().min(1).max(11_184_812),
+    license: fontLicense,
+    source: z.string().min(1).max(1000),
+  })
+  .strict();
+export const fontResolveInput = fontRef
+  .extend({
+    use: z.enum(["web", "document"]),
+    text: z.string().max(200_000).default(""),
+    formats: z
+      .array(z.enum(["ttf", "otf", "woff", "woff2"]))
+      .min(1)
+      .max(4),
+  })
+  .strict();
+export const fontReadInput = fontRef
+  .extend({ offset: z.number().int().min(0), length: z.number().int().min(1).max(262144) })
+  .strict();
+export const fontFindInput = z
+  .object({
+    query: z.string().max(200).default(""),
+    limit: z.number().int().min(1).max(100).default(50),
+  })
+  .strict();