@bendyline/squisq 0.1.1

package/src/schemas/LayoutStrategy.ts

@@ -0,0 +1,178 @@
+/**
+ * Layout Strategy
+ *
+ * Provides orientation-specific layout hints for slide templates.
+ * Templates use these hints to position content appropriately for
+ * different aspect ratios (landscape, portrait, square).
+ *
+ * Key adaptations by orientation:
+ * - Portrait: Larger relative text, stacked layouts instead of side-by-side
+ * - Square: Balanced layout with moderate adjustments
+ * - Landscape: Default/reference layout
+ */
+
+import type { ViewportOrientation, ViewportConfig } from './Viewport.js';
+import { calculateFontScale } from './Viewport.js';
+
+/**
+ * Layout hints for template positioning based on orientation.
+ */
+export interface LayoutHints {
+  /** Primary content Y position (percentage string, e.g., "35%") */
+  primaryY: string;
+  /** Secondary content Y position (percentage string) */
+  secondaryY: string;
+  /** Tertiary/detail Y position (percentage string) */
+  tertiaryY: string;
+  /** Title font size multiplier (relative to base) */
+  titleScale: number;
+  /** Body text font size multiplier (relative to base) */
+  bodyScale: number;
+  /** Two-column: left X position (percentage string) */
+  columnLeftX: string;
+  /** Two-column: right X position (percentage string) */
+  columnRightX: string;
+  /** Two-column in portrait: top Y position for stacked layout */
+  columnTopY: string;
+  /** Two-column in portrait: bottom Y position for stacked layout */
+  columnBottomY: string;
+  /** Whether two-column should stack vertically */
+  stackColumns: boolean;
+  /** Max text width (percentage string) for wrapping */
+  maxTextWidth: string;
+  /** Horizontal padding from edges (percentage string) */
+  horizontalPadding: string;
+  /** Caption position Y for imageWithCaption (percentage string) */
+  captionY: string;
+  /** Caption font size multiplier */
+  captionScale: number;
+}
+
+/**
+ * Layout configurations by orientation.
+ */
+const LAYOUT_CONFIGS: Record<ViewportOrientation, LayoutHints> = {
+  landscape: {
+    primaryY: '35%',
+    secondaryY: '55%',
+    tertiaryY: '75%',
+    titleScale: 1.0,
+    bodyScale: 1.0,
+    columnLeftX: '25%',
+    columnRightX: '75%',
+    columnTopY: '35%',
+    columnBottomY: '65%',
+    stackColumns: false,
+    maxTextWidth: '80%',
+    horizontalPadding: '10%',
+    captionY: '85%',
+    captionScale: 1.0,
+  },
+  portrait: {
+    // Content positioned higher for thumb-reach zone on mobile
+    primaryY: '25%',
+    secondaryY: '42%',
+    tertiaryY: '58%',
+    // Titles scale down for narrower width; body text scales up to fill vertical space
+    titleScale: 0.7,
+    bodyScale: 1.5,
+    // Stacked columns instead of side-by-side
+    columnLeftX: '50%',
+    columnRightX: '50%',
+    columnTopY: '30%',
+    columnBottomY: '55%',
+    stackColumns: true,
+    // Wider relative to viewport to use available space
+    maxTextWidth: '90%',
+    horizontalPadding: '5%',
+    captionY: '75%',
+    captionScale: 0.85,
+  },
+  square: {
+    primaryY: '30%',
+    secondaryY: '50%',
+    tertiaryY: '70%',
+    titleScale: 0.85,
+    bodyScale: 0.9,
+    columnLeftX: '25%',
+    columnRightX: '75%',
+    columnTopY: '35%',
+    columnBottomY: '65%',
+    stackColumns: false,
+    maxTextWidth: '85%',
+    horizontalPadding: '7.5%',
+    captionY: '82%',
+    captionScale: 0.9,
+  },
+};
+
+/**
+ * Get layout hints for a given orientation.
+ */
+export function getLayoutHints(orientation: ViewportOrientation): LayoutHints {
+  return LAYOUT_CONFIGS[orientation];
+}
+
+/**
+ * Calculate a scaled font size based on viewport and layout hints.
+ *
+ * @param basePx - Base font size in pixels (designed for 1920x1080)
+ * @param viewport - Target viewport configuration
+ * @param orientation - Viewport orientation
+ * @param isTitle - Whether this is title text (uses titleScale) or body (uses bodyScale)
+ */
+export function scaledFontSize(
+  basePx: number,
+  viewport: ViewportConfig,
+  orientation: ViewportOrientation,
+  isTitle: boolean = false,
+): number {
+  const fontScale = calculateFontScale(viewport);
+  const layout = getLayoutHints(orientation);
+  const typeScale = isTitle ? layout.titleScale : layout.bodyScale;
+  return Math.round(basePx * fontScale * typeScale);
+}
+
+/**
+ * Get position for two-column layout based on orientation.
+ * Returns { left: {x, y}, right: {x, y} } positions.
+ */
+export function getTwoColumnPositions(orientation: ViewportOrientation): {
+  left: { x: string; y: string };
+  right: { x: string; y: string };
+} {
+  const layout = getLayoutHints(orientation);
+
+  if (layout.stackColumns) {
+    // Portrait: stack vertically
+    return {
+      left: { x: '50%', y: layout.columnTopY },
+      right: { x: '50%', y: layout.columnBottomY },
+    };
+  }
+
+  // Landscape/square: side by side
+  return {
+    left: { x: layout.columnLeftX, y: '50%' },
+    right: { x: layout.columnRightX, y: '50%' },
+  };
+}
+
+/**
+ * Get safe text bounds for a given orientation.
+ * Returns margins to keep text away from edges.
+ */
+export function getSafeTextBounds(orientation: ViewportOrientation): {
+  left: string;
+  right: string;
+  top: string;
+  bottom: string;
+} {
+  const layout = getLayoutHints(orientation);
+  return {
+    left: layout.horizontalPadding,
+    right: layout.horizontalPadding,
+    top: '10%',
+    bottom: '10%',
+  };
+}

