@autumnsgrove/gossamer 0.0.1 → 0.1.1

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,219 @@
+/**
+ * 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'],
+  },
+
+  // ==========================================================================
+  // GLASS-OPTIMIZED CHARACTER SETS
+  // Designed for subtle overlays on Glass components
+  // More characters = more visible gradations
+  // ==========================================================================
+
+  'glass-dots': {
+    name: 'Glass Dots',
+    description: 'Soft dot gradations for glass overlays',
+    characters: ' ·∘∙○•●',
+    bestFor: ['glass overlays', 'subtle backgrounds', 'mist effects'],
+  },
+
+  'glass-mist': {
+    name: 'Glass Mist',
+    description: 'Ethereal mist effect for glass',
+    characters: ' .·∙•◦○◉●',
+    bestFor: ['glass overlays', 'fog effects', 'ambient backgrounds'],
+  },
+
+  'glass-dust': {
+    name: 'Glass Dust',
+    description: 'Floating dust particles',
+    characters: ' ˙·∘°•◦○',
+    bestFor: ['glass overlays', 'particle effects', 'light scatter'],
+  },
+
+  'glass-soft': {
+    name: 'Glass Soft',
+    description: 'Soft block gradations for glass',
+    characters: ' ·░▒▓',
+    bestFor: ['glass overlays', 'soft gradients', 'frosted effect'],
+  },
+
+  'glass-sparkle': {
+    name: 'Glass Sparkle',
+    description: 'Subtle sparkles for glass',
+    characters: ' ·.✧✦✫★',
+    bestFor: ['glass overlays', 'highlight effects', 'magical themes'],
+  },
+
+  'glass-wave': {
+    name: 'Glass Wave',
+    description: 'Flowing wave patterns for glass',
+    characters: ' .~∼≈≋',
+    bestFor: ['glass overlays', 'water effects', 'flowing motion'],
+  },
+
+  'glass-organic': {
+    name: 'Glass Organic',
+    description: 'Natural, organic feel for glass',
+    characters: ' .·:;∘○◦•●',
+    bestFor: ['glass overlays', 'nature themes', 'grove aesthetic'],
+  },
+};
+
+/**
+ * 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('');
+}