# OSHUN Android 60 FPS Validation

Status: Active Owner: OSHUN Mobile Engineering Last Updated: February 16, 2026

## Goal

Validate that key OSHUN shell interactions sustain 60 FPS on a mid-range Android
device.

## Device Profile

Use at least one physical mid-range Android device, for example:

- Pixel 6a class
- Samsung A54 class
- Any Android 13+ device with 60Hz display and non-flagship CPU/GPU

## Validation Targets

Interactions to measure:

1. Swipe-back transition (`Home -> Domain detail -> swipe back`)
2. Pull-to-refresh on home feed
3. Draggable bottom sheet drag-dismiss

## Tooling

Added automation in `apps/oshun/mobile/scripts`:

- `validate-android-fps.sh` resets + captures `adb shell dumpsys gfxinfo`
- `parse-gfxinfo.mjs` computes pass/fail using the shared thresholds in
  `apps/oshun/mobile/config/animation-budgets.json`
- `apps/oshun/mobile/src/performance/animationBudgets.ts` is the typed mobile
  contract that documents the same profiling and battery ceilings for tests and
  release signoff

Run from `apps/oshun/mobile`:

```bash
pnpm run perf:fps:android com.oshun.mobile swipe-back
pnpm run perf:fps:android com.oshun.mobile pull-to-refresh
pnpm run perf:fps:android com.oshun.mobile sheet-drag
```

## Pass Criteria

The parser enforces:

- `totalFrames >= 120`
- `jankyPercent <= 5`
- `p95 <= 20ms` (or `p90 <= 18ms` when `p95` unavailable)
- `estimatedFps >= 57`

All checks must pass.

## Result Log Template

| Date | Device | Interaction | Total Frames | Janky % | p95 ms | Estimated FPS | Result | Notes |
| ---- | ------ | ----------- | ------------ | ------- | ------ | ------------- | ------ | ----- |
| TODO | TODO   | swipe-back  | TODO         | TODO    | TODO   | TODO          | TODO   | TODO  |
| TODO | TODO   | refresh     | TODO         | TODO    | TODO   | TODO          | TODO   | TODO  |
| TODO | TODO   | sheet-drag  | TODO         | TODO    | TODO   | TODO          | TODO   | TODO  |

## Current Status

Automation and thresholds are implemented.

Direct physical-device execution is still required to populate the result log
and finalize release sign-off.