package/src/schemas/MediaProvider.ts

@@ -0,0 +1,70 @@
+/**
+ * MediaProvider — abstract interface for resolving and managing media assets.
+ *
+ * Components (ImageLayer, VideoLayer, editor preview) use a MediaProvider to
+ * resolve relative media paths to displayable URLs and to manage media storage.
+ *
+ * This decouples the rendering layer from the storage backend:
+ * - In the dev site, a SlotStorage-backed provider serves blob URLs from IndexedDB
+ * - In production, a simple basePath provider constructs CDN URLs
+ * - In tests, a memory-backed provider returns data URIs
+ */
+
+/**
+ * Metadata about a stored media asset.
+ */
+export interface MediaEntry {
+  /** Filename (e.g., 'hero.jpg') */
+  name: string;
+  /** MIME type (e.g., 'image/jpeg') */
+  mimeType: string;
+  /** File size in bytes */
+  size: number;
+}
+
+/**
+ * Interface for resolving and managing media assets.
+ *
+ * All methods are async to support IndexedDB and other async storage backends.
+ * The `resolveUrl` method is the primary integration point for rendering
+ * components — it converts a relative media path into a displayable URL.
+ */
+export interface MediaProvider {
+  /**
+   * Resolve a relative media path to a displayable URL.
+   *
+   * Returns a URL that can be used in <img src>, <video src>, etc.
+   * This may be a blob: URL, data: URL, or absolute HTTP URL depending
+   * on the provider implementation.
+   *
+   * @param relativePath - Relative path as stored in the document (e.g., 'hero.jpg')
+   * @returns Displayable URL, or the original path if resolution fails
+   */
+  resolveUrl(relativePath: string): Promise<string>;
+
+  /**
+   * List all media assets available in this provider's scope.
+   */
+  listMedia(): Promise<MediaEntry[]>;
+
+  /**
+   * Add a media asset. Returns the relative path to reference in documents.
+   *
+   * @param name - Filename for the asset (e.g., 'photo.jpg')
+   * @param data - Binary content (ArrayBuffer, Blob, or Uint8Array)
+   * @param mimeType - MIME type of the data
+   * @returns The relative path to use in document references
+   */
+  addMedia(name: string, data: ArrayBuffer | Blob | Uint8Array, mimeType: string): Promise<string>;
+
+  /**
+   * Remove a media asset by its relative path.
+   */
+  removeMedia(relativePath: string): Promise<void>;
+
+  /**
+   * Dispose of any held resources (e.g., revoke blob URLs).
+   * Call this when the provider is no longer needed.
+   */
+  dispose(): void;
+}

package/src/schemas/Theme.ts

