@autumnsgrove/gossamer 0.0.1 → 0.1.0

package/src/utils/image.ts

@@ -0,0 +1,275 @@
+/**
+ * Image Utilities
+ *
+ * Image loading, processing, and pixel manipulation for ASCII conversion.
+ */
+
+/**
+ * Image loading options
+ */
+export interface ImageLoadOptions {
+  /** Cross-origin setting for external images */
+  crossOrigin?: 'anonymous' | 'use-credentials' | '';
+  /** Maximum width to scale image to */
+  maxWidth?: number;
+  /** Maximum height to scale image to */
+  maxHeight?: number;
+  /** Whether to preserve aspect ratio when scaling */
+  preserveAspectRatio?: boolean;
+}
+
+/**
+ * Load an image from a URL
+ */
+export function loadImage(src: string, options: ImageLoadOptions = {}): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+
+    if (options.crossOrigin !== undefined) {
+      img.crossOrigin = options.crossOrigin;
+    }
+
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error(`Failed to load image: ${src}`));
+
+    img.src = src;
+  });
+}
+
+/**
+ * Load and scale an image to fit within bounds
+ */
+export async function loadAndScaleImage(
+  src: string,
+  maxWidth: number,
+  maxHeight: number,
+  options: ImageLoadOptions = {}
+): Promise<{ image: HTMLImageElement; width: number; height: number }> {
+  const img = await loadImage(src, options);
+
+  let width = img.naturalWidth;
+  let height = img.naturalHeight;
+
+  // Scale down if needed
+  if (width > maxWidth || height > maxHeight) {
+    const widthRatio = maxWidth / width;
+    const heightRatio = maxHeight / height;
+    const scale = Math.min(widthRatio, heightRatio);
+
+    width = Math.floor(width * scale);
+    height = Math.floor(height * scale);
+  }
+
+  return { image: img, width, height };
+}
+
+/**
+ * Draw an image to a canvas and get its pixel data
+ */
+export function imageToPixelData(
+  image: HTMLImageElement | HTMLCanvasElement | ImageBitmap,
+  width?: number,
+  height?: number
+): ImageData {
+  const w = width ?? (image instanceof HTMLImageElement ? image.naturalWidth : image.width);
+  const h = height ?? (image instanceof HTMLImageElement ? image.naturalHeight : image.height);
+
+  const canvas = document.createElement('canvas');
+  canvas.width = w;
+  canvas.height = h;
+
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Failed to get 2D context');
+  }
+
+  ctx.drawImage(image, 0, 0, w, h);
+  return ctx.getImageData(0, 0, w, h);
+}
+
+/**
+ * Extract brightness values from image data
+ */
+export function extractBrightness(
+  imageData: ImageData,
+  brightnessFunction: (r: number, g: number, b: number) => number = (r, g, b) => 0.21 * r + 0.72 * g + 0.07 * b
+): number[] {
+  const { data, width, height } = imageData;
+  const brightness: number[] = new Array(width * height);
+
+  for (let i = 0; i < data.length; i += 4) {
+    brightness[i / 4] = brightnessFunction(data[i], data[i + 1], data[i + 2]);
+  }
+
+  return brightness;
+}
+
+/**
+ * Sample image data at cell-based intervals
+ */
+export function sampleImageCells(
+  imageData: ImageData,
+  cellWidth: number,
+  cellHeight: number,
+  brightnessFunction: (r: number, g: number, b: number) => number = (r, g, b) => 0.21 * r + 0.72 * g + 0.07 * b
+): { brightness: number; color: string }[][] {
+  const { data, width, height } = imageData;
+  const cols = Math.ceil(width / cellWidth);
+  const rows = Math.ceil(height / cellHeight);
+
+  const result: { brightness: number; color: string }[][] = [];
+
+  for (let row = 0; row < rows; row++) {
+    result[row] = [];
+
+    for (let col = 0; col < cols; col++) {
+      const cellData = sampleCell(data, width, col * cellWidth, row * cellHeight, cellWidth, cellHeight);
+      const brightness = brightnessFunction(cellData.r, cellData.g, cellData.b);
+
+      result[row][col] = {
+        brightness,
+        color: `rgb(${Math.round(cellData.r)}, ${Math.round(cellData.g)}, ${Math.round(cellData.b)})`,
+      };
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Sample average color from a cell region
+ */
+function sampleCell(
+  data: Uint8ClampedArray,
+  imageWidth: number,
+  startX: number,
+  startY: number,
+  cellWidth: number,
+  cellHeight: number
+): { r: number; g: number; b: number; a: number } {
+  let totalR = 0;
+  let totalG = 0;
+  let totalB = 0;
+  let totalA = 0;
+  let count = 0;
+
+  for (let y = startY; y < startY + cellHeight; y++) {
+    for (let x = startX; x < startX + cellWidth; x++) {
+      const px = (y * imageWidth + x) * 4;
+
+      if (px >= 0 && px + 3 < data.length) {
+        totalR += data[px];
+        totalG += data[px + 1];
+        totalB += data[px + 2];
+        totalA += data[px + 3];
+        count++;
+      }
+    }
+  }
+
+  if (count === 0) {
+    return { r: 0, g: 0, b: 0, a: 0 };
+  }
+
+  return {
+    r: totalR / count,
+    g: totalG / count,
+    b: totalB / count,
+    a: totalA / count,
+  };
+}
+
+/**
+ * Convert RGB to hex color string
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+  const toHex = (n: number) =>
+    Math.max(0, Math.min(255, Math.round(n)))
+      .toString(16)
+      .padStart(2, '0');
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+/**
+ * Convert hex color to RGB
+ */
+export function hexToRgb(hex: string): { r: number; g: number; b: number } | null {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result
+    ? {
+        r: parseInt(result[1], 16),
+        g: parseInt(result[2], 16),
+        b: parseInt(result[3], 16),
+      }
+    : null;
+}
+
+/**
+ * Adjust image brightness
+ */
+export function adjustBrightness(imageData: ImageData, amount: number): ImageData {
+  const { data, width, height } = imageData;
+  const adjusted = new Uint8ClampedArray(data.length);
+
+  for (let i = 0; i < data.length; i += 4) {
+    adjusted[i] = Math.min(255, Math.max(0, data[i] + amount));
+    adjusted[i + 1] = Math.min(255, Math.max(0, data[i + 1] + amount));
+    adjusted[i + 2] = Math.min(255, Math.max(0, data[i + 2] + amount));
+    adjusted[i + 3] = data[i + 3];
+  }
+
+  return new ImageData(adjusted, width, height);
+}
+
+/**
+ * Adjust image contrast
+ */
+export function adjustContrast(imageData: ImageData, amount: number): ImageData {
+  const { data, width, height } = imageData;
+  const adjusted = new Uint8ClampedArray(data.length);
+  const factor = (259 * (amount + 255)) / (255 * (259 - amount));
+
+  for (let i = 0; i < data.length; i += 4) {
+    adjusted[i] = Math.min(255, Math.max(0, factor * (data[i] - 128) + 128));
+    adjusted[i + 1] = Math.min(255, Math.max(0, factor * (data[i + 1] - 128) + 128));
+    adjusted[i + 2] = Math.min(255, Math.max(0, factor * (data[i + 2] - 128) + 128));
+    adjusted[i + 3] = data[i + 3];
+  }
+
+  return new ImageData(adjusted, width, height);
+}
+
+/**
+ * Invert image colors
+ */
+export function invertColors(imageData: ImageData): ImageData {
+  const { data, width, height } = imageData;
+  const inverted = new Uint8ClampedArray(data.length);
+
+  for (let i = 0; i < data.length; i += 4) {
+    inverted[i] = 255 - data[i];
+    inverted[i + 1] = 255 - data[i + 1];
+    inverted[i + 2] = 255 - data[i + 2];
+    inverted[i + 3] = data[i + 3];
+  }
+
+  return new ImageData(inverted, width, height);
+}
+
+/**
+ * Convert image to grayscale
+ */
+export function toGrayscale(imageData: ImageData): ImageData {
+  const { data, width, height } = imageData;
+  const grayscale = new Uint8ClampedArray(data.length);
+
+  for (let i = 0; i < data.length; i += 4) {
+    const gray = 0.21 * data[i] + 0.72 * data[i + 1] + 0.07 * data[i + 2];
+    grayscale[i] = gray;
+    grayscale[i + 1] = gray;
+    grayscale[i + 2] = gray;
+    grayscale[i + 3] = data[i + 3];
+  }
+
+  return new ImageData(grayscale, width, height);
+}

package/src/utils/performance.ts

@@ -0,0 +1,282 @@
+/**
+ * Performance Utilities
+ *
+ * Visibility detection, resource management, and optimization helpers.
+ */
+
+/**
+ * Visibility observer callback type
+ */
+export type VisibilityCallback = (isVisible: boolean, entry: IntersectionObserverEntry) => void;
+
+/**
+ * Create an IntersectionObserver for visibility-based animation control
+ *
+ * @param element - Element to observe
+ * @param callback - Called when visibility changes
+ * @param threshold - Visibility threshold (0-1, default: 0.1)
+ * @returns Cleanup function to disconnect observer
+ */
+export function createVisibilityObserver(
+  element: Element,
+  callback: VisibilityCallback,
+  threshold: number = 0.1
+): () => void {
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        callback(entry.isIntersecting, entry);
+      }
+    },
+    { threshold }
+  );
+
+  observer.observe(element);
+
+  return () => {
+    observer.disconnect();
+  };
+}
+
+/**
+ * Create a ResizeObserver for responsive canvas sizing
+ *
+ * @param element - Element to observe
+ * @param callback - Called on resize with new dimensions
+ * @param debounceMs - Debounce delay in ms (default: 100)
+ * @returns Cleanup function to disconnect observer
+ */
+export function createResizeObserver(
+  element: Element,
+  callback: (width: number, height: number, entry: ResizeObserverEntry) => void,
+  debounceMs: number = 100
+): () => void {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+
+  const observer = new ResizeObserver((entries) => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+
+    timeout = setTimeout(() => {
+      const entry = entries[0];
+      if (entry) {
+        const { width, height } = entry.contentRect;
+        callback(width, height, entry);
+      }
+    }, debounceMs);
+  });
+
+  observer.observe(element);
+
+  return () => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    observer.disconnect();
+  };
+}
+
+/**
+ * Check if the user prefers reduced motion
+ */
+export function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined') return false;
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * Create a listener for reduced motion preference changes
+ *
+ * @param callback - Called when preference changes
+ * @returns Cleanup function to remove listener
+ */
+export function onReducedMotionChange(callback: (prefersReduced: boolean) => void): () => void {
+  if (typeof window === 'undefined') {
+    return () => {};
+  }
+
+  const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+  const handler = (event: MediaQueryListEvent) => {
+    callback(event.matches);
+  };
+
+  mediaQuery.addEventListener('change', handler);
+
+  // Call immediately with current value
+  callback(mediaQuery.matches);
+
+  return () => {
+    mediaQuery.removeEventListener('change', handler);
+  };
+}
+
+/**
+ * Check if the browser is in a low-power mode or has reduced capabilities
+ */
+export function isLowPowerMode(): boolean {
+  // Check for battery API (if available)
+  if (typeof navigator !== 'undefined' && 'getBattery' in navigator) {
+    // Battery API is async, so this is a simplified check
+    // Real implementation would need to be async
+    return false;
+  }
+
+  // Fallback: check for hardware concurrency
+  if (typeof navigator !== 'undefined' && navigator.hardwareConcurrency) {
+    return navigator.hardwareConcurrency <= 2;
+  }
+
+  return false;
+}
+
+/**
+ * Get recommended FPS based on device capabilities
+ */
+export function getRecommendedFPS(): number {
+  if (prefersReducedMotion()) {
+    return 0; // No animation
+  }
+
+  if (isLowPowerMode()) {
+    return 15; // Low power mode
+  }
+
+  // Default for capable devices
+  return 30;
+}
+
+/**
+ * Performance monitoring for debugging
+ */
+export interface PerformanceMetrics {
+  fps: number;
+  frameTime: number;
+  droppedFrames: number;
+}
+
+/**
+ * Create a simple FPS counter
+ */
+export function createFPSCounter(): {
+  tick: () => void;
+  getFPS: () => number;
+  getMetrics: () => PerformanceMetrics;
+  reset: () => void;
+} {
+  const frameTimes: number[] = [];
+  const maxSamples = 60;
+  let droppedFrames = 0;
+  let lastFrameTime = performance.now();
+
+  function tick(): void {
+    const now = performance.now();
+    const delta = now - lastFrameTime;
+    lastFrameTime = now;
+
+    frameTimes.push(now);
+
+    if (frameTimes.length > maxSamples) {
+      frameTimes.shift();
+    }
+
+    // Count dropped frames (assuming 60fps target, frames taking >20ms are "dropped")
+    if (delta > 20) {
+      droppedFrames += Math.floor(delta / 16.67) - 1;
+    }
+  }
+
+  function getFPS(): number {
+    if (frameTimes.length < 2) return 0;
+
+    const oldest = frameTimes[0];
+    const newest = frameTimes[frameTimes.length - 1];
+    const elapsed = newest - oldest;
+
+    if (elapsed === 0) return 0;
+
+    return ((frameTimes.length - 1) / elapsed) * 1000;
+  }
+
+  function getMetrics(): PerformanceMetrics {
+    const fps = getFPS();
+    const frameTime = fps > 0 ? 1000 / fps : 0;
+
+    return {
+      fps: Math.round(fps * 10) / 10,
+      frameTime: Math.round(frameTime * 100) / 100,
+      droppedFrames,
+    };
+  }
+
+  function reset(): void {
+    frameTimes.length = 0;
+    droppedFrames = 0;
+    lastFrameTime = performance.now();
+  }
+
+  return { tick, getFPS, getMetrics, reset };
+}
+
+/**
+ * Request idle callback with fallback
+ */
+export function requestIdleCallback(
+  callback: () => void,
+  options?: { timeout?: number }
+): number {
+  // Use globalThis for cross-environment compatibility
+  const global = globalThis as typeof globalThis & {
+    requestIdleCallback?: typeof window.requestIdleCallback;
+    setTimeout: typeof setTimeout;
+  };
+
+  if (typeof global.requestIdleCallback === 'function') {
+    return global.requestIdleCallback(callback, options);
+  }
+
+  // Fallback using setTimeout
+  return global.setTimeout(callback, options?.timeout ?? 1) as unknown as number;
+}
+
+/**
+ * Cancel idle callback with fallback
+ */
+export function cancelIdleCallback(id: number): void {
+  // Use globalThis for cross-environment compatibility
+  const global = globalThis as typeof globalThis & {
+    cancelIdleCallback?: typeof window.cancelIdleCallback;
+    clearTimeout: typeof clearTimeout;
+  };
+
+  if (typeof global.cancelIdleCallback === 'function') {
+    global.cancelIdleCallback(id);
+  } else {
+    global.clearTimeout(id);
+  }
+}
+
+/**
+ * Check if we're running in a browser environment
+ */
+export function isBrowser(): boolean {
+  return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
+/**
+ * Check if Canvas is supported
+ */
+export function isCanvasSupported(): boolean {
+  if (!isBrowser()) return false;
+
+  const canvas = document.createElement('canvas');
+  return !!(canvas.getContext && canvas.getContext('2d'));
+}
+
+/**
+ * Check if OffscreenCanvas is supported
+ */
+export function isOffscreenCanvasSupported(): boolean {
+  return typeof OffscreenCanvas !== 'undefined';
+}