@autumnsgrove/gossamer 0.0.1 → 0.1.0

package/src/animation.ts

@@ -0,0 +1,243 @@
+/**
+ * Gossamer Animation Utilities
+ *
+ * FPS limiting, animation loop management, and timing utilities.
+ */
+
+/**
+ * Animation state for tracking loop execution
+ */
+export interface AnimationState {
+  /** Whether animation is currently running */
+  isRunning: boolean;
+  /** Current animation frame ID */
+  frameId: number | null;
+  /** Timestamp of last frame */
+  lastFrameTime: number;
+  /** Frame interval in ms (derived from FPS) */
+  frameInterval: number;
+  /** Total elapsed time in ms */
+  elapsedTime: number;
+  /** Current frame count */
+  frameCount: number;
+}
+
+/**
+ * Options for creating an animation loop
+ */
+export interface AnimationOptions {
+  /** Target frames per second (default: 30) */
+  fps?: number;
+  /** Callback when animation starts */
+  onStart?: () => void;
+  /** Callback when animation stops */
+  onStop?: () => void;
+  /** Callback for each frame - return false to stop */
+  onFrame: (time: number, deltaTime: number, frameCount: number) => boolean | void;
+}
+
+/**
+ * Create a managed animation loop with FPS limiting
+ */
+export function createAnimationLoop(options: AnimationOptions): {
+  start: () => void;
+  stop: () => void;
+  pause: () => void;
+  resume: () => void;
+  getState: () => AnimationState;
+} {
+  const { fps = 30, onStart, onStop, onFrame } = options;
+
+  const state: AnimationState = {
+    isRunning: false,
+    frameId: null,
+    lastFrameTime: 0,
+    frameInterval: 1000 / fps,
+    elapsedTime: 0,
+    frameCount: 0,
+  };
+
+  let pausedTime = 0;
+  let isPaused = false;
+
+  function animate(currentTime: number): void {
+    if (!state.isRunning || isPaused) return;
+
+    const deltaTime = currentTime - state.lastFrameTime;
+
+    if (deltaTime >= state.frameInterval) {
+      state.elapsedTime += deltaTime;
+      state.frameCount++;
+
+      const continueAnimation = onFrame(currentTime, deltaTime, state.frameCount);
+
+      if (continueAnimation === false) {
+        stop();
+        return;
+      }
+
+      // Adjust for frame timing drift
+      state.lastFrameTime = currentTime - (deltaTime % state.frameInterval);
+    }
+
+    state.frameId = requestAnimationFrame(animate);
+  }
+
+  function start(): void {
+    if (state.isRunning) return;
+
+    state.isRunning = true;
+    state.lastFrameTime = performance.now();
+    state.elapsedTime = 0;
+    state.frameCount = 0;
+    isPaused = false;
+
+    onStart?.();
+    state.frameId = requestAnimationFrame(animate);
+  }
+
+  function stop(): void {
+    state.isRunning = false;
+    isPaused = false;
+
+    if (state.frameId !== null) {
+      cancelAnimationFrame(state.frameId);
+      state.frameId = null;
+    }
+
+    onStop?.();
+  }
+
+  function pause(): void {
+    if (!state.isRunning || isPaused) return;
+
+    isPaused = true;
+    pausedTime = performance.now();
+
+    if (state.frameId !== null) {
+      cancelAnimationFrame(state.frameId);
+      state.frameId = null;
+    }
+  }
+
+  function resume(): void {
+    if (!state.isRunning || !isPaused) return;
+
+    isPaused = false;
+    // Adjust lastFrameTime to account for paused duration
+    state.lastFrameTime += performance.now() - pausedTime;
+    state.frameId = requestAnimationFrame(animate);
+  }
+
+  function getState(): AnimationState {
+    return { ...state };
+  }
+
+  return { start, stop, pause, resume, getState };
+}
+
+/**
+ * Simple throttle function for limiting function execution
+ */
+export function throttle<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  limit: number
+): (...args: Parameters<T>) => void {
+  let lastCall = 0;
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+
+  return (...args: Parameters<T>): void => {
+    const now = Date.now();
+
+    if (now - lastCall >= limit) {
+      lastCall = now;
+      fn(...args);
+    } else if (!timeout) {
+      timeout = setTimeout(() => {
+        lastCall = Date.now();
+        timeout = null;
+        fn(...args);
+      }, limit - (now - lastCall));
+    }
+  };
+}
+
+/**
+ * Debounce function for delaying execution until activity stops
+ */
+export function debounce<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  delay: number
+): (...args: Parameters<T>) => void {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+
+  return (...args: Parameters<T>): void => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+
+    timeout = setTimeout(() => {
+      timeout = null;
+      fn(...args);
+    }, delay);
+  };
+}
+
+/**
+ * Calculate actual FPS from frame times
+ */
+export function calculateFPS(frameTimes: number[], sampleSize: number = 60): number {
+  if (frameTimes.length < 2) return 0;
+
+  const samples = frameTimes.slice(-sampleSize);
+  const totalTime = samples[samples.length - 1] - samples[0];
+  const frameCount = samples.length - 1;
+
+  if (totalTime <= 0) return 0;
+
+  return (frameCount / totalTime) * 1000;
+}
+
+/**
+ * Easing functions for smooth animations
+ */
+export const easings = {
+  /** Linear - no easing */
+  linear: (t: number): number => t,
+
+  /** Ease in - slow start */
+  easeIn: (t: number): number => t * t,
+
+  /** Ease out - slow end */
+  easeOut: (t: number): number => t * (2 - t),
+
+  /** Ease in/out - slow start and end */
+  easeInOut: (t: number): number => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+
+  /** Sine ease in */
+  sineIn: (t: number): number => 1 - Math.cos((t * Math.PI) / 2),
+
+  /** Sine ease out */
+  sineOut: (t: number): number => Math.sin((t * Math.PI) / 2),
+
+  /** Sine ease in/out */
+  sineInOut: (t: number): number => -(Math.cos(Math.PI * t) - 1) / 2,
+
+  /** Bounce at end */
+  bounceOut: (t: number): number => {
+    const n1 = 7.5625;
+    const d1 = 2.75;
+
+    if (t < 1 / d1) {
+      return n1 * t * t;
+    } else if (t < 2 / d1) {
+      return n1 * (t -= 1.5 / d1) * t + 0.75;
+    } else if (t < 2.5 / d1) {
+      return n1 * (t -= 2.25 / d1) * t + 0.9375;
+    } else {
+      return n1 * (t -= 2.625 / d1) * t + 0.984375;
+    }
+  },
+};
+
+export type EasingFunction = (t: number) => number;