@@ -0,0 +1,235 @@
+/**
+ * Theme System
+ *
+ * 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)`.
+ *
+ * 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.
+ */
+
+import type { LayoutHints } from './LayoutStrategy.js';
+import type { AnimationType, TransitionType } from './Doc.js';
+import type { PersistentLayerConfig } from './BlockTemplates.js';
+
+// ============================================
+// Color Palette
+// ============================================
+
+/**
+ * Core color palette for a theme. Every color is a CSS color 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;
+}
+
+// ============================================
+// Typography
+// ============================================
+
+/**
+ * Typography settings for a theme.
+ */
+export interface ThemeTypography {
+  /** Font family for body / description text */
+  bodyFontFamily: string;
+  /** Font family for titles and headings */
+  titleFontFamily: string;
+  /** Font family for code / monospaced text (optional) */
+  monoFontFamily?: string;
+  /** 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;
+}
+
+// ============================================
+// 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.
+   *
+   * @example
+   * ```
+   * { statHighlight: { entrance: 'dramatic' }, titleBlock: { showAccentLine: false } }
+   * ```
+   */
+  templateHints?: Record<string, Record<string, string | number | boolean>>;
+}
+
+// ============================================
+// Theme
+// ============================================
+
+/**
+ * A complete, JSON-serializable theme definition.
+ */
+export interface Theme {
+  /** Unique identifier (e.g. "documentary") */
+  id: string;
+  /** Human-readable display name */
+  name: string;
+  /** Short description for theme pickers */
+  description?: string;
+  /** 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".
+ *
+ * @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(
+    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`;
+  }
+  return merged;
+}

package/src/schemas/Types.ts

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

package/src/schemas/Viewport.ts

@@ -0,0 +1,91 @@
+/**
+ * Viewport Configuration
+ *
+ * Defines viewport dimensions for doc rendering across different aspect ratios.
+ * Templates use this configuration to adapt their layouts appropriately.
+ *
+ * Supported aspect ratios:
+ * - 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
+ */
+
+/**
+ * Viewport configuration for doc rendering.
+ */
+export interface ViewportConfig {
+  /** Canonical width in virtual pixels */
+  width: number;
+  /** Canonical height in virtual pixels */
+  height: number;
+  /** Human-readable name for debugging/display */
+  name: string;
+}
+
+/**
+ * Standard viewport presets for common aspect ratios.
+ */
+export const VIEWPORT_PRESETS = {
+  /** 16:9 landscape (default, 1080p) */
+  landscape: { width: 1920, height: 1080, name: '16:9 Landscape' },
+  /** 9:16 portrait (vertical video, stories) */
+  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) */
+  standard: { width: 1440, height: 1080, name: '4:3 Standard' },
+} as const;
+
+/**
+ * Viewport preset name.
+ */
+export type ViewportPreset = keyof typeof VIEWPORT_PRESETS;
+
+/**
+ * Viewport orientation derived from aspect ratio.
+ */
+export type ViewportOrientation = 'landscape' | 'portrait' | 'square';
+
+/**
+ * Get a viewport configuration from a preset name or return the config if already a ViewportConfig.
+ */
+export function getViewport(viewport: ViewportPreset | ViewportConfig): ViewportConfig {
+  if (typeof viewport === 'string') {
+    return VIEWPORT_PRESETS[viewport];
+  }
+  return viewport;
+}
+
+/**
+ * Calculate font scale factor for a viewport.
+ * Based on diagonal pixels relative to 1080p landscape reference.
+ * This ensures text remains readable across different viewport sizes.
+ */
+const REFERENCE_DIAGONAL = Math.sqrt(1920 * 1920 + 1080 * 1080); // ~2203
+
+export function calculateFontScale(viewport: ViewportConfig): number {
+  const currentDiagonal = Math.sqrt(
+    viewport.width * viewport.width + viewport.height * viewport.height,
+  );
+  return currentDiagonal / REFERENCE_DIAGONAL;
+}
+
+/**
+ * Determine if viewport is landscape, portrait, or square.
+ */
+export function getViewportOrientation(viewport: ViewportConfig): ViewportOrientation {
+  const ratio = viewport.width / viewport.height;
+  // Allow small tolerance for "square" classification
+  if (Math.abs(ratio - 1) < 0.05) return 'square';
+  return ratio > 1 ? 'landscape' : 'portrait';
+}
+
+/**
+ * Get aspect ratio as a string (e.g., "16:9", "9:16", "1:1").
+ */
+export function getAspectRatioString(viewport: ViewportConfig): string {
+  const gcd = (a: number, b: number): number => (b === 0 ? a : gcd(b, a % b));
+  const divisor = gcd(viewport.width, viewport.height);
+  return `${viewport.width / divisor}:${viewport.height / divisor}`;
+}

package/src/schemas/index.ts

@@ -0,0 +1,14 @@
+export * from './Types.js';
+export * from './Doc.js';
+export * from './BlockTemplates.js';
+export * from './Theme.js';
+export * from './themeLibrary.js';
+export * from './Viewport.js';
+export {
+  getLayoutHints,
+  getTwoColumnPositions,
+  getSafeTextBounds,
+  scaledFontSize as layoutScaledFontSize,
+} from './LayoutStrategy.js';
+export type { LayoutHints } from './LayoutStrategy.js';
+export type { MediaProvider, MediaEntry } from './MediaProvider.js';