From 74e0549196367a7e5bfb27f5a42c466c8c59939d Mon Sep 17 00:00:00 2001
From: James Mackay <NotExpectedYet>
Date: Mon, 12 Oct 2026 06:53:13 +0100
Subject: [PATCH] docs(readme): the t55 state ladder and the label tier's retry
 rule
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The State ladder section still described tier 7 as "app open → on" and
tier 8 as "On — powered, awake, nothing more specific", which the t55
ladder change makes wrong: an open app with nothing playing is `idle`,
`buffering` is a state, and `on` now means "no source reported anything
at all". The retired-piece table gets the same vocabulary, and the
app-name row records that the manifest label is fetched for the app on
screen and retried after a failure instead of being cached as a miss.
---
 README.md | 39 ++++++++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 59b2e33..8dd670b 100644
--- a/README.md
+++ b/README.md
@@ -63,22 +63,31 @@ remote protocol is the fast push/command path:
 
 1. **Plug off** — the power switch says `off` → `off`.
 2. **Protocol power push** (`is_on`) — `False` → `off`; `None` falls through.
-3. **ADB wake** (exact `mWakefulness` parse) — asleep → `idle` (standby).
-4. **Intent** — a just-sent command's target state, self-healing against
+3. **Intent** — a just-sent command's target state, self-healing against
    reality within 30 s (retry goes over the transport that served it).
-5. **Jellyfin** — `playing` / `paused` while a Jellyfin session is active.
-6. **ADB media session** — `playing` / `paused` for apps that publish a
-   session (foreground app preferred).
-7. **Foreground fallback** — an app is open (`current_app` protocol push,
-   then the ADB `mResumedActivity` parse) but publishes no media session →
-   `on`. Its identity comes from the TTL-capped last-known-state cache, the
-   last channel entered, or the zero-cost "audio playback" hint
-   (`media recently active`) — never resurrecting `playing` past the 60 s
-   state TTL.
-8. **On** — powered, awake, nothing more specific.
+4. **Jellyfin** — `playing` / `paused` while a Jellyfin session is active.
+5. **ADB media session** — `playing` / `paused` / `buffering` for apps that
+   publish a session (foreground app preferred). `buffering` is the media
+   session's own PlaybackState 6 (`state=PlaybackState {state=6, …}`), and a
+   buffering session advertises the playback controls exactly like `playing`.
+6. **Idle** — the device is powered (protocol `is_on` true, ADB awake, or the
+   power plug on) and nothing is playing, or ADB reports it asleep (standby).
+   A powered Shield with an app open and nothing playing reads `idle`.
+7. **On** — **no source reported anything at all**: no transport connected, no
+   power entity, no Jellyfin, no media session. `on` is the "we cannot know"
+   state and the only situation it describes — it never appears while any
+   source reported a power or media state, and never masks a
+   `playing`/`paused`/`buffering` source.
+
+The foreground tier is what keeps an app's identity visible while the state is
+`idle`: the `current_app` protocol push (then the ADB `mResumedActivity`
+parse), with its title from the TTL-capped last-known-state cache, the last
+channel entered, or the zero-cost "audio playback" hint
+(`media recently active`) — never resurrecting `playing` past the 60 s state
+TTL.
 
 TiviMate (`ar.tvplayer.tv`) is the documented no-session case: it publishes
-no MediaSession on Shield Android 11 (RESEARCH_SHIELD R2), so tiers 6–7 plus
+no MediaSession on Shield Android 11 (RESEARCH_SHIELD R2), so tiers 5–6 plus
 the audio hint are what keep it visible.
 
 **Standalone setup** offers both state sources at once — the Nvidia Remote
@@ -174,8 +183,8 @@ What each retired piece used to provide, and what covers it now:
 
 | Retired piece | Covered by |
 |---------------|------------|
-| `androidtv` playback state | the ADB media-session state ladder (`playing` / `paused` / `idle` / `off`) |
-| `androidtv` app name / `app_id` lookups | the manager's store + the app-name map + the manifest label of the running app |
+| `androidtv` playback state | the ADB media-session state ladder (`playing` / `paused` / `buffering` / `idle` / `off`, plus `on` only when no source reported anything) |
+| `androidtv` app name / `app_id` lookups | the manager's store + the app-name map + the manifest label of the app that is currently on screen (fetched on demand; a failed fetch is retried on the next poll instead of being cached as a permanent miss) |
 | `androidtv_remote` power, volume and key commands | the protocol transport: the `remote` entity, `media_player` volume, `KEYCODE_*` commands |
 | `androidtv_remote` availability | the availability contract (protocol `is_on`, ADB awake, power switch) |
 | `universal` media player templates | the media player entity's own attributes plus the `media_dag_*` attributes |