feat: implement Phase 5.1 media processing foundation

  - Add MediaProcessor class with lazy WASM loading
  - Implement WASM module wrapper with memory management
  - Create Canvas-based fallback for browsers without WASM
  - Add browser compatibility detection and strategy selection
  - Include comprehensive type definitions for media processing
  - Add 70 tests covering all media processing modules

  Part of Enhanced S5.js grant Phase 5: Media Processing Foundation

Author: julesl23

src/index.ts

@@ -11,17 +11,22 @@ export { JSCryptoImplementation } from './api/crypto/js.js';
 export { DirectoryWalker } from './fs/utils/walker.js';
 export { BatchOperations } from './fs/utils/batch.js';
 
+// Export media processing classes
+export { MediaProcessor } from './media/index.js';
+export { CanvasMetadataExtractor } from './media/fallback/canvas.js';
+export { WASMModule } from './media/wasm/module.js';
+
 // Export types
-export type { 
-  DirV1, 
-  FileRef, 
-  DirRef, 
+export type {
+  DirV1,
+  FileRef,
+  DirRef,
   DirLink,
   PutOptions,
   GetOptions,
   ListOptions,
   ListResult,
-  CursorData 
+  CursorData
 } from './fs/dirv1/types.js';
 
 // Export utility types
@@ -35,4 +40,12 @@ export type {
   BatchOptions,
   BatchProgress,
   BatchResult
-} from './fs/utils/batch.js';
+} from './fs/utils/batch.js';
+
+// Export media types
+export type {
+  ImageMetadata,
+  MediaOptions,
+  InitializeOptions,
+  ImageFormat
+} from './media/types.js';

src/media/compat/browser.ts