package/src/characters.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Tests for character set utilities
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  CHARACTER_SETS,
+  getCharacterSet,
+  getCharacters,
+  getCharacterSetNames,
+  createCharacterSet,
+  validateCharacterSet,
+  invertCharacters,
+} from './characters';
+
+describe('CHARACTER_SETS', () => {
+  it('should contain standard character set', () => {
+    expect(CHARACTER_SETS.standard).toBeDefined();
+    expect(CHARACTER_SETS.standard.characters).toBe(' .:-=+*#%@');
+  });
+
+  it('should have all expected character sets', () => {
+    const expectedSets = [
+      'standard',
+      'dense',
+      'minimal',
+      'grove',
+      'dots',
+      'blocks',
+      'lines',
+      'stars',
+      'nature',
+      'weather',
+      'binary',
+      'math',
+    ];
+
+    for (const setName of expectedSets) {
+      expect(CHARACTER_SETS[setName]).toBeDefined();
+    }
+  });
+
+  it('should have all character sets start with space', () => {
+    for (const [name, set] of Object.entries(CHARACTER_SETS)) {
+      expect(set.characters[0]).toBe(' ');
+    }
+  });
+});
+
+describe('getCharacterSet', () => {
+  it('should return character set by name', () => {
+    const result = getCharacterSet('standard');
+    expect(result).toBeDefined();
+    expect(result?.name).toBe('Standard');
+    expect(result?.characters).toBe(' .:-=+*#%@');
+  });
+
+  it('should return undefined for unknown set', () => {
+    const result = getCharacterSet('nonexistent');
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('getCharacters', () => {
+  it('should return characters string for valid set', () => {
+    expect(getCharacters('minimal')).toBe(' .:*#');
+    expect(getCharacters('blocks')).toBe(' ░▒▓█');
+  });
+
+  it('should return standard characters for unknown set', () => {
+    expect(getCharacters('nonexistent')).toBe(' .:-=+*#%@');
+  });
+});
+
+describe('getCharacterSetNames', () => {
+  it('should return array of all set names', () => {
+    const names = getCharacterSetNames();
+    expect(Array.isArray(names)).toBe(true);
+    expect(names).toContain('standard');
+    expect(names).toContain('minimal');
+    expect(names).toContain('blocks');
+  });
+
+  it('should return same count as CHARACTER_SETS keys', () => {
+    const names = getCharacterSetNames();
+    expect(names.length).toBe(Object.keys(CHARACTER_SETS).length);
+  });
+});
+
+describe('createCharacterSet', () => {
+  it('should create character set with all properties', () => {
+    const result = createCharacterSet(
+      'custom',
+      ' abc',
+      'A custom set',
+      ['testing']
+    );
+
+    expect(result.name).toBe('custom');
+    expect(result.characters).toBe(' abc');
+    expect(result.description).toBe('A custom set');
+    expect(result.bestFor).toEqual(['testing']);
+  });
+
+  it('should use defaults for optional parameters', () => {
+    const result = createCharacterSet('minimal', ' xy');
+
+    expect(result.name).toBe('minimal');
+    expect(result.characters).toBe(' xy');
+    expect(result.description).toBe('');
+    expect(result.bestFor).toEqual([]);
+  });
+});
+
+describe('validateCharacterSet', () => {
+  it('should return true for valid character sets', () => {
+    expect(validateCharacterSet(' .:-=+*#%@')).toBe(true);
+    expect(validateCharacterSet(' ab')).toBe(true);
+    expect(validateCharacterSet(' ░▒▓█')).toBe(true);
+  });
+
+  it('should return false for too short sets', () => {
+    expect(validateCharacterSet('')).toBe(false);
+    expect(validateCharacterSet(' ')).toBe(false);
+  });
+
+  it('should return false for sets not starting with space', () => {
+    expect(validateCharacterSet('abc')).toBe(false);
+    expect(validateCharacterSet('.:-=')).toBe(false);
+  });
+});
+
+describe('invertCharacters', () => {
+  it('should reverse character string', () => {
+    expect(invertCharacters(' abc')).toBe('cba ');
+    expect(invertCharacters(' .:-=')).toBe('=-:. ');
+  });
+
+  it('should handle single character', () => {
+    expect(invertCharacters(' ')).toBe(' ');
+  });
+
+  it('should be reversible', () => {
+    const original = ' .:-=+*#%@';
+    const inverted = invertCharacters(original);
+    const restored = invertCharacters(inverted);
+    expect(restored).toBe(original);
+  });
+});

package/src/characters.ts

@@ -0,0 +1,164 @@
+/**
+ * Gossamer Character Sets
+ *
+ * Predefined character sets for ASCII rendering, ordered from light to dark.
+ * Character density determines which character represents each brightness level.
+ */
+
+/**
+ * Character set configuration
+ */
+export interface CharacterSet {
+  /** Unique identifier for the character set */
+  name: string;
+  /** Description of the set's aesthetic */
+  description: string;
+  /** Characters ordered from lightest (space) to darkest */
+  characters: string;
+  /** Recommended use cases */
+  bestFor: string[];
+}
+
+/**
+ * Standard character sets for ASCII rendering
+ */
+export const CHARACTER_SETS: Record<string, CharacterSet> = {
+  standard: {
+    name: 'Standard',
+    description: 'Classic ASCII art character set',
+    characters: ' .:-=+*#%@',
+    bestFor: ['general', 'images', 'patterns'],
+  },
+
+  dense: {
+    name: 'Dense',
+    description: 'High detail character set with many gradations',
+    characters: " .'`^\",:;Il!i><~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$",
+    bestFor: ['detailed images', 'portraits', 'high contrast'],
+  },
+
+  minimal: {
+    name: 'Minimal',
+    description: 'Clean and simple with few characters',
+    characters: ' .:*#',
+    bestFor: ['backgrounds', 'subtle effects', 'clean aesthetic'],
+  },
+
+  grove: {
+    name: 'Grove',
+    description: 'Organic, soft characters inspired by nature',
+    characters: ' ·∙•◦○◉●',
+    bestFor: ['organic patterns', 'soft backgrounds', 'nature themes'],
+  },
+
+  dots: {
+    name: 'Dots',
+    description: 'Braille-like dot patterns',
+    characters: ' ⋅∘∙●',
+    bestFor: ['stipple effects', 'pointillism', 'dotted textures'],
+  },
+
+  blocks: {
+    name: 'Blocks',
+    description: 'Block-based characters for sharp edges',
+    characters: ' ░▒▓█',
+    bestFor: ['retro effects', 'pixel art', 'bold patterns'],
+  },
+
+  lines: {
+    name: 'Lines',
+    description: 'Line-based characters for directional effects',
+    characters: ' -─═╌│┃',
+    bestFor: ['rain effects', 'streaks', 'motion blur'],
+  },
+
+  stars: {
+    name: 'Stars',
+    description: 'Star and sparkle characters',
+    characters: ' ·✧✦✫✬✯★',
+    bestFor: ['sparkle effects', 'night sky', 'magical themes'],
+  },
+
+  nature: {
+    name: 'Nature',
+    description: 'Nature-themed decorative characters',
+    characters: ' .~≈∿⌇☘',
+    bestFor: ['decorative', 'themed effects', 'organic patterns'],
+  },
+
+  weather: {
+    name: 'Weather',
+    description: 'Weather-related symbols',
+    characters: ' ·.:*❄❅❆',
+    bestFor: ['snow effects', 'weather simulations', 'seasonal themes'],
+  },
+
+  binary: {
+    name: 'Binary',
+    description: 'Digital-style binary characters',
+    characters: ' 01',
+    bestFor: ['digital effects', 'matrix style', 'tech themes'],
+  },
+
+  math: {
+    name: 'Math',
+    description: 'Mathematical symbols',
+    characters: ' +-×÷=≠≈∞',
+    bestFor: ['abstract patterns', 'tech themes', 'decorative'],
+  },
+};
+
+/**
+ * Get a character set by name
+ */
+export function getCharacterSet(name: string): CharacterSet | undefined {
+  return CHARACTER_SETS[name];
+}
+
+/**
+ * Get just the characters string from a named set
+ */
+export function getCharacters(name: string): string {
+  return CHARACTER_SETS[name]?.characters || CHARACTER_SETS.standard.characters;
+}
+
+/**
+ * List all available character set names
+ */
+export function getCharacterSetNames(): string[] {
+  return Object.keys(CHARACTER_SETS);
+}
+
+/**
+ * Create a custom character set
+ */
+export function createCharacterSet(
+  name: string,
+  characters: string,
+  description: string = '',
+  bestFor: string[] = []
+): CharacterSet {
+  return {
+    name,
+    description,
+    characters,
+    bestFor,
+  };
+}
+
+/**
+ * Validate that a character string is suitable for ASCII rendering
+ * (should start with space and have at least 2 characters)
+ */
+export function validateCharacterSet(characters: string): boolean {
+  if (characters.length < 2) return false;
+  if (characters[0] !== ' ') return false;
+  return true;
+}
+
+/**
+ * Reverse a character set (for inverted brightness mapping)
+ */
+export function invertCharacters(characters: string): string {
+  return characters.split('').reverse().join('');
+}

package/src/index.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for core index functions
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  calculateBrightness,
+  brightnessToChar,
+  DEFAULT_CHARACTERS,
+  DEFAULT_CONFIG,
+  VERSION,
+} from './index';
+
+describe('calculateBrightness', () => {
+  it('should return 0 for black', () => {
+    expect(calculateBrightness(0, 0, 0)).toBe(0);
+  });
+
+  it('should return 255 for white', () => {
+    expect(calculateBrightness(255, 255, 255)).toBeCloseTo(255, 5);
+  });
+
+  it('should weight green highest', () => {
+    // Green contributes 0.72, so pure green should be brighter than pure red
+    const greenBrightness = calculateBrightness(0, 255, 0);
+    const redBrightness = calculateBrightness(255, 0, 0);
+    const blueBrightness = calculateBrightness(0, 0, 255);
+
+    expect(greenBrightness).toBeGreaterThan(redBrightness);
+    expect(greenBrightness).toBeGreaterThan(blueBrightness);
+    expect(redBrightness).toBeGreaterThan(blueBrightness);
+  });
+
+  it('should calculate correct luminance values', () => {
+    // Pure red: 0.21 * 255 = 53.55
+    expect(calculateBrightness(255, 0, 0)).toBeCloseTo(53.55, 1);
+    // Pure green: 0.72 * 255 = 183.6
+    expect(calculateBrightness(0, 255, 0)).toBeCloseTo(183.6, 1);
+    // Pure blue: 0.07 * 255 = 17.85
+    expect(calculateBrightness(0, 0, 255)).toBeCloseTo(17.85, 1);
+  });
+
+  it('should handle mid-gray', () => {
+    const gray = calculateBrightness(128, 128, 128);
+    // 128 * (0.21 + 0.72 + 0.07) = 128
+    expect(gray).toBe(128);
+  });
+});
+
+describe('brightnessToChar', () => {
+  it('should return space for brightness 0', () => {
+    expect(brightnessToChar(0)).toBe(' ');
+  });
+
+  it('should return last character for brightness 255', () => {
+    expect(brightnessToChar(255)).toBe('@');
+  });
+
+  it('should map mid-brightness to middle character', () => {
+    // With ' .:-=+*#%@' (10 chars), brightness 127-128 should be around index 4-5
+    const char = brightnessToChar(127);
+    expect(['=', '+'].includes(char)).toBe(true);
+  });
+
+  it('should use custom character set', () => {
+    const customSet = ' abc';
+    expect(brightnessToChar(0, customSet)).toBe(' ');
+    expect(brightnessToChar(255, customSet)).toBe('c');
+  });
+
+  it('should handle two-character set', () => {
+    const binarySet = ' #';
+    expect(brightnessToChar(0, binarySet)).toBe(' ');
+    expect(brightnessToChar(127, binarySet)).toBe(' ');
+    expect(brightnessToChar(255, binarySet)).toBe('#');
+  });
+
+  it('should clamp to valid range', () => {
+    // Even with extreme values, should not crash
+    expect(() => brightnessToChar(-10)).not.toThrow();
+    expect(() => brightnessToChar(300)).not.toThrow();
+  });
+});
+
+describe('DEFAULT_CHARACTERS', () => {
+  it('should be standard ASCII art character set', () => {
+    expect(DEFAULT_CHARACTERS).toBe(' .:-=+*#%@');
+  });
+
+  it('should start with space', () => {
+    expect(DEFAULT_CHARACTERS[0]).toBe(' ');
+  });
+
+  it('should have 10 characters', () => {
+    expect(DEFAULT_CHARACTERS.length).toBe(10);
+  });
+});
+
+describe('DEFAULT_CONFIG', () => {
+  it('should have all required properties', () => {
+    expect(DEFAULT_CONFIG.characters).toBe(DEFAULT_CHARACTERS);
+    expect(DEFAULT_CONFIG.cellWidth).toBe(8);
+    expect(DEFAULT_CONFIG.cellHeight).toBe(12);
+    expect(DEFAULT_CONFIG.color).toBe('#ffffff');
+    expect(DEFAULT_CONFIG.backgroundColor).toBe('');
+    expect(DEFAULT_CONFIG.fontFamily).toBe('monospace');
+    expect(DEFAULT_CONFIG.animate).toBe(false);
+    expect(DEFAULT_CONFIG.fps).toBe(30);
+  });
+});
+
+describe('VERSION', () => {
+  it('should be a semver string', () => {
+    expect(VERSION).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+});