feat: Integrate adaptive performance system with GPUComposer

[CripterHack]

Summary

This PR integrates an adaptive performance system into GPU-IO via GPUComposer, providing automatic quality tuning based on device capabilities and real-time FPS. It introduces an opt-in autoPerformanceProfile option, quality presets, and a small set of public APIs for manual control. Backward compatibility is preserved.

Key Features

• Automatic initial quality selection (device detection, reduced-motion, data-saver)
• Real-time FPS monitoring with automatic quality upgrade/downgrade
• Four quality presets (high, medium, low, minimal) with tuned budgets
• Opt-in via autoPerformanceProfile (boolean or options)
• Manual control: setQualityPreset, getCurrentQualityPreset, resetPerformanceConfig
• Debug support: setPerformanceDebugLogging, debugLogging option

Implementation Details

Core Modules

• src/performance/autoProfile.ts

  • QUALITY_PRESETS and QUALITY_SEQUENCE
  • detectQualityProfile(capabilities) for initial preset selection
  • translatePresetToConfig(preset) mapping preset → runtime config
  • Environment hooks: reduced-motion and connection monitoring

• src/PerformanceAdapter.ts

  • Bridges quality presets to composer performance config
  • Stores original config; supports reset and current preset access
  • Provides applyPreset() and applyQualityPreset() utilities

• src/GPUComposer.ts

  • Adds autoPerformanceProfile option to the constructor
  • Initializes _autoProfileOptions and _performanceAdapter when enabled
  • Extends tick() to monitor FPS and adjust quality:
    • Target FPS defaults to 60 (configurable via autoPerformanceProfile.targetFPS)
    • Downgrade when fps < targetFPS * 0.8
    • Upgrade when fps > targetFPS * 1.2 (checked less frequently: every 120 ticks)
  • Public APIs:
    • setQualityPreset(presetId)
    • getCurrentQualityPreset() → returns QualityPreset | null
    • resetPerformanceConfig() → revert to original
    • setPerformanceDebugLogging(enabled)
  • Cleans _debugPerformance in dispose()

Quality Presets

Presets are tuned for fluid simulation defaults and include a frame budget:

• high: frameBudget: 22ms, particle-heavy, 3 render passes
• medium: frameBudget: 28ms, balanced, 2 passes
• low: frameBudget: 32ms, performance-focused, 1 pass
• minimal: frameBudget: 36ms, maximal performance, 1 pass

Exact fields are defined in QualityPreset and translated via translatePresetToConfig().

Default Behavior

• Disabled by default; existing apps work unchanged
• When autoPerformanceProfile is enabled:
  • If profileId is provided, the initial preset uses that value
  • Otherwise, a preset is detected via detectQualityProfile() (considers WebGL2, memory, cores, DPI, reduced-motion, data-saver)
  • tick() publishes metrics and performs upgrades/downgrades using 20% thresholds

Usage Examples

// Enable with defaults
const composer = new GPUComposer({
  canvas,
  autoPerformanceProfile: true,
});

// Advanced options
const composer = new GPUComposer({
  canvas,
  autoPerformanceProfile: {
    targetFPS: 60,
    profileId: 'medium',
    debugLogging: true,
    onPerformanceUpdate: ({ fps, numTicks }) => {
      console.log(`FPS: ${fps} ticks: ${numTicks}`);
    },
    onCanvasResize: (w, h) => console.log(`Canvas: ${w}x${h}`),
    onRequestDowngrade: (id) => console.log(`Quality → ${id}`),
  },
});

// Manual runtime control
composer.setQualityPreset('low');
const current = composer.getCurrentQualityPreset();
composer.resetPerformanceConfig();
composer.setPerformanceDebugLogging(true);

Tests & Docs

• Tests: tests/mocha/performanceAutoProfile.js exercises detection, thresholds, and APIs
• Karma: karma.conf.js adds ChromeLowSpec/ChromeHighSpec launchers for performance scenarios
• Docs: docs/auto_profile_usage_guide.md with code samples and behavior details
• Examples: examples/auto-performance/ interactive demo (FPS, current preset, manual overrides)

Browser & Accessibility

• Respects prefers-reduced-motion (auto-selects minimal, can be overridden with profileId)
• Monitors navigator.connection.saveData to request downgrades via callback

Backward Compatibility

• Opt-in; default constructor behavior unchanged
• No breaking changes to existing public APIs
• Debug logging and performance hooks are optional

Verification Checklist

• Build succeeds (pnpm build)
• Tests pass for auto-profile suite
• Example runs and demonstrates auto-tuning behavior
• API docs and usage guide updated

Future Work

• Tighten integration: directly apply performance config to internal programs/layers
• Configurable upgrade cadence and hysteresis
• Additional metrics (GPU timing, dropped frames)

[CripterHack]

@amandaghassaei
Please review this PR that adds adaptive performance with tests and fixes for the previous existing issues.

[amandaghassaei]

This sounds really cool, thanks so much for the contribution! It's going to take me a few weeks to get some time to properly check this out, but I will get that done before the end of the year. Thanks again! - Amanda