@bendyline/squisq 1.3.0 → 1.4.1

package/src/schemas/Theme.ts

@@ -3,25 +3,41 @@
  *
  * A Theme bundles color palette, typography, visual style, render-style
  * algorithm, and per-block color schemes into one JSON-serializable object.
- * Builders choose a theme from the built-in library or create a custom one
- * via `createTheme(base, overrides)`.
+ *
+ * Built-in themes and customizer-authored themes share this exact schema.
+ * Customizer-authored themes additionally specify `seedColors` so the few
+ * fields the user picked can be re-edited later; built-ins typically omit
+ * `seedColors` and ship with explicit `colors` already filled in.
  *
  * Design principles:
- * - Fully JSON-serializable (no functions) — storable in config / APIs.
- * - Doc carries an optional `themeId` pointer; resolution happens at render time.
- * - `createTheme` deep-merges a base theme with partial overrides.
+ * - Fully JSON-serializable. No functions; no raw CSS font strings.
+ * - Font families are structured `FontFamily` references resolved by
+ *   `resolveFontFamily()` at render time.
+ * - Doc carries an optional `themeId`; resolution happens at render time
+ *   via `resolveTheme(id)`.
+ * - `createTheme` deep-merges a base theme with partial overrides;
+ *   `compileTheme` fills in defaults and derives missing color slots from
+ *   `seedColors`; both produce a complete `Theme`.
  */
 
 import type { LayoutHints } from './LayoutStrategy.js';
 import type { AnimationType, TransitionType } from './Doc.js';
 import type { PersistentLayerConfig } from './BlockTemplates.js';
 
