fix(tv): give Apple TV a working wait primitive

[filip131311]

Fixes #620.

Reproduced

Apple TV 4K simulator, tvOS 26.5, com.apple.TVSettings, on a provably static screen:

await-screen-idle  → { settled: false, waitedMs: 6002, polls: 31 }      ← and no note at all
await-ui-element   → { success: false, elapsed: 4001, note: "…tvOS is not supported…" }
describe           → 12 focusables, source "tv-focus"                    ← works fine

Root cause — one line

Both wait tools fetch through describeIos, which short-circuits every tvOS read (describe/platforms/ios/index.ts:93-96) to emptyTree() + a hint. await-screen-idle resets whenever the tree is empty (await-screen-idle/index.ts:164-169), so on tvOS that condition is permanently true — the tool is structurally incapable of returning settled: true there, and polls to the timeout to find out. It also reads only data.tree and never data.hint, which is why the good explanatory note its sibling emits was silently dropped.

describe works on the same screens because it routes TV targets to the focus view before the iOS dispatch (describe/index.ts:107,126) — a branch the wait tools never got. They now poll that same source.

Design decisions worth reviewing

Real frames, not synthesized ones. My first read of the payload (and the issue's doc nit) said TvElement has no frame. That's true of the TypeScript interface and false of the data — I probed the daemon socket directly:

{"label":"Appearance","frame":{"y":0.249,"x":0.552,"width":0.406,"height":0.061},
 "value":"Dark","traits":["button","_focusGuide"],"tapPoint":{"x":0.755,"y":0.280}}

They survive into the tool because tv-control.ts:459-465 passes the parsed objects through by reference; only the type omitted them, and describe's rendering drops them. So the adapter uses them, and isVisible / reading order mean here what they mean everywhere else. An index-derived band remains as a fallback for backends that genuinely report no bounds (Android TV) and for zero-size elements.

The hint on an empty read is load-bearing, not decoration. await-ui-element treats an empty tree as an untrustworthy read only when a hint (or a prior match) says so. An adapter that returned an empty focus view without one would make condition: "hidden" report success on the first poll of a still-launching app — releasing an interaction that was deliberately gated. That is strictly worse than the bug being fixed, so it has two tests.

The cursor is marked with a synthetic focused trait, not only the focused field. That buys two things the field cannot: {role:"focused"} becomes selectable, so "wait until focus lands on X" is expressible — the wait a TV run-sequence actually needs between tv-remote and select — and the cursor enters the idle fingerprint, so a screen whose focus is still moving doesn't read as settled. Safe as a role token: role matching is a case-insensitive substring and no real trait on either backend contains "focused" (_focusGuide, _tvFocusable do not).

Android TV deliberately keeps its full uiautomator tree. An empty focus set is steady state there — react-native-tvos screens drive focus with RN's own engine, invisible to the OS accessibility tree — whereas on Apple TV it's a transition. Routing Android TV onto the focus source "for consistency" would import this very bug onto a platform that works. There's an explicit test guarding it.

The wait path never repairs the read path. describeTv retries with sleeps and can respawn the tvOS ax daemon (recycleAx). Inside a 200 ms poll that is redundant at best and destructive at worst — respawning drops the very state being waited on. The wait takes one bare read per poll and points at describe for the repair; a test asserts recycleAx is never called and that api.describe call count equals polls.

A tax this removes that the issue doesn't mention

The MCP layer waits on await-screen-idle before every auto-screenshot and handles failure by sleeping the full budget (mcp-server.ts:342-344). Since settled could never become true on tvOS, every launch-app/restart-app cost 3000 ms and every run-sequence 15000 ms before the screenshot. It now returns as soon as the screen holds.

That also rules out the issue's suggested "fail fast": returning immediately would make the auto-screenshot capture splash screens, and returning by throwing is the slowest possible outcome there.

note is not tvOS-specific

await-screen-idle gained a note for any unsettled wait on an empty read. I found this matters beyond TV: on a device whose screen is simply off, describe returns an empty root with no hint and the tool stalls the whole budget saying only settled: false. Now it says the screen reported no content. (Neither tool detects "screen is off" as such — worth its own issue, since mWakefulness makes it a one-line check.)

Verified live

Apple TV 4K / tvOS 26.5, branch tool-server:

await-screen-idle                                   → { settled: true, waitedMs: 765, polls: 3 }
await-ui-element {text:"About", role:"focused"}     → { success: true, elapsed: 5 }
await-ui-element text "Region" == "Poland"          → { success: true, elapsed: 4 }

Previously: never settled, and every condition failed at full timeout.

Tests

tv-focus-tree.test.ts (11) covers the adapter: real frames preserved, ordered non-degenerate fallback, bundle id on the root but not matchable, labels/values/traits matchable, cursor marked once and not duplicated, orphan cursor still surfaced, and the empty-read hint. await-tv-focus.test.ts (12) covers tool behaviour: settles on a static view, doesn't settle while the cursor moves or the set grows, explains an empty view, never calls recycleAx, all four conditions on tvOS, hidden refusing to resolve on an empty view, and the Android-TV routing guard.

Mutation-verified: removing the tvOS routing fails 11 of 12 (the 12th is the Android-TV guard, correctly unaffected).

Full tool-server suite green — 3109 passed / 299 files.

Docs

The skill's "focusable elements with labels and normalized frames" is corrected: the frames exist in the source but the focus view doesn't print them, and a TV is navigated by D-pad rather than coordinate. The navigation step that told the agent to "count rows/columns from the frames" now points at the order of the focusable list. Only packages/skills/skills/… is edited — the other copies are generated.

Not in scope

• Flows on tvOS are still broken. utils/ui-tree-match.ts fetchTree routes tvOS into describeIos with no isTvOs option, so flow directives and the recorder still see an empty tree. describeTvFocus drops in there verbatim; I left it out to keep this reviewable and will file it separately.
• Neither wait tool is picked up by the tool-description extractor (both use const-reference ids), so their descriptions aren't scored by the quality gate. Real gap, worth its own issue; deliberately not "fixed" here since enrolling two long descriptions into the scored average is a separate risk.
• A physical Apple TV still falls into the ordinary iOS path (isTvOsSimulator is simulator-list based). Pre-existing.