adaptive-performance.md

Adaptive performance

Modern phones throttle aggressively: once the device reaches a serious thermal state, the OS cuts CPU/GPU clocks whether you cooperate or not. The difference between a graceful app and a janky one is who decides what to drop — you, or the scheduler.

The pattern is simple: map device health to a quality tier, and derive every expensive knob from that tier.

1. Derive a quality tier

import {
  useThermalState,
  useLowPowerMode,
} from 'react-native-device-pulse';

export type QualityTier = 'high' | 'medium' | 'low';

export function useQualityTier(): QualityTier {
  const thermal = useThermalState();
  const lowPower = useLowPowerMode();

  if (thermal === 'critical') return 'low';
  if (thermal === 'serious' || lowPower) return 'medium';
  return 'high'; // 'nominal', 'fair' and 'unknown'
}

Treat 'unknown' as healthy — it usually just means an older Android device, and punishing it by default would degrade the experience for no reason.

2. Spend the tier

Knob	high	medium	low
Video / stream quality	1080p	720p	480p
Animation	full (springs, blurs)	simplified	none / instant
List rendering	rich cells, images	images capped	text only
Background work (prefetch, sync, analytics flush)	on	reduced	paused
Frame-rate targets (games, maps)	60 fps	30 fps	30 fps

function AnimatedHeader() {
  const tier = useQualityTier();

  if (tier === 'low') {
    return <StaticHeader />; // no animation at all
  }
  return <ParallaxHeader blurEnabled={tier === 'high'} />;
}

3. React to memory pressure

Memory warnings mean the OS is about to start killing processes — yours included. Drop anything you can rebuild:

import { useMemoryWarning } from 'react-native-device-pulse';

function App() {
  useMemoryWarning(() => {
    imageCache.clear();
    queryClient.clear(); // e.g. react-query in-memory cache
  });
  // ...
}

Guidelines

• Degrade one step at a time. Going straight from 1080p to 240p is noticeable; 1080p → 720p usually is not.
• Be sticky on recovery. Devices oscillate around thermal boundaries. Upgrade quality only after the state has been better for a while (e.g. 30–60 s), or you will visibly flip-flop.
• Respect the user's explicit choice. Low Power Mode is the user saying "please spend less battery" — pausing prefetch and lowering frame rates there is expected behavior, not a regression.
• Log tier changes. Correlating dropped quality with thermal events in analytics tells you which real-world devices need attention.