PixelPilot uiux-ambient-awareness.instructions.md

Ambient Awareness

Great apps adapt to their environment. This file covers battery-aware UI, light sensor theming, network-adaptive loading, and respecting device context. The difference between "feels native" and "feels like a website."

---

CRITICAL RULES

1. Progressive enhancement — These are optimizations, not requirements.
2. Respect privacy — Never use sensors for tracking. Local only.
3. Graceful fallback — Always have a default if API unavailable.
4. User control — Let users override automatic behavior.
5. Performance — Sensor polling must be throttled.

---

BATTERY-AWARE UI

Reduce animations and features when battery is low:

// batteryAwareness.ts
interface BatteryState {
  level: number;         // 0 to 1
  charging: boolean;
  chargingTime: number;  // Seconds until full
  dischargingTime: number;
}

class BatteryManager {
  private battery: BatteryState | null = null;
  private listeners: Set<(state: BatteryState) => void> = new Set();
  private lowBatteryThreshold = 0.2; // 20%

  async init(): Promise<void> {
    if (!('getBattery' in navigator)) return;

    try {
      const battery = await (navigator as any).getBattery();
      
      this.updateState(battery);
      
      battery.addEventListener('chargingchange', () => this.updateState(battery));
      battery.addEventListener('levelchange', () => this.updateState(battery));
    } catch {
      // API not available
    }
  }

  private updateState(battery: any): void {
    this.battery = {
      level: battery.level,
      charging: battery.charging,
      chargingTime: battery.chargingTime,
      dischargingTime: battery.dischargingTime,
    };
    
    this.notifyListeners();
    this.applyOptimizations();
  }

  private applyOptimizations(): void {
    if (!this.battery) return;

    const isLowBattery = this.battery.level < this.lowBatteryThreshold && !this.battery.charging;
    
    document.documentElement.classList.toggle('low-battery', isLowBattery);
    document.documentElement.setAttribute('data-battery', isLowBattery ? 'low' : 'normal');
  }

  private notifyListeners(): void {
    if (!this.battery) return;
    this.listeners.forEach(fn => fn(this.battery!));
  }

  subscribe(fn: (state: BatteryState) => void): () => void {
    this.listeners.add(fn);
    if (this.battery) fn(this.battery);
    return () => this.listeners.delete(fn);
  }

  isLowBattery(): boolean {
    return this.battery 
      ? this.battery.level < this.lowBatteryThreshold && !this.battery.charging 
      : false;
  }

  getLevel(): number | null {
    return this.battery?.level ?? null;
  }
}

export const batteryManager = new BatteryManager();