--- name: tv-remote-ui description: How this app stays usable from a TV remote (Android TV / Google TV). Read before adding or changing any interactive UI — a new page, dialog, control bar, list, card, or overlay — and before touching plugins/dpad.client.ts, utils/dpad.ts, or the Android manifest/activity. Triggers on "remote", "d-pad", "dpad", "Android TV", "smart TV", "leanback", "focus", "keyboard navigation", "arrow keys", "back button". --- # Remote-friendly UI Ventic runs on desktop **and** on Android TV, where the only input is a d-pad: **up, down, left, right, OK, back**. No pointer, no hover, no text entry worth having. Anything you add has to be reachable and legible with those six keys. ## How it already works `app/plugins/dpad.client.ts` is the whole mechanism, and it is generic — new pages get remote support for free as long as they follow the rules below. - **Arrows** move focus to the nearest focusable element in that direction, scored by `pickDirection()` in `app/utils/dpad.ts`. Sideways drift is measured between the boxes' **edges**, not their centres — boxes that face each other at all count as level, or a 44px nav link never reaches the 361px poster beside it. Anything level like that beats everything that isn't, however much closer: a run along the toolbar has to reach Downloads 264px away rather than fall into the grid 74px below. Drift costs double only among equals, which is what keeps a grid walking straight down its column. - **A rect is the document's, not the screen's**, so every candidate is put through `clipped()` first: each edge pulled inside every scroller it sits in, collapsing onto the edge it went past rather than being dropped. Without it a poster three rows above the fold still measured level with the toolbar — right off the search box landed on it instead of on Settings, and up out of the drawer landed on one 350px above the screen, after which every further press was measured from somewhere nobody could see. Collapsing and not dropping is what keeps a horizontal row walking: its next card is off the right edge by design, and sat on that edge it is still the nearest thing that way. It is handed a real `DOMRect`, whose edges are prototype getters — destructure it, never spread it, or every edge is `NaN` and the page answers no arrow at all. - **A press never leaves a scroll region that still has content that way**; it scrolls the region instead (`scroller()`, which `nudge` shares). A title page's synopsis is prose, so nothing above the Play row is a target and up escaped straight to the toolbar — leaving the title, poster and overview unreachable for the rest of the visit, there being nothing to move *to* that would bring them back. - **The scroll is animated, and both halves of that are ours.** `heading` holds where each scroller is going and `step()` eases it there on a frame loop, because the platform's animation cannot be retargeted: `scrollTo` with a smooth behaviour *cancels* whatever is running and eases in from a standstill, so a press landing mid-scroll stopped the page dead and started again — measured on the set at eight presses 120ms apart, the page crawled at 5px a frame for three seconds and then covered 2000px in half of one, once the presses stopped. Easing toward a moving target has no standstill in it, and costs nothing extra: the same per-frame durations as the platform's, at 60fps. The loop stops when it arrives, and lets go the moment a wheel or a finger moves the scroller instead. - **Every decision about that scroll is taken against the page at rest.** A rect read mid-animation describes a page on its way somewhere, and `scrollIntoView` is no better — its `nearest` is measured from where the scroll has got to, so it asks for the whole remaining distance *plus* a row and each press of a burst aims further than the last. `show()` works the destination out itself from the resting geometry; `move()` measures candidates the same way, because mid-flight every row below the fold clips onto the same edge and only document order tells them apart, which walked the grid *backwards*; and `focusFirst()` likewise, or it lands on a row already on its way off the screen. A heading is clamped to where the scroller can stop, and re-clamped every frame — an unreachable one is answered with for ever, and every later press is then judged against a page that does not exist. `nudge` steps on from where the scroller is heading, and keeps focus unless the element it was on really did scroll out of view. - The handler sits on `document` in the **bubble** phase and bails on `e.defaultPrevented`, so any component that already handles arrows keeps them: Vuetify sliders, lists, selects, and the player's seek keys. - A component may own an axis but never the one that leads *out* of it, or the d-pad has no exit but Back. A second handler in the **capture** phase takes the key back for the ones that would: up/down off a `[role="slider"]` (whose value is left/right, and which otherwise changes as you try to leave), up/down off the first/last item of a `.v-list` (which otherwise wraps, so the drawer cycles for ever instead of letting go), and left/right off the ends of a `.v-slide-group` — chip groups and tabs wrap the same way, which is why the category chips circled instead of reaching the genre filter beside them. - **Only `tabindex="-1"` opts out.** Vuetify's lists rove the tabindex across their items and park `-2` on the ones that aren't current — every drawer link carries it, and they are all real targets. A wrapper that merely *contains* other targets (the `.v-list` div is focusable itself) is not one. - **Nothing that way?** The page scrolls by 80% of a screen instead (`nudge()`), then focus is dropped so the next press lands on the freshly revealed row. This is what makes lazily-mounted content (`v-lazy` rows) reachable at all. - **OK** is plain Enter — the browser clicks a focused ``/`