@bendyline/squisq 1.2.2 → 1.4.0

package/src/schemas/ImageEditDoc.ts

@@ -0,0 +1,95 @@
+/**
+ * ImageEditDoc — JSON document describing a layered, editable image.
+ *
+ * This is the persistent state of the `<ImageEditor>` component. It lives
+ * inside a `<imagebasename>_files/` sidecar folder (exposed as a
+ * {@link ContentContainer}) at `state.json`, alongside referenced asset
+ * bytes in `assets/` and version snapshots in `.versions/`.
+ *
+ * Layers compose the existing core {@link Layer} types (image / text /
+ * shape) so renderers can share infrastructure with the doc system.
+ * Editor-specific metadata (name, visibility, lock, opacity, blendMode)
+ * lives in {@link EditorLayerMeta} and is merged onto each layer. The
+ * {@link Layer.animation} field is permitted but ignored by the image
+ * editor — animations are a slideshow concept.
+ *
+ * All asset paths in layers (e.g. `ImageLayer.content.src`) are
+ * relative to the sidecar root, keeping the document portable.
+ */
+
+import type { ImageLayer, ShapeLayer, TextLayer } from './Doc.js';
+
+// ============================================
+// Layer type
+// ============================================
+
+/**
+ * Per-layer editor metadata. Merged into each layer so the persisted
+ * shape is a single object. All fields optional; sensible defaults
+ * apply when absent (visible: true, locked: false, opacity: 1).
+ */
+export interface EditorLayerMeta {
+  /** Human-readable name shown in the layers panel. */
+  name?: string;
+  /** When false, the layer is hidden from rendering. Default true. */
+  visible?: boolean;
+  /** When true, the layer cannot be selected/edited. Default false. */
+  locked?: boolean;
+  /** 0..1 multiplier on the layer's alpha. Default 1. */
+  opacity?: number;
+  /**
+   * Canvas blend mode (matches the CSS / Canvas2D vocabulary).
+   * Default 'source-over' (normal compositing).
+   */
+  blendMode?: GlobalCompositeOperation;
+}
+
+/** A layer in an {@link ImageEditDoc}. */
+export type ImageEditLayer = (ImageLayer | TextLayer | ShapeLayer) & EditorLayerMeta;
+
+/** The layer kinds the image editor supports. */
+export type ImageEditLayerKind = ImageEditLayer['type'];
+
+// ============================================
+// Document
+// ============================================
+
+/** Canvas dimensions and background. */
+export interface ImageEditCanvas {
+  /** Canvas width in pixels. */
+  width: number;
+  /** Canvas height in pixels. */
+  height: number;
+  /**
+   * Background fill (CSS color, or `'transparent'` for an alpha canvas).
+   * Default: `'transparent'`.
+   */
+  background?: string;
+}
+
+/** Optional document metadata. */
+export interface ImageEditMeta {
+  /** Path to the original source image (sidecar-relative). Set when the doc is seeded from an existing image. */
+  sourcePath?: string;
+  /** ISO timestamp set on first save. */
+  createdAt?: string;
+  /** ISO timestamp updated on every save. */
+  updatedAt?: string;
+}
+
+/**
+ * The persisted image-editor document.
+ *
+ * Layers are composited back-to-front: `layers[0]` is the bottom of the stack
+ * (typically the base raster), `layers[layers.length - 1]` is the top.
+ */
+export interface ImageEditDoc {
+  /** Schema version. Bumped on breaking changes. */
+  version: 1;
+  /** Canvas configuration. */
+  canvas: ImageEditCanvas;
+  /** Layers, back-to-front. */
+  layers: ImageEditLayer[];
+  /** Optional metadata. */
+  meta?: ImageEditMeta;
+}

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,5 +272,93 @@ 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;
 }
+
+// ============================================
+// Surface Schemes — orthogonal to Theme
+// ============================================
+
+/**
+ * A Surface Scheme is the light/dark axis, orthogonal to the editorial
+ * 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.
+ */
+export interface SurfaceScheme {
+  /** Identifier — 'light', 'dark', or a custom id. */
+  id: string;
+  background: string;
+  backgroundLight: string;
+  text: string;
+  textMuted: string;
+}
+
+/** Near-white paper with dark text — standard light mode. */
+export const LIGHT_SURFACE: SurfaceScheme = {
+  id: 'light',
+  background: '#ffffff',
+  backgroundLight: '#f5f5f5',
+  text: '#1a1a1a',
+  textMuted: '#666666',
+};
+
+/** Dark charcoal paper with light text — standard dark mode. */
+export const DARK_SURFACE: SurfaceScheme = {
+  id: 'dark',
+  background: '#1a202c',
+  backgroundLight: '#2d3748',
+  text: '#f0f0f0',
+  textMuted: '#a0aec0',
+};
+
+/**
+ * Overlay a SurfaceScheme's surface colors onto a Theme's palette,
+ * leaving everything else (primary, highlight, warning, typography,
+ * style, renderStyle, colorSchemes) untouched.
+ */
+export function applySurface(theme: Theme, surface: SurfaceScheme): Theme {
+  return {
+    ...theme,
+    colors: {
+      ...theme.colors,
+      background: surface.background,
+      backgroundLight: surface.backgroundLight,
+      text: surface.text,
+      textMuted: surface.textMuted,
+    },
+  };
+}
+
+// ============================================
+// 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),
+  };
+}