@@ -0,0 +1,236 @@
+/**
+ * Browser compatibility detection and strategy selection
+ */
+export class BrowserCompatibility {
+  /**
+   * Check if WebAssembly is supported
+   */
+  static hasWebAssembly(): boolean {
+    return typeof WebAssembly !== 'undefined' &&
+           typeof WebAssembly.compile === 'function' &&
+           typeof WebAssembly.instantiate === 'function';
+  }
+
+  /**
+   * Check if Canvas API is supported
+   */
+  static hasCanvas(): boolean {
+    if (typeof document === 'undefined') {
+      return false;
+    }
+
+    try {
+      const canvas = document.createElement('canvas');
+      const ctx = canvas.getContext('2d');
+      return ctx !== null;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if Image constructor is available
+   */
+  static hasImage(): boolean {
+    return typeof Image !== 'undefined';
+  }
+
+  /**
+   * Check if Blob is supported
+   */
+  static hasBlob(): boolean {
+    return typeof Blob !== 'undefined';
+  }
+
+  /**
+   * Check if URL.createObjectURL is supported
+   */
+  static hasObjectURL(): boolean {
+    return typeof URL !== 'undefined' &&
+           typeof URL.createObjectURL === 'function' &&
+           typeof URL.revokeObjectURL === 'function';
+  }
+
+  /**
+   * Select the best strategy based on capabilities
+   */
+  static selectStrategy(options: {
+    hasWebAssembly?: boolean;
+    hasCanvas?: boolean;
+    hasImage?: boolean;
+    preferredStrategy?: 'wasm' | 'canvas' | 'basic' | 'none';
+  }): 'wasm' | 'canvas' | 'basic' | 'none' {
+    const {
+      hasWebAssembly = this.hasWebAssembly(),
+      hasCanvas = this.hasCanvas(),
+      hasImage = this.hasImage(),
+      preferredStrategy
+    } = options;
+
+    // If a preferred strategy is specified and available, use it
+    if (preferredStrategy) {
+      switch (preferredStrategy) {
+        case 'wasm':
+          if (hasWebAssembly) return 'wasm';
+          break;
+        case 'canvas':
+          if (hasCanvas && hasImage) return 'canvas';
+          break;
+        case 'basic':
+          if (hasImage) return 'basic';
+          break;
+        case 'none':
+          return 'none';
+      }
+    }
+
+    // Auto-select based on capabilities
+    if (hasWebAssembly) {
+      return 'wasm';
+    } else if (hasCanvas && hasImage) {
+      return 'canvas';
+    } else if (hasImage) {
+      return 'basic';
+    } else {
+      return 'none';
+    }
+  }
+
+  /**
+   * Get comprehensive capability report
+   */
+  static checkCapabilities(): CapabilityReport {
+    const hasWebAssembly = this.hasWebAssembly();
+    const hasCanvas = this.hasCanvas();
+    const hasImage = this.hasImage();
+    const hasBlob = this.hasBlob();
+    const hasObjectURL = this.hasObjectURL();
+
+    const recommendedStrategy = this.selectStrategy({
+      hasWebAssembly,
+      hasCanvas,
+      hasImage
+    });
+
+    return {
+      hasWebAssembly,
+      hasCanvas,
+      hasImage,
+      hasBlob,
+      hasObjectURL,
+      recommendedStrategy
+    };
+  }
+
+  /**
+   * Detect browser type
+   */
+  static detectBrowser(): BrowserType {
+    // Check if we're in Node.js
+    if (typeof window === 'undefined' && typeof process !== 'undefined') {
+      return 'node';
+    }
+
+    // Check for browser-specific features
+    const userAgent = typeof navigator !== 'undefined' ? navigator.userAgent : '';
+
+    if (userAgent.includes('Chrome') && !userAgent.includes('Edg')) {
+      return 'chrome';
+    } else if (userAgent.includes('Firefox')) {
+      return 'firefox';
+    } else if (userAgent.includes('Safari') && !userAgent.includes('Chrome')) {
+      return 'safari';
+    } else if (userAgent.includes('Edg')) {
+      return 'edge';
+    } else {
+      return 'unknown';
+    }
+  }
+
+  /**
+   * Get browser-specific recommendations
+   */
+  static getRecommendations(): string[] {
+    const browser = this.detectBrowser();
+    const capabilities = this.checkCapabilities();
+    const recommendations: string[] = [];
+
+    // General recommendations
+    if (!capabilities.hasWebAssembly) {
+      recommendations.push('WebAssembly not supported. Using Canvas fallback for image processing.');
+    }
+
+    if (!capabilities.hasCanvas) {
+      recommendations.push('Canvas API not available. Limited image processing capabilities.');
+    }
+
+    // Browser-specific recommendations
+    switch (browser) {
+      case 'safari':
+        recommendations.push('Safari detected. Some WASM features may have reduced performance.');
+        break;
+      case 'firefox':
+        recommendations.push('Firefox detected. Optimal WASM performance available.');
+        break;
+      case 'chrome':
+      case 'edge':
+        recommendations.push('Chromium-based browser detected. All features supported.');
+        break;
+      case 'node':
+        recommendations.push('Node.js environment detected. Limited image processing without Canvas libraries.');
+        break;
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Get performance hints based on capabilities
+   */
+  static getPerformanceHints(options?: {
+    hasWebAssembly?: boolean;
+    hasCanvas?: boolean;
+  }): PerformanceHints {
+    const capabilities = options || this.checkCapabilities();
+
+    return {
+      useWASM: capabilities.hasWebAssembly ?? false,
+      maxImageSize: capabilities.hasWebAssembly
+        ? 50 * 1024 * 1024  // 50MB with WASM
+        : 10 * 1024 * 1024, // 10MB with Canvas
+      cacheStrategy: capabilities.hasWebAssembly ? 'aggressive' : 'conservative',
+      parallelProcessing: capabilities.hasWebAssembly,
+      preferredFormats: capabilities.hasWebAssembly
+        ? ['webp', 'jpeg', 'png']
+        : ['jpeg', 'png']
+    };
+  }
+}
+
+/**
+ * Browser type enumeration
+ */
+export type BrowserType = 'chrome' | 'firefox' | 'safari' | 'edge' | 'node' | 'unknown';
+
+/**
+ * Capability report interface
+ */
+export interface CapabilityReport {
+  hasWebAssembly: boolean;
+  hasCanvas: boolean;
+  hasImage: boolean;
+  hasBlob: boolean;
+  hasObjectURL: boolean;
+  recommendedStrategy: 'wasm' | 'canvas' | 'basic' | 'none';
+}
+
+/**
+ * Performance hints interface
+ */
+export interface PerformanceHints {
+  useWASM: boolean;
+  maxImageSize: number;
+  cacheStrategy: 'aggressive' | 'conservative';
+  parallelProcessing?: boolean;
+  preferredFormats?: string[];
+}