@bendyline/squisq 2.1.0 → 2.3.0

package/src/spatial/Geohash.ts

@@ -1,196 +0,0 @@
-/**
- * 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';
-import { haversineDistance } from './Haversine.js';
-
-/**
- * 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) return [];
-  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) return '';
-  const [c1, c2, c3, c4] = geohash4.split('');
-  return `${c1}/${c2}/${c3}/${c4}`;
-}
-
-/**
- * Compute all geohash cells along the great-circle path between two geohash cells.
- * Samples points along the spherical arc from `from` to `to`, encoding each to a
- * geohash at the given precision, and returns the deduplicated list of intermediate
- * cells (excluding `from` and `to`).
- *
- * Uses spherical linear interpolation (SLERP) via 3D unit vectors, which correctly
- * handles antimeridian crossings and polar paths — both of which flat lat/lng
- * interpolation gets wrong.
- */
-export function getGeohashPath(from: string, to: string, precision = 4): string[] {
-  if (from === to) return [];
-
-  const fromCenter = decodeGeohash(from);
-  const toCenter = decodeGeohash(to);
-
-  // Use haversine for accurate great-circle distance (step sizing)
-  const distKm = haversineDistance(
-    { lat: fromCenter.lat, lng: fromCenter.lng },
-    { lat: toCenter.lat, lng: toCenter.lng },
-  );
-
-  // Step every ~15km to avoid skipping any geohash4 cell (~39x19km)
-  const steps = Math.max(2, Math.ceil(distKm / 15));
-
-  // Convert endpoints to unit Cartesian vectors for SLERP
-  const φ1 = (fromCenter.lat * Math.PI) / 180;
-  const λ1 = (fromCenter.lng * Math.PI) / 180;
-  const φ2 = (toCenter.lat * Math.PI) / 180;
-  const λ2 = (toCenter.lng * Math.PI) / 180;
-
-  const x1 = Math.cos(φ1) * Math.cos(λ1);
-  const y1 = Math.cos(φ1) * Math.sin(λ1);
-  const z1 = Math.sin(φ1);
-  const x2 = Math.cos(φ2) * Math.cos(λ2);
-  const y2 = Math.cos(φ2) * Math.sin(λ2);
-  const z2 = Math.sin(φ2);
-
-  // Central angle between the two points
-  const dot = Math.max(-1, Math.min(1, x1 * x2 + y1 * y2 + z1 * z2));
-  const d = Math.acos(dot);
-  // Near-antipodal fallback: sin(d)≈0 means the great circle is undefined.
-  // Extremely unlikely for geohash path use; fall back to linear lat/lng.
-  const useLinear = Math.abs(Math.sin(d)) < 1e-10;
-
-  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;
-    let lat: number;
-    let lng: number;
-    if (useLinear) {
-      lat = fromCenter.lat + t * (toCenter.lat - fromCenter.lat);
-      lng = fromCenter.lng + t * (toCenter.lng - fromCenter.lng);
-    } else {
-      const A = Math.sin((1 - t) * d) / Math.sin(d);
-      const B = Math.sin(t * d) / Math.sin(d);
-      const x = A * x1 + B * x2;
-      const y = A * y1 + B * y2;
-      const z = A * z1 + B * z2;
-      lat = (Math.atan2(z, Math.sqrt(x * x + y * y)) * 180) / Math.PI;
-      lng = (Math.atan2(y, x) * 180) / Math.PI;
-    }
-    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
-  );
-}

package/src/spatial/Haversine.ts

@@ -1,59 +0,0 @@
-/**
- * Haversine Distance Calculation
- *
- * Provides accurate distance calculation between two geographic coordinates
- * using the Haversine formula, which accounts for Earth's curvature.
- */
-
-import type { Coordinates } from '../schemas/Types.js';
-
-/**
- * Calculate distance between two coordinates using Haversine formula.
- *
- * @param from Start coordinates
- * @param to End coordinates
- * @returns Distance in kilometers
- */
-export function haversineDistance(from: Coordinates, to: Coordinates): number {
-  const R = 6371; // Earth's radius in kilometers
-
-  const dLat = toRadians(to.lat - from.lat);
-  const dLng = toRadians(to.lng - from.lng);
-
-  const a =
-    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
-    Math.cos(toRadians(from.lat)) *
-      Math.cos(toRadians(to.lat)) *
-      Math.sin(dLng / 2) *
-      Math.sin(dLng / 2);
-
-  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
-
-  return R * c;
-}
-
-/**
- * Calculate bearing from one coordinate to another.
- *
- * @param from Start coordinates
- * @param to End coordinates
- * @returns Bearing in degrees (0-360, where 0 = north, 90 = east)
- */
-export function calculateBearing(from: Coordinates, to: Coordinates): number {
-  const dLng = toRadians(to.lng - from.lng);
-  const lat1 = toRadians(from.lat);
-  const lat2 = toRadians(to.lat);
-
-  const x = Math.sin(dLng) * Math.cos(lat2);
-  const y = Math.cos(lat1) * Math.sin(lat2) - Math.sin(lat1) * Math.cos(lat2) * Math.cos(dLng);
-
-  const bearing = Math.atan2(x, y);
-  return ((bearing * 180) / Math.PI + 360) % 360;
-}
-
-/**
- * Convert degrees to radians.
- */
-function toRadians(degrees: number): number {
-  return (degrees * Math.PI) / 180;
-}

