@bendyline/squisq 2.0.1 → 2.2.0

package/src/schemas/Theme.ts

@@ -1,406 +0,0 @@
-/**
- * Theme System
- *
- * A Theme bundles color palette, typography, visual style, render-style
- * algorithm, and per-block color schemes into one JSON-serializable object.
- *
- * 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; 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, 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
-// ============================================
-
-export { THEME_SCHEMA_VERSION } from './themeConstants.js';
-export type ThemeSchemaVersion = typeof THEME_SCHEMA_VERSION;
-
-/**
- * Frontmatter key under which a document inlines its custom Theme
- * definitions. The theme analog of `FRONTMATTER_CUSTOM_TEMPLATES_KEY`
- * (custom block templates). See `doc/customThemesFrontmatter.ts` for the
- * codec and `doc/resolveDocTheme.ts` for doc-scoped resolution.
- */
-export const FRONTMATTER_CUSTOM_THEMES_KEY = 'squisq-custom-themes';
-
-// ============================================
-// Color Palette
-// ============================================
-
-/**
- * Core color palette for a theme. Every color is a `#rrggbb` hex string.
- */
-export interface ThemeColorPalette {
-  /** Primary accent color */
-  primary: string;
-  /** Secondary accent color */
-  secondary: string;
-  /** Background color (typically dark) */
-  background: string;
-  /** Lighter background for contrast panels */
-  backgroundLight: string;
-  /** Main text color */
-  text: string;
-  /** Muted/secondary text color */
-  textMuted: string;
-  /** Highlight/emphasis color */
-  highlight: string;
-  /** Warning/alert color */
-  warning: string;
-}
-
-/**
- * A named color scheme used by templates for per-block color variation
- * (e.g., statHighlight or sectionHeader).
- */
-export interface ThemeColorScheme {
-  /** Background fill */
-  bg: string;
-  /** Primary text tint */
-  text: string;
-  /** Accent / secondary tint */
-  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 */
-  bodyFont: FontFamily;
-  /** Font family for titles and headings */
-  titleFont: FontFamily;
-  /** Font family for code / monospaced text (optional) */
-  monoFont?: FontFamily;
-  /** Multiplier applied to LayoutHints.titleScale (default 1.0) */
-  titleScale?: number;
-  /** Multiplier applied to LayoutHints.bodyScale (default 1.0) */
-  bodyScale?: number;
-  /** Default body line height (default 1.4) */
-  lineHeight?: number;
-  /** Default title line height */
-  titleLineHeight?: number;
-  /** Default title font weight */
-  titleWeight?: 'normal' | 'bold';
-}
-
-// ============================================
-// Visual Style
-// ============================================
-
-/**
- * Global visual-style knobs that templates consult.
- */
-export interface ThemeStyle {
-  /** Default border radius for cards / shapes (px) */
-  borderRadius?: number;
-  /** Whether templates should default to text shadows */
-  textShadow?: boolean;
-  /** Darkness of overlay on image-backed blocks (0–1) */
-  overlayOpacity?: number;
-  /** Multiplier on all animation durations (1.0 = normal, <1 faster, >1 slower) */
-  animationSpeed?: number;
-  /** Default horizontal padding for text (percentage string, e.g. "5%") */
-  blockPadding?: string;
-  /**
-   * Photographic grade applied to template imagery (full-bleed photos,
-   * feature halves, accent strips) so photos look native to the theme.
-   * Duotone tints default to the theme primary. Blocks opt out per
-   * template via `imageTreatment: 'none'`.
-   */
-  imageTreatment?: ImageTreatment;
-}
-
-// ============================================
-// Render Style
-// ============================================
-
-/**
- * Render-style algorithm preset. Controls layout tweaks, default animations,
- * transitions, and per-template behavioral hints.
- */
-export interface RenderStyle {
-  /** Identifier for this algorithmic approach (e.g. "documentary", "magazine") */
-  name: string;
-  /** Partial overrides merged onto the orientation-based LayoutHints */
-  layoutOverrides?: Partial<LayoutHints>;
-  /** Default entrance animation for text layers */
-  defaultTextAnimation?: AnimationType;
-  /** Default animation for background / image layers */
-  defaultImageAnimation?: AnimationType;
-  /** Whether to apply Ken Burns ambient motion to images by default */
-  ambientMotion?: boolean;
-  /** Default block-to-block transition */
-  defaultTransition?: { type: TransitionType; duration?: number };
-  /**
-   * Per-template behavioral hints. Keys are template names, values are
-   * string/number/boolean maps that templates can read to vary their output.
-   * Templates that consume hints publish a `hintSchema` export documenting
-   * the keys they recognise.
-   */
-  templateHints?: Record<string, Record<string, string | number | boolean>>;
-}
-
-// ============================================
-// Theme
-// ============================================
-
-/**
- * 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;
-  /**
-   * Id of the theme this custom theme was derived from, if any. Recorded
-   * by `compileTheme({ base })` so a customizer can re-open the theme and
-   * re-inherit the base's render style / color schemes / typography.
-   * Absent on built-ins.
-   */
-  basedOn?: string;
-  /** Optional authoring seeds (customizer fills these; built-ins typically omit) */
-  seedColors?: ThemeSeedColors;
-  /** Color palette */
-  colors: ThemeColorPalette;
-  /** Typography settings */
-  typography: ThemeTypography;
-  /** Global visual-style knobs */
-  style: ThemeStyle;
-  /** Algorithmic render-style preset */
-  renderStyle: RenderStyle;
-  /**
-   * Named color schemes for per-block color variation.
-   * Templates reference these by name (e.g. "blue", "warm").
-   */
-  colorSchemes: Record<string, ThemeColorScheme>;
-  /** Optional persistent layers baked into the theme */
-  persistentLayers?: PersistentLayerConfig;
-}
-
-// ============================================
-// Deep-Partial helper type
-// ============================================
-
-/**
- * Recursively makes every property optional.
- */
-export type DeepPartial<T> = {
-  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-
-// ============================================
-// Helpers
-// ============================================
-
-/**
- * Deep-merge `source` into `target`, returning a new object.
- * Arrays are replaced wholesale (not concatenated).
- */
-function deepMerge<T extends Record<string, unknown>>(target: T, source: DeepPartial<T>): T {
-  const result = { ...target } as Record<string, unknown>;
-  for (const key of Object.keys(source)) {
-    const srcVal = (source as Record<string, unknown>)[key];
-    const tgtVal = (target as Record<string, unknown>)[key];
-    if (
-      srcVal !== null &&
-      srcVal !== undefined &&
-      typeof srcVal === 'object' &&
-      !Array.isArray(srcVal) &&
-      tgtVal !== null &&
-      tgtVal !== undefined &&
-      typeof tgtVal === 'object' &&
-      !Array.isArray(tgtVal)
-    ) {
-      result[key] = deepMerge(
-        tgtVal as Record<string, unknown>,
-        srcVal as DeepPartial<Record<string, unknown>>,
-      );
-    } else if (srcVal !== undefined) {
-      result[key] = srcVal;
-    }
-  }
-  return result as T;
-}
-
-/**
- * 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".
- */
-export function createTheme(base: Theme, overrides: DeepPartial<Theme>): Theme {
-  const merged = deepMerge(
-    base as unknown as Record<string, unknown>,
-    overrides as DeepPartial<Record<string, unknown>>,
-  ) as unknown as 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,
-    },
-  };
-}
-
-// ============================================
-// Caller-owned registry — for custom themes
-// ============================================
-
-/** 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[];
-}
-
-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);
-}
-
-/**
- * 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/Transitions.ts

@@ -1,224 +0,0 @@
-/**
- * Shared transition vocabulary for block-to-block slide changes.
- *
- * The canonical names are based on PowerPoint / PresentationML transition
- * names where possible, with a few legacy renderer aliases kept so older
- * Squisq documents continue to work.
- */
-
-export const DEFAULT_TRANSITION_DURATION_SECONDS = 0.7;
-
-export const TRANSITION_TYPES = [
-  // Existing / common transitions
-  'cut',
-  'fade',
-  'dissolve',
-  'push',
-  'wipe',
-  'split',
-  'reveal',
-  'randomBars',
-  'shape',
-  'uncover',
-  'cover',
-  'zoom',
-  'pan',
-
-  // PowerPoint subtle / exciting transitions
-  'flash',
-  'fallOver',
-  'drape',
-  'curtains',
-  'wind',
-  'prestige',
-  'fracture',
-  'crush',
-  'peelOff',
-  'pageCurl',
-  'airplane',
-  'origami',
-  'checkerboard',
-  'blinds',
-  'clock',
-  'ripple',
-  'honeycomb',
-  'glitter',
-  'vortex',
-  'shred',
-  'switch',
-  'flip',
-  'gallery',
-  'cube',
-  'doors',
-  'box',
-  'ferrisWheel',
-  'conveyor',
-  'rotate',
-  'window',
-  'orbit',
-  'flyThrough',
-  'morph',
-
-  // PresentationML/Open XML precise names and legacy aliases
-  'checker',
-  'circle',
-  'comb',
-  'diamond',
-  'newsflash',
-  'plus',
-  'pull',
-  'random',
-  'randomBar',
-  'strips',
-  'wedge',
-  'wheel',
-  'prism',
-  'warp',
-  'ferris',
-  'flythrough',
-  'wheelReverse',
-  'pageCurlDouble',
-  'pageCurlSingle',
-  'slideLeft',
-  'slideRight',
-  'slideUp',
-  'slideDown',
-] as const;
-
-export type TransitionType = (typeof TRANSITION_TYPES)[number];
-
-export const TRANSITION_DIRECTIONS = [
-  'left',
-  'right',
-  'up',
-  'down',
-  'in',
-  'out',
-  'horizontal',
-  'vertical',
-] as const;
-
-export type TransitionDirection = (typeof TRANSITION_DIRECTIONS)[number];
-
-/**
- * Transition between blocks.
- *
- * A block's transition is the lead-in from the previous block. The same
- * transition drives the entering block and the previous block's exit.
- */
-export interface Transition {
-  /** Transition type */
-  type: TransitionType;
-  /** Duration in seconds. Defaults to DEFAULT_TRANSITION_DURATION_SECONDS. */
-  duration?: number;
-  /** Optional direction/variant for directional transitions. */
-  direction?: TransitionDirection;
-}
-
-const TRANSITION_TYPE_SET = new Set<string>(TRANSITION_TYPES);
-
-const TRANSITION_TYPE_ALIASES: Record<string, TransitionType> = {
-  none: 'cut',
-  randombars: 'randomBars',
-  randombar: 'randomBar',
-  // Self-referential spellings (`checkerboard`, `shape`, `uncover`) are
-  // intentionally absent: an exact valid type returns early from
-  // `normalizeTransitionType`, and any case variant resolves through
-  // `NORMALIZED_TRANSITION_TYPES`. Only the *plural* aliases need an entry.
-  checkerboards: 'checkerboard',
-  shapes: 'shape',
-  ferris: 'ferrisWheel',
-  ferriswheel: 'ferrisWheel',
-  flythrough: 'flyThrough',
-  flythru: 'flyThrough',
-  pagecurl: 'pageCurl',
-  pagecurldouble: 'pageCurlDouble',
-  pagecurlsingle: 'pageCurlSingle',
-  wheelreverse: 'wheelReverse',
-  slideleft: 'slideLeft',
-  slideright: 'slideRight',
-  slideup: 'slideUp',
-  slidedown: 'slideDown',
-};
-
-const NORMALIZED_TRANSITION_TYPES = new Map<string, TransitionType>(
-  TRANSITION_TYPES.map((type) => [normalizeToken(type), type]),
-);
-
-export function isTransitionType(value: string): value is TransitionType {
-  return TRANSITION_TYPE_SET.has(value);
-}
-
-export function normalizeTransitionType(value: string): TransitionType | null {
-  const trimmed = value.trim();
-  if (!trimmed) return null;
-  if (isTransitionType(trimmed)) return trimmed;
-  const normalized = normalizeToken(trimmed);
-  return TRANSITION_TYPE_ALIASES[normalized] ?? NORMALIZED_TRANSITION_TYPES.get(normalized) ?? null;
-}
-
-export function normalizeTransitionDirection(value: string): TransitionDirection | null {
-  const normalized = normalizeToken(value);
-  switch (normalized) {
-    case 'left':
-    case 'l':
-      return 'left';
-    case 'right':
-    case 'r':
-      return 'right';
-    case 'up':
-    case 'u':
-      return 'up';
-    case 'down':
-    case 'd':
-      return 'down';
-    case 'in':
-      return 'in';
-    case 'out':
-      return 'out';
-    case 'horizontal':
-    case 'horz':
-    case 'h':
-      return 'horizontal';
-    case 'vertical':
-    case 'vert':
-    case 'v':
-      return 'vertical';
-    default:
-      return null;
-  }
-}
-
-export function resolveTransitionDuration(
-  transition: Transition | undefined,
-  fallback: number = DEFAULT_TRANSITION_DURATION_SECONDS,
-): number {
-  const duration = transition?.duration;
-  return duration != null && Number.isFinite(duration) && duration > 0 ? duration : fallback;
-}
-
-/**
- * Resolve the effective transition for a block: the authored value wins
- * (markdown frontmatter and transform styles both write `block.transition`
- * upstream), then the theme's `renderStyle.defaultTransition`, then
- * `undefined` (the player's built-in default).
- *
- * Block 0 never gets a theme default — an entrance transition on the first
- * block would dim the opening frames of every exported video.
- *
- * The theme parameter is structural (not `Theme`) to avoid a schema import
- * cycle; pass any resolved theme.
- */
-export function resolveBlockTransition(
-  block: { transition?: Transition },
-  theme: { renderStyle: { defaultTransition?: Transition } },
-  blockIndex: number,
-): Transition | undefined {
-  if (block.transition) return block.transition;
-  if (blockIndex === 0) return undefined;
-  return theme.renderStyle.defaultTransition;
-}
-
-function normalizeToken(value: string): string {
-  return value.toLowerCase().replace(/[\s_-]+/g, '');
-}

package/src/schemas/Types.ts

@@ -1,15 +0,0 @@
-/**
- * Core geographic types shared across squisq.
- */
-
-export interface Coordinates {
-  lat: number;
-  lng: number;
-}
-
-export interface BoundingBox {
-  north: number;
-  south: number;
-  east: number;
-  west: number;
-}