@bendyline/squisq 0.1.1

package/src/schemas/themeLibrary.ts

@@ -0,0 +1,492 @@
+/**
+ * Built-in Theme Library
+ *
+ * Ships 8 curated themes covering documentary, editorial, minimal, and
+ * cinematic styles. Each theme is fully JSON-serializable.
+ *
+ * Usage:
+ * ```ts
+ * import { THEMES, resolveTheme } from '@bendyline/squisq/schemas';
+ *
+ * const theme = resolveTheme('minimalist'); // look up by id
+ * const theme = THEMES.documentary;         // direct access
+ * ```
+ */
+
+import type { Theme, ThemeColorScheme } from './Theme.js';
+
+// ============================================
+// Shared constants
+// ============================================
+
+const SERIF = '"PT Serif", Georgia, "Times New Roman", serif';
+const SANS = '"Inter", "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif';
+const MONO = '"JetBrains Mono", "Fira Code", "Consolas", monospace';
+const MERRIWEATHER = '"Merriweather", Georgia, "Times New Roman", serif';
+const GEORGIA = 'Georgia, "Times New Roman", serif';
+
+/** Standard 6-scheme set used by the documentary theme (migrated from old COLOR_SCHEMES). */
+const CLASSIC_COLOR_SCHEMES: Record<string, ThemeColorScheme> = {
+  blue: { bg: '#1a365d', text: '#63b3ed', accent: '#90cdf4' },
+  green: { bg: '#22543d', text: '#9ae6b4', accent: '#68d391' },
+  purple: { bg: '#44337a', text: '#d6bcfa', accent: '#b794f4' },
+  red: { bg: '#742a2a', text: '#fc8181', accent: '#feb2b2' },
+  orange: { bg: '#744210', text: '#fbd38d', accent: '#f6ad55' },
+  teal: { bg: '#234e52', text: '#81e6d9', accent: '#4fd1c5' },
+};
+
+// ============================================
+// 1. Documentary (default — migrated from old DEFAULT_THEME)
+// ============================================
+
+const documentary: Theme = {
+  id: 'documentary',
+  name: 'Documentary',
+  description: 'Classic dark cinematic look with serif typography. The original Squisq style.',
+  colors: {
+    primary: '#3d5a80',
+    secondary: '#63b3ed',
+    background: '#1a202c',
+    backgroundLight: '#2d3748',
+    text: '#ffffff',
+    textMuted: '#a0aec0',
+    highlight: '#63b3ed',
+    warning: '#fc8181',
+  },
+  typography: {
+    bodyFontFamily: SERIF,
+    titleFontFamily: SERIF,
+    titleWeight: 'bold',
+  },
+  style: {
+    textShadow: true,
+    overlayOpacity: 0.5,
+    animationSpeed: 1.0,
+  },
+  renderStyle: {
+    name: 'documentary',
+    defaultTextAnimation: 'fadeIn',
+    defaultImageAnimation: 'slowZoom',
+    ambientMotion: true,
+    defaultTransition: { type: 'fade', duration: 0.8 },
+  },
+  colorSchemes: CLASSIC_COLOR_SCHEMES,
+  persistentLayers: {
+    bottomLayers: [
+      {
+        template: 'gradientBackground',
+        config: { type: 'gradientBackground', preset: 'dark-vignette' },
+      },
+    ],
+  },
+};
+
+// ============================================
+// 2. Minimalist
+// ============================================
+
+const minimalist: Theme = {
+  id: 'minimalist',
+  name: 'Minimalist',
+  description: 'Clean near-white background with sans-serif type and minimal animation.',
+  colors: {
+    primary: '#2d3748',
+    secondary: '#4a5568',
+    background: '#f7fafc',
+    backgroundLight: '#edf2f7',
+    text: '#1a202c',
+    textMuted: '#718096',
+    highlight: '#3182ce',
+    warning: '#e53e3e',
+  },
+  typography: {
+    bodyFontFamily: SANS,
+    titleFontFamily: SANS,
+    titleWeight: 'bold',
+    lineHeight: 1.6,
+  },
+  style: {
+    textShadow: false,
+    overlayOpacity: 0.3,
+    animationSpeed: 1.2,
+    borderRadius: 8,
+  },
+  renderStyle: {
+    name: 'minimalist',
+    defaultTextAnimation: 'fadeIn',
+    ambientMotion: false,
+    defaultTransition: { type: 'fade', duration: 0.6 },
+    templateHints: {
+      titleBlock: { showAccentLine: false },
+    },
+  },
+  colorSchemes: {
+    blue: { bg: '#ebf8ff', text: '#2b6cb0', accent: '#3182ce' },
+    green: { bg: '#f0fff4', text: '#276749', accent: '#38a169' },
+    purple: { bg: '#faf5ff', text: '#553c9a', accent: '#805ad5' },
+    red: { bg: '#fff5f5', text: '#c53030', accent: '#e53e3e' },
+    orange: { bg: '#fffaf0', text: '#c05621', accent: '#dd6b20' },
+    teal: { bg: '#e6fffa', text: '#285e61', accent: '#319795' },
+  },
+};
+
+// ============================================
+// 3. Bold
+// ============================================
+
+const bold: Theme = {
+  id: 'bold',
+  name: 'Bold',
+  description: 'High-contrast black with vivid accents and dramatic animations.',
+  colors: {
+    primary: '#e53e3e',
+    secondary: '#ed8936',
+    background: '#000000',
+    backgroundLight: '#1a1a1a',
+    text: '#ffffff',
+    textMuted: '#cbd5e0',
+    highlight: '#f6e05e',
+    warning: '#fc8181',
+  },
+  typography: {
+    bodyFontFamily: SANS,
+    titleFontFamily: SANS,
+    titleWeight: 'bold',
+    titleScale: 1.15,
+    bodyScale: 1.0,
+    titleLineHeight: 1.1,
+  },
+  style: {
+    textShadow: true,
+    overlayOpacity: 0.6,
+    animationSpeed: 0.8,
+  },
+  renderStyle: {
+    name: 'bold',
+    defaultTextAnimation: 'zoomIn',
+    defaultImageAnimation: 'slowZoom',
+    ambientMotion: true,
+    defaultTransition: { type: 'dissolve', duration: 0.5 },
+    templateHints: {
+      statHighlight: { entrance: 'dramatic' },
+      fullBleedQuote: { entrance: 'dramatic' },
+    },
+  },
+  colorSchemes: {
+    blue: { bg: '#1a202c', text: '#63b3ed', accent: '#90cdf4' },
+    green: { bg: '#1a202c', text: '#48bb78', accent: '#68d391' },
+    purple: { bg: '#1a202c', text: '#b794f4', accent: '#d6bcfa' },
+    red: { bg: '#1a202c', text: '#fc8181', accent: '#feb2b2' },
+    orange: { bg: '#1a202c', text: '#f6ad55', accent: '#fbd38d' },
+    teal: { bg: '#1a202c', text: '#4fd1c5', accent: '#81e6d9' },
+  },
+};
+
+// ============================================
+// 4. Morning Light
+// ============================================
+
+const morningLight: Theme = {
+  id: 'morning-light',
+  name: 'Morning Light',
+  description: 'Warm light background with dark text and gentle serif typography.',
+  colors: {
+    primary: '#744210',
+    secondary: '#975a16',
+    background: '#faf8f5',
+    backgroundLight: '#f5f0eb',
+    text: '#2d3748',
+    textMuted: '#718096',
+    highlight: '#dd6b20',
+    warning: '#c53030',
+  },
+  typography: {
+    bodyFontFamily: MERRIWEATHER,
+    titleFontFamily: MERRIWEATHER,
+    titleWeight: 'bold',
+    lineHeight: 1.7,
+  },
+  style: {
+    textShadow: false,
+    overlayOpacity: 0.35,
+    animationSpeed: 1.1,
+    borderRadius: 4,
+  },
+  renderStyle: {
+    name: 'morning-light',
+    defaultTextAnimation: 'fadeIn',
+    ambientMotion: false,
+    defaultTransition: { type: 'fade', duration: 1.0 },
+  },
+  colorSchemes: {
+    blue: { bg: '#ebf8ff', text: '#2c5282', accent: '#4299e1' },
+    green: { bg: '#f0fff4', text: '#22543d', accent: '#48bb78' },
+    purple: { bg: '#faf5ff', text: '#44337a', accent: '#9f7aea' },
+    red: { bg: '#fff5f5', text: '#9b2c2c', accent: '#fc8181' },
+    orange: { bg: '#fffaf0', text: '#744210', accent: '#ed8936' },
+    teal: { bg: '#e6fffa', text: '#234e52', accent: '#38b2ac' },
+  },
+};
+
+// ============================================
+// 5. Tech Dark
+// ============================================
+
+const techDark: Theme = {
+  id: 'tech-dark',
+  name: 'Tech Dark',
+  description: 'True black with neon cyan/green accents and monospace titles.',
+  colors: {
+    primary: '#00e5ff',
+    secondary: '#00e676',
+    background: '#0a0a0a',
+    backgroundLight: '#1a1a2e',
+    text: '#e0e0e0',
+    textMuted: '#9e9e9e',
+    highlight: '#00e5ff',
+    warning: '#ff5252',
+  },
+  typography: {
+    bodyFontFamily: SANS,
+    titleFontFamily: MONO,
+    monoFontFamily: MONO,
+    titleWeight: 'bold',
+    titleScale: 0.9,
+    lineHeight: 1.5,
+  },
+  style: {
+    textShadow: true,
+    overlayOpacity: 0.55,
+    animationSpeed: 0.9,
+    borderRadius: 2,
+  },
+  renderStyle: {
+    name: 'tech-dark',
+    defaultTextAnimation: 'typewriter',
+    defaultImageAnimation: 'slowZoom',
+    ambientMotion: true,
+    defaultTransition: { type: 'dissolve', duration: 0.4 },
+    templateHints: {
+      statHighlight: { entrance: 'dramatic' },
+    },
+  },
+  colorSchemes: {
+    blue: { bg: '#0d1b2a', text: '#00b0ff', accent: '#40c4ff' },
+    green: { bg: '#0d1b0d', text: '#00e676', accent: '#69f0ae' },
+    purple: { bg: '#1a0d2e', text: '#d500f9', accent: '#ea80fc' },
+    red: { bg: '#2e0d0d', text: '#ff5252', accent: '#ff8a80' },
+    orange: { bg: '#2e1a0d', text: '#ff9100', accent: '#ffab40' },
+    teal: { bg: '#0d2e2e', text: '#1de9b6', accent: '#64ffda' },
+  },
+};
+
+// ============================================
+// 6. Magazine
+// ============================================
+
+const magazine: Theme = {
+  id: 'magazine',
+  name: 'Magazine',
+  description: 'Rich editorial palette with mixed serif/sans typography and slide transitions.',
+  colors: {
+    primary: '#c53030',
+    secondary: '#2b6cb0',
+    background: '#1a202c',
+    backgroundLight: '#2d3748',
+    text: '#f7fafc',
+    textMuted: '#cbd5e0',
+    highlight: '#ed8936',
+    warning: '#fc8181',
+  },
+  typography: {
+    bodyFontFamily: SANS,
+    titleFontFamily: GEORGIA,
+    titleWeight: 'bold',
+    titleScale: 1.05,
+    lineHeight: 1.5,
+  },
+  style: {
+    textShadow: true,
+    overlayOpacity: 0.45,
+    animationSpeed: 1.0,
+    borderRadius: 6,
+  },
+  renderStyle: {
+    name: 'magazine',
+    defaultTextAnimation: 'fadeIn',
+    defaultImageAnimation: 'slowZoom',
+    ambientMotion: true,
+    defaultTransition: { type: 'slideLeft', duration: 0.7 },
+  },
+  colorSchemes: {
+    blue: { bg: '#1a365d', text: '#90cdf4', accent: '#63b3ed' },
+    green: { bg: '#1c4532', text: '#9ae6b4', accent: '#68d391' },
+    purple: { bg: '#322659', text: '#d6bcfa', accent: '#b794f4' },
+    red: { bg: '#63171b', text: '#feb2b2', accent: '#fc8181' },
+    orange: { bg: '#652b19', text: '#fbd38d', accent: '#f6ad55' },
+    teal: { bg: '#1d4044', text: '#81e6d9', accent: '#4fd1c5' },
+  },
+};
+
+// ============================================
+// 7. Cinematic
+// ============================================
+
+const cinematic: Theme = {
+  id: 'cinematic',
+  name: 'Cinematic',
+  description: 'Ultra-dark with moody gradients, gold accents, and slow dissolve transitions.',
+  colors: {
+    primary: '#d69e2e',
+    secondary: '#b7791f',
+    background: '#0a0f1a',
+    backgroundLight: '#1a202c',
+    text: '#f7fafc',
+    textMuted: '#a0aec0',
+    highlight: '#ecc94b',
+    warning: '#fc8181',
+  },
+  typography: {
+    bodyFontFamily: SERIF,
+    titleFontFamily: SERIF,
+    titleWeight: 'bold',
+    lineHeight: 1.5,
+    titleLineHeight: 1.2,
+  },
+  style: {
+    textShadow: true,
+    overlayOpacity: 0.55,
+    animationSpeed: 1.2,
+  },
+  renderStyle: {
+    name: 'cinematic',
+    defaultTextAnimation: 'fadeIn',
+    defaultImageAnimation: 'slowZoom',
+    ambientMotion: true,
+    defaultTransition: { type: 'dissolve', duration: 1.2 },
+    templateHints: {
+      titleBlock: { showAccentLine: true },
+    },
+  },
+  colorSchemes: {
+    blue: { bg: '#0d1b2a', text: '#90cdf4', accent: '#63b3ed' },
+    green: { bg: '#0d1b14', text: '#9ae6b4', accent: '#68d391' },
+    purple: { bg: '#1a0d2e', text: '#d6bcfa', accent: '#b794f4' },
+    red: { bg: '#2a0d0d', text: '#fc8181', accent: '#feb2b2' },
+    orange: { bg: '#2a1a0d', text: '#fbd38d', accent: '#f6ad55' },
+    teal: { bg: '#0d2a2a', text: '#81e6d9', accent: '#4fd1c5' },
+  },
+  persistentLayers: {
+    bottomLayers: [
+      {
+        template: 'gradientBackground',
+        config: { type: 'gradientBackground', preset: 'radial-dark' },
+      },
+    ],
+  },
+};
+
+// ============================================
+// 8. Warm Earth
+// ============================================
+
+const warmEarth: Theme = {
+  id: 'warm-earth',
+  name: 'Warm Earth',
+  description: 'Natural warm tones with earthy browns and terracotta accents.',
+  colors: {
+    primary: '#9c4221',
+    secondary: '#c05621',
+    background: '#1c1410',
+    backgroundLight: '#2d241e',
+    text: '#faf5f0',
+    textMuted: '#c4a882',
+    highlight: '#dd6b20',
+    warning: '#e53e3e',
+  },
+  typography: {
+    bodyFontFamily: GEORGIA,
+    titleFontFamily: GEORGIA,
+    titleWeight: 'bold',
+    lineHeight: 1.6,
+  },
+  style: {
+    textShadow: true,
+    overlayOpacity: 0.5,
+    animationSpeed: 1.1,
+  },
+  renderStyle: {
+    name: 'warm-earth',
+    defaultTextAnimation: 'fadeIn',
+    defaultImageAnimation: 'panLeft',
+    ambientMotion: true,
+    defaultTransition: { type: 'fade', duration: 0.9 },
+  },
+  colorSchemes: {
+    blue: { bg: '#2a1f14', text: '#90cdf4', accent: '#63b3ed' },
+    green: { bg: '#1e2a14', text: '#9ae6b4', accent: '#68d391' },
+    purple: { bg: '#2a142a', text: '#d6bcfa', accent: '#b794f4' },
+    red: { bg: '#2a1414', text: '#fc8181', accent: '#feb2b2' },
+    orange: { bg: '#2a1e0a', text: '#fbd38d', accent: '#f6ad55' },
+    teal: { bg: '#142a28', text: '#81e6d9', accent: '#4fd1c5' },
+  },
+  persistentLayers: {
+    bottomLayers: [
+      {
+        template: 'gradientBackground',
+        config: { type: 'gradientBackground', preset: 'earth-tones' },
+      },
+    ],
+  },
+};
+
+// ============================================
+// Theme Library
+// ============================================
+
+/**
+ * All built-in themes, keyed by id.
+ */
+export const THEMES: Record<string, Theme> = {
+  documentary,
+  minimalist,
+  bold,
+  'morning-light': morningLight,
+  'tech-dark': techDark,
+  magazine,
+  cinematic,
+  'warm-earth': warmEarth,
+};
+
+/** The default theme id. */
+export const DEFAULT_THEME_ID = 'documentary';
+
+/** The default theme (documentary — migrated from old DEFAULT_THEME). */
+export const DEFAULT_THEME: Theme = documentary;
+
+/**
+ * Resolve a theme by id. Returns the default theme when `id` is
+ * undefined or not found in the library.
+ */
+export function resolveTheme(id: string | undefined): Theme {
+  if (id && id in THEMES) return THEMES[id];
+  return DEFAULT_THEME;
+}
+
+/**
+ * Get all available theme ids.
+ */
+export function getAvailableThemes(): string[] {
+  return Object.keys(THEMES);
+}
+
+/**
+ * Get a summary of all 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,
+  }));
+}

package/src/spatial/Geohash.ts

@@ -0,0 +1,168 @@
+/**
+ * Geohash Utilities
+ *
+ * Provides geohash encoding/decoding and spatial utilities using the standard
+ * ngeohash library for core operations, plus custom utilities for overlap checking
+ * and distance calculation.
+ *
+ * Geohashes are a hierarchical spatial indexing system that divides the world
+ * into a grid of cells. Each additional character narrows the area by ~1/32.
+ *
+ * Precision guide:
+ * - 4 chars: ~39km x 19km (used for tile indexing)
+ * - 5 chars: ~5km x 5km
+ * - 6 chars: ~1.2km x 0.6km
+ */
+
+import ngeohash from 'ngeohash';
+
+/**
+ * Encode latitude/longitude to a geohash string.
+ * Uses the standard ngeohash library.
+ */
+export function encodeGeohash(lat: number, lng: number, precision = 9): string {
+  return ngeohash.encode(lat, lng, precision);
+}
+
+/**
+ * Decode a geohash to latitude/longitude center with error bounds.
+ * Uses the standard ngeohash library.
+ */
+export function decodeGeohash(hash: string): {
+  lat: number;
+  lng: number;
+  latErr: number;
+  lngErr: number;
+} {
+  const result = ngeohash.decode(hash);
+  return {
+    lat: result.latitude,
+    lng: result.longitude,
+    latErr: result.error.latitude,
+    lngErr: result.error.longitude,
+  };
+}
+
+/**
+ * Get the 8 neighboring geohash cells.
+ * Returns up to 8 neighbors (fewer at poles or antimeridian).
+ * Uses the standard ngeohash library.
+ */
+export function getNeighbors(hash: string): string[] {
+  return ngeohash.neighbors(hash);
+}
+
+/**
+ * Get a 3x3 grid of geohash4 cells (center + 8 neighbors).
+ * Used for landing bonus expansions in Fly mode.
+ *
+ * @param geohash4 - Center geohash4 cell
+ * @returns Array of 9 geohash4 cells (center first, then neighbors)
+ *
+ * @example
+ * getGeohash4Neighbors('c23n')
+ * // => ['c23n', 'c23p', 'c23q', 'c23j', 'c23m', 'c23k', 'c23h', 'c23e', 'c23s']
+ */
+export function getGeohash4Neighbors(geohash4: string): string[] {
+  if (geohash4.length !== 4) {
+    throw new Error(`getGeohash4Neighbors requires 4-char geohash, got: ${geohash4}`);
+  }
+  const neighbors = getNeighbors(geohash4);
+  return [geohash4, ...neighbors];
+}
+
+/**
+ * Get the prefix of a geohash at a given precision.
+ * Simple helper for extracting geohash prefixes for directory organization.
+ */
+export function getGeohashPrefix(geohash: string, precision: number): string {
+  return geohash.slice(0, precision);
+}
+
+/**
+ * Convert a geohash prefix to a hierarchical path.
+ *
+ * Examples:
+ *   "9mud" -> "9/m/u/d"
+ *   "9q8y" -> "9/q/8/y"
+ *   "c24k" -> "c/2/4/k"
+ *
+ * This is used for organizing files in hierarchical directories to avoid
+ * thousands of folders in a single directory, which causes filesystem
+ * performance issues.
+ */
+export function geohashToHierarchicalPath(geohash4: string): string {
+  if (geohash4.length !== 4) {
+    throw new Error(`geohashToHierarchicalPath requires 4-char geohash, got: ${geohash4}`);
+  }
+  const [c1, c2, c3, c4] = geohash4.split('');
+  return `${c1}/${c2}/${c3}/${c4}`;
+}
+
+/**
+ * Compute all geohash cells along the path between two geohash cells.
+ * Interpolates lat/lng points between the centers of `from` and `to`,
+ * encoding each to a geohash at the given precision, and returns the
+ * deduplicated list of intermediate cells (excluding `from` and `to`).
+ */
+export function getGeohashPath(from: string, to: string, precision = 4): string[] {
+  if (from === to) return [];
+
+  const fromCenter = decodeGeohash(from);
+  const toCenter = decodeGeohash(to);
+
+  // Compute approximate distance to determine step count
+  const dLat = Math.abs(toCenter.lat - fromCenter.lat);
+  const dLng = Math.abs(toCenter.lng - fromCenter.lng);
+  // Rough km: 1 degree lat ≈ 111km, 1 degree lng ≈ 111km * cos(midLat)
+  const midLatRad = ((fromCenter.lat + toCenter.lat) / 2) * (Math.PI / 180);
+  const approxKm = Math.sqrt((dLat * 111) ** 2 + (dLng * 111 * Math.cos(midLatRad)) ** 2);
+
+  // Step every ~15km to avoid skipping any geohash4 cell (~39x19km)
+  const steps = Math.max(2, Math.ceil(approxKm / 15));
+
+  const seen = new Set<string>();
+  seen.add(from);
+  seen.add(to);
+
+  const path: string[] = [];
+  for (let i = 1; i < steps; i++) {
+    const t = i / steps;
+    const lat = fromCenter.lat + t * (toCenter.lat - fromCenter.lat);
+    const lng = fromCenter.lng + t * (toCenter.lng - fromCenter.lng);
+    const hash = encodeGeohash(lat, lng, precision);
+    if (!seen.has(hash)) {
+      seen.add(hash);
+      path.push(hash);
+    }
+  }
+
+  return path;
+}
+
+/**
+ * Check if a geohash cell overlaps with a bounding box.
+ * Custom implementation (not available in ngeohash).
+ */
+export function geohashOverlapsBounds(
+  hash: string,
+  bounds: { north: number; south: number; east: number; west: number },
+): boolean {
+  const { lat, lng, latErr, lngErr } = decodeGeohash(hash);
+
+  const hashNorth = lat + latErr;
+  const hashSouth = lat - latErr;
+  const hashEast = lng + lngErr;
+  const hashWest = lng - lngErr;
+
+  return !(
+    hashNorth < bounds.south ||
+    hashSouth > bounds.north ||
+    hashEast < bounds.west ||
+    hashWest > bounds.east
+  );
+}
+
+// haversineDistance is now in shared/spatial/Haversine.ts (canonical location).
+// Re-export for backwards compatibility with existing imports.
+export { haversineDistance } from './Haversine.js';