package/src/spatial/index.ts

@@ -1,2 +0,0 @@
-export * from './Haversine.js';
-export * from './Geohash.js';

package/src/storage/ContentContainer.ts

@@ -1,220 +0,0 @@
-/**
- * ContentContainer — virtual file system for document containers.
- *
- * A Squisq document is more than just markdown: it's a container of files
- * including the primary markdown document, images, audio, timing data, and
- * other media. ContentContainer provides an abstract async file system
- * interface for reading, writing, and listing these files.
- *
- * Paths are forward-slash separated strings relative to the container root
- * (e.g., 'images/hero.jpg', 'index.md'). No leading slash.
- *
- * Implementations (in core):
- * - MemoryContentContainer — in-memory Map (for zip import, tests, transient use)
- * - ScopedContentContainer — a prefix-scoped view onto a parent container
- */
-
-/**
- * Metadata about a file in a ContentContainer.
- */
-export interface ContentEntry {
-  /** Relative path within the container (e.g., 'images/hero.jpg') */
-  path: string;
-  /** MIME type (e.g., 'image/jpeg') */
-  mimeType: string;
-  /** File size in bytes */
-  size: number;
-}
-
-/**
- * Abstract async file system for document containers.
- *
- * All paths are forward-slash separated, relative to the container root,
- * with no leading slash. Example: 'images/hero.jpg', 'index.md'.
- */
-export interface ContentContainer {
-  /** Read a file's binary content. Returns null if the file does not exist. */
-  readFile(path: string): Promise<ArrayBuffer | null>;
-
-  /** Write a file. Creates or overwrites. */
-  writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void>;
-
-  /** Remove a file. No-op if the file does not exist. */
-  removeFile(path: string): Promise<void>;
-
-  /**
-   * List files in the container.
-   *
-   * Returns file **entries** (`ContentEntry[]` with `.path`/`.mimeType`/`.size`),
-   * NOT bare path strings — despite the name. Read `entry.path` for the path;
-   * calling string methods (e.g. `.startsWith`) directly on an entry will throw.
-   * @param prefix — Optional path prefix to filter by (e.g., 'images/')
-   */
-  listFiles(prefix?: string): Promise<ContentEntry[]>;
-
-  /** Check whether a file exists. */
-  exists(path: string): Promise<boolean>;
-
-  /**
-   * Find the primary markdown document path.
-   *
-   * Discovery order: index.md → doc.md → document.md → first *.md at root.
-   * Returns null if no markdown file is found at the root level.
-   */
-  getDocumentPath(): Promise<string | null>;
-
-  /**
-   * Convenience: read the primary markdown document as a UTF-8 string.
-   * Returns null if no markdown file is found.
-   */
-  readDocument(): Promise<string | null>;
-
-  /**
-   * Convenience: write a markdown document.
-   * @param markdown — The markdown content
-   * @param filename — Filename to use (defaults to 'index.md')
-   */
-  writeDocument(markdown: string, filename?: string): Promise<void>;
-}
-
-// ============================================
-// Well-known markdown filenames in priority order
-// ============================================
-
-const MARKDOWN_PRIORITY = ['index.md', 'doc.md', 'document.md'];
-
-/**
- * Find the primary markdown path from a list of file entries.
- * Exported for reuse by other ContentContainer implementations.
- */
-export function findDocumentPath(entries: ContentEntry[]): string | null {
-  // Only consider root-level files (no '/' in path)
-  const rootFiles = entries.filter((e) => !e.path.includes('/'));
-
-  for (const name of MARKDOWN_PRIORITY) {
-    const match = rootFiles.find((e) => e.path.toLowerCase() === name);
-    if (match) return match.path;
-  }
-
-  // Fallback: first .md file at root
-  const firstMd = rootFiles.find((e) => e.path.toLowerCase().endsWith('.md'));
-  return firstMd?.path ?? null;
-}
-
-// ============================================
-// MemoryContentContainer
-// ============================================
-
-interface MemoryFile {
-  data: ArrayBuffer;
-  mimeType: string;
-}
-
-/**
- * In-memory ContentContainer backed by a Map.
- *
- * Used for zip import (deserialize into memory), tests, and transient operations.
- */
-export class MemoryContentContainer implements ContentContainer {
-  private files = new Map<string, MemoryFile>();
-
-  async readFile(path: string): Promise<ArrayBuffer | null> {
-    const stored = this.files.get(path)?.data;
-    // A container owns its bytes. Returning the backing buffer would let a
-    // caller mutate stored state without going through writeFile().
-    return stored ? stored.slice(0) : null;
-  }
-
-  async writeFile(path: string, data: ArrayBuffer | Uint8Array, mimeType?: string): Promise<void> {
-    // Copy to a standalone ArrayBuffer. Uint8Array/Buffer may share a larger
-    // backing buffer (e.g., Node's buffer pool), so we must slice to the
-    // exact byte range to avoid storing stale pool data.
-    // ArrayBuffer.isView is cross-realm-safe (unlike `instanceof
-    // ArrayBuffer`, which fails for values created in jsdom/iframes).
-    let source: Uint8Array;
-    if (ArrayBuffer.isView(data)) {
-      source = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-    } else {
-      source = new Uint8Array(data);
-    }
-    // Always materialize in this realm, including for iframe ArrayBuffers and
-    // views backed by SharedArrayBuffer.
-    const owned = new Uint8Array(source.byteLength);
-    owned.set(source);
-    this.files.set(path, {
-      data: owned.buffer,
-      mimeType: mimeType ?? guessMimeType(path),
-    });
-  }
-
-  async removeFile(path: string): Promise<void> {
-    this.files.delete(path);
-  }
-
-  async listFiles(prefix?: string): Promise<ContentEntry[]> {
-    const entries: ContentEntry[] = [];
-    for (const [path, file] of this.files) {
-      if (prefix && !path.startsWith(prefix)) continue;
-      entries.push({
-        path,
-        mimeType: file.mimeType,
-        size: file.data.byteLength,
-      });
-    }
-    return entries;
-  }
-
-  async exists(path: string): Promise<boolean> {
-    return this.files.has(path);
-  }
-
-  async getDocumentPath(): Promise<string | null> {
-    return findDocumentPath(await this.listFiles());
-  }
-
-  async readDocument(): Promise<string | null> {
-    const docPath = await this.getDocumentPath();
-    if (!docPath) return null;
-    const data = await this.readFile(docPath);
-    if (!data) return null;
-    return new TextDecoder().decode(data);
-  }
-
-  async writeDocument(markdown: string, filename?: string): Promise<void> {
-    const name = filename ?? 'index.md';
-    const data = new TextEncoder().encode(markdown);
-    await this.writeFile(name, data, 'text/markdown');
-  }
-}
-
-// ============================================
-// MIME type guessing
-// ============================================
-
-const EXTENSION_MIME_MAP: Record<string, string> = {
-  '.md': 'text/markdown',
-  '.txt': 'text/plain',
-  '.json': 'application/json',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.png': 'image/png',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.mp4': 'video/mp4',
-  '.webm': 'video/webm',
-  '.mp3': 'audio/mpeg',
-  '.wav': 'audio/wav',
-  '.ogg': 'audio/ogg',
-  '.css': 'text/css',
-  '.html': 'text/html',
-  '.js': 'application/javascript',
-};
-
-function guessMimeType(path: string): string {
-  const dot = path.lastIndexOf('.');
-  if (dot === -1) return 'application/octet-stream';
-  const ext = path.slice(dot).toLowerCase();
-  return EXTENSION_MIME_MAP[ext] ?? 'application/octet-stream';
-}

