# Home performance baseline

This is the repeatable performance check for Home. The source baseline is the current
good-performing release line at commit `5467fba` (0.2.84). Numbers are only comparable on
the same television, Android build, server, network and signed-in profile, so benchmark
results belong with the test run or release notes rather than as universal targets here.

## What is measured

- `coldStartToHomeNoCompilation`: cold launch without ahead-of-time compilation, used as
  the control for the baseline profile.
- `coldStartToHomeWithProfile`: cold launch as a release is shipped. `timeToFullDisplayMs`
  ends when Home reports its first D-pad-ready, settled frame.
- `warmStartToHomeWithProfile`: returning to a resident process.
- `homeDpadAndRows`: frame timing during rapid travel across cards, down four rows, and back
  through already displayed artwork. The route deliberately does not idle between presses.
- Debug milestones in `MembyStartup`: process start to `home_visible`,
  `first_row_visible`, and `home_interactive`.
- Debug frame windows in `EmbyClientPerf`: jank percentage, p50/p95/p99 UI frame time,
  frames over 16 ms and 33 ms, and the maximum frame time.

Compose Layout Inspector supplies card and row recomposition counts. Capture a system trace
at the same time when a frame regression needs attribution; the trace shows Compose work,
Coil fetch/decode activity and main-thread scheduling together.

## Run protocol

Use a physical TV with a signed-in profile and a populated Home cache. Keep the TV's display
mode, server, network and Home row preferences unchanged between the reference and candidate
runs.

```powershell
$env:JAVA_HOME = "C:\Program Files\Android\Android Studio\jbr"
.\gradlew.bat :benchmark:connectedBenchmarkReleaseAndroidTest `
  -P android.testInstrumentationRunnerArguments.class=com.ponzischeme89.memby.benchmark.HomeBenchmark
```

For an interactive debug capture, clear logcat, cold-start Memby, wait for Home, then rapidly
hold Right and move through at least four rows. Record:

```powershell
adb logcat -s MembyStartup EmbyClientPerf
```

In Layout Inspector, enable recomposition counts and repeat the same route. Unchanged cards
outside the old and new focus targets should normally be skipped; focus animation should not
cause per-frame card recomposition. In Android Studio's system trace, inspect the slowest
frames for main-thread Compose work and Coil image fetch/decode slices.

## Regression gates

Use the median of at least five iterations. Investigate before release when, against a fresh
reference run on the same setup:

- profiled cold-start `timeToFullDisplayMs` or warm start regresses by more than 10%;
- `frameDurationCpuMs` p95 regresses by more than 10%, or p99 crosses 33 ms;
- a previously displayed card causes a network fetch or another decode on the return pass;
- focus animation recomposes a card on every animation frame or invalidates unaffected cards;
- adding a Home row materially changes first-row visibility time. Below-the-fold rows may
  affect `home_interactive`, but must not delay `first_row_visible`.

Regenerate the baseline profile after changing the startup or first-browse path:

```powershell
.\gradlew.bat :app:generateReleaseBaselineProfile
```

Keep the reference and candidate benchmark result directories together. Hardware variance
makes the paired result the baseline; a number copied from a different TV is not evidence of
a regression or an improvement.