+// ============================================
+// Schema version
+// ============================================
+
+/** Current Theme schema version. Bump on breaking changes; loader migrates. */
+export const THEME_SCHEMA_VERSION = '1' as const;
+export type ThemeSchemaVersion = typeof THEME_SCHEMA_VERSION;
+
 // ============================================
 // Color Palette
 // ============================================
 
 /**
- * Core color palette for a theme. Every color is a CSS color string.
+ * Core color palette for a theme. Every color is a `#rrggbb` hex string.
  */
 export interface ThemeColorPalette {
   /** Primary accent color */
@@ -55,20 +71,51 @@ export interface ThemeColorScheme {
   accent: string;
 }
 
+/**
+ * Optional authoring metadata. When present and `colors` is partial,
+ * `compileTheme` derives missing color slots from these seeds via OKLCh
+ * lightening / darkening. Round-trips a customizer-authored theme back
+ * into editable form.
+ */
+export interface ThemeSeedColors {
+  primary: string;
+  secondary?: string;
+  accent?: string;
+  background?: string;
+  text?: string;
+}
+
 // ============================================
 // Typography
 // ============================================
 
+/** Categorical bucket for a font family — drives default fallback. */
+export type FontFamilyKind = 'sans' | 'serif' | 'mono' | 'display';
+
+/**
+ * Structured reference to a font family. Either a curated stack id (looked
+ * up in `AVAILABLE_FONT_STACKS`) or a custom user-supplied name with a
+ * structured fallback bucket. Themes never carry raw CSS family strings.
+ */
+export type FontFamily =
+  | { stackId: string }
+  | {
+      custom: {
+        name: string;
+        fallback: 'serif' | 'sans-serif' | 'monospace' | 'system-ui';
+      };
+    };
+
 /**
  * Typography settings for a theme.
  */
 export interface ThemeTypography {
   /** Font family for body / description text */
-  bodyFontFamily: string;
+  bodyFont: FontFamily;
   /** Font family for titles and headings */
-  titleFontFamily: string;
+  titleFont: FontFamily;
   /** Font family for code / monospaced text (optional) */
-  monoFontFamily?: string;
+  monoFont?: FontFamily;
   /** Multiplier applied to LayoutHints.titleScale (default 1.0) */
   titleScale?: number;
   /** Multiplier applied to LayoutHints.bodyScale (default 1.0) */
@@ -125,11 +172,8 @@ export interface RenderStyle {
   /**
    * Per-template behavioral hints. Keys are template names, values are
    * string/number/boolean maps that templates can read to vary their output.
-   *
-   * @example
-   * ```
-   * { statHighlight: { entrance: 'dramatic' }, titleBlock: { showAccentLine: false } }
-   * ```
+   * Templates that consume hints publish a `hintSchema` export documenting
+   * the keys they recognise.
    */
   templateHints?: Record<string, Record<string, string | number | boolean>>;
 }
@@ -139,15 +183,20 @@ export interface RenderStyle {
 // ============================================
 
 /**
- * A complete, JSON-serializable theme definition.
+ * A complete, JSON-serializable theme definition. Built-in and customizer-
+ * authored themes share this exact shape.
  */
 export interface Theme {
+  /** Schema version. Always '1' for now. */
+  schemaVersion: ThemeSchemaVersion;
   /** Unique identifier (e.g. "documentary") */
   id: string;
   /** Human-readable display name */
   name: string;
   /** Short description for theme pickers */
   description?: string;
+  /** Optional authoring seeds (customizer fills these; built-ins typically omit) */
+  seedColors?: ThemeSeedColors;
   /** Color palette */
   colors: ThemeColorPalette;
   /** Typography settings */
@@ -214,14 +263,6 @@ function deepMerge<T extends Record<string, unknown>>(target: T, source: DeepPar
  * Create a new theme by deep-merging overrides onto a base theme.
  * The returned theme gets its own `id` if one is provided in overrides,
  * otherwise keeps the base theme's `id` suffixed with "-custom".
- *
- * @example
- * ```ts
- * const myTheme = createTheme(THEMES.documentary, {
- *   colors: { primary: '#ff0000' },
- *   typography: { bodyFontFamily: '"Inter", sans-serif' },
- * });
- * ```
  */
 export function createTheme(base: Theme, overrides: DeepPartial<Theme>): Theme {
   const merged = deepMerge(
@@ -231,6 +272,7 @@ export function createTheme(base: Theme, overrides: DeepPartial<Theme>): Theme {
   if (!overrides.id && merged.id === base.id) {
     merged.id = `${base.id}-custom`;
   }
+  if (!merged.schemaVersion) merged.schemaVersion = THEME_SCHEMA_VERSION;
   return merged;
 }
 
@@ -243,11 +285,6 @@ export function createTheme(base: Theme, overrides: DeepPartial<Theme>): Theme {
  * identity of a Theme. A Theme chooses voice (serif vs sans, muted vs
  * bold, documentary vs magazine); a SurfaceScheme chooses what the paper
  * looks like. Any theme can render on either surface.
- *
- * When a SurfaceScheme is applied to a Theme (via `applySurface`), these
- * fields override the corresponding entries in `ThemeColorPalette` —
- * everything else (primary, highlight, warning, etc.) stays as the theme
- * defined it.
  */
 export interface SurfaceScheme {
   /** Identifier — 'light', 'dark', or a custom id. */
@@ -279,9 +316,7 @@ export const DARK_SURFACE: SurfaceScheme = {
 /**
  * Overlay a SurfaceScheme's surface colors onto a Theme's palette,
  * leaving everything else (primary, highlight, warning, typography,
- * style, renderStyle, colorSchemes) untouched. Returns a new Theme;
- * callers that want to preserve the original's id should set it
- * explicitly in the overrides.
+ * style, renderStyle, colorSchemes) untouched.
  */
 export function applySurface(theme: Theme, surface: SurfaceScheme): Theme {
   return {
@@ -295,3 +330,35 @@ export function applySurface(theme: Theme, surface: SurfaceScheme): Theme {
     },
   };
 }
+
+// ============================================
+// Runtime registry — for custom themes
+// ============================================
+
+const CUSTOM_THEME_REGISTRY = new Map<string, Theme>();
+
+/**
+ * Register a Theme so it can be looked up by id via `resolveTheme(id)`.
+ * Lets `Doc.themeId` round-trip through Doc serialization for custom themes.
+ *
+ * Registered themes take precedence over built-ins with the same id.
+ */
+export function registerTheme(theme: Theme): void {
+  CUSTOM_THEME_REGISTRY.set(theme.id, theme);
+}
+
+/** Remove a previously registered theme. */
+export function unregisterTheme(id: string): void {
+  CUSTOM_THEME_REGISTRY.delete(id);
+}
+
+/** Snapshot of all currently registered (non-built-in) themes. */
+export function getRegisteredThemes(): Theme[] {
+  return Array.from(CUSTOM_THEME_REGISTRY.values());
+}
+
+/** @internal — used by themeLibrary's `resolveTheme` to check the registry first. */
+export function lookupRegisteredTheme(id: string | undefined): Theme | undefined {
+  if (!id) return undefined;
+  return CUSTOM_THEME_REGISTRY.get(id);
+}

package/src/schemas/colorUtils.ts

@@ -0,0 +1,186 @@
+/**
+ * Color Utilities
+ *
+ * Pure-JS color math used by theme compilation and contrast checks.
+ * No dependencies. Operates on `#rrggbb` hex strings.
+ *
+ * Internally uses OKLCh — perceptually uniform, so lightening by 0.1
+ * looks like the same change at any starting point. Out-of-gamut
+ * results are clamped to sRGB.
+ */
+
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/** Test whether a string is a valid `#rgb` or `#rrggbb` hex color. */
+export function isHex(value: string): boolean {
+  return HEX_RE.test(value);
+}
+
+/** Parse `#rgb` or `#rrggbb` into 0..1 sRGB triplet. Returns null on failure. */
+function parseHex(hex: string): [number, number, number] | null {
+  if (!HEX_RE.test(hex)) return null;
+  let body = hex.slice(1);
+  if (body.length === 3)
+    body = body
+      .split('')
+      .map((c) => c + c)
+      .join('');
+  return [
+    parseInt(body.slice(0, 2), 16) / 255,
+    parseInt(body.slice(2, 4), 16) / 255,
+    parseInt(body.slice(4, 6), 16) / 255,
+  ];
+}
+
+function toHex(rgb: [number, number, number]): string {
+  const ch = (v: number) => {
+    const c = Math.max(0, Math.min(255, Math.round(v * 255)));
+    return c.toString(16).padStart(2, '0');
+  };
+  return '#' + ch(rgb[0]) + ch(rgb[1]) + ch(rgb[2]);
+}
+
+function srgbToLinear(c: number): number {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+function linearToSrgb(c: number): number {
+  return c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+
+interface OKLCh {
+  L: number;
+  C: number;
+  h: number;
+}
+
+function rgbToOklch(rgb: [number, number, number]): OKLCh {
+  const [sr, sg, sb] = rgb;
+  const r = srgbToLinear(sr);
+  const g = srgbToLinear(sg);
+  const b = srgbToLinear(sb);
+
+  const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+  const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+  const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+
+  const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+  const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+  const bb = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+
+  const C = Math.sqrt(a * a + bb * bb);
+  let h = (Math.atan2(bb, a) * 180) / Math.PI;
+  if (h < 0) h += 360;
+  return { L, C, h };
+}
+
+function oklchToRgb({ L, C, h }: OKLCh): [number, number, number] {
+  const hr = (h * Math.PI) / 180;
+  const a = C * Math.cos(hr);
+  const bb = C * Math.sin(hr);
+
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * bb;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * bb;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * bb;
+
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+
+  const r = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const b = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+
+  return [
+    Math.max(0, Math.min(1, linearToSrgb(r))),
+    Math.max(0, Math.min(1, linearToSrgb(g))),
+    Math.max(0, Math.min(1, linearToSrgb(b))),
+  ];
+}
+
+/**
+ * Lighten a color by `amount` (0..1) in OKLCh L space.
+ * Falls back to the input on parse failure.
+ */
+export function oklchLighten(hex: string, amount: number): string {
+  const rgb = parseHex(hex);
+  if (!rgb) return hex;
+  const lch = rgbToOklch(rgb);
+  lch.L = Math.max(0, Math.min(1, lch.L + amount));
+  return toHex(oklchToRgb(lch));
+}
+
+/**
+ * Darken a color by `amount` (0..1) in OKLCh L space.
+ * Falls back to the input on parse failure.
+ */
+export function oklchDarken(hex: string, amount: number): string {
+  return oklchLighten(hex, -amount);
+}
+
+/**
+ * Adjust the OKLCh chroma of a color by a multiplier (e.g. 0.7 to mute).
+ */
+export function oklchSetChroma(hex: string, multiplier: number): string {
+  const rgb = parseHex(hex);
+  if (!rgb) return hex;
+  const lch = rgbToOklch(rgb);
+  lch.C = Math.max(0, lch.C * multiplier);
+  return toHex(oklchToRgb(lch));
+}
+
+/**
+ * WCAG relative luminance of a hex color, returned as 0..1.
+ */
+export function relativeLuminance(hex: string): number {
+  const rgb = parseHex(hex);
+  if (!rgb) return 0;
+  const [r, g, b] = rgb.map(srgbToLinear) as [number, number, number];
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * WCAG contrast ratio between two hex colors. Returns 1..21.
+ */
+export function contrastRatio(a: string, b: string): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const lighter = Math.max(la, lb);
+  const darker = Math.min(la, lb);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Pick a near-white or near-black text color that contrasts well against `bg`.
+ */
+export function pickContrastingText(bg: string, light = '#f7fafc', dark = '#1a202c'): string {
+  return contrastRatio(bg, dark) >= contrastRatio(bg, light) ? dark : light;
+}
+
+/**
+ * Derive a 5-step lighter→darker scale from a seed color.
+ * Stops are evenly spaced in OKLCh L space around the seed.
+ * `spread` controls amplitude (0.05 = subtle, 0.15 = balanced, 0.22 = high).
+ */
+export function deriveScale(
+  seedHex: string,
+  spread = 0.15,
+): {
+  lighter2: string;
+  lighter1: string;
+  base: string;
+  darker1: string;
+  darker2: string;
+} {
+  return {
+    lighter2: oklchLighten(seedHex, spread),
+    lighter1: oklchLighten(seedHex, spread / 2),
+    base: seedHex,
+    darker1: oklchDarken(seedHex, spread / 2),
+    darker2: oklchDarken(seedHex, spread),
+  };
+}

package/src/schemas/fontStacks.ts

@@ -0,0 +1,257 @@
+/**
+ * Font Stacks
+ *
+ * Curated registry of font families used by built-in themes and offered in
+ * the theme customizer. Each stack has a stable `id` (referenced by JSON
+ * theme files via `{ stackId }`) and a CSS `family` string that resolves
+ * to the actual font when rendered.
+ *
+ * Themes never carry raw CSS font strings — they reference a `stackId` or
+ * specify a `{ custom: { name, fallback } }` form, both of which resolve
+ * here at render time.
+ */
+
+import type { FontFamily, FontFamilyKind } from './Theme.js';
+
+export interface FontStack {
+  /** Stable identifier referenced by Theme JSON. */
+  id: string;
+  /** Display label for pickers. */
+  label: string;
+  /** Full CSS font-family string with safe fallbacks. */
+  family: string;
+  /** Categorical bucket for the picker UI. */
+  kind: FontFamilyKind;
+  /**
+   * Google Fonts family name, when this stack is served by Google Fonts.
+   * Used by exports that bundle a `<link>` to fonts.googleapis.com so the
+   * face renders correctly even when the host page doesn't preload it.
+   * Omit (or set to undefined) for purely system stacks.
+   */
+  googleFontFamily?: string;
+}
+
+/** All curated stacks, in the order they should appear in pickers. */
+export const AVAILABLE_FONT_STACKS: FontStack[] = [
+  // System defaults
+  {
+    id: 'system-sans',
+    label: 'System Sans',
+    family: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+    kind: 'sans',
+  },
+  {
+    id: 'system-serif',
+    label: 'System Serif',
+    family: 'Georgia, "Times New Roman", serif',
+    kind: 'serif',
+  },
+  {
+    id: 'system-mono',
+    label: 'System Mono',
+    family: 'Consolas, "Courier New", monospace',
+    kind: 'mono',
+  },
+  // Curated Google Fonts. `googleFontFamily` is the canonical family
+  // name Google serves the face under (used by exports that emit a
+  // `<link rel="stylesheet" href="https://fonts.googleapis.com/...">`
+  // so the face renders even when the host doesn't preload it).
+  {
+    id: 'inter',
+    label: 'Inter',
+    family: '"Inter", "Segoe UI", Roboto, sans-serif',
+    kind: 'sans',
+    googleFontFamily: 'Inter',
+  },
+  {
+    id: 'ibm-plex-sans',
+    label: 'IBM Plex Sans',
+    family: '"IBM Plex Sans", "Segoe UI", Roboto, sans-serif',
+    kind: 'sans',
+    googleFontFamily: 'IBM Plex Sans',
+  },
+  {
+    id: 'roboto',
+    label: 'Roboto',
+    family: '"Roboto", "Segoe UI", Arial, sans-serif',
+    kind: 'sans',
+    googleFontFamily: 'Roboto',
+  },
+  {
+    id: 'dm-sans',
+    label: 'DM Sans',
+    family: '"DM Sans", "Segoe UI", Roboto, sans-serif',
+    kind: 'sans',
+    googleFontFamily: 'DM Sans',
+  },
+  {
+    id: 'oswald',
+    label: 'Oswald',
+    family: '"Oswald", Impact, "Arial Black", sans-serif',
+    kind: 'display',
+    googleFontFamily: 'Oswald',
+  },
+  {
+    id: 'playfair',
+    label: 'Playfair Display',
+    family: '"Playfair Display", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Playfair Display',
+  },
+  {
+    id: 'source-serif',
+    label: 'Source Serif',
+    family: '"Source Serif 4", "PT Serif", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Source Serif 4',
+  },
+  {
+    id: 'merriweather',
+    label: 'Merriweather',
+    family: '"Merriweather", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Merriweather',
+  },
+  {
+    id: 'lora',
+    label: 'Lora',
+    family: '"Lora", "Merriweather", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Lora',
+  },
+  {
+    id: 'pt-serif',
+    label: 'PT Serif',
+    family: '"PT Serif", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'PT Serif',
+  },
+  {
+    id: 'crimson',
+    label: 'Crimson Text',
+    family: '"Crimson Text", Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Crimson Text',
+  },
+  {
+    id: 'cormorant',
+    label: 'Cormorant Garamond',
+    family: '"Cormorant Garamond", Garamond, Georgia, serif',
+    kind: 'serif',
+    googleFontFamily: 'Cormorant Garamond',
+  },
+  {
+    id: 'dm-serif',
+    label: 'DM Serif Display',
+    family: '"DM Serif Display", Georgia, serif',
+    kind: 'display',
+    googleFontFamily: 'DM Serif Display',
+  },
+  {
+    id: 'jetbrains-mono',
+    label: 'JetBrains Mono',
+    family: '"JetBrains Mono", "Fira Code", Consolas, monospace',
+    kind: 'mono',
+    googleFontFamily: 'JetBrains Mono',
+  },
+  // Themed system stacks with emoji fallbacks (used by gezellig)
+  {
+    id: 'system-sans-emoji',
+    label: 'System Sans + Emoji',
+    family:
+      'system-ui, -apple-system, "Segoe UI", Roboto, "OpenMoji Color", "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", sans-serif',
+    kind: 'sans',
+  },
+  {
+    id: 'system-serif-emoji',
+    label: 'System Serif + Emoji',
+    family:
+      'Georgia, "Times New Roman", "OpenMoji Color", "Apple Color Emoji", "Segoe UI Emoji", "Noto Color Emoji", serif',
+    kind: 'serif',
+  },
+];
+
+const STACKS_BY_ID: Record<string, FontStack> = Object.fromEntries(
+  AVAILABLE_FONT_STACKS.map((s) => [s.id, s]),
+);
+
+/** Look up a stack by id. Returns undefined if not registered. */
+export function getFontStack(id: string): FontStack | undefined {
+  return STACKS_BY_ID[id];
+}
+
+/** Default fallback CSS family per kind, used when a custom font has no fallback specified. */
+const FALLBACK_BY_KIND: Record<FontFamilyKind, string> = {
+  sans: 'system-ui, sans-serif',
+  serif: 'Georgia, serif',
+  mono: 'Consolas, monospace',
+  display: 'Impact, Arial, sans-serif',
+};
+
+/**
+ * Resolve a `FontFamily` reference (or legacy raw string) to a CSS family string.
+ * Used by `getThemeFont` at render time. Never returns an empty string —
+ * unrecognized stackIds fall back to the requested role's default.
+ */
+export function resolveFontFamily(
+  family: FontFamily | string | undefined,
+  roleFallback: string,
+): string {
+  if (!family) return roleFallback;
+  if (typeof family === 'string') return family;
+  if ('stackId' in family) {
+    const stack = STACKS_BY_ID[family.stackId];
+    return stack ? stack.family : roleFallback;
+  }
+  if ('custom' in family) {
+    const { name, fallback } = family.custom;
+    const fb =
+      fallback === 'system-ui'
+        ? 'system-ui, sans-serif'
+        : fallback === 'serif'
+          ? 'Georgia, serif'
+          : fallback === 'monospace'
+            ? 'Consolas, monospace'
+            : 'system-ui, sans-serif';
+    const safeName = name.includes(' ') || name.includes(',') ? `"${name}"` : name;
+    return `${safeName}, ${fb}`;
+  }
+  return roleFallback;
+}
+
+/** Convenience: quick `{ stackId }` factory for code that constructs themes. */
+export function fontStack(id: string): FontFamily {
+  return { stackId: id };
+}
+
+/**
+ * Build a `https://fonts.googleapis.com/css2?...` URL that loads the
+ * subset of supplied `FontFamily` references that are served by Google
+ * Fonts. Returns `null` when nothing in the list needs Google hosting
+ * (system stacks, custom fonts, or unknown stack ids) — callers can use
+ * that to skip emitting a `<link>` entirely.
+ *
+ * The URL requests regular + bold (400/700) for each family, which is
+ * what the templates use. `display=swap` keeps the fallback visible
+ * while the web font streams in.
+ */
+export function buildGoogleFontsUrl(families: Array<FontFamily | undefined>): string | null {
+  const names = new Set<string>();
+  for (const f of families) {
+    if (!f || typeof f === 'string') continue;
+    if ('stackId' in f) {
+      const stack = STACKS_BY_ID[f.stackId];
+      if (stack?.googleFontFamily) names.add(stack.googleFontFamily);
+    }
+  }
+  if (names.size === 0) return null;
+  // css2 syntax: ?family=Name+With+Spaces:wght@400;700&family=Other:wght@400;700&display=swap
+  const params = Array.from(names)
+    .sort()
+    .map((name) => `family=${encodeURIComponent(name).replace(/%20/g, '+')}:wght@400;700`)
+    .join('&');
+  return `https://fonts.googleapis.com/css2?${params}&display=swap`;
+}
+
+/** Default fallback families exposed for tools that need them. */
+export const FONT_FALLBACKS = FALLBACK_BY_KIND;

package/src/schemas/index.ts

@@ -3,6 +3,10 @@ export * from './Doc.js';
 export * from './BlockTemplates.js';
 export * from './Theme.js';
 export * from './themeLibrary.js';
+export * from './themeValidator.js';
+export * from './themeCompile.js';
+export * from './fontStacks.js';
+export * from './colorUtils.js';
 export * from './Viewport.js';
 export {
   getLayoutHints,
@@ -12,3 +16,11 @@ export {
 } from './LayoutStrategy.js';
 export type { LayoutHints } from './LayoutStrategy.js';
 export type { MediaProvider, MediaEntry } from './MediaProvider.js';
+export type {
+  ImageEditDoc,
+  ImageEditLayer,
+  ImageEditLayerKind,
+  ImageEditCanvas,
+  ImageEditMeta,
+  EditorLayerMeta,
+} from './ImageEditDoc.js';