package/src/storage/LocalForageAdapter.ts

@@ -1,103 +0,0 @@
-/**
- * LocalForage adapter - IndexedDB storage with automatic fallbacks.
- *
- * Uses localforage which provides IndexedDB storage with automatic
- * fallbacks to WebSQL and localStorage. This allows storing much more
- * data than raw localStorage (which is limited to ~5MB).
- *
- * Unlike LocalStorageAdapter, this adapter can store binary data
- * (ArrayBuffer, Blob, Uint8Array) natively without JSON serialization.
- *
- * Ported from qualla-internal/shared/services/StorageAdapters.ts with
- * configurable store name and key prefix.
- */
-
-import localforage from 'localforage';
-import type { StorageAdapter } from './Storage.js';
-
-export interface LocalForageAdapterOptions {
-  /** IndexedDB database name (default: 'squisq') */
-  name?: string;
-  /** IndexedDB object store name (default: 'data') */
-  storeName?: string;
-  /** Key prefix for namespacing (default: '') */
-  prefix?: string;
-  /** Human-readable description (default: 'Squisq storage') */
-  description?: string;
-}
-
-export class LocalForageAdapter implements StorageAdapter {
-  readonly supportsEnumeration = true;
-  private store: LocalForage;
-  private prefix: string;
-
-  constructor(options: LocalForageAdapterOptions = {}) {
-    const {
-      name = 'squisq',
-      storeName = 'data',
-      prefix = '',
-      description = 'Squisq storage',
-    } = options;
-
-    this.prefix = prefix;
-    this.store = localforage.createInstance({ name, storeName, description });
-  }
-
-  async get<T>(key: string): Promise<T | null> {
-    try {
-      const value = await this.store.getItem<T>(this.prefix + key);
-      return value;
-    } catch (e: unknown) {
-      console.warn('[Storage] get (IndexedDB) failed:', key, e);
-      return null;
-    }
-  }
-
-  async set<T>(key: string, value: T): Promise<void> {
-    try {
-      await this.store.setItem(this.prefix + key, value);
-    } catch (e: unknown) {
-      console.error('[Storage] set (IndexedDB) failed:', key, e);
-      throw e;
-    }
-  }
-
-  async remove(key: string): Promise<void> {
-    try {
-      await this.store.removeItem(this.prefix + key);
-    } catch (e: unknown) {
-      console.warn('[Storage] remove (IndexedDB) failed:', key, e);
-    }
-  }
-
-  async clear(): Promise<void> {
-    try {
-      if (this.prefix) {
-        // Only remove keys with our prefix
-        const keys = await this.store.keys();
-        const keysToRemove = keys.filter((k) => k.startsWith(this.prefix));
-        await Promise.all(keysToRemove.map((k) => this.store.removeItem(k)));
-      } else {
-        // No prefix — clear the entire store
-        await this.store.clear();
-      }
-    } catch (e: unknown) {
-      console.error('[Storage] clear (IndexedDB) failed:', e);
-    }
-  }
-
-  async keys(): Promise<string[]> {
-    try {
-      const allKeys = await this.store.keys();
-      if (this.prefix) {
-        return allKeys
-          .filter((k) => k.startsWith(this.prefix))
-          .map((k) => k.slice(this.prefix.length));
-      }
-      return allKeys;
-    } catch (e: unknown) {
-      console.warn('[Storage] keys (IndexedDB) failed:', e);
-      return [];
-    }
-  }
-}

package/src/storage/LocalStorageAdapter.ts

@@ -1,57 +0,0 @@
-/**
- * localStorage adapter for web browsers.
- * Supports a configurable key prefix to namespace stored data.
- */
-
-import type { StorageAdapter } from './Storage.js';
-
-export class LocalStorageAdapter implements StorageAdapter {
-  readonly supportsEnumeration = true;
-  private prefix: string;
-
-  constructor(prefix = '') {
-    this.prefix = prefix;
-  }
-
-  async get<T>(key: string): Promise<T | null> {
-    try {
-      const raw = localStorage.getItem(this.prefix + key);
-      if (raw === null) return null;
-      return JSON.parse(raw) as T;
-    } catch {
-      return null;
-    }
-  }
-
-  async set<T>(key: string, value: T): Promise<void> {
-    localStorage.setItem(this.prefix + key, JSON.stringify(value));
-  }
-
-  async remove(key: string): Promise<void> {
-    localStorage.removeItem(this.prefix + key);
-  }
-
-  async clear(): Promise<void> {
-    const keysToRemove: string[] = [];
-    for (let i = 0; i < localStorage.length; i++) {
-      const k = localStorage.key(i);
-      if (k && k.startsWith(this.prefix)) {
-        keysToRemove.push(k);
-      }
-    }
-    for (const k of keysToRemove) {
-      localStorage.removeItem(k);
-    }
-  }
-
-  async keys(): Promise<string[]> {
-    const result: string[] = [];
-    for (let i = 0; i < localStorage.length; i++) {
-      const k = localStorage.key(i);
-      if (k && k.startsWith(this.prefix)) {
-        result.push(k.slice(this.prefix.length));
-      }
-    }
-    return result;
-  }
-}