@bendyline/squisq 1.5.2 → 2.0.1

package/src/schemas/BlockTemplates.ts

@@ -110,6 +110,19 @@ interface BaseTemplateBlock {
    * Used with sourceStartTime to precisely position the block.
    */
   sourceDuration?: number;
+  /**
+   * Transform provenance: the id of the source Block this template block
+   * was derived from. Lets narration timing (and any per-source styling)
+   * be remapped onto transformed/summarized docs.
+   */
+  sourceBlockId?: string;
+  /** All source block ids when the block summarizes more than one. */
+  sourceBlockIds?: string[];
+  /**
+   * Char offset of the extraction inside the source block's plain text.
+   * Provenance only — NOT a time (see sourceStartTime for seconds).
+   */
+  sourceCharOffset?: number;
   /**
    * Per-block override for the theme's photographic image grade
    * (`theme.style.imageTreatment`). `'none'` opts this block's imagery out;
@@ -357,6 +370,92 @@ export interface ListBlockInput extends BaseTemplateBlock {
   accentImage?: AccentImage;
 }
 
+/**
+ * Tree block — renders a hierarchical filesystem-style treeview from an
+ * ASCII tree fence (file trees, dependency trees, outlines). The nested
+ * `items` arrive via `templateData`, derived from the fence by the pipeline
+ * (peer to how `diagram` receives `nodes`/`edges`).
+ */
+export interface TreeBlockInput extends BaseTemplateBlock {
+  template: 'tree';
+  /** Nested tree items (usually via `templateData.items`). */
+  items?: TreeTemplateItem[];
+  /** Optional title above the tree. */
+  title?: string;
+  /** Color scheme for folder rows / icons. */
+  colorScheme?: ColorScheme;
+}
+
+/** One node supplied via `templateData.items` (mirrors `TreeLayerItem`). */
+export interface TreeTemplateItem {
+  id: string;
+  label: string;
+  isDir?: boolean;
+  comment?: string;
+  children: TreeTemplateItem[];
+}
+
+/**
+ * One point on a timeline track. Event positions are normalized across the
+ * whole timeline (0 = left edge, 1 = right edge) so events on separate tracks
+ * remain horizontally comparable.
+ */
+export interface TimelineTemplateEvent {
+  /** Stable id used by cross-track branch links. */
+  id: string;
+  /** Short label displayed next to the event dot. */
+  label: string;
+  /** Optional longer callout text. */
+  description?: string;
+  /** Normalized horizontal position; renderers clamp values to 0..1. */
+  position: number;
+  /** Preferred callout placement. Defaults to alternating above/below. */
+  side?: 'above' | 'below';
+  /** Description placement when it should sit opposite the event label. */
+  descriptionSide?: 'above' | 'below';
+  /** False renders the point only (useful for dense cadence tracks). */
+  callout?: boolean;
+  /** Dot treatment. Defaults to `filled`. */
+  marker?: 'filled' | 'hollow' | 'diamond';
+}
+
+/** A horizontal timeline lane with zero or more positioned events. */
+export interface TimelineTemplateTrack {
+  id: string;
+  /** Optional label displayed to the left of the track. */
+  label?: string;
+  /** Optional label displayed after the track's terminal arrow. */
+  endLabel?: string;
+  events: TimelineTemplateEvent[];
+}
+
+/**
+ * A branch or relationship between two events. Source and target resolve
+ * against event ids globally, so links may cross tracks.
+ */
+export interface TimelineTemplateLink {
+  source: string;
+  target: string;
+  /** Optional text displayed near the branch path. */
+  label?: string;
+}
+
+/**
+ * Timeline block - renders one or more horizontal tracks with event dots,
+ * text callouts, and optional branches between events.
+ */
+export interface TimelineBlockInput extends BaseTemplateBlock {
+  template: 'timeline';
+  /** Tracks and their events (usually supplied through `templateData`). */
+  tracks?: TimelineTemplateTrack[];
+  /** Optional branch/cross-track links between event ids. */
+  links?: TimelineTemplateLink[];
+  /** Optional title above the timeline. */
+  title?: string;
+  /** Color scheme for tracks, markers, and branch links. */
+  colorScheme?: ColorScheme;
+}
+
 /**
  * Photo grid - 2-4 images in a tiled layout.
  * Used when multiple images are available for visual variety.
@@ -477,13 +576,57 @@ export interface VideoPullQuoteInput extends BaseTemplateBlock {
 }
 
 /**
- * Diagram block - renders child headings as a node-and-edge diagram.
+ * One diagram node supplied via `templateData.nodes` (canvas units, the
+ * same coordinate space as `Block.x`/`Block.y`). This is the data-driven
+ * alternative to child headings — used when a diagram is derived from an
+ * ASCII-art fence.
+ */
+export interface DiagramTemplateNode {
+  id: string;
+  /** Display label; may contain `\n` for multi-line labels. */
+  label: string;
+  x: number;
+  y: number;
+  /** Per-node width override in canvas units (defaults to the standard card width). */
+  w?: number;
+  /** Per-node height override in canvas units. */
+  h?: number;
+  /** Id of the node visually containing this one; containers draw behind their children. */
+  container?: string;
+}
+
+/** A position along one side of a diagram node, normalized from 0 to 1. */
+export interface DiagramEdgeAnchor {
+  side: 'top' | 'right' | 'bottom' | 'left';
+  /** Left→right on horizontal sides; top→bottom on vertical sides. */
+  offset: number;
+}
+
+/** An edge for `DiagramTemplateNode` lists. `directed` defaults to true. */
+export interface DiagramTemplateEdge {
+  source: string;
+  target: string;
+  /** Edge label rendered at the midpoint. */
+  label?: string;
+  /** False suppresses the end arrowhead (a plain connecting line). */
+  directed?: boolean;
+  /** Optional authored attachment on the source node. */
+  sourceAnchor?: DiagramEdgeAnchor;
+  /** Optional authored attachment on the target node. */
+  targetAnchor?: DiagramEdgeAnchor;
+  /** Per-edge path routing; ASCII-derived edges use orthogonal routing. */
+  routing?: 'straight' | 'orthogonal' | 'curved';
+}
+
+/**
+ * Diagram block - renders a node-and-edge diagram.
  *
- * Unlike other templates, the diagram template reads its content from
- * the parent block's `children` (passed via `context.children`) — each
- * child heading becomes a node, positioned by its `x`/`y` and connected
- * by its `connectsTo`. Per-diagram options on this input control overall
- * appearance; per-node data lives on the child blocks themselves.
+ * Two data sources, in precedence order:
+ * 1. Child headings (`context.children`) — each child is a node positioned
+ *    by its `x`/`y` and connected by its `connectsTo` (legacy authored form).
+ * 2. `nodes`/`edges` on this input (usually via `templateData`, derived
+ *    from an ASCII-art diagram fence in the block body).
+ * Per-diagram options on this input control overall appearance.
  */
 export interface DiagramBlockInput extends BaseTemplateBlock {
   template: 'diagram';
@@ -501,6 +644,10 @@ export interface DiagramBlockInput extends BaseTemplateBlock {
   endStyle?: MarkerStyle;
   /** Edge line style (default: 'solid'). */
   lineStyle?: 'solid' | 'dashed' | 'dotted';
+  /** Data-driven node list; used only when the block has no children. */
+  nodes?: DiagramTemplateNode[];
+  /** Edges for `nodes`. */
+  edges?: DiagramTemplateEdge[];
 }
 
 /**
@@ -591,6 +738,8 @@ export type TemplateBlock =
   | VideoPullQuoteInput
   | DataTableInput
   | DiagramBlockInput
+  | TreeBlockInput
+  | TimelineBlockInput
   | DrawingBlockInput
   | RawLayersInput;
 
@@ -630,7 +779,7 @@ export interface TemplateContext {
   /** Layout hints for this orientation */
   layout: LayoutHints;
   /**
-   * The block's direct children (set by `getLayers` when the block has
+   * The block's direct children (set by `materializeBlockLayers` when the block has
    * `children`). Most templates ignore this; aggregate templates like
    * `diagram` consume it to render each child as part of their output.
    */

package/src/schemas/Doc.ts

@@ -215,11 +215,23 @@ export interface Block {
   /** Which audio segment this block belongs to (0-indexed) */
   audioSegment: number;
 
+  /**
+   * Transform provenance: the source block id this block was derived
+   * from (see `BaseTemplateBlock.sourceBlockId`). Present on blocks a
+   * transform produced; lets a persisted transformed Doc keep its typed
+   * link back to the source content.
+   */
+  sourceBlockId?: string;
+  /** All source block ids when this block summarizes several. */
+  sourceBlockIds?: string[];
+  /** Char offset of the extraction inside the source block's plain text. */
+  sourceCharOffset?: number;
+
   /**
    * Pre-computed visual layers, rendered back-to-front.
    *
    * Optional — template-derived blocks typically omit this and compute
-   * layers on demand via `getLayers()` from `@bendyline/squisq/doc`.
+   * layers on demand via `materializeBlockLayers()` from `@bendyline/squisq/doc`.
    * Raw blocks (e.g., hand-crafted by AI) may provide layers directly.
    */
   layers?: Layer[];
@@ -368,7 +380,8 @@ export type Layer =
   | PathLayer
   | MapLayer
   | VideoLayer
-  | TableLayer;
+  | TableLayer
+  | TreeLayer;
 
 interface BaseLayer {
   /** Unique identifier for this layer */
@@ -573,14 +586,9 @@ export interface PathLayer extends BaseLayer {
     borderStyle?: BorderStyle;
     /** Optional stroke dash pattern (SVG `stroke-dasharray` syntax). */
     dasharray?: string;
-    /**
-     * Legacy arrowhead flag. Prefer `startMarker`/`endMarker`. When those are
-     * unset, `'end'`/`'start'`/`'both'` render a filled-triangle arrowhead.
-     */
-    arrow?: 'none' | 'end' | 'start' | 'both';
-    /** Marker at the path start (overrides `arrow`). Default: derived from `arrow`. */
+    /** Marker at the path start. */
     startMarker?: MarkerStyle;
-    /** Marker at the path end (overrides `arrow`). Default: derived from `arrow`. */
+    /** Marker at the path end. */
     endMarker?: MarkerStyle;
   };
 }
@@ -696,6 +704,61 @@ export interface TableLayerStyle {
   borderRadius?: number;
 }
 
+/**
+ * One node in a `TreeLayer` — a JSON-serializable hierarchy item (mirrors
+ * the treeview codec's `TreeItem`). Rendered as an indented filesystem-style
+ * row with a folder/file icon and connector rails.
+ */
+export interface TreeLayerItem {
+  id: string;
+  label: string;
+  /** True renders a folder (container) icon; else a file (leaf) icon. */
+  isDir?: boolean;
+  /** Trailing comment shown muted after the label. */
+  comment?: string;
+  children: TreeLayerItem[];
+}
+
+/**
+ * A hierarchical treeview rendered as interactive HTML inside a
+ * `<foreignObject>` (like `TableLayer`): folder/file icons, connector
+ * rails, and collapse chevrons. Interactive (collapse/expand) in the live
+ * React player; captured fully-expanded and static in frame/PDF export.
+ */
+export interface TreeLayer extends BaseLayer {
+  type: 'tree';
+  content: {
+    items: TreeLayerItem[];
+    style: TreeLayerStyle;
+  };
+}
+
+/** Styling options for a TreeLayer. */
+export interface TreeLayerStyle {
+  /** Leaf (file) row text color. */
+  rowColor: string;
+  /** Container (folder) row text color. */
+  dirColor: string;
+  /** Connector rail / branch color. */
+  connectorColor: string;
+  /** Icon color. */
+  iconColor: string;
+  /** Muted comment color. */
+  commentColor: string;
+  /** Font size in pixels. */
+  fontSize: number;
+  /** Row label font family. */
+  fontFamily?: string;
+  /** Monospace font for the connector rails. */
+  monoFontFamily?: string;
+  /** Indent step per depth level, in pixels. */
+  indentPx: number;
+  /** FontAwesome icon token for containers (default `folder`). */
+  folderIcon?: string;
+  /** FontAwesome icon token for leaves (default `file`). */
+  fileIcon?: string;
+}
+
 /**
  * Available map tile styles from free/open-source providers.
  */

package/src/schemas/Media.ts

@@ -1,8 +1,9 @@
 /**
  * Media-clip timing model.
  *
- * An additive layer on top of the legacy sequential `Doc.audio.segments[]`
- * narration track. A {@link MediaClip} is a piece of audio or video whose
+ * An additive layer on top of the simple sequential `Doc.audio.segments[]`
+ * narration track, which remains first-class. A {@link MediaClip} is a piece
+ * of audio or video whose
  * timing is expressed *relative to its parent block* (or the whole document),
  * with an optional `startAt` offset and an optional `spillover` past the
  * block's end. {@link resolveMediaSchedule} flattens these into absolute,
@@ -51,6 +52,15 @@ export interface MediaClip {
    * `startAt`) back to the exact line. Absent for programmatically built clips.
    */
   sourceLine?: number;
+  /**
+   * Round-trip home of the authoring annotation: the block whose contents
+   * held the paragraph, its position in that block's ORIGINAL contents
+   * array (before extraction), and the paragraph's exact source text.
+   * `docToMarkdown` re-inserts the annotation from this — `raw` verbatim
+   * when present, a re-serialized annotation otherwise. Absent for
+   * programmatically built clips (those emit at the document top).
+   */
+  origin?: { blockId: string; index: number; raw?: string };
 }
 
 /**

package/src/schemas/Theme.ts

@@ -23,13 +23,15 @@
 import type { LayoutHints } from './LayoutStrategy.js';
 import type { AnimationType, ImageTreatment, TransitionType } from './Doc.js';
 import type { PersistentLayerConfig } from './BlockTemplates.js';
+import { THEME_SCHEMA_VERSION } from './themeConstants.js';
+import { validateTheme } from './themeValidator.js';
+import { cloneAndFreezeData } from '../internal/immutable.js';
 
 // ============================================
 // Schema version
 // ============================================
 
-/** Current Theme schema version. Bump on breaking changes; loader migrates. */
-export const THEME_SCHEMA_VERSION = '1' as const;
+export { THEME_SCHEMA_VERSION } from './themeConstants.js';
 export type ThemeSchemaVersion = typeof THEME_SCHEMA_VERSION;
 
 /**
@@ -354,33 +356,51 @@ export function applySurface(theme: Theme, surface: SurfaceScheme): Theme {
 }
 
 // ============================================
-// Runtime registry — for custom themes
+// Caller-owned 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);
+/** A caller-owned custom-theme registry for SSR tenants, tests, and embedders. */
+export interface ThemeRegistry {
+  register(theme: Theme): void;
+  unregister(id: string): boolean;
+  get(id: string): Theme | undefined;
+  list(): 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());
+function validatedThemeSnapshot(theme: Theme): Theme {
+  const result = validateTheme(theme);
+  if (!result.valid || !result.theme) {
+    const details = result.errors
+      .slice(0, 5)
+      .map((error) => `${error.path || '<root>'}: ${error.message}`)
+      .join('; ');
+    throw new TypeError(`Cannot register invalid theme: ${details}`);
+  }
+  return cloneAndFreezeData(result.theme);
 }
 
-/** @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);
+/**
+ * Create a registry whose state is owned by the caller rather than the
+ * process. Registered values are validated and stored as deeply frozen
+ * snapshots, so later caller mutation cannot alter resolution behavior.
+ */
+export function createThemeRegistry(initialThemes: readonly Theme[] = []): ThemeRegistry {
+  const themes = new Map<string, Theme>();
+  const registry: ThemeRegistry = {
+    register(theme): void {
+      const snapshot = validatedThemeSnapshot(theme);
+      themes.set(snapshot.id, snapshot);
+    },
+    unregister(id): boolean {
+      return themes.delete(id);
+    },
+    get(id): Theme | undefined {
+      return themes.get(id);
+    },
+    list(): Theme[] {
+      return Array.from(themes.values());
+    },
+  };
+  for (const theme of initialThemes) registry.register(theme);
+  return Object.freeze(registry);
 }

package/src/schemas/Viewport.ts

@@ -8,7 +8,7 @@
  * - landscape (16:9) - Default, standard video/presentation format
  * - portrait (9:16) - Vertical video, mobile stories
  * - square (1:1) - Social media posts
- * - standard (4:3) - Legacy presentation format
+ * - standard (4:3) - Classic presentation format
  */
 
 /**
@@ -33,7 +33,7 @@ export const VIEWPORT_PRESETS = {
   portrait: { width: 1080, height: 1920, name: '9:16 Portrait' },
   /** 1:1 square (social media) */
   square: { width: 1080, height: 1080, name: '1:1 Square' },
-  /** 4:3 standard (legacy) */
+  /** 4:3 standard */
   standard: { width: 1440, height: 1080, name: '4:3 Standard' },
 } as const;
 

package/src/schemas/fontStacks.ts

@@ -258,3 +258,82 @@ export function buildGoogleFontsUrl(families: Array<FontFamily | undefined>): st
 
 /** Default fallback families exposed for tools that need them. */
 export const FONT_FALLBACKS = FALLBACK_BY_KIND;
+
+// ── Arbitrary font-name matching ─────────────────────────────────────
+//
+// Used by file-import theme inference (OOXML fontScheme → FontFamily):
+// a typeface name from an office document either matches a curated stack
+// or becomes a `{ custom }` reference that preserves the original face.
+
+/** Normalize a raw typeface name for lookup: trim, unquote, lowercase, collapse whitespace. */
+function normalizeFontName(name: string): string {
+  return name
+    .trim()
+    .replace(/^["']+|["']+$/g, '')
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+}
+
+/**
+ * Normalized name → stackId. Seeded from every stack's label and Google
+ * Fonts family name, plus explicit aliases for common variants and the
+ * web-safe faces that already anchor the system stacks' CSS families.
+ */
+const STACK_NAME_ALIASES: Record<string, string> = (() => {
+  const aliases: Record<string, string> = {};
+  for (const stack of AVAILABLE_FONT_STACKS) {
+    aliases[normalizeFontName(stack.label)] = stack.id;
+    if (stack.googleFontFamily) aliases[normalizeFontName(stack.googleFontFamily)] = stack.id;
+  }
+  Object.assign(aliases, {
+    playfair: 'playfair',
+    'source serif': 'source-serif',
+    'source serif pro': 'source-serif',
+    'crimson pro': 'crimson',
+    cormorant: 'cormorant',
+    georgia: 'system-serif',
+    'times new roman': 'system-serif',
+    times: 'system-serif',
+    consolas: 'system-mono',
+    'courier new': 'system-mono',
+    courier: 'system-mono',
+    'segoe ui': 'system-sans',
+    'system-ui': 'system-sans',
+  });
+  return aliases;
+})();
+
+const MONO_NAME_RE =
+  /\b(mono|monospace|consolas|courier|menlo|inconsolata|cascadia|fira code|source code|code)\b/;
+const SERIF_NAME_RE =
+  /\b(georgia|times|garamond|cambria|caslon|baskerville|bodoni|didot|palatino|book antiqua|goudy|minion|charter|constantia|century schoolbook|antiqua|roman)\b/;
+
+/**
+ * Guess the structured fallback bucket for an arbitrary typeface name.
+ * Deliberately never guesses `system-ui` — a wrong serif/sans guess is
+ * recoverable in the customizer; `system-ui` erases the signal entirely.
+ */
+export function guessFontFallback(
+  name: string,
+): 'serif' | 'sans-serif' | 'monospace' | 'system-ui' {
+  const n = normalizeFontName(name);
+  if (MONO_NAME_RE.test(n)) return 'monospace';
+  if ((n.includes('serif') && !n.includes('sans')) || SERIF_NAME_RE.test(n)) return 'serif';
+  return 'sans-serif';
+}
+
+/**
+ * Map an arbitrary typeface name (e.g. from an imported office document's
+ * fontScheme) to a `FontFamily`: a curated `{ stackId }` when the name
+ * matches a known stack, else `{ custom }` preserving the original name
+ * (original casing, quotes stripped) with a heuristic fallback bucket.
+ * Empty/blank names resolve to the system sans stack.
+ */
+export function matchFontFamily(name: string): FontFamily {
+  const normalized = normalizeFontName(name);
+  if (!normalized) return { stackId: 'system-sans' };
+  const stackId = STACK_NAME_ALIASES[normalized];
+  if (stackId) return { stackId };
+  const displayName = name.trim().replace(/^["']+|["']+$/g, '');
+  return { custom: { name: displayName, fallback: guessFontFallback(name) } };
+}

package/src/schemas/themeCompile.ts

@@ -28,6 +28,8 @@ import {
   oklchSetChroma,
   pickContrastingText,
   relativeLuminance,
+  deriveScale,
+  isHex,
 } from './colorUtils.js';
 
 /** Internal default theme used to fill in fields the customizer doesn't expose. */
@@ -134,6 +136,19 @@ export function deriveColorPalette(
   };
 }
 
+/**
+ * Expand one accent color into a full `{bg, text, accent}` color scheme via
+ * the OKLCh scale — dark saturated bg, light readable text, the picked accent.
+ * Falls back to a neutral scheme when the input isn't a valid hex. Shared by
+ * the editor's accent list and file-import theme inference so both derive
+ * identical schemes from the same accent.
+ */
+export function accentToColorScheme(accent: string): ThemeColorScheme {
+  if (!isHex(accent)) return { bg: '#1a202c', text: '#e2e8f0', accent: '#63b3ed' };
+  const scale = deriveScale(accent, 0.3);
+  return { bg: scale.darker2, text: scale.lighter2, accent: scale.base };
+}
+
 /** Map a contrast preset to numeric spread used by `deriveColorPalette`. */
 export type ContrastPreset = 'subtle' | 'balanced' | 'high';
 

package/src/schemas/themeConstants.ts

@@ -0,0 +1,2 @@
+/** Current Theme schema version. Bump on breaking changes; loader migrates. */
+export const THEME_SCHEMA_VERSION = '1' as const;

package/src/schemas/themeLibrary.ts

@@ -9,17 +9,21 @@
  * ```ts
  * import { THEMES, resolveTheme } from '@bendyline/squisq/schemas';
  *
- * const theme = resolveTheme('minimalist'); // by id, with registry override
+ * const theme = resolveTheme('minimalist'); // built-in lookup by id
  * const theme = THEMES.documentary;         // direct access to a built-in
  * ```
  */
 
-import type { Theme } from './Theme.js';
-import { lookupRegisteredTheme } from './Theme.js';
+import type { Theme, ThemeRegistry } from './Theme.js';
 import { BUILTIN_THEMES } from './themes/index.js';
+import { cloneAndFreezeData } from '../internal/immutable.js';
 
 /** All built-in themes, keyed by id. */
-export const THEMES: Record<string, Theme> = BUILTIN_THEMES;
+export const THEMES: Readonly<Record<string, Theme>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(BUILTIN_THEMES).map(([id, theme]) => [id, cloneAndFreezeData(theme)]),
+  ),
+);
 
 /** The default theme id. */
 export const DEFAULT_THEME_ID = 'standard';
@@ -28,27 +32,29 @@ export const DEFAULT_THEME_ID = 'standard';
 export const DEFAULT_THEME: Theme = THEMES[DEFAULT_THEME_ID];
 
 /**
- * Resolve a theme by id. Custom themes registered via `registerTheme()`
- * take precedence over built-ins; otherwise built-ins are searched and
- * the default theme is returned for unknown ids.
+ * Resolve a theme by id. When a caller-owned registry is supplied its themes
+ * take precedence over built-ins; unknown ids fall back to the default.
  */
-export function resolveTheme(id: string | undefined): Theme {
-  const registered = lookupRegisteredTheme(id);
+export function resolveTheme(id: string | undefined, registry?: ThemeRegistry): Theme {
+  const registered = id ? registry?.get(id) : undefined;
   if (registered) return registered;
   if (id && id in THEMES) return THEMES[id];
   return DEFAULT_THEME;
 }
 
-/** Get all built-in theme ids. */
-export function getAvailableThemes(): string[] {
-  return Object.keys(THEMES);
+/** Get built-in ids plus ids from an optional caller-owned registry. */
+export function getAvailableThemes(registry?: ThemeRegistry): string[] {
+  return Array.from(
+    new Set([...Object.keys(THEMES), ...(registry?.list().map((theme) => theme.id) ?? [])]),
+  );
 }
 
-/** Get a summary of all built-in themes (id + name + description) for theme pickers. */
-export function getThemeSummaries(): Array<{ id: string; name: string; description?: string }> {
-  return Object.values(THEMES).map((t) => ({
-    id: t.id,
-    name: t.name,
-    description: t.description,
-  }));
+/** Get summaries for built-ins plus an optional caller-owned registry. */
+export function getThemeSummaries(
+  registry?: ThemeRegistry,
+): Array<{ id: string; name: string; description?: string }> {
+  return getAvailableThemes(registry).map((id) => {
+    const theme = resolveTheme(id, registry);
+    return { id, name: theme.name, description: theme.description };
+  });
 }

package/src/schemas/themeValidator.ts

@@ -11,7 +11,7 @@
  */
 
 import type { Theme, ThemeColorPalette } from './Theme.js';
-import { THEME_SCHEMA_VERSION } from './Theme.js';
+import { THEME_SCHEMA_VERSION } from './themeConstants.js';
 import { isHex } from './colorUtils.js';
 import { isTransitionType } from './Transitions.js';
 

package/src/schemas/themes/gezellig.json

@@ -2,7 +2,7 @@
   "schemaVersion": "1",
   "id": "gezellig",
   "name": "Gezellig",
-  "description": "Warm sage + terracotta palette inspired by the Gezel desktop app. Subtle orange-tinted dark background, cream text, sage and terracotta accents.",
+  "description": "Cozy, warm-hued palette with a subtle orange-tinted dark background, cream text, and sage and terracotta accents.",
   "colors": {
     "primary": "#b0724c",
     "secondary": "#667f62",