From aea87521eb6eaa6d8275492ec318c4e48d6d8d74 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Wed, 18 Nov 2026 17:21:24 +0300 Subject: [PATCH 01/12] Reach elements by id in the harness; Home's carousel holds still under a hero press (#1442) Device and simulator scripts now reach elements by accessibility id instead of walking to them with direction keys, check where focus landed before taking a shot, and cannot press a title without naming it. This is the harness half of the series, after the ids (#1431) and the `focus:`/`press:`/`state:` tokens (#1432). - **`tools/tv-session.sh` gains `focus `, `press [--rk RK]` and `state [--out FILE]`**, all under the TV lock. - Ids and ratingKeys are checked locally before anything reaches ssh or the FIFO. - A press on an element that acts on a title needs `--rk`, and the app refuses the press if that title is not the element's. - `key` refuses by-id words, so the verbs are the only way to send one. - The FIFO write escapes `'` for the remote shell and refuses any whitespace inside a token, because the app splits on whitespace. - `state` sends a random nonce and polls `plxnative-a11y.json` until the nonce matches. - **`tools/a11y.py` is the simulator helper.** - It provides `focus`, `press(subject=)` and `expect_focus`. - Its command line applies the same title guard, with `--subject`. The library `press()` is unguarded, for scripts that drive the mock. - **Every element whose press acts on a title it names now carries that title's ratingKey as its `A11y` subject.** It is read the way the activation reads it, with no state and no IO. - This covers the Home hero, the item menu, the Detail hero (a started show names the episode the press acts on), the Play Version rows, the player HUD's queue and restart controls, the failure screen's retries, the More menu's quality rungs, and the track and subtitle rows that write to the server. - `SUBJECT_BEARING` is the one list. A test holds it equal to every file that builds a play, queue-step or write message. - **Home's hero/grid door.** A by-id press queues its focus move and its OK in the same frame, so it used to act on the element focused before the move. - A scripted focus move now clears that remap. - While a key's move has left the picture behind the focus, any by-id press of the focused element is refused as `unloaded` until the picture catches up. - A key move followed by a quick OK keeps today's behaviour. - **The carousel holds still under a hero press.** While a press is armed on a hero button, the countdown restarts and a Flip or edge key is refused, so the commit acts on the title the press was accepted against. This also fixes a person's OK just before a turn. - **A by-id press resolves against the live focus, and every delivery reads the live press state.** A by-id press batched after a key sees the focus that key moved, and a screen's tick sees a press armed in the same frame. - **The Watchlist captures drive by id only.** Focus is checked through `state` before each shot, and any `a11y: refused` line fails the capture. `tests/player_shots.sh` presses the HUD by id. - **The docs carry two rules:** prefer ids, walking only where focus travel is the subject; and the subject rule, pointing to `SUBJECT_BEARING`. They are in the `tv-session` and `ui-sim` skills, `docs/agent-reference.md`, `tests/README.md` and `rust-modules/ui/src/CLAUDE.md`. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/tv-session/SKILL.md | 41 +- .agents/skills/ui-sim/SKILL.md | 27 + ci/test_tv_session.py | 45 + docs/DESIGN.md | 10 +- docs/agent-reference.md | 19 +- rust-modules/appkit/src/more_menu.rs | 13 + rust-modules/appkit/src/player_hud/command.rs | 25 + rust-modules/appkit/src/player_hud/loaded.rs | 14 + rust-modules/appkit/src/track_menu.rs | 37 + rust-modules/media/src/route/decision.rs | 38 + rust-modules/screens/src/detail/mod.rs | 51 +- rust-modules/screens/src/detail/tests.rs | 163 ++++ .../screens/src/home/hero_shade_tests.rs | 2 +- .../screens/src/home/hero_watchlist_tests.rs | 51 +- rust-modules/screens/src/home/mod.rs | 192 ++++- rust-modules/screens/src/home/tests.rs | 527 +++++++++++- rust-modules/screens/src/item_menu.rs | 85 +- rust-modules/screens/src/player/mod.rs | 249 +++++- rust-modules/screens/src/player/overlay.rs | 32 +- .../screens/src/player/overlay_tests.rs | 145 ++++ rust-modules/screens/src/registry.rs | 24 +- rust-modules/screens/src/versions_panel.rs | 76 +- rust-modules/src/app/run.rs | 149 ++++ rust-modules/src/focusprobe.rs | 7 + rust-modules/ui/src/CLAUDE.md | 21 + rust-modules/ui/src/a11y.rs | 12 +- rust-modules/ui/src/dispatch.rs | 8 + rust-modules/ui/src/dispatch/by_id.rs | 48 +- rust-modules/ui/src/dispatch/snapshot.rs | 12 +- rust-modules/ui/src/fixture.rs | 27 +- rust-modules/ui/src/input_tests.rs | 50 ++ tests/README.md | 17 + tests/player_shots.sh | 41 +- tests/scenarios/watchlist_captures.json | 112 ++- tests/test_a11y_tool.py | 796 +++++++++++++++++- tools/a11y.py | 331 +++++++- tools/tv-session.sh | 467 +++++++++- tools/watchlist_captures.py | 120 ++- 38 files changed, 3867 insertions(+), 217 deletions(-) diff --git a/.agents/skills/tv-session/SKILL.md b/.agents/skills/tv-session/SKILL.md index 2a9927d757..e1b6e566c2 100644 --- a/.agents/skills/tv-session/SKILL.md +++ b/.agents/skills/tv-session/SKILL.md @@ -41,8 +41,12 @@ read from the gitignored `src/config.local.h` at runtime and never printed. ```bash tools/tv-session.sh up [--flavor ] [--screen ] [--server ] [--stream[=PORT]] [--remote[=PORT]] [--no-token] tools/tv-session.sh status [--flavor ] # re-assert without disturbing the session -tools/tv-session.sh key down down ok # key tokens through the real handlers +tools/tv-session.sh key down down ok # key tokens through the real handlers (never focus:/press:/state:) tools/tv-session.sh click 960 540 # authored 1920x1080 coords +tools/tv-session.sh focus watchlist.grid.card.7 # move focus to an element BY ID (no key walk) +tools/tv-session.sh press nav.watchlist # focus it, then an OK press +tools/tv-session.sh press home.shelf.0.card.2 --rk # an element that acts on a title it names (card, credit, hero button, menu row, player Next...) REQUIRES the title it must be +tools/tv-session.sh state [--out FILE] # the app's JSON snapshot: route, owner, focused id, every element tools/tv-session.sh shot [out.png] # panel capture (video plane included) tools/tv-session.sh log [--flavor ] [regex] # the on-device event log tools/tv-session.sh screen off|on # blank/restore the PANEL only (app keeps running) @@ -283,7 +287,40 @@ a log you did not watch being produced. Every `plxnative-*` trigger in the install's runtime root is read **once at boot**, so it must be in place before the launch. Anything you want to do to a *running* app goes through -the remote FIFO (`tv-session.sh key` / `click`). +the remote FIFO (`tv-session.sh key` / `click`, or by id: `focus` / `press` / `state`). `key` sends keys +and the like (`down`, `ok`, `ck:,`, `txt:...`) and refuses a `focus:`, `press:` or `state:` word, so each +by-id action has ONE door, the verb, where the id is checked and a title's press must name the title. A word +with whitespace in it is refused too (`key back "ok press:"`): the app cuts a FIFO line at any +whitespace, so it would be two tokens, the second a press nothing had checked. + +**Prefer `focus` / `press` by id over key walks.** A walk of `down down right ok` breaks when a row +gains a card; an id (`watchlist.grid.card.7`, `detail.hero.go_to_show`; the grammar is in `tools/a11y.py`) +names the element whatever the row holds. Ids resolve in the namespace of whoever owns input, so a +menu answers `itemmenu.*`, not the screen under it. A press of any element that ACTS ON a title it names (it +plays, restarts, finishes or retries it, marks it watched or unwatched, bookmarks it, acts on the title a menu was +opened for, or opens that title's own page or menu where the title can change under the press: a card, a credit, +the Home carousel's Info, a hero button, an item-menu row, a Play Version row, a player control that starts a +title) needs `--rk `, the ratingKey of the title the press acts on, which `state` prints as the element's +subject (Mark watched on a started show is the on-deck episode, a player's Next the queue neighbour). Navigation is +not the test: only a control whose target the page fixes (`detail.hero.go_to_show`, the Play Version opener, a +panel opener such as `player.control.subtitles`, a seek, `home.hero.action`) is pressed bare. The ids are +`SUBJECT_BEARING` in `tools/a11y.py`, the one list (`a11y_subject_bearing` in `tools/tv-session.sh` is the same +list, and a test holds them equal), so a re-sorted row, a moved hero or a menu opened on another card cannot press a +different title: the subject is compared where the press is delivered, and the press commits about 200 ms later, so +Home's carousel does not turn while a press stands on a hero control (the 8 s countdown restarts from full while +the press stands, as a focus move restarts it, so no turn is owed when the press settles and the next one comes a +full interval later; Flip and Left/Right at the edge are refused while it stands, dropped rather than applied +when it settles, so send them again then), which keeps the title the press was accepted +against the title it plays (a landing that takes that title out of the hero pool inside the 200 ms is the one +change nothing holds: the press then acts on its successor). At Home's hero/grid door +a quick OK after a key lands on what the picture shows, not on the focused +element: while the picture lags (about 8 frames, 130 ms at 60 fps: the dive's midpoint), a by-id press of the focused element, named or bare, is +refused as `unloaded` (`a11y: refused press unloaded`), and you press again once the screen has settled. On a +real account the `ratingKey` you name must be one you read from the log (the boot rule: never `ok` a title you have not read). `state` is the +structured readback: it sends a random nonce and reads `plxnative-a11y.json` until the nonce comes +back, so a stale file never passes for the answer. Walks stay for tests whose subject is travel +(fps walks, focus fingerprints, `hold`, timed keys). These need a debug (`devtriggers`) build; +a release build answers none of them. **Some exceptions are deliberate and read LIVE**: `plxnative-failtest` (so a read-out variant can be swapped mid-playback), `plxnative-testpat` (the same for the synthetic ground), diff --git a/.agents/skills/ui-sim/SKILL.md b/.agents/skills/ui-sim/SKILL.md index 6c93a40878..8d42232b2b 100644 --- a/.agents/skills/ui-sim/SKILL.md +++ b/.agents/skills/ui-sim/SKILL.md @@ -221,6 +221,33 @@ Tokens: `up`/`down`/`left`/`right`, `ok`, `back`, `play`/`pause`/`stop`, `ck:X,Y authored 1920×1080 coords), `okdown`/`okup` (split halves — the only way to drive a press-and-hold past `press::LONG_MS`), and `shot` (simulator only). +**Reach a target by id, not by walking to it.** A debug (`devtriggers`) build also takes +`focus:`, `press:` (focus, then an ordinary OK) and `press:@` (refuses and +presses nothing when the element the id NAMES carries another subject than the one given), plus +`state:`, which writes `plxnative-a11y.json` in the runtime dir (route, owner, the focused full +id, every element's id, role, rect, `visible`, `loaded`, label and subject) with the nonce echoed back. +An id is a place-based dot path (`nav.watchlist`, `watchlist.grid.card.7`, `detail.hero.play`) in the +namespace of whoever OWNS input, so inside a menu it is the menu's (`itemmenu.watchlist_remove`); a +refusal presses nothing and logs `a11y: refused owner=` (`unloaded` is not +an error: the element is not pressable yet, a card whose item has not landed or Home's focused element while its picture +lags a key across the hero/grid door, so press again once the screen has settled). `tools/a11y.py` writes +the tokens (`focus`, `press`) and reads the answer (`expect_focus`). Prefer these over key walks; a walk +stays where the test's subject IS the travel (fps walks, focus fingerprints, a held key). + +The simulator boots against the owner's real server unless you aim it at the mock, and OK on a title +can play it, so the command line refuses to press one UNNAMED: `python3 tools/a11y.py press +` WITHOUT `--subject ` (and `send press:` without an `@`) exits 2 and sends +nothing when the id is of an element that ACTS ON a title it names (it plays, restarts, finishes or retries it, +marks it watched or unwatched, bookmarks it, acts on the title a menu was opened for, or opens that title's own page +or menu where the title can change under the press: a card, a credit, the Home carousel's Info, a hero button, an +item-menu row, a Play Version row, a player control that starts a title; only a control whose target the page fixes +stays bare). `SUBJECT_BEARING` in `tools/a11y.py` is the one list of those ids, and the key to name is the ratingKey +of the title the press acts on, which `state` prints as the element's subject. Read the ratingKey from `state` +first. The library functions `a11y.press` / `press_token` stay unguarded, for a script that drives the mock (a +script that imports them against a real server has no check). `a11y.py +send` writes ONE token: a word with whitespace in it (`send "back press:"`) exits 2 and sends +nothing, because the app cuts a FIFO line at any whitespace and the second token would skip that guard. + A desktop keyboard also works directly in `make sim-macos-run`: arrows, RETURN, ESC (`is_ok`/`is_back` have always accepted keyboard keys), plus space=pause, `p`=play, `s`=stop, backspace=BACK. diff --git a/ci/test_tv_session.py b/ci/test_tv_session.py index 709c53201e..a54c634e76 100644 --- a/ci/test_tv_session.py +++ b/ci/test_tv_session.py @@ -974,5 +974,50 @@ def test_the_other_lifecycle_subcommands_still_wake_an_asleep_set(self): self.assertTrue(woke) +class SelfTest(unittest.TestCase): + """The script's own `selftest` (`make check` runs it as `tools/tv-session.sh selftest`). Every other case here + sources the script with `selftest` as $1, which RUNS it, and grades only its own markers, so a `bad` line + there was invisible: this one grades the selftest itself, including the by-id guard and the FIFO quoting.""" + + def _run(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + (root / "tools").mkdir() + script_link = root / "tools" / "tv-session.sh" + script_link.symlink_to(SCRIPT) + bin_dir = root / "bin" + bin_dir.mkdir() + (bin_dir / "make").write_text( + "#!/bin/sh\n" + "printf '%s\\n' debug com.beb.plxnative.debug /app /run /events 8911 fake-host\n", + encoding="utf-8", + ) + (bin_dir / "make").chmod(0o755) + environment = os.environ.copy() + environment["PATH"] = f"{bin_dir}:{environment['PATH']}" + return subprocess.run( + ["bash", "-c", 'source "$1" selftest; echo "RC:$?"', "selftest", str(script_link)], + text=True, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + env=environment, + check=False, + timeout=60, + ).stdout + + def test_the_selftest_passes_and_reports_the_by_id_and_fifo_contracts(self): + out = self._run() + # The identity checks print ✗ lines by design (they exercise a refusal), so the verdict is the exit + # status, which is the first failed contract's `return 1`, and every contract's own ✓ line. + self.assertIn("RC:0", out, out) + for contract in ("tv-session direct-screen contract", + "tv-session by-id contract (grammar, a title's element needs --rk, nonce match)", + "tv-session FIFO quoting (any one-word token is sent as one remote word; a token with whitespace is not sent)", + "tv-session key door (focus:/press:/state: only through their verbs; a refusal sends nothing)", + "tv-session usage text (the whole command and option list, ending on --keep)", + "tv-session identity contract"): + self.assertIn(contract, out) + + if __name__ == "__main__": unittest.main() diff --git a/docs/DESIGN.md b/docs/DESIGN.md index e3ce31c2f2..3bed1fb99c 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -186,7 +186,15 @@ the episode strip's `EPISODE` look, its caption band and `StillFooter::Shelf`. holds focus (`HomeScreen::row_holds_focus`), and it restarts at its full length when focus returns to the hero. A page that rests at the hero while a Continue Watching card is focused (the row scrolls nothing) therefore keeps its billboard still and presents nothing once settled, as it always did when focus on a - row scrolled the page off the hero (the `home-idle` scene grades it). + row scrolled the page off the hero (the `home-idle` scene grades it). A press standing on a hero control + (its dip, about 200 ms: Play, Info or the bookmark disc; `HomeScreen::hero_press_armed`, read from the press + machine) restarts the countdown at its full length every tick, as a focus move does, so no turn falls due + inside the press and none is owed once it has settled: the next one comes a full interval after the press, + not on the first tick after Play or Info, which is often the person's return to Home. A press therefore acts + on the title it was armed on (unless a landing takes that title out of the hero pool inside the dip: the press + then acts on its successor). `HomeCmd::Flip` and Left/Right at the hero's edge are REFUSED while the press + stands (the page answers `Handled::No` and the turn is dropped, not applied when the press settles), so the + caller sends them again once it has. Tile text is `TileLabel::title(t)` or `TileLabel::titled(t, caption)`, with the focused-label band driven by `line_reveal_for` and `under_band` (a line shows once the room under its card holds its diff --git a/docs/agent-reference.md b/docs/agent-reference.md index 61084e49d2..12e8e5edf8 100644 --- a/docs/agent-reference.md +++ b/docs/agent-reference.md @@ -2704,7 +2704,24 @@ path. Never run only this one before a release. `tests/README.md` has the tier t in authored 1920x1080 coords, and they replay through the real key/pointer handlers. `ok` is a TAP (both edges at once); **`okdown` / `okup` are the split halves**, which is the only way to drive a press-and-**hold** — `okdown`, sleep past `press::LONG_MS` (500 ms), `okup` opens the - item context menu; + item context menu; a debug build also takes `focus:`, `press:[@]` and + `state:` (the structured readback `plxnative-a11y.json`, beside `focusprobe`'s fingerprint), + via `tools/tv-session.sh focus|press|state` or `tools/a11y.py`. A press of an element that ACTS ON a title it + names (it plays, restarts, finishes or retries it, marks it watched or unwatched, bookmarks it, or opens that + title's own page or menu where the title can change under the press, as a card, a credit or the Home + carousel's Info do) names the title: `--rk ` on `tv-session.sh press`, `--subject ` on + `a11y.py press` (`send press:@`), the ratingKey of the title the press acts on, which `state` + prints as the element's subject. Those THREE command lines refuse the unnamed press (exit 2, nothing sent); only + a control whose target the page fixes (Go to Show, Also available, the Play Version opener, More, a panel + opener, a seek) is pressed bare, and `SUBJECT_BEARING` in `tools/a11y.py` is the one list of the ids. The + guard is on the command lines only: the library functions `a11y.press()` and `a11y.press_token()` are + unguarded on purpose, for scripts that drive the mock, so a script that imports them against a real server has + no check at all. + `tv-session.sh key` and `a11y.py send` are not a way round that: `key` refuses a `focus:`, `press:` or + `state:` word (the three verbs are the one door for them), and both refuse a word with whitespace in it + (the app cuts the FIFO at any whitespace, so `back press:` would be a second, unchecked token). + Prefer them over a key walk to a + target; walks remain for tests whose subject is travel (fps walks, focus fingerprints); With `devtriggers`, `hang:` stalls the frame thread under the `dev hang probe` guard and `hang-raw:` sleeps without a label; both accept unsigned decimal u64 milliseconds capped at 5000, via `tools/tv-session.sh key hang:1000` or `key hang-raw:1000` with the existing TV lock. diff --git a/rust-modules/appkit/src/more_menu.rs b/rust-modules/appkit/src/more_menu.rs index e7164febc2..659cff5742 100644 --- a/rust-modules/appkit/src/more_menu.rs +++ b/rust-modules/appkit/src/more_menu.rs @@ -944,6 +944,19 @@ where } } +impl MoreMenuPart<'_> { + /// **What a press of the row `key` performs**, for a row that performs one (the Quality and Speed drill-ins + /// open a page and have none): the row's [`Action`], read off the form's binding the way `a11y` reads + /// its id. The overlay screen asks it to name the title a folded row plays. + pub fn action_at(&self, key: &E) -> Option { + let form = &self.state.form; + match form.binding_at(form.index_of_key(RowKey(key.index()?))?)?.id { + MoreRow::Act(action) => Some(action), + MoreRow::OpenQuality | MoreRow::OpenSpeed => None, + } + } +} + impl Part for MoreMenuPart<'_> where H::Elem: IndexElem, diff --git a/rust-modules/appkit/src/player_hud/command.rs b/rust-modules/appkit/src/player_hud/command.rs index 89539613b8..2c699091c4 100644 --- a/rust-modules/appkit/src/player_hud/command.rs +++ b/rust-modules/appkit/src/player_hud/command.rs @@ -173,6 +173,31 @@ impl HudCommand { } } + /// **The ratingKey a press of this command plays or restarts**, read off the session the way the app's + /// performer reads it (`app::playback::perform_hud_command`): a queue step plays the row + /// [`queue_neighbor`](plx_media::route::queue_neighbor) names, a restart plays the item now playing + /// ([`cur_rk`](plx_media::route::cur_rk)). `None` for a command that starts no title (a seek, a panel + /// opener) and for a press that would start nothing (no neighbour, an item with no key). This is what an + /// accessibility id's subject names for a control that changes or restarts what plays, so a harness press + /// of it must say which title it means (`tools/a11y.py`, `SUBJECT_BEARING`). A pure read of the session's + /// own memory: no IO. + pub fn plays_rk(self, ps: &plx_media::route::PlaybackSession) -> Option { + use plx_media::route::{cur_rk, queue_neighbor, QueueStep}; + let rk = match self { + HudCommand::Previous => queue_neighbor(ps, QueueStep::Previous)?.rk, + HudCommand::Next => queue_neighbor(ps, QueueStep::Next)?.rk, + HudCommand::FromBeginning => cur_rk(ps), + HudCommand::TogglePlay + | HudCommand::Seek(_) + | HudCommand::OpenTracks(_) + | HudCommand::OpenMore(_) + | HudCommand::ToggleSection(_) + | HudCommand::GoToDetail + | HudCommand::ToggleStats => return None, + }; + (!rk.is_empty()).then_some(rk) + } + /// **Is a press of this command meaningful now?** The table's "Enabled" column, from the /// frame's [`HudModel`] alone. pub fn enabled(self, model: &HudModel) -> bool { diff --git a/rust-modules/appkit/src/player_hud/loaded.rs b/rust-modules/appkit/src/player_hud/loaded.rs index 9a6432c6fb..5b7af2e2ee 100644 --- a/rust-modules/appkit/src/player_hud/loaded.rs +++ b/rust-modules/appkit/src/player_hud/loaded.rs @@ -118,6 +118,20 @@ pub fn reference_with_info_actions_for_test() -> Arc { .compiled } +/// **The reference package whose `fwd` control carries `command`** instead of its seek (`"next"`, `"toggle_play"`): +/// the row then holds two controls with one command, so the second is named by its POSITION in an accessibility id +/// (`player.control.`) and not by its word. Loaded like [`reference_for_test`]. +#[cfg(any(test, feature = "test-support"))] +pub fn reference_with_forward_as_for_test(command: &str) -> Arc { + let text = include_str!("../hud_format/fixtures/reference/hud.json"); + let forward = r#"{ "id": "fwd", "command": "seek", "by": 30,"#; + assert_eq!(text.matches(forward).count(), 1, "the reference fixture has one forward seek"); + let replaced = text.replace(forward, &format!(r#"{{ "id": "fwd", "command": "{command}","#)); + load(&crate::hud_format::fixtures::with_hud("reference", &replaced), "0.0.0-test", plx_platform::i18n::english(), &plx_ui::fixture::FixtureMeasure) + .expect("the reference fixture with a replaced forward control loads") + .compiled +} + /// **The reference with its Chapters and Info discs taken out of the row**, under `policy` (`"modal"` or `"inline"`): the /// two section bands stay, so both sections are laid out, and the package places no opener for either. A More fold /// row is the only way to either section. Loaded like [`reference_for_test`]. diff --git a/rust-modules/appkit/src/track_menu.rs b/rust-modules/appkit/src/track_menu.rs index 2cb427a325..d019ded370 100644 --- a/rust-modules/appkit/src/track_menu.rs +++ b/rust-modules/appkit/src/track_menu.rs @@ -339,6 +339,31 @@ impl FormId for TrackRow { } impl TrackRow { + /// **Does a press of this row WRITE to the playing title on the server?** A track pick selects the part's streams on + /// the PMS (`route`'s `select_streams`, `PUT /library/parts/{id}`: the transcoder encodes the SELECTED audio and burns + /// the SELECTED subtitle) and a search result installs its subtitle on the item (`PUT /library/metadata/{rk}/subtitles`), + /// so the overlay screen names the title playing on those rows (the harness's `press ... --rk`). Every other row + /// opens a page, picks a local setting (Style, Timing, the search language) or reconfigures the live stream (Boost + /// dialog, Normalize loudness) and writes nothing of the title's. An exhaustive match, so a new row cannot compile + /// without the decision. + pub fn writes_title(&self) -> bool { + match *self { + TrackRow::Audio(_) | TrackRow::SubOff | TrackRow::SubForcedOnly | TrackRow::Sub(_) | TrackRow::SearchHit(_) => true, + TrackRow::Boost + | TrackRow::Loudness + | TrackRow::Timing + | TrackRow::Style + | TrackRow::OpenOther + | TrackRow::OpenLang(_) + | TrackRow::OpenField(_) + | TrackRow::Choice(..) + | TrackRow::OpenSearch + | TrackRow::SearchLang + | TrackRow::SearchRetry + | TrackRow::LangChoice(_) => false, + } + } + /// **The row's name in the menu's accessibility ids** (`plx_ui::a11y`), relative to the menu: /// what the row IS, and the index it already carries when it is one of a list (`audio.`, /// `sub.`, `hit.`, `lang.`, `language.`). A singleton is its word: `boost`, @@ -2453,6 +2478,18 @@ where } } +impl TrackMenuPart<'_> { + /// **Does a press of the row `key` write to the playing title** ([`TrackRow::writes_title`]), read off the form's + /// binding the way `a11y` reads its id. The overlay screen asks it to name the title playing on those rows. + pub fn writes_title_at(&self, key: &E) -> bool { + let form = &self.state.form; + key.index() + .and_then(|index| form.index_of_key(RowKey(index))) + .and_then(|at| form.binding_at(at)) + .is_some_and(|binding| binding.id.writes_title()) + } +} + impl Part for TrackMenuPart<'_> where H::Elem: IndexElem, diff --git a/rust-modules/media/src/route/decision.rs b/rust-modules/media/src/route/decision.rs index cad1c067f0..54011dc2e1 100644 --- a/rust-modules/media/src/route/decision.rs +++ b/rust-modules/media/src/route/decision.rs @@ -7125,6 +7125,35 @@ pub fn cur_sid(ps: &PlaybackSession) -> ServerId { pub fn swap_cur_sid_for_test(ps: &mut PlaybackSession, sid: ServerId) -> ServerId { { let s = &mut *ps; std::mem::replace(&mut s.cur_sid, sid) } } +/// Test-only: install the playing item's ratingKey, the queue it came from and its Up Next directly. +/// +/// In production the three have one writer, `apply_plan` (the queue and Up Next from the plan's `QueueInfo`), so a suite +/// elsewhere that needs "this episode is playing, with a neighbour on each side" sets it through here, as it sets the +/// server through [`swap_cur_sid_for_test`]. The player's accessibility ids read the neighbours and the key it +/// hands them (`HudCommand::plays_rk`). +#[cfg(any(test, feature = "test-support"))] +pub fn seed_queue_for_test(ps: &mut PlaybackSession, cur_rk: &str, rows: Vec, up_next: Option) { + ps.cur_rk = cur_rk.to_owned(); + ps.queue = rows; + ps.up_next = up_next.map(std::sync::Arc::new); +} +/// Test-only: record the request a Try again repeats ([`retry_rk`]) without a plan having landed, as a play that is +/// asked for and fails before `apply_plan` leaves the session. Does not touch `cur_rk`. +#[cfg(any(test, feature = "test-support"))] +pub fn seed_request_for_test(ps: &mut PlaybackSession, rk: &str) { + ps.request = Some(PlaybackRequest { + sid: ServerId::UNSET, + rk: rk.to_owned(), + part: String::new(), + vcodec: String::new(), + acodec: String::new(), + title: String::new(), + ctx: String::new(), + preview: false, + version: None, + show_rk: String::new(), + }); +} /// The `Client` for the currently-playing item's server, `None` before the first play (or after a /// plan that never resolved). The main-thread twin of `client_for(env.sid)` on the resolve worker /// — every in-playback PMS call in this file goes through one of the two, and none through @@ -10889,6 +10918,15 @@ pub fn can_retry_current_play(ps: &PlaybackSession) -> bool { ps.request.is_some() } +/// The ratingKey [`retry_current_play`] resolves again: the key of the request this session last made, which a Try +/// again, a Play automatically and a quality pick on the failure read-out all repeat. It is NOT [`cur_rk`]: the +/// request is recorded when the play is asked for and `cur_rk` only when its plan lands (`apply_plan`), so a play +/// that failed before its plan landed has the request's key here and none (or the previous item's) there. `None` +/// when no request was made (URL and dev-trigger playback), which has nothing to retry. +pub fn retry_rk(ps: &PlaybackSession) -> Option { + ps.request.as_ref().map(|request| request.rk.clone()).filter(|rk| !rk.is_empty()) +} + /// Resume target not yet proven by a presented frame. A refused retry keeps this so the next /// quality choice can try again at the same point. pub fn unpresented_resume_ns(ps: &PlaybackSession) -> i64 { diff --git a/rust-modules/screens/src/detail/mod.rs b/rust-modules/screens/src/detail/mod.rs index 6cd7e474b6..f99e7977f5 100644 --- a/rust-modules/screens/src/detail/mod.rs +++ b/rust-modules/screens/src/detail/mod.rs @@ -1987,7 +1987,10 @@ impl Focusable f /// linked heading `collection.heading` and the About footer's two stops `about.card` and /// `about.languages`. An index is a position in the collection its segment names, so a card or an /// episode off screen has its id as well. The `subject` of a season, an episode or a card is its - /// ratingKey. + /// ratingKey, and so is the subject of each hero control that PLAYS or WRITES to a title: the + /// ratingKey it acts on ([`hero_control_subject`]), which on a show that has been started is the + /// on-deck episode, not the page's. A control whose target the page fixes (it only navigates or opens + /// a menu) has none. fn a11y(&self, key: &u32, cx: &Cx<'_, H>) -> Option> { let meta = H::metadata(cx); let located = self.locate(*key, meta).filter(|l| self.valid(*l, meta))?; @@ -1997,7 +2000,13 @@ impl Focusable f // projection outlives the borrow of the views (a read-side state file only) let with_subject = |a: A11y<'static>, rk: &str| if rk.is_empty() { a } else { a.with_subject(rk.to_owned()) }; Some(match located { - Located::Hero(ctl) => A11y::new(named("hero").name(ctl.a11y_name()), A11yRole::Button), + Located::Hero(ctl) => { + let a = A11y::new(named("hero").name(ctl.a11y_name()), A11yRole::Button); + match d.and_then(|d| hero_control_subject(ctl, d, self.selected())) { + Some(rk) => with_subject(a, rk), + None => a, + } + } Located::Season(i) => { let season = d?.seasons.get(i)?; let a = A11y::new(named("season").index(i), A11yRole::Tab).with_label(season.title.clone()); @@ -4688,7 +4697,7 @@ impl DetailScreen { StoreId::ViewState, StoreCmd::ViewState(ViewStateCmd::Request { sid: d.sid, - rk: hero::hero_episode(d).map_or_else(|| d.rk.clone(), |ep| ep.rk.clone()), + rk: hero_control_subject(ctl, d, None).map_or_else(|| d.rk.clone(), str::to_owned), // The watched action follows the episode displayed by the hero. scope: hero_mark_scope(d), write: if ctl == hero::HeroCtl::MarkWatched { @@ -4832,6 +4841,42 @@ impl DetailScreen { } +/// **The ratingKey a hero control acts on**: the accessibility `subject` of each control that plays a +/// title or writes to one, so the harness's guard can make a press name the title it is about (the rule is +/// never to press OK on a title whose ratingKey you have not read). It is what the activation itself +/// reads, not the route's key: Play and Restart play [`Detail::play_episode`] on a show page, the loaded +/// card (`selected`) or the page's item on any other; the watched toggle writes the on-deck episode of a +/// show that has been started, else the page's item; the bookmark and the trailer act on the page's item. +/// `None` for the controls that only navigate or open a menu or a panel (Go to Show, Also available, Play +/// Version, More): the control itself acts on no title. The panel or menu one of them opens has rows of its +/// own, each guarded by its own subject: a library item's menu (`itemmenu.*`) carries its title's key, and the +/// Play Version panel's `versions.row.` (`versions_panel.rs`, OK delivers `AppMsg::PlayVersion`, which plays) +/// carries [`play_subject`], this function's answer for Play. Exhaustive, so a new control must be placed here. +pub(crate) fn hero_control_subject<'a>( + ctl: hero::HeroCtl, + d: &'a Detail, + selected: Option<&'a plx_data::pms::PmsMovie>, +) -> Option<&'a str> { + use hero::HeroCtl; + match ctl { + HeroCtl::Play | HeroCtl::Restart => Some(if d.is_show { + d.play_episode().map_or(d.rk.as_str(), |ep| ep.rk.as_str()) + } else { + selected.map_or(d.rk.as_str(), |m| m.rk.as_str()) + }), + HeroCtl::MarkWatched | HeroCtl::MarkUnwatched => Some(hero::hero_episode(d).map_or(d.rk.as_str(), |ep| ep.rk.as_str())), + HeroCtl::Watchlist | HeroCtl::Trailer => Some(d.rk.as_str()), + HeroCtl::GoToShow | HeroCtl::Alt | HeroCtl::Version | HeroCtl::More => None, + } +} + +/// **The ratingKey the hero's Play plays** ([`hero_control_subject`] of Play, with no loaded card to prefer): what the +/// Play Version panel's rows play too, since a committed row plays the hero's title in that version +/// (`AppMsg::PlayVersion`, [`DetailScreen::play_hero`]). +pub(crate) fn play_subject(d: &Detail) -> Option<&str> { + hero_control_subject(hero::HeroCtl::Play, d, None) +} + /// The versions the hero's Play chooses among, for its Play Version disc and panel: the page's /// own movie or episode, or on a show page the episode its Play plays. pub(crate) fn hero_versions(d: &Detail) -> &[plx_data::pms::MediaVersion] { diff --git a/rust-modules/screens/src/detail/tests.rs b/rust-modules/screens/src/detail/tests.rs index acdf10910c..2b23c6792e 100644 --- a/rust-modules/screens/src/detail/tests.rs +++ b/rust-modules/screens/src/detail/tests.rs @@ -5733,6 +5733,168 @@ fn pdf_proposal_on_deck_watched_action_targets_one_episode() { plx_plex::plex::reset_servers_for_test(); } +/// The hero row's elements as `(id, subject)`, in the row's order. +fn hero_subjects(screen: &DetailScreen) -> Vec<(String, Option)> { + let measure = plx_ui::fixture::FixtureMeasure; + let context = cx(&measure, None); + let mut keys = Vec::new(); + Focusable::::a11y_elems(screen, hero::HERO_GROUP, &context, &mut keys); + keys.iter() + .map(|key| { + let a = Focusable::::a11y(screen, key, &context).expect("a hero control projects"); + (a.path.to_string(), a.subject.map(|rk| rk.into_owned())) + }) + .collect() +} + +fn named<'a>(row: &'a [(String, Option)], id: &str) -> Option<&'a str> { + row.iter().find(|(path, _)| path == id).and_then(|(_, subject)| subject.as_deref()) +} + +/// **Every hero control that plays a title or writes to one names the title it acts on**, so the harness +/// can make a press say which title it means. On a show that has been STARTED that is the on-deck +/// episode, not the page's key: Play and Restart play it, the watched toggle writes it, and only the +/// bookmark acts on the page's own item. The controls that open a menu or a panel carry none. +#[test] +fn a_started_shows_hero_controls_name_the_on_deck_episode_they_act_on() { + let two = || plx_appkit::version_list::sample().into_iter().take(2).collect::>(); + let on_deck = plx_data::metadata::Episode { resume_ms: 30_000, versions: two(), ..episode("e2", 2) }; + let mut d = detail(ServerId::UNSET, "show"); + d.guid = "plex://show/5d77680135a8fc45188ba331".into(); + d.episodes = vec![episode("e1", 1), on_deck.clone()].into(); + d.on_deck = Some(on_deck); + let _guard = install(d); + let screen = bare(&_guard, ServerId::UNSET, "show"); + let row = hero_subjects(&screen); + let owned = |id: &str, rk: Option<&str>| (id.to_string(), rk.map(str::to_string)); + assert_eq!( + row, + vec![ + owned("hero.play", Some("e2")), + owned("hero.watchlist", Some("show")), + owned("hero.restart", Some("e2")), + owned("hero.mark_watched", Some("e2")), + owned("hero.version", None), + owned("hero.more", None), + ] + ); + clear(); +} + +/// A show nobody has started: Play plays the season's first episode, and the toggle writes the WHOLE show +/// (the page's own key), because no episode is the hero's subject yet. +#[test] +fn an_unstarted_shows_play_names_its_first_episode_and_its_toggle_the_show() { + let mut d = detail(ServerId::UNSET, "show"); + d.guid = "plex://show/5d77680135a8fc45188ba331".into(); + let _guard = install(d); + let screen = bare(&_guard, ServerId::UNSET, "show"); + let row = hero_subjects(&screen); + assert_eq!(named(&row, "hero.play"), Some("e1")); + assert_eq!(named(&row, "hero.mark_watched"), Some("show")); + assert_eq!(named(&row, "hero.watchlist"), Some("show")); + clear(); +} + +/// A movie page, and an episode's page (the Go to Show disc is there and only navigates). +#[test] +fn a_movie_and_an_episode_page_name_their_own_item_and_go_to_show_names_none() { + let _guard = install(Detail { + sid: ServerId::UNSET, + rk: "movie".into(), + kind: "movie".into(), + guid: "plex://movie/5d77680135a8fc45188ba331".into(), + resume_ms: 30_000, + dur_ms: 600_000, + ..Default::default() + }); + let screen = bare(&_guard, ServerId::UNSET, "movie"); + let row = hero_subjects(&screen); + for id in ["hero.play", "hero.watchlist", "hero.restart", "hero.mark_watched"] { + assert_eq!(named(&row, id), Some("movie"), "{id}"); + } + clear(); + drop(_guard); + + let _guard = install(episode_naming_its_show()); + let screen = bare(&_guard, ServerId::UNSET, "ep"); + let row = hero_subjects(&screen); + assert_eq!(named(&row, "hero.play"), Some("ep")); + assert_eq!(named(&row, "hero.mark_watched"), Some("ep")); + assert!(row.contains(&("hero.go_to_show".to_string(), None)), "Go to Show only navigates: {row:?}"); + clear(); +} + +/// The subject is the key the press ACTS on, read off the effect it pushes: the on-deck episode's for Play +/// and for the watched toggle, and the loaded card's for a movie page that holds one. +#[test] +fn a_hero_controls_subject_is_the_rating_key_its_activation_acts_on() { + let _guard = plx_base::testlock::serial(); + plx_plex::plex::reset_servers_for_test(); + let sid = plx_plex::plex::register_for_test("hero-subject", "127.0.0.1", 1, "t", "c"); + let on_deck = plx_data::metadata::Episode { rk: "next-episode".into(), resume_ms: 60_000, dur_ms: 120_000, ..episode("next-episode", 3) }; + let mut d = Detail { sid, rk: "show".into(), is_show: true, kind: "show".into(), ..Default::default() }; + d.episodes = vec![episode("first", 1), on_deck.clone()].into(); + d.on_deck = Some(on_deck); + plx_data::metadata::set_current_for_test(test_store().state_mut(), Some(d)); + let mut screen = bare(&_guard, sid, "show"); + let subject = |screen: &DetailScreen, id: &str| named(&hero_subjects(screen), id).map(str::to_string); + + let (_, effects) = step(&mut screen, &ScreenEvent::Activate(hero::ELEM_PLAY), Some(hero::ELEM_PLAY)); + let played = match play_item(&effects) { + Some((PlayIntent::Item { rk, .. }, _)) => rk.clone(), + Some((PlayIntent::Movie { item, .. }, _)) => item.rk.clone(), + None => panic!("Play pushes a play request"), + }; + assert_eq!(subject(&screen, "hero.play").as_deref(), Some(played.as_str())); + assert_eq!(played, "next-episode"); + + let (_, effects) = step(&mut screen, &ScreenEvent::PressCommit(plx_machine::machine::PressId(1)), Some(hero::ELEM_MARK_WATCHED)); + let marked = effects.iter().find_map(|effect| match &effect.fx { + Fx::App(AppFx::Store(StoreId::ViewState, StoreCmd::ViewState(ViewStateCmd::Request { rk, .. }))) => Some(rk.clone()), + _ => None, + }).expect("one watched request"); + assert_eq!(subject(&screen, "hero.mark_watched").as_deref(), Some(marked.as_str())); + clear(); + plx_plex::plex::reset_servers_for_test(); + drop(_guard); + + // a movie page that holds the card it was opened from plays THAT card's key + let _guard = install(Detail { sid: ServerId::UNSET, rk: "movie".into(), kind: "movie".into(), ..Default::default() }); + let mut screen = bare(&_guard, ServerId::UNSET, "movie"); + screen.selected = Some(plx_data::pms::PmsMovie { rk: "card".into(), ..Default::default() }); + let (_, effects) = step(&mut screen, &ScreenEvent::Activate(hero::ELEM_PLAY), Some(hero::ELEM_PLAY)); + let played = match play_item(&effects) { + Some((PlayIntent::Movie { item, .. }, _)) => item.rk.clone(), + Some((PlayIntent::Item { rk, .. }, _)) => rk.clone(), + None => panic!("Play pushes a play request"), + }; + assert_eq!(played, "card"); + assert_eq!(subject(&screen, "hero.play").as_deref(), Some("card")); + clear(); +} + +/// Every control is placed: the ones that play or write have a subject, the ones that only navigate or open +/// a menu or a panel have none (the trailer disc is not shown today, so only this table reaches it). +#[test] +fn the_hero_controls_that_play_or_write_have_a_subject_and_the_rest_have_none() { + let d = detail(ServerId::UNSET, "show"); + for (ctl, acts) in [ + (hero::HeroCtl::Play, true), + (hero::HeroCtl::Restart, true), + (hero::HeroCtl::Trailer, true), + (hero::HeroCtl::MarkWatched, true), + (hero::HeroCtl::MarkUnwatched, true), + (hero::HeroCtl::Watchlist, true), + (hero::HeroCtl::GoToShow, false), + (hero::HeroCtl::Alt, false), + (hero::HeroCtl::Version, false), + (hero::HeroCtl::More, false), + ] { + assert_eq!(hero_control_subject(ctl, &d, None).is_some(), acts, "{}", ctl.a11y_name()); + } +} + // ---- the Go to Show disc on an episode's page ------------------------------------------------ fn episode_naming_its_show() -> Detail { @@ -5859,6 +6021,7 @@ pub(crate) fn detail_conforms() -> plx_ui::a11y::Namespaces { assert_eq!(find("hero.play"), Some(hero::ELEM_PLAY)); assert_eq!(project(hero::ELEM_PLAY).role, Role::Button); + assert_eq!(project(hero::ELEM_PLAY).subject.as_deref(), Some("e1"), "Play plays the first episode of a show not yet started"); assert_eq!(find("hero.nope"), None); for (i, rk) in ["s1", "s2", "s3"].into_iter().enumerate() { let elem = find(&format!("season.{i}")).expect("a season tab"); diff --git a/rust-modules/screens/src/home/hero_shade_tests.rs b/rust-modules/screens/src/home/hero_shade_tests.rs index 2b16901e9e..e63f3fa73c 100644 --- a/rust-modules/screens/src/home/hero_shade_tests.rs +++ b/rust-modules/screens/src/home/hero_shade_tests.rs @@ -111,7 +111,7 @@ fn the_pager_slides_with_the_page_it_belongs_to() { }; let rest = chevrons(&s); assert_eq!(rest.len(), 1, "a settled billboard draws one pager"); - assert!(s.flip(view, 1)); + assert!(s.flip(view, 1, &plx_machine::machine::PressRead::default())); for slide in [0.25, 0.5, 0.75] { s.hero_slide.jump(slide); let (out_x, in_x) = s.slide_offsets().unwrap(); diff --git a/rust-modules/screens/src/home/hero_watchlist_tests.rs b/rust-modules/screens/src/home/hero_watchlist_tests.rs index b69986ba52..9053b8a1be 100644 --- a/rust-modules/screens/src/home/hero_watchlist_tests.rs +++ b/rust-modules/screens/src/home/hero_watchlist_tests.rs @@ -131,6 +131,53 @@ fn an_episode_hero_adds_its_show() { assert_eq!(item_menu_act(&out), Some(Action::WatchlistAdd { hex: HEX_SHOW })); } +/// Every hero control's `(id, subject)`, in row order. +fn hero_subjects(s: &HomeScreen, view: HubsView<'_>) -> Vec<(String, Option)> { + let c = cx(view, None); + let mut elems = Vec::new(); + Focusable::::a11y_elems(s, HERO_GROUP, &c, &mut elems); + elems + .iter() + .map(|e| { + let a = Focusable::::a11y(s, e, &c).expect("a hero control projects"); + (a.path.to_string(), a.subject.map(|t| t.into_owned())) + }) + .collect() +} + +/// **A hero control names the title it acts on.** The carousel advances by itself, so a bare +/// `press home.hero.play` would play whatever is showing at that frame: Play, the disc and Info all carry +/// the ratingKey of the hero item shown now (the one every activation reads), and it follows the carousel. +#[test] +fn every_hero_control_names_the_shown_hero_as_its_subject() { + let _guard = plx_base::testlock::serial(); + let snapshot = seeded(true); + let view = snapshot.view(); + let mut s = screen(view); + let shown = |s: &HomeScreen| hero_subjects(s, view); + let want = |rk: &str| { + ["hero.play", "hero.watchlist", "hero.info"].map(|id| (id.to_string(), Some(rk.to_string()))).to_vec() + }; + assert_eq!(shown(&s), want("1"), "the first hero"); + step(&mut s, view, None, &ScreenEvent::App(AppMsg::Home(HomeCmd::PinHero(1)))); + tick(&mut s, view, 1); + assert_eq!(shown(&s), want("2"), "the subject follows the carousel"); +} + +/// The failure read-out's lone action acts on no title, so it names none (and a hero item with no +/// ratingKey has none to name). +#[test] +fn the_failure_readouts_action_names_no_subject() { + let _guard = plx_base::testlock::serial(); + let mut state = plx_data::pms::PmsState::default(); + let adapter = std::sync::Arc::new(plx_data::pms::PmsAdapter::default()); + plx_data::pms::seed_for_test(&mut state, &adapter, 0, plx_data::pms::HubState::Failed); + let snapshot = plx_data::pms::hubs_snapshot(&state); + let view = snapshot.view(); + let s = screen(view); + assert_eq!(hero_subjects(&s, view), vec![("hero.action".to_string(), None)]); +} + /// The first answer for an already-listed title snaps the fill: nothing flips on open. #[test] fn an_already_listed_title_does_not_flip_on_open() { @@ -160,7 +207,7 @@ fn rotating_the_hero_does_not_flip() { let mut s = screen(view); tick(&mut s, view, 1); s.set_watchlist(HEX_A, Membership::On); - assert!(s.flip(view, 1)); + assert!(s.flip(view, 1, &plx_machine::machine::PressRead::default())); tick(&mut s, view, 1); assert_eq!(s.watchlist_hex(), Some(HEX_B)); s.set_watchlist(HEX_B, Membership::Off); @@ -244,7 +291,7 @@ fn a_vanished_disc_returns_focus_to_play() { let mixed = plx_data::pms::hubs_snapshot(&state); let mview = mixed.view(); let mut m = screen(mview); - assert!(m.flip(mview, 1)); + assert!(m.flip(mview, 1, &plx_machine::machine::PressRead::default())); let want = key(&m, HERO_WATCHLIST_ELEM); assert_eq!(Focusable::::reconcile(&m, want, &cx(mview, Some(want))).elem, HERO_PLAY_ELEM); } diff --git a/rust-modules/screens/src/home/mod.rs b/rust-modules/screens/src/home/mod.rs index 5cb3601f63..6bab396949 100644 --- a/rust-modules/screens/src/home/mod.rs +++ b/rust-modules/screens/src/home/mod.rs @@ -32,7 +32,7 @@ use plx_ui::landing_hero::{ }; use plx_machine::machine::{ Canon, Cx, Delivery, Edge, Effects, EntryId, FocusKey, Fx, GroupId, Handled, InputEvent, - InputKind, InstanceId, Key, LogicalState, Machine, MachineId, Measure, Tick, + InputKind, InstanceId, Key, LogicalState, Machine, MachineId, Measure, PressRead, Tick, }; use plx_machine::present::{PresentEvent, Provenance}; use plx_ui::screen::{ @@ -804,6 +804,9 @@ pub struct HomeScreen { reveal_press: Option, /// Stable element still visible while the engine has already crossed the hero/grid door. /// This is a press landing policy, not current focus, and retires at the visual midpoint. + /// It exists for a hand on the remote: a `By::Script` arrival (a by-id press, which names its + /// element) clears it, and while it holds, the focused element's `a11y` is not loaded + /// (`Self::a11y`), so a by-id press of it is refused as `unloaded` until the picture catches up. visible_activation: Option, cta_available: bool, strip_chosen: bool, @@ -1582,9 +1585,48 @@ impl HomeScreen { .unwrap_or(0) } - fn flip(&mut self, view: HubsView<'_>, dir: i32) -> bool { + /// **Is a press standing on one of this page's hero controls?** Read from the press machine + /// through the context, never mirrored: [`PressRead::live`] (a press that can still commit, and + /// through its commit: it ends with the spring-back, not at the commit) and its `owner` (the + /// element the press was armed on, retained after the arm is gone), and the owner is a hero + /// control when [`Self::locate`] says so. + /// + /// **Why the billboard holds for it.** A hero control's press (Play, Info, the bookmark disc) + /// commits about 200 ms after OK goes down (the release is held for `MIN_DIP_MS`, 90 ms, and the + /// commit follows it by `COMMIT_MS`, 120 ms), and its `activate` re-reads the title the + /// billboard shows AT THE COMMIT ([`Self::selected_hero`]), because the press armed on an + /// element, not on a title. Pressing the control that already holds focus moves no focus, so + /// nothing restarted the 8 s countdown: if it ran out inside the dip, the carousel turned and the + /// press that was accepted against one title (a person's OK a moment before the flip; a scripted + /// `press home.hero.play --rk X`) played the next page's. While this is true the countdown + /// restarts from its full length every tick ([`Self::restart_hero_countdown`], the reset a focus + /// move already makes), so no turn falls due inside the press and none is OWED once it has + /// settled: the next one comes a full interval later, not on the first tick after Play or Info + /// when the person is coming back to Home. [`Self::flip`] refuses as well, for the writers the + /// countdown does not drive. + fn hero_press_armed(&self, press: &PressRead) -> bool { + press.live && matches!(self.focused_loc(press.owner), Some(Located::Hero(_))) + } + + /// Start the 8 s countdown again from its full length: the ONE reset. A turn (`flip`), an + /// uncover, a focus move by a person or a script, a page that is off the hero or has a shelf + /// holding focus, and a press standing on a hero control ([`Self::hero_press_armed`]) all end + /// here, so "what restarts the carousel's clock" has one spelling. + fn restart_hero_countdown(&mut self) { + self.hero_auto = HERO_AUTO_S; + } + + /// Turn the billboard one page (`dir` is +1 or -1). **Every writer of the shown title that a person + /// or the countdown drives goes through here** (the 8 s auto-advance, `HomeCmd::Flip`, Left/Right at + /// the hero's edge), so the one refusal below, [`Self::hero_press_armed`], holds for all three. A + /// refused turn changes nothing and is not owed: the countdown has no turn pending for it (it + /// restarts while the press stands, in `tick`), and `HomeCmd::Flip` and an edge key are a request + /// the caller makes again once the press has settled. The two writers it does not cover are not a + /// person's: `HomeCmd::SelectHero` / `PinHero` (the dev scenarios' direct selection) and + /// [`Self::reconcile_carousel`] (the title LEFT the pool, which no press can hold). + fn flip(&mut self, view: HubsView<'_>, dir: i32, press: &PressRead) -> bool { let n = view.hero_count(); - if n <= 1 || self.hero_flip_cd > 0.0 { + if n <= 1 || self.hero_flip_cd > 0.0 || self.hero_press_armed(press) { return false; } let cur = self.carousel_index(view).min(n - 1); @@ -1601,7 +1643,7 @@ impl HomeScreen { self.hero_dir = dir as f32; self.hero_slide.jump(0.0); self.hero_flip_cd = HERO_FLIP_CD; - self.hero_auto = HERO_AUTO_S; + self.restart_hero_countdown(); // One line per page TURN (a key press or the 8 s advance, never a frame): the demo film // reads the pages it showed from these (`tools/site_video.py`, `hero_pool.logged`, `hero_pool.turns`). if let Some(page) = view.hero(next) { @@ -2001,13 +2043,26 @@ impl HomeScreen { // (~24 ms of GPU a frame on the TV), and the next transition's first frame paid that // queue in its `glClear`. // `a_settled_hero_counting_down_lets_the_gate_close_and_still_flips` holds both halves. - self.hero_auto = self.hero_auto - dt; - if self.hero_auto <= 0.0 { - self.hero_flip_cd = 0.0; - self.flip(view, 1); + // + // **A press standing on a hero control restarts the countdown** ([`Self::hero_press_armed`], + // read through `cx.press`), every tick of it, the way a focus move restarts it: the press + // is a deliberate interaction, and the page it was accepted against must still be the page + // it commits on. Nothing is owed afterwards. The next turn comes a full interval after the + // press settles, not on the first tick after Play or Info, which is often the person's + // return to Home. Only a press that stands on a hero control changes `hero_auto` here; a + // cancelled one, a shelf card's and another page's hero are `PressRead`s this page does + // not arm on, so the schedule with no press is the decrement below, bit for bit. + if self.hero_press_armed(&cx.press) { + self.restart_hero_countdown(); + } else { + self.hero_auto = self.hero_auto - dt; + if self.hero_auto <= 0.0 { + self.hero_flip_cd = 0.0; + self.flip(view, 1, &cx.press); + } } } else { - self.hero_auto = HERO_AUTO_S; + self.restart_hero_countdown(); } let snap_to = pinned_snap(self.snap_target, self.rows.len()); self.snap.step(snap_to, K_SNAP, dt); @@ -2230,7 +2285,7 @@ impl HomeScreen { ); } HomeCmd::Flip(direction) => { - if direction == 0 || !self.flip(H::hubs(cx), direction.signum()) { + if direction == 0 || !self.flip(H::hubs(cx), direction.signum(), &cx.press) { return Handled::No; } fx.invalidate(Provenance::Input); @@ -3250,37 +3305,36 @@ impl Focusable for HomeScreen { /// position in the page and `` the card's place in the row's LISTING (the hub's window offset /// plus its place in the window, `CardSource::global`), so a window that pages never gives one id /// to another title; the card's `subject` (its ratingKey) is what a press names to stay safe - /// when a publication moves them. A listing position the window does not hold is no element. + /// when a publication moves them. A hero control's `subject` is the ratingKey of the hero item it acts + /// on (the carousel advances by itself, so a press names the title it read); the failure read-out's + /// `hero.action` has none. While the picture still shows the other side of the hero/grid door + /// after a KEY crossed it, the focused element is not loaded, so a by-id press of it is refused as + /// `unloaded` (its press would land on the element the picture shows, `activation_elem`) until the + /// picture catches up (about 8 frames, 130 ms at 60 fps: the dive's midpoint). That projection + /// still carries the element's own label and subject, but the state file lists neither for an + /// element that is not loaded (`dispatch::snapshot`), so a reader of `state` sees `loaded: false` + /// and no subject until the door has settled. A listing position the window does not hold is no + /// element. fn a11y(&self, key: &u32, cx: &Cx<'_, H>) -> Option> { - // while the question is open its answers are the page's only elements - if let Some(answer) = self.plaintext_alert.a11y(*key) { - return answer; - } - let view = H::hubs(cx); - match self.locate(*key)? { - Located::Hero(slot) => { - if !self.hero_has(view, slot) { - return None; - } - let name = match slot { - _ if status_read(view).is_some() => "action", - 0 => "play", - 1 => "info", - _ => "watchlist", - }; - Some(A11y::new(A11yPath::new().name("hero").name(name), A11yRole::Button)) - } - Located::Heading(row) => { - let title = self.rows.get(row)?.title.as_str(); - Some(A11y::new(shelf_path(self.rows.get(row)?, row).name("heading"), A11yRole::Button).with_label(title)) - } - Located::Item(row, col) => { - let projection = self.rows.get(row)?; - // a slot whose card has not landed exists and can be focused, not pressed: it is - // not loaded, which `card_a11y` says by the same rule the shelf's draw skips it by - Some(ui_cards::card_a11y::(shelf_path(projection, row), &self.cards(view, row), col)) - } - } + let own = self.element_a11y(key, cx)?; + // A press on the engine's focused element lands where `activation_elem` says: while the picture + // still shows the other side of the hero/grid door after a KEY crossed it, that is the element + // the picture shows. A by-id press that names the focused element moves no focus + // (`FocusEngine::set` answers `Nothing`), so it cannot clear the remap the way a scripted + // arrival does (`[Down, press:X]`), and an element with no subject to compare (a linked + // heading) cannot be refused by it either. So the focused element is NOT PRESSABLE while its + // press would land elsewhere: `loaded: false`, which the dispatcher refuses as `unloaded` + // for any press, named or bare, until the picture catches up (the retry is the caller's). + // This projection keeps the element's own label and subject (it is still what the element + // is), but the state file lists an element that is not loaded without text (`snapshot.rs`), + // so a reader of `state` sees `loaded: false` and no subject, and asks again. `focus:` is + // unaffected (only a press asks `loaded`). Any other element is pressed where it stands, + // because a press moves focus to it first. + let focused = cx.focus.current.is_some_and(|f| f.entry == self.entry && f.elem == *key); + if focused && self.activation_elem(*key) != *key { + return Some(own.with_loaded(false)); + } + Some(own) } /// Every element of group `g` in index order: the hero's controls in ROW order, a shelf's cards @@ -3403,6 +3457,48 @@ impl HomeScreen { } } + /// An element's own projection, whatever the picture shows ([`Focusable::a11y`] is this one, but + /// not loaded while the press on the engine's focused element would land on another). + fn element_a11y(&self, key: &u32, cx: &Cx<'_, H>) -> Option> { + // while the question is open its answers are the page's only elements + if let Some(answer) = self.plaintext_alert.a11y(*key) { + return answer; + } + let view = H::hubs(cx); + match self.locate(*key)? { + Located::Hero(slot) => { + if !self.hero_has(view, slot) { + return None; + } + let name = match slot { + _ if status_read(view).is_some() => "action", + 0 => "play", + 1 => "info", + _ => "watchlist", + }; + let a = A11y::new(A11yPath::new().name("hero").name(name), A11yRole::Button); + // The ratingKey of the hero item the controls act on NOW (`selected_hero`, the one every + // activation reads), because the carousel advances by itself: a bare `press home.hero.play` + // plays whatever title is showing at that frame. The failure read-out's lone action acts + // on no title, and an item with no key has no subject to name. + Some(match self.selected_hero(view).map(|hero| hero.item.rk.as_str()).filter(|rk| !rk.is_empty() && name != "action") { + Some(rk) => a.with_subject(rk.to_owned()), + None => a, + }) + } + Located::Heading(row) => { + let title = self.rows.get(row)?.title.as_str(); + Some(A11y::new(shelf_path(self.rows.get(row)?, row).name("heading"), A11yRole::Button).with_label(title)) + } + Located::Item(row, col) => { + let projection = self.rows.get(row)?; + // a slot whose card has not landed exists and can be focused, not pressed: it is + // not loaded, which `card_a11y` says by the same rule the shelf's draw skips it by + Some(ui_cards::card_a11y::(shelf_path(projection, row), &self.cards(view, row), col)) + } + } + } + /// The hero controls in row order, as slots, and how many: the failure read-out's lone action, /// else Play, the bookmark disc when the selected title has one, then Info. fn hero_slots(&self, view: HubsView<'_>) -> ([usize; HERO_NBTN], usize) { @@ -3584,7 +3680,7 @@ impl Machine for HomeScreen { } ScreenEvent::Uncover => { self.covered = false; - self.hero_auto = HERO_AUTO_S; + self.restart_hero_countdown(); // **Damage only for what changed under the cover.** Raised unconditionally this // made Home redraw itself on the BACK commit of every glass menu: the page damage // retakes the host snapshot on the close's first frame, which is the frame that @@ -3624,7 +3720,15 @@ impl Machine for HomeScreen { self.feed_shelves(ev, cx, fx); let from_loc = from.and_then(|key| self.locate(key.elem)); let to_loc = self.locate(to.elem); - if let (Some(a), Some(b)) = (from_loc, to_loc) { + if *by == By::Script { + // A scripted arrival (a by-id `focus:`/`press:`) NAMES what the press that + // follows acts on, and the dispatcher queues that press in the same frame, before + // the dive has run a tick. The picture's remap is for a hand on the remote that + // has not yet seen the page move, so it never applies here, and one a key left + // behind does not survive the move either. The dive itself still runs: the + // remap is where a press lands, not the picture. + self.visible_activation = None; + } else if let (Some(a), Some(b)) = (from_loc, to_loc) { if self.on_grid_page(a) != self.on_grid_page(b) { self.visible_activation = from.map(|key| key.elem); } @@ -3672,7 +3776,7 @@ impl Machine for HomeScreen { self.strip_chosen = false; } if matches!(by, By::Dir | By::Pointer | By::Script) { - self.hero_auto = HERO_AUTO_S; + self.restart_hero_countdown(); } fx.invalidate(Provenance::Input); Handled::Yes @@ -3715,7 +3819,7 @@ impl Machine for HomeScreen { if let Some(shelf) = self.grid.shelves.get_mut(row) { shelf.reset_page_requests(); } } if matches!(self.focused_loc(cx.focus.current), Some(Located::Hero(_))) - && self.flip(H::hubs(cx), direction) + && self.flip(H::hubs(cx), direction, &cx.press) { fx.invalidate(Provenance::Input); Handled::Yes diff --git a/rust-modules/screens/src/home/tests.rs b/rust-modules/screens/src/home/tests.rs index 6be34d75c9..53175e6b9e 100644 --- a/rust-modules/screens/src/home/tests.rs +++ b/rust-modules/screens/src/home/tests.rs @@ -91,7 +91,20 @@ fn step( focus: Option>, event: &ScreenEvent, ) -> (Handled, Vec>, bool) { - let context = cx(view, focus); + step_pressed(s, view, focus, PressRead::default(), event) +} + +/// [`step`] with the press machine's read as `press` (the context a delivery runs with while a press +/// stands somewhere). +fn step_pressed( + s: &mut HomeScreen, + view: HubsView<'_>, + focus: Option>, + press: PressRead, + event: &ScreenEvent, +) -> (Handled, Vec>, bool) { + let mut context = cx(view, focus); + context.press = press; let mut out = Vec::new(); let mut present = plx_machine::present::Present::new(); let handled = { @@ -250,7 +263,7 @@ fn the_pager_is_not_a_focus_stop_and_the_rows_end_pages_instead() { Outcome::Edge(EdgeRule::Screen) ); let before = s.carousel.clone(); - assert!(s.flip(snapshot.view(), 1)); + assert!(s.flip(snapshot.view(), 1, &PressRead::default())); assert_ne!(s.carousel, before); assert_eq!(engine.current(owner).unwrap().elem, HERO_INFO_ELEM); } @@ -1787,6 +1800,307 @@ fn activation_across_the_snap_midpoint_is_not_a_canonical_collision() { "the same input activates different items, so these cannot be the same logical state"); } +// --- The hero/grid door: where a press LANDS -------------------------------------------------- +// +// A human's quick OK after a Dir key across the door lands on what the picture still shows +// (`visible_activation`); a by-id press names what it presses, so a scripted ARRIVAL clears that +// remap and lands on exactly the named element. A by-id press of the element focus already rests +// on cannot clear it, so that element is not loaded (`Focusable::a11y`) while the picture lags and +// the dispatcher refuses the press as `unloaded`. + +/// A page with a poster shelf first, so the door exists (the Continue Watching row stands in view +/// on the hero's page and has none), and three cards in it. The billboard shows the shelf's FIRST +/// title, so the test's `card` and `next` are its second and third: a press that lands on the wrong +/// side of the door acts on a different rating key. +struct Door { + s: HomeScreen, + snapshot: plx_data::pms::HubsSnapshot, + hero: FocusKey, + card: FocusKey, + next: FocusKey, + hero_rk: String, + card_rk: String, + next_rk: String, +} + +impl Door { + fn new() -> Self { + let mut state = plx_data::pms::PmsState::default(); + let adapter = std::sync::Arc::new(plx_data::pms::PmsAdapter::default()); + plx_data::pms::seed_grid_for_test(&mut state, &adapter, 1, 3); + let snapshot = plx_data::pms::hubs_snapshot(&state); + let s = screen(snapshot.view()); + let view = snapshot.view(); + let hero = FocusKey { entry: s.entry, elem: HERO_PLAY_ELEM }; + let card = FocusKey { entry: s.entry, elem: s.rows[0].elems[1] }; + let next = FocusKey { entry: s.entry, elem: s.rows[0].elems[2] }; + let hero_rk = s.selected_hero(view).expect("the page has a hero").item.rk.to_string(); + let card_rk = s.item_at(view, 0, 1).expect("the second card").rk.to_string(); + let next_rk = s.item_at(view, 0, 2).expect("the third card").rk.to_string(); + assert!(hero_rk != card_rk && hero_rk != next_rk && card_rk != next_rk, + "premise: three different titles ({hero_rk}, {card_rk}, {next_rk})"); + assert!(!s.holds_page(0), "premise: the first shelf is not the Continue Watching row, so the door exists"); + Self { s, snapshot, hero, card, next, hero_rk, card_rk, next_rk } + } + + fn view(&self) -> HubsView<'_> { self.snapshot.view() } + + /// The page at rest on the shelves. + fn on_the_shelves(&mut self) { + self.s.snap.jump(1.0); + self.s.snap_target = 1.0; + } + + fn moved(&mut self, from: FocusKey, to: FocusKey, by: By) { + let view = self.snapshot.view(); + step(&mut self.s, view, Some(to), &ScreenEvent::FocusMoved { from: Some(from), to, by }); + } + + /// The press the focus `at` commits, as the requests it emitted: `(kind, rk)`. + fn press(&mut self, at: FocusKey) -> Vec<(&'static str, String)> { + let view = self.snapshot.view(); + let (_, out, _) = step(&mut self.s, view, Some(at), &ScreenEvent::PressCommit(plx_machine::machine::PressId(1))); + out.iter().filter_map(|stamped| match &stamped.fx { + Fx::App(AppFx::Home(HomeReq::Play { rk, .. })) => Some(("play", rk.to_string())), + Fx::App(AppFx::Home(HomeReq::Detail { rk, .. })) => Some(("detail", rk.to_string())), + _ => None, + }).collect() + } + + /// `(loaded, subject)` the screen projects for `elem` while the engine's focus is `at`. + fn projection(&self, elem: u32, at: FocusKey) -> (bool, Option) { + let a = Focusable::::a11y(&self.s, &elem, &cx(self.view(), Some(at))).expect("the element exists"); + (a.loaded, a.subject.map(|s| s.into_owned())) + } + + /// The dive passes its midpoint with focus on `at`: the picture catches up with the engine. + fn settle(&mut self, at: FocusKey) { + self.s.snap.jump(if self.s.snap_target >= 0.5 { 1.0 } else { 0.0 }); + let view = self.snapshot.view(); + step(&mut self.s, view, Some(at), &ScreenEvent::Tick(Tick { ms: 16, dt_us: 16_667 })); + } +} + +/// A scripted arrival on a card from the hero's Play, then the press: the card's title opens. The +/// picture is still on the hero (the dive has not run a frame), and a by-id press puts the move and +/// the OK in ONE frame, so the remap a human's quick OK gets must not apply to it. +#[test] +fn a_scripted_arrival_on_a_card_across_the_door_presses_that_card() { + let _guard = plx_base::testlock::serial(); + let mut d = Door::new(); + let (hero, card) = (d.hero, d.card); + d.moved(hero, card, By::Script); + assert!(d.s.snap.pos < 0.5, "premise: the picture is still on the hero"); + assert_eq!(d.press(card), [("detail", d.card_rk.clone())], "the card's title opens, not the hero's"); +} + +/// **At 60 fps the dive is still short of its midpoint when the press machine's dip floor is over.** The +/// machine holds an OK's release for at least its 90 ms floor (`MIN_DIP_MS`, `ui/src/dispatch/press.rs`: +/// six 60 Hz frames, 100 ms) and commits `COMMIT_MS` (120 ms) after the release, about 200 ms after OK goes +/// down. The page's snap spring (`K_SNAP`) has crossed only 41% of the door at 100 ms: its midpoint is +/// 119 ms away. The test delivers the commit at that 100 ms point, earlier than the machine commits, so it +/// holds the screen's rule while the picture is still on the far side: the remap a key's arrival would leave +/// is live there, and the scripted press must not get it. (The simulator's Home draws at 11-15 fps and has +/// crossed the midpoint by its second frame.) +#[test] +fn a_scripted_press_committing_after_the_dip_floor_at_60_fps_still_lands_on_its_card() { + let _guard = plx_base::testlock::serial(); + let mut d = Door::new(); + let (hero, card) = (d.hero, d.card); + d.moved(hero, card, By::Script); + for frame in 0..6 { + let view = d.snapshot.view(); + step(&mut d.s, view, Some(card), &ScreenEvent::Tick(Tick { ms: 16 * (frame + 1), dt_us: 16_667 })); + } + assert!(d.s.snap.pos > 0.3 && d.s.snap.pos < 0.5, + "premise: 100 ms in, the picture is still on the hero ({})", d.s.snap.pos); + assert_eq!(d.press(card), [("detail", d.card_rk.clone())], "the card's title opens, not the hero's"); +} + +/// The reverse: from a card with the page on the shelves, a scripted arrival on the hero's Play +/// plays the hero's item, not the card the page came from. +#[test] +fn a_scripted_arrival_on_the_hero_across_the_door_presses_the_hero() { + let _guard = plx_base::testlock::serial(); + let mut d = Door::new(); + d.on_the_shelves(); + let (hero, card) = (d.hero, d.card); + d.moved(card, hero, By::Script); + assert!(d.s.snap.pos > 0.5, "premise: the picture is still on the shelves"); + assert_eq!(d.press(hero), [("play", d.hero_rk.clone())], "the hero's item plays, not the card's"); +} + +/// A stale remap must not survive a scripted move that crosses no door: a Dir key across it sets +/// the remap, the scripted move to the card's neighbour (same page) then presses THAT card. +#[test] +fn a_scripted_move_within_a_page_clears_the_remap_an_earlier_key_left() { + let _guard = plx_base::testlock::serial(); + let mut d = Door::new(); + let (hero, card, next) = (d.hero, d.card, d.next); + d.moved(hero, card, By::Dir); + d.moved(card, next, By::Script); + assert!(d.s.snap.pos < 0.5, "premise: the picture is still on the hero"); + assert_eq!(d.press(next), [("detail", d.next_rk.clone())]); +} + +/// The human case is kept: a Dir key across the door and a quick OK activates what the picture +/// still shows, the hero's Play, in both directions. +#[test] +fn a_key_across_the_door_and_a_quick_ok_still_lands_on_what_the_picture_shows() { + let _guard = plx_base::testlock::serial(); + let mut d = Door::new(); + let (hero, card) = (d.hero, d.card); + d.moved(hero, card, By::Dir); + assert_eq!(d.press(card), [("play", d.hero_rk.clone())], "the picture still shows the hero"); + d.on_the_shelves(); + d.s.visible_activation = None; + d.moved(card, hero, By::Dir); + assert_eq!(d.press(hero), [("detail", d.card_rk.clone())], "the picture still shows the card"); +} + +/// A by-id press on the element the engine's focus ALREADY rests on emits no `FocusMoved` +/// (`FocusEngine::set` answers `Nothing`), so the Script rule cannot clear the remap a key left: the +/// `[Down, press:X]` batch. And an element with no subject (a linked heading) gives a subject check +/// nothing to refuse by. So while the focused element's press would land on another element, it is NOT +/// LOADED, and the dispatcher refuses any by-id press of it as `unloaded` (`ui/src/dispatch/by_id.rs`, +/// pinned by `input_tests::a_refused_press_emits_no_key_and_a_subject_mismatch_presses_nothing`). Its +/// `a11y` keeps its own subject; the state file lists none for an element that is not loaded. +#[test] +fn the_focused_element_is_not_pressable_while_its_press_would_land_elsewhere() { + let _guard = plx_base::testlock::serial(); + let mut d = Door::new(); + let (hero, card, next) = (d.hero, d.card, d.next); + d.moved(hero, card, By::Dir); + assert_eq!(d.projection(card.elem, card), (false, Some(d.card_rk.clone())), + "the focused card's press lands on the hero: not loaded, and still its own title"); + assert_eq!(d.projection(next.elem, card), (true, Some(d.next_rk.clone())), + "another card is pressed where it stands: a press moves focus to it first"); + assert_eq!(d.projection(hero.elem, card), (true, Some(d.hero_rk.clone())), "the hero is not the focused one"); + // the dive passes its midpoint: the picture catches up and the press lands on the card itself + d.settle(card); + assert_eq!(d.projection(card.elem, card), (true, Some(d.card_rk.clone()))); + assert_eq!(d.press(card), [("detail", d.card_rk.clone())], "once settled the press acts on the named card"); + // and the reverse door: from the card to the hero's Play, the picture still on the shelves + d.moved(card, hero, By::Dir); + assert_eq!(d.projection(hero.elem, hero), (false, Some(d.hero_rk.clone())), + "the hero's press would now open the card the picture still shows"); + assert_eq!(d.projection(card.elem, hero), (true, Some(d.card_rk.clone()))); + d.settle(hero); + assert_eq!(d.projection(hero.elem, hero), (true, Some(d.hero_rk.clone()))); + assert_eq!(d.press(hero), [("play", d.hero_rk.clone())], "once settled the press acts on the hero's item"); +} + +/// How long the lag lasts at 60 fps: the frames between a Dir key across the door and the focused element +/// being pressable again, which is the picture's snap crossing its midpoint (`K_SNAP`, critically +/// damped: 8 frames, about 130 ms). Measured in both directions so the prose that quotes it has a test behind it. +#[test] +fn the_lag_a_key_leaves_lasts_about_eight_frames_at_60_fps_in_both_directions() { + let _guard = plx_base::testlock::serial(); + let mut d = Door::new(); + let (hero, card) = (d.hero, d.card); + let frames_until_pressable = |d: &mut Door, at: FocusKey| -> u32 { + for frame in 1..=60u32 { + let view = d.snapshot.view(); + step(&mut d.s, view, Some(at), &ScreenEvent::Tick(Tick { ms: frame * 17, dt_us: 16_667 })); + if d.projection(at.elem, at).0 { return frame; } + } + panic!("the picture never caught up"); + }; + d.moved(hero, card, By::Dir); + let down = frames_until_pressable(&mut d, card); + d.on_the_shelves(); // the page at rest there, as a key that comes later finds it + d.moved(card, hero, By::Dir); + let up = frames_until_pressable(&mut d, hero); + assert!((6..=10).contains(&down) && (6..=10).contains(&up), "hero to grid {down} frames, grid to hero {up}"); +} + +/// A Scripted arrival names what it presses and clears the remap, so the element it lands on is +/// pressable at once (the round-5 rule, unchanged by the lag rule above). +#[test] +fn a_scripted_arrival_leaves_the_focused_element_pressable() { + let _guard = plx_base::testlock::serial(); + let mut d = Door::new(); + let (hero, card) = (d.hero, d.card); + d.moved(hero, card, By::Script); + assert_eq!(d.projection(card.elem, card), (true, Some(d.card_rk.clone()))); +} + +/// A home whose catalog is `rows` (seeded in order), for the linked-heading door tests below. +fn heading_door(rows: &[(&'static str, &'static str, &'static str)]) -> (HomeScreen, plx_data::pms::HubsSnapshot) { + let mut state = plx_data::pms::PmsState::default(); + let adapter = std::sync::Arc::new(plx_data::pms::PmsAdapter::default()); + plx_data::pms::seed_named_hubs_for_test(&mut state, &adapter, 3, rows); + let snapshot = plx_data::pms::hubs_snapshot(&state); + let mut s = screen(snapshot.view()); + s.carousel = Some((plx_plex::plex::ServerId::UNSET, "1".into())); + (s, snapshot) +} + +/// Did the requests push a collection page (what OK on a linked heading does)? +fn pushed_collection(out: &[Stamped]) -> bool { + out.iter().any(|stamped| matches!(&stamped.fx, Fx::App(AppFx::Content(ContentReq::Push(ContentArg::Collection(_)))))) +} + +/// **A linked heading has no subject, so the lag rule is what protects it.** A Down from the hero seats +/// the linked heading under the billboard and the door's remap points at the hero's Play. A bare by-id +/// press of the heading resolves (an element with no subject gives a subject check nothing to refuse +/// by), moves no focus because it is already seated, and its OK arrives in the same frame: it would PLAY +/// THE HERO. The heading is not loaded while the picture lags its focus, and the dispatcher refuses it. +#[test] +fn a_bare_press_of_a_linked_heading_is_refused_while_the_picture_lags_its_focus() { + let _guard = plx_base::testlock::serial(); + let rows = [COLLECTION_ROWS[1], COLLECTION_ROWS[0]]; + // the hazard, as a human's quick OK meets it: the OK the heading's press queues plays the hero + let (mut human, snapshot) = heading_door(&rows); + let hero = FocusKey { entry: human.entry, elem: HERO_PLAY_ELEM }; + let heading = heading_key(&human, 0); + step(&mut human, snapshot.view(), Some(heading), &ScreenEvent::FocusMoved { from: Some(hero), to: heading, by: By::Dir }); + let (_, out, _) = step(&mut human, snapshot.view(), Some(heading), &ScreenEvent::Activate(heading.elem)); + assert!(has_home(&out, |r| matches!(r, HomeReq::Play { .. })), "premise: the remap lands the press on the hero"); + + // the by-id door: the heading is not pressable until the picture has caught up + let (mut s, snapshot) = heading_door(&rows); + let view = snapshot.view(); + step(&mut s, view, Some(heading), &ScreenEvent::FocusMoved { from: Some(hero), to: heading, by: By::Dir }); + let loaded = |s: &HomeScreen| Focusable::::a11y(s, &heading.elem, &cx(view, Some(heading))).unwrap().loaded; + let a = Focusable::::a11y(&s, &heading.elem, &cx(view, Some(heading))).unwrap(); + assert!(!a.loaded && a.subject.is_none(), "unloaded, and a heading has no subject: {a:?}"); + assert_eq!(Focusable::::a11y_find(&s, &a.path, &cx(view, Some(heading))), Some(heading.elem), + "the id still resolves: `focus:` is unaffected, and the refusal is the press's"); + // the picture catches up: the press acts on the heading itself + s.snap.jump(1.0); + step(&mut s, view, Some(heading), &ScreenEvent::Tick(Tick { ms: 16, dt_us: 16_667 })); + assert!(loaded(&s)); + let (_, out, _) = step(&mut s, view, Some(heading), &ScreenEvent::Activate(heading.elem)); + assert!(pushed_collection(&out) && !has_home(&out, |r| matches!(r, HomeReq::Play { .. } | HomeReq::Detail { .. })), + "settled, the heading opens its collection and nothing else"); +} + +/// The variant from the Continue Watching row: a Down from a deck card to the linked heading under it, then +/// a bare press of the heading, would RESUME THE CARD (the deck row stands in view on the hero's page, so +/// the door lies between it and the heading). +#[test] +fn a_bare_press_of_a_heading_under_the_deck_is_refused_while_the_picture_lags_its_focus() { + let _guard = plx_base::testlock::serial(); + let _press = deck_press_is(plx_media::route::DeckPress::Play); + let rows = [("home.continue", "", "Continue Watching"), COLLECTION_ROWS[1]]; + let (mut human, snapshot) = heading_door(&rows); + let card = FocusKey { entry: human.entry, elem: human.rows[0].elems[0] }; + let heading = heading_key(&human, 1); + step(&mut human, snapshot.view(), Some(heading), &ScreenEvent::FocusMoved { from: Some(card), to: heading, by: By::Dir }); + let (_, out, _) = step(&mut human, snapshot.view(), Some(heading), &ScreenEvent::Activate(heading.elem)); + assert!(has_home(&out, |r| matches!(r, HomeReq::Play { .. })), "premise: the remap resumes the deck card"); + + let (mut s, snapshot) = heading_door(&rows); + let view = snapshot.view(); + step(&mut s, view, Some(heading), &ScreenEvent::FocusMoved { from: Some(card), to: heading, by: By::Dir }); + let loaded = |s: &HomeScreen| Focusable::::a11y(s, &heading.elem, &cx(view, Some(heading))).unwrap().loaded; + assert!(!loaded(&s), "the heading's press would resume the card: not pressable"); + s.snap.jump(1.0); + step(&mut s, view, Some(heading), &ScreenEvent::Tick(Tick { ms: 16, dt_us: 16_667 })); + assert!(loaded(&s)); +} + #[test] fn the_home_census_covers_input_motion_and_current_projection() { let _guard = plx_base::testlock::serial(); @@ -7103,3 +7417,212 @@ fn the_backdrop_has_its_name_back_after_a_trip_to_the_grid() { assert_eq!((s.snap.pos, s.snap.vel), (0.0, 0.0), "the dive has parked on the hero, position and velocity"); assert_eq!(name(&s), Some(parked), "back at the hero the backdrop is the picture it was, with its name"); } + +// ---- A hero control's press plays the title it was armed on, whatever the carousel does in its dip ---- + +/// What the press machine reads while a press stands on `elem` of `s`'s page: live, dipping, and the +/// owner is the pressed element (`InputMachine::press_read`). +fn press_on(s: &HomeScreen, elem: u32) -> PressRead { + PressRead { + scale: 0.97, identity: 1, live: true, active: true, + owner: Some(FocusKey { entry: s.entry, elem }), ..Default::default() + } +} + +/// The read of a press that was CANCELLED (a direction key moved focus off its element, BACK, a +/// declined hold): `live` is gone at the cancel while the spring-back is still on screen (`active`) and +/// the owner is retained for it (`press::a_cancelled_press_stops_being_live_while_it_is_still_on_screen`). +fn press_cancelled_on(s: &HomeScreen, elem: u32) -> PressRead { + PressRead { live: false, ..press_on(s, elem) } +} + +fn hero_tick_16(frame: u32) -> ScreenEvent { + ScreenEvent::Tick(Tick { ms: frame * 16, dt_us: 16_667 }) +} + +/// Three heroes, Home parked at the hero with the countdown `left` seconds from turning the page. +fn countdown_at(left: f32) -> (plx_data::pms::HubsSnapshot, HomeScreen) { + let mut state = plx_data::pms::PmsState::default(); + let adapter = std::sync::Arc::new(plx_data::pms::PmsAdapter::default()); + plx_data::pms::seed_for_test(&mut state, &adapter, 3, plx_data::pms::HubState::Ready); + let snapshot = plx_data::pms::hubs_snapshot(&state); + assert!(snapshot.view().hero_count() > 1, "the auto-advance only arms with more than one hero slot"); + let mut s = screen(snapshot.view()); + s.hero_auto = left; + (snapshot, s) +} + +fn shown_rk(s: &HomeScreen) -> String { + s.carousel.as_ref().map(|(_, rk)| rk.clone()).expect("the carousel shows a hero") +} + +/// Ticks `s` with no press until the carousel turns (or `limit` frames pass) and says how many it took. +fn frames_until_the_carousel_turns( + s: &mut HomeScreen, view: HubsView<'_>, focus: FocusKey, from: u32, limit: u32, +) -> Option { + let before = shown_rk(s); + (1..=limit).find(|n| { + step(s, view, Some(focus), &hero_tick_16(from + n)); + shown_rk(s) != before + }) +} + +/// **Review finding on PR #1442, round 7: the carousel can turn inside a hero press's dip.** A hero +/// control is a `Control`: OK arms a press that commits about 200 ms after OK goes down (`MIN_DIP_MS` + +/// `COMMIT_MS`), and the commit re-reads the title the billboard shows. Pressing the control that already has focus moves no focus, +/// so nothing restarted the 8 s countdown; if it ran out inside the dip the page turned and a press +/// accepted against one title (`press home.hero.play --rk X`, or a person's OK a moment before the turn) +/// played the next page's. **Round 8:** a press on a hero control restarts the countdown, as a focus move +/// does, every tick it stands; so the press plays the title it was armed on, and no turn is OWED when it +/// settles (a turn owed during the dip fired on the first tick after Play or Info, often the person's +/// return to Home): the next one comes a full interval after the press. +#[test] +fn a_hero_press_plays_the_title_it_was_armed_on_when_the_countdown_runs_out_inside_its_dip() { + let _guard = plx_base::testlock::serial(); + for elem in [HERO_PLAY_ELEM, HERO_INFO_ELEM] { + // 0.05 s left: three 16.667 ms frames would run it out, inside the six press frames below + // (`the_carousel_turns_on_schedule_...` pins that this schedule turns the page at frame 3) + let (snapshot, mut s) = countdown_at(0.05); + let view = snapshot.view(); + let armed_on = shown_rk(&s); + let focus = FocusKey { entry: s.entry, elem }; + let press = press_on(&s, elem); + for frame in 1..=6 { + step_pressed(&mut s, view, Some(focus), press, &hero_tick_16(frame)); + assert_eq!(shown_rk(&s), armed_on, "frame {frame}: the carousel turned under the press"); + assert!(s.outgoing.is_none(), "frame {frame}: a page slide began under the press"); + assert_eq!(s.hero_auto, HERO_AUTO_S, "frame {frame}: the press did not restart the countdown"); + } + let (_, out, _) = step_pressed(&mut s, view, Some(focus), press, + &ScreenEvent::PressCommit(plx_machine::machine::PressId(1))); + let acted = if elem == HERO_PLAY_ELEM { + has_home(&out, |r| matches!(r, HomeReq::Play { rk, .. } if *rk == armed_on)) + } else { + has_home(&out, |r| matches!(r, HomeReq::Detail { rk, .. } if *rk == armed_on)) + }; + assert!(acted, "elem {elem}: the press did not act on the title it was armed on ({armed_on}) among {} effects", out.len()); + // The press settles (the spring-back is over: no press is live). Nothing is owed: the page + // does not turn on this tick or the next, only after a full interval from here. + let turned_after = frames_until_the_carousel_turns(&mut s, view, focus, 6, 600) + .expect("the carousel turns again once the press has settled"); + assert!(turned_after > 400, + "elem {elem}: the page turned {turned_after} frames after the press settled; no turn is owed"); + assert!( + (turned_after as f32 * 0.016_667 - HERO_AUTO_S).abs() < 0.05, + "elem {elem}: turned {turned_after} frames after the press, not a full {HERO_AUTO_S} s interval later" + ); + assert!(s.outgoing.is_some(), "and it slides"); + } +} + +/// **The countdown is not stopped by anything else.** No press, a press on another page's element, a +/// press on a shelf card, and a CANCELLED press (`live` is gone at the cancel while `active` and the +/// owner stay for the spring-back) each leave the carousel turning on schedule: the hold reads `live` +/// and the hero owner, not `active`, not the owner alone. +#[test] +fn the_carousel_turns_on_schedule_unless_a_press_stands_on_one_of_its_hero_controls() { + let _guard = plx_base::testlock::serial(); + let reads: Vec<(&str, Box PressRead>)> = vec![ + ("no press", Box::new(|_| PressRead::default())), + ("a cancelled hero press, still springing back", Box::new(|s| press_cancelled_on(s, HERO_PLAY_ELEM))), + ("a press on a card of a shelf", Box::new(|s| press_on(s, s.rows[0].elems[0]))), + ("a press on another page's hero control", Box::new(|s| PressRead { + owner: Some(FocusKey { entry: EntryId(s.entry.0 + 1), elem: HERO_PLAY_ELEM }), ..press_on(s, HERO_PLAY_ELEM) + })), + ]; + for (what, read) in reads { + let (snapshot, mut s) = countdown_at(0.05); + let view = snapshot.view(); + let before = shown_rk(&s); + let focus = FocusKey { entry: s.entry, elem: HERO_PLAY_ELEM }; + let press = read(&s); + for frame in 1..=2 { + step_pressed(&mut s, view, Some(focus), press, &hero_tick_16(frame)); + assert_eq!(shown_rk(&s), before, "{what}: turned early, at frame {frame}"); + } + step_pressed(&mut s, view, Some(focus), press, &hero_tick_16(3)); + assert_ne!(shown_rk(&s), before, "{what}: the countdown ran out and the page did not turn"); + assert!(s.outgoing.is_some(), "{what}: and it slides"); + } +} + +/// **A cancelled press releases the hold, and the countdown runs from where the restart left it.** The +/// press restarts the countdown through its dip (the page does not turn, `hero_auto` rests at its full +/// length), and the frame its read says it was cancelled the countdown is counting again from that full +/// length: one tick off it, the page still the one shown, and the turn a full interval after the press. +#[test] +fn a_cancelled_hero_press_releases_the_carousel() { + let _guard = plx_base::testlock::serial(); + let (snapshot, mut s) = countdown_at(0.05); + let view = snapshot.view(); + let before = shown_rk(&s); + let focus = FocusKey { entry: s.entry, elem: HERO_PLAY_ELEM }; + let held = press_on(&s, HERO_PLAY_ELEM); + for frame in 1..=5 { + step_pressed(&mut s, view, Some(focus), held, &hero_tick_16(frame)); + } + assert_eq!(shown_rk(&s), before, "held through the dip"); + assert_eq!(s.hero_auto, HERO_AUTO_S, "the premise: the press restarted the countdown"); + let cancelled = press_cancelled_on(&s, HERO_PLAY_ELEM); + step_pressed(&mut s, view, Some(focus), cancelled, &hero_tick_16(6)); + assert!( + (s.hero_auto - (HERO_AUTO_S - 0.016_667)).abs() < 1e-4, + "the cancel released the hold: the countdown ran one tick from its full length, got {}", + s.hero_auto + ); + assert_eq!(shown_rk(&s), before, "no turn is owed for the dip the press held"); + assert!(s.outgoing.is_none()); + let turned_after = frames_until_the_carousel_turns(&mut s, view, focus, 6, 600) + .expect("the carousel turns once the countdown has run its length"); + assert!( + ((turned_after + 1) as f32 * 0.016_667 - HERO_AUTO_S).abs() < 0.05, + "turned {turned_after} frames after the cancel tick, not a full interval after the press" + ); +} + +/// **The other two turns are refused while a hero press stands, and dropped, not kept.** Right at the +/// hero's edge moves no focus (so it does not abandon the press) and `HomeCmd::Flip` is addressed to the +/// page: both go through the one turn, which refuses (`Handled::No`) so neither can replace the title under +/// a press. Nothing is queued: once the press has settled the page has not turned, and the caller sends +/// the turn again. Both work as ever with no press. +#[test] +fn a_manual_turn_is_refused_while_a_hero_press_stands_and_not_applied_after() { + let _guard = plx_base::testlock::serial(); + let (snapshot, mut s) = countdown_at(HERO_AUTO_S); + let view = snapshot.view(); + let before = shown_rk(&s); + let focus = FocusKey { entry: s.entry, elem: HERO_INFO_ELEM }; + let press = press_on(&s, HERO_INFO_ELEM); + + let (handled, _, _) = step_pressed(&mut s, view, Some(focus), press, &hero_edge_right()); + assert_eq!(handled, Handled::No, "the edge key is not taken while a press stands"); + let (handled, _, _) = step_pressed(&mut s, view, Some(focus), press, + &ScreenEvent::App(AppMsg::Home(HomeCmd::Flip(1)))); + assert_eq!(handled, Handled::No); + assert_eq!(shown_rk(&s), before, "neither turned the page under the press"); + assert!(s.outgoing.is_none()); + // the press settles: the refused turns are not owed + step(&mut s, view, Some(focus), &hero_tick_16(1)); + assert_eq!(shown_rk(&s), before, "a refused turn is dropped, not applied when the press settles"); + assert!(s.outgoing.is_none()); + + let (handled, _, _) = step(&mut s, view, Some(focus), &hero_edge_right()); + assert_eq!(handled, Handled::Yes, "with no press the edge key turns the page as ever"); + assert_ne!(shown_rk(&s), before); +} + +/// The predicate itself, over the three hero slots: Play, Info and the bookmark disc are hero controls +/// (`Located::Hero`), a shelf card and another page's element are not, and only a LIVE press counts. +#[test] +fn a_press_is_armed_on_the_hero_when_it_is_live_and_its_owner_is_one_of_this_pages_hero_controls() { + let _guard = plx_base::testlock::serial(); + let (snapshot, s) = countdown_at(HERO_AUTO_S); + let _ = snapshot; + for elem in [HERO_PLAY_ELEM, HERO_INFO_ELEM, HERO_WATCHLIST_ELEM] { + assert!(s.hero_press_armed(&press_on(&s, elem)), "elem {elem}"); + assert!(!s.hero_press_armed(&press_cancelled_on(&s, elem)), "a cancelled press on {elem}"); + } + assert!(!s.hero_press_armed(&PressRead::default())); + assert!(!s.hero_press_armed(&press_on(&s, s.rows[0].elems[0])), "a shelf card"); + assert!(!s.hero_press_armed(&PressRead { owner: None, ..press_on(&s, HERO_PLAY_ELEM) }), "no owner"); +} diff --git a/rust-modules/screens/src/item_menu.rs b/rust-modules/screens/src/item_menu.rs index 02558930c4..1c8776d75d 100644 --- a/rust-modules/screens/src/item_menu.rs +++ b/rust-modules/screens/src/item_menu.rs @@ -971,7 +971,10 @@ impl Focusable for ItemMenuScreen { } /// `itemmenu.`: the menu's [`ItemRow`] names its rows (`ItemRow::a11y_name`; a plain word), the Play /// Version page's one row per version `itemmenu.version.`. The label is the row's drawn - /// words (read side only). + /// words (read side only). Every row's `subject` is the ratingKey of the item the menu was opened on + /// ([`ItemMenuArg::rk`], captured at open): a row (Play, Mark watched, Remove from Deck, a Watchlist + /// write) acts on THAT title, so a press names it. A Catalog menu (a Watchlist tile no server holds) + /// has no ratingKey, so its rows carry no subject. fn a11y(&self, key: &u32, _: &Cx<'_, H>) -> Option> { let index = self.form.index_of_key(RowKey(*key))?; let path = match *self.form.id_at(index)? { @@ -979,10 +982,11 @@ impl Focusable for ItemMenuScreen { row => A11yPath::new().name(row.a11y_name()), }; let a = A11y::new(path, Role::Row); - Some(match plx_ui::geom::table_row(&self.form.table, index) { + let a = match plx_ui::geom::table_row(&self.form.table, index) { Some(row) => a.with_label(row.label.as_str()), None => a, - }) + }; + Some(if self.arg.rk.is_empty() { a } else { a.with_subject(self.arg.rk.as_str()) }) } fn a11y_elems(&self, g: GroupId, _: &Cx<'_, H>, out: &mut Vec) { if g == GroupId(0) { @@ -2591,4 +2595,79 @@ pub(crate) mod tests { } }); } + + /// Every row's `(id, subject)` of the menu as it stands, in listing order. + fn row_subjects(s: &ItemMenuScreen) -> Vec<(String, Option)> { + with_cx(|cx| { + let mut keys = Vec::new(); + Focusable::::a11y_elems(s, GroupId(0), cx, &mut keys); + keys.iter() + .map(|key| { + let a = Focusable::::a11y(s, key, cx).expect("a bound row projects"); + (a.path.to_string(), a.subject.map(|c| c.into_owned())) + }) + .collect() + }) + } + + /// **A row names the title it acts on.** Play, Mark watched, Remove from Deck and the Watchlist rows + /// all act on the item the menu was opened on, so a harness press (`press:itemmenu.@`) has + /// something to compare: every row carries the menu's own ratingKey as its subject, on every kind of + /// menu and on the Play Version page too, and a Catalog menu (no ratingKey: its title is a Watchlist + /// guid no server holds) carries none rather than a made-up one. + #[test] + fn every_row_names_the_menus_item_as_its_subject() { + let mut card = leaf_menu_with_versions(); + let rows = row_subjects(&card); + assert!(rows.len() >= 3, "the menu has rows: {rows:?}"); + for (id, subject) in &rows { + assert_eq!(subject.as_deref(), Some("42"), "{id}"); + } + open_play_version_page(&mut card); + let versions = row_subjects(&card); + assert!(versions.iter().any(|(id, _)| id == "version.0"), "{versions:?}"); + for (id, subject) in &versions { + assert_eq!(subject.as_deref(), Some("42"), "{id}"); + } + + let arg = |rk: &str, kind: ItemMenuKind| ItemMenuArg { + sid: plx_plex::plex::ServerId::from_raw(3), + rk: rk.into(), + kind, + host: EntryId(1), + focus: None, + anchor: [0; 4], + loaded_episode: false, + from_home: false, + catalog: None, + watchlist: None, + }; + let mut strip = ItemMenuScreen::new( + EntryId(8), + arg("77", ItemMenuKind::Episode { mark: PosterMark::None, versions: Vec::new() }), + ); + let mut tab = ItemMenuScreen::new( + EntryId(8), + arg("season-9", ItemMenuKind::Season { mark: PosterMark::None, show_rk: "show-1".into(), index: 4 }), + ); + for (menu, want) in [(&mut strip, "77"), (&mut tab, "season-9")] { + menu.build_rows(test_store().view(), DeckPress::Play); + let rows = row_subjects(menu); + assert!(!rows.is_empty()); + for (id, subject) in &rows { + assert_eq!(subject.as_deref(), Some(want), "{id}"); + } + } + + let mut catalog = ItemMenuScreen::new( + EntryId(8), + arg("", ItemMenuKind::Catalog { state: plx_data::watchlist::model::TileState::NotOnAnyServer }), + ); + catalog.build_rows(test_store().view(), DeckPress::Play); + let rows = row_subjects(&catalog); + assert!(!rows.is_empty()); + for (id, subject) in &rows { + assert_eq!(*subject, None, "{id}: a Catalog menu has no ratingKey to name"); + } + } } diff --git a/rust-modules/screens/src/player/mod.rs b/rust-modules/screens/src/player/mod.rs index 011a0c0470..fa0570142c 100644 --- a/rust-modules/screens/src/player/mod.rs +++ b/rust-modules/screens/src/player/mod.rs @@ -1091,6 +1091,26 @@ impl Machine for PlayerScreen } } +/// **The ratingKey of the item the session is playing**, `None` when it holds none (a URL playback has no key). +/// What a player control that restarts or finishes the playing item names as its accessibility subject +/// ([`PlayerScreen::control_subject`]). +fn playing_rk(ps: &plx_media::route::PlaybackSession) -> Option { + let rk = plx_media::route::cur_rk(ps); + (!rk.is_empty()).then_some(rk) +} + +/// What a pick of a rung of the More menu's quality ladder names as its accessibility subject: the title it +/// re-resolves, read the way the performer reads it (`app::playback::apply_more_action`). On a failed play the pick is +/// the failure read-out's Retry at the chosen rung, so it repeats the failed REQUEST ([`plx_media::route::retry_rk`]); +/// on a live one it asks the route again for the item playing. +fn quality_pick_subject(ps: &plx_media::route::PlaybackSession) -> Option { + if matches!(plx_media::player::state(ps), plx_media::player::PlaybackState::Error) { + plx_media::route::retry_rk(ps) + } else { + playing_rk(ps) + } +} + /// **Does this key press continue the relative-seek gesture in progress?** Every key but LEFT and /// RIGHT ends it ([`PlayerScreen::handle_key`] resets the burst), except OK on a control whose /// command is a seek: two seek controls pressed inside [`BURST_GAP_MS`](plx_appkit::player_hud::seek_jump::BURST_GAP_MS) are one gesture, and their steps @@ -2353,15 +2373,7 @@ impl PlayerScreen { ) { let Some(i) = focused.and_then(|e| e.checked_sub(player_hud::ELEM_SECTION_BASE)) else { return }; let chapters = plx_appkit::chapters_panel::has_chapters(H::metadata(cx)); - let command = player_hud::geometry::frame_state_content( - &self.compiled, - self.hud.sections.bits(), - self.eff_slot(), - chapters, - self.model.is_episode, - self.model.paused, - ) - .and_then(|(state, skip)| player_hud::geometry::section_command(state.skip_variant(skip), i as usize)); + let command = self.section_command_at(chapters, i as usize); // A command that is not meaningful now (Go to details with no detail page) is not asked, but the press still // puts the page away: the overlay's card closed when it had no action to report, too. let Some(command) = command else { return }; @@ -2628,12 +2640,58 @@ impl PlayerScreen { /// Both spellings are built from static names and an integer, never from content. fn control_path(&self, i: i32) -> A11yPath { let path = A11yPath::new().name("control"); - match self.row_word(i) { - Some(word) if (0..i).all(|j| self.row_word(j) != Some(word)) => path.name(word), - _ => path.index(i as usize), + match self.control_word(i) { + Some(word) => path.name(word), + None => path.index(i as usize), + } + } + + /// The word item `i`'s id is spelled with ([`Self::control_path`]): its [`Self::row_word`] when no earlier item of + /// the row has the same one, `None` when the id is the item's position. + fn control_word(&self, i: i32) -> Option<&'static str> { + self.row_word(i).filter(|&word| (0..i).all(|j| self.row_word(j) != Some(word))) + } + + /// The command the package placed at item `i` of the row, enabled or not (`player_hud::geometry::row_declared`). + fn row_declared(&self, i: i32) -> Option { + player_hud::geometry::row_declared(&self.compiled, self.hud.sections.bits(), self.eff_slot(), &self.model, i) + } + + /// **The ratingKey a press of item `i` of the control row plays, restarts or finishes**, the subject of its + /// accessibility id (`tools/a11y.py`, `SUBJECT_BEARING`), read off the session the way the app's performer + /// reads it: Previous and Next the queue neighbour they would start ([`HudCommand::plays_rk`]), From beginning + /// the item playing, Up Next's `next_episode` the episode `up_next` holds (`app::playback::play_up_next`), the + /// Skip pill the item playing (a final credits segment finishes it). A control that starts or writes no title + /// (a seek, a panel opener, `watch`, `watch_credits`) has none and stays pressable bare. An id spelled by POSITION + /// hides its word, so `player.control.` is guarded whole and carries the playing item's key when its command + /// names no other. No IO: the session is the frame's own copy. + fn control_subject(&self, i: i32, ps: &plx_media::route::PlaybackSession) -> Option { + let target = match (self.row_declared(i), self.row_word(i)) { + (Some(command), _) => command.plays_rk(ps), + (None, Some("next_episode")) => plx_media::route::up_next(ps).map(|next| next.rk.clone()).filter(|rk| !rk.is_empty()), + (None, Some("skip")) => playing_rk(ps), + (None, _) => None, + }; + match self.control_word(i) { + Some(_) => target, + None => target.or_else(|| playing_rk(ps)), } } + /// **The command of an open section's button `i`** (`player_hud::geometry::section_command` over the frame's state): what + /// [`Self::section_pressed`] performs and what the button's accessibility subject is read from. + fn section_command_at(&self, chapters: bool, i: usize) -> Option { + player_hud::geometry::frame_state_content( + &self.compiled, + self.hud.sections.bits(), + self.eff_slot(), + chapters, + self.model.is_episode, + self.model.paused, + ) + .and_then(|(state, skip)| player_hud::geometry::section_command(state.skip_variant(skip), i)) + } + /// The failure read-out's row, when the read-out owns the frame: the read-out and each action's rect /// (`None` for a slot the row does not draw). The condition `groups_in` declares the row under. fn failure_row( @@ -2780,9 +2838,13 @@ impl Focusable for PlayerScree return None; } let item = A11y::new(self.control_path(i), Role::Button); - return Some(match self.row_word(i) { + let item = match self.row_word(i) { Some(word) => item.with_label(word), None => item, + }; + return Some(match self.control_subject(i, H::session(cx)) { + Some(rk) => item.with_subject(rk), + None => item, }); } if (ELEM_TAB_BASE..ELEM_FAILURE_BASE).contains(&key) { @@ -2798,13 +2860,34 @@ impl Focusable for PlayerScree let at = (key - ELEM_FAILURE_BASE) as usize; let (readout, frames) = self.failure_row(cx.measure)?; frames.get(at).copied().flatten()?; - let word = player_hud::failure_action_word(*readout.actions().get(at)?); - return Some(A11y::new(A11yPath::new().name("failure").name(word), Role::Button)); + let action = *readout.actions().get(at)?; + let item = A11y::new(A11yPath::new().name("failure").name(player_hud::failure_action_word(action)), Role::Button); + // Try again and Play automatically resolve the failed request again (`app::playback::retry_failed_playback`, + // `route::retry_current_play`): the key of THAT request, which a play that failed before its plan landed + // holds and `cur_rk` does not. Change quality, Repair and Back start no title. + use plx_media::player::FailureAction as Fail; + return Some(match action { + Fail::TryAgain | Fail::PlayAutomatically => match plx_media::route::retry_rk(H::session(cx)) { + Some(rk) => item.with_subject(rk), + None => item, + }, + Fail::ChangeQuality | Fail::Repair | Fail::Back => item, + }); } if (ELEM_SECTION_BASE..ELEM_SECTION_END).contains(&key) { let at = (key - ELEM_SECTION_BASE) as usize; - return (at < self.section_rects(chapters).len()) - .then(|| A11y::new(A11yPath::new().name("section").index(at), Role::Button)); + if at >= self.section_rects(chapters).len() { + return None; + } + // The Info card's buttons (From the beginning, Go to details) are named by POSITION, so the whole + // spelling is guarded: the key of what the button's command plays, else the item playing. + let ps = H::session(cx); + let subject = self.section_command_at(chapters, at).and_then(|command| command.plays_rk(ps)).or_else(|| playing_rk(ps)); + let item = A11y::new(A11yPath::new().name("section").index(at), Role::Button); + return Some(match subject { + Some(rk) => item.with_subject(rk), + None => item, + }); } if (ELEM_CHAPTER_BASE..plx_ui::dispatch::STRIP_BASE).contains(&key) { let (_, src) = self.strip_source(cx)?; @@ -4517,6 +4600,138 @@ pub(crate) mod step_ladder_tests { assert_eq!(row.len, elems.len(), "with both live no cell of the row is a hole"); } + /// The `subject` of the element `id` names on `page`, `None` when it names none or is no element. + fn subject_of(page: &PlayerScreen, cx: &Cx<'_, TestHost>, id: &str) -> Option { + let path = plx_ui::a11y::A11yPath::parse_relative(id).expect("a well-formed path"); + let key = Focusable::::a11y_find(page, &path, cx)?; + Focusable::::a11y(page, &key, cx)?.subject.map(Cow::into_owned) + } + + /// **The controls that start a title name the one they start** (`SUBJECT_BEARING`, so the harness's press + /// must name it), read the way the app's performer reads it: Previous and Next the queue neighbour + /// (`queue_transport::step`), Up Next's `next_episode` the episode `up_next` holds (`play_up_next`), the Skip pill + /// the item playing (a final credits segment finishes it). The rest of the row starts no title and names none, so + /// `tests/player_shots.sh` still opens its panels bare. + #[test] + fn the_player_controls_that_start_a_title_name_the_one_they_start() { + use plx_data::metadata::{Marker, MarkerKind}; + let _g = plx_base::testlock::serial(); + let ps = super::overlay_tests::middle_episode_session(); + let mut page = PlayerScreen::new(ENTRY, plx_appkit::player_hud::loaded::classic_for_test()); + let controls = player_hud::Controls::for_item(true, true, true); + page.slot = ControlSlot::Discs(controls); + page.model.controls = controls; + page.model.is_episode = true; + let playing = cx_over(&ps); + assert_eq!(subject_of(&page, &playing, "control.next").as_deref(), Some("12"), "Next plays the following episode"); + assert_eq!(subject_of(&page, &playing, "control.previous").as_deref(), Some("10"), "Previous plays the preceding one"); + for id in ["control.subtitles", "control.audio", "control.more"] { + assert_eq!(subject_of(&page, &playing, id), None, "{id} opens a panel: it names no title"); + } + + let marker = |kind| Marker { kind, start_ms: 1_000, end_ms: 2_000, final_seg: kind == MarkerKind::Credits }; + page.slot = player_hud::slot_for(Some(marker(MarkerKind::Credits)), true, plx_media::route::NextEpisodeMode::Countdown); + assert!(matches!(page.slot, ControlSlot::UpNext(_)), "rig: the Up Next pair"); + assert_eq!(subject_of(&page, &playing, "control.next_episode").as_deref(), Some("12"), "Next Episode plays what up_next holds"); + assert_eq!(subject_of(&page, &playing, "control.watch_credits"), None, "Watch Credits starts nothing"); + + page.slot = player_hud::slot_for(Some(marker(MarkerKind::Intro)), false, plx_media::route::NextEpisodeMode::Countdown); + assert!(matches!(page.slot, ControlSlot::Skip(_)), "rig: the Skip pill"); + assert_eq!(subject_of(&page, &playing, "control.skip").as_deref(), Some("11"), "Skip acts on the item playing"); + + // an idle session names nothing: nothing to play, so the guarded doors cannot press the control + let idle = cx(); + page.slot = ControlSlot::Discs(controls); + assert_eq!(subject_of(&page, &idle, "control.next"), None, "no queue: Next plays nothing"); + } + + /// **An id spelled by position hides its word, so it is guarded whole**: a package placing two Next controls + /// (or any command twice) names the second `control.`, and that id carries what its command plays, else the + /// item playing, so a bare `press player.control.5` cannot start the queue's next episode behind the word. + #[test] + fn a_position_spelled_control_carries_a_subject_whatever_its_command() { + let _g = plx_base::testlock::serial(); + let ps = super::overlay_tests::middle_episode_session(); + let controls = player_hud::Controls::for_item(true, true, true); + let positional = |command: &str| { + let mut page = PlayerScreen::new(ENTRY, plx_appkit::player_hud::loaded::reference_with_forward_as_for_test(command)); + page.slot = ControlSlot::Discs(controls); + page.model.controls = controls; + page.model.is_episode = true; + let cx = cx_over(&ps); + let mut elems = Vec::new(); + Focusable::::a11y_elems(&page, GROUP_ROW, &cx, &mut elems); + let ids: Vec<_> = elems + .iter() + .filter_map(|key| Focusable::::a11y(&page, key, &cx)) + .filter(|a| a.path.to_string().rsplit('.').next().is_some_and(|last| last.chars().all(|c| c.is_ascii_digit()))) + .map(|a| (a.path.to_string(), a.subject.map(Cow::into_owned))) + .collect(); + (subject_of(&page, &cx, "control.next"), ids) + }; + let (first, ids) = positional("next"); + assert_eq!(first.as_deref(), Some("12"), "the first Next keeps its word"); + assert_eq!(ids, [("control.5".to_owned(), Some("12".to_owned()))], "the second is `control.5` and plays the same episode"); + let (_, ids) = positional("toggle_play"); + assert_eq!(ids, [("control.5".to_owned(), Some("11".to_owned()))], "a repeated pause names the item playing"); + } + + /// **The failure read-out's Try again and Play automatically resolve the failed REQUEST again** + /// (`retry_failed_playback`, `route::retry_current_play`), so each names the request's key and not `cur_rk`: a + /// play that failed before its plan landed holds the item it asked for in the one and the previous item in the + /// other. Change quality, Repair and Back start no title and name none; a session that made no request (a URL) + /// has nothing to retry and names none. + #[test] + fn the_failure_actions_that_play_again_name_the_request_they_repeat() { + use plx_media::player::FailureAction as Fail; + let _g = plx_base::testlock::serial(); + let mut ps = super::overlay_tests::middle_episode_session(); + let mut page = PlayerScreen::new(ENTRY, plx_appkit::player_hud::loaded::classic_for_test()); + let subjects = |ps: &plx_media::route::PlaybackSession, page: &mut PlayerScreen| { + let cx = cx_over(ps); + let actions = vec![Fail::PlayAutomatically, Fail::TryAgain, Fail::ChangeQuality, Fail::Back]; + let readout = plx_appkit::player_hud::FailureReadout::captured( + plx_media::player::error_now(ps), actions, String::new(), ps.repair_status); + let busy = player_hud::Busy::Readout(plx_ui::widgets::StatusKind::Failed, c"Playback failed"); + page.busy = busy; + page.presentation = player_hud::Presentation { busy, failure: Some(std::sync::Arc::new(readout)) }; + ["failure.play_automatically", "failure.try_again", "failure.change_quality", "failure.back"].map(|id| { + let path = plx_ui::a11y::A11yPath::parse_relative(id).expect("a well-formed path"); + let key = Focusable::::a11y_find(page, &path, &cx).unwrap_or_else(|| panic!("{id} is an element")); + Focusable::::a11y(page, &key, &cx).expect(id).subject.map(Cow::into_owned) + }) + }; + assert_eq!(subjects(&ps, &mut page), [None, None, None, None], "no request was made: nothing to retry"); + // the item playing is `11`; the request that failed is `99` (its plan never landed) + plx_media::route::seed_request_for_test(&mut ps, "99"); + assert_eq!(plx_media::route::cur_rk(&ps), "11", "rig: the session holds another item"); + assert_eq!( + subjects(&ps, &mut page), + [Some("99".to_owned()), Some("99".to_owned()), None, None], + "Try again and Play automatically name the request's key, not `cur_rk`" + ); + } + + /// **The Info card's buttons are named by position, so each carries a subject**: From the beginning restarts + /// the item playing and Go to details leaves for its page, both naming it (`section.` is guarded whole). + #[test] + fn the_info_cards_buttons_name_the_item_playing() { + let _g = plx_base::testlock::serial(); + let ps = super::overlay_tests::middle_episode_session(); + let mut page = PlayerScreen::new(ENTRY, plx_appkit::player_hud::loaded::reference_with_info_actions_for_test()); + page.model.chapters = true; + page.model.is_episode = true; + page.hud.sections = input::Sections::NONE.toggled(Section::Info, false); + let playing = cx_over(&ps); + assert_eq!(page.section_command_at(true, 0), Some(HudCommand::FromBeginning), "rig: the Info card's first button"); + assert_eq!(subject_of(&page, &playing, "section.0").as_deref(), Some("11"), "From the beginning restarts the item playing"); + assert_eq!(page.section_command_at(true, 1), Some(HudCommand::GoToDetail), "rig: the second button"); + assert_eq!(subject_of(&page, &playing, "section.1").as_deref(), Some("11"), "Go to details names the same item"); + assert_eq!(subject_of(&page, &playing, "section.2"), None, "there is no third button"); + let idle = cx(); + assert_eq!(subject_of(&page, &idle, "section.0"), None, "nothing playing: nothing to name"); + } + /// Every group this screen declares resolves back through `group_of` to the group it came /// from — the property `Focusable`'s two queries must agree on for the engine's own /// bookkeeping to be internally consistent. diff --git a/rust-modules/screens/src/player/overlay.rs b/rust-modules/screens/src/player/overlay.rs index 112092f879..73cd64890b 100644 --- a/rust-modules/screens/src/player/overlay.rs +++ b/rust-modules/screens/src/player/overlay.rs @@ -988,8 +988,36 @@ impl Focusable) -> Option> { match &self.panel { - Panel::Tracks(p) => TrackMenuPart { state: p, entry: self.entry, group: Self::GROUP }.a11y(key, cx).map(plx_ui::a11y::A11y::into_owned), - Panel::More(p) => MoreMenuPart { state: p, entry: self.entry, group: Self::GROUP }.a11y(key, cx).map(plx_ui::a11y::A11y::into_owned), + Panel::Tracks(p) => { + let part = TrackMenuPart { state: p, entry: self.entry, group: Self::GROUP }; + let row = part.a11y(key, cx)?.into_owned(); + // A track pick selects the part's streams on the PMS and a search result installs its subtitle on the + // item (`TrackRow::writes_title`): those rows name the title playing. The rest of the menu names none. + Some(match part.writes_title_at(key).then(|| super::playing_rk(H::session(cx))).flatten() { + Some(rk) => row.with_subject(rk), + None => row, + }) + } + Panel::More(p) => { + let part = MoreMenuPart { state: p, entry: self.entry, group: Self::GROUP }; + let row = part.a11y(key, cx)?.into_owned(); + // A folded Previous, Next or From beginning plays a title: the row names the key its command plays, + // read the way the performer reads it (`HudCommand::plays_rk`). A quality rung re-resolves the title + // (`super::quality_pick_subject`), a retry of the failed request when the play failed. Every other row + // (Stats, a speed) names none. + let ps = H::session(cx); + use plx_appkit::more_menu::Action; + let subject = match part.action_at(key) { + Some(Action::Hud(command)) => command.plays_rk(ps), + Some(Action::SetQuality(_)) => super::quality_pick_subject(ps), + // exhaustive, so a new action cannot reach here without deciding whether it acts on a title + Some(Action::None | Action::ToggleStats | Action::SetSpeed(_) | Action::SendDiagnostics) | None => None, + }; + Some(match subject { + Some(rk) => row.with_subject(rk), + None => row, + }) + } Panel::Timing(_) => None, } } diff --git a/rust-modules/screens/src/player/overlay_tests.rs b/rust-modules/screens/src/player/overlay_tests.rs index afa8bee798..cae3042573 100644 --- a/rust-modules/screens/src/player/overlay_tests.rs +++ b/rust-modules/screens/src/player/overlay_tests.rs @@ -125,6 +125,17 @@ pub(super) fn failure_fixture(ps: &plx_media::route::PlaybackSession) -> plx_app plx_appkit::player_hud::FailureReadout::captured(error, actions, support, ps.repair_status) } +/// A session playing the middle episode `11` of a three-episode queue, `12` up next: the neighbours the accessibility +/// subjects of the player's title-changing controls (the HUD's row, the Info card, a More fold) name. +pub(super) fn middle_episode_session() -> plx_media::route::PlaybackSession { + let mut ps = plx_media::route::PlaybackSession::IDLE; + let sid = plx_media::route::cur_sid(&ps); + let row = |rk: &str, item_id: i64| plx_plex::plex::QueueRow { item_id, sid, rk: rk.into(), kind: "episode".into(), ..Default::default() }; + let next = plx_media::route::UpNext { rk: "12".into(), ..Default::default() }; + plx_media::route::seed_queue_for_test(&mut ps, "11", vec![row("10", 10), row("11", 11), row("12", 12)], Some(next)); + ps +} + pub(super) fn presentation_fixture(ps: &plx_media::route::PlaybackSession) -> plx_appkit::player_hud::Presentation { use plx_media::player; use plx_appkit::player_hud::{Busy, Presentation}; @@ -459,6 +470,140 @@ fn the_more_popover_mounts_on_the_speed_page_when_addressed_to_it() { assert_eq!(more_page(&page), None); } +/// **A folded row that starts a title names it** (`more.fold.previous|next|from_beginning`, in `SUBJECT_BEARING`), +/// read the way the performer reads it (`HudCommand::plays_rk`): Previous and Next the queue neighbour, From +/// beginning the item playing. The other folds (a seek, a panel, Go to details, Stats) start none and name none. +#[test] +fn a_folded_row_that_starts_a_title_names_it() { + use plx_appkit::player_hud::command::HudCommand; + let _g = plx_base::testlock::serial(); + plx_media::speed_audio::force_speed_decoder_for_test(true); // a host test loads no FFmpeg + let ps = middle_episode_session(); + let meta = plx_data::stores::metadata::MetadataStore::default(); + let minimal = plx_appkit::player_hud::loaded::load( + &plx_appkit::hud_format::fixtures::bytes("minimal"), + "0.0.0-test", + plx_platform::i18n::english(), + &FixtureMeasure, + ) + .expect("the minimal fixture loads") + .compiled; + let model = plx_appkit::player_hud::model::HudModel { + controls: plx_appkit::player_hud::Controls::for_item(true, true, true), + chapters: true, + detail: true, + ..Default::default() + }; + let folded = plx_appkit::more_menu::folded_rows(minimal.folds(), &model, meta.view()); + let page = PlayerOverlayScreen::new_folded(&ps, meta.view(), ENTRY, OverlayKind::More { page: None }, false, None, folded.clone()); + let cx = Cx { views: &ps, ..cx() }; + let mut named = Vec::new(); + for row in &folded { + let key = MoreRow::Act(MoreAction::Hud(row.command)).key().0; + let projected = Focusable::::a11y(&page, &key, &cx).unwrap_or_else(|| panic!("{:?} is a row", row.command)); + let want = match row.command { + HudCommand::Previous => Some("10"), + HudCommand::Next => Some("12"), + HudCommand::FromBeginning => Some("11"), + _ => None, + }; + assert_eq!(projected.subject.as_deref(), want, "{:?} ({})", row.command, projected.path); + if want.is_some() { + named.push(projected.path.to_string()); + } + } + assert!(named.len() >= 2, "the minimal package folds title-starting commands: {named:?}"); + // the rows that are not folds (Quality, Speed, Stats) name nothing + for row in [MoreRow::OpenQuality, MoreRow::OpenSpeed, MoreRow::Act(MoreAction::ToggleStats)] { + let projected = Focusable::::a11y(&page, &row.key().0, &cx).expect("a root row"); + assert_eq!(projected.subject, None, "{}", projected.path); + } +} + +/// **A track pick and a subtitle-search result write to the title playing, so each names it** (`TrackRow::writes_title`): +/// the audio and subtitle rows (Off and Forced only included) select the part's streams on the PMS. The rows that open +/// a page or pick a local setting (Timing, Style) name none. +#[test] +fn a_track_pick_names_the_title_it_writes_to() { + let _g = plx_base::testlock::serial(); + plx_media::player::sidecar::reset(); + let ps = middle_episode_session(); + let mut store = plx_data::stores::metadata::MetadataStore::default(); + assert!(store.run(plx_data::stores::metadata::MetadataCmd::InstallPlaying(Some( + english_audio_with_subs(&ps, vec![plx_data::metadata::Stream { + id: 1, + index: 0, + lang: "English".into(), + lang_code: "eng".into(), + codec: "srt".into(), + ..Default::default() + }]), + )))); + let rows = |tab: i32| { + let page = PlayerOverlayScreen::new(&ps, store.view(), ENTRY, OverlayKind::Tracks { tab }); + let cx = Cx { views: &ps, ..cx() }; + let mut elems = Vec::new(); + Focusable::::a11y_elems(&page, GroupId(0), &cx, &mut elems); + elems.iter() + .filter_map(|key| Focusable::::a11y(&page, key, &cx)) + .map(|a| (a.path.to_string(), a.subject.map(std::borrow::Cow::into_owned))) + .collect::>() + }; + let subject_of = |rows: &[(String, Option)], id: &str| { + rows.iter().find(|(path, _)| path == id).unwrap_or_else(|| panic!("{id} is a row: {rows:?}")).1.clone() + }; + let audio = rows(0); + assert_eq!(subject_of(&audio, "audio.0").as_deref(), Some("11"), "an audio pick: {audio:?}"); + let subs = rows(1); + for id in ["off", "forced", "sub.0"] { + assert_eq!(subject_of(&subs, id).as_deref(), Some("11"), "{id}: {subs:?}"); + } + for id in ["timing", "style"] { + assert_eq!(subject_of(&subs, id), None, "{id} writes nothing of the title's: {subs:?}"); + } + // nothing playing: nothing to name + let idle = plx_media::route::PlaybackSession::IDLE; + let page = PlayerOverlayScreen::new(&idle, store.view(), ENTRY, OverlayKind::Tracks { tab: 1 }); + let off = TrackRow::SubOff.key().0; + let projected = Focusable::::a11y(&page, &off, &cx()).expect("the Off row"); + assert_eq!(projected.subject, None); +} + +/// **A quality rung names the title it re-resolves**: on a live play the item playing (`cur_rk`), on a failed one the +/// REQUEST the failure read-out's Retry repeats (`app::playback::apply_more_action` retries `ps.request` when the +/// state is `Error`, and a request whose plan never landed is not `cur_rk`). The Stats switch names none. +#[test] +fn a_quality_rung_names_the_title_it_re_resolves() { + let _g = plx_base::testlock::serial(); + plx_media::speed_audio::force_speed_decoder_for_test(true); // a host test loads no FFmpeg + let mut ps = middle_episode_session(); + let meta = plx_data::stores::metadata::MetadataStore::default(); + let rungs = |ps: &plx_media::route::PlaybackSession| { + let page = PlayerOverlayScreen::new(ps, meta.view(), ENTRY, OverlayKind::More { page: Some(MorePage::Quality) }); + let cx = Cx { views: ps, ..cx() }; + let mut elems = Vec::new(); + Focusable::::a11y_elems(&page, GroupId(0), &cx, &mut elems); + elems.iter() + .filter_map(|key| Focusable::::a11y(&page, key, &cx)) + .map(|a| (a.path.to_string(), a.subject.map(std::borrow::Cow::into_owned))) + .collect::>() + }; + let live = rungs(&ps); + let (rung_rows, other): (Vec<_>, Vec<_>) = live.iter().partition(|(id, _)| id.contains("rung.")); + assert!(!rung_rows.is_empty(), "the Quality page lists rungs: {live:?}"); + assert!(rung_rows.iter().all(|(_, subject)| subject.as_deref() == Some("11")), "live: the item playing: {rung_rows:?}"); + assert!(other.iter().all(|(_, subject)| subject.is_none()), "the other rows name none: {other:?}"); + // a play that failed before its plan landed: the failure screen's quality pick retries the request, not `cur_rk` + plx_media::route::seed_request_for_test(&mut ps, "99"); + plx_media::route::refuse_for_test(&mut ps, plx_media::route::PlayVerdict::DirectPlayDisabled); + assert_eq!(plx_media::player::state(&ps), plx_media::player::PlaybackState::Error, "rig: the play failed"); + let failed = rungs(&ps); + assert!( + failed.iter().filter(|(id, _)| id.contains("rung.")).all(|(_, subject)| subject.as_deref() == Some("99")), + "failed: the request the retry repeats: {failed:?}" + ); +} + /// **A folded row closes More first, then asks the app's one performer for its command.** OK on each row of the /// root a package folds dismisses the menu and asks `PlayerReq::Command(command)`, in that order and with nothing /// else: the order the Tracks->Timing hand-off keeps, so a row that opens a panel or a section finds the menu diff --git a/rust-modules/screens/src/registry.rs b/rust-modules/screens/src/registry.rs index 5c0b7a6901..0af0400f2c 100644 --- a/rust-modules/screens/src/registry.rs +++ b/rust-modules/screens/src/registry.rs @@ -805,6 +805,25 @@ pub struct CardIdentity { pub elem: u32, } +/// **The page a Play Version panel belongs to**: the metadata store's loaded detail when it is the item `arg` +/// names. The mount reads the versions off it, and [`versions_subject`] the key its rows play. +fn versions_page<'a>( + meta: plx_data::metadata::MetadataView<'a>, + arg: &crate::versions_panel::VersionsArg, +) -> Option<&'a plx_data::metadata::Detail> { + meta.current().filter(|d| plx_plex::plex::same_item((d.sid, d.rk.as_str()), (arg.sid, arg.rk.as_str()))) +} + +/// **The ratingKey a Play Version row plays**, the subject of its accessibility id: the page's Play pill's own +/// (`detail::hero_control_subject(Play, ..)`: on a show the episode the hero plays, else the page's item), because +/// the row's OK delivers `AppMsg::PlayVersion` to that page, which plays it as its Play pill would. It lives here +/// because a panel may not name the page's module (`ci/check-deps.sh`, `sibling`), and it reads the page off +/// the host's metadata view, the way the mount does. +pub(crate) fn versions_subject(cx: &Cx<'_, H>, arg: &crate::versions_panel::VersionsArg) -> Option { + let d = versions_page(H::metadata(cx), arg)?; + crate::detail::play_subject(d).map(str::to_owned) +} + /// The slot ranges to project, sorted and merged, clamped to `total`. Shared by the sliding-window /// key projections of the Library grid and the Collection page. pub(crate) fn merged_ranges(mut ranges: Vec>, total: usize) -> Vec> { @@ -2463,10 +2482,7 @@ where crate::alt_sources::AltSourcesScreen::new(entry, arg.clone(), H::metadata(cx)), ), AppArg::VersionsPanel(arg) => { - let versions = H::metadata(cx) - .current() - .filter(|d| plx_plex::plex::same_item((d.sid, d.rk.as_str()), (arg.sid, arg.rk.as_str()))) - .map_or(&[][..], crate::detail::hero_versions); + let versions = versions_page(H::metadata(cx), arg).map_or(&[][..], crate::detail::hero_versions); Box::new(crate::versions_panel::VersionsPanelScreen::new(entry, arg.clone(), versions)) } AppArg::TracksPanel(arg) => Box::new( diff --git a/rust-modules/screens/src/versions_panel.rs b/rust-modules/screens/src/versions_panel.rs index 4da5e56b99..0337fb281a 100644 --- a/rust-modules/screens/src/versions_panel.rs +++ b/rust-modules/screens/src/versions_panel.rs @@ -17,7 +17,7 @@ use std::convert::Infallible; use plx_data::pms::MediaVersion; use plx_plex::plex::{MediaId, ServerId}; -use crate::registry::{AppLike, AppMsg, PageMemory}; +use crate::registry::{AppLike, AppMsg, MetadataLike, PageMemory}; use plx_ui::a11y::{A11y, A11yPath}; use plx_ui::frame::Budget; use plx_machine::machine::{ @@ -161,7 +161,7 @@ impl> Machine for VersionsPanelScreen { } /// One column of `Bare` rows over the table's own cursor, *Also available*'s `Focusable`. -impl> Focusable for VersionsPanelScreen { +impl + MetadataLike> Focusable for VersionsPanelScreen { fn groups(&self, cx: &Cx<'_, H>, out: &mut Vec) { out.push(GroupSpec { id: GroupId(0), @@ -211,9 +211,19 @@ impl> Focusable for VersionsPanelScreen { /// ([`plx_ui::geom::table_a11y`]): `n` is the row's ordinal among the focusable rows (the same /// count `GroupSpec::len` states), so a separator or note never shifts an id. The label is the /// row's own text, for the state file only. The elements and the inverse are the shared ones. - fn a11y(&self, elem: &u32, _cx: &Cx<'_, H>) -> Option> { + /// + /// **A row plays, so it names what it plays.** OK delivers `AppMsg::PlayVersion` to the page, which plays the + /// hero's title as its Play pill would, in the version the row names: the subject is the Play pill's own + /// (`registry::versions_subject`: the page's loaded item, read from the metadata store the way the mount reads the + /// versions), so `versions.row.` needs a press that names the title. The key is derived from `cx`, not kept on the + /// screen: it is no part of the screen's recorded state (`SHAPE`). + fn a11y(&self, elem: &u32, cx: &Cx<'_, H>) -> Option> { let slot = self.form.index_of_key(RowKey(*elem))?; - plx_ui::geom::table_a11y(&self.form.table, Some(&self.form), slot) + let row = plx_ui::geom::table_a11y(&self.form.table, Some(&self.form), slot)?; + Some(match crate::registry::versions_subject(cx, &self.arg) { + Some(rk) => row.with_subject(rk), + None => row, + }) } fn a11y_elems(&self, g: GroupId, _cx: &Cx<'_, H>, out: &mut Vec) { if g == GroupId(0) { @@ -245,7 +255,7 @@ impl LogicalState for VersionsPanelScreen { } } -impl> Screen for VersionsPanelScreen { +impl + MetadataLike> Screen for VersionsPanelScreen { fn name(&self) -> &'static str { "versions" } @@ -343,6 +353,26 @@ pub(crate) mod tests { type Memory = PageMemory; } + thread_local! { + // TEST ONLY: the page a panel reads its subject off, as `screens::detail::tests`'s `TEST_METADATA`. + static TEST_METADATA: std::cell::UnsafeCell = + std::cell::UnsafeCell::new(plx_data::stores::metadata::MetadataStore::default()); + } + fn test_store() -> &'static mut plx_data::stores::metadata::MetadataStore { + TEST_METADATA.with(|cell| unsafe { &mut *cell.get() }) + } + impl MetadataLike for HostFixture { + fn metadata<'a>(_cx: &Cx<'a, Self>) -> plx_data::metadata::MetadataView<'a> { + test_store().view() + } + } + /// Make `d` the page the metadata store holds (or none), and keep the shared store to this test. + fn page(d: Option) -> plx_base::testlock::Serial { + let guard = plx_base::testlock::serial(); + plx_data::metadata::set_current_for_test(test_store().state_mut(), d); + guard + } + fn panel() -> VersionsPanelScreen { let anchor = [500.0f32, 600.0, 64.0, 64.0].map(f32::to_bits); VersionsPanelScreen::new( @@ -388,6 +418,42 @@ pub(crate) mod tests { assert_eq!(Focusable::::a11y_find(&p, &past, &cx), None); } + fn row_subject(p: &VersionsPanelScreen, row: u32) -> Option { + let cx = cx(); + Focusable::::a11y(p, &row, &cx)?.subject.map(Cow::into_owned) + } + + /// **A row plays, so it names the title it plays** (`versions.row.` is in `SUBJECT_BEARING`): the subject is + /// what the page's Play pill plays, the key `AppMsg::PlayVersion` acts on (`DetailScreen::play_hero`), and not the + /// route's. A movie page plays itself; a show page plays the episode its hero plays, so the route's show key + /// would name the wrong title. With no page loaded (or another one) a row names none, and the guarded doors + /// cannot press it. + #[test] + fn a_row_names_the_title_its_page_plays() { + use plx_data::metadata::{Detail, Episode}; + let sid = ServerId::from_raw(1); + let p = panel(); + { + let _guard = page(Some(Detail { sid, rk: "42".into(), kind: "movie".into(), ..Default::default() })); + for row in 0..plx_appkit::version_list::sample().len() as u32 { + assert_eq!(row_subject(&p, row).as_deref(), Some("42"), "row {row} plays the movie"); + } + } + { + let episode = Episode { rk: "e1".into(), index: 1, season: 1, ..Default::default() }; + let _guard = page(Some(Detail { + sid, rk: "42".into(), kind: "show".into(), is_show: true, episodes: vec![episode].into(), ..Default::default() + })); + assert_eq!(row_subject(&p, 0).as_deref(), Some("e1"), "a show's rows play the hero's episode, not the show"); + } + { + let _guard = page(Some(Detail { sid, rk: "another".into(), kind: "movie".into(), ..Default::default() })); + assert_eq!(row_subject(&p, 0), None, "another page is loaded: the panel names no title"); + } + let _guard = page(None); + assert_eq!(row_subject(&p, 0), None, "no page loaded"); + } + /// OK on a row closes the panel and reports THAT version to the page that opened it. #[test] fn a_row_reports_its_version_to_the_host_page() { diff --git a/rust-modules/src/app/run.rs b/rust-modules/src/app/run.rs index b70fbf22c6..c757a1728a 100644 --- a/rust-modules/src/app/run.rs +++ b/rust-modules/src/app/run.rs @@ -8606,6 +8606,155 @@ mod lifecycle_regression_tests { assert_eq!(app.pages.input.press.scale(), 1.0); } + /// **`[Down, press:@]` across Home's hero/grid door, through the real dispatcher.** The + /// Down crosses the door and leaves the picture on the hero for a few frames (a human's quick OK + /// there lands on the hero's Play); the by-id press of the card the Down landed on moves no focus + /// (it is already there), so nothing clears that remap. Home projects its focused element not + /// loaded while the picture lags, and the dispatcher, asking with the focus the Down left (not + /// the one its drain began with), refuses the press as `unloaded`: nothing plays and nothing + /// opens. Once the picture has settled the same press opens the card's title. + #[cfg(feature = "devtriggers")] + #[test] + fn a_by_id_press_in_the_batch_of_the_key_that_crossed_homes_door_is_refused_until_the_picture_settles() { + use plx_machine::machine::{InputEvent, InputKind, Key, OkTap, Source, Tick}; + let _serial = plx_base::testlock::serial(); + plx_base::eventlog::with_private_log(|| { + let mut app = app(); + let mut t = 0u32; + super::super::bridge::show_page(&mut app.pages, AppArg::Home); + app.runtime.bridge(&mut app.bridge).seed_hub_grid_for_test(3, 4); + settle(&mut app, &mut t); + let home = app.pages.nav.top_page().unwrap().id; + let at = |t: u32| Tick { ms: t + 16, dt_us: 16_000 }; + let by_id = |id: &str, press: Option<&str>, t: u32| InputEvent { + at: at(t), + source: Source::RemoteFifo, + kind: InputKind::ById { + id: id.into(), + press: press.map(|_| OkTap { sym: 0x0d, wcode: 0 }), + expect: press.map(std::sync::Arc::::from), + }, + }; + let snapshot = |app: &mut App| app.pages.a11y_snapshot(&mut app.runtime.bridge(&mut app.bridge)); + let refused = || std::fs::read_to_string(plx_base::eventlog::events_log()).unwrap_or_default() + .lines().filter(|line| line.contains("a11y: refused")).map(str::to_owned).collect::>(); + let hero = "home.hero.play"; + + // the card a Down from the hero's Play lands on, and its title (a dry run) + let tokens = |app: &mut App, t: &mut u32, id: &str| { + let now = *t; + step(app, t, vec![by_id(id, None, now)]); + settle(app, t); + }; + tokens(&mut app, &mut t, hero); + assert_eq!(snapshot(&mut app).focused.as_deref(), Some(hero), "premise: the hero's Play is focused"); + let now = t; + step(&mut app, &mut t, vec![plx_ui::fixture::key(Key::Down, at(now))]); + settle(&mut app, &mut t); + let after = snapshot(&mut app); + let card = after.focused.clone().expect("a Down from the hero lands somewhere"); + let rk = after.elems.iter().find(|e| e.id == card).and_then(|e| e.subject.clone()) + .expect("the card carries the ratingKey its press acts on"); + assert!(card.starts_with("home.") && card != hero, "premise: the Down crossed the door onto a card: {card}"); + + // back to the hero, then ONE batch: the Down and the press naming the card it lands on + tokens(&mut app, &mut t, hero); + assert_eq!(snapshot(&mut app).focused.as_deref(), Some(hero)); + assert!(refused().is_empty(), "premise: nothing refused so far: {:?}", refused()); + let now = t; + step(&mut app, &mut t, vec![plx_ui::fixture::key(Key::Down, at(now)), by_id(&card, Some(&rk), now)]); + for _ in 0..24 { step(&mut app, &mut t, vec![]); } + let lines = refused(); + assert_eq!(lines.len(), 1, "{lines:?}"); + assert!(lines[0].ends_with(&format!("a11y: refused press {card} unloaded owner=home")), "{lines:?}"); + assert_eq!(snapshot(&mut app).focused.as_deref(), Some(card.as_str()), "the Down moved focus"); + assert_eq!(app.pages.nav.top_page().unwrap().id, home, "nothing opened"); + assert!(!plx_media::route::play_pending(), "and nothing played"); + + // the picture has caught up: the same press opens the card's title + let now = t; + step(&mut app, &mut t, vec![by_id(&card, Some(&rk), now)]); + for _ in 0..24 { step(&mut app, &mut t, vec![]); } + assert_eq!(refused().len(), 1, "no second refusal: {:?}", refused()); + assert_ne!(app.pages.nav.top_page().unwrap().id, home, "the card's title opened"); + }); + } + + /// **A press accepted against one hero is played against it, even in the frame the carousel turns** + /// (PR #1442, round 7). A hero control's press commits a dip (about 200 ms) after OK and plays the + /// title the billboard shows AT THE COMMIT; the press of the control that already has focus moves + /// nothing, so the 8 s countdown ran on, and a countdown that ran out inside the dip turned the page: + /// `press home.hero.play --rk X`, accepted against X, played the next page's title. The hardest frame + /// is the one the press ARMS in: the dispatcher built that frame's press read before its drain, so + /// the frame's own Tick, delivered after the arm, read a press that was not live, and the carousel + /// turned there. A dry run finds the frame the page turns on; the press is then delivered in that + /// frame's batch. + #[cfg(feature = "devtriggers")] + #[test] + fn a_hero_press_accepted_in_the_frame_the_carousel_turns_plays_the_title_it_was_accepted_against() { + use plx_machine::machine::{InputEvent, InputKind, OkTap, Source, Tick}; + let _serial = plx_base::testlock::serial(); + // One run: Home on the hero's Play, then frames until the page has turned (or, with + // `press_in`, that many frames and ONE batch carrying the press). Returns the frame the page + // turned on (a dry run only), the title the press named, and the titles Home asked to play. + let run = |press_in: Option| -> (Option, String, Vec) { + plx_base::eventlog::with_private_log(|| { + let mut app = app(); + let mut t = 0u32; + super::super::bridge::show_page(&mut app.pages, AppArg::Home); + app.runtime.bridge(&mut app.bridge).seed_hubs_for_test(3, plx_data::pms::HubState::Ready); + settle(&mut app, &mut t); + let at = |t: u32| Tick { ms: t + 16, dt_us: 16_000 }; + let by_id = |press: Option<&str>, t: u32| InputEvent { + at: at(t), + source: Source::RemoteFifo, + kind: InputKind::ById { + id: "home.hero.play".into(), + press: press.map(|_| OkTap { sym: 0x0d, wcode: 0 }), + expect: press.map(std::sync::Arc::::from), + }, + }; + let shown = |app: &mut App| { + let snapshot = app.pages.a11y_snapshot(&mut app.runtime.bridge(&mut app.bridge)); + assert_eq!(snapshot.focused.as_deref(), Some("home.hero.play"), "premise: Play is focused"); + snapshot.elems.iter().find(|e| e.id == "home.hero.play").and_then(|e| e.subject.clone()) + .expect("the hero's Play carries the ratingKey it acts on") + }; + let now = t; + step(&mut app, &mut t, vec![by_id(None, now)]); + settle(&mut app, &mut t); + let named = shown(&mut app); + let mut turned = None; + // the countdown restarts at the focus move: 8 s is 500 frames, then some + for frame in 0..560usize { + if press_in == Some(frame) { + let now = t; + step(&mut app, &mut t, vec![by_id(Some(&named), now)]); + // the dip, the commit and the spring-back + for _ in 0..40 { step(&mut app, &mut t, vec![]); } + break; + } + step(&mut app, &mut t, vec![]); + if press_in.is_none() && shown(&mut app) != named { + turned = Some(frame); + break; + } + } + let played = app.runtime.bridge(&mut app.bridge).take_observed_home_commands().into_iter() + .filter_map(|(_, request, _)| match request { plx_screens::registry::HomeReq::Play { rk, .. } => Some(rk), _ => None }) + .collect(); + (turned, named, played) + }) + }; + let (turned, named, _) = run(None); + let frame = turned.expect("premise: the countdown turns the page within 560 frames"); + assert!(frame > 400, "premise: the turn is the 8 s countdown's, frame {frame}"); + let (_, named_again, played) = run(Some(frame)); + assert_eq!(named_again, named, "premise: the same hero is shown when the press arrives"); + assert_eq!(played, vec![named.clone()], + "the press named {named} in the frame the page turned on and must play it, not the next page's"); + } + /// What `hold_bench_tick` put on the input queue in one frame: `(ok_down, ok_up, back, direction)` /// counts, plus whether an item menu was up when it ran (so an OK edge can be held against it). #[derive(Default, Debug)] diff --git a/rust-modules/src/focusprobe.rs b/rust-modules/src/focusprobe.rs index 68b337a44b..714b7147a3 100644 --- a/rust-modules/src/focusprobe.rs +++ b/rust-modules/src/focusprobe.rs @@ -14,6 +14,13 @@ //! differs from the last one. What a key press did is then the diff between the fingerprint before //! it and the fingerprint after. //! +//! The fingerprint is the readback for travel: it says THAT focus moved, by index and rating key, +//! not by an element's name. The structured readback by id is `state:` (`app/a11y_state.rs`): the app +//! writes `plxnative-a11y.json` with the route, the input owner, the focused full id and every +//! element's id, role, rect and subject, and a test reaches a target with `focus:` / +//! `press:` (`tools/a11y.py`, `tools/tv-session.sh focus|press|state`) instead of walking keys. +//! A flow whose subject is the travel itself, like this module's, keeps its key walk and this line. +//! //! # Rules this module keeps //! //! **Read-only.** Every field comes from a getter the screen already exposes for the app's own diff --git a/rust-modules/ui/src/CLAUDE.md b/rust-modules/ui/src/CLAUDE.md index 6dc875deb1..67eda52d87 100644 --- a/rust-modules/ui/src/CLAUDE.md +++ b/rust-modules/ui/src/CLAUDE.md @@ -78,6 +78,27 @@ arguments, and its time is the `dt` it is handed. nothing here is close — and then it lands *here*, as a reusable `View`, so the next screen gets it for free. + **A new focusable element answers an accessibility id.** Tests and agents reach it with + `focus:` / `press:` (`tools/a11y.py`), not by walking keys to it, so an element that + cannot be named cannot be tested. An element whose press ACTS ON a title it names (it plays, restarts, + finishes or retries it, marks it watched or unwatched, bookmarks it, or opens that title's own page or menu where + the title can change under the press: a card, a credit, the Home carousel's Info, a hero or menu button, a Play + Version row, a player control that starts a title) also carries the ratingKey of the title the press acts on as its + `subject` (`A11y::with_subject`), because the harness refuses to press it without naming the title (that key is not + always the page's or the playing item's: Detail's Mark watched writes a started show's on-deck episode, + `hero_control_subject`; the player's Next plays the queue neighbour, `HudCommand::plays_rk`). Navigation is not the + test: only a control whose target the page fixes (Go to Show, Also available, the Play Version opener, More, a panel + opener, a seek) carries none. A screen whose OK can land somewhere other than on the focused element (Home's door + remap, after a Dir key) projects that element `loaded: false` while the picture lags its focus, so a by-id press + of it, named or bare, is refused as `unloaded` and the caller retries once the screen has settled. A new such shape joins `SUBJECT_BEARING` in `tools/a11y.py`, the one list, + and `a11y_subject_bearing` in `tools/tv-session.sh`; `tests/test_a11y_tool.py` counts the `with_subject` calls per + file and fails on a file that constructs a Play, queue step or write message it does not list. It gets its id from the three `Focusable` hooks (`a11y`, + `a11y_elems`, `a11y_find`, `screen.rs`) or from the shared widget it composes (`card_a11y` for a + card, `PageHeader`, `LinkedHeading`, `MasterDetail`), never from a screen-local table. + The `#[cfg(test)] mod a11y_coverage_tests` in `rust-modules/screens/src/registry.rs` (its + `coverage()`) is an exhaustive `match` over `AppArg`, so a new screen does not compile in the TEST + build until it is tabled there. + A mechanism is forked the same way and more quietly, because it looks like three lines of glue. Find the ready-made one first; if it almost fits, extend it in place for every caller; if it truly cannot do the job, say why before writing a new one, which then lands here. PR #843 diff --git a/rust-modules/ui/src/a11y.rs b/rust-modules/ui/src/a11y.rs index 7b98ccfc1a..6c5c0e8e25 100644 --- a/rust-modules/ui/src/a11y.rs +++ b/rust-modules/ui/src/a11y.rs @@ -13,7 +13,7 @@ //! [`A11yPath::parse_id`], whose result exists to be COMPARED with a projected path //! ([`Focusable::a11y_find`]); it is never logged and never kept. //! -//! An element's [`A11y::label`] and [`A11y::subject`] (the ratingKey of a catalog card) are runtime +//! An element's [`A11y::label`] and [`A11y::subject`] (the ratingKey of the title the element acts on) are runtime //! text. They never reach a `LogLine` or a heartbeat; the state file a test reads back is where they //! are written. A `press:@` token records its `@` text in the recording's `in` //! row, which on a press that resolves equals the element's subject, so a recording of a @@ -283,10 +283,16 @@ pub enum Role { /// One element's projection: its id and what a test reads about it. /// -/// `label` and `subject` are runtime text (a card's title, its ratingKey): they go to the state file, +/// `label` and `subject` are runtime text (a card's title; the ratingKey of the title the press acts on, see +/// `SUBJECT_BEARING` in `tools/a11y.py`): they go to the state file, /// never to a log line or heartbeat (a press's `@` guard is kept by a recording, see the /// module doc). -/// `loaded` is false for a placeholder whose item has not arrived. The borrow is of the view the +/// `loaded` is false for a placeholder whose item has not arrived, and more generally for an element +/// that is **not pressable yet**: a screen whose OK would not land on its focused element for a few +/// frames (Home's hero/grid door, while the picture lags the key that crossed it) projects that element +/// not loaded, and a by-id press of it is refused as `unloaded`. The element's own `a11y` keeps its label +/// and subject, but the state file lists neither for an element that is not `loaded` +/// (`dispatch::snapshot::project_into`). The borrow is of the view the /// projection was asked of; a view built per query returns [`A11y::into_owned`]. #[derive(Clone, Debug, PartialEq, Eq)] pub struct A11y<'a> { diff --git a/rust-modules/ui/src/dispatch.rs b/rust-modules/ui/src/dispatch.rs index 2dae593efb..0aa1702e5f 100644 --- a/rust-modules/ui/src/dispatch.rs +++ b/rust-modules/ui/src/dispatch.rs @@ -3164,6 +3164,14 @@ where let entry_owner = InputOwner::Entry(entry); addressed.owner = if self.owner_entry() == Some(entry) { self.owner() } else { entry_owner }; addressed.focus = self.input.engine.read(entry_owner); + // **The press is read where the delivery runs, as the focus is.** `parts` was + // built before this drain, and an OK-down arms its press INSIDE it (`Fx::Press`, + // queued ahead of the next delivery): the frame's own Tick, delivered after the + // arm, would otherwise read a press that is not live yet, and a screen that acts + // on a press standing on its element (Home's carousel, which restarts its countdown + // while a hero control's press dips: `HomeScreen::hero_press_armed`) would be one + // frame late on exactly the frame the press began. + addressed.press = self.input.press_read(parts.tick.ms); addressed.page_image = self.page_image_read().for_owner(entry, id); } // **A page whose first seat is still on its way HOLDS an arrow other than Up** (design diff --git a/rust-modules/ui/src/dispatch/by_id.rs b/rust-modules/ui/src/dispatch/by_id.rs index b43cf27936..6f50723a74 100644 --- a/rust-modules/ui/src/dispatch/by_id.rs +++ b/rust-modules/ui/src/dispatch/by_id.rs @@ -5,20 +5,44 @@ //! arms on X and `[focus:X, ok]` presses X. The dispatcher (not a screen) then: //! //! 1. resolves the id against the input owner's view only (`owner_view`, so an id of the page under -//! a modal is `Unknown`: the modal owns input) through the replay hook +//! a modal is `Unknown`: the modal owns input), asking the view with the engine's focus as this +//! position finds it (not as the drain began), through the replay hook //! [`ReplayAuthority::resolve_id`](super::ReplayAuthority::resolve_id); -//! 2. for a press with a subject, compares the element's `subject` first (the race between a -//! `state` read and the press is closed in this one step); +//! 2. for a press, refuses an element that is not `loaded` (`unloaded`), then, for a press with a +//! subject, compares the element's `subject` as the page stands AT THAT POSITION (the race between +//! a `state` read and the press is closed there, and only up to the arm: see "The dip" below); //! 3. on success abandons a press armed elsewhere (`abandon_if_off`, the rule a direction key //! uses), sets focus with `By::Script` and notes the d-pad (hover is not live); -//! 4. pushes to the FRONT of the queue, in order, the `FocusMoved{by: Script}` delivery and, for a -//! press, an ordinary OK `Down` and `Up`. +//! 4. pushes to the FRONT of the queue, in order, the `FocusMoved{by: Script}` delivery (when focus +//! moved) and, for a press, an ordinary OK `Down` and `Up`. +//! +//! A press on the element focus ALREADY rests on moves nothing (`FocusEngine::set` answers `Nothing`) and +//! delivers no `FocusMoved`, so a screen cannot tell it from a human's OK. The screen's own answer is +//! its projection of the FOCUSED element: while its OK would land somewhere else than on that element +//! (Home's hero/grid door, while the picture lags a Dir key's move: about 8 frames, 130 ms at 60 fps: the dive's midpoint), the screen projects it +//! `loaded: false`, and step 2 refuses ANY press of it as `unloaded`, subject or not (a linked heading +//! has none to compare). The caller asks again once the screen has settled; `focus:` asks no `loaded`. //! //! The OK Down is delivered next and the screen sees it exactly as a remote OK; unconsumed, it //! arms on the engine's current key, which is now the element. The Up follows, and the delivery //! path applies its release in order after the arm. A later input of the same batch that moves -//! focus off the element abandons the uncommitted press, so the result is the named element -//! pressed, or nothing. **All or nothing**: a refusal moves no focus and emits no key. +//! focus off the element abandons the uncommitted press, so an accepted press acts on the named +//! element or on nothing, and a screen whose OK lands elsewhere says so by projecting the element +//! not loaded (above). **All or nothing**: a refusal moves no focus and emits no key. +//! +//! **The dip is the screen's.** Step 2 closes the race at the delivery, and the press it queues +//! commits a dip later (`MIN_DIP_MS` + `COMMIT_MS`, about 200 ms), when the screen re-reads what the +//! element acts on. What keeps that title from changing inside the dip is the screen reading the +//! press through its context (`cx.press`: `live` and `owner`; a delivery reads it as it stands at its +//! position, so the Tick of the frame that armed the press already sees it) and letting nothing change +//! the title while one stands on its element. Home's carousel does (`HomeScreen::hero_press_armed`): +//! while a press stands on a hero control the 8 s countdown restarts from its full length every tick, +//! as a focus move restarts it, so no turn falls due inside the press and none is owed after it (the +//! next one comes a full interval later). `HomeCmd::Flip` and Left/Right at the hero's edge are +//! REFUSED while the press stands (the page answers `Handled::No` and the turn is dropped, not +//! applied when the press settles), so the caller sends them again once it has. A hero press +//! therefore plays the title it was accepted against. A landing that takes the title OUT of the pool +//! is not held (there is no such title to play): the press acts on its successor. //! //! A refusal leaves one `Fx::Log` line carrying words and ids only (`a11y: refused //! owner=`). The label and subject of an element never reach it. @@ -35,7 +59,9 @@ pub enum IdRefusal { /// The television keyboard, or no page, owns input, or the owner changed earlier in the /// batch so the delivery was addressed to a screen that no longer owns it. NoOwner, - /// A press on a paged slot whose data has not landed. + /// A press on an element that is not loaded: a paged slot whose data has not landed, or the + /// element a screen's OK would not land on yet (Home's focused element while its picture lags the + /// hero/grid door). Not an error: ask again once the screen has settled. Unloaded, /// A press whose `@` is not the element's subject. SubjectMismatch, @@ -123,7 +149,11 @@ where return IdAnswer::refused(IdRefusal::Unknown); } let Split { views, measure, .. } = rig.split(); - let cx = parts.cx::(views, measure); + let mut cx = parts.cx::(views, measure); + // `parts` was built before the drain, so its focus is the one from before any earlier key of + // this batch (`[Down, press:X]`): the screen's projection (`a11y`'s `loaded` of its focused + // element) is asked with the engine's focus as it stands at this delivery position. + cx.focus = self.input.engine.read(InputOwner::Entry(entry)); let Some(elem) = view.a11y_find(&path, &cx) else { return IdAnswer::refused(IdRefusal::Unknown) }; let Some(a11y) = view.a11y(&elem, &cx) else { return IdAnswer::refused(IdRefusal::Unknown) }; // An element the owner cannot place is not one a recording could replay. diff --git a/rust-modules/ui/src/dispatch/snapshot.rs b/rust-modules/ui/src/dispatch/snapshot.rs index 7f6abc3257..0f7269b09c 100644 --- a/rust-modules/ui/src/dispatch/snapshot.rs +++ b/rust-modules/ui/src/dispatch/snapshot.rs @@ -32,7 +32,11 @@ where { /// The owner view as the state file lists it: the route word (the top page's), who owns input, /// the focused full id, every group and every element (no cap), each with where it rests, whether - /// any of it shows, whether it is focused and whether its item has loaded. + /// any of it shows, whether it is focused and whether it is `loaded`: its item has arrived AND a + /// press of it would act on it now (`loaded: false` is "not pressable yet": an unpaged slot, or the + /// focused element of a screen whose OK would land elsewhere for a few frames, Home's hero/grid + /// door lag; the by-id press refuses it as `unloaded`). An unloaded element lists no label and no + /// subject. /// /// A keyboard or an owner-less tree lists no element: nothing is addressable then (the by-id /// resolution refuses `NoOwner`). @@ -86,8 +90,10 @@ where /// /// `ns` qualifies every element's id that has no namespace yet, except those of the `strip` group, /// which take `nav`. An element a view lists but does not project (`a11y` answers `None`) is left -/// out; the group's `len` still counts it, so a reader sees the gap. An unloaded element carries no -/// label and no subject. +/// out; the group's `len` still counts it, so a reader sees the gap. **An element that is not `loaded` +/// carries no label and no subject in the state file, whatever its `a11y` says**: the file is what +/// a caller presses from, and "not loaded" there means "not pressable yet" (an item that has not +/// arrived, or a screen whose OK would not land on the element yet), so it names nothing to press. pub(super) fn project_into + ?Sized>( snap: &mut A11ySnapshot, view: &F, diff --git a/rust-modules/ui/src/fixture.rs b/rust-modules/ui/src/fixture.rs index 00d418d38a..b306a54c38 100644 --- a/rust-modules/ui/src/fixture.rs +++ b/rust-modules/ui/src/fixture.rs @@ -202,6 +202,10 @@ pub struct FixtureRow { /// The first element whose data has not landed (an unloaded paged slot, for the by-id /// `Unloaded` refusal). `usize::MAX` is a row every element of which has landed. pub unloaded_from: usize, + /// The row's FOCUSED element is not loaded (a screen whose press on its focused element lands + /// elsewhere while its picture lags, as Home's does across the hero/grid door). It reads the + /// context's focus, so a resolution handed a stale focus does not see it. + pub unloaded_while_focused: bool, } impl Focusable for FixtureRow { @@ -262,8 +266,10 @@ impl Focusable for FixtureRow { } /// `row.`: the row's role follows what its elements are for the press. The subject is /// `rk` (a catalog key's stand-in) and the label is a word, never a title. - fn a11y(&self, key: &u32, _cx: &Cx<'_, FixtureHost>) -> Option> { + fn a11y(&self, key: &u32, cx: &Cx<'_, FixtureHost>) -> Option> { let i = *key as usize; + let held = self.unloaded_while_focused + && cx.focus.current.is_some_and(|focus| focus.entry == self.entry && focus.elem == *key); (i < self.len).then(|| { let role = match self.kind { ElemKind::Card => Role::Card, @@ -273,7 +279,7 @@ impl Focusable for FixtureRow { A11y::new(A11yPath::new().name("row").index(i), role) .with_label("row item") .with_subject(format!("rk{i}")) - .with_loaded(i < self.unloaded_from) + .with_loaded(i < self.unloaded_from && !held) }) } fn a11y_elems(&self, g: GroupId, _cx: &Cx<'_, FixtureHost>, out: &mut Vec) { @@ -405,6 +411,10 @@ impl FixtureScreen { pub(crate) fn set_unloaded_from(&mut self, from: usize) { self.row.unloaded_from = from; } + /// The row's focused element is not loaded while it holds focus. + pub(crate) fn set_unloaded_while_focused(&mut self, held: bool) { + self.row.unloaded_while_focused = held; + } } impl Composed for FixtureScreen { @@ -447,6 +457,15 @@ impl Machine for FixtureScreen { }); if cx.focus.current.is_some() { self.state.events.push("has_focus"); } } + // Page 660 (a `Control` row) says what the press machine reads in each Tick it is delivered: + // a press standing on the focused element, or none (`a_tick_in_the_frame_a_press_armed_...`). + if self.arg == FixtureArg::Page(660) && matches!(ev, ScreenEvent::Tick(_)) { + self.state.events.push(if cx.press.live && cx.press.owner.is_some() && cx.press.owner == cx.focus.current { + "tick_press_on_focus" + } else { + "tick_press_idle" + }); + } // Page 800 makes stale interactive delivery observable at BOTH exits: the logical // handler and an adapter/store write. The dispatcher must reject it before step. if self.arg == FixtureArg::Page(800) && matches!(ev, @@ -772,6 +791,7 @@ impl FixtureModal { drawn: 0, kind: ElemKind::Card, unloaded_from: usize::MAX, + unloaded_while_focused: false, }, draw_at: 0, recorded_draws: 0, recorded_at: 0, speculative_draws: 0, lifted: None, @@ -1102,6 +1122,7 @@ impl Mounter for FixtureMounter { drawn: 0, kind, unloaded_from: usize::MAX, + unloaded_while_focused: false, }, draw_at: 0, recorded_draws: 0, recorded_at: 0, speculative_draws: 0, lifted: None, @@ -1861,7 +1882,7 @@ fn the_fixture_focusables_conform_to_the_accessibility_id_contract() { hold_hint: Default::default(), }; for (kind, role) in [(ElemKind::Card, Role::Card), (ElemKind::Bare, Role::Row), (ElemKind::Control, Role::Button)] { - let row = FixtureRow { len: 5, group: GroupId(1), entry: EntryId(1), prepared: 0, drawn: 0, kind, unloaded_from: 3 }; + let row = FixtureRow { len: 5, group: GroupId(1), entry: EntryId(1), prepared: 0, drawn: 0, kind, unloaded_from: 3, unloaded_while_focused: false }; super::a11y::conformance(&row, &cx); let third = row.a11y(&2, &cx).unwrap(); assert_eq!(third.role, role); diff --git a/rust-modules/ui/src/input_tests.rs b/rust-modules/ui/src/input_tests.rs index 5d5a7b7903..8b6d8a46bf 100644 --- a/rust-modules/ui/src/input_tests.rs +++ b/rust-modules/ui/src/input_tests.rs @@ -1430,6 +1430,56 @@ fn press_by_id_delivers_ok_down_and_up_so_a_card_commits_and_a_bare_element_acti assert!(!events.contains("\"press_commit\""), "{events}"); } +/// **A by-id input resolves against the focus an earlier input of its batch moved.** The dispatcher +/// hands every delivery of a drain the context it built BEFORE the drain, so a `[Right, press:X]` batch +/// resolved `X` against the focus from before the `Right`. A screen whose press on its focused element +/// lands elsewhere (Home's hero/grid door) answers that by projecting the element NOT LOADED while it +/// holds focus, and the dispatcher must read that projection with the focus the key left, in the same +/// batch as in the next frame, or the press goes through to the other element. +#[test] +fn a_by_id_press_resolves_against_the_focus_an_earlier_key_of_its_batch_moved() { + let (mut d, mut rig) = boot(FixtureArg::Page(700)); + assert_eq!(elem(&d), Some(0), "the row's first element is seated"); + fixture_screen(&mut d).set_unloaded_while_focused(true); + // the key and the press in ONE batch: the press names the element the key lands on + d.frame(&mut rig, tick(16), vec![key(Key::Right, tick(16)), by_id("detail.row.1", true, None, tick(16))], + vec![], &mut NoTap); + settle(&mut d, &mut rig, 32, 800); + assert_eq!(elem(&d), Some(1), "the key moved focus"); + assert_eq!(refusals(&rig), vec!["a11y: refused press detail.row.1 unloaded owner=detail"], "{:?}", rig.log); + let events = events_of(&d, 0); + assert!(!events.contains("\"press_commit\"") && !events.contains("\"activate\""), "nothing was pressed: {events}"); + // the next frame sees the same + d.frame(&mut rig, tick(816), vec![by_id("detail.row.1", true, None, tick(816))], vec![], &mut NoTap); + settle(&mut d, &mut rig, 832, 1600); + assert_eq!(refusals(&rig).len(), 2, "{:?}", rig.log); + assert!(!events_of(&d, 0).contains("\"press_commit\"")); + // `focus:` asks no `loaded`; once the screen has caught up the press is accepted + fixture_screen(&mut d).set_unloaded_while_focused(false); + d.frame(&mut rig, tick(1616), vec![by_id("detail.row.1", true, None, tick(1616))], vec![], &mut NoTap); + settle(&mut d, &mut rig, 1632, 2400); + assert_eq!(refusals(&rig).len(), 2, "{:?}", rig.log); + assert_eq!(events_of(&d, 0).matches("\"press_commit\"").count(), 1); +} + +/// **A delivery reads the press as it stands at its position in the frame, as it reads the focus.** +/// `parts` is built before the drain, and an OK-down arms its press INSIDE it, ahead of the frame's own +/// Tick: that Tick read a press that was not live yet, so a screen that holds something still while a +/// press stands on its element (Home's carousel, over a hero control's dip) was one frame late on +/// exactly the frame the press began, and the frame a countdown ran out on could turn the page under +/// a press it had just been accepted for (PR #1442, round 7). +#[test] +fn a_tick_in_the_frame_a_press_armed_reads_that_press_live_on_the_focused_element() { + let (mut d, mut rig) = boot(FixtureArg::Page(660)); + d.frame(&mut rig, tick(16), vec![], vec![], &mut NoTap); + let events = events_of(&d, 0); + assert!(events.contains("tick_press_idle") && !events.contains("tick_press_on_focus"), "no press yet: {events}"); + d.frame(&mut rig, tick(32), vec![key(Key::Ok, tick(32))], vec![], &mut NoTap); + let events = events_of(&d, 0); + assert!(events.contains("\"tick_press_on_focus\""), + "the arm frame's own Tick must read the press it followed: {events}"); +} + /// **A refused press emits no key, and an `expect` that is not the element's subject presses /// nothing**; the subject that is, presses. An unloaded slot can be focused but not pressed. #[test] diff --git a/tests/README.md b/tests/README.md index 1504a48635..08302dcc4f 100644 --- a/tests/README.md +++ b/tests/README.md @@ -163,6 +163,23 @@ The split is not just anonymisation. The symbolic key keeps "five cases delibera item" visible in the tracked file — which is the fact the per-case resume reset exists for — and it makes a mis-set item a named setup error instead of a mystery failure. +## Reaching a target by accessibility id, not by key walk + +A debug (`devtriggers`) build takes `focus:`, `press:[@]` and `state:` on +the remote FIFO (`tools/a11y.py` writes and reads them; `tools/tv-session.sh focus|press|state` is +the television's form). An id is a place-based dot path in the namespace of whoever owns input +(`nav.watchlist`, `watchlist.grid.card.7`, `itemmenu.watchlist_remove`); a press of an element that acts on a +title it names (`a11y.SUBJECT_BEARING` is the one list) names that title, +`press:@`, the ratingKey of the title the press acts on, and the app refuses it when another title is there (the committed scenario's +`press:itemmenu.watchlist_remove@2001`, `press:home.hero.watchlist@200622` and `press:detail.hero.watchlist@1001`); `state` writes +`plxnative-a11y.json` (route, owner, the focused id, every element) and echoes the nonce, so a script +can assert where focus is before it takes a screenshot. **A script that only needs to REACH a screen +element uses these**, as `tests/scenarios/watchlist_captures.json` does (`keys` entries, plus an +`expect_focus` checked before `shot`; no capture there walks with a direction key: each reaches its +target by id or by a boot trigger, except `w6/detail-offline.png`, which navigates by pointer clicks) and +`tests/player_shots.sh` does (`press:player.control.*`). A key walk stays where the walk is the subject: +the fps scenes, the focus fingerprints (`tests/focusfp.sh`), `hold` and timed keys. + ## Which install it drives (`--flavor`) Three builds can sit on one television: **`com.beb.plxnative`**, the app users install, diff --git a/tests/player_shots.sh b/tests/player_shots.sh index 3a3783e9db..b916cd1012 100755 --- a/tests/player_shots.sh +++ b/tests/player_shots.sh @@ -5,7 +5,8 @@ # the Info card, the Chapters strip and the `…` popover. This boots `plxnative-sim` straight into a # real playback — `plxnative-playurl` at a Range-capable `tests/serve_fixtures.py`, plus # `plxnative-clocksink` so the seam accepts and discards the access units and a presentation clock -# advances — drives the transport with the remote FIFO and writes one shot per panel. The same +# advances — drives the transport with the remote FIFO (each control pressed by its accessibility +# id, `press:player.control.subtitles`, not walked to) and writes one shot per panel. The same # script run against two commits produces two comparable sets. # # CLIP=/tmp/plxfix/clip.mp4 tests/player_shots.sh /tmp/shots-mine @@ -70,24 +71,42 @@ exec 3<> "$D/plxnative-remote" send() { for t in "$@"; do printf '%s ' "$t" >&3; sleep "$STEP"; done; } shot() { printf 'shot ' >&3; sleep 2; mv "$D"/shot-*.png "$OUT/$1.png" 2>/dev/null || true; } +# A control is pressed BY ID (`press:`, tools/a11y.py), not walked to with direction keys: the +# player's ids are `player.control.`, `player.tab.info|chapters` and `player.scrub`, and an id +# names the disc or tab whatever the row holds. A refusal (`a11y: refused press ...` in the event log: +# the HUD is not up, the id names nothing on this clip) presses nothing, so `press` says so and returns +# 1: the shot that would follow is of a state the script did not reach. The HUD must be UP to be +# pressed, and it lingers HUD_LINGER_MS (4.5 s, plx_appkit::player_hud::LINGER_MS) after the input +# that raised it: the shot-then-press gap here (STEP + 2 s = 2.9 s) fits, so a slower STEP can make +# the first press refuse. +refusals() { local n; n=$(grep -c 'a11y: refused' "$LOG" 2>/dev/null || true); echo "${n:-0}"; } +press() { + local before after; before=$(refusals) + printf 'press:player.%s ' "$1" >&3; sleep "$STEP" + after=$(refusals) + [ "$after" -eq "$before" ] && return 0 + grep 'a11y: refused' "$LOG" | tail -n "$((after - before))" >&2 + return 1 +} +must_press() { press "$1" || { echo "player_shots: the app refused press:player.$1 (is the HUD up?)" >&2; exit 1; }; } + # The bare transport, focus at rest on the scrubber. LEFT/RIGHT is a scrub, so a bare `right` -# raises it without changing what the row holds. +# raises it without changing what the row holds (a key: the raise is the subject). send right shot hud # Row 1 is the control row: the Subtitles / Audio / … discs. -send up -send ok; shot menu; send back -send right ok; shot menu-audio; send back -send right ok; shot more; send back +must_press control.subtitles; shot menu; send back +must_press control.audio; shot menu-audio; send back +must_press control.more; shot more; send back -# Row 2 is the tab strip under the discs: Info, then Chapters. -send down down -send ok; shot info; send back -send right ok; shot chapters; send back +# Row 2 is the tab strip under the discs: Info, then Chapters (a clip without chapters draws no +# Chapters tab: its press is refused and that shot is skipped). +must_press tab.info; shot info; send back +if press tab.chapters; then shot chapters; send back; else echo "no Chapters tab on $CLIP: no chapters shot"; fi # …and a transport key WITH a panel up: the panel must stay and the film must pause (issue 28). -send left ok +must_press tab.info sleep 1 printf 'pause ' >&3; sleep 1 shot info-paused diff --git a/tests/scenarios/watchlist_captures.json b/tests/scenarios/watchlist_captures.json index e8b62a76b0..426432e7b3 100644 --- a/tests/scenarios/watchlist_captures.json +++ b/tests/scenarios/watchlist_captures.json @@ -1,5 +1,5 @@ { - "comment": "The Watchlist wave-3 capture list: each ui-sim capture, the board it answers, the dev triggers armed in a fresh instance root, the mock state and the key walk. ONE CAPTURE RECIPE, automated by tools/watchlist_captures.py (`python3 tools/watchlist_captures.py --sim [--out DIR] [--only FILE ...]`): (1) tests/mock_pms.py starts in that process on loopback with authorize_after=2, and `POST /_mock/discover {\"list\": }` resets its Discover list to the capture's `mock` mode (`default` is the 14-title fixture, `empty` clears the list, `movies_only` keeps only the movie titles so Type = TV Shows matches nothing); (2) a fresh instance root gets `plxnative-plextv` and `plxnative-discover` aimed at the mock, and a prep boot with `plxnative-login` signs in through the app's own QR flow - the stored mock session is the account, so no `token` trigger is armed (a `token` boot reads the Watchlist as unavailable for the profile); (3) the capture's `triggers` are armed, the simulator boots, waits `boot_wait_s`, sends each key as a FIFO token through `plxnative-remote` with `key_wait_s` between them (`hold` is `okdown`, 1.2 s, `okup`) and then `shot`; (4) the instance root's shot-N.png becomes `/`, and a capture with `expect_write` fails unless the mock logged that write. `compare` names a baseline PNG (651035609 built the same way in a separate worktree) for the reader to put beside the new capture; the driver does not diff it. Build the simulator with `make sim-macos SIM_TDIR=` (debug; the release build serves as well). Nothing reaches plex.tv, a real server or a television. The PNGs are scratch output, never committed. WAVE 6 (Bump B) captures live under `w6/`: `board` names the Design board each answers; `mock_extra` is merged into the Discover reset (`guids: all` gives every library title a Discover guid so a card's menu offers Add), `unreachable` aims plex.tv at a closed port after the sign-in (the plex.tv-unreachable Detail), and a key `k@0.12` waits 0.12 s instead of key_wait_s (the mid-flip shot); `mock:` POSTs to /_mock/discover mid-walk, `sleep:` waits, and `ck:,` clicks at logical 1920x1080 pixels. DetailOffline is the catalog page of a title matched on the mock server that then went away: the Watchlist matches Harbor Lights, `{\"pms\":\"fail\"}` makes every PMS request answer 503, a click on Movies makes the library read fail (its failure is what commits the server Unreachable), a click on the Watchlist tab reads the list again (the read re-derives the tiles: ServerOffline), and a click on the first tile opens its catalog page. Run it from a release AND a debug simulator and grep each .log/.out for `panic`. HOME HERO captures live under `home-hero/` and answer the HomeHero board (canvas v44): the hero row's bookmark disc, second after Continue/Play, focused (`right` from Play); `heropin 0` holds the first hero and `mock_extra episode_shows: catalog` points every episode's show at the first catalogued show (The Long Meridian: on the `default` list, off the `empty` one), so the Continue Watching hero has a title the Discover stand-in knows. W-NOTIFY (library add flips a tile live) lives in `library-add-flips-tile.png`: the Watchlist tab stays open, `lib:{\"op\":\"add\",\"title\":\"Northbound Tide\"}` makes the mock library hold a title the list carries as coming soon and pushes the `timeline` frame a server would send (the captured three-frame add sequence; only its finished frame owes the re-match), the tile flips from Coming soon to its on-your-servers face with no key pressed, and `expect_log` fails the capture unless the app logged the library re-match.", + "comment": "The Watchlist wave-3 capture list: each ui-sim capture, the board it answers, the dev triggers armed in a fresh instance root, the mock state and the keys it sends. ONE CAPTURE RECIPE, automated by tools/watchlist_captures.py (`python3 tools/watchlist_captures.py --sim [--out DIR] [--only FILE ...]`): (1) tests/mock_pms.py starts in that process on loopback with authorize_after=2, and `POST /_mock/discover {\"list\": }` resets its Discover list to the capture's `mock` mode (`default` is the 14-title fixture, `empty` clears the list, `movies_only` keeps only the movie titles so Type = TV Shows matches nothing); (2) a fresh instance root gets `plxnative-plextv` and `plxnative-discover` aimed at the mock, and a prep boot with `plxnative-login` signs in through the app's own QR flow - the stored mock session is the account, so no `token` trigger is armed (a `token` boot reads the Watchlist as unavailable for the profile); (3) the capture's `triggers` are armed, the simulator boots, waits `boot_wait_s`, sends each `keys` entry as a FIFO token through `plxnative-remote` with `key_wait_s` between them (`hold` is `okdown`, 1.2 s, `okup`), checks `expect_focus` and then sends `shot`. A capture REACHES its target by an accessibility-id token, or by a boot trigger, and never by a direction key: no `keys` entry is `up`, `down`, `left` or `right`. `focus:` moves focus to the element an id names (`nav.watchlist`, `watchlist.grid.card.7`, `home.shelf.2.card.0`) and `press:` focuses it and presses OK (ids are the app's place-based dot paths, grammar in tools/a11y.py; a malformed one fails the run before anything boots). A press of an element that acts on a title it names (the ids are `SUBJECT_BEARING` in tools/a11y.py) names that title, `press:@`, the ratingKey of the title the press acts on, and the app refuses it when another title is there: `press:itemmenu.watchlist_remove@2001` (The Long Meridian, the mock's second Watchlist title) and `press:home.hero.watchlist@200622` (the first Continue Watching episode of the `catalog` mock) and `press:detail.hero.watchlist@1001` (the Detail page of Harbor Lights, the `first_movie_off` mock's first movie); the one bare title press is `watchlist.grid.card.7`, a coming-soon card with no key. The keys that stay are those whose subject is the key itself: `hold`, a timing such as `ok@0.12`, `back`; and the one capture that navigates by pointer, `w6/detail-offline.png`, whose `ck:,` clicks are its walk. `expect_focus` is the full id the app must have focused when the walk is done: the driver asks the app for a `state:` snapshot and fails the capture, naming both ids, when it differs (a walk that ends in a timed key is checked before that key, because the shot must follow it within the wait). A capture whose focus a boot trigger decides (an opener row: `account-menu-new.png`, `item-menu-new.png`) or a pointer click does (`w6/detail-offline.png`) leaves it out, and a refused id (`a11y: refused ...` in the event log) fails the capture either way. A `hold` on a tile (a Watchlist tile, a Home shelf card) opens its menu, so a hold capture's `expect_focus` is the menu's opening row (`itemmenu.`); (4) the instance root's shot-N.png becomes `/`, and a capture with `expect_write` fails unless the mock logged that write. `compare` names a baseline PNG (651035609 built the same way in a separate worktree) for the reader to put beside the new capture; the driver does not diff it. Build the simulator with `make sim-macos SIM_TDIR=` (debug; the release build serves as well). Nothing reaches plex.tv, a real server or a television. The PNGs are scratch output, never committed. WAVE 6 (Bump B) captures live under `w6/`: `board` names the Design board each answers; `mock_extra` is merged into the Discover reset (`guids: all` gives every library title a Discover guid so a card's menu offers Add), `unreachable` aims plex.tv at a closed port after the sign-in (the plex.tv-unreachable Detail), and a key `k@0.12` waits 0.12 s instead of key_wait_s (the mid-flip shot); `mock:` POSTs to /_mock/discover mid-walk, `sleep:` waits, and `ck:,` clicks at logical 1920x1080 pixels. DetailOffline is the catalog page of a title matched on the mock server that then went away: the Watchlist matches Harbor Lights, `{\"pms\":\"fail\"}` makes every PMS request answer 503, a click on Movies makes the library read fail (its failure is what commits the server Unreachable), a click on the Watchlist tab reads the list again (the read re-derives the tiles: ServerOffline), and a click on the first tile opens its catalog page. Run it from a release AND a debug simulator and grep each .log/.out for `panic`. HOME HERO captures live under `home-hero/` and answer the HomeHero board (canvas v44): the hero row's bookmark disc, second after Continue/Play, focused (`focus:home.hero.watchlist`, the hero's bookmark control); `heropin 0` holds the first hero and `mock_extra episode_shows: catalog` points every episode's show at the first catalogued show (The Long Meridian: on the `default` list, off the `empty` one), so the Continue Watching hero has a title the Discover stand-in knows. W-NOTIFY (library add flips a tile live) lives in `library-add-flips-tile.png`: the Watchlist tab stays open, `lib:{\"op\":\"add\",\"title\":\"Northbound Tide\"}` makes the mock library hold a title the list carries as coming soon and pushes the `timeline` frame a server would send (the captured three-frame add sequence; only its finished frame owes the re-match), the tile flips from Coming soon to its on-your-servers face with no key pressed, and `expect_log` fails the capture unless the app logged the library re-match.", "output_dir": "/tmp/watchlist-captures", "boot_wait_s": 5, "key_wait_s": 2, @@ -10,11 +10,9 @@ "mock": "default", "triggers": {}, "keys": [ - "up", - "right", - "right", - "right" - ] + "focus:nav.watchlist" + ], + "expect_focus": "nav.watchlist" }, { "file": "watchlist-page.png", @@ -24,8 +22,9 @@ "watchlist": "" }, "keys": [ - "down" - ] + "focus:watchlist.grid.card.0" + ], + "expect_focus": "watchlist.grid.card.0" }, { "file": "sort-filter-open.png", @@ -35,10 +34,9 @@ "watchlist": "" }, "keys": [ - "down", - "up", - "ok" - ] + "press:watchlist.header.sort" + ], + "expect_focus": "watchlist_menu.type_all" }, { "file": "empty.png", @@ -47,7 +45,8 @@ "triggers": { "watchlist": "" }, - "keys": [] + "keys": [], + "expect_focus": "watchlist.header.sort" }, { "file": "filtered.png", @@ -57,14 +56,11 @@ "watchlist": "" }, "keys": [ - "down", - "up", - "ok", - "down", - "down", - "ok", + "press:watchlist.header.sort", + "press:watchlist_menu.type_shows", "back" - ] + ], + "expect_focus": "watchlist.header.sort" }, { "file": "hold-menu.png", @@ -74,10 +70,10 @@ "watchlist": "" }, "keys": [ - "down", - "right", + "focus:watchlist.grid.card.1", "hold" - ] + ], + "expect_focus": "itemmenu.go_to_show" }, { "file": "after-removal.png", @@ -87,13 +83,11 @@ "watchlist": "" }, "keys": [ - "down", - "right", + "focus:watchlist.grid.card.1", "hold", - "down", - "down", - "ok" + "press:itemmenu.watchlist_remove@2001" ], + "expect_focus": "watchlist.grid.card.1", "expect_write": "PUT /actions/removeFromWatchlist" }, { @@ -105,6 +99,7 @@ "libgrid": "0,2" }, "keys": [], + "expect_focus": "library.grid.card.2", "compare": "watched-tick-base.png" }, { @@ -136,7 +131,8 @@ "triggers": { "detail": "1001" }, - "keys": [] + "keys": [], + "expect_focus": "detail.hero.play" }, { "file": "w6/detail-on-list.png", @@ -145,7 +141,8 @@ "triggers": { "detail": "1001" }, - "keys": [] + "keys": [], + "expect_focus": "detail.hero.play" }, { "file": "w6/detail-added.png", @@ -155,9 +152,9 @@ "detail": "1001" }, "keys": [ - "right", - "ok" + "press:detail.hero.watchlist@1001" ], + "expect_focus": "detail.hero.watchlist", "expect_write": "PUT /actions/addToWatchlist" }, { @@ -168,9 +165,10 @@ "detail": "1001" }, "keys": [ - "right", + "focus:detail.hero.watchlist", "ok@0.12" - ] + ], + "expect_focus": "detail.hero.watchlist" }, { "file": "w6/detail-not-on-server.png", @@ -180,11 +178,9 @@ "watchlist": "" }, "keys": [ - "down", - "down", - "right", - "ok" - ] + "press:watchlist.grid.card.7" + ], + "expect_focus": "catalog.primary" }, { "file": "w6/detail-offline.png", @@ -212,7 +208,8 @@ "triggers": { "detail": "1001" }, - "keys": [] + "keys": [], + "expect_focus": "detail.hero.play" }, { "file": "w6/hold-menu.png", @@ -222,12 +219,10 @@ "heropin": "0" }, "keys": [ - "down", - "down", - "down", - "down", + "focus:home.shelf.2.card.0", "hold" ], + "expect_focus": "itemmenu.go_to_item", "mock_extra": { "guids": "all" } @@ -240,10 +235,10 @@ "watchlist": "" }, "keys": [ - "down", - "right", + "focus:watchlist.grid.card.1", "hold" - ] + ], + "expect_focus": "itemmenu.go_to_show" }, { "file": "w6/watchlist-hold-unplayable.png", @@ -253,20 +248,18 @@ "watchlist": "" }, "keys": [ - "down", - "down", - "right", - "right", - "right", + "focus:watchlist.grid.card.9", "hold" - ] + ], + "expect_focus": "itemmenu.go_to_catalog" }, { "file": "home-hero/outline.png", "mock": "empty", "keys": [ - "right" + "focus:home.hero.watchlist" ], + "expect_focus": "home.hero.watchlist", "board": "HomeHero", "triggers": { "heropin": "0" @@ -279,8 +272,9 @@ "file": "home-hero/filled.png", "mock": "default", "keys": [ - "right" + "focus:home.hero.watchlist" ], + "expect_focus": "home.hero.watchlist", "board": "HomeHero", "triggers": { "heropin": "0" @@ -293,9 +287,9 @@ "file": "home-hero/added.png", "mock": "empty", "keys": [ - "right", - "ok" + "press:home.hero.watchlist@200622" ], + "expect_focus": "home.hero.watchlist", "expect_write": "PUT /actions/addToWatchlist", "board": "HomeHero", "triggers": { @@ -309,9 +303,10 @@ "file": "home-hero/added-midflip.png", "mock": "empty", "keys": [ - "right", + "focus:home.hero.watchlist", "ok@0.12" ], + "expect_focus": "home.hero.watchlist", "board": "HomeHero", "triggers": { "heropin": "0" @@ -332,6 +327,7 @@ "lib:{\"op\":\"add\",\"title\":\"Northbound Tide\"}", "sleep:4" ], + "expect_focus": "watchlist.grid.card.0", "expect_log": "notify: library re-match" } ], diff --git a/tests/test_a11y_tool.py b/tests/test_a11y_tool.py index 42bf97a63a..c132789212 100644 --- a/tests/test_a11y_tool.py +++ b/tests/test_a11y_tool.py @@ -1,21 +1,34 @@ -"""tools/a11y.py: the nonce matching of the `state:` read-back, with no app, no television and no -real clock. A fake clock and an injected `sleep` stand in for time; the "app" is a function that reads -the token the tool wrote to a real FIFO and answers into a temp directory the way the app does -(replace the state file whole).""" +"""tools/a11y.py: the nonce matching of the `state:` read-back, the id grammar, the `focus:` / +`press:` tokens and `expect_focus`, with no app, no television and no real clock. A fake clock and an +injected `sleep` stand in for time; the "app" is a function that reads the token the tool wrote to a real +FIFO and answers into a temp directory the way the app does (replace the state file whole). + +It also holds the harness half of the first by-id migration: tools/watchlist_captures.py's step +classification and focus check, and the committed tests/scenarios/watchlist_captures.json held to the +id grammar (no simulator is needed to know a token is malformed, or that a walk crept back in).""" import importlib.util import json import os import pathlib import re import shutil +import sys import tempfile import unittest +from unittest import mock ROOT = pathlib.Path(__file__).resolve().parents[1] _spec = importlib.util.spec_from_file_location("a11y_tool", ROOT / "tools" / "a11y.py") a11y = importlib.util.module_from_spec(_spec) _spec.loader.exec_module(a11y) +# The capture driver does `import a11y` from its own directory; give it THIS module so the exceptions it +# catches are the ones the tests raise. +sys.modules["a11y"] = a11y +_cspec = importlib.util.spec_from_file_location("watchlist_captures_tool", ROOT / "tools" / "watchlist_captures.py") +captures = importlib.util.module_from_spec(_cspec) +_cspec.loader.exec_module(captures) + HAS_FIFO = hasattr(os, "mkfifo") @@ -99,12 +112,43 @@ def test_a_zero_timeout_still_asks_once(self): self.assertEqual(a11y.wait_for(lambda: "now", 0, clock=Clock(), sleep=lambda s: None), "now") +#: One token as the writer sees it, spelled with each separator the app cuts a FIFO line at: +#: `rust-modules/src/remote.rs` finds the end of the run at ASCII whitespace and then `split_whitespace`s it, so +#: VT, NEL, NBSP, the U+2000 block, the line and paragraph separators and the ideographic space split a word too. +SMUGGLED = ["back press:home.continue.card.0", "back\tpress:x", "back\rpress:x", "back\x0bpress:x", "back\x0cpress:x", + "back\npress:x", "back\u0085press:x", "back press:x", "back press:x", "back press:x", + "back press:x", "back
press:x", "back
press:x", "back press:x", "back press:x", + "back press:x"] + + class Send(unittest.TestCase): def test_a_token_with_whitespace_or_nothing_is_refused(self): - for bad in ["", "two words", "tab\tbed", "line\nbreak", " lead"]: + for bad in ["", "two words", "tab\tbed", "line\nbreak", " lead"] + SMUGGLED: with self.assertRaises(ValueError, msg=repr(bad)): a11y.send("/nonexistent", bad) + @unittest.skipUnless(HAS_FIFO, "needs os.mkfifo") + def test_a_refused_token_writes_nothing_and_a_non_space_word_is_one_token(self): + """U+2019, U+2014 and U+2026 share lead bytes with the Unicode spaces; Cyrillic and accented text are words.""" + runtime = tempfile.mkdtemp(prefix="a11y-tool-") + self.addCleanup(shutil.rmtree, runtime, ignore_errors=True) + fifo = pathlib.Path(runtime, a11y.FIFO_NAME) + os.mkfifo(fifo) + reader = os.open(fifo, os.O_RDONLY | os.O_NONBLOCK) + self.addCleanup(os.close, reader) + for bad in SMUGGLED: + with self.assertRaises(ValueError, msg=repr(bad)): + a11y.send(fifo, bad) + try: + nothing = os.read(reader, 4096) # b"" (no writer left) or, on some platforms, would-block + except BlockingIOError: + nothing = b"" + self.assertEqual(nothing, b"") + words = ["txt:привет", "txt:café", "txt:it’s—a…b", "ck:10,20"] + for word in words: + a11y.send(fifo, word) + self.assertEqual(os.read(reader, 4096).decode().split("\n")[:-1], words) + @unittest.skipUnless(HAS_FIFO, "needs os.mkfifo") def test_one_token_is_one_newline_terminated_write_to_the_fifo(self): runtime = tempfile.mkdtemp(prefix="a11y-tool-") @@ -189,5 +233,747 @@ def test_the_request_is_a_state_token_in_the_apps_grammar(self): self.assertTrue(re.fullmatch(a11y.NONCE_RE, nonce), nonce) +GOOD_IDS = [ + "nav.watchlist", "nav.profile", "home.hero.play", "home.shelf.2.card.5", "home.continue.card.0", + "watchlist.grid.card.0", "watchlist.header.sort", "watchlist_menu.type_all", "library.rail.12", + "itemmenu.version.0", "detail.hero.mark_watched", "under-posters.row.3", "player.control.subtitles", +] +BAD_IDS = [ + "", "home", "nav.", ".nav", "nav..x", "Nav.watchlist", "nav.Watchlist", "nav.watch-list", "nav.05", + "nav.-1", "nav.a b", "nav.a;b", "nav.x'y", "nav.$HOME", "nav.a[0]", "nav.0x1", "under-posters.row-3", + "nav.watchlist\nnav.home", "nav.watchlist ", " nav.watchlist", "-nav.x", "1nav.x", "nav.x@12", None, 7, +] + + +class IdGrammar(unittest.TestCase): + """The app's grammar (`plx_ui::a11y::A11yPath::parse_id`), mirrored; tools/tv-session.sh mirrors it too + (its `cmd_selftest` holds the same lists).""" + + def test_well_formed_ids_pass(self): + for id_ in GOOD_IDS: + self.assertTrue(a11y.valid_id(id_), id_) + + def test_everything_else_is_refused_before_it_is_sent(self): + for id_ in BAD_IDS: + self.assertFalse(a11y.valid_id(id_), repr(id_)) + + def test_an_index_is_canonical_and_a_hyphen_is_only_for_the_namespace(self): + self.assertTrue(a11y.valid_id("nav.0")) + self.assertTrue(a11y.valid_id("nav.10")) + self.assertFalse(a11y.valid_id("nav.00")) + self.assertFalse(a11y.valid_id("nav.01")) + self.assertTrue(a11y.valid_id("a-b.c_d")) + self.assertFalse(a11y.valid_id("a-b.c-d")) + + def test_a_press_subject_is_printable_ascii_with_no_space_and_no_at(self): + for ok in ["1234", "5d7768ab", "a_b-c", "1.2", "x:y"]: + self.assertTrue(a11y.valid_subject(ok), ok) + for bad in ["", "1 2", "12@3", "tab\t", "é", "new\nline", None]: + self.assertFalse(a11y.valid_subject(bad), repr(bad)) + + +class Tokens(unittest.TestCase): + def test_the_builders_and_the_parser_are_inverses(self): + self.assertEqual(a11y.focus_token("nav.watchlist"), "focus:nav.watchlist") + self.assertEqual(a11y.press_token("detail.hero.play"), "press:detail.hero.play") + self.assertEqual(a11y.press_token("home.shelf.2.card.5", "1234"), "press:home.shelf.2.card.5@1234") + for token, parsed in [ + ("focus:nav.watchlist", ("focus", "nav.watchlist", None)), + ("press:detail.hero.play", ("press", "detail.hero.play", None)), + ("press:watchlist.grid.card.3@9001", ("press", "watchlist.grid.card.3", "9001")), + ]: + self.assertEqual(a11y.parse_token(token), parsed) + + def test_a_malformed_id_or_subject_never_becomes_a_token(self): + for id_ in BAD_IDS: + with self.assertRaises(ValueError, msg=repr(id_)): + a11y.focus_token(id_) + with self.assertRaises(ValueError, msg=repr(id_)): + a11y.press_token(id_) + for subject in ["", "1 2", "12@3", "é"]: + with self.assertRaises(ValueError, msg=repr(subject)): + a11y.press_token("watchlist.grid.card.3", subject) + + def test_focus_takes_no_subject_and_other_tokens_are_not_by_id(self): + for token in ["focus:nav.watchlist@12", "focus:", "press:", "press:nav", "ok", "state:abc", "ck:1,2", + "FOCUS:nav.x", "press:nav.x@", "press:nav.x@a@b"]: + with self.assertRaises(ValueError, msg=token): + a11y.parse_token(token) + + def test_refusal_lines_are_picked_out_of_an_event_log(self): + log = "\n".join([ + "12:00:00 boot: fine", + "12:00:01 a11y: refused press watchlist.grid.card.3 subject_mismatch owner=watchlist", + "12:00:02 route=watchlist", + "a11y: refused focus nav.nope unknown owner=home ", + ]) + self.assertEqual(a11y.refusals(log), [ + "a11y: refused press watchlist.grid.card.3 subject_mismatch owner=watchlist", + "a11y: refused focus nav.nope unknown owner=home", + ]) + self.assertEqual(a11y.refusals("nothing here\n"), []) + + +def without_test_code(text): + """`text` of a Rust file with every `#[cfg(test)]` item (a `mod tests { .. }`, a `mod tests;`, a fixture fn) and every + `//` line removed: what the production build compiles, near enough to ask which messages it constructs.""" + out, i = [], 0 + attr = re.compile(r"#\[cfg\((?:test|all\(test|any\(test)[^\n]*\]\s*") + while True: + found = attr.search(text, i) + if not found: + out.append(text[i:]) + break + out.append(text[i:found.start()]) + j = found.end() + while text.startswith("#[", j): # further attributes of the same item + j = text.index("]", j) + 1 + while j < len(text) and text[j] in " \n": + j += 1 + depth = 0 + while j < len(text): # the item: up to its `;`, or its balanced braces + c = text[j] + j += 1 + if c == ";" and depth == 0: + break + if c == "{": + depth += 1 + elif c == "}": + depth -= 1 + if depth == 0: + break + i = j + return "\n".join(line for line in "".join(out).splitlines() if not line.lstrip().startswith("//")) + + +class SubjectBearing(unittest.TestCase): + """An element whose press ACTS ON a title it names (it plays or writes it, or opens that title's own page or menu + where the title can change under the press) is pressed by NAMING that title, the ratingKey of the title the + press acts on: the real-account rule is never to press OK on a title whose ratingKey you have not read, and OK on + a Detail episode's still PLAYS it at once. ONE list of those id shapes lives in `a11y.SUBJECT_BEARING`; + tools/tv-session.sh's `a11y_subject_bearing` is the same list.""" + + SUBJECT_IDS = ["home.shelf.2.card.5", "home.continue.card.0", "watchlist.grid.card.7", "library.grid.card.3", + "collection.card.1", "detail.related.card.0", "detail.episodes.still.3", "detail.episodes.text.3", + "detail.season.2", "filmography.row.4", "catalog.primary", "home.hero.play", "home.hero.info", + "home.hero.watchlist", "detail.hero.play", "detail.hero.restart", "detail.hero.trailer", + "detail.hero.mark_watched", "detail.hero.mark_unwatched", "detail.hero.watchlist", + "itemmenu.play", "itemmenu.watchlist_remove", "itemmenu.version.0", "versions.row.0", "versions.row.3", + "player.control.previous", "player.control.next", "player.control.next_episode", + "player.control.from_beginning", "player.control.skip", "player.control.5", "player.control.12", + "player.section.0", "player.section.1", "player.failure.try_again", + "player.failure.play_automatically", "more.fold.previous", "more.fold.next", + "more.fold.from_beginning", "more.rung.auto", "more.rung.p720", "menu.audio.0", "menu.sub.1", "menu.off", + "menu.forced", "menu.hit.2"] + # `detail.hero.go_to_show|alt|version|more` only navigate or open a menu or a panel: no title is acted on; the + # player's panel openers, seeks, pause and the Up Next / Skip cancels start none (tests/player_shots.sh presses + # `player.control.subtitles|audio|more` and `player.tab.*` bare) + PLAIN_IDS = ["nav.watchlist", "detail.hero.go_to_show", "detail.hero.alt", "detail.hero.version", + "detail.hero.more", "detail.about.card", + "detail.about.languages", "detail.collection.heading", "under-posters.row.3", "filmography.tab.2", + "watchlist.header.sort", "player.control.play", "catalog.back", + "player.control.subtitles", "player.control.audio", "player.control.more", "player.control.play_pause", + "player.control.seek_back", "player.control.seek_forward", "player.control.watch", + "player.control.watch_credits", "player.control.chapters", "player.control.info", + "player.control.go_to_detail", "player.tab.info", "player.tab.chapters", "player.chapter.0", + "player.scrub", "player.failure.change_quality", "player.failure.repair", "player.failure.back", + "player.repair.cancel", "more.quality", "more.speed", "more.stats", + "more.rate.1500", "more.fold.go_to_detail", "more.fold.play_pause", "menu.boost", "menu.loudness", + "menu.timing", "menu.style", "menu.search", "menu.field.size", "menu.retry", "menu.lang.0", + "home.hero.action"] # the failure read-out's retry: no title, so pressed bare + + def test_the_subject_bearing_shapes_are_matched_and_nothing_else(self): + for id_ in self.SUBJECT_IDS: + self.assertTrue(a11y.subject_bearing(id_), id_) + for id_ in self.PLAIN_IDS: + self.assertFalse(a11y.subject_bearing(id_), id_) + + def test_the_guarded_builder_wants_a_subject_for_each_and_the_library_builder_does_not(self): + for id_ in self.SUBJECT_IDS: + with self.assertRaises(ValueError, msg=id_) as e: + a11y.guarded_press_token(id_) + self.assertIn("--subject", str(e.exception)) + self.assertEqual(a11y.guarded_press_token(id_, "77"), f"press:{id_}@77") + self.assertEqual(a11y.press_token(id_), f"press:{id_}") # the library stays unguarded + for id_ in self.PLAIN_IDS: + self.assertEqual(a11y.guarded_press_token(id_), f"press:{id_}") + + def test_the_shell_guard_is_the_same_list(self): + """tools/tv-session.sh cannot import this module, so its `case` line is read back and compared.""" + text = (ROOT / "tools" / "tv-session.sh").read_text() + found = re.search(r"^a11y_subject_bearing\(\) \{.*?^\s*((?:[^\s|)]+\|)*[^\s|)]+)\) return 0 ;;", text, + re.S | re.M) + self.assertIsNotNone(found, "tv-session.sh no longer has a11y_subject_bearing's case line") + self.assertEqual(tuple(found.group(1).split("|")), a11y.SUBJECT_BEARING) + + def test_every_production_with_subject_call_is_a_site_the_list_was_derived_from(self): + """`SUBJECT_BEARING` was read off the code (`git grep with_subject rust-modules`), one entry per production + CALL site. A new call site, even in a file that already has one, is a new id shape: the COUNT per file + fails here until the list above, tv-session.sh's copy and this table say what it presses (a table of + files alone would pass a second call added beside the first).""" + calls = {} + for root, dirs, files in os.walk(ROOT / "rust-modules"): + dirs[:] = [d for d in dirs if not d.startswith("target")] + for name in files: + path = pathlib.Path(root, name) + if path.suffix == ".rs": + n = path.read_text(errors="replace").count(".with_subject(") + if n: + calls[path.relative_to(ROOT / "rust-modules").as_posix()] = n + # file -> (calls in it, what it presses). The detail call is ONE closure, applied to four id shapes. + production = { + "ui/src/cards/mod.rs": (1, "card_a11y:
.card."), + "screens/src/detail/mod.rs": (1, "detail.season., detail.episodes.still|text., the six detail.hero.* " + "controls that play or write (one closure)"), + "screens/src/filmography.rs": (1, "filmography.row."), + "screens/src/catalog.rs": (1, "catalog.primary"), + "screens/src/home/mod.rs": (1, "home.hero.play|info|watchlist (not the failure read-out's action)"), + "screens/src/item_menu.rs": (1, "itemmenu., itemmenu.version. (not a Catalog menu's rows)"), + "screens/src/versions_panel.rs": (1, "versions.row.: the Play Version panel's rows (OK plays)"), + "screens/src/player/mod.rs": (3, "player.control. (control_subject), player.section., " + "player.failure.try_again|play_automatically"), + "screens/src/player/overlay.rs": (2, "more.fold.previous|next|from_beginning (the More menu's folded rows), " + "more.rung. (the quality rungs re-resolve the title); " + "menu.audio|sub|off|forced|hit (the Tracks menu's writes)"), + } + not_a_production_site = { + "ui/src/a11y.rs": (1, "the builder itself and its tests"), + "ui/src/dispatch/snapshot.rs": (1, "its own #[cfg(test)] fixture"), + "ui/src/fixture.rs": (1, "FixtureHost, test-only"), + } + expected = {**production, **not_a_production_site} + self.assertEqual(calls, {path: n for path, (n, _) in expected.items()}) + # every production site is spelled in the list: one glob of SUBJECT_BEARING per id shape it presses + # the Home hero is three explicit ids, not a glob: `home.hero.action` (the failure read-out's retry) acts on + # no title; the Detail hero is six explicit ids: `go_to_show`, `alt`, `version` and `more` only navigate + for glob in ("*.card.*", "detail.episodes.*", "detail.season.*", "filmography.row.*", "catalog.primary", + "home.hero.play", "home.hero.info", "home.hero.watchlist", + "detail.hero.play", "detail.hero.restart", "detail.hero.trailer", "detail.hero.mark_watched", + "detail.hero.mark_unwatched", "detail.hero.watchlist", "itemmenu.*", "versions.row.*", + "player.control.previous", "player.control.next", "player.control.next_episode", + "player.control.from_beginning", "player.control.skip", "player.control.[0-9]*", + "player.section.*", "player.failure.try_again", "player.failure.play_automatically", + "more.fold.previous", "more.fold.next", "more.fold.from_beginning", "more.rung.*", "menu.audio.*", "menu.sub.*", "menu.off", + "menu.forced", "menu.hit.*"): + self.assertIn(glob, a11y.SUBJECT_BEARING) + self.assertEqual(len(a11y.SUBJECT_BEARING), 34) + self.assertNotIn("menu.*", a11y.SUBJECT_BEARING) + self.assertNotIn("home.hero.*", a11y.SUBJECT_BEARING) + self.assertNotIn("detail.hero.*", a11y.SUBJECT_BEARING) + # the player's controls are spelled by word, never `player.control.*`: its panel openers stay pressable bare + self.assertNotIn("player.control.*", a11y.SUBJECT_BEARING) + self.assertNotIn("more.fold.*", a11y.SUBJECT_BEARING) + + # The messages a screen constructs when a press PLAYS or WRITES a title: a Play request, a queue step or restart + # (`PlayerReq::Command` carries Previous, Next and From beginning), the Play Version commit, the watched, + # deck and watchlist writes, the catalog pill's write, the item menu's own actions that Detail and Home push + # through `AppFx::ItemMenu` (`ItemMenuAction::Play`, `PlayFromStart`, `PlayTrailer`, `PlayVersion`, + # `MarkWatched`, `MarkUnwatched`, `RemoveFromDeck`; a file that imports the type as `ItemMenuAction as + # Action`, as Detail's hero and Home's do, is read under that alias too: `acting_hits`), and the Tracks menu's + # two writes to the server: a track pick (`PlayerReq::CommitTrack`, which selects the part's streams) and a + # subtitle-search result (`SubSearchCmd::Download`, which installs the subtitle on the item). It does NOT see + # the presses that only OPEN a title's page or menu (a card, a credit, the Home carousel's Info): those are held + # by the `with_subject` call count per file, and by `card_a11y`'s `*.card.*`. + ITEM_MENU_ACTIONS = r"(?:Play|PlayFromStart|PlayTrailer|PlayVersion|MarkWatched|MarkUnwatched|RemoveFromDeck)" + ITEM_MENU_ALIAS = re.compile(r"ItemMenuAction as (\w+)") + TITLE_ACTING = re.compile( + r"\b(ContentReq::Play\b|HomeReq::Play\b|LibraryReq::Play\b|AppMsg::PlayVersion|" + r"PlayerReq::(?:Command|StandIn|RetryPlayback|PlayAutomatically|More|CommitTrack)\b|SubSearchCmd::Download\b|" + r"Write::(?:Watched|Unwatched|RemoveFromDeck)\b|" + r"ItemMenuAction::" + ITEM_MENU_ACTIONS + r"\b|" + r"WatchlistAdd\b|WatchlistRemove\b|AppFx::Catalog\b|PlayIntent::\w+)") + + @classmethod + def acting_hits(cls, source): + """The title-acting messages the PRODUCTION code of one file constructs.""" + text = without_test_code(source) + hits = cls.TITLE_ACTING.findall(text) + for alias in cls.ITEM_MENU_ALIAS.findall(text): + hits += re.findall(rf"\b{alias}::{cls.ITEM_MENU_ACTIONS}\b", text) + return hits + PLAYER_WORDS = ("player.control.previous", "player.control.next", "player.control.next_episode", + "player.control.from_beginning", "player.control.skip", "player.control.[0-9]*", + "player.section.*", "player.failure.try_again", "player.failure.play_automatically") + # file -> the SUBJECT_BEARING entries guarding the presses it constructs. A file that constructs one of the + # messages and is not here fails this test until someone has decided what its elements are: guard them (a subject + # and an entry) or say why they are not pressable by id. + TITLE_ACTING_FILES = { + "screens/src/catalog.rs": ("catalog.primary",), + "screens/src/detail/extras.rs": ("*.card.*",), # an extra is a card: its subject is the clip's key + "screens/src/detail/hero.rs": ("detail.hero.watchlist",), + "screens/src/detail/mod.rs": ("detail.hero.play", "detail.hero.restart", "detail.hero.trailer", + "detail.hero.mark_watched", "detail.hero.mark_unwatched", "detail.episodes.*", + "versions.row.*"), # receives AppMsg::PlayVersion; the panel names the title + "screens/src/home/mod.rs": ("home.hero.play", "home.hero.watchlist", "*.card.*"), + "screens/src/item_menu.rs": ("itemmenu.*",), + "screens/src/item_menu/watchlist.rs": ("itemmenu.*",), # a Catalog menu's rows have no key: unpressable + "screens/src/library/recommended.rs": ("*.card.*",), + "screens/src/player/mod.rs": PLAYER_WORDS, + "screens/src/player/overlay.rs": ("more.fold.previous", "more.fold.next", "more.fold.from_beginning", + "more.rung.*", "menu.audio.*", "menu.sub.*", "menu.off", "menu.forced", + "menu.hit.*"), + "screens/src/versions_panel.rs": ("versions.row.*",), + "appkit/src/track_menu.rs": ("menu.hit.*",), # a search result's OK asks the download; the overlay names the title + } + + def test_every_file_that_constructs_a_title_acting_message_is_covered_by_the_list(self): + """The systematic half of the guard: SUBJECT_BEARING is read off `with_subject` calls (what carries a + subject), and this reads the other side (what ACTS). Every non-test file of the screens, appkit and ui + crates that constructs a title-acting message is named in `TITLE_ACTING_FILES`, with the list entries that + guard its presses, and no file there has stopped constructing one. An unguarded new Play, queue step or write + is therefore a failure here, not a review finding.""" + found = {} + for crate in ("screens", "appkit", "ui"): + base = ROOT / "rust-modules" / crate / "src" + for root, _dirs, files in os.walk(base): + for name in files: + if not name.endswith(".rs") or name == "tests.rs" or name.endswith("_tests.rs"): + continue + path = pathlib.Path(root, name) + hits = set(self.acting_hits(path.read_text(errors="replace"))) + if hits: + found[path.relative_to(ROOT / "rust-modules").as_posix()] = sorted(hits) + self.assertEqual(set(found), set(self.TITLE_ACTING_FILES), found) + for file, globs in self.TITLE_ACTING_FILES.items(): + for glob in globs: + self.assertIn(glob, a11y.SUBJECT_BEARING, f"{file}: its presses are guarded by {glob}") + + def test_the_census_helper_reads_production_code_only(self): + text = ("fn a() { ContentReq::Play }\n// PlayerReq::Command\n#[cfg(test)]\nmod tests { fn t() { PlayerReq::Command } }\n" + "#[cfg(test)]\nmod more_tests;\nfn b() { Write::Watched }\n") + self.assertEqual(sorted(self.acting_hits(text)), ["ContentReq::Play", "Write::Watched"]) + + def test_the_census_reads_the_item_menu_actions_by_either_spelling(self): + spelled = "fn a() { Some(ItemMenuAction::PlayTrailer { rk }) }\nfn b() { Write::RemoveFromDeck }\n" + self.assertEqual(sorted(self.acting_hits(spelled)), ["ItemMenuAction::PlayTrailer", "Write::RemoveFromDeck"]) + aliased = ("fn a() {\n use crate::registry::ItemMenuAction as Action;\n Action::MarkWatched(rk);\n" + " Action::WatchlistRemove(guid);\n}\n") + self.assertEqual(sorted(self.acting_hits(aliased)), ["Action::MarkWatched", "WatchlistRemove"]) + # another enum called `Action` in a file that never imports the item menu's is none of the census's business + self.assertEqual(self.acting_hits("fn a() { Action::Play(i); episodes::Action::Play(i) }\n"), []) + + def test_the_detail_closure_is_applied_to_exactly_the_shapes_the_list_names(self): + """The one `.with_subject(` call in screens/src/detail/mod.rs sits inside a closure applied at each id shape + it names (the hero's controls, a season tab, an episode), so the CALL count above cannot see a fourth + application: this holds those, and a new one fails here until the list and the table say what it presses.""" + text = (ROOT / "rust-modules" / "screens" / "src" / "detail" / "mod.rs").read_text() + self.assertEqual(text.count("with_subject(a, "), 3, "hero, season, episode (still and text)") + + def test_the_detail_hero_ids_are_the_controls_whose_subject_the_screen_tests_assert(self): + """`hero_control_subject` names a ratingKey for each control that plays or writes and none for the rest, and + the screens test `the_hero_controls_that_play_or_write_have_a_subject_and_the_rest_have_none` holds that table. + This reads that table and `HeroCtl::a11y_name` back, so the `detail.hero.*` ids of SUBJECT_BEARING are + exactly the controls with a subject: a control added to one side and not the other fails here.""" + hero = (ROOT / "rust-modules" / "screens" / "src" / "detail" / "hero.rs").read_text() + names = dict(re.findall(r'HeroCtl::(\w+) => "(\w+)",', hero.split("pub const fn a11y_name", 1)[1].split("}", 1)[0])) + self.assertEqual(len(names), 10, names) + tests = (ROOT / "rust-modules" / "screens" / "src" / "detail" / "tests.rs").read_text() + table = tests.split("fn the_hero_controls_that_play_or_write_have_a_subject_and_the_rest_have_none", 1)[1].split("\n}\n", 1)[0] + acts = dict(re.findall(r"\(hero::HeroCtl::(\w+), (true|false)\)", table)) + self.assertEqual(set(acts), set(names), "the screens test places every control") + with_subject = {f"detail.hero.{names[ctl]}" for ctl, flag in acts.items() if flag == "true"} + listed = {shape for shape in a11y.SUBJECT_BEARING if shape.startswith("detail.hero.")} + self.assertEqual(with_subject, listed) + + +@unittest.skipUnless(HAS_FIFO, "needs os.mkfifo") +class Fifo(unittest.TestCase): + def setUp(self): + self.runtime = tempfile.mkdtemp(prefix="a11y-tool-") + self.addCleanup(shutil.rmtree, self.runtime, ignore_errors=True) + self.fifo = pathlib.Path(self.runtime, a11y.FIFO_NAME) + os.mkfifo(self.fifo) + self.reader = os.open(self.fifo, os.O_RDONLY | os.O_NONBLOCK) + self.addCleanup(os.close, self.reader) + + def written(self): + try: + return os.read(self.reader, 4096).decode().split() + except BlockingIOError: + return [] + + def test_focus_and_press_write_their_tokens(self): + a11y.focus(self.fifo, "nav.watchlist") + a11y.press(self.fifo, "detail.hero.play") + a11y.press(self.fifo, "home.shelf.0.card.1", "4711") + self.assertEqual(self.written(), ["focus:nav.watchlist", "press:detail.hero.play", "press:home.shelf.0.card.1@4711"]) + + def test_a_malformed_id_writes_nothing(self): + with self.assertRaises(ValueError): + a11y.focus(self.fifo, "Nav.Watchlist") + with self.assertRaises(ValueError): + a11y.press(self.fifo, "nav.x", "1 2") + self.assertEqual(self.written(), []) + + +@unittest.skipUnless(HAS_FIFO, "needs os.mkfifo") +class CommandLine(unittest.TestCase): + """`python3 tools/a11y.py `: a bad argument or a missing app is one line on stderr and an exit + code, never a traceback (found by running it against the simulator: `focus Bad.Id` printed one).""" + + def setUp(self): + self.runtime = tempfile.mkdtemp(prefix="a11y-tool-") + self.addCleanup(shutil.rmtree, self.runtime, ignore_errors=True) + self.fifo = pathlib.Path(self.runtime, a11y.FIFO_NAME) + os.mkfifo(self.fifo) + self.reader = os.open(self.fifo, os.O_RDONLY | os.O_NONBLOCK) + self.addCleanup(os.close, self.reader) + + def run_main(self, *argv): + import contextlib + import io + err = io.StringIO() + with contextlib.redirect_stderr(err): + code = a11y.main(list(argv)) + return code, err.getvalue() + + def written(self): + try: + return os.read(self.reader, 4096).decode().split() + except BlockingIOError: + return [] + + def test_a_malformed_id_or_subject_is_one_line_and_exit_2_and_sends_nothing(self): + for argv in (("focus", self.runtime, "Bad.Id"), ("press", self.runtime, "nav.x", "--subject", "a b"), + ("expect", self.runtime, "nav")): + code, err = self.run_main(*argv) + self.assertEqual(code, 2, argv) + self.assertTrue(err.startswith("a11y: ") and err.count("\n") == 1, f"{argv}: {err!r}") + self.assertEqual(self.written(), []) + + def test_a_subject_bearing_press_without_a_subject_is_refused_and_sends_nothing(self): + for id_ in ("home.shelf.2.card.5", "detail.episodes.still.3", "detail.episodes.text.3", "detail.season.1", + "filmography.row.0", "catalog.primary", "home.hero.play", "home.hero.info", "home.hero.watchlist", + "itemmenu.play", "itemmenu.watchlist_remove", "itemmenu.version.0", "versions.row.1", + "player.control.next", "player.control.next_episode", "player.control.5", "player.section.0", + "player.failure.try_again", "more.fold.from_beginning", "more.rung.p720"): + code, err = self.run_main("press", self.runtime, id_) + self.assertEqual(code, 2, id_) + self.assertTrue(err.startswith("a11y: ") and err.count("\n") == 1 and "--subject" in err, f"{id_}: {err!r}") + code, err = self.run_main("send", self.runtime, f"press:{id_}") # the raw writer is no way round it + self.assertEqual(code, 2, id_) + self.assertTrue("--subject" in err or "subject" in err, err) + self.assertEqual(self.written(), []) + + def test_send_is_one_word_so_no_press_rides_in_behind_another_token(self): + """`send "back press:"` would write ONE line the app cuts into two tokens, the second a title's press + with no subject named: it is refused (exit 2, one line, nothing written) for every separator the app uses.""" + for token in SMUGGLED + ["", " back", "back "]: + code, err = self.run_main("send", self.runtime, token) + self.assertEqual(code, 2, repr(token)) + self.assertTrue(err.startswith("a11y: ") and err.count("\n") == 1 and "ONE token" in err, f"{token!r}: {err!r}") + self.assertEqual(self.written(), []) + + def test_a_subject_bearing_press_that_names_its_title_is_sent(self): + self.assertEqual(self.run_main("press", self.runtime, "detail.episodes.still.3", "--subject", "77"), (0, "")) + self.assertEqual(self.run_main("press", self.runtime, "home.hero.play", "--subject", "200622"), (0, "")) + self.assertEqual(self.run_main("send", self.runtime, "press:itemmenu.watchlist_remove@2001"), (0, "")) + self.assertEqual(self.run_main("send", self.runtime, "press:detail.episodes.text.0@78"), (0, "")) + self.assertEqual(self.run_main("press", self.runtime, "detail.hero.mark_watched", "--subject", "200622"), (0, "")) + self.assertEqual(self.run_main("press", self.runtime, "detail.hero.go_to_show"), (0, "")) # only navigates + self.assertEqual(self.run_main("press", self.runtime, "home.hero.action"), (0, "")) # the retry names no title + self.assertEqual(self.run_main("press", self.runtime, "versions.row.1", "--subject", "1001"), (0, "")) + self.assertEqual(self.run_main("press", self.runtime, "player.control.next", "--subject", "200623"), (0, "")) + self.assertEqual(self.run_main("press", self.runtime, "player.control.subtitles"), (0, "")) # opens a panel + self.assertEqual(self.run_main("send", self.runtime, "ok"), (0, "")) + self.assertEqual(self.written(), ["press:detail.episodes.still.3@77", "press:home.hero.play@200622", + "press:itemmenu.watchlist_remove@2001", "press:detail.episodes.text.0@78", + "press:detail.hero.mark_watched@200622", "press:detail.hero.go_to_show", + "press:home.hero.action", "press:versions.row.1@1001", + "press:player.control.next@200623", "press:player.control.subtitles", "ok"]) + + def test_the_library_press_stays_unguarded_for_a_card_with_no_subject(self): + """The mock scenario presses `watchlist.grid.card.7`, a coming-soon card whose subject is null.""" + fifo = pathlib.Path(self.runtime, a11y.FIFO_NAME) + a11y.press(fifo, "watchlist.grid.card.7") + self.assertEqual(self.written(), ["press:watchlist.grid.card.7"]) + + def test_the_verbs_write_their_tokens_and_exit_0(self): + self.assertEqual(self.run_main("focus", self.runtime, "nav.watchlist"), (0, "")) + self.assertEqual(self.run_main("press", self.runtime, "watchlist.grid.card.2", "--subject", "77"), (0, "")) + self.assertEqual(self.run_main("send", self.runtime, "back"), (0, "")) + self.assertEqual(self.written(), ["focus:nav.watchlist", "press:watchlist.grid.card.2@77", "back"]) + + def test_no_fifo_or_no_answer_is_one_line_and_exit_1(self): + gone = pathlib.Path(self.runtime, "nowhere") + code, err = self.run_main("focus", str(gone), "nav.watchlist") + self.assertEqual(code, 1) + self.assertTrue(err.startswith("a11y: ") and err.count("\n") == 1, err) + with mock.patch.object(a11y, "expect_focus", side_effect=TimeoutError("no snapshot named state:x")): + code, err = self.run_main("expect", self.runtime, "nav.watchlist") + self.assertEqual((code, err), (1, "a11y: no snapshot named state:x\n")) + + def test_a_focus_mismatch_names_both_ids_and_exits_1(self): + err = a11y.FocusMismatch("nav.watchlist", "nav.home", {"route": "home", "owner": "page"}) + with mock.patch.object(a11y, "expect_focus", side_effect=err): + code, text = self.run_main("expect", self.runtime, "nav.watchlist") + self.assertEqual(code, 1) + self.assertIn("nav.watchlist", text) + self.assertIn("nav.home", text) + + +@unittest.skipUnless(HAS_FIFO, "needs os.mkfifo") +class ExpectFocus(unittest.TestCase): + """`expect_focus` asks `state` again until the focused id is the one wanted; the fake app answers each + request (by its nonce) with the next focus of a script.""" + + def setUp(self): + self.runtime = tempfile.mkdtemp(prefix="a11y-tool-") + self.addCleanup(shutil.rmtree, self.runtime, ignore_errors=True) + self.fifo = pathlib.Path(self.runtime, a11y.FIFO_NAME) + os.mkfifo(self.fifo) + self.reader = os.open(self.fifo, os.O_RDONLY | os.O_NONBLOCK) + self.addCleanup(os.close, self.reader) + self.clock = Clock() + + def app(self, focuses, route="watchlist", owner="page"): + """An idle hook that answers every state request with the next entry of `focuses` (the last repeats).""" + script = list(focuses) + asked = [] + + def sleep(seconds): + self.clock.sleep(seconds) + try: + data = os.read(self.reader, 4096).decode() + except BlockingIOError: + return + for token in data.split(): + if token.startswith("state:"): + focused = script.pop(0) if len(script) > 1 else script[0] + asked.append(focused) + answer_file(self.runtime, {"nonce": token[len("state:"):], "route": route, "owner": owner, + "focused": focused, "elements": []}) + return sleep, asked + + def test_it_returns_the_snapshot_when_the_focus_is_already_there(self): + sleep, asked = self.app(["nav.watchlist"]) + got = a11y.expect_focus(self.runtime, "nav.watchlist", clock=self.clock, sleep=sleep) + self.assertEqual(got["focused"], "nav.watchlist") + self.assertEqual(asked, ["nav.watchlist"], "one request") + + def test_it_asks_again_until_the_focus_lands(self): + sleep, asked = self.app([None, "home.hero.play", "nav.watchlist"]) + got = a11y.expect_focus(self.runtime, "nav.watchlist", timeout=10, clock=self.clock, sleep=sleep) + self.assertEqual(got["focused"], "nav.watchlist") + self.assertEqual(asked, [None, "home.hero.play", "nav.watchlist"], "a fresh state each time, until it matched") + + def test_a_focus_that_never_lands_is_a_mismatch_naming_both_ids_and_the_route(self): + sleep, _ = self.app(["home.shelf.0.card.0"], route="home", owner="page") + with self.assertRaises(a11y.FocusMismatch) as caught: + a11y.expect_focus(self.runtime, "nav.watchlist", timeout=1, clock=self.clock, sleep=sleep) + e = caught.exception + self.assertIsInstance(e, AssertionError) + self.assertEqual((e.want, e.got), ("nav.watchlist", "home.shelf.0.card.0")) + message = str(e) + for part in ["nav.watchlist", "home.shelf.0.card.0", "'home'", "'page'"]: + self.assertIn(part, message) + self.assertGreaterEqual(self.clock.now, 1.0, "it waited out its time") + + def test_an_app_that_never_answers_is_a_timeout_not_a_mismatch(self): + with self.assertRaises(TimeoutError) as caught: + a11y.expect_focus(self.runtime, "nav.watchlist", timeout=0.5, clock=self.clock, sleep=self.clock.sleep) + self.assertNotIsInstance(caught.exception, a11y.FocusMismatch) + + def test_nothing_focused_reads_as_a_mismatch_with_none(self): + sleep, _ = self.app([None]) + with self.assertRaises(a11y.FocusMismatch) as caught: + a11y.expect_focus(self.runtime, "nav.watchlist", timeout=0.3, clock=self.clock, sleep=sleep) + self.assertIsNone(caught.exception.got) + + def test_an_app_that_goes_quiet_after_answering_is_a_mismatch_with_what_it_said(self): + answers = {"n": 0} + + def sleep(seconds): + self.clock.sleep(seconds) + data = b"" + try: + data = os.read(self.reader, 4096) + except BlockingIOError: + pass + if answers["n"] == 0 and data: + answers["n"] += 1 + (token,) = data.decode().split() + answer_file(self.runtime, {"nonce": token[len("state:"):], "focused": "home.hero.play"}) + + with self.assertRaises(a11y.FocusMismatch) as caught: + a11y.expect_focus(self.runtime, "nav.watchlist", timeout=8, clock=self.clock, sleep=sleep) + self.assertEqual(caught.exception.got, "home.hero.play") + + def test_a_malformed_id_is_refused_before_anything_is_sent(self): + with self.assertRaises(ValueError): + a11y.expect_focus(self.runtime, "Nav.Watchlist", clock=self.clock, sleep=self.clock.sleep) + try: + data = os.read(self.reader, 4096) + except BlockingIOError: + data = b"" + self.assertEqual(data, b"", "no state request went out") + + +class CaptureDriver(unittest.TestCase): + """tools/watchlist_captures.py: how a `keys` entry is classified and when `expect_focus` is checked.""" + + def test_every_keys_entry_has_one_kind(self): + for token, kind in [ + ("hold", "hold"), ("up", "key"), ("ok", "key"), ("back", "key"), ("ok@0.12", "key"), + ("ck:854,91", "key"), ("mock:{\"pms\":\"fail\"}", "mock"), ("lib:{\"op\":\"add\"}", "lib"), + ("sleep:3", "sleep"), ("focus:nav.watchlist", "byid"), ("press:detail.hero.watchlist@1001", "byid"), + ("press:watchlist.grid.card.3@9001", "byid"), + ]: + self.assertEqual(captures.step_kind(token), kind, token) + + def test_the_at_of_a_press_subject_is_not_a_timing(self): + """`press:@` must never reach the `key@wait` branch, which would send the bare press and sleep s.""" + token = "press:watchlist.grid.card.3@9001" + self.assertNotEqual(captures.step_kind(token), "key") + self.assertEqual(captures.expect_position(["focus:nav.x", token]), 2, "not a timed key: checked after the walk") + + def test_the_focus_is_checked_after_the_walk_or_before_a_final_timed_key(self): + self.assertEqual(captures.expect_position([]), 0) + self.assertEqual(captures.expect_position(["focus:nav.watchlist"]), 1) + self.assertEqual(captures.expect_position(["focus:nav.watchlist", "hold"]), 2) + self.assertEqual(captures.expect_position(["focus:detail.hero.watchlist", "ok@0.12"]), 1, + "the shot must follow the timed key within its wait: check before it") + self.assertEqual(captures.expect_position(["ok@0.12", "focus:nav.watchlist"]), 2, "only the LAST entry decides") + + def test_a_malformed_by_id_step_fails_before_anything_boots(self): + captures.check_steps("a.png", ["focus:nav.watchlist", "press:home.shelf.0.card.1@12", "hold", "back"]) + for token in ["focus:Nav.Watchlist", "press:nav", "focus:nav.x@12", "press:nav.x@a b", "focus:"]: + with self.assertRaises(captures.Failure, msg=token): + captures.check_steps("a.png", [token]) + + def test_no_expect_focus_checks_nothing(self): + with mock.patch.object(a11y, "expect_focus", side_effect=AssertionError("must not ask")): + captures.check_focus(pathlib.Path("/nonexistent"), {"file": "a.png"}) + + def test_a_mismatch_fails_the_capture_with_both_ids_and_the_apps_refusals(self): + runtime = pathlib.Path(tempfile.mkdtemp(prefix="a11y-tool-")) + self.addCleanup(shutil.rmtree, runtime, ignore_errors=True) + (runtime / "plxnative-events.log").write_text( + "boot\na11y: refused focus watchlist.grid.card.99 unknown owner=watchlist\n") + err = a11y.FocusMismatch("watchlist.grid.card.99", "watchlist.grid.card.0", {"route": "watchlist", "owner": "page"}) + with mock.patch.object(a11y, "expect_focus", side_effect=err): + with self.assertRaises(captures.Failure) as caught: + captures.check_focus(runtime, {"file": "a.png", "expect_focus": "watchlist.grid.card.99"}) + message = str(caught.exception) + for part in ["a.png", "watchlist.grid.card.99", "watchlist.grid.card.0", "a11y: refused focus watchlist.grid.card.99 unknown"]: + self.assertIn(part, message) + + def test_an_app_that_never_answers_fails_the_capture_naming_the_cause(self): + with mock.patch.object(a11y, "expect_focus", side_effect=TimeoutError("no snapshot named state:x")): + with self.assertRaises(captures.Failure) as caught: + captures.check_focus(pathlib.Path("/nonexistent"), {"file": "a.png", "expect_focus": "nav.x"}) + self.assertIn("RELEASE=1", str(caught.exception)) + + def test_a_capture_that_fails_before_its_shot_reports_the_failure_and_keeps_its_logs(self): + """A `w6/x.png` capture that fails before its shot (here: the app never opens the FIFO) leaves its + logs where the shot would have gone. The directory does not exist yet (the shot makes it), so the + driver makes it in its `finally`: without it the copy raised FileNotFoundError, which hid the + Failure and ended the whole run instead of printing `FAIL` and going on to the next capture.""" + out = pathlib.Path(tempfile.mkdtemp(prefix="a11y-tool-")) + self.addCleanup(shutil.rmtree, out, ignore_errors=True) + spec = {"file": "w6/x.png", "mock": "default", "triggers": {}, "keys": []} + with mock.patch.object(captures, "sign_in"), mock.patch.object(captures, "post"), \ + mock.patch.object(captures, "require_stand_in"), \ + mock.patch.object(captures.subprocess, "Popen", return_value=mock.Mock()), \ + mock.patch.object(captures.time, "sleep"): + with self.assertRaises(captures.Failure) as caught: + captures.capture(pathlib.Path("plxnative-sim"), spec, {"boot_wait_s": 0, "key_wait_s": 0}, out) + self.assertIn("plxnative-remote", str(caught.exception)) + self.assertTrue((out / "w6" / "x.out").is_file(), "the console log is kept beside the missing shot") + + def test_the_wait_is_passed_to_the_read_back(self): + with mock.patch.object(a11y, "expect_focus", return_value={}) as asked: + captures.check_focus(pathlib.Path("/nonexistent"), {"file": "a.png", "expect_focus": "nav.watchlist"}) + asked.assert_called_once_with(pathlib.Path("/nonexistent"), "nav.watchlist", timeout=captures.FOCUS_WAIT_S) + + +class CommittedScenario(unittest.TestCase): + """The committed tests/scenarios/watchlist_captures.json, held to the grammar without a simulator.""" + + # Captures with no `expect_focus`: a boot trigger decides what is focused (an account or item menu opens on + # a row that depends on the session and the card), or a pointer click does (`ck:`, the one capture that + # navigates by pointer: `w6/detail-offline.png`). + NO_EXPECT = {"account-menu-new.png", "item-menu-new.png", "w6/detail-offline.png"} + POINTER_WALKS = {"w6/detail-offline.png"} + DIRECTIONS = {"up", "down", "left", "right"} + + @classmethod + def setUpClass(cls): + cls.doc = json.loads((ROOT / "tests" / "scenarios" / "watchlist_captures.json").read_text()) + cls.captures = {c["file"]: c for c in cls.doc["captures"]} + + def test_every_by_id_token_and_every_expect_focus_is_in_the_grammar(self): + by_id = 0 + for file, spec in self.captures.items(): + captures.check_steps(file, spec["keys"]) + by_id += sum(captures.step_kind(k) == "byid" for k in spec["keys"]) + if "expect_focus" in spec: + self.assertTrue(a11y.valid_id(spec["expect_focus"]), f"{file}: {spec['expect_focus']!r}") + self.assertGreater(by_id, 10, "the migration is in the file") + + def test_no_capture_walks_with_direction_keys_to_reach_its_target(self): + for file, spec in self.captures.items(): + walked = [k for k in spec["keys"] if k.partition("@")[0] in self.DIRECTIONS] + self.assertEqual(walked, [], f"{file} walks with {walked}: name the target by id (focus:/press:)") + + def test_the_only_capture_that_navigates_by_pointer_is_the_named_one(self): + clicking = {file for file, spec in self.captures.items() if any(k.startswith("ck:") for k in spec["keys"])} + self.assertEqual(clicking, self.POINTER_WALKS) + + def test_the_texts_that_say_no_direction_key_stands_between_boot_and_target_say_the_exception(self): + """tools/watchlist_captures.py's docstring, the scenario's comment and tests/README.md all state it.""" + for name, text in (("the scenario comment", self.doc["comment"]), + ("tools/watchlist_captures.py", (ROOT / "tools" / "watchlist_captures.py").read_text())): + self.assertIn("w6/detail-offline.png", text, name) + self.assertIn("ck:", text, name) + self.assertNotIn("whose target no id is read for", text, name) + readme = (ROOT / "tests" / "README.md").read_text() + self.assertIn("w6/detail-offline.png", readme) + + def test_a_subject_bearing_press_in_the_scenario_is_the_named_coming_soon_card(self): + """The driver writes a token raw (the library path, unguarded), so a title's press with no `@` + is a decision: the one here is `watchlist.grid.card.7`, a coming-soon card whose subject is null. Every + other title's press names it (`@`), so a hero that moved or a menu opened on another card is + refused by the app and fails the capture.""" + presses = [k for spec in self.captures.values() for k in spec["keys"] + if k.startswith("press:") and a11y.subject_bearing(k[len("press:"):].partition("@")[0])] + self.assertEqual({k for k in presses if "@" not in k}, {"press:watchlist.grid.card.7"}) + self.assertEqual({k for k in presses if "@" in k}, + {"press:itemmenu.watchlist_remove@2001", "press:home.hero.watchlist@200622", + "press:detail.hero.watchlist@1001"}) + + def test_a_capture_without_expect_focus_is_a_named_exception(self): + missing = {file for file, spec in self.captures.items() if "expect_focus" not in spec} + self.assertEqual(missing, self.NO_EXPECT) + + def test_the_first_capture_is_the_nav_watchlist_tab_by_id(self): + spec = self.captures["home-bookmark-tab-focused.png"] + self.assertEqual(spec["keys"], ["focus:nav.watchlist"]) + self.assertEqual(spec["expect_focus"], "nav.watchlist") + + def test_the_keys_that_stay_are_the_ones_whose_subject_is_the_key(self): + """A hold, a timing and back stay keys; the mid-flip captures focus by id and then send the timed OK.""" + for file in ["w6/detail-added-midflip.png", "home-hero/added-midflip.png"]: + keys = self.captures[file]["keys"] + self.assertEqual(len(keys), 2, file) + self.assertEqual((captures.step_kind(keys[0]), keys[1]), ("byid", "ok@0.12"), file) + self.assertEqual(captures.expect_position(keys), 1, file) + for file in ["hold-menu.png", "w6/hold-menu.png", "after-removal.png", "w6/watchlist-hold.png", + "w6/watchlist-hold-unplayable.png"]: + self.assertIn("hold", self.captures[file]["keys"], file) + self.assertEqual(self.captures["filtered.png"]["keys"][-1], "back") + + def test_the_comment_describes_the_forms_the_driver_takes(self): + comment = self.doc["comment"] + for part in ["focus:", "press:", "expect_focus", "`hold`", "ok@0.12", "`back`", "state:"]: + self.assertIn(part, comment) + self.assertNotIn("sends each key as a FIFO token", comment, "the old recipe sentence is gone") + + def test_a_hold_that_opens_a_menu_expects_the_menus_namespace(self): + for file in ["hold-menu.png", "w6/hold-menu.png", "w6/watchlist-hold.png", "w6/watchlist-hold-unplayable.png"]: + self.assertTrue(self.captures[file]["expect_focus"].startswith("itemmenu."), file) + self.assertTrue(self.captures["sort-filter-open.png"]["expect_focus"].startswith("watchlist_menu.")) + + if __name__ == "__main__": unittest.main() diff --git a/tools/a11y.py b/tools/a11y.py index 906e732bae..5a2e1c6a32 100644 --- a/tools/a11y.py +++ b/tools/a11y.py @@ -1,31 +1,65 @@ #!/usr/bin/env python3 -"""Read what is on screen BY ID: the harness side of the app's `state:` token. +"""Drive and read the app BY ID: the harness side of the `focus:` / `press:` / `state:` FIFO tokens. -The app (a `devtriggers` build, so not a `RELEASE=1` one) answers `state:` by replacing -`plxnative-a11y.json` in its runtime directory with a snapshot of the page that owns input: its -route word, who owns input, the focused full id, every focus group and every element with its id, -role, rest rectangle, visibility, focus, loaded flag, label and subject (the a11y-ids plan, D7/D8). -The file is replaced atomically, so a reader never sees half of one; but it may still be the PREVIOUS -request's answer, which is why every request carries a fresh nonce and a reader waits until the file -names it. +The app (a `devtriggers` build, so not a `RELEASE=1` one) takes three accessibility-id tokens (the +a11y-ids plan, D1-D8): - from a11y import state, send, wait_for + focus: move focus to the element the id names + press: focus it, then press OK (an ordinary OK Down and Up) + press:@ ... but only if the element's subject (the ratingKey of the title the press + acts on) is ; a mismatch refuses and presses nothing + state: replace `plxnative-a11y.json` in the runtime directory with a snapshot of the + page that owns input: its route word, who owns input, the focused full id, + every focus group and every element with its id, role, rest rectangle, + visibility, focus, loaded flag, label and subject + +An id is `.` (`nav.watchlist`, `home.hero.play`, `home.shelf.2.card.5`, `watchlist.grid.card.3`): +a namespace `[a-z][a-z0-9_-]*`, then segments that are each a name `[a-z][a-z0-9_]*` or a canonical decimal +index. A refused id leaves one event-log line, `a11y: refused owner=`; nothing moves. + +The state file is replaced atomically, so a reader never sees half of one; but it may still be the PREVIOUS +request's answer, which is why every request carries a fresh nonce and a reader waits until the file names it. + + from a11y import focus, press, expect_focus, state, send, wait_for + focus(fifo, "nav.watchlist") # no key walk: the id names the target + expect_focus(runtime, "nav.watchlist") # `state`, then compare the focused id (FocusMismatch) + press(fifo, "nav.watchlist") # an element with no subject: nothing to name snap = state(runtime) # send `state:`, wait for it ids = [e["id"] for e in snap["elements"]] wait_for(lambda: any(e["id"] == "nav.watchlist" for e in state(runtime)["elements"]), timeout=10) +Prefer these to key walks for REACHING a target. A walk stays right for a test whose subject is travel (an +fps walk, a focus fingerprint) and for keys whose subject is the key itself (a hold, a timing, back). + A snapshot holds titles and rating keys. It is for the harness that asked: do not paste it into an issue, a log or a recording. Command line (a manual smoke: boot the simulator on the mock, then): - python3 tools/a11y.py state [--timeout SECONDS] - python3 tools/a11y.py send + python3 tools/a11y.py state [--timeout SECONDS] + python3 tools/a11y.py send + python3 tools/a11y.py focus + python3 tools/a11y.py press [--subject RATINGKEY] (a title's id REQUIRES --subject) + python3 tools/a11y.py expect [--timeout SECONDS] `` is the app's runtime directory (`PLXNATIVE_RUNTIME_DIR` under the simulator); the -token goes into its `plxnative-remote` FIFO. +token goes into its `plxnative-remote` FIFO. Exit 0 is done; 1 is a focus that is not the expected one, +an app that never answered or a FIFO that is not there; 2 is an id, subject or token the grammar refuses +(nothing was sent). Each failure is one line on stderr, never a traceback. + +A title is pressed by NAME. A `press` (or a `send press:`) of an element that ACTS ON a title it names +(the ids are `SUBJECT_BEARING` below: the rule is stated there) needs `--subject `, the ratingKey of +the title the press acts on, and exits 2 without it, because the simulator boots against the owner's real server +unless it is aimed at a mock, and OK on a title can play it. Only the COMMAND LINE refuses: the library +functions `press` / `press_token` stay unguarded for a script that drives the mock, so a script that imports +them against a real server has no check. `send` writes ONE word: a token with whitespace in it +(`"back press:card"`) is refused, because the app would cut it into two tokens and the second would never meet +the press guard. + +On the television use `tools/tv-session.sh focus|press|state`. """ import argparse +import fnmatch import json import os import pathlib @@ -42,6 +76,174 @@ POLL_S = 0.05 +# The id grammar the app enforces (`plx_ui::a11y::A11yPath::parse_id`): `.`, the namespace +# `[a-z][a-z0-9_-]*`, at least one segment after it, each a name `[a-z][a-z0-9_]*` or a canonical +# decimal index (`0`, or digits with no leading zero: one element has one spelling). +ID_RE = re.compile(r"[a-z][a-z0-9_-]*(\.([a-z][a-z0-9_]*|0|[1-9][0-9]*))+") +# A press subject: printable ASCII with no space and no `@` (`by_id_subject_ok`). +SUBJECT_RE = re.compile(r"[\x21-\x3f\x41-\x7e]+") +REFUSED_PREFIX = "a11y: refused " + + +def valid_id(text): + """Is `text` a full accessibility id in the app's grammar?""" + return isinstance(text, str) and ID_RE.fullmatch(text) is not None + + +def valid_subject(text): + """May `text` ride after the `@` of `press:@`?""" + return isinstance(text, str) and SUBJECT_RE.fullmatch(text) is not None + + +# The id shapes whose element carries a SUBJECT, the ratingKey of the title the press acts on (a catalog page's +# hex id). THE RULE: an element is on this list when its press ACTS ON a title it names: it plays, restarts, +# finishes or retries it, marks it watched or unwatched, bookmarks it, opens or removes it from a menu that acts +# on it, or opens that title's own page or menu where the title can change under the press (a card, a credit and +# the Home carousel's Info only open a page, and are on it). Navigation is not the test: only a control whose +# target the page fixes (Go to Show, Also available, the Play Version opener, More, a panel opener, a seek) is +# not, and stays pressable bare. The real-account rule is never to press OK on a title whose ratingKey you have +# not read, so the COMMAND LINE and `tools/tv-session.sh press` make the press name it (`--subject` / `--rk`) and +# the app refuses a mismatch. This tuple is THE list (the other spellings of it, +# `a11y_subject_bearing` in tools/tv-session.sh, the docs and the refusal message, describe it by that rule): it +# is read off the code, not guessed. Each production `A11y::with_subject` call SITE is an entry +# (`git grep -n with_subject rust-modules`), a test here holds the number of calls per file equal to the table +# below, and a census test reads every file that constructs a title-acting message (Play, PlayVersion, Resume, a +# queue step, a watched or watchlist write) and holds the set of those files equal to the table's. +# +# *.card.* ui/src/cards/mod.rs `card_a11y`:
.card., every poster, still and headshot +# detail.episodes.* screens/src/detail/mod.rs: `episodes.still.` (OK plays) and `episodes.text.` +# detail.season.* the same file: `season.`, a season tab +# filmography.row.* screens/src/filmography.rs: `row.`, a credit (its subject is the local copy's key) +# catalog.primary screens/src/catalog.rs: the Add to / On Watchlist pill (its subject is the hex id) +# home.hero.play screens/src/home/mod.rs: `hero.play|info|watchlist`, the hero item's ratingKey (three +# home.hero.info explicit ids, not a glob: `home.hero.action`, the failure read-out's retry, is not a title's +# home.hero.watchlist control and stays pressable) +# detail.hero.play screens/src/detail/mod.rs `hero_control_subject`: the Detail hero's six controls that +# detail.hero.restart PLAY or WRITE, each named by the ratingKey it acts on and not by the route's: Play and +# detail.hero.trailer Restart the episode (a show) or the picked version's movie, Mark watched / unwatched +# detail.hero.mark_watched the ON-DECK episode of a started show (`hero::hero_episode`, so a chain `press +# detail.hero.mark_unwatched detail.episodes.text.0 --rk E`, `press detail.hero.go_to_show`, `press +# detail.hero.watchlist detail.hero.mark_watched` cannot mark an episode nobody named), Watchlist and Trailer +# the page's own title. Explicit ids, not a glob: `go_to_show`, `alt`, `version` and +# `more` only navigate or open a menu and stay pressable bare +# versions.row.* screens/src/versions_panel.rs: the Play Version panel's `row.` (OK plays the hero's title +# in that version): the Play pill's own key (`registry::versions_subject`) +# itemmenu.* screens/src/item_menu.rs: `` and `version.`, the menu's item's ratingKey +# player.control.previous screens/src/player/mod.rs `control_subject`, the player's control row: Previous and +# player.control.next Next the queue neighbour they would start, Up Next's `next_episode` the episode +# player.control.next_episode `up_next` holds, From beginning and the Skip pill (a final credits segment finishes +# player.control.from_beginning the item) the item playing. Explicit words, not a glob: `play_pause`, the seeks, +# player.control.skip `subtitles`, `audio`, `more`, `watch` and `watch_credits` start no title and stay +# pressable bare (tests/player_shots.sh opens its panels with them) +# player.control.[0-9]* the row's items an id spells by POSITION (a package placing two controls with one word): +# the position hides the word, so the whole spelling is guarded and each carries its +# command's key, else the item playing +# player.section.* the same file: the open Info card's buttons (From beginning, Go to details), positional too +# player.failure.try_again the failure read-out's two actions that resolve the failed play again: the key +# player.failure.play_automatically of the REQUEST they repeat (`route::retry_rk`; the item playing, `cur_rk`, is +# only installed when a plan lands, so a play that failed earlier differs). +# `change_quality`, `repair` and `back` start no title +# more.fold.previous screens/src/player/overlay.rs: the More menu's folded rows that start a title (the +# more.fold.next package placed the command in no reachable state), `HudCommand::plays_rk`; the other +# more.fold.from_beginning folds start none +# more.rung.* the same file: the Quality page's rungs. A pick re-resolves the title: after a failed play it +# is the failure read-out's Retry at that rung (the request's key, as above), on a live one +# it asks the route again for the item playing (`quality_pick_subject`) +# menu.audio.* the same file, the Tracks menu: a track pick selects the part's streams on the PMS (`PUT +# menu.sub.* /library/parts/{id}`) and a subtitle-search result installs its subtitle on the item (`PUT +# menu.off /library/metadata/{rk}/subtitles`), each naming the item playing +# menu.forced (`TrackRow::writes_title`, an exhaustive match: a new row cannot compile without the decision) +# menu.hit.* +# +# fnmatch globs, which are spelled exactly like the `case` patterns of `a11y_subject_bearing` in +# tools/tv-session.sh (tests/test_a11y_tool.py reads both and holds them equal). Not subject-bearing, so never +# in the list: `detail.hero.go_to_show|alt|version|more` (they navigate or open a menu), `detail.about.card`, +# `under-posters.row.3` and every other `*.row.*` outside Filmography and the Play Version panel. NOT GUARDED, on +# purpose: the rest of the Tracks menu (`menu.boost|loudness` reconfigure the live stream, `menu.timing|style| +# field.*|.|search_language|language.*|lang.*|other|search|retry` open a page or pick a local setting), +# the player's panel openers and seeks, `player.chapter.` and the scrubber (they only seek) and `more.quality| +# speed|stats|rate.*` (a drill-in, a local switch, a speed). The discriminator for the reconfigures (`more.rate.*`, +# `menu.boost|loudness`): on a URI attempt they re-resolve the playing request too (`route::request_viewer_reconfigure`), +# but that needs a proven playhead and pause state, so it refuses without a live attempt: they can never START a +# title from a failed or idle session, and only a quality rung can (it retries the failed request). +# +# The rows of a Catalog item menu have NO ratingKey to name (a Watchlist title no server holds: its identity is a +# guid), so the guarded doors cannot press them at all (the library `press`, unguarded, still can): the safe side, +# because they act on a catalog title. `home.hero.action` is not in the list: it has no title (the failure +# read-out's retry, shown while there is no hero) and a bare press of it goes out. +SUBJECT_BEARING = ("*.card.*", "detail.episodes.*", "detail.season.*", "filmography.row.*", "catalog.primary", + "home.hero.play", "home.hero.info", "home.hero.watchlist", + "detail.hero.play", "detail.hero.restart", "detail.hero.trailer", "detail.hero.mark_watched", + "detail.hero.mark_unwatched", "detail.hero.watchlist", "itemmenu.*", "versions.row.*", + "player.control.previous", "player.control.next", "player.control.next_episode", + "player.control.from_beginning", "player.control.skip", "player.control.[0-9]*", + "player.section.*", "player.failure.try_again", "player.failure.play_automatically", + "more.fold.previous", "more.fold.next", "more.fold.from_beginning", "more.rung.*", + "menu.audio.*", "menu.sub.*", "menu.off", "menu.forced", "menu.hit.*") + + +def subject_bearing(id_): + """Does the element `id_` names carry a title's subject (see SUBJECT_BEARING)?""" + return any(fnmatch.fnmatchcase(id_, shape) for shape in SUBJECT_BEARING) + + +def focus_token(id_): + """`focus:`. Raises ValueError for an id the app would refuse as malformed.""" + if not valid_id(id_): + raise ValueError(f"not an accessibility id (...., e.g. nav.watchlist): {id_!r}") + return f"focus:{id_}" + + +def press_token(id_, subject=None): + """`press:`, or `press:@` when the press must name the title it acts on (`SUBJECT_BEARING`).""" + if not valid_id(id_): + raise ValueError(f"not an accessibility id (...., e.g. nav.watchlist): {id_!r}") + if subject is None: + return f"press:{id_}" + if not valid_subject(subject): + raise ValueError(f"a press subject is printable ASCII with no space and no '@': {subject!r}") + return f"press:{id_}@{subject}" + + +def guarded_press_token(id_, subject=None): + """`press_token`, for a caller that is a person's or an agent's command: a subject-bearing id (see + SUBJECT_BEARING) must name the title it means, or this raises ValueError and nothing is sent. + `press_token` itself stays unguarded, because a library caller may mean an element whose subject is + null (the mock scenario's coming-soon card `watchlist.grid.card.7`).""" + if subject is None and valid_id(id_) and subject_bearing(id_): + raise ValueError(f"press {id_}: this element is a title's, so the press must name the title with " + f"--subject (read it from `state` first); nothing was sent") + return press_token(id_, subject) + + +def parse_token(token): + """The inverse of the two builders: `(act, id, subject)` for a `focus:` or `press:` token (`subject` is + None without one). Raises ValueError for anything else, a malformed id, or a `focus:` with a subject.""" + for act, build in (("focus", focus_token), ("press", press_token)): + if token.startswith(act + ":"): + id_, at, subject = token[len(act) + 1:].partition("@") + if at and act == "focus": + raise ValueError(f"a focus token takes no subject: {token!r}") + subject = subject if at else None + if act == "focus": + build(id_) + else: + build(id_, subject) + return act, id_, subject + raise ValueError(f"not a focus: or press: token: {token!r}") + + +def refusals(log_text): + """The `a11y: refused owner=` lines of an event log, in order. They carry + words and ids only (never a label or a subject), so they are safe to print.""" + out = [] + for line in log_text.splitlines(): + at = line.find(REFUSED_PREFIX) + if at >= 0: + out.append(line[at:].strip()) + return out + + def new_nonce(): """A fresh nonce in the app's grammar (16 hex digits).""" return secrets.token_hex(8) @@ -51,9 +253,12 @@ def send(fifo, token): """Write ONE token to the remote FIFO, newline-terminated, in a single write. The FIFO is whitespace-delimited and a trailing partial token waits for its terminator, so a token - must not contain whitespace and must end with one. A single `write` of fewer than PIPE_BUF bytes is - atomic, so two writers cannot interleave inside a token. The FIFO is opened read-write: a - write-only open blocks when the app is gone, and this one never does. + must not contain whitespace and must end with one. A word with whitespace in it is TWO tokens to the app + (`rust-modules/src/remote.rs` cuts at ASCII whitespace and then at any Unicode whitespace), and the + second would never meet a guard written for the first, so it is refused here: `str.isspace` is the + superset of both. A single `write` of fewer than PIPE_BUF bytes is atomic, so two writers cannot + interleave inside a token. The FIFO is opened read-write: a write-only open blocks when the app is gone, + and this one never does. """ if not token or any(c.isspace() for c in token): raise ValueError(f"a FIFO token is one non-empty word with no whitespace: {token!r}") @@ -122,6 +327,56 @@ def answer(): raise TimeoutError(f"no snapshot named state:{nonce} appeared in {runtime} within {timeout} s") from None +def focus(fifo, id_): + """Move focus to the element `id_` names: `focus:` into the FIFO. Nothing is waited for; a refused + id logs `a11y: refused focus ...` and moves nothing (`expect_focus` is how a caller knows it landed).""" + send(fifo, focus_token(id_)) + + +def press(fifo, id_, subject=None): + """Focus `id_` and press OK on it, once. With `subject` (the ratingKey of the title the press acts on; + `SUBJECT_BEARING` lists the ids that need one) the app presses only if the element's subject is that; a + mismatch presses nothing and logs `a11y: refused press ... subject_mismatch`. UNGUARDED: nothing here + refuses an unnamed press of a title-acting id, only the command line does (`guarded_press_token`).""" + send(fifo, press_token(id_, subject)) + + +class FocusMismatch(AssertionError): + """The app's focused id is not the one a caller expected. `want` and `got` are ids (`got` None when + nothing is focused) and `snapshot` is the last answer, whose `route` and `owner` words the message carries.""" + + def __init__(self, want, got, snapshot): + self.want, self.got, self.snapshot = want, got, snapshot + route, owner = snapshot.get("route"), snapshot.get("owner") + super().__init__(f"expected focus on {want}, the app has {got!r} (route {route!r}, input owned by {owner!r})") + + +def expect_focus(runtime, want, timeout=DEFAULT_TIMEOUT_S, fifo=None, interval=POLL_S, retry_s=0.25, + clock=time.monotonic, sleep=time.sleep): + """Return the snapshot once the app's focused id is `want`, asking again (a fresh `state` each time) + until `timeout` seconds pass: focus lands a frame after its token, and a page's first tile takes it only + when its rows land. Raises FocusMismatch (naming both ids) when time is up with the app answering + something else, and TimeoutError when the app never answered at all (not running, a RELEASE=1 build).""" + if not valid_id(want): + raise ValueError(f"not an accessibility id (...., e.g. nav.watchlist): {want!r}") + deadline = clock() + timeout + last = None + while True: + remaining = max(deadline - clock(), 0.0) + try: + last = state(runtime, timeout=max(min(DEFAULT_TIMEOUT_S, remaining), interval), fifo=fifo, + interval=interval, clock=clock, sleep=sleep) + except TimeoutError: + if last is None: + raise + raise FocusMismatch(want, last.get("focused"), last) from None + if last.get("focused") == want: + return last + if clock() >= deadline: + raise FocusMismatch(want, last.get("focused"), last) + sleep(min(retry_s, max(deadline - clock(), 0.0))) + + def main(argv=None): parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) sub = parser.add_subparsers(dest="command", required=True) @@ -131,12 +386,48 @@ def main(argv=None): p_send = sub.add_parser("send", help="write one token to the FIFO") p_send.add_argument("runtime") p_send.add_argument("token") + p_focus = sub.add_parser("focus", help="focus the element an id names") + p_focus.add_argument("runtime") + p_focus.add_argument("id") + p_press = sub.add_parser("press", help="focus an element and press OK on it") + p_press.add_argument("runtime") + p_press.add_argument("id") + p_press.add_argument("--subject", help="press only if the element's subject (a ratingKey) is this") + p_expect = sub.add_parser("expect", help="wait until the focused id is the one given (exit 1 if not)") + p_expect.add_argument("runtime") + p_expect.add_argument("id") + p_expect.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT_S) args = parser.parse_args(argv) - if args.command == "state": - json.dump(state(args.runtime, args.timeout), sys.stdout, indent=1) - print() - else: - send(pathlib.Path(args.runtime, FIFO_NAME), args.token) + fifo = pathlib.Path(args.runtime, FIFO_NAME) + try: + if args.command == "state": + json.dump(state(args.runtime, args.timeout), sys.stdout, indent=1) + print() + elif args.command == "focus": + focus(fifo, args.id) + elif args.command == "press": + send(fifo, guarded_press_token(args.id, args.subject)) + elif args.command == "expect": + expect_focus(args.runtime, args.id, args.timeout) + else: + # ONE word: the app cuts a line at whitespace, so `back press:` is two tokens and the + # second would skip the press guard below. Checked here, before the guard, so the refusal says why. + if not args.token or any(c.isspace() for c in args.token): + raise ValueError(f"send writes ONE token, with no whitespace in it (the app would read {args.token!r} " + f"as several, past the press guard); nothing was sent") + act, id_, subject = parse_token(args.token) if args.token.startswith("press:") else (None, None, None) + if act: # the raw writer is no way round the guard: a `press:` token is held to it too + guarded_press_token(id_, subject) + send(fifo, args.token) + except FocusMismatch as e: + print(e, file=sys.stderr) + return 1 + except ValueError as e: # a malformed id, subject or token: nothing was sent + print(f"a11y: {e}", file=sys.stderr) + return 2 + except (TimeoutError, OSError) as e: # the app never answered, or there is no FIFO to write to + print(f"a11y: {e}", file=sys.stderr) + return 1 return 0 diff --git a/tools/tv-session.sh b/tools/tv-session.sh index 5454b750fd..b8547934af 100755 --- a/tools/tv-session.sh +++ b/tools/tv-session.sh @@ -4,8 +4,15 @@ # # tv-session.sh up [opts] wake -> deploy-if-stale -> clear triggers -> arm -> launch -> verify # tv-session.sh status re-assert an existing session without disturbing it -# tv-session.sh key … send key tokens (down, ok, back, play, pause, stop, …) +# tv-session.sh key … send key tokens (down, ok, back, play, pause, stop, …); never `focus:`, +# `press:` or `state:` (the three verbs below are their one door) # tv-session.sh click click at authored 1920x1080 coords +# tv-session.sh focus move focus to the element an accessibility id names (`nav.watchlist`) +# tv-session.sh press [--rk ] +# focus that element and press OK; an element that acts on a title it names +# (the list is `SUBJECT_BEARING` in tools/a11y.py) needs --rk: see "BY ID" below +# tv-session.sh state [--out FILE] +# what is on screen, by id: the focused id, the groups, every element # tv-session.sh shot [out.png] grab the panel (video plane included) via the capture service # tv-session.sh log [pattern] fetch the on-device event log, optionally grepped # tv-session.sh screen off|on blank the PANEL while the app keeps running (see below) @@ -118,7 +125,26 @@ # its own reasons is the only one that knows when unmuting is correct; restoring automatically # would fight a human who muted the set on purpose before handing it to a lane. # -# THE TV LOCK: every subcommand that DRIVES the set (up, key, click, shot, down) requires the +# BY ID, NOT BY WALK: `focus`, `press` and `state` are the FIFO's accessibility-id tokens (`focus:`, +# `press:[@]`, `state:`; debug builds only, `devtriggers`). Ids are place-based dot paths +# (`nav.watchlist`, `home.hero.play`, `detail.hero.play`, `watchlist.grid.card.3`); `state` lists the real ones. +# Prefer them to `key` walks, which are for tests whose subject is travel. Never press OK on a title whose +# ratingKey you have not read: `press` refuses, without `--rk`, any id whose element ACTS ON a title it names (it +# plays, restarts, finishes or retries it, marks it watched or unwatched, bookmarks it, acts on the title a menu was +# opened for, or opens that title's own page or menu where the title can change under the press: a card, a credit, +# the Home carousel's Info). Navigation is not the test: only a control whose target the page fixes (Go to Show, Also +# available, the Play Version opener, More, a panel opener, a seek) is pressed bare. The list of those ids is +# `SUBJECT_BEARING` in tools/a11y.py, read off the code (`a11y_subject_bearing` below is the same list), and the +# `--rk` is the ratingKey of the title the press acts on, which `state` prints as the element's subject (on a started +# show's Mark watched it is the on-deck episode, on a player's Next the queue neighbour, not the page's or the playing +# item's). The app +# refuses the press when the element now there carries another subject (`a11y: refused press subject_mismatch +# ...` in the event log). `key` refuses a +# `focus:`, `press:` or `state:` word, so there is ONE door per action, and a word with whitespace in it is +# refused (the app would cut it into two tokens, the second past every check here). +# A `state` snapshot holds titles and rating keys: it is for you, not for an issue or a recording. +# +# THE TV LOCK: every subcommand that DRIVES the set (up, key, click, focus, press, state, shot, down) requires the # television's lock and refuses when another lane holds it; `status`, `log` and `fg` are read-only # and only name the holder. Take one for a whole session rather than letting each command take its own # 10-minute implicit lease — the gap between two of your own commands is exactly where another @@ -1002,6 +1028,153 @@ cmd_up() { echo "== session up" } +# `fifo_write` / `fifo_send`: any ONE-WORD token reaches the remote shell as ONE quoted word; a token with +# whitespace in it (any the app cuts a line at: see `fifo_token_ok`) is refused, and nothing is sent for a +# refusal. Round trip through `sh -c`, the way the set's shell reads it. Then the doors in front of it: `key` +# refuses the three by-id tokens and judges every word before sending any, while `click`, `focus` and `press` +# still send through `send_tokens` (no television: `tv` and `require_lock` are stubbed in a subshell). +selftest_fifo() { + local REMOTE_FIFO probe word stmt got sent_to_tv=0 sent_arg="" _real_tv marker + probe=$(mktemp "${TMPDIR:-/tmp}/plx-fifo-selftest.XXXXXX") || { bad "no scratch file for the FIFO quoting check"; return 1; } + REMOTE_FIFO=$probe + # one-word tokens, injection attempts spelled without a space (a space is refused below), and non-ASCII text + # that is NOT whitespace: Cyrillic, an accented letter, a curly apostrophe, an em dash and an ellipsis + # (U+2019, U+2014, U+2026 share their lead bytes with the Unicode spaces `fifo_token_ok` refuses) + for word in "txt:it's" "txt:';echo\${IFS}pwned>&2;'" "'" "''" 'a"b' 'a$HOME`id`b;&|()<>' 'x\y\n' "txt:a+b" "txt:*" \ + "back" "ck:10,20" "txt:привет" "txt:caf$(printf '\303\251')" "txt:it’s—a…b"; do + stmt=$(fifo_write "$word") || { bad "fifo_write refused a one-word token: $word"; rm -f "$probe"; return 1; } + : > "$probe" + sh -c "$stmt" 2>/dev/null + got=$(cat "$probe") + [ "$got" = "$word" ] || { bad "the FIFO got '$got' for the word '$word'"; rm -f "$probe"; return 1; } + done + rm -f "$probe" + # A token is ONE word: the app cuts a line at ANY whitespace, so each of these would be two tokens, the second + # (a title's press with no subject) past every check in this file. The multi-byte ones are U+0085, U+00A0, + # U+1680, U+2000, U+200A, U+2028, U+2029, U+202F, U+205F and U+3000. + local refused=( + $'back\nok' "back ok" $'back\tok' $'back\rok' $'back\vok' $'back\fok' " back" "back " "txt:a b" + "back press:home.hero.play" "ok press:home.shelf.2.card.5" $'back\n press:x' + $'back\xc2\x85press:x' $'back\xc2\xa0press:x' $'back\xe1\x9a\x80press:x' $'back\xe2\x80\x80press:x' + $'back\xe2\x80\x8apress:x' $'back\xe2\x80\xa8press:x' $'back\xe2\x80\xa9press:x' $'back\xe2\x80\xafpress:x' + $'back\xe2\x81\x9fpress:x' $'back\xe3\x80\x80press:x' + ) + for word in "${refused[@]}"; do + if fifo_write "$word" >/dev/null 2>&1; then bad "fifo_write accepted a token with whitespace in it: $(printf '%s' "$word" | od -An -c | tr -s ' ' | head -c 60)"; return 1; fi + done + # fifo_send: a refusal sends nothing, a word is sent as one ssh command carrying the escaped quote. + _real_tv=$(declare -f tv) + tv() { sent_to_tv=1; sent_arg=$1; } + for word in "${refused[@]}"; do + fifo_send "$word" >/dev/null 2>&1; got=$? + [ "$got" = 2 ] && [ "$sent_to_tv" = 0 ] || { eval "$_real_tv"; bad "a token with whitespace was sent (status $got)"; return 1; } + done + fifo_send "txt:it's" >/dev/null 2>&1; got=$? + eval "$_real_tv" + [ "$got" = 0 ] && [ "$sent_to_tv" = 1 ] || { bad "an ordinary word was not sent (status $got)"; return 1; } + case "$sent_arg" in + *"'txt:it'\\''s'"*) ;; + *) bad "the apostrophe was not escaped for the remote shell: $sent_arg"; return 1 ;; + esac + ok "tv-session FIFO quoting (any one-word token is sent as one remote word; a token with whitespace is not sent)" + + # ---- `key` is not a second door for the by-id tokens. `key_word_ok` is the predicate (returns 2, so it can be + # tested here: `cmd_key` exits). + for word in down ok back "ck:10,20" "txt:a+b" "txt:press:x" "pat:x" "shot" "hang:1000" "focused" "pressed:x" "stated"; do + key_word_ok "$word" >/dev/null 2>&1 || { bad "key refused the key token: $word"; return 1; } + done + for word in "focus:nav.watchlist" "press:home.continue.card.0" "press:home.hero.play" "press:home.shelf.2.card.5@1234" \ + "press:nav.watchlist" "state:abc" "focus:" "press:" "state:"; do + if key_word_ok "$word" >/dev/null 2>&1; then bad "key accepted the by-id token: $word"; return 1; fi + done + got=$(key_word_ok "press:home.continue.card.0" 2>&1 || true) # (not a pipe into grep: the refusal's status 2 fails a pipefail pipeline) + case "$got" in + *"use the press verb"*) ;; + *) bad "key's refusal does not point to the press verb: $got"; return 1 ;; + esac + # ... and every door still sends what it should, and a refusal sends NOTHING (not even the words in front of + # the bad one). + selftest_key_doors || return 1 + ok "tv-session key door (focus:/press:/state: only through their verbs; a refusal sends nothing)" +} + +# The usage text ends on the header's last option row (`--keep`) and holds every option whole: it began as a line +# count that stopped inside `--remote` once the list outgrew it. +selftest_usage() { + local out last + out=$(usage) || { bad "usage: the header's end marker (# SCREEN OFF is a panel state) is gone"; return 1; } + case "$(printf '%s\n' "$out" | sed -n 1p)" in + "tv-session.sh "*) ;; + *) bad "usage does not start at the header's title"; return 1 ;; + esac + last=$(printf '%s\n' "$out" | tail -n 1) + case "$last" in + " --keep "*) ;; + *) bad "usage ends at '$last', not at the header's last option row (--keep; if an option was added after it, move this check)"; return 1 ;; + esac + printf '%s\n' "$out" | grep -q 'never a router port forward' || { bad "usage stops inside the --remote entry"; return 1; } + ok "tv-session usage text (the whole command and option list, ending on --keep)" +} + +# Run one door (`cmd_key`, `cmd_press`, ...) in a subshell, the set and its lock stubbed out: each `tv` call is one +# line in `$1`. Prints " ". `exit` inside a door only ends the subshell. +selftest_door() { # $1 = scratch file, then the door and its words + local marker=$1 rc + shift + : > "$marker" + ( tv() { printf '%s\n' "$1" >> "$marker"; }; require_lock() { :; }; info() { :; }; "$@" ) >/dev/null 2>&1; rc=$? + printf '%s %s' "$rc" "$(grep -c . "$marker")" +} + +selftest_key_doors() { + local marker rc=0 + marker=$(mktemp "${TMPDIR:-/tmp}/plx-key-selftest.XXXXXX") || { bad "no scratch file for the key check"; return 1; } + selftest_key_doors_in "$marker" || rc=1 + rm -f "$marker" + return "$rc" +} + +selftest_key_doors_in() { # $1 = scratch file + local m=$1 + # a refusal: status 2 and nothing sent + local -a refused=( + "cmd_key press:home.continue.card.0" "cmd_key focus:nav.watchlist" "cmd_key state:abc" + "cmd_key back press:home.continue.card.0" "cmd_key press:home.hero.play back" + "cmd_press home.hero.play" "cmd_press home.hero.info" "cmd_press home.hero.watchlist" + "cmd_press itemmenu.play" "cmd_press itemmenu.watchlist_remove" "cmd_press itemmenu.version.0" + "cmd_press detail.hero.play" "cmd_press detail.hero.restart" "cmd_press detail.hero.trailer" + "cmd_press detail.hero.mark_watched" "cmd_press detail.hero.mark_unwatched" "cmd_press detail.hero.watchlist" + "cmd_press home.shelf.2.card.5" "cmd_press home.hero.play --rk" "cmd_press home.hero.play --rk 1+2" + "cmd_press versions.row.1" "cmd_press player.control.next" "cmd_press player.control.previous" + "cmd_press player.control.next_episode" "cmd_press player.control.from_beginning" "cmd_press player.control.skip" + "cmd_press player.control.5" "cmd_press player.section.0" "cmd_press player.failure.try_again" + "cmd_press player.failure.play_automatically" "cmd_press more.fold.next" "cmd_press more.fold.from_beginning" + "cmd_press more.rung.auto" "cmd_press menu.audio.0" "cmd_press menu.sub.1" "cmd_press menu.off" + "cmd_press menu.forced" "cmd_press menu.hit.2" + ) + local door + for door in "${refused[@]}"; do + # shellcheck disable=SC2086 # the words are spelled in the entry, none holds a space + [ "$(selftest_door "$m" $door)" = "2 0" ] || { bad "$door was not refused with nothing sent ($(selftest_door "$m" $door))"; return 1; } + done + # one WORD with whitespace in it (a space, an NBSP) is refused before the `back` ahead of it is sent + [ "$(selftest_door "$m" cmd_key back "ok press:home.continue.card.0")" = "2 0" ] || { bad "key sent a word with a space in it"; return 1; } + [ "$(selftest_door "$m" cmd_key back $'ok\xc2\xa0press:x')" = "2 0" ] || { bad "key sent a word with an NBSP in it"; return 1; } + [ "$(selftest_door "$m" cmd_key ok "back +press:x")" = "2 0" ] || { bad "key sent a word with a newline in it"; return 1; } + # the doors that stay open: key tokens through `key`/`click`, and the ids through their verbs + [ "$(selftest_door "$m" cmd_key back ok)" = "0 2" ] || { bad "key did not send two key tokens"; return 1; } + [ "$(selftest_door "$m" cmd_click 10 20)" = "0 1" ] && grep -q "'ck:10,20'" "$m" || { bad "click did not send ck:10,20"; return 1; } + [ "$(selftest_door "$m" cmd_focus nav.watchlist)" = "0 1" ] && grep -q "'focus:nav.watchlist'" "$m" || { bad "focus did not send its token"; return 1; } + [ "$(selftest_door "$m" cmd_press home.hero.play --rk 12)" = "0 1" ] && grep -q "'press:home.hero.play@12'" "$m" || { bad "press --rk did not send press:@"; return 1; } + [ "$(selftest_door "$m" cmd_press itemmenu.watchlist_remove --rk 7)" = "0 1" ] && grep -q "'press:itemmenu.watchlist_remove@7'" "$m" || { bad "an item-menu press naming its title was not sent"; return 1; } + [ "$(selftest_door "$m" cmd_press home.hero.action)" = "0 1" ] && grep -q "'press:home.hero.action'" "$m" || { bad "a bare press of the failure read-out's retry (no title) was not sent"; return 1; } + [ "$(selftest_door "$m" cmd_press detail.hero.mark_watched --rk 200622)" = "0 1" ] && grep -q "'press:detail.hero.mark_watched@200622'" "$m" || { bad "a Detail hero press naming its title was not sent"; return 1; } + # a Detail hero control whose target the page fixes (it only navigates or opens a menu) names no title, so a bare press of it goes out + [ "$(selftest_door "$m" cmd_press detail.hero.go_to_show)" = "0 1" ] && grep -q "'press:detail.hero.go_to_show'" "$m" || { bad "a bare press of the Detail hero's Go to Show (it only navigates) was not sent"; return 1; } + return 0 +} + # Host-only regression for the command contract above. It deliberately performs no TV I/O and is # run by `make check`; keeping it in this script proves the same Bash-3 code cmd_up calls rather # than a Python reimplementation of the option semantics. @@ -1050,6 +1223,70 @@ cmd_selftest() { } ok "tv-session direct-screen contract" + # ---- by accessibility id: the grammar, the card guard and the nonce match. Pure: nothing is sent. + local aid + for aid in nav.watchlist home.hero.play home.shelf.2.card.5 watchlist.grid.card.0 under-posters.row.3 \ + library.rail.12 itemmenu.version.0 detail.hero.mark_watched; do + a11y_id_ok "$aid" || { bad "a11y_id_ok refused the well-formed id $aid"; return 1; } + done + for aid in "" home nav. .nav nav..x Nav.watchlist nav.Watchlist nav.watch-list nav.05 nav.-1 "nav.a b" "nav.a;b" \ + "nav.x'y" 'nav.$HOME' 'nav.a[0]' nav.0x1 under-posters.row-3 "nav.watchlist +nav.home"; do + ! a11y_id_ok "$aid" || { bad "a11y_id_ok accepted a malformed id: $aid"; return 1; } + done + [ "$(a11y_token focus nav.watchlist)" = "focus:nav.watchlist" ] || { bad "focus token"; return 1; } + [ "$(a11y_token press detail.hero.go_to_show)" = "press:detail.hero.go_to_show" ] || { bad "press token"; return 1; } + [ "$(a11y_token press home.shelf.2.card.5 1234)" = "press:home.shelf.2.card.5@1234" ] || { bad "press-with-subject token"; return 1; } + [ "$(a11y_token press catalog.primary 5d7768ab)" = "press:catalog.primary@5d7768ab" ] || { bad "press subject on the catalog pill"; return 1; } + # Every id whose press acts on a title it names is pressed by name (`SUBJECT_BEARING`): a card, a Detail episode + # (OK on a still PLAYS it), a season tab, a Filmography credit, the catalog pill, a Home hero Play, Info or + # Watchlist button (the carousel advances by itself, so a bare press acts on whichever title is showing), a Detail + # hero control that plays or writes (Play, Restart, Trailer, Mark watched, Mark unwatched, Watchlist: each acts on + # the ratingKey its subject names), an item-menu row (it acts on the title the hold opened), a Play Version row, a + # player control that starts or restarts a title (Previous, Next, Next Episode, From beginning, Skip, an id spelled + # by position, an Info card button, a failure retry, a More fold). Without --rk each is refused; with it, each is + # sent as press:@. + for aid in home.shelf.2.card.5 home.continue.card.0 watchlist.grid.card.3 detail.episodes.still.0 \ + detail.episodes.text.0 detail.episodes.still.3 detail.season.1 filmography.row.2 catalog.primary \ + home.hero.play home.hero.info home.hero.watchlist detail.hero.play detail.hero.restart detail.hero.trailer \ + detail.hero.mark_watched detail.hero.mark_unwatched detail.hero.watchlist \ + itemmenu.play itemmenu.watchlist_remove itemmenu.version.0 versions.row.0 versions.row.2 \ + player.control.next player.control.previous player.control.next_episode player.control.from_beginning \ + player.control.skip player.control.5 player.section.0 player.section.1 player.failure.try_again \ + player.failure.play_automatically more.fold.previous more.fold.next more.fold.from_beginning more.rung.auto \ + more.rung.p720 menu.audio.0 menu.sub.1 menu.off menu.forced menu.hit.2; do + if a11y_token press "$aid" >/dev/null 2>&1; then bad "a press of $aid without --rk was accepted"; return 1; fi + [ "$(a11y_token press "$aid" 4321)" = "press:$aid@4321" ] || { bad "press of $aid with --rk was not sent as press:@"; return 1; } + [ "$(a11y_token focus "$aid")" = "focus:$aid" ] || { bad "focus of $aid was refused"; return 1; } + done + # ... and the ones that start or write no title still press with none (nothing is named by `--rk` there): the + # Detail hero's controls whose target the page fixes (`go_to_show`, `alt`, `version`, `more`: they navigate or open a + # menu or a panel), `home.hero.action` (the failure read-out's retry), which acts on no title, and the player's controls that open a + # panel, seek, pause or leave (tests/player_shots.sh presses its panel openers bare) are pressed bare. + for aid in detail.about.card detail.about.languages detail.hero.go_to_show detail.hero.alt detail.hero.version \ + detail.hero.more under-posters.row.3 filmography.tab.2 nav.watchlist home.hero.action \ + player.control.subtitles player.control.audio player.control.more player.control.play_pause \ + player.control.seek_back player.control.watch player.control.watch_credits player.tab.info \ + player.tab.chapters player.chapter.0 player.scrub player.failure.change_quality player.failure.back \ + more.quality more.speed more.stats more.rate.1500 more.fold.go_to_detail menu.boost menu.loudness menu.timing menu.style \ + menu.search menu.field.size menu.retry menu.lang.0; do + [ "$(a11y_token press "$aid")" = "press:$aid" ] || { bad "press of $aid needlessly wanted --rk"; return 1; } + done + for aid in "1 2" "12'34" '12@3' '12$x' "12;x" ""; do + if a11y_token press watchlist.grid.card.3 "$aid" >/dev/null 2>&1; then bad "an unsafe --rk was accepted: $aid"; return 1; fi + done + if a11y_token focus nav.watchlist 123 >/dev/null 2>&1; then bad "focus accepted a ratingKey"; return 1; fi + if a11y_token press "nav.Bad" >/dev/null 2>&1; then bad "press accepted a malformed id"; return 1; fi + a11y_answers abc '{"schema":1,"nonce":"abc","elements":[]}' || { bad "a11y_answers missed its own nonce"; return 1; } + a11y_answers abc '{ "nonce" : "abc" }' || { bad "a11y_answers is whitespace-sensitive"; return 1; } + if a11y_answers abc '{"nonce":"abd"}'; then bad "a11y_answers took another request's file"; return 1; fi + if a11y_answers abc '{"label":"abc"}'; then bad "a11y_answers matched a value that is not the nonce"; return 1; fi + aid=$(a11y_nonce) + [ "${#aid}" -eq 16 ] || { bad "a11y_nonce is not 16 characters"; return 1; } + ok "tv-session by-id contract (grammar, a title's element needs --rk, nonce match)" + selftest_fifo || return 1 + selftest_usage || return 1 + # ---- identity: `--guest` must resolve the real managed-user token or REFUSE, and must never # fall through to the owner's — the 2026-09-10 TV session 5 defect (a warning printed, then the # owner's token pushed anyway; a real playback wrote progress into the household Plex account, @@ -1157,20 +1394,218 @@ cmd_status() { fi } -cmd_key() { - [ $# -gt 0 ] || { echo "usage: tv-session.sh key ..." >&2; exit 2; } +# One token into the remote FIFO. The app drains it each frame; the write is time-boxed so a FIFO +# with no reader (app not running) cannot wedge this shell. `fifo_write` single-quotes the token for the +# remote shell the POSIX way (`'` becomes `'\''`) and refuses a token with whitespace in it, so ANY one-word +# token is safe here: an apostrophe in a `txt:` token included (`txt:` spells a space `+`). `focus`, `press` and +# `state` additionally validate their ids, subjects and nonce against the app's grammar (`a11y_id_ok`, +# `a11y_subject_ok`) before they get here. +# +# A TOKEN IS ONE WORD. The app cuts the FIFO into tokens at ANY whitespace: `rust-modules/src/remote.rs` finds +# the end of the complete run at ASCII whitespace (space, tab, newline, CR, FF) and then `split_whitespace` +# cuts it at every Unicode White_Space (VT, U+0085, U+00A0, U+2000-200A, U+2028/9, U+202F, U+205F, U+3000, ...). +# So `key $'back press:'` would write TWO tokens, the second a title's press with no subject named, past +# every check in this file. Refusing only a newline left that door open; every one of those separators is +# refused now, and the word is judged as BYTES (`LC_ALL=C`), so the multi-byte ones are matched in any locale. +fifo_token_ok() { # $1 = one token; says why not (stderr) and returns 2 for a word the app would read as several + local LC_ALL=C + case "$1" in + *[$' \t\n\r\v\f']*|*$'\xc2\x85'*|*$'\xc2\xa0'*|*$'\xe1\x9a\x80'*|*$'\xe3\x80\x80'*|\ + *$'\xe2\x80'[$'\x80\x81\x82\x83\x84\x85\x86\x87\x88\x89\x8a\xa8\xa9\xaf']*|*$'\xe2\x81\x9f'*) + echo "tv-session: a FIFO token is ONE word with no whitespace in it (the app reads a space, tab, newline or any other whitespace as the end of a token, so a second word would be a second token, past every check here)" >&2 + return 2 ;; + esac + return 0 +} + +fifo_write() { # $1 = one token; prints the one remote statement that writes it to the FIFO, or returns 2 + local sq="'" esc + fifo_token_ok "$1" || return 2 + esc=${1//$sq/$sq\\$sq$sq} + printf '%s' "printf '%s\n' '$esc' > $REMOTE_FIFO" +} + +# Returns 2 (and sends nothing) for a word `fifo_write` refuses, else 0: the remote `kill` that ends the +# time box exits non-zero whenever the write finished, so its status says nothing about the send. +fifo_send() { # $1 = one token + local stmt + stmt=$(fifo_write "$1") || return 2 + tv "($stmt) & P=\$!; sleep 2; kill \$P 2>/dev/null" 2>/dev/null + return 0 +} + +# `key` is for KEYS and the like (`down`, `ok`, `ck:,`, `txt:...`): never for the by-id tokens, which have +# ONE door each, `focus`, `press` and `state`, because those are where an id is checked against the grammar and a +# title's press is made to name the title (`--rk`). Returns 2 (and says why) for a word that starts one. +key_word_ok() { # $1 = one word given to `key` + case "$1" in + focus:*|press:*|state:*) + echo "tv-session: key does not send '${1%%:*}:' tokens: use the ${1%%:*} verb (focus , press [--rk ], state), which checks the id and makes a title's press name the title" >&2 + return 2 ;; + esac + return 0 +} + +# Every word is judged BEFORE any is sent (and before the lock is asked for): `key back "ok press:x"` must not +# send `back` and then refuse. The sender behind `key`, `click`, `focus` and `press`; exits 2 on a refusal. +send_tokens() { # $@ = tokens, in order + local t + for t in "$@"; do fifo_write "$t" >/dev/null || exit 2; done require_lock "tv-session key" - # the app drains the FIFO each frame; time-box the write so a FIFO with no reader - # (app not running) cannot wedge this shell for t in "$@"; do - tv "(printf '%s\n' '$t' > $REMOTE_FIFO) & P=\$!; sleep 2; kill \$P 2>/dev/null" 2>/dev/null + fifo_send "$t" || exit 2 info "sent $t" done } +cmd_key() { + [ $# -gt 0 ] || { echo "usage: tv-session.sh key ... (key tokens: down ok back ... ; focus/press/state have their own verbs)" >&2; exit 2; } + local t + for t in "$@"; do key_word_ok "$t" || exit 2; done + send_tokens "$@" +} + cmd_click() { [ $# -eq 2 ] || { echo "usage: tv-session.sh click (authored 1920x1080)" >&2; exit 2; } - cmd_key "ck:$1,$2" + send_tokens "ck:$1,$2" +} + +# ----------------------------------------------------- by accessibility id ---- +# `focus:`, `press:[@]` and `state:` are FIFO tokens of a `devtriggers` build +# (rust-modules/ui/src/a11y.rs, dispatch/by_id.rs, src/app/a11y_state.rs). The checks below are the +# grammar's own, so a malformed id stops HERE rather than as a refusal line on the set. (Quoting for the +# remote shell is `fifo_write`'s, for every word `key` and `click` send as well, and so is the refusal of a word +# with whitespace in it; `key` itself refuses these three tokens: see `key_word_ok`.) +# +# id .: ns [a-z][a-z0-9_-]*, then one or more segments, each a name [a-z][a-z0-9_]* +# or a canonical decimal index (0, or digits with no leading zero) +# subject a ratingKey (or a catalog hex id): [A-Za-z0-9_-]+, a subset of what the app accepts +A11Y_ID_RE='^[a-z][a-z0-9_-]*(\.([a-z][a-z0-9_]*|0|[1-9][0-9]*))+$' +A11Y_SUBJECT_RE='^[A-Za-z0-9_-]+$' +A11Y_STATE_TRIES=24 # `state` polls the runtime root this many times, a half second apart + +a11y_id_ok() { # $1 = a full accessibility id. LC_ALL=C: [a-z] must not follow a locale's collation. + case "$1" in *$'\n'*) return 1 ;; esac + printf '%s\n' "$1" | LC_ALL=C grep -Eq "$A11Y_ID_RE" +} + +a11y_subject_ok() { # $1 = a ratingKey / subject + case "$1" in *$'\n'*) return 1 ;; esac + printf '%s\n' "$1" | LC_ALL=C grep -Eq "$A11Y_SUBJECT_RE" +} + +# The token for focusing or pressing an id; says why not (stderr) and returns 2 when it must not be sent. +# a11y_token focus -> focus: +# a11y_token press [] -> press: or press:@ +# An element whose subject is a title is pressed BY NAME (`--rk`): the real-account rule's own guard (never +# press OK on a title whose ratingKey you have not read), and the app compares it against the subject of the +# element it finds there. `press` refuses without it; `focus` moves nothing that is account-affecting, so it +# takes none. Which ids those are is `a11y_subject_bearing`. +# +# THE LIST IS READ OFF THE CODE (`git grep -n with_subject rust-modules`), one entry per production +# `A11y::with_subject` call SITE, and is the same list as `SUBJECT_BEARING` in tools/a11y.py, which carries the table of +# what each entry is and why (a test holds the two equal; another holds the number of calls per file equal to the +# sites it was derived from, and another the set of files that construct a title-acting message equal to the files it +# covers). THE RULE (stated in full at `SUBJECT_BEARING`): an id is in it when its press ACTS ON a title it names, which +# includes opening that title's own page or menu where the title can change under the press (a card, a credit, the Home +# carousel's Info); only a control whose target the page fixes is pressed bare. A bare `*.row.*` would also catch `under-posters.row.3`, so the namespaced ones are spelled +# out, and the player's controls are spelled by word (`player.control.subtitles` opens a panel and stays bare) with +# the positional spelling `player.control.[0-9]*` guarded whole, and the player's menus' rows by kind (a folded command +# that starts a title and `more.rung.*`, the quality rungs, which re-resolve it; the Tracks menu's track picks and +# subtitle-search results, which write to the title on the server; `more.speed|stats` and the rest stay bare). The rows of a Catalog item menu have no ratingKey, +# so `press` cannot name them and refuses them (a Watchlist title no server holds: the safe side). +a11y_subject_bearing() { # $1 = a full accessibility id + case "$1" in + *.card.*|detail.episodes.*|detail.season.*|filmography.row.*|catalog.primary|home.hero.play|home.hero.info|home.hero.watchlist|detail.hero.play|detail.hero.restart|detail.hero.trailer|detail.hero.mark_watched|detail.hero.mark_unwatched|detail.hero.watchlist|itemmenu.*|versions.row.*|player.control.previous|player.control.next|player.control.next_episode|player.control.from_beginning|player.control.skip|player.control.[0-9]*|player.section.*|player.failure.try_again|player.failure.play_automatically|more.fold.previous|more.fold.next|more.fold.from_beginning|more.rung.*|menu.audio.*|menu.sub.*|menu.off|menu.forced|menu.hit.*) return 0 ;; + esac + return 1 +} + +a11y_token() { + local act="$1" id="${2:-}" rk="${3:-}" + a11y_id_ok "$id" || { echo "tv-session: not an accessibility id: '$id' (want ...., e.g. nav.watchlist)" >&2; return 2; } + case "$act" in + focus) + [ -z "$rk" ] || { echo "tv-session: focus takes no ratingKey" >&2; return 2; } + printf 'focus:%s\n' "$id" ;; + press) + if a11y_subject_bearing "$id"; then + [ -n "$rk" ] || { + echo "tv-session: press $id: pressing this element acts on a title it names (the ids are SUBJECT_BEARING in tools/a11y.py), so name the title with --rk , the ratingKey of the title the press acts on (read it from \`state\`'s subject for the element, or the log, first)" >&2 + return 2; } + fi + if [ -n "$rk" ]; then + a11y_subject_ok "$rk" || { echo "tv-session: --rk wants a ratingKey of letters, digits, _ and -" >&2; return 2; } + printf 'press:%s@%s\n' "$id" "$rk" + else + printf 'press:%s\n' "$id" + fi ;; + *) echo "tv-session: internal: a11y_token focus|press" >&2; return 2 ;; + esac +} + +cmd_focus() { + [ $# -eq 1 ] || { echo "usage: tv-session.sh focus (e.g. nav.watchlist)" >&2; exit 2; } + local tok; tok=$(a11y_token focus "$1") || exit 2 + send_tokens "$tok" +} + +cmd_press() { + local id="" rk="" usage="usage: tv-session.sh press [--rk ] (a title's element needs --rk)" + while [ $# -gt 0 ]; do + case "$1" in + --rk) [ $# -ge 2 ] || { echo "$usage" >&2; exit 2; } + rk="$2"; shift 2 ;; + --rk=*) rk="${1#*=}"; shift ;; + -*) echo "$usage" >&2; exit 2 ;; + *) [ -z "$id" ] || { echo "$usage" >&2; exit 2; } + id="$1"; shift ;; + esac + done + [ -n "$id" ] || { echo "$usage" >&2; exit 2; } + local tok; tok=$(a11y_token press "$id" "$rk") || exit 2 + send_tokens "$tok" +} + +# A nonce in the app's grammar ([A-Za-z0-9_-]{1,32}): 16 hex digits. +a11y_nonce() { od -An -N8 -tx1 /dev/urandom | tr -d ' \n'; } + +# Does the state file text `$2` answer the request that carried nonce `$1`? The file is compact JSON, +# so the member reads `"nonce":""`; a stale file names another nonce and does not match. +a11y_answers() { printf '%s' "$2" | grep -Eq "\"nonce\" *: *\"$1\""; } + +# Ask the app what is on screen: write `state:`, then read `$RUNDIR/plxnative-a11y.json` over ssh +# until it names that nonce (a bounded wait: the app is not running, was built without devtriggers, or is +# stalled). Prints the snapshot, or writes it to FILE (owner-only) and prints one line about it. +cmd_state() { + local out="" usage="usage: tv-session.sh state [--out FILE]" + while [ $# -gt 0 ]; do + case "$1" in + --out) [ $# -ge 2 ] && [ -n "$2" ] || { echo "$usage" >&2; exit 2; } + out="$2"; shift 2 ;; + --out=*) out="${1#*=}"; [ -n "$out" ] || { echo "$usage" >&2; exit 2; }; shift ;; + *) echo "$usage" >&2; exit 2 ;; + esac + done + require_lock "tv-session state" + local nonce doc i + nonce=$(a11y_nonce) + fifo_send "state:$nonce" + for i in $(seq 1 "$A11Y_STATE_TRIES"); do + doc=$(tvq "cat $RUNDIR/plxnative-a11y.json") + if [ -n "$doc" ] && a11y_answers "$nonce" "$doc"; then + if [ -n "$out" ]; then + ( umask 077; printf '%s\n' "$doc" > "$out" ) || { bad "cannot write $out"; return 1; } + ok "state:$nonce answered; $(printf '%s' "$doc" | wc -c | tr -d ' ') bytes written to $out" + else + printf '%s\n' "$doc" + fi + return 0 + fi + sleep 0.5 + done + bad "no snapshot named state:$nonce appeared in $RUNDIR (app not running, a RELEASE=1 build, or its loop is stalled)" + return 1 } cmd_shot() { @@ -1471,6 +1906,17 @@ CUT esac } +# The text an unknown subcommand prints: the header's command and option list, from line 3 down to the paragraph +# that opens the prose (`# SCREEN OFF is a panel state`), found by THAT LINE and not by a line count. The count it +# replaced (`sed -n '3,60p'`) went stale each time the list grew, and the text stopped in the middle of `--remote`; +# `selftest_usage` holds the end. +usage() { + local text + text=$(awk 'NR < 3 { next } /^# SCREEN OFF is a panel state/ { found = 1; exit } { print } END { exit !found }' \ + "${BASH_SOURCE[0]}") || { echo "tv-session: internal: the header's usage text has no end marker (# SCREEN OFF ...)" >&2; return 1; } + printf '%s\n' "$text" | sed 's/^# \{0,1\}//' +} + case "${1:-}" in selftest) cmd_selftest ;; wan) shift; cmd_wan "$@" ;; @@ -1481,8 +1927,11 @@ case "${1:-}" in status) shift; cmd_status ;; key) shift; cmd_key "$@" ;; click) shift; cmd_click "$@" ;; + focus) shift; cmd_focus "$@" ;; + press) shift; cmd_press "$@" ;; + state) shift; cmd_state "$@" ;; shot) shift; cmd_shot "$@" ;; log) shift; cmd_log "$@" ;; down) shift; cmd_down ;; - *) sed -n '3,55p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 2 ;; + *) usage; exit 2 ;; esac diff --git a/tools/watchlist_captures.py b/tools/watchlist_captures.py index d3d0bdd91f..2a1a1843da 100644 --- a/tools/watchlist_captures.py +++ b/tools/watchlist_captures.py @@ -8,13 +8,33 @@ 2. a fresh instance root with `plxnative-plextv` and `plxnative-discover` aimed at the mock; a prep boot with `plxnative-login` signs in through the app's own QR flow (the stored mock session is the account; no `token` trigger is armed); - 3. arm the capture's `triggers`, boot, wait `boot_wait_s`, send each key through - `plxnative-remote` (`hold` is okdown, 1.2 s, okup), then `shot`; + 3. arm the capture's `triggers`, boot, wait `boot_wait_s`, send each `keys` entry through + `plxnative-remote` (`hold` is okdown, 1.2 s, okup), check `expect_focus`, then `shot`; + A capture REACHES its target by an accessibility-id token (tools/a11y.py, the app's devtriggers + tokens) or by a boot trigger: `focus:` moves focus to the element the id names (`nav.watchlist`, + `watchlist.grid.card.7`, `home.shelf.2.card.0`) and `press:` focuses it and presses OK, so no + direction key stands between the boot and the target in any capture. What stays a key is a key whose + subject is the key itself: `hold`, a timing (`ok@0.12`), `back`; and `ck:,` pointer clicks, + which `w6/detail-offline.png` alone uses as its walk. An id is checked against the grammar before + anything boots. A press of an element that acts on a title it names (`a11y.SUBJECT_BEARING` is the one + list) NAMES that title, `press:@`, and the app refuses it when + another title is there, so a hero that moved on or a menu opened on another card fails the capture + instead of acting on it: `press:itemmenu.watchlist_remove@2001` (The Long Meridian, the mock's second + Watchlist title), `press:home.hero.watchlist@200622` (the first Continue Watching episode of the + `catalog` mock) and `press:detail.hero.watchlist@1001` (the Detail page of Harbor Lights, the + `first_movie_off` mock's first movie). The one bare title press is `watchlist.grid.card.7`, a coming-soon card with no key. A key `mock:` POSTs to /_mock/discover mid-walk (`{"pms":"fail"}` makes the PMS side answer 503: once a library read fails and the list is read again, a title matched there reads ServerOffline); `lib:` POSTs to /_mock/library (a TEST-ONLY library add/remove plus the `timeline` frame the feed carries for it: W-notify); `sleep:` waits seconds; any other key, `ck:,` (a click at logical 1920x1080 pixels) included, goes to the FIFO as it is; + `expect_focus` names the full id the app must have focused when the walk is done: the driver asks + for a `state` snapshot (`a11y.expect_focus`) and fails the capture, naming both ids, when it + differs; a walk that ends in a TIMED key is checked before that key (its shot must follow it within + the wait, and a `state` round trip is longer). A capture whose boot trigger decides what is focused + (an opener row: `account-menu-new.png`, `item-menu-new.png`) or whose pointer clicks do + (`w6/detail-offline.png`) may leave it out. A refused id (`a11y: refused ...` in the event log) + fails the capture whatever the focus; A capture with `unreachable` aims the plex.tv and Discover triggers at a closed loopback port AFTER the sign-in, so the stored mock session is the account but the service cannot answer (the "plex.tv unreachable" state); @@ -38,15 +58,67 @@ import time import urllib.request +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent)) +import a11y # noqa: E402 (tools/a11y.py: the by-id tokens and the `state` read-back) + ROOT = pathlib.Path(__file__).resolve().parent.parent SCENARIO = ROOT / "tests" / "scenarios" / "watchlist_captures.json" # --scenario overrides SIGN_IN_DONE = "hubs: landed" # the event-log line after which the sign-in's session is on disk +FOCUS_WAIT_S = 8 # how long `expect_focus` waits for the app to answer with the focus it wants class Failure(Exception): pass +def step_kind(token): + """How the driver sends one `keys` entry: `hold`, `mock`, `lib`, `sleep`, `byid` (`focus:`, + `press:[@]`) or `key` (everything else: a key name, `ck:,`, `ok@0.12`). + The `@` of a by-id token is a subject's, never a timing's: only a `key` carries `key@`.""" + if token == "hold": + return "hold" + for kind in ("mock", "lib", "sleep"): + if token.startswith(kind + ":"): + return kind + if token.startswith(("focus:", "press:")): + return "byid" + return "key" + + +def check_steps(file, keys): + """Fail, before anything boots, on a by-id entry the app would refuse as malformed.""" + for token in keys: + if step_kind(token) == "byid": + try: + a11y.parse_token(token) + except ValueError as e: + raise Failure(f"{file}: {e}") + + +def expect_position(keys): + """Where in the walk `expect_focus` is checked: after the last entry, or BEFORE it when the last is a + timed key (`ok@0.12`): that capture's shot must follow the key within the wait, and the `state` round + trip is longer than a flip.""" + if keys and step_kind(keys[-1]) == "key" and "@" in keys[-1]: + return len(keys) - 1 + return len(keys) + + +def check_focus(runtime, spec): + """Fail the capture unless the app has the focus `spec["expect_focus"]` names (a no-op without one).""" + want = spec.get("expect_focus") + if not want: + return + try: + a11y.expect_focus(runtime, want, timeout=FOCUS_WAIT_S) + except a11y.FocusMismatch as e: + events = runtime / "plxnative-events.log" + refused = a11y.refusals(events.read_text(errors="replace")) if events.exists() else [] + raise Failure(f"{spec['file']}: {e}" + (f"; the app refused: {'; '.join(refused)}" if refused else "")) + except TimeoutError as e: + raise Failure(f"{spec['file']}: {e} (a RELEASE=1 build has no state: token, or the app is stalled)") + + def sim_env(runtime): """This machine's environment minus every PLXNATIVE_* variable, plus the instance root.""" env = {k: v for k, v in os.environ.items() if not k.startswith("PLXNATIVE_")} @@ -105,7 +177,7 @@ def capture(sim, spec, scenario, out_dir): srv, pms = mock_pms.serve(0, authorize_after=2) port = srv.server_address[1] runtime = pathlib.Path(tempfile.mkdtemp(prefix="plxnative-wl-")) - proc = None + proc = log = None try: post(port, "/_mock/discover", dict({"list": spec["mock"]}, **spec.get("mock_extra", {}))) for name in ("plextv", "discover"): @@ -134,25 +206,34 @@ def capture(sim, spec, scenario, out_dir): def send(tok): os.write(fd, (tok + " ").encode()) - for key in spec["keys"]: - if key == "hold": + keys = spec["keys"] + at = expect_position(keys) + for i, key in enumerate(keys): + if i == at: + check_focus(runtime, spec) + kind = step_kind(key) + if kind == "hold": send("okdown") time.sleep(1.2) send("okup") - elif key.startswith("mock:"): + elif kind == "mock": # `mock:{"pms":"fail"}`: POST that body to /_mock/discover mid-walk (the PMS goes # away after the Watchlist matched a title on it: the server-offline state). post(port, "/_mock/discover", json.loads(key[5:])) continue - elif key.startswith("lib:"): + elif kind == "lib": # `lib:{"op":"add","title":"Northbound Tide"}`: POST that body to /_mock/library, a # TEST-ONLY library change plus the `timeline` frame the feed would carry for it # (the W-notify scenario: the tile flips without leaving the tab). post(port, "/_mock/library", json.loads(key[4:])) continue - elif key.startswith("sleep:"): + elif kind == "sleep": time.sleep(float(key[6:])) continue + elif kind == "byid": + # `focus:` / `press:[@]`: the app resolves the id at its ordered + # delivery position, so it acts after every token written before it. + send(key) else: # `key@0.3` waits 0.3 s instead of key_wait_s before the next key (or the shot): # the way to catch a spring mid-flight. @@ -161,6 +242,8 @@ def send(tok): time.sleep(float(wait) if wait else scenario["key_wait_s"]) continue time.sleep(scenario["key_wait_s"]) + if at == len(keys): + check_focus(runtime, spec) send("shot") shot, last = None, -1 for _ in range(40): # the file appears before it is written: wait for a non-empty, steady size @@ -177,6 +260,10 @@ def send(tok): os.close(fd) (out_dir / spec["file"]).parent.mkdir(parents=True, exist_ok=True) shutil.copy(shot, out_dir / spec["file"]) + events = runtime / "plxnative-events.log" + refused = a11y.refusals(events.read_text(errors="replace")) if events.exists() else [] + if refused: # the picture is of a state the walk did not reach + raise Failure(f"{spec['file']}: the app refused a by-id token: {'; '.join(refused)}") want_log = spec.get("expect_log") if want_log and want_log not in (runtime / "plxnative-events.log").read_text(errors="replace"): raise Failure(f"{spec['file']}: the event log has no `{want_log}`") @@ -189,13 +276,20 @@ def send(tok): if proc is not None: proc.kill() proc.wait() + if log is not None: + log.close() # the console file the sim wrote to: a leaked handle is a ResourceWarning in a later test + if proc is not None: # The run's event log (a panic, a frame guard's catch) and console are kept beside the - # capture as .log / .out. + # capture as .log / .out. A failed capture (a focus mismatch, a missing shot) gets here + # BEFORE the shot's own mkdir, so a `w6/x.png` capture makes its directory first: without it the + # copy raises FileNotFoundError, which hides the Failure and ends the whole run. + (out_dir / spec["file"]).parent.mkdir(parents=True, exist_ok=True) stem = spec["file"][:-len(".png")] for name, ext in (("plxnative-events.log", ".log"), ("sim.out", ".out")): if (runtime / name).is_file(): shutil.copy(runtime / name, out_dir / (stem + ext)) srv.shutdown() + srv.server_close() # the listening socket too: a run of 25 captures leaves none behind shutil.rmtree(runtime, ignore_errors=True) @@ -209,6 +303,14 @@ def main(): scenario = json.loads(pathlib.Path(args.scenario).read_text()) out_dir = pathlib.Path(args.out or scenario["output_dir"]) out_dir.mkdir(parents=True, exist_ok=True) + for spec in scenario["captures"]: + try: + check_steps(spec["file"], spec["keys"]) + if spec.get("expect_focus") and not a11y.valid_id(spec["expect_focus"]): + raise Failure(f"{spec['file']}: expect_focus {spec['expect_focus']!r} is not an accessibility id") + except Failure as e: + print(f"FAIL {e}", file=sys.stderr) + return 1 failed = [] for spec in scenario["captures"]: if args.only and spec["file"] not in args.only: From 06a54f5c9c2cde8da1d6ff1267a253fc918050d8 Mon Sep 17 00:00:00 2001 From: Gleb Linnik Date: Wed, 18 Nov 2026 19:48:01 +0300 Subject: [PATCH 02/12] Glass menus are frosted, and their open and close fit the frame budget (#1459) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary The glass menus (Library and Watchlist Sort & Filter, the +N list, and the profile menu) are now frosted glass rather than a grey field: the frozen page behind the panel is blurred once, under a thin face of rgb(58,58,64) at .36 over rgb(40,40,46) at .44 (the owner's pick from the mock). The pass that follows makes the frost and the menus' existing close costs fit the TV's frame budget together. **The frost** (`gfx::FrameCache`, profiler phase `glass.frost_build`; `glass.frost` stays the name of the experimental full-resolution frost quad in `glassload.rs`): - Once per page snapshot, the region under the settled panel plus a 120 px margin (`FROST_MARGIN`, aligned to 8) is reduced 1/4 → 1/8 and blurred with two Kawase passes (d = 1.5, 2.5; σ ≈ 24 px). The panel composites that texture; nothing is blurred per frame. - Legibility keeps every contrast floor. The body is capped at `FROST_BODY_CEILING` = 0.333, derived rather than tuned: the tertiary ink reaches 3:1 at a body of 0.3372, minus 1/255. A soft knee from 0.9 of the ceiling (`y = knee + d·o/(o+d)`) keeps a bright page from reading flat; at 0.6 the frost was visibly darker than the mock. - The frost is a compile-time variant of the glass shader (`#define PLX_FROST`, `FS_GLASS_FROST`) linked with `link_optional_program`. If it fails to link, the log says `glass frost prog unavailable` and the menus keep the field face (`MENU_GLASS_FIELD_TOP/BOT`, .78/.86). The plain glass program is unchanged. The ~45 `static mut GL_*` uniform locations became a by-value `GlassUniforms`. **The body bake** (`FrameCache::frost_bake_owed`, `fs_frost_bake.frag`, phase `glass.bake`): the modal dim and the ceiling are applied once into a 1/8-resolution texture, keyed by the frost epoch, the region, the dim (field texture, `tex_ledger::revision`, tint) and the cap, instead of per pixel on every frame. The dim reaches the bake as `ModalPresentation.dim` (`ModalStack::first_dim` → `UnderlayField::dim_of`, `Dispatcher::modal_presentation_at`). A page-sourced dim that latches after the head's bake wakes exactly one corrective frame (`DimSink::dim_settled` → `popover::host::frost_body_stale`). ## The account menu's close no longer re-takes the page The account menu is a Sheet, which freezes its host while open, so `bind_owner` re-took the page on the close's first frame (14.9M GPU cycles, 133% of a refresh). Now a layer that has only started closing drops the ground stage and keeps the page snapshot for every presentation style (`ModalCacheKey::began_closing` returns whether it did; `kept_host_live` and `live_hosts` are gone). That is safe only if a page that changes under a cover says so. Pages now report a setting that moved under a cover at the head of `step`, through one shared helper (`registry::moved(&mut held, now)` plus `fx.invalidate(Provenance::Nav)`): Home, Library (including `sort_value`), Recommended (`deck_press`), Collection, Person, Search, Detail and Watchlist (caption policy and `rev`). Home damages on `FocusMoved` only when the focus or the `place()` fingerprint moved, and on `RestoreMemory` only when `projected_generation` or `place()` changed. ## The morph is frosted the whole way, and its rows show earlier The owner's direction from an iOS 26 recording: the droplet never reads as clear glass. `Frame::clear`, `clear_at` and `FROST_FROM`/`FROST_TO` are gone; the morph hands the glass only its join (clarity 0). From the first glass frame through the close's hand-back the body is the frost under `FROST_FACE`; a frame where the frost is not built yet wears the latched field under the heavier face, never the sharp page. `draw_shadowed` asks for the frost before the field check, so the build lands at the head of the open's second frame (O2) and stands when the glass first draws; nothing is added to O1. The rows fade in from `ROWS_FROM_AT` 0.05 (was 0.55; opaque at 0.8, was 0.96), first visible on the third glass frame (~33 ms) at a lens scale of ~0.2, and `content_alpha` is capped at `ground_alpha`. The close's row timing is unchanged. ## The opener is handed back the frame the droplet is gone After the profile menu closed, the "Demo" chip sat lighter for ~300 ms and then snapped darker (the owner's TV clip). The droplet's close ends ~14 frames after Back, but the surface (and with it the opener's lift, which paints the chip over the lighter latched field) was retired only when the Sheet container's spring rested, ~17 frames later. `Surface::faded` now also retires a closing surface on `Screen::handed_back`, for every style. In a sim film of the same scene the chip patch read 86 for frames 186-203 and 77 after; with the fix it reads 77 from the first hand-back frame. Regression tests: `a_morph_menus_surface_and_lift_end_on_the_frame_its_droplet_is_gone` (fails without the fix) and the rewritten `account_menu_route_tests::the_morph_begins_and_ends_on_the_chip_as_the_bar_draws_it` (asserts the surface leaves at the hand-back and the bar then draws the chip at its resting rect; red without the fix). ## Tried and reverted: folding the dim into the page The dim was folded into the held-page blit (`fs_dim_fold.frag`) to drop its separate full-screen pass. On the TV (same session, A-B-A, 11 cycles each) it COST GPU time on every dim-visible frame: Library open steady 9.36 / 9.34M with it and 9.05M without (+0.31M), account 7.60 / 7.60M against 7.19M (+0.41M), with 0.02M drift between the two fold-on runs. The `scrims` phase read 0 with the fold, but the folded draw landed in no phase, so only the frame total showed the cost. It is reverted in this branch. ## Measured on the TV All builds `ARM_PROFILE=release`, debug flavour, mock accounts only (the synthetic PMS checked before any key; the account menu signs in through the loopback plex.tv stand-in). GPU_ACTIVE from Mali HWCNT, median per frame role over 11 cycles; the budget is 11.2M per 60 Hz refresh. - **base:** main at 952d0a473 (#1444). - **frost only:** the frost before this pass (run 3). - **this branch:** the measured shape is run 6's fold-off build (ad499735e with the fold forced off; the branch's revert removes the same code). Run 5 measured ad499735e with the fold on; its pacing column is from that build. | | base | frost only | this branch | |---|---|---|---| | Library, rows visible (100-200 ms) | 10.74M | 11.48M (26 frames over) | 10.40M | | Library, open steady | 9.42M | 10.44M | 9.05M | | Library, close C3 | 10.42M | 11.81M (11 over) | 10.29M | | Library rows window, missed refreshes | 1 | 23 | 0 (run 5, fold on) | | Account, close's re-take frame (C2) | 14.90M (133%) | 14.91M | 5.10M | | Account close, missed refreshes | 25 | 33 | 1 (run 5, fold on) | | Account, open steady | 7.27M | 7.63M | 7.19M | - The frost's own build is one frame per snapshot (p50 0.68M; timed on the TV as `glass.frost`, renamed `glass.frost_build` afterwards) and the panel composite (`glass.frozen`) costs less than the base glass's (run 5: 4.19M against 4.63M). - Every program linked on the device: no `glass frost prog unavailable`, `link FAILED` or `shader compile FAILED` line in any log. - The DISPLAY captures of both menus show no banding, seam or flip. - The base and frost-only columns are from run 3, the third from run 6: different sessions. Run 6's fold-on build reproduced run 5 within 0.05M, which bounds the drift between sessions. - Not re-measured on the TV: the frosted-morph and hand-back changes (seen on the TV by the owner, not profiled), the pacing of the final shape (run 6 had no pacing leg; its frames are 0.3-0.4M cheaper than run 5's), and the commits after ad499735e (the revert, the merge of main, a test-isolation fix). ## Not fixed here - O1, the open's capture-and-latch frame, is over budget on main too (12.2-12.9M); the second frame is late in 19-21 of 21 cycles. Pre-existing, unchanged here. - The account menu's open missed 6 refreshes against 2-3 on base in run 5 (fold on). Without the fold its open frames are back at base (7.19M steady against 7.27M); its pacing was not re-measured. - `glass.bake` records at 2.0M during the dim ramp; not attributed. - The review noted that a close may rebuild the frost once (the close's first frame re-captures the page after the ground stage is dropped, which moves the page epoch). The run 5 HWCNT leg recorded one frost build per open-close cycle (11 over 11 cycles), and the close frames are under budget (Library C2 7.16M, account 5.50M), so it was left as is. - Damage under a cover not yet narrowed: Collection and Person on Enter/Uncover, `cards/grid.rs:355` and `shelf.rs:337/359`, `library/status.rs:53`, the `others_up` path (no Uncover), and the container chrome (not audited). --- docs/DESIGN.md | 2 +- docs/backdrop-blur-profiling.md | 2 +- docs/liquid-glass.md | 10 +- docs/watchlist.md | 10 +- rust-modules/gfx/src/gfx.rs | 1181 ++++++++++++++--- rust-modules/gfx/src/gfx/profile.rs | 5 + .../gfx/src/shaders/fs_frost_bake.frag | 58 + rust-modules/gfx/src/shaders/fs_glass.frag | 15 + rust-modules/screens/src/CLAUDE.md | 15 + rust-modules/screens/src/account_menu.rs | 5 + rust-modules/screens/src/collection.rs | 33 +- rust-modules/screens/src/detail/mod.rs | 6 +- rust-modules/screens/src/detail/tests.rs | 30 +- rust-modules/screens/src/home/mod.rs | 44 +- rust-modules/screens/src/home/tests.rs | 105 ++ rust-modules/screens/src/inputs.rs | 12 + rust-modules/screens/src/library/menu.rs | 5 + rust-modules/screens/src/library/mod.rs | 15 +- .../screens/src/library/recommended.rs | 11 + .../screens/src/library/recommended_tests.rs | 25 +- rust-modules/screens/src/library/tests.rs | 26 + rust-modules/screens/src/person.rs | 36 + rust-modules/screens/src/registry.rs | 2 +- rust-modules/screens/src/registry/captions.rs | 13 + rust-modules/screens/src/search/mod.rs | 12 +- rust-modules/screens/src/search/tests.rs | 24 + .../screens/src/watchlist/cards_harness.rs | 12 +- rust-modules/screens/src/watchlist/menu.rs | 5 + rust-modules/screens/src/watchlist/page.rs | 38 +- .../screens/src/watchlist/page_tests.rs | 47 + .../src/app/account_menu_route_tests.rs | 172 ++- rust-modules/src/app/bridge_test_support.rs | 26 +- rust-modules/src/app/run.rs | 4 +- rust-modules/ui/src/CLAUDE.md | 62 +- rust-modules/ui/src/containers/modal.rs | 91 +- rust-modules/ui/src/containers/tests.rs | 207 +++ rust-modules/ui/src/dispatch.rs | 10 + rust-modules/ui/src/fixture.rs | 11 +- rust-modules/ui/src/lib.rs | 35 +- rust-modules/ui/src/popover.rs | 138 +- rust-modules/ui/src/popover_glass.rs | 257 +++- rust-modules/ui/src/popover_host_mock.rs | 31 + rust-modules/ui/src/popover_host_tests.rs | 152 ++- rust-modules/ui/src/popover_morph.rs | 248 ++-- rust-modules/ui/src/screen.rs | 12 + rust-modules/ui/src/theme.rs | 52 +- rust-modules/ui/src/underlay.rs | 12 + rust-modules/ui/src/widgets.rs | 25 +- 48 files changed, 2815 insertions(+), 534 deletions(-) create mode 100644 rust-modules/gfx/src/shaders/fs_frost_bake.frag diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 3bed1fb99c..1e57de5ed0 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -204,7 +204,7 @@ shelf pitch, `consts::TITLE_DY + CARD_DY` (see `related.rs`, `cast.rs`, `extras. heading-to-card distance Home and the Library use, quoted as the sum rather than as a number this file would then have to keep in step. -Menus over a page are glass on frozen ground (DS6: `popover_glass`, gradient face, 1 px rim, soft shadow, 30% scrim; the body shows the dim's latched field and the rim refracts the once-captured host snapshot, so nothing is re-blurred while a menu is up). Every other surface stands on the page's own latched light: `widgets::panel_ground` draws the +Menus over a page are glass on frozen ground (DS6: `popover_glass`, gradient face, 1 px rim, soft shadow, 30% scrim; the body is a once-per-snapshot frost of the captured host page, the dim baked in, with the dim's latched field as the fallback body, and the rim refracts the once-captured host snapshot, so a menu runs no live blur chain). Every other surface stands on the page's own latched light: `widgets::panel_ground` draws the underlay field the modal dim latched, windowed to the panel's rect and graded toward the panel material under its frost. Backdrop-blur glass (`Glass::DYNAMIC_BACKDROP`) is chrome-only — the top bar's track and the profile chip — plus two non-interactive standing notes in the page layer: the "Hold OK for options" diff --git a/docs/backdrop-blur-profiling.md b/docs/backdrop-blur-profiling.md index 8501f46167..f34ca64017 100644 --- a/docs/backdrop-blur-profiling.md +++ b/docs/backdrop-blur-profiling.md @@ -85,7 +85,7 @@ to the correct cropped-texture UV offset. ## Cache and refresh policy -(Historical: DS6 later put popover glass back, `popover_glass`; since 2026-10-17 it stands on the frozen host and the latched field, not on this chain.) Popover panels stopped using the chain on 2026-09-19 (they stand on the latched underlay field, +(Historical: DS6 later put popover glass back, `popover_glass`; since 2026-10-17 it stands on the frozen host, not on this chain: its body is a frost of the host snapshot built once per snapshot by its own chain, `FrameCache::frost_passes`, and the latched field is the fallback body.) Popover panels stopped using the chain on 2026-09-19 (they stand on the latched underlay field, `widgets::panel_ground`); the cached popover preset `Glass::CACHED`, which reused the blurred `mid` texture until explicit page invalidation or a region containment miss, went with them. `Glass::DYNAMIC_BACKDROP` (the chrome) keeps drawing the glass material diff --git a/docs/liquid-glass.md b/docs/liquid-glass.md index 6172812e82..9f2c84119c 100644 --- a/docs/liquid-glass.md +++ b/docs/liquid-glass.md @@ -8,9 +8,11 @@ taste, so a design can be drawn against them instead of into them. **Update (DS6, Watchlist wave 2): popover menus are glass again** — `widgets::panel_ground` calls `popover_glass::draw` first (gradient face, 1 px rim, top highlight, soft shadow, `GlassRim::Menu` rim refraction, 30% compact scrim) and the field ground described next -is the fallback. Since 2026-10-17 that glass stands on FROZEN ground and is not a blur chain user: -its body is the latched underlay field, its rim refracts the host snapshot captured once when the -menu opened (`gfx::draw_glass_frozen`), and the frame's dim is applied to both at composite. The +is the fallback. Since 2026-10-17 that glass stands on FROZEN ground and is not a user of the live +blur chain below: its body is a frost of the host snapshot (one blur per snapshot, its own chain, +`FrameCache::frost_passes`, with the frame's dim baked in; the latched underlay field is the fallback +body), its rim refracts the host snapshot captured once when the menu opened +(`gfx::draw_glass_frozen`), and the frame's dim is applied to that rim snapshot at composite. The live version it replaced measured about 2 to 2.6M Mali GPU cycles a frame over the field ground; read the 2026-09-19 text below as the pre-DS6 history it is. @@ -342,7 +344,7 @@ source in the page layer rather than a member of the shared top band, flat fallb Library's scroll capsule (`ui::scroll_capsule`: the library's name, count and sort ("Films 1,284 · Date viewed") on the same standing container, `GlassRim::Standing` and `Material::UltraThin`, wearing the hold hint's fixed face; flat track fallback; drawn only while the chrome is tucked on a page whose header names two or more libraries; region-budgeted by `scroll_capsule::tests::a_long_names_capsule_stays_inside_the_glass_region_budget`), on -`Glass::DYNAMIC_BACKDROP` (the one preset left). **Popovers and sheets over a UI page were not glass, until DS6 (menus are again, on frozen ground with no blur chain; the field below is every sheet's ground and a menu's fallback)**: +`Glass::DYNAMIC_BACKDROP` (the one preset left). **Popovers and sheets over a UI page were not glass, until DS6 (menus are again, on frozen ground with no live blur chain: the body is a once-per-snapshot frost of the captured page; the field below is every sheet's ground and a menu's fallback)**: Sort, Filter, Sources, the item menu, *Also available*, *Track information*, *About*, Account, the person biography and the decision alert all draw their ground through `widgets::panel_ground` over the latched underlay field — the surfaces reach it as `DrawFrame::underlay`, the decision alert diff --git a/docs/watchlist.md b/docs/watchlist.md index a51aa7db8b..05ecdb9bd1 100644 --- a/docs/watchlist.md +++ b/docs/watchlist.md @@ -259,10 +259,12 @@ loaded yet (a matched copy whose facts have not arrived) leaves the wash on its the flat surface is for a page that has no key and for a title that has none. **The menus' glass (DS6).** The Sort & Filter panel and the hold menu are glass on frozen ground -(`ui::popover_glass`): the panel's body shows the modal dim's latched field and its rim refracts the -host snapshot taken once when the hold menu opened (the Sort & Filter panel's is retaken once when the -reflow a click started has stopped, below), with the frame's dim applied to both. Nothing behind -the hold menu is re-rendered or re-blurred while it opens, stands or closes, and the page under it +(`ui::popover_glass`): the panel's body is a frost of the page (one blur of the host snapshot with the +modal dim baked in, built once per snapshot; the modal dim's latched field is the fallback body) and +its rim refracts the host snapshot taken once when the hold menu opened, with the frame's dim applied +to the rim's snapshot at composite. The Sort & Filter panel's snapshot is retaken once when the +reflow a click started has stopped (below), and its frost is rebuilt once after that retake. Nothing +behind the hold menu is re-rendered while it opens, stands or closes, and the page under it does not move until it has let go (the Remove landing above). **The Sort & Filter menu shows each click**: its value reaches the grid at once and the cards reflow under the open panel (a card that changes slot in its row slides, one that changes row crossfades, the longest mover on top, a new diff --git a/rust-modules/gfx/src/gfx.rs b/rust-modules/gfx/src/gfx.rs index 41aad3b00d..4f85e72e1c 100644 --- a/rust-modules/gfx/src/gfx.rs +++ b/rust-modules/gfx/src/gfx.rs @@ -115,6 +115,22 @@ macro_rules! glsl_undithered { }; } +/// The FROST variant of the glass fragment source ([`GLASS_FROST`]): [`glsl_dithered`] with +/// `#define PLX_FROST` in front of the dither prelude, so `fs_glass.frag`'s `#ifdef PLX_FROST` code (the +/// frosted body's bare return: the baked body takes no dim and no ceiling at composite) is part of +/// this program and of no other. The plain glass program is [`glsl_dithered`] of the same file and +/// carries none of it. +macro_rules! glsl_dithered_frost { + ($file:literal) => { + // SAFETY: as `glsl!` — GLSL sources contain no interior NUL. + unsafe { + ::std::ffi::CStr::from_bytes_with_nul_unchecked( + concat!("#define PLX_FROST\n", include_str!("shaders/dither.glsl"), include_str!($file), "\0").as_bytes(), + ) + } + }; +} + macro_rules! glsl_dithered { ($file:literal) => { // SAFETY: as `glsl!` — GLSL sources contain no interior NUL. @@ -209,6 +225,10 @@ const VS_ART_WASH: &CStr = glsl!( ); const FS_BLUR: &CStr = glsl!("shaders/fs_blur.frag"); const FS_GLASS: &CStr = glsl_dithered!("shaders/fs_glass.frag"); +/// [`FS_GLASS`] behind `PLX_FROST`: the glass a menu's frosted body is drawn with ([`GLASS_FROST`]). +const FS_GLASS_FROST: &CStr = glsl_dithered_frost!("shaders/fs_glass.frag"); +/// The frost's BODY BAKE ([`FrostBake`]): the retained blur dimmed and capped once, at 1/8 resolution. +const FS_FROST_BAKE: &CStr = glsl!("shaders/fs_frost_bake.frag"); const FS_FLAT: &CStr = glsl!("shaders/fs_flat.frag"); const FS_RAMP: &CStr = glsl!("shaders/fs_ramp.frag"); /// The PLAIN TEXTURE program's fragment half ([`PLAIN_IMAGE`]): `fs_img.frag`'s `u_card.z < 0.5` @@ -3911,6 +3931,25 @@ pub struct FrameCache { /// where it was drawn, and the pixels are PREMULTIPLIED (the frame is drawn onto a transparent /// clear, so what the blend leaves is `(rgb * a, a)`). region: [c_int; 4], + /// **The retained FROST** (a glass menu's body): a blur of the page snapshot's `frost_rect`, its + /// own texture and FBO, at 1/8 of that rect. Built ONCE per snapshot ([`frost_build_owed`](Self::frost_build_owed) + /// at the head of a later frame), never per frame, and given back by [`release_frost`](Self::release_frost). + /// `frost_key` is the snapshot's epoch it was built from, `frost_want` the region the standing + /// menu asked for, `frost_off` the latch after a failed build. + frost: c_uint, + frost_fbo: c_uint, + frost_dim: (c_int, c_int), + frost_rect: [c_int; 4], + frost_key: u32, + frost_want: Option<[c_int; 4]>, + frost_off: bool, + /// **The frost's BODY**: the retained frost dimmed by the modal dim and held under its ceiling, the + /// texture the menu's glass actually draws ([`frost_read`](Self::frost_read)), at the frost's own + /// size and orientation. Baked by [`frost_bake_owed`](Self::frost_bake_owed) at the head of a frame + /// whenever its inputs ([`BodyKey`]) change, and given back with the frost. + body: c_uint, + body_fbo: c_uint, + body_key: Option, } #[cfg_attr(test, allow(dead_code))] @@ -3929,7 +3968,239 @@ impl FrameCache { prev: 0, prev_w: 0, prev_h: 0, + frost: 0, + frost_fbo: 0, + frost_dim: (0, 0), + frost_rect: [0; 4], + frost_key: 0, + frost_want: None, + frost_off: false, + body: 0, + body_fbo: 0, + body_key: None, + } + } + + /// The standing menu's settled panel, `[x, y, w, h]` authored px: the region the frost is owed over. + pub fn frost_want(&mut self, panel: [f32; 4]) { + self.frost_want = Some(frost_region(panel)); + } + + /// The frost as the glass reads it: its texture and canvas rect, whatever snapshot it was built + /// from (a stale one is kept until its replacement lands). `None`: none yet, or it failed. + /// + /// The texture is the BODY ([`frost_bake_owed`](Self::frost_bake_owed)): what the glass draws is the + /// frost already dimmed and capped, so a frost with no bake yet answers `None` (the field ground) + /// rather than an undimmed, uncapped picture the composite has no code to fix. + pub fn frost_read(&self) -> Option<(c_uint, [f32; 4], u32)> { + (self.frost != 0 && self.frost_rect[2] > 0 && self.body != 0 && self.body_key.is_some()).then(|| { + let r = self.frost_rect; + (self.body, [r[0] as f32, r[1] as f32, r[2] as f32, r[3] as f32], self.frost_key) + }) + } + + /// Could a frost be built at all (no latched failure, an FBO backend, and the glass program's frost + /// variant linked, [`glass_frost_linked`]: a menu whose frost nobody can draw keeps the field + /// ground and its heavier face)? Host tests' stand-in says no. + pub fn frost_possible(&self) -> bool { + !self.off && !self.fbo_off && !self.frost_off && glass_frost_linked() + } + + /// Is the baked body the one for `dim`, the dim the glass is about to draw under? `false` is a body + /// baked from a PREDICTION that did not hold (the dim's field latched after the frame's head): the + /// glass draws it for this one frame and the next head's bake replaces it. + pub fn frost_body_for(&self, dim: Option) -> bool { + self.body_key.is_some_and(|k| k.dim == BodyKey::dim_key(dim)) + } + + /// Is the frost the one for snapshot `key` over the region the menu wants? + pub fn frost_fresh(&self, key: u32) -> bool { + self.frost != 0 && self.frost_key == key && self.frost_want == Some(self.frost_rect) + } + + /// Give the frost's texture back: it goes with its host. + pub fn release_frost(&mut self) { + if self.frost_fbo != 0 { + // SAFETY: render thread, current context, like every GL resource here. + unsafe { glDeleteFramebuffers(1, &self.frost_fbo) }; + self.frost_fbo = 0; + } + delete_tex(self.frost); + self.frost = 0; + self.frost_rect = [0; 4]; + self.frost_want = None; + if self.body_fbo != 0 { + // SAFETY: as above. + unsafe { glDeleteFramebuffers(1, &self.body_fbo) }; + self.body_fbo = 0; + } + delete_tex(self.body); + self.body = 0; + self.body_key = None; + } + + /// **Build the frost a standing menu is owed**, if the page snapshot (epoch `key`) holds and none + /// is fresh for it. Called at the HEAD of a frame (before any draw reaches the frame's + /// framebuffer, so there is no mid-frame render-target switch to resolve), which is also always + /// a LATER frame than the capture it reads. `true` once a build ran. + pub fn frost_build_owed(&mut self, key: u32) -> bool { + let Some(want) = self.frost_want else { return false }; + if self.frost_fresh(key) || self.frost_off || !self.valid || self.tex == 0 || self.region != [0; 4] { + return false; + } + if blur_source_pass() || backdrop::discovering() || unsafe { LIVE_SCISSOR }.is_some() { + return false; + } + if video_plane_refuses("FrameCache::frost_build_owed") || !blur_lazy_init() || !glass_frost_linked() { + return false; + } + let ok = profile::phase("glass.frost_build", || unsafe { self.frost_passes(want) }); + if ok { + self.frost_rect = want; + self.frost_key = key; + } else { + self.frost_off = true; + log("frost: build failed — menus keep the field ground"); + } + ok + } + + /// **Bake the frost's body** if a frost stands and the body is not already the one for `dim` and the + /// ceiling `(knee, ceiling)`: the retained frost dimmed by `dim` (the frame's lowest modal dim, as + /// the glass would have applied it at composite), THEN held under the ceiling, into [`body`](Self::frost_read) + /// at 1/8 resolution (one 240x135 pass). Called at the HEAD of a frame beside + /// [`frost_build_owed`](Self::frost_build_owed), before any draw reaches the frame's framebuffer, so + /// the frame's render pass is not split. Runs when the snapshot, the dim (every frame of its ramp) + /// or the ceiling changed; at rest, never. `true` once a bake ran. + /// + /// The precondition is "a frost EXISTS", not "the page is held": a closing menu is served the stale + /// frost while its dim ramps down, and every frame of that ramp owes a bake. + pub fn frost_bake_owed(&mut self, dim: Option, knee: f32, ceiling: f32) -> bool { + if self.frost == 0 || self.frost_rect[2] <= 0 || self.frost_off || self.off { + return false; + } + let cap = frost_cap_uniform(knee, ceiling); + let key = BodyKey::of(self.frost_key, self.frost_rect, dim, cap); + if self.body_key == Some(key) { + return false; + } + if blur_source_pass() || backdrop::discovering() || unsafe { LIVE_SCISSOR }.is_some() { + return false; + } + if video_plane_refuses("FrameCache::frost_bake_owed") { + return false; + } + let Some((_, _, bake)) = (unsafe { std::ptr::addr_of!(GLASS_FROST).read() }) else { return false }; + let ok = profile::phase("glass.bake", || unsafe { self.bake_passes(&bake, dim, cap) }); + if ok { + self.body_key = Some(key); + } else { + self.frost_off = true; + self.body_key = None; + log("frost: body bake failed — menus keep the field ground"); + } + ok + } + + /// The bake's one pass: the frost into the body target with `fs_frost_bake.frag`, the quad's flip + /// undone by the program's UV window so the body is stored the way the frost is ([`FROST_BOTTOM_UP`]), + /// which is the orientation every glass mapping already assumes. + unsafe fn bake_passes(&mut self, bake: &FrostBake, dim: Option, cap: [f32; 2]) -> bool { + let (w8, h8) = self.frost_dim; + if w8 <= 0 || h8 <= 0 { + return false; + } + while glGetError() != GL_NO_ERROR {} + if self.body == 0 || self.body_fbo == 0 { + delete_tex(self.body); + let Some((t, f)) = fbo_target(w8, h8, "frost") else { return false }; + (self.body, self.body_fbo) = (t, f); + } + glDisable(GL_BLEND); + use_prog(bake.prog); + glBindFramebuffer(GL_FRAMEBUFFER, self.body_fbo); + glViewport(0, 0, w8, h8); + glClear(GL_COLOR_BUFFER_BIT); + glUniform2f(bake.cap, cap[0], cap[1]); + match dim.filter(|d| d.tint[3] > 0.0) { + Some(d) => { + glUniform4f(bake.dim, d.tint[0], d.tint[1], d.tint[2], d.tint[3]); + let r = self.frost_rect; + let u = snapshot_to_screen([r[0] as f32, r[1] as f32, r[2] as f32, r[3] as f32], [1.0, 1.0], FROST_BOTTOM_UP); + glUniform4f(bake.dim_uv, u[0], u[1], u[2], u[3]); + glUniform1f(bake.dim_field, if d.tex != 0 { 1.0 } else { 0.0 }); + if d.tex != 0 { + glActiveTexture(GL_TEXTURE3); + glBindTexture(GL_TEXTURE_2D, d.tex); + glActiveTexture(GL_TEXTURE0); + } + } + None => { + glUniform4f(bake.dim, 0.0, 0.0, 0.0, 0.0); + glUniform1f(bake.dim_field, 0.0); + } } + note_px(Class::Blur, (w8 as f64) * (h8 as f64)); + glBindTexture(GL_TEXTURE_2D, self.frost); + glDrawArrays(GL_TRIANGLE_STRIP, 0, 4, straighten::Extent::Target); + glBindFramebuffer(GL_FRAMEBUFFER, plx_base::surface::default_fb()); + let (vx, vy, vw, vh) = plx_base::surface::viewport(); + glViewport(vx, vy, vw, vh); + glEnable(GL_BLEND); + glGetError() == GL_NO_ERROR + } + + /// The chain: the snapshot's window to 1/4 (four taps one authored px out: the exact 4x4 box), + /// to 1/8 (one bilinear tap on the shared corner: the 2x2 box), then [`FROST_TAPS`] at 1/8. The + /// last pass lands in the retained texture; the scratch targets are given back. See + /// [`FROST_TAPS`] for sigma. Every pass is a full quad into an exactly-sized target with BPROG, the + /// live chain's own shader, so the orientation rule is [`blur_bottom_up`] of [`FROST_PASSES`]. + unsafe fn frost_passes(&mut self, want: [c_int; 4]) -> bool { + let [rx, ry, rw, rh] = want; + if rw < 8 || rh < 8 || rw % 8 != 0 || rh % 8 != 0 { + return false; + } + let ((w4, h4), (w8, h8)) = ((rw / 4, rh / 4), (rw / 8, rh / 8)); + while glGetError() != GL_NO_ERROR {} + if self.frost == 0 || self.frost_dim != (w8, h8) { + self.release_frost(); + let Some((t, f)) = fbo_target(w8, h8, "frost") else { return false }; + (self.frost, self.frost_fbo, self.frost_dim) = (t, f, (w8, h8)); + } + let Some((t4, f4)) = fbo_target(w4, h4, "frost") else { return false }; + let Some((ts, fs)) = fbo_target(w8, h8, "frost") else { + glDeleteFramebuffers(1, &f4); + delete_tex(t4); + return false; + }; + glDisable(GL_BLEND); + use_prog(BPROG); + let pass = |fbo: c_uint, src: c_uint, w: c_int, h: c_int, uv: [f32; 4], texel: [f32; 2]| { + glBindFramebuffer(GL_FRAMEBUFFER, fbo); + glViewport(0, 0, w, h); + glClear(GL_COLOR_BUFFER_BIT); + glUniform4f(BL_UVRECT, uv[0], uv[1], uv[2], uv[3]); + glUniform2f(BL_TEXEL, texel[0], texel[1]); + note_px(Class::Blur, (w as f64) * (h as f64)); + glBindTexture(GL_TEXTURE_2D, src); + glDrawArrays(GL_TRIANGLE_STRIP, 0, 4, straighten::Extent::Target); + }; + // The snapshot is bottom-up: the region's bottom edge sits at v = 1 - (y + h) / H. + let win = [rx as f32 / SCR_W, 1.0 - (ry + rh) as f32 / SCR_H, rw as f32 / SCR_W, rh as f32 / SCR_H]; + pass(f4, self.tex, w4, h4, win, [1.0 / SCR_W, 1.0 / SCR_H]); + pass(self.frost_fbo, t4, w8, h8, [0.0, 0.0, 1.0, 1.0], [0.0, 0.0]); + let (d1, d2) = (FROST_TAPS[0], FROST_TAPS[1]); + pass(fs, self.frost, w8, h8, [0.0, 0.0, 1.0, 1.0], [d1 / w8 as f32, d1 / h8 as f32]); + pass(self.frost_fbo, ts, w8, h8, [0.0, 0.0, 1.0, 1.0], [d2 / w8 as f32, d2 / h8 as f32]); + glBindFramebuffer(GL_FRAMEBUFFER, plx_base::surface::default_fb()); + let (vx, vy, vw, vh) = plx_base::surface::viewport(); + glViewport(vx, vy, vw, vh); + glEnable(GL_BLEND); + glDeleteFramebuffers(1, &f4); + glDeleteFramebuffers(1, &fs); + delete_tex(t4); + delete_tex(ts); + glGetError() == GL_NO_ERROR } /// Copy the framebuffer into the retained second slot. `false` (nothing retained) in a blur @@ -3983,6 +4254,7 @@ impl FrameCache { self.valid = false; self.checked = false; self.region = [0; 4]; + self.release_frost(); } /// Draw the second slot across the canvas at `alpha`, over what is drawn so far. @@ -4248,7 +4520,8 @@ impl FrameCache { pub fn resident_bytes(&self) -> usize { let one = |t: c_uint, w: c_int, h: c_int| if t == 0 { 0 } else { w as usize * h as usize * 4 }; - one(self.tex, self.w, self.h) + one(self.prev, self.prev_w, self.prev_h) + one(self.tex, self.w, self.h) + one(self.prev, self.prev_w, self.prev_h) + one(self.frost, self.frost_dim.0, self.frost_dim.1) + + one(self.body, self.frost_dim.0, self.frost_dim.1) } /// Draw the cached viewport across the authored canvas. A framebuffer copy is bottom-up; @@ -5430,52 +5703,249 @@ fn chamfer() -> ([f32; 4], [f32; 3]) { } static mut GPROG: c_uint = 0; -static mut GL_RECT: c_int = 0; -static mut GL_SCREEN: c_int = 0; -static mut GL_UVRECT: c_int = 0; -static mut GL_TEX: c_int = 0; -static mut GL_TINT: c_int = 0; -static mut GL_RADIUS: c_int = 0; -static mut GL_CH: c_int = 0; -static mut GL_UVPX: c_int = 0; -static mut GL_BEVEL: c_int = 0; -static mut GL_LENS: c_int = 0; -static mut GL_EDGE: c_int = 0; -static mut GL_LIGHT: c_int = 0; -static mut GL_SPEC: c_int = 0; -static mut GL_DITHER_AMT: c_int = 0; -static mut GL_SCRIM_TOP: c_int = 0; -static mut GL_SCRIM_BOT: c_int = 0; -static mut GL_RIMCOL_G: c_int = 0; -static mut GL_RIMLIT_G: c_int = 0; -static mut GL_RIMW_G: c_int = 0; -static mut GL_SHARP: c_int = 0; -static mut GL_SHARP_RECT: c_int = 0; -static mut GL_SHARP_PX: c_int = 0; -static mut GL_SHARPW: c_int = 0; -static mut GL_RIMCLEAR: c_int = 0; -/// `u_boff`, `u_mrg`, `u_mrg_rk`, `u_mrg_tint`, `u_clear`: a morphing menu glass's join, the colour -/// the joined shape wears and its clarity ([`GlassMorph`]). Uniforms are per-program state, so EVERY -/// draw of `GPROG` sets them: the ones at their off values (no offset, `k` 0, tint amount 0, clear 0) -/// are today's glass. -static mut GL_BOFF: c_int = 0; -static mut GL_MRG: c_int = 0; -static mut GL_MRG_RK: c_int = 0; -static mut GL_MRG_TINT: c_int = 0; -static mut GL_CLEAR: c_int = 0; -static mut GL_DEEP: c_int = 0; -static mut GL_SOURCE_ALPHA: c_int = 0; -static mut GL_SOURCE_GROUND: c_int = 0; -static mut GL_DIM: c_int = 0; -static mut GL_DIM_UV: c_int = 0; -static mut GL_DIM_FIELD: c_int = 0; -static mut GL_DIM_TEX: c_int = 0; -static mut GL_DIM_SHARP: c_int = 0; -static mut GL_WASH_ON: c_int = 0; -static mut GL_WASH_UV: c_int = 0; -/// `u_wash_tl`, `u_wash_tr`, `u_wash_br`, `u_wash_bl`. -static mut GL_WASH_K: [c_int; 4] = [0; 4]; -static mut GL_WASH_W: c_int = 0; + +/// The glass program's uniform locations ([`FS_GLASS`] behind [`VS_IMG_DITHERED`]): one `Copy` struct, +/// so the FROST variant ([`GLASS_FROST`], the same source behind `PLX_FROST`) carries its own — two +/// programs linked from one source are not promised the same locations. Obtained by value +/// from [`glass_program`] and nowhere else, which binds the program the draw calls for. The same +/// shape as [`RectUniforms`]; `-1` is a location GL ignores. +/// +/// `boff`, `mrg`, `mrg_rk`, `mrg_tint`, `clear`: a morphing menu glass's join, the colour the joined +/// shape wears and the clarity ([`GlassMorph`]: a morphing menu sets only the join, its clarity is +/// always 0; clarity 1 is the profile chip's lift on the host snapshot). Uniforms are per-program +/// state, so EVERY draw of a glass program sets them: the ones at their off values (no offset, `k` 0, +/// tint amount 0, clear 0) are today's glass. `wash_k` is `u_wash_tl`, `u_wash_tr`, `u_wash_br`, `u_wash_bl`. +#[derive(Clone, Copy)] +struct GlassUniforms { + rect: c_int, + screen: c_int, + uvrect: c_int, + tex: c_int, + tint: c_int, + radius: c_int, + ch: c_int, + uvpx: c_int, + bevel: c_int, + lens: c_int, + edge: c_int, + light: c_int, + spec: c_int, + scrim_top: c_int, + scrim_bot: c_int, + rimcol: c_int, + rimlit: c_int, + rimw: c_int, + sharp: c_int, + sharp_rect: c_int, + sharp_px: c_int, + sharpw: c_int, + rimclear: c_int, + boff: c_int, + mrg: c_int, + mrg_rk: c_int, + mrg_tint: c_int, + clear: c_int, + deep: c_int, + source_alpha: c_int, + source_ground: c_int, + dim: c_int, + dim_uv: c_int, + dim_field: c_int, + dim_tex: c_int, + dim_sharp: c_int, + wash_on: c_int, + wash_uv: c_int, + wash_w: c_int, + dither_amt: c_int, + wash_k: [c_int; 4], +} + +impl GlassUniforms { + const NONE: GlassUniforms = GlassUniforms { + rect: 0, + screen: 0, + uvrect: 0, + tex: 0, + tint: 0, + radius: 0, + ch: 0, + uvpx: 0, + bevel: 0, + lens: 0, + edge: 0, + light: 0, + spec: 0, + scrim_top: 0, + scrim_bot: 0, + rimcol: 0, + rimlit: 0, + rimw: 0, + sharp: 0, + sharp_rect: 0, + sharp_px: 0, + sharpw: 0, + rimclear: 0, + boff: 0, + mrg: 0, + mrg_rk: 0, + mrg_tint: 0, + clear: 0, + deep: 0, + source_alpha: 0, + source_ground: 0, + dim: 0, + dim_uv: 0, + dim_field: 0, + dim_tex: 0, + dim_sharp: 0, + wash_on: 0, + wash_uv: 0, + wash_w: 0, + dither_amt: 0, + wash_k: [0; 4], + }; + + /// Look every location up in `program`, and give it its dither tile (`u_dither_tex` on unit 2). + unsafe fn of(program: c_uint) -> GlassUniforms { + let loc = |name: &CStr| glGetUniformLocation(program, name.as_ptr()); + GlassUniforms { + rect: loc(c"u_trect"), + screen: loc(c"u_tscreen"), + uvrect: loc(c"u_uvrect"), + tex: loc(c"u_tex"), + tint: loc(c"u_tint"), + radius: loc(c"u_iradius"), + ch: loc(c"u_ch"), + uvpx: loc(c"u_uvpx"), + bevel: loc(c"u_bevel"), + lens: loc(c"u_lens"), + edge: loc(c"u_edge"), + light: loc(c"u_light"), + spec: loc(c"u_spec"), + scrim_top: loc(c"u_scrim_top"), + scrim_bot: loc(c"u_scrim_bot"), + rimcol: loc(c"u_rimcol"), + rimlit: loc(c"u_rimlit"), + rimw: loc(c"u_rimw"), + sharp: loc(c"u_sharp"), + sharp_rect: loc(c"u_sharp_rect"), + sharp_px: loc(c"u_sharp_px"), + sharpw: loc(c"u_sharpw"), + rimclear: loc(c"u_rimclear"), + boff: loc(c"u_boff"), + mrg: loc(c"u_mrg"), + mrg_rk: loc(c"u_mrg_rk"), + mrg_tint: loc(c"u_mrg_tint"), + clear: loc(c"u_clear"), + deep: loc(c"u_deep"), + source_alpha: loc(c"u_source_alpha"), + source_ground: loc(c"u_source_ground"), + dim: loc(c"u_dim"), + dim_uv: loc(c"u_dim_uv"), + dim_field: loc(c"u_dim_field"), + dim_tex: loc(c"u_dim_tex"), + dim_sharp: loc(c"u_dim_sharp"), + wash_on: loc(c"u_wash_on"), + wash_uv: loc(c"u_wash_uv"), + wash_w: loc(c"u_wash_w"), + dither_amt: dither_uniforms(program), + wash_k: [c"u_wash_tl", c"u_wash_tr", c"u_wash_br", c"u_wash_bl"].map(loc), + } + } + + /// The constants a glass program holds for life, set once at link (uniforms are per-program + /// state, so none of THESE belongs in the draw): the screen, the snapshot on unit 0, the dim's + /// field on unit 3 (0 is the snapshot, 1 the sharp grab, 2 the dither tile; bound per draw, and + /// only by a draw that owes a field dim), the rim's second source on unit 1 (only the texture + /// bound there changes, and only when a chain is rebuilt), and the material constants. `u_bevel` + /// and `u_lens` are the exception and are set per draw — see [`GlassRim`], which is the one thing + /// a surface gets to say about the material. `uvpx` is NOT set here: the snapshot is a REGION and + /// that ratio moves with it, so it belongs to the draw (`draw_blur_backdrop` says what goes wrong + /// if it is left behind). + unsafe fn init(&self, program: c_uint) { + use_prog(program); + glUniform2f(self.screen, SCR_W, SCR_H); + glUniform1i(self.tex, 0); + glUniform1i(self.dim_tex, 3); + glUniform1i(self.sharp, 1); + let (edge, light) = chamfer(); + glUniform4fv(self.edge, 1, edge.as_ptr()); + glUniform3f(self.light, light[0], light[1], light[2]); + } +} + +/// [`GPROG`]'s locations, written once at [`blur_lazy_init`]. +static mut GLASS_UNIFORMS: GlassUniforms = GlassUniforms::NONE; +/// The glass program for a FROSTED BODY ([`FS_GLASS_FROST`]: `fs_glass.frag` behind +/// `PLX_FROST`), linked at boot beside the plain one so the first menu open pays no compile hitch. +/// Bound by [`glass_program`] only for a draw that has a [`GlassFrost`]; `None` (a driver that +/// refused it) leaves every glass surface on [`GPROG`], and [`glass_frost_linked`] tells the frost's +/// owner not to build a frost nobody can draw. +static mut GLASS_FROST: Option<(c_uint, GlassUniforms, FrostBake)> = None; + +/// **The frost's body bake program** (`fs_frost_bake.frag` on [`VS_IMG`], the blur chain's own vertex +/// half) and its locations, linked with [`GLASS_FROST`]'s variant and part of the same optional unit: a +/// driver that refuses either leaves menus the field ground, since the variant's composite no longer +/// dims or caps the body itself. +#[derive(Clone, Copy)] +struct FrostBake { + prog: c_uint, + trect: c_int, + tscreen: c_int, + uvrect: c_int, + dim: c_int, + dim_uv: c_int, + dim_field: c_int, + cap: c_int, +} + +impl FrostBake { + /// Link the bake and set its per-program constants (the full-target quad, its samplers' units). + unsafe fn link() -> Option { + let prog = link_optional_program(VS_IMG.as_ptr(), FS_FROST_BAKE.as_ptr())?; + let loc = |n: &CStr| glGetUniformLocation(prog, n.as_ptr()); + let b = Self { + prog, + trect: loc(c"u_trect"), + tscreen: loc(c"u_tscreen"), + uvrect: loc(c"u_uvrect"), + dim: loc(c"u_dim"), + dim_uv: loc(c"u_dim_uv"), + dim_field: loc(c"u_dim_field"), + cap: loc(c"u_frost_cap"), + }; + use_prog(prog); + glUniform1i(loc(c"u_tex"), 0); + glUniform1i(loc(c"u_dim_tex"), 3); + glUniform2f(b.tscreen, SCR_W, SCR_H); + glUniform4f(b.trect, 0.0, 0.0, SCR_W, SCR_H); + // The frost texel's own UV with the quad's flip undone: the body is stored the way the frost is. + glUniform4f(b.uvrect, 0.0, 1.0, 1.0, -1.0); + Some(b) + } +} + +/// **The glass program for this draw, bound, with its uniform locations**, and whether it is the +/// frost variant: the variant when `frost` asks for it and it linked, else the plain program. The +/// ONLY way a draw obtains the glass program's locations (a draw that wrote the plain program's +/// locations while the variant is bound would be a silent miss). +#[inline] +unsafe fn glass_program(frost: bool) -> (GlassUniforms, bool) { + if frost { + if let Some((program, u, _)) = std::ptr::addr_of!(GLASS_FROST).read() { + use_prog(program); + return (u, true); + } + } + use_prog(GPROG); + (std::ptr::addr_of!(GLASS_UNIFORMS).read(), false) +} + +/// Is the glass program's frost variant linked? A menu's frost is only built when it is +/// ([`FrameCache::frost_possible`]); without the variant menus keep the field look and its face. +pub fn glass_frost_linked() -> bool { + unsafe { std::ptr::addr_of!(GLASS_FROST).read().is_some() } +} /// Invalidate the scratch snapshot used by the synthetic load dial and navigation experiments. /// Live surfaces own separate retained outputs through the frame's layer/region registry. @@ -5781,68 +6251,20 @@ fn blur_lazy_init() -> bool { return false; } }; - GL_RECT = glGetUniformLocation(GPROG, c"u_trect".as_ptr()); - GL_SCREEN = glGetUniformLocation(GPROG, c"u_tscreen".as_ptr()); - GL_UVRECT = glGetUniformLocation(GPROG, c"u_uvrect".as_ptr()); - GL_TEX = glGetUniformLocation(GPROG, c"u_tex".as_ptr()); - GL_TINT = glGetUniformLocation(GPROG, c"u_tint".as_ptr()); - GL_RADIUS = glGetUniformLocation(GPROG, c"u_iradius".as_ptr()); - GL_CH = glGetUniformLocation(GPROG, c"u_ch".as_ptr()); - GL_UVPX = glGetUniformLocation(GPROG, c"u_uvpx".as_ptr()); - GL_BEVEL = glGetUniformLocation(GPROG, c"u_bevel".as_ptr()); - GL_LENS = glGetUniformLocation(GPROG, c"u_lens".as_ptr()); - GL_EDGE = glGetUniformLocation(GPROG, c"u_edge".as_ptr()); - GL_LIGHT = glGetUniformLocation(GPROG, c"u_light".as_ptr()); - GL_SPEC = glGetUniformLocation(GPROG, c"u_spec".as_ptr()); - GL_DITHER_AMT = dither_uniforms(GPROG); - GL_SCRIM_TOP = glGetUniformLocation(GPROG, c"u_scrim_top".as_ptr()); - GL_SCRIM_BOT = glGetUniformLocation(GPROG, c"u_scrim_bot".as_ptr()); - GL_RIMCOL_G = glGetUniformLocation(GPROG, c"u_rimcol".as_ptr()); - GL_RIMLIT_G = glGetUniformLocation(GPROG, c"u_rimlit".as_ptr()); - GL_RIMW_G = glGetUniformLocation(GPROG, c"u_rimw".as_ptr()); - GL_SHARP = glGetUniformLocation(GPROG, c"u_sharp".as_ptr()); - GL_SHARP_RECT = glGetUniformLocation(GPROG, c"u_sharp_rect".as_ptr()); - GL_SHARP_PX = glGetUniformLocation(GPROG, c"u_sharp_px".as_ptr()); - GL_SHARPW = glGetUniformLocation(GPROG, c"u_sharpw".as_ptr()); - GL_RIMCLEAR = glGetUniformLocation(GPROG, c"u_rimclear".as_ptr()); - GL_BOFF = glGetUniformLocation(GPROG, c"u_boff".as_ptr()); - GL_MRG = glGetUniformLocation(GPROG, c"u_mrg".as_ptr()); - GL_MRG_RK = glGetUniformLocation(GPROG, c"u_mrg_rk".as_ptr()); - GL_MRG_TINT = glGetUniformLocation(GPROG, c"u_mrg_tint".as_ptr()); - GL_CLEAR = glGetUniformLocation(GPROG, c"u_clear".as_ptr()); - GL_DEEP = glGetUniformLocation(GPROG, c"u_deep".as_ptr()); - GL_SOURCE_ALPHA = glGetUniformLocation(GPROG, c"u_source_alpha".as_ptr()); - GL_SOURCE_GROUND = glGetUniformLocation(GPROG, c"u_source_ground".as_ptr()); - GL_DIM = glGetUniformLocation(GPROG, c"u_dim".as_ptr()); - GL_DIM_UV = glGetUniformLocation(GPROG, c"u_dim_uv".as_ptr()); - GL_DIM_FIELD = glGetUniformLocation(GPROG, c"u_dim_field".as_ptr()); - GL_DIM_TEX = glGetUniformLocation(GPROG, c"u_dim_tex".as_ptr()); - GL_DIM_SHARP = glGetUniformLocation(GPROG, c"u_dim_sharp".as_ptr()); - GL_WASH_ON = glGetUniformLocation(GPROG, c"u_wash_on".as_ptr()); - GL_WASH_UV = glGetUniformLocation(GPROG, c"u_wash_uv".as_ptr()); - GL_WASH_K = [c"u_wash_tl", c"u_wash_tr", c"u_wash_br", c"u_wash_bl"] - .map(|name| glGetUniformLocation(GPROG, name.as_ptr())); - GL_WASH_W = glGetUniformLocation(GPROG, c"u_wash_w".as_ptr()); - use_prog(GPROG); - glUniform2f(GL_SCREEN, SCR_W, SCR_H); - glUniform1i(GL_TEX, 0); - // The composite-time dim's field, on unit 3 (0 is the snapshot, 1 the sharp grab, 2 the - // dither tile). Bound per draw, and only by a draw that owes a field dim. - glUniform1i(GL_DIM_TEX, 3); - // The rim's second source lives on unit 1 for the life of the program; only the texture - // bound there changes, and only when a chain is rebuilt. - glUniform1i(GL_SHARP, 1); - // Material constants and the orientation term: fixed for the life of the process, and - // uniforms are per-program state, so none of THESE belongs in the draw. `u_bevel`/`u_lens` - // are the exception and are set per draw — see [`GlassRim`], which is the one thing a - // surface gets to say about the material. - let (edge, light) = chamfer(); - glUniform4fv(GL_EDGE, 1, edge.as_ptr()); - glUniform3f(GL_LIGHT, light[0], light[1], light[2]); - // `GL_UVPX` is NOT set here. It was, back when the grab was always the whole screen and one - // authored pixel was therefore always `1/SCR_W` of the texture — but the snapshot is a - // REGION now and that ratio moves with it, so it belongs to the draw. `draw_blur_backdrop` - // says what goes wrong if it is left behind. + let plain = GlassUniforms::of(GPROG); + plain.init(GPROG); + GLASS_UNIFORMS = plain; + // The same source behind `PLX_FROST`, for the menus' frosted body. Optional: a compiler that + // refuses the variant must cost the menus their frost and not every glass surface its program. + GLASS_FROST = link_optional_program(VS_IMG_DITHERED.as_ptr(), FS_GLASS_FROST.as_ptr()).and_then(|program| { + let bake = FrostBake::link()?; + let u = GlassUniforms::of(program); + u.init(program); + Some((program, u, bake)) + }); + if !glass_frost_linked() { + log("glass frost prog unavailable — menus keep the field ground and the heavier face"); + } use_prog(PROG); let (gx, gy, gw, gh) = plx_base::surface::viewport(); @@ -7620,8 +8042,10 @@ pub struct GlassMerge { /// **What a menu glass does while its morph runs** (`ui::popover_morph::Frame`): optionally JOINED /// to a second shape ([`GlassMerge`]) and CLEAR — the sharp page over the whole face instead of the -/// frosted material. [`GlassMorph::NONE`] (no join, clarity 0) is the glass every settled menu and -/// every chip wears, bit for bit. +/// frosted material. A morphing menu is joined but never clear (its body is the frost on every frame, +/// `ui::popover_morph`); clarity is the opener chip's lift on the host snapshot, before the field +/// latches (`ui::widgets::LiftGround::Snapshot`). [`GlassMorph::NONE`] (no join, clarity 0) is the glass +/// every settled menu and every chip wears, bit for bit. #[derive(Clone, Copy, Debug, PartialEq)] pub struct GlassMorph { pub merge: Option, @@ -7646,6 +8070,98 @@ impl GlassMorph { } } +/// **A menu's FROST** (`ui::popover::host`'s retained blur of its frozen page, [`FrameCache::frost_read`]): +/// the texture the glass body shows INSTEAD of the latched field ground, the canvas rect it holds, +/// and the body's brightness ceiling. [`GlassFrost::NONE`] (`tex` 0) is the field ground, bit for bit. +/// +/// The texture is the region's own, [`FROST_PASSES`] flips from the bottom-up snapshot it was drawn from +/// ([`FROST_BOTTOM_UP`]); the glass samples it through a UV window ([`blur_uv_rect`]) and +/// `CLAMP_TO_EDGE` is what a fragment of the (rare) overshoot past the region reads, which is the +/// region's edge texel, so the body never goes black or wraps. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct GlassFrost { + pub tex: c_uint, + /// The canvas rect `tex` holds, authored px `[x, y, w, h]`, top-down. + pub rect: [f32; 4], + /// The body's soft knee: the brightest channel below this is untouched. + pub knee: f32, + /// The hard ceiling no body channel reaches (`ui::theme::FROST_BODY_CEILING`); 0 = no cap. + pub ceiling: f32, + /// The snapshot epoch the frost was built from: a rebuild into the same texture is a different draw. + pub rev: u32, +} +impl GlassFrost { + pub const NONE: Self = Self { tex: 0, rect: [0.0; 4], knee: 0.0, ceiling: 0.0, rev: 0 }; + /// `(knee, headroom)` of `fs_frost_bake.frag`'s `u_frost_cap`: `y = knee + headroom * o / (o + headroom)` + /// above the knee, `o = m - knee`. Slope 1 at the knee and never the ceiling, so a body of 1.0 + /// lands just under it. `[0, 0]` = no cap. + fn cap_uniform(&self) -> [f32; 2] { + if self.tex == 0 { [0.0, 0.0] } else { frost_cap_uniform(self.knee, self.ceiling) } + } + /// The same cap on one body channel, for host tests (the shader's rule on its brightest channel). + pub fn cap(&self, m: f32) -> f32 { + let [k, d] = self.cap_uniform(); + if d <= 0.0 { return m; } + let o = (m - k).max(0.0); + m.min(k) + d * (o / (o + d)) + } +} + +/// `(knee, headroom)` of `fs_frost_bake.frag`'s `u_frost_cap` for a body ceiling: `[0, 0]` (no cap) when +/// the ceiling is not above the knee or the knee is not below 1. Pure. +pub fn frost_cap_uniform(knee: f32, ceiling: f32) -> [f32; 2] { + let d = ceiling - knee; + if ceiling <= 0.0 || d <= 0.0 || knee >= 1.0 { + return [0.0, 0.0]; + } + [knee, d] +} + +/// **What a frost body was baked from**: when this equals the key of a bake that is due, the body +/// texture is still right and nothing runs. `frost` is the snapshot epoch the blur was built from, `rect` +/// its region, `dim` the modal dim applied (its field texture, that texture's content revision and the +/// tint's bits), `cap` the ceiling's `(knee, headroom)` bits. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +struct BodyKey { + frost: u32, + rect: [c_int; 4], + dim: Option<(u32, u64, [u32; 4])>, + cap: [u32; 2], +} + +impl BodyKey { + /// The dim's share of the key: none for no dim (or a transparent one), else its field texture, that + /// texture's content revision (a field re-latched in place is a different ink) and its tint's bits. + fn dim_key(dim: Option) -> Option<(u32, u64, [u32; 4])> { + dim.filter(|d| d.tint[3] > 0.0).map(|d| (d.tex, tex_ledger::revision(d.tex), d.tint.map(f32::to_bits))) + } + fn of(frost: u32, rect: [c_int; 4], dim: Option, cap: [f32; 2]) -> Self { + Self { frost, rect, dim: Self::dim_key(dim), cap: cap.map(f32::to_bits) } + } +} + +/// Passes the frost's chain runs from the bottom-up page snapshot: 1/4, 1/8, then two Kawase taps. +const FROST_PASSES: usize = 4; +/// Is the retained frost stored bottom-up? The parity of [`FROST_PASSES`], as the live chain reads its own. +const FROST_BOTTOM_UP: bool = blur_bottom_up(FROST_PASSES); +/// The two Kawase offsets at the frost's 1/8 resolution, in texels. Per axis a pass at offset `d` +/// has variance `d^2 + 1/4` (four bilinear taps on the diagonals), so `[1.5, 2.5]` give +/// `2.5 + 6.5 = 9` texel^2: sigma 3 texels = 24 px at 1/8, the Gaussian the owner approved. +const FROST_TAPS: [f32; 2] = [1.5, 2.5]; +/// How far past a menu's settled panel the frost's region reaches, authored px (a multiple of 8): +/// 72 (3 sigma, where the clamped region edge stops mattering) plus the lens' push and a morph's overshoot. +pub const FROST_MARGIN: f32 = 120.0; + +/// The frost's region for a settled panel `[x, y, w, h]`: grown by [`FROST_MARGIN`], clamped to the +/// canvas and aligned OUT to multiples of 8, so every 1/8 texel is whole authored pixels. Pure. +pub fn frost_region(panel: [f32; 4]) -> [c_int; 4] { + let lo = |v: f32, max: f32| ((v - FROST_MARGIN).max(0.0).min(max) / 8.0).floor() as c_int * 8; + let hi = |v: f32, max: f32| (((v + FROST_MARGIN).min(max).max(0.0)) / 8.0).ceil() as c_int * 8; + let (x0, y0) = (lo(panel[0], SCR_W), lo(panel[1], SCR_H)); + let (x1, y1) = (hi(panel[0] + panel[2], SCR_W), hi(panel[1] + panel[3], SCR_H)); + [x0, y0, (x1 - x0).max(0), (y1 - y0).max(0)] +} + /// **Snapshot UV back to the screen**: `(su, sv, ou, ov)` with `screen_uv = uv * (su, sv) + (ou, ov)` /// over the whole canvas, top-down — `blur_uv_rect` inverted, for the region `reg` the snapshot holds /// in a window of `span` of its texture. Both composite-time terms that live on the page (the dim's @@ -7765,13 +8281,13 @@ pub fn draw_blur_backdrop( (c.rh / 2) as f32 / c.mh as f32, ]; let uv = blur_uv_rect(x, y, w, h, c.reg, span, c.bottom_up); - use_prog(GPROG); + let (gu, _) = glass_program(false); let source_alpha = if retained.as_ref().is_some_and(|image| image.alpha_invariant) { live.and_then(|request| backdrop::source_alpha(request.z)).unwrap_or(1.0) } else { 1.0 }; let ground = tokens::CLEAR_RGB; - glUniform1f(GL_SOURCE_ALPHA, source_alpha); - glUniform3f(GL_SOURCE_GROUND, ground.0, ground.1, ground.2); + glUniform1f(gu.source_alpha, source_alpha); + glUniform3f(gu.source_ground, ground.0, ground.1, ground.2); // THE MODAL DIM, at composite. A band whose dim is the last draw under it filters the // UNDIMMED prefix once (`backdrop::dim_deferred` skipped the dim in the replay) and takes // this frame's dim here, in `srcRGB`, before the sharp rim mix — the sharp grab is off the @@ -7785,17 +8301,17 @@ pub fn draw_blur_backdrop( }; match dim { Some(d) if d.tint[3] > 0.0 => { - glUniform4f(GL_DIM, d.tint[0], d.tint[1], d.tint[2], d.tint[3]); - glUniform1f(GL_DIM_FIELD, if d.tex != 0 { 1.0 } else { 0.0 }); + glUniform4f(gu.dim, d.tint[0], d.tint[1], d.tint[2], d.tint[3]); + glUniform1f(gu.dim_field, if d.tex != 0 { 1.0 } else { 0.0 }); if d.tex != 0 { let [su, sv, ou, ov] = snapshot_to_screen(c.reg, span, c.bottom_up); - glUniform4f(GL_DIM_UV, su, sv, ou, ov); + glUniform4f(gu.dim_uv, su, sv, ou, ov); glActiveTexture(GL_TEXTURE3); glBindTexture(GL_TEXTURE_2D, d.tex); glActiveTexture(GL_TEXTURE0); } } - _ => glUniform4f(GL_DIM, 0.0, 0.0, 0.0, 0.0), + _ => glUniform4f(gu.dim, 0.0, 0.0, 0.0, 0.0), } // THE PAGE WASH, as a delta, in the same slot of the same expression (`backdrop::Ground`): // the image keeps the wash it was drawn under and the composite owes this frame's @@ -7808,29 +8324,29 @@ pub fn draw_blur_backdrop( let [rx, ry, rw, rh] = d.rect; // Snapshot UV -> screen UV (0..1 over the canvas) -> the wash's own frame. let (kx, ky) = (SCR_W / rw.max(1.0), SCR_H / rh.max(1.0)); - glUniform1f(GL_WASH_ON, 1.0); - glUniform4f(GL_WASH_UV, su * kx, sv * ky, ou * kx - rx / rw.max(1.0), ov * ky - ry / rh.max(1.0)); - for (loc, k) in (*std::ptr::addr_of!(GL_WASH_K)).iter().zip(d.corners) { + glUniform1f(gu.wash_on, 1.0); + glUniform4f(gu.wash_uv, su * kx, sv * ky, ou * kx - rx / rw.max(1.0), ov * ky - ry / rh.max(1.0)); + for (loc, k) in gu.wash_k.iter().zip(d.corners) { glUniform3f(*loc, k[0], k[1], k[2]); } - glUniform2f(GL_WASH_W, d.weight[0], d.weight[1]); + glUniform2f(gu.wash_w, d.weight[0], d.weight[1]); } - None => glUniform1f(GL_WASH_ON, 0.0), + None => glUniform1f(gu.wash_on, 0.0), } // The sharp grab below is off the finished framebuffer: the dim is in it already. - glUniform1f(GL_DIM_SHARP, 0.0); + glUniform1f(gu.dim_sharp, 0.0); // A live glass is never a morphing menu's: the join and the clear glass are OFF, so a // frozen menu's last draw (the uniforms are the program's) cannot reach this surface. - glUniform2f(GL_BOFF, 0.0, 0.0); - glUniform2f(GL_MRG_RK, 0.0, 0.0); - glUniform4f(GL_MRG_TINT, 0.0, 0.0, 0.0, 0.0); - glUniform1f(GL_CLEAR, 0.0); + glUniform2f(gu.boff, 0.0, 0.0); + glUniform2f(gu.mrg_rk, 0.0, 0.0); + glUniform4f(gu.mrg_tint, 0.0, 0.0, 0.0, 0.0); + glUniform1f(gu.clear, 0.0); // A BLUR is the slowest field the app produces, so the policy is the area test, per draw // — moving or not: a panel's glass is a fraction of the screen and the tile is one fetch, // and gating it on motion (one day, 2026-09-04) flickered the bands in and out on every // appear spring. It was `GLASS_NOISE` (½ LSB, uniform) feeding an unconditional sine // hash, then a constant set once at link. - glUniform1f(GL_DITHER_AMT, dither_for_field(w, h)); + glUniform1f(gu.dither_amt, dither_for_field(w, h)); glBindTexture(GL_TEXTURE_2D, c.out); // **Per DRAW, not per init.** This is the UV travelled by one authored screen pixel, and it // is what turns the lens's displacement (in px) into a texture offset. It was a boot-time @@ -7839,7 +8355,7 @@ pub fn draw_blur_backdrop( // the 38px lens would have silently become a ~15px one — the rim would still refract, just // less, with nothing anywhere to say so. glUniform2f( - GL_UVPX, + gu.uvpx, span[0] / c.reg[2], if c.bottom_up { -span[1] / c.reg[3] @@ -7915,10 +8431,10 @@ pub fn draw_blur_backdrop( glActiveTexture(GL_TEXTURE0); } let suv = blur_uv_rect(x, y, w, h, sreg, sspan, true); - glUniform4f(GL_SHARP_RECT, suv[0], suv[1], suv[2], suv[3]); - glUniform2f(GL_SHARP_PX, sspan[0] / sreg[2], -sspan[1] / sreg[3]); - glUniform1f(GL_SHARPW, sharpw); - glUniform1f(GL_RIMCLEAR, rim.rimclear()); + glUniform4f(gu.sharp_rect, suv[0], suv[1], suv[2], suv[3]); + glUniform2f(gu.sharp_px, sspan[0] / sreg[2], -sspan[1] / sreg[3]); + glUniform1f(gu.sharpw, sharpw); + glUniform1f(gu.rimclear, rim.rimclear()); // `deep` is authored px; the snapshot's own UV-per-authored-pixel is already in hand, and // its v may be negative, so the radius is taken on the ABSOLUTE step or the cross collapses // to a line on one axis. @@ -7926,7 +8442,7 @@ pub fn draw_blur_backdrop( // **BOTH axes, and it was one for a while.** The cross was offset by `vec2(d, d)` from the // U step alone, but an authored pixel is `1/SCR_W` of the texture across and `1/SCR_H` of it // down — so the four extra taps landed the full radius sideways and 56% of it vertically, - // and the "softer material" was squashed. `GL_UVPX` two lines up already computes the pair; + // and the "softer material" was squashed. `gu.uvpx` two lines up already computes the pair; // this is the same expression, rectified. The shader reads the ON/OFF state off `.x` now, // which is why there is no flag component left to carry. let dpx = if deep > 0.0 { @@ -7935,7 +8451,7 @@ pub fn draw_blur_backdrop( 0.0 }; glUniform2f( - GL_DEEP, + gu.deep, dpx * (span[0] / c.reg[2]).abs(), dpx * (span[1] / c.reg[3]).abs(), ); @@ -7947,19 +8463,19 @@ pub fn draw_blur_backdrop( glActiveTexture(GL_TEXTURE0); } let (bevel, lens, spec) = rim.params(); - glUniform1f(GL_BEVEL, bevel); - glUniform1f(GL_LENS, lens); - glUniform4fv(GL_SPEC, 1, spec.as_ptr()); - glUniform4fv(GL_TINT, 1, tint); - glUniform4fv(GL_SCRIM_TOP, 1, face.scrim_top.as_ptr()); - glUniform4fv(GL_SCRIM_BOT, 1, face.scrim_bot.as_ptr()); - glUniform4fv(GL_RIMCOL_G, 1, face.rim.as_ptr()); - glUniform4fv(GL_RIMLIT_G, 1, face.rim_lit.as_ptr()); - glUniform1f(GL_RIMW_G, face.rim_w); - glUniform4f(GL_UVRECT, uv[0], uv[1], uv[2], uv[3]); - glUniform1f(GL_RADIUS, radius); - glUniform2f(GL_CH, w * 0.5, h * 0.5); - let ext = set_rect(GL_RECT, x, y, w, h); + glUniform1f(gu.bevel, bevel); + glUniform1f(gu.lens, lens); + glUniform4fv(gu.spec, 1, spec.as_ptr()); + glUniform4fv(gu.tint, 1, tint); + glUniform4fv(gu.scrim_top, 1, face.scrim_top.as_ptr()); + glUniform4fv(gu.scrim_bot, 1, face.scrim_bot.as_ptr()); + glUniform4fv(gu.rimcol, 1, face.rim.as_ptr()); + glUniform4fv(gu.rimlit, 1, face.rim_lit.as_ptr()); + glUniform1f(gu.rimw, face.rim_w); + glUniform4f(gu.uvrect, uv[0], uv[1], uv[2], uv[3]); + glUniform1f(gu.radius, radius); + glUniform2f(gu.ch, w * 0.5, h * 0.5); + let ext = set_rect(gu.rect, x, y, w, h); profile::phase("glass.composite", || { glDrawArrays(GL_TRIANGLE_STRIP, 0, 4, ext); }); @@ -7971,18 +8487,22 @@ pub fn draw_blur_backdrop( /// [`draw_blur_backdrop`] (the face gradient, the rim, the lit edge, the lens), fed two pictures /// the frame already holds instead of a blur chain: `ground`, the latched underlay field /// (`ui::underlay`'s 60x32 reconstruction of the undimmed host page, mapped over the whole screen -/// top-down), as the backdrop the panel's body shows, and `sharp`, the host snapshot -/// (`ui::popover::host`'s one page-sized capture, bottom-up as [`FrameCache`] holds it), as the -/// rim's sharp source. Neither is taken here and neither is a function of this frame's page: +/// top-down), as the backdrop the panel's body shows (unless a `frost` stands in for it, below), and +/// `sharp`, the host snapshot (`ui::popover::host`'s one page-sized capture, bottom-up as +/// [`FrameCache`] holds it), as the rim's sharp source. Neither is taken here and neither is a function of this frame's page: /// nothing is copied off the framebuffer, no source pass runs and no backdrop entry is requested, /// so a menu standing over its host costs one panel quad however long it stands, and its morph or /// slide moves that quad over pictures that do not change. /// -/// Both pictures are UNDIMMED, so the modal dim the frame drew under the panel is applied to both -/// at composite (`dim`, the [`backdrop::Dim`] a glass over a live band applies the same way): -/// blur is linear and the dim's ink is a smooth field, so the panel shows the dimmed page it -/// stands on. `sharp` 0 draws the single-source material (the host holds no undimmed page this -/// frame). +/// Without a `frost`, both pictures are UNDIMMED, so the modal dim the frame drew under the panel +/// is applied to both at composite (`dim`, the [`backdrop::Dim`] a glass over a live band applies +/// the same way): blur is linear and the dim's ink is a smooth field, so the panel shows the dimmed +/// page it stands on. With a `frost` ([`GlassFrost`]: the host's retained blur of its page, on the +/// frost variant of the glass program) the body is that texture instead of `ground`, the BAKED body +/// ([`FrameCache::frost_bake_owed`]): already dimmed by the frame's lowest modal dim and held +/// under its ceiling, so the composite dims only `sharp` (`ground` is still required, and is the +/// body again when the frost variant did not link). `sharp` 0 draws the single-source material +/// (the host holds no undimmed page this frame). /// /// Returns whether the material was handled, a culled or `drawmask`ed quad included (as /// [`draw_field_panel`] answers). `false` — no glass program, no ground, a video-plane frame — @@ -8017,6 +8537,7 @@ pub fn draw_glass_frozen( rim: GlassRim, face: GlassFace, morph: GlassMorph, + frost: GlassFrost, ) -> bool { if ground == 0 || unsafe { GPROG } == 0 || unsafe { BLUR_OFF } { return false; @@ -8037,80 +8558,102 @@ pub fn draw_glass_frozen( return true; } unsafe { - use_prog(GPROG); - glUniform1f(GL_SOURCE_ALPHA, 1.0); + // The body's picture: the menu's FROST (a retained blur of its page, drawn through a UV + // window of its region) or the latched field. Unit 0 is whichever, so the dim's field is its + // own texture (mode 1) over a frost and the body's own texel (mode 2) over the field. Only a + // draw WITH a frost takes the frost variant of the glass program (the one that draws the + // baked body as it is); every other glass draw keeps the plain program, and a driver that + // refused the variant leaves a frost nobody can draw, so it falls back to the field here too. + let (gu, framed) = + glass_program(frost.tex != 0 && frost.rect[2] > 0.0 && frost.rect[3] > 0.0); + let body = if framed { frost.tex } else { ground }; + // A frost body is the BAKED texel (`FrameCache::frost_bake_owed`): its dim and its ceiling are in + // it, and the variant's composite carries neither. The dim set below is for the SHARP source + // (the rim band and the clear face), which is the undimmed page. + glUniform1f(gu.source_alpha, 1.0); let g = tokens::CLEAR_RGB; - glUniform3f(GL_SOURCE_GROUND, g.0, g.1, g.2); + glUniform3f(gu.source_ground, g.0, g.1, g.2); // `v_cuv` IS the screen point over the screen, top-down (the field's own mapping), so the // dim's field is read at `v_cuv` itself. match dim { Some(d) if d.tint[3] > 0.0 => { - glUniform4f(GL_DIM, d.tint[0], d.tint[1], d.tint[2], d.tint[3]); - let mode = frozen_dim_field(ground, d.tex); - glUniform1f(GL_DIM_FIELD, mode); + glUniform4f(gu.dim, d.tint[0], d.tint[1], d.tint[2], d.tint[3]); + let mode = frozen_dim_field(body, d.tex); + glUniform1f(gu.dim_field, mode); if mode == 1.0 { - glUniform4f(GL_DIM_UV, 1.0, 1.0, 0.0, 0.0); + let u = if framed { snapshot_to_screen(frost.rect, [1.0, 1.0], FROST_BOTTOM_UP) } else { [1.0, 1.0, 0.0, 0.0] }; + glUniform4f(gu.dim_uv, u[0], u[1], u[2], u[3]); glActiveTexture(GL_TEXTURE3); glBindTexture(GL_TEXTURE_2D, d.tex); glActiveTexture(GL_TEXTURE0); } } - _ => glUniform4f(GL_DIM, 0.0, 0.0, 0.0, 0.0), + _ => glUniform4f(gu.dim, 0.0, 0.0, 0.0, 0.0), } // A frozen page carries its wash in the snapshot: no delta (the uniform is the program's, // so the last live glass's `1` would otherwise stay). - glUniform1f(GL_WASH_ON, 0.0); - glUniform1f(GL_DIM_SHARP, if sharp != 0 { 1.0 } else { 0.0 }); - glUniform1f(GL_DITHER_AMT, dither_for_field(q.w, q.h)); - glBindTexture(GL_TEXTURE_2D, ground); - glUniform2f(GL_UVPX, 1.0 / SCR_W, 1.0 / SCR_H); + glUniform1f(gu.wash_on, 0.0); + glUniform1f(gu.dim_sharp, if sharp != 0 { 1.0 } else { 0.0 }); + glUniform1f(gu.dither_amt, dither_for_field(q.w, q.h)); + glBindTexture(GL_TEXTURE_2D, body); + if framed { + let sy = if FROST_BOTTOM_UP { -1.0 } else { 1.0 }; + glUniform2f(gu.uvpx, 1.0 / frost.rect[2], sy / frost.rect[3]); + } else { + glUniform2f(gu.uvpx, 1.0 / SCR_W, 1.0 / SCR_H); + } let sharpw = if sharp != 0 { rim.sharp() } else { 0.0 }; // The snapshot is the whole drawable, bottom-up: its window is the screen rect over the // screen, with the row order flipped (`frame_cache_uv`). let full = [0.0, 0.0, SCR_W, SCR_H]; let suv = blur_uv_rect(x, y, w, h, full, [1.0, 1.0], true); - glUniform4f(GL_SHARP_RECT, suv[0], suv[1], suv[2], suv[3]); - glUniform2f(GL_SHARP_PX, 1.0 / SCR_W, -1.0 / SCR_H); - glUniform1f(GL_SHARPW, sharpw); + glUniform4f(gu.sharp_rect, suv[0], suv[1], suv[2], suv[3]); + glUniform2f(gu.sharp_px, 1.0 / SCR_W, -1.0 / SCR_H); + glUniform1f(gu.sharpw, sharpw); glActiveTexture(GL_TEXTURE1); glBindTexture(GL_TEXTURE_2D, if sharp != 0 { sharp } else { ground }); glActiveTexture(GL_TEXTURE0); - glUniform1f(GL_RIMCLEAR, rim.rimclear()); + glUniform1f(gu.rimclear, rim.rimclear()); // The field is already the softest picture of the page there is: no deep cross. - glUniform2f(GL_DEEP, 0.0, 0.0); + glUniform2f(gu.deep, 0.0, 0.0); let (bevel, lens, spec) = rim.params(); - glUniform1f(GL_BEVEL, bevel); - glUniform1f(GL_LENS, lens); - glUniform4fv(GL_SPEC, 1, spec.as_ptr()); - glUniform4fv(GL_TINT, 1, tint); - glUniform4fv(GL_SCRIM_TOP, 1, face.scrim_top.as_ptr()); - glUniform4fv(GL_SCRIM_BOT, 1, face.scrim_bot.as_ptr()); - glUniform4fv(GL_RIMCOL_G, 1, face.rim.as_ptr()); - glUniform4fv(GL_RIMLIT_G, 1, face.rim_lit.as_ptr()); - glUniform1f(GL_RIMW_G, face.rim_w); - glUniform4f(GL_UVRECT, q.x / SCR_W, q.y / SCR_H, q.w / SCR_W, q.h / SCR_H); - glUniform1f(GL_RADIUS, radius); - glUniform2f(GL_CH, w * 0.5, h * 0.5); + glUniform1f(gu.bevel, bevel); + glUniform1f(gu.lens, lens); + glUniform4fv(gu.spec, 1, spec.as_ptr()); + glUniform4fv(gu.tint, 1, tint); + glUniform4fv(gu.scrim_top, 1, face.scrim_top.as_ptr()); + glUniform4fv(gu.scrim_bot, 1, face.scrim_bot.as_ptr()); + glUniform4fv(gu.rimcol, 1, face.rim.as_ptr()); + glUniform4fv(gu.rimlit, 1, face.rim_lit.as_ptr()); + glUniform1f(gu.rimw, face.rim_w); + if framed { + let uv = blur_uv_rect(q.x, q.y, q.w, q.h, frost.rect, [1.0, 1.0], FROST_BOTTOM_UP); + glUniform4f(gu.uvrect, uv[0], uv[1], uv[2], uv[3]); + } else { + glUniform4f(gu.uvrect, q.x / SCR_W, q.y / SCR_H, q.w / SCR_W, q.h / SCR_H); + } + glUniform1f(gu.radius, radius); + glUniform2f(gu.ch, w * 0.5, h * 0.5); // The join and the clarity, set on EVERY draw (the program's state): the panel's centre in // the quad's own frame, the joined shape's centre, half-size, radius and reach (`k` 0 = no // join), the colour the joined shape wears (amount 0 = none), and the clarity, which needs // a sharp source to show. let (qcx, qcy) = (q.x + q.w * 0.5, q.y + q.h * 0.5); - glUniform2f(GL_BOFF, x + w * 0.5 - qcx, y + h * 0.5 - qcy); + glUniform2f(gu.boff, x + w * 0.5 - qcx, y + h * 0.5 - qcy); match merge { Some(m) => { - glUniform4f(GL_MRG, m.rect.x + m.rect.w * 0.5 - qcx, m.rect.y + m.rect.h * 0.5 - qcy, m.rect.w * 0.5, m.rect.h * 0.5); - glUniform2f(GL_MRG_RK, m.radius, m.k); - glUniform4f(GL_MRG_TINT, m.tint[0], m.tint[1], m.tint[2], m.tint[3].clamp(0.0, 1.0)); + glUniform4f(gu.mrg, m.rect.x + m.rect.w * 0.5 - qcx, m.rect.y + m.rect.h * 0.5 - qcy, m.rect.w * 0.5, m.rect.h * 0.5); + glUniform2f(gu.mrg_rk, m.radius, m.k); + glUniform4f(gu.mrg_tint, m.tint[0], m.tint[1], m.tint[2], m.tint[3].clamp(0.0, 1.0)); } None => { - glUniform4f(GL_MRG, 0.0, 0.0, 0.0, 0.0); - glUniform2f(GL_MRG_RK, 0.0, 0.0); - glUniform4f(GL_MRG_TINT, 0.0, 0.0, 0.0, 0.0); + glUniform4f(gu.mrg, 0.0, 0.0, 0.0, 0.0); + glUniform2f(gu.mrg_rk, 0.0, 0.0); + glUniform4f(gu.mrg_tint, 0.0, 0.0, 0.0, 0.0); } } - glUniform1f(GL_CLEAR, if sharp != 0 { morph.clear.clamp(0.0, 1.0) } else { 0.0 }); - let ext = set_rect(GL_RECT, q.x, q.y, q.w, q.h); + glUniform1f(gu.clear, if sharp != 0 { morph.clear.clamp(0.0, 1.0) } else { 0.0 }); + let ext = set_rect(gu.rect, q.x, q.y, q.w, q.h); profile::phase("glass.frozen", || { glDrawArrays(GL_TRIANGLE_STRIP, 0, 4, ext); }); @@ -9318,6 +9861,7 @@ mod tests { ("fs_field.frag", FS_FIELD), ("fs_field_panel.frag", FS_FIELD_PANEL), ("fs_glass.frag", FS_GLASS), + ("fs_glass.frag (frost)", FS_GLASS_FROST), ("fs_art_wash.frag", FS_ART_WASH), ] { let code = shader_code(src); @@ -11328,6 +11872,198 @@ mod tests { assert!(body("impl Drop for DirectPass {").contains("rclip_set(None)"), "the direct pass leaves with none"); } + /// **The plain glass program carries nothing of the frost; the frost program's composite has no + /// body dim and no cap.** The frost variant is `#ifdef PLX_FROST` in `fs_glass.frag`: its body is the + /// BAKED texel (`fs_frost_bake.frag`), so `srcRGB` ends `return c;` with no `dimRGB` call and the cap's + /// uniform and code are gone from the composite altogether (measured: 0.38M cycles executing, 0.31M + /// more paid even switched off, and 0.27M for the body's dim fetch). Preprocessed WITHOUT the macro + /// no word of the frost is left (so a compiler that rejects the variant can only cost the menus + /// their frost, `GLASS_FROST` being an optional link); WITH it the text is the plain text with that + /// one return swapped, and `dimRGB` itself stays for the sharp source (rim band, clear face). + #[test] + fn the_plain_glass_program_carries_no_frost_and_the_variant_composite_has_no_cap_and_no_body_dim() { + let file = include_str!("shaders/fs_glass.frag"); + let plain = preprocess(file, &[]); + for needle in ["frost", "PLX_FROST", "u_frost_cap"] { + assert!(!plain.contains(needle), "the plain glass program names `{needle}`"); + } + assert!(plain.contains(" return dimRGB(c, uv, g);\n"), "the plain srcRGB ends as it always did"); + let frost = preprocess(file, &["PLX_FROST"]); + for needle in ["u_frost_cap", "frost_cap", "max(c.r, max(c.g, c.b))", "o / (o + "] { + assert!(!frost.contains(needle), "the frost composite carries no cap code: `{needle}`"); + } + let body_fetch = |src: &str| { + let from = src.find("vec3 srcRGB(").expect("srcRGB"); + src[from..from + src[from..].find("highp float sdBox").expect("the end of srcRGB")].to_string() + }; + assert!(!body_fetch(&frost).contains("dimRGB("), "the frost body takes no dim: it is baked"); + assert!(body_fetch(&plain).contains("dimRGB("), "the plain body still does"); + assert!(frost.contains("dimRGB(sharp, v_cuv"), "the sharp source keeps its dim (the rim band and the clear face)"); + assert_eq!( + frost, + plain.replace(" return dimRGB(c, uv, g);\n", " return c;\n"), + "the frost program is the plain one with the body's return bare, nothing else" + ); + let (plain_src, frost_src) = (FS_GLASS.to_str().unwrap(), FS_GLASS_FROST.to_str().unwrap()); + assert!(!plain_src.contains("#define PLX_FROST"), "the plain program never defines the macro"); + assert_eq!( + frost_src.strip_prefix("#define PLX_FROST\n"), + Some(plain_src), + "the variant is the plain source behind the one define, in front of the dither prelude" + ); + } + + /// **The bake program has what the composite lost, in the pinned order.** `fs_frost_bake.frag` + /// applies the dim (flat ink or the field texel at the screen point, `fs_glass.frag`'s `dimRGB` + /// modes 0 and 1) and THEN the cap, with the former composite's cap statements verbatim, and writes an + /// opaque body. Capping before the dim would let the ink raise the body past the ceiling the ink + /// floors were derived from (`ui::popover_glass`'s tertiary-ink test grades the order). + #[test] + fn the_bake_program_dims_then_caps_with_the_statements_the_composite_dropped() { + let bake = shader_code(FS_FROST_BAKE); + let dim = bake.find("c = mix(c, ink, a);").expect("the bake dims the body"); + let cap = bake.find("if (u_frost_cap.y > 0.0) {").expect("the bake caps the body"); + assert!(dim < cap, "dim, THEN cap"); + assert!(bake.contains("texture2D(u_dim_tex, v_cuv * u_dim_uv.xy + u_dim_uv.zw)"), "the field at the screen point"); + for line in [ + "float m = max(c.r, max(c.g, c.b));", + "float o = max(m - u_frost_cap.x, 0.0);", + "float y = min(m, u_frost_cap.x) + u_frost_cap.y * (o / (o + u_frost_cap.y));", + "c *= y / max(m, 0.0001);", + ] { + assert!(bake.contains(line), "the cap is the composite's own: `{line}`"); + } + assert!(bake.contains("gl_FragColor = vec4(c, 1.0);"), "an opaque body"); + let src = include_str!("gfx.rs"); + let prod = &src[..src.find("\n#[cfg(test)]\nmod tests").expect("the unit tests")]; + assert!( + prod.contains("link_optional_program(VS_IMG.as_ptr(), FS_FROST_BAKE.as_ptr())"), + "the bake is an optional link on the blur chain's vertex half" + ); + assert!( + prod.contains("glUniform4f(b.uvrect, 0.0, 1.0, 1.0, -1.0)"), + "the pass's flip is undone by its UV window: the body is stored the way the frost is (FROST_BOTTOM_UP)" + ); + assert!(prod.contains("let bake = FrostBake::link()?;"), "no bake, no frost variant: menus keep the field ground"); + assert!(prod.contains("profile::phase(\"glass.bake\""), "the bake has its own profiler phase"); + } + + /// CPU model of one grey channel through `fs_frost_bake.frag`: the dim (`mix(c, ink, a)`) and then + /// the cap (`GlassFrost::cap`). + fn bake_model(f: &GlassFrost, c: f32, ink: f32, a: f32) -> f32 { + f.cap(c + (ink - c) * a) + } + + /// **The baked body, magnified as the composite samples it, against today's per-pixel body.** + /// Today (before the bake) the glass bilinear-sampled the 8-bit frost at each fragment, dimmed + /// that by the field's ink AT THE FRAGMENT, and capped the result. The bake dims and caps each 1/8 + /// texel once at the texel's centre, stores it in 8 bits, and the composite bilinear-samples that. + /// Over one row of 240 texels (the canvas at 1/8) against a 60-cell field that is linear between + /// cell centres (the 60x32 field, GL_LINEAR), the two differ by, at most: + /// * storage: 0.5/255, one 8-bit rounding of the stored texel, which bilinear cannot grow; + /// * the dim: it is AFFINE in the frost value and in the ink, so the interpolation of baked + /// texels reproduces it exactly except across a cell-centre kink of the field, where sampling + /// at texel centres and interpolating misses by at most `|slope change| * h / 4` (`h` = 8 px), + /// scaled by the dim's alpha; + /// * the cap: concave (`y'' = -2d^2/(o+d)^3`, so `|y''| <= 2/d` for headroom `d`), hence the + /// blend of capped texels is NEVER above the cap of the blend (Jensen) and below it by at most + /// `h_v^2 / 8 * 2/d = h_v^2/(4d)`, `h_v` the largest step between neighbouring dimmed texels. + /// A white or black frost is flat: its bound is the storage term alone. + #[test] + fn the_baked_body_magnified_is_the_per_pixel_body_within_storage_kink_and_concavity() { + let ceiling = 0.333_f32; + let f = GlassFrost { tex: 1, rect: [0.0; 4], knee: 0.9 * ceiling, ceiling, rev: 0 }; + let d = ceiling - 0.9 * ceiling; + let store = 0.5 / 255.0; + // The field's ink at a pixel: linear between cell centres (32 px cells), clamped at the ends. + let cells: Vec = (0..60).map(|i| 0.55 + 0.25 * (i as f32 * 0.37).sin()).collect(); + let ink = |x: f32| { + let t = (x / 32.0 - 0.5).clamp(0.0, 58.999); + let (i, u) = (t.floor() as usize, t.fract()); + cells[i] + (cells[i + 1] - cells[i]) * u + }; + let kink = (1..59).map(|i| (cells[i + 1] - 2.0 * cells[i] + cells[i - 1]).abs() / 32.0).fold(0.0_f32, f32::max) * 8.0 / 4.0; + let a = 0.30_f32; + let rows: [(&str, Vec); 4] = [ + ("gradient", (0..240).map(|i| (i as f32 / 239.0 * 255.0).round() / 255.0).collect()), + ("white", vec![1.0; 240]), + ("black", vec![0.0; 240]), + ("steep", (0..240).map(|i| if i < 120 { 0.9 } else { 0.5 }).collect()), + ]; + for (name, frost) in rows { + let baked: Vec = (0..240) + .map(|i| (bake_model(&f, frost[i], ink((i as f32 + 0.5) * 8.0), a) * 255.0).round() / 255.0) + .collect(); + let dimmed: Vec = (0..240).map(|i| frost[i] + (ink((i as f32 + 0.5) * 8.0) - frost[i]) * a).collect(); + let step = (0..239).map(|i| (dimmed[i + 1] - dimmed[i]).abs()).fold(0.0_f32, f32::max); + let (dim_gap, cap_gap) = (a * kink, step * step / (4.0 * d)); + let lerp = |row: &[f32], x: f32| { + let t = (x / 8.0 - 0.5).clamp(0.0, 238.999); + let (i, u) = (t.floor() as usize, t.fract()); + row[i] + (row[i + 1] - row[i]) * u + }; + for x in 0..1920 { + let x = x as f32 + 0.5; + let today = f.cap(lerp(&frost, x) + (ink(x) - lerp(&frost, x)) * a); + let now = lerp(&baked, x); + assert!( + now - today <= store + dim_gap + 1e-5, + "{name} @{x}: the baked body is never brighter than today's beyond storage and the kink: {now} vs {today}" + ); + assert!( + today - now <= store + dim_gap + cap_gap + 1e-5, + "{name} @{x}: and is below it by at most storage + kink + concavity ({}): {now} vs {today}", + store + dim_gap + cap_gap + ); + // A blend of capped texels cannot pass the ceiling (storage may round up by half a code). + assert!(now <= ceiling + store + 1e-6, "{name} @{x}: {now} passes the ceiling {ceiling}"); + } + if name == "white" || name == "black" { + assert!(dim_gap + cap_gap <= 0.003, "{name}: a flat frost's bound is the kink alone, {}", dim_gap + cap_gap); + } + } + // Concavity itself: any two capped values blend under the cap of their blend, and under the ceiling. + for (u, v) in [(0.0_f32, 1.0), (0.2, 0.9), (0.3, 0.31), (0.6, 1.0)] { + for t in [0.1_f32, 0.5, 0.9] { + let blend = f.cap(u) * (1.0 - t) + f.cap(v) * t; + assert!(blend <= f.cap(u * (1.0 - t) + v * t) + 1e-6, "capped texels blend under the cap of the blend"); + assert!(blend < ceiling, "{blend} passes the ceiling"); + } + } + } + + /// The frost program's wiring, which no host test can drive. It is an OPTIONAL link at boot (a + /// driver that refuses it logs `glass frost prog unavailable` and leaves every glass on the plain + /// program: never an exit, never a lost program), it owns its own uniform locations + /// (`GlassUniforms::of`, not the plain program's), only a draw that has a frost asks for it, the + /// live glass never does, and with it missing no frost is built, so menus keep the field ground + /// and the heavier face. + #[test] + fn the_glass_frost_program_is_an_optional_link_only_a_frosted_draw_takes() { + let src = include_str!("gfx.rs"); + let prod = &src[..src.find("\n#[cfg(test)]\nmod tests").expect("the unit tests")]; + let body = |head: &str| { + let from = prod.find(head).unwrap_or_else(|| panic!("`{head}` is gone")); + let rest = &prod[from..]; + &rest[..rest.find("\n}\n").expect("the end of the function")] + }; + assert!( + prod.contains("GLASS_FROST = link_optional_program(VS_IMG_DITHERED.as_ptr(), FS_GLASS_FROST.as_ptr())"), + "the frost glass is fs_glass.frag behind PLX_FROST on the glass's own vertex shader, an optional link" + ); + assert!(prod.contains("log(\"glass frost prog unavailable"), "a refusal logs one line"); + assert!(prod.contains("let u = GlassUniforms::of(program);"), "the variant looks its own locations up"); + assert!( + body("pub fn draw_glass_frozen(").contains("glass_program(frost.tex != 0 && frost.rect[2] > 0.0 && frost.rect[3] > 0.0)"), + "a frozen glass asks for the variant only when it has a frost" + ); + assert!(body("pub fn draw_blur_backdrop(").contains("glass_program(false)"), "the live glass never does"); + assert!(!body("pub fn draw_glass_frozen(").contains("use_prog(GPROG)"), "the frozen glass binds through glass_program"); + assert!(prod.contains("!self.off && !self.fbo_off && !self.frost_off && glass_frost_linked()"), "no variant, no frost owed"); + assert!(prod.contains("|| !blur_lazy_init() || !glass_frost_linked()"), "and none built"); + assert!(!prod.contains("static mut GL_"), "the glass's locations are GlassUniforms, not a static per uniform"); + } + /// Under a live rounded clip a flat or ramp rect is the rect program's SDF fill (its flat fast /// path is the same expression), because the dedicated `fs_flat` / `fs_ramp` stay branch-free /// and unmasked; every other rect keeps its program, and nothing changes while no clip is live. @@ -12353,3 +13089,56 @@ mod card_split_tests { } } } + +#[cfg(test)] +mod frost_tests { + use super::*; + + /// The region is the panel grown by the reach, aligned OUT to whole 1/8 texels and clamped to the canvas. + #[test] + fn the_frost_region_is_the_panel_plus_its_reach_aligned_to_eighths() { + let r = frost_region([630.0, 270.0, 660.0, 540.0]); + assert_eq!(r, [504, 144, 912, 792], "{r:?}"); + let r = frost_region([13.0, 7.0, 101.0, 55.0]); + assert_eq!((r[0], r[1]), (0, 0), "clamped at the canvas origin: {r:?}"); + for r in [r, frost_region([1800.0, 1000.0, 120.0, 80.0]), frost_region([0.0, 0.0, SCR_W, SCR_H])] { + assert!(r.iter().all(|v| v % 8 == 0), "whole 1/8 texels: {r:?}"); + assert!(r[0] + r[2] <= SCR_W as c_int && r[1] + r[3] <= SCR_H as c_int, "inside the canvas: {r:?}"); + } + } + + /// **The knee is the identity below it, bends with a continuous slope above it, and the ceiling is + /// HARD** (nothing reaches it, a full white body lands just under). The knee sits at 0.9 of the + /// ceiling (`ui::theme::FROST_BODY_KNEE_AT`), so a body at 0.85 of it comes through unchanged and + /// only the last tenth bends. The slope is 1 on both sides of the knee: a curve that steepens + /// above it (a normalisation that made white land ON the ceiling did) is a kink, not a knee. + #[test] + fn the_frost_cap_is_a_soft_knee_under_a_hard_ceiling() { + let ceiling = 0.333; + let f = GlassFrost { tex: 1, rect: [0.0, 0.0, 8.0, 8.0], knee: 0.9 * ceiling, ceiling, rev: 0 }; + for i in 0..=100 { + let m = f.knee * i as f32 / 100.0; + assert!((f.cap(m) - m).abs() <= 1e-6, "untouched below the knee at {m}: {}", f.cap(m)); + } + assert!((f.cap(0.85 * ceiling) - 0.85 * ceiling).abs() <= 1.0 / 255.0, "0.85 of the ceiling passes through"); + let e = 1e-4; + let slope = (f.cap(f.knee + e) - f.cap(f.knee)) / e; + assert!((0.98..=1.005).contains(&slope), "the slope is continuous at the knee (1 below it): {slope}"); + let white = f.cap(1.0); + assert!(white < ceiling && white > ceiling - 1.0 / 255.0, "white lands just under the ceiling: {white}"); + let mut last = 0.0; + for i in 0..=100 { + let y = f.cap(i as f32 / 100.0); + assert!(y >= last && y < ceiling, "monotone and under the ceiling at {i}: {y}"); + last = y; + } + assert_eq!(GlassFrost::NONE.cap(0.9), 0.9, "no frost, no cap"); + } + + /// The retained frost is stored the way the passes leave it: four flips from the bottom-up snapshot. + #[test] + fn the_frost_is_stored_bottom_up_after_four_flips() { + assert!(FROST_BOTTOM_UP); + assert_eq!(FROST_TAPS.iter().map(|d| d * d + 0.25).sum::(), 9.0, "sigma 3 texels = 24 px at 1/8"); + } +} diff --git a/rust-modules/gfx/src/gfx/profile.rs b/rust-modules/gfx/src/gfx/profile.rs index 13351ffb11..199fa9988b 100644 --- a/rust-modules/gfx/src/gfx/profile.rs +++ b/rust-modules/gfx/src/gfx/profile.rs @@ -107,6 +107,11 @@ mod imp { "glass.sharp", // A menu's glass on frozen ground (`gfx::draw_glass_frozen`): the panel quad alone. "glass.frozen", + // A menu's frost BUILD (`FrameCache::frost_build_owed`): the frozen page's blur, once per snapshot. + "glass.frost_build", + // The frost body's dim-and-ceiling bake (`FrameCache::frost_bake_owed`): one 1/8-resolution pass. + "glass.bake", + // `glassload`'s frost quad, a full-resolution quad into framebuffer 0 (NOT a menu's frost build). "glass.frost", "glass.foreground", "panel.glass", diff --git a/rust-modules/gfx/src/shaders/fs_frost_bake.frag b/rust-modules/gfx/src/shaders/fs_frost_bake.frag new file mode 100644 index 0000000000..faedd38ae9 --- /dev/null +++ b/rust-modules/gfx/src/shaders/fs_frost_bake.frag @@ -0,0 +1,58 @@ +// THE FROST'S BODY BAKE — the menu body's dim and ceiling, applied ONCE to the retained frost at its own +// 1/8 resolution (`gfx::FrameCache::frost_bake_owed`) instead of per pixel of the glass quad on every +// frame the menu stands (`fs_glass.frag`, which under PLX_FROST now reads the baked texel and does +// neither). +// +// WHY. Measured on the television (Mali, `glass.frozen`, the settled open, M GPU cycles): the frost +// composite was 5.58M against 4.62M for the latched field it replaced. The ceiling cost 0.69M of it: +// 0.38M executing and 0.31M paid even when its uniform switched it off (the code's registers and its +// branch are the cost, not the work), and the body's dim fetch, a second field read beside the frost +// texture, cost 0.27M. A composite with neither measured 4.23M. This program is where both went: a +// 240x135 target at the full canvas, 32 thousand fragments, run when the frost's snapshot or the +// frame's dim changes (every frame of the dim's own ramp; once per open at rest). +// +// THE ORDER IS PINNED and it is the one the composite had: DIM, then CAP, then (in the glass) the face. +// A body capped BEFORE the dim would let the dim's ink raise it past the ceiling the ink floors were +// derived from (`ui::theme::FROST_BODY_CEILING`; the tertiary-ink test grades the order). +// +// The dim is `mix(c, ink, a)` with `ink = u_dim.rgb` times the field texel at the screen point when +// `u_dim_field` says so (`fs_glass.frag`'s `dimRGB`, modes 0 and 1: a body is never the field's own +// texel, mode 2). `v_cuv` is the frost texel's own UV (the pass un-flips its quad so the body is stored +// the way the frost is), and `u_dim_uv` is `gfx::snapshot_to_screen` of the frost's rect, the mapping the +// glass's own sharp-source dim reads the same field through. +// +// THE CEILING is `fs_glass.frag`'s former `u_frost_cap` block, statement for statement: `(knee, +// headroom)`; the brightest CHANNEL is held under `knee + headroom` by `knee + headroom * o / (o + +// headroom)` (`o` the excess over the knee); the whole texel scales by the capped/uncapped ratio, so hue +// survives. Headroom 0 = no cap. The branches are uniform and coherent, and this pass is 1/64 of a +// full-screen quad, so unlike the composite it can afford them. +// +// The body is OPAQUE: the glass reads `.rgb` only and its alpha is the tint's. +precision mediump float; +varying highp vec2 v_cuv; +uniform sampler2D u_tex; +uniform sampler2D u_dim_tex; +uniform vec4 u_dim; +uniform highp vec4 u_dim_uv; +uniform float u_dim_field; +uniform vec2 u_frost_cap; +void main(){ + vec3 c = texture2D(u_tex, v_cuv).rgb; + if (u_dim.a > 0.0) { + vec3 ink = u_dim.rgb; + float a = u_dim.a; + if (u_dim_field > 0.0) { + vec4 f = texture2D(u_dim_tex, v_cuv * u_dim_uv.xy + u_dim_uv.zw); + ink *= f.rgb; + a *= f.a; + } + c = mix(c, ink, a); + } + if (u_frost_cap.y > 0.0) { + float m = max(c.r, max(c.g, c.b)); + float o = max(m - u_frost_cap.x, 0.0); + float y = min(m, u_frost_cap.x) + u_frost_cap.y * (o / (o + u_frost_cap.y)); + c *= y / max(m, 0.0001); + } + gl_FragColor = vec4(c, 1.0); +} diff --git a/rust-modules/gfx/src/shaders/fs_glass.frag b/rust-modules/gfx/src/shaders/fs_glass.frag index 22c48f0d64..0685961003 100644 --- a/rust-modules/gfx/src/shaders/fs_glass.frag +++ b/rust-modules/gfx/src/shaders/fs_glass.frag @@ -211,6 +211,17 @@ uniform highp vec4 u_mrg; uniform highp vec2 u_mrg_rk; uniform vec4 u_mrg_tint; uniform float u_clear; +// THE FROSTED BODY, `#ifdef PLX_FROST` only: the FROST VARIANT of this program (`gfx::FS_GLASS_FROST`, +// linked beside the plain one, drawn by a glass that has a `gfx::GlassFrost`). Its body texture is the +// BAKED body (`fs_frost_bake.frag`, `gfx::FrameCache::frost_bake_owed`): the menu's retained blur +// ALREADY dimmed by the modal dim and ALREADY held under its brightness ceiling +// (`ui::theme::FROST_BODY_CEILING`), at 1/8 resolution, once per change rather than per pixel per +// frame. So under `PLX_FROST` the body fetch below does no `dimRGB` and carries no ceiling code and no +// cap uniform: measured on the television, the ceiling cost 0.69M GPU cycles of the settled open +// (0.31M of it even when switched off) and the body's dim fetch 0.27M. `dimRGB` itself stays for the +// SHARP source (the rim band, the clear face), which is the undimmed page. +// The plain program has none of this: a compiler that refuses the variant costs the menus their frost +// and not every glass surface its program. // The composite-time modal dim over `c`, sampled at snapshot UV `uv` (see `u_dim`); `g` is the // `u_tex` texel already read at `uv`, the ink in mode 2. @@ -251,7 +262,11 @@ vec3 srcRGB(highp vec2 uv, out vec4 g){ * mix(u_wash_w.x, u_wash_w.y, w.y); } c = mix(u_source_ground, c, u_source_alpha); +#ifdef PLX_FROST + return c; +#else return dimRGB(c, uv, g); +#endif } highp float sdBox(highp vec2 p, highp vec2 b, highp float r){ diff --git a/rust-modules/screens/src/CLAUDE.md b/rust-modules/screens/src/CLAUDE.md index d785050605..c05373dbca 100644 --- a/rust-modules/screens/src/CLAUDE.md +++ b/rust-modules/screens/src/CLAUDE.md @@ -63,6 +63,21 @@ A screen mounted as a modal surface is the same trait with a different `Style`; instantiates the same screens a second time for its own inner stack, which is how one `OnboardScreen` mounts twice (§6.2). +## A page reports what it draws that changed under a cover + +A glass menu or Sheet freezes the page under it, and the host retakes that snapshot on typed page +damage (`Present::page_damaged()`, read by `popover::host::begin_frame`; page motion also does once +every surface is fading), the close's first frame included: a page that returns from under a cover (`Uncover`, `Enter(Restored)`, a focus +restored onto the key it already holds) should raise none of its own, and one that does it +unconditionally costs the close a dropped frame. So a page draws from a user setting only if it keeps the value it +last drew from and compares it at the head of `step`, on whichever event comes first +(`registry::moved(&mut self.field, now)`, then `fx.invalidate(Provenance::Nav)`): Home, Library, +Recommended, the collection, person, Search, Detail and Watchlist pages do so for the Under posters +policy (and Library's sort value line, the Continue Watching press the deck draws). A page that +reads the catalog or a store compares its revision the same way (Home's `sync_catalog_changed`, the +Watchlist's `rev`). The collection and person pages are not narrowed yet: both still damage on every +`Uncover`/`Enter` (over-damage, safe: the host may retake their page when nothing changed). + ## A landing must not move ground somebody is looking at The Library's seven reported bugs in 2026-09 had one cause, and the shape recurs on every screen diff --git a/rust-modules/screens/src/account_menu.rs b/rust-modules/screens/src/account_menu.rs index 61ea91c437..3e4a7fd698 100644 --- a/rust-modules/screens/src/account_menu.rs +++ b/rust-modules/screens/src/account_menu.rs @@ -514,6 +514,11 @@ impl Screen for AccountMenuScreen { fn opener_alpha(&self) -> f32 { self.popover.opener_alpha() } + /// The droplet has drained into the chip: the surface, and the lift that holds the chip above + /// it, end on this frame (`Screen::handed_back`), not when the container's spring comes to rest. + fn handed_back(&self) -> bool { + self.popover.handed_back() + } /// The modal dim: the COMPACT role, as every menu hung off a chip: how dark the page goes behind /// this menu. The role sets only the PEAK; the morph ramps it (`Popover::dim` -> /// `Scrim::following`): in as the glass grows, out with the slab. diff --git a/rust-modules/screens/src/collection.rs b/rust-modules/screens/src/collection.rs index 5c2f242446..3c6f258401 100644 --- a/rust-modules/screens/src/collection.rs +++ b/rust-modules/screens/src/collection.rs @@ -964,7 +964,11 @@ impl CollectionScreen { impl Machine for CollectionScreen { type Ev = ScreenEvent; fn step(&mut self, ev: &Self::Ev, cx: &Cx<'_, H>, fx: &mut Effects<'_, H>) -> Handled { - self.page.policy = crate::registry::captions::policy_for(H::screen_inputs(cx)); + // Under posters is a setting Settings changes while it covers the page: noticed here, on + // whichever event comes first, and answered with page damage (a returning page raises none). + if crate::registry::moved(&mut self.page.policy, crate::registry::captions::policy_for(H::screen_inputs(cx))) { + fx.invalidate(Provenance::Nav); + } // The content index is current before the stack reads it for this event. match ev { ScreenEvent::Tick(_) => self.resync(cx), @@ -1202,6 +1206,33 @@ mod tests { out } + /// **A collection page, covered, notices that Settings changed what its members draw under + /// the posters** (`step`'s head): a page returning from under a cover raises no damage of its + /// own, and typed page damage is what retakes a frozen host's snapshot. + #[test] + fn the_collection_damages_the_page_when_the_under_posters_setting_moved_under_a_cover() { + use crate::registry::captions::{PolicyPin, FIXTURE_TITLE_ON}; + use plx_plex::plex::session::UnderPosters; + let _guard = plx_base::testlock::serial(); + let (store, mut screen) = seeded(); + let mut uncover_under = |setting: UnderPosters| { + let _pin = PolicyPin::set(setting); + let mut present = plx_machine::present::Present::new(); + let mut out = Vec::new(); + let mut fx = Effects::new(&mut out, + plx_machine::machine::MachineId::Instance(plx_machine::machine::InstanceId(9)), &mut present); + Machine::::step(&mut screen, &ScreenEvent::Cover, &cx(store.view(), None), &mut fx); + drop(fx); + present.page_damaged() + }; + // Probed with `Cover`: this page still damages unconditionally on `Uncover`/`Enter` (a + // leftover), and the head compare is the same on whichever event comes first. + uncover_under(UnderPosters::DEFAULT); + assert!(!uncover_under(UnderPosters::DEFAULT), "control: an unchanged setting damages nothing"); + assert!(uncover_under(FIXTURE_TITLE_ON), "the Title switch moved the caption policy"); + assert!(!uncover_under(FIXTURE_TITLE_ON), "...once"); + } + fn opens_summary(out: &[plx_machine::machine::Stamped]) -> bool { out.iter().any(|e| matches!(e.fx, plx_machine::machine::Fx::App(AppFx::Content( ContentReq::Panel(ContentPanel::CollectionAbout))))) diff --git a/rust-modules/screens/src/detail/mod.rs b/rust-modules/screens/src/detail/mod.rs index f99e7977f5..24326a7372 100644 --- a/rust-modules/screens/src/detail/mod.rs +++ b/rust-modules/screens/src/detail/mod.rs @@ -2166,7 +2166,11 @@ impl Machine for // Related and the collection's members are POSTER shelves: they follow the Under posters // setting, so the band each reserves and the caption `cards::label` builds cannot disagree. // Extras (landscape stills) and Cast (headshots) are not posters and keep the legacy block. - self.caption_policy = crate::registry::captions::policy_for(H::screen_inputs(cx)); + // Settings changes the setting while it covers the page, and a returning page raises no + // damage of its own: the first event after it is where the page learns, and repaints. + if crate::registry::moved(&mut self.caption_policy, crate::registry::captions::policy_for(H::screen_inputs(cx))) { + fx.invalidate(Provenance::Nav); + } let policy = Some(self.caption_policy); self.related.set_caption_policy(policy); self.collection.set_caption_policy(policy); diff --git a/rust-modules/screens/src/detail/tests.rs b/rust-modules/screens/src/detail/tests.rs index 2b23c6792e..7eaf8e7f48 100644 --- a/rust-modules/screens/src/detail/tests.rs +++ b/rust-modules/screens/src/detail/tests.rs @@ -33,7 +33,7 @@ impl ScreenArg for TestArg { pub(super) struct TestHost; impl crate::registry::ScreenInputsLike for TestHost { - fn screen_inputs<'a>(_: &Cx<'a, Self>) -> &'a crate::registry::ScreenInputs { crate::registry::empty_fixture() } + fn screen_inputs<'a>(_: &Cx<'a, Self>) -> &'a crate::registry::ScreenInputs { crate::registry::caption_fixture() } } impl crate::registry::PlayerLike for TestHost { @@ -254,6 +254,34 @@ fn install(d: Detail) -> plx_base::testlock::Serial { guard } +/// **A detail page, covered, notices that Settings changed what its poster shelves draw under the +/// posters** (`step`'s head): a page returning from under a cover raises no damage of its own, and +/// typed page damage is what retakes a frozen host's snapshot. +#[test] +fn the_detail_damages_the_page_when_the_under_posters_setting_moved_under_a_cover() { + use crate::registry::captions::{PolicyPin, FIXTURE_TITLE_ON}; + use plx_plex::plex::session::UnderPosters; + let _guard = install(Detail { sid: ServerId::UNSET, rk: "page".into(), ..Default::default() }); + let mut screen = bare_held(ServerId::UNSET, "page"); + let measure = plx_ui::fixture::FixtureMeasure; + let mut uncover_under = |setting: UnderPosters| { + let _pin = PolicyPin::set(setting); + screen.sync_keys(test_store().view()); + let mut effects = Vec::new(); + let mut present = plx_machine::present::Present::new(); + { + let mut sink = Effects::new(&mut effects, + plx_machine::machine::MachineId::Instance(plx_machine::machine::InstanceId(1)), &mut present); + Machine::::step(&mut screen, &ScreenEvent::Uncover, &cx(&measure, None), &mut sink); + } + present.page_damaged() + }; + assert!(!uncover_under(UnderPosters::DEFAULT), "control: an unchanged setting damages nothing"); + assert!(uncover_under(FIXTURE_TITLE_ON), "the Title switch moved the caption policy"); + assert!(!uncover_under(FIXTURE_TITLE_ON), "...once"); + clear(); +} + fn clear() { plx_data::metadata::set_current_for_test(test_store().state_mut(), None); // The *Also available* store outlives a page, so a test that seeded it hands the next one an diff --git a/rust-modules/screens/src/home/mod.rs b/rust-modules/screens/src/home/mod.rs index 6bab396949..af137221b4 100644 --- a/rust-modules/screens/src/home/mod.rs +++ b/rust-modules/screens/src/home/mod.rs @@ -3436,6 +3436,11 @@ impl HomeScreen { self.grid.shelves = shelves; } + /// Where the page stands: the billboard/shelves snap, the page's scroll and each shelf's scroll. + fn place(&self) -> (f32, f32, Vec) { + (self.snap.pos, self.grid.scroll_y.pos, self.grid.shelves.iter().map(ui_cards::Shelf::scroll).collect()) + } + fn cancel_row_page(&mut self, row: usize, cx: &Cx<'_, H>, fx: &mut Effects<'_, H>) { let requested = self.grid.shelves.get(row).is_some_and(ui_cards::Shelf::has_page_request); if let Some(shelf) = self.grid.shelves.get_mut(row) { shelf.reset_page_requests(); shelf.drop_page_flight(); } @@ -3563,13 +3568,14 @@ impl Machine for HomeScreen { type Ev = ScreenEvent; fn step(&mut self, ev: &Self::Ev, cx: &Cx<'_, H>, fx: &mut Effects<'_, H>) -> Handled { - self.deck_press = H::screen_inputs(cx).preference::(); - // What the page draws under each poster is the Under posters setting, which Settings - // changes while it covers Home and which nothing else tells the page about: this is where - // it is noticed, on whichever event comes first, and it is what repaints the page (a - // returning Home raises no damage of its own, see `Uncover`). - let policy = crate::registry::captions::policy_for(H::screen_inputs(cx)); - if std::mem::replace(&mut self.caption_policy, policy) != policy { + // What the page draws under each poster is the Under posters setting, and what its Continue + // Watching deck's tile promises is the Continue Watching setting. Settings changes both + // while it covers Home and nothing else tells the page about it: this is where they are + // noticed, on whichever event comes first, and it is what repaints the page (a returning + // Home raises no damage of its own, see `Uncover`). + let inputs = H::screen_inputs(cx); + let pressed = crate::registry::moved(&mut self.deck_press, inputs.preference::()); + if crate::registry::moved(&mut self.caption_policy, crate::registry::captions::policy_for(inputs)) | pressed { fx.invalidate(Provenance::Nav); } match self.plaintext_alert.step(ev, cx) { @@ -3657,10 +3663,17 @@ impl Machine for HomeScreen { Handled::Yes } ScreenEvent::RestoreMemory(PageMemory::Home(memory)) => { + // The dispatcher hands this to the host page of EVERY dismissal, and a covered page + // comes back to the place and projection it was frozen at: that is not a change. + // A body minted again (a pop, an eviction) lands somewhere else, and is. + let before = (self.projected_generation, self.place()); self.adopt_shows(memory, H::hubs(cx)); self.restore(memory); self.sync_catalog(cx); self.cta_available = self.hero_len(H::hubs(cx)) > 0; + if before != (self.projected_generation, self.place()) { + fx.invalidate(Provenance::Nav); + } Handled::Yes } ScreenEvent::Enter(enter) => { @@ -3747,7 +3760,13 @@ impl Machine for HomeScreen { None => {} } } - if matches!(by, By::Restore) && self.restore_reveal { + // The jump to a saved region is what a restore can change that the page draws, beyond + // the focus itself. A covered page comes back to the place it was frozen at (the + // dispatcher hands every dismissal's host its `RestoreMemory`), so the jump is + // usually a no-op: read where the page stands before and after it. + let jumped = matches!(by, By::Restore) && self.restore_reveal; + let placed = jumped.then(|| self.place()); + if jumped { // A restored page opens at its saved region, rather than replaying the // hero-to-grid door with an invisible engine cursor during the transition. self.restore_reveal = false; @@ -3778,7 +3797,14 @@ impl Machine for HomeScreen { if matches!(by, By::Dir | By::Pointer | By::Script) { self.restart_hero_countdown(); } - fx.invalidate(Provenance::Input); + // **A focus that did not move repaints nothing.** A modal's dismissal re-enters the + // covered page, and `FocusEngine::enter` announces the key it already holds as + // `from == to` (the page learns of its own reveal, and was drawn with that focus). + // Page damage retakes a frozen host's snapshot on the close's first frame, which is + // the cost the account menu's BACK paid with the chip focused. + if from.as_ref() != Some(to) || placed.is_some_and(|before| before != self.place()) { + fx.invalidate(Provenance::Input); + } Handled::Yes } ScreenEvent::PressCommit(_) => { diff --git a/rust-modules/screens/src/home/tests.rs b/rust-modules/screens/src/home/tests.rs index 53175e6b9e..4a7a681771 100644 --- a/rust-modules/screens/src/home/tests.rs +++ b/rust-modules/screens/src/home/tests.rs @@ -3390,6 +3390,111 @@ fn home_raises_no_damage_coming_back_from_under_a_cover_unless_what_it_draws_cha assert!(damage(&mut s, next.view(), ScreenEvent::Enter(Enter::Fresh { focus: FocusTarget::ContainerGroup(GroupId(0)) }))); } +/// **Home, covered, notices that Settings changed what its Continue Watching deck promises.** The +/// deck's tile draws the press's triangle only while a press plays, which is the Continue Watching +/// setting Settings changes under a cover: a returning page raises no damage of its own, so `step`'s +/// head compares it and answers with page damage, once. +#[test] +fn home_damages_the_page_when_the_continue_watching_setting_moved_under_a_cover() { + let _guard = plx_base::testlock::serial(); + let mut state = plx_data::pms::PmsState::default(); + let adapter = std::sync::Arc::new(plx_data::pms::PmsAdapter::default()); + plx_data::pms::seed_recent_window_for_test(&mut state, &adapter, 0, 24, true); + let snapshot = plx_data::pms::hubs_snapshot(&state); + let mut s = screen(snapshot.view()); + let mut uncover_under = |mode: plx_media::route::DeckPress| { + let _press = deck_press_is(mode); + let context = cx(snapshot.view(), None); + let mut out = Vec::new(); + let mut present = plx_machine::present::Present::new(); + { + let mut fx = Effects::new(&mut out, plx_machine::machine::MachineId::Instance(InstanceId(9)), &mut present); + Machine::::step(&mut s, &ScreenEvent::Uncover, &context, &mut fx); + } + present.page_damaged() + }; + assert!(!uncover_under(plx_media::route::DeckPress::Details), "control: an unchanged setting damages nothing"); + assert!(uncover_under(plx_media::route::DeckPress::Play), "the press moved from opening to playing"); + assert!(!uncover_under(plx_media::route::DeckPress::Play), "...once"); +} + +/// **A focus that did not move damages nothing.** A modal's dismissal re-enters the covered page +/// (`FocusEngine::enter`), which announces the key it already holds as `FocusMoved { from: Some(k), +/// to: k, by: Restore }`: the page was only covered, so the focus the snapshot was drawn with is the +/// focus it comes back to. Home raised `Input` page damage for it, and typed page damage is what +/// retakes the host snapshot on the close's first frame (the account menu's BACK, with the chip +/// focused: 14.9M GPU cycles against an 11.2M budget on the TV). A real move, and a restore that +/// jumps the page to its saved place, still repaint. +#[test] +fn home_raises_no_damage_for_a_restore_onto_the_focus_it_already_holds() { + let _guard = plx_base::testlock::serial(); + let mut state = plx_data::pms::PmsState::default(); + let adapter = std::sync::Arc::new(plx_data::pms::PmsAdapter::default()); + plx_data::pms::seed_recent_window_for_test(&mut state, &adapter, 0, 24, true); + let snapshot = plx_data::pms::hubs_snapshot(&state); + let view = snapshot.view(); + let mut s = screen(view); + let damage = |s: &mut HomeScreen, focus: Option>, event: ScreenEvent| { + let context = cx(view, focus); + let mut out = Vec::new(); + let mut present = plx_machine::present::Present::new(); + { + let mut fx = Effects::new(&mut out, plx_machine::machine::MachineId::Instance(InstanceId(9)), &mut present); + Machine::::step(s, &event, &context, &mut fx); + } + present.page_damaged() + }; + let hero = FocusKey { entry: s.entry, elem: HERO_PLAY_ELEM }; + let card = FocusKey { entry: s.entry, elem: s.rows[0].elems[0] }; + + assert!(!damage(&mut s, Some(hero), ScreenEvent::FocusMoved { from: Some(hero), to: hero, by: By::Restore }), + "a restore onto the focus the page already holds moves nothing"); + assert!(damage(&mut s, Some(card), ScreenEvent::FocusMoved { from: Some(hero), to: card, by: By::Dir }), + "a key that moves focus still repaints the page"); + assert!(damage(&mut s, Some(hero), ScreenEvent::FocusMoved { from: None, to: hero, by: By::Restore }), + "a restore that lands focus where it was not still repaints"); + // the dispatcher's `RestoreMemory` re-arms the saved-place jump on every dismissal's host page + s.restore_reveal = true; + assert!(!damage(&mut s, Some(hero), ScreenEvent::FocusMoved { from: Some(hero), to: hero, by: By::Restore }), + "a jump to the place the page already stands at moves nothing"); + assert!(!s.restore_reveal, "premise: the jump was taken"); + s.restore_reveal = true; + s.snap.jump(1.0); + assert!(damage(&mut s, Some(hero), ScreenEvent::FocusMoved { from: Some(hero), to: hero, by: By::Restore }), + "a jump that moves the page repaints it"); +} + +/// **A dismissal's `RestoreMemory` damages only a page it moves.** The dispatcher hands the host page +/// its own memory back on every modal's close; a page that was only covered stands where it was +/// frozen, so it repaints nothing (the account menu's BACK), while a body minted again lands at the +/// remembered place and does. +#[test] +fn home_raises_damage_for_a_restored_memory_only_when_it_moves_the_page() { + let _guard = plx_base::testlock::serial(); + let mut state = plx_data::pms::PmsState::default(); + let adapter = std::sync::Arc::new(plx_data::pms::PmsAdapter::default()); + plx_data::pms::seed_recent_window_for_test(&mut state, &adapter, 0, 24, true); + let snapshot = plx_data::pms::hubs_snapshot(&state); + let view = snapshot.view(); + let damage = |s: &mut HomeScreen, memory: HomeMemory| { + let context = cx(view, None); + let mut out = Vec::new(); + let mut present = plx_machine::present::Present::new(); + { + let mut fx = Effects::new(&mut out, plx_machine::machine::MachineId::Instance(InstanceId(9)), &mut present); + Machine::::step(s, &ScreenEvent::RestoreMemory(PageMemory::Home(memory)), &context, &mut fx); + } + present.page_damaged() + }; + let mut covered = screen(view); + covered.grid.scroll_y.jump(120.0); + covered.grid.scroll_target = 120.0; + let memory = memory_of(&covered); + assert!(!damage(&mut covered, memory.clone()), "a covered page handed its own memory stands where it was"); + let mut remounted = screen(view); + assert!(damage(&mut remounted, memory), "a page minted again lands at the remembered place"); +} + /// `HomeCmd::PinHero` — the screenshot pipeline's hero pin (`/tmp/plxnative-heropin=`) — /// selects that slot and HOLDS it: the auto-advance never fires, however long the page sits /// uncovered, so a capture taken at any settled moment shows the same billboard. diff --git a/rust-modules/screens/src/inputs.rs b/rust-modules/screens/src/inputs.rs index 2c85dc7d69..f3741b7c0d 100644 --- a/rust-modules/screens/src/inputs.rs +++ b/rust-modules/screens/src/inputs.rs @@ -60,6 +60,18 @@ impl Default for ScreenInputs { install_language: Default::default(), running_language: Default::default(), player_presentation: Default::default() } } } +/// **Did a setting a page draws from move since the page last held it?** Settings changes a +/// setting while it covers a page, and nothing else tells the page: it keeps what it last drew from +/// in `held`, reads the setting again at the head of its next `step` (whichever event comes first) +/// and asks here. `true` is what the page answers with page damage (`Effects::invalidate`): a page +/// coming back from under a cover raises none of its own, and typed page damage is what retakes a +/// frozen host's snapshot. +pub fn moved(held: &mut T, now: T) -> bool { + let changed = *held != now; + *held = now; + changed +} + impl ScreenInputs { pub fn preference(&self) -> S::Value { if let Some(value) = self.preferences.as_ref().and_then(S::own) { return value; } diff --git a/rust-modules/screens/src/library/menu.rs b/rust-modules/screens/src/library/menu.rs index b0f7ec8d67..9bcbe5c6a9 100644 --- a/rust-modules/screens/src/library/menu.rs +++ b/rust-modules/screens/src/library/menu.rs @@ -911,6 +911,11 @@ impl Screen for LibraryMenu { fn opener_alpha(&self) -> f32 { self.popover.opener_alpha() } + /// The droplet has drained into the header control: the surface, and the lift that holds the + /// control above it, end on this frame (`Screen::handed_back`). + fn handed_back(&self) -> bool { + self.popover.handed_back() + } fn name(&self) -> &'static str { "library_menu" } diff --git a/rust-modules/screens/src/library/mod.rs b/rust-modules/screens/src/library/mod.rs index 2513422553..6503bc2818 100644 --- a/rust-modules/screens/src/library/mod.rs +++ b/rust-modules/screens/src/library/mod.rs @@ -212,6 +212,9 @@ pub enum Listing { pub struct LibraryScreen { /// Derived from retained effective frame inputs, shared by live/target grid geometry. caption_policy: plx_ui::caption_policy::CaptionPolicy, + /// The Sort value setting the grid last drew its value lines from (`caption_policy` does not + /// carry it): what `step` compares to damage a page that Settings changed it under. + sort_value: bool, /// Which listing the page shows. Fixed at mount by the `AppArg` that mounted it, so it is not /// part of the canon: `LibraryCollections` / `LibraryRecommended` already say it. listing: Listing, @@ -357,6 +360,7 @@ impl LibraryScreen { let layout = Layout::new(false, 0); Self { caption_policy: crate::registry::caption_policy_of(plx_plex::plex::session::UnderPosters::DEFAULT), + sort_value: plx_plex::plex::session::UnderPosters::DEFAULT.sort_value, listing: Listing::All, entry, instance, kind, wanted_kind: Some(kind), listed: Default::default(), values: false, keys: KeyRegistry::default(), pair: MasterDetail::new( @@ -1278,8 +1282,15 @@ impl LibraryScreen { impl Machine for LibraryScreen { type Ev = ScreenEvent; fn step(&mut self, ev: &Self::Ev, cx: &Cx<'_, H>, fx: &mut Effects<'_, H>) -> Handled { - let handled = self.step_event(ev, cx, fx); - handled + // What the grid draws under each poster (the Under posters policy and the sort value line) is + // a setting Settings changes while it covers the page: noticed here, on whichever event + // comes first, and answered with page damage (a returning page raises none of its own). + let inputs = H::screen_inputs(cx); + let policy = crate::registry::moved(&mut self.caption_policy, crate::registry::captions::policy_for(inputs)); + if crate::registry::moved(&mut self.sort_value, crate::registry::captions::sort_value_for(inputs)) | policy { + fx.invalidate(Provenance::Nav); + } + self.step_event(ev, cx, fx) } } diff --git a/rust-modules/screens/src/library/recommended.rs b/rust-modules/screens/src/library/recommended.rs index bc800476cc..d1a58d9ad6 100644 --- a/rust-modules/screens/src/library/recommended.rs +++ b/rust-modules/screens/src/library/recommended.rs @@ -207,6 +207,8 @@ pub(super) enum Readout { /// The Recommended page: a vertical stack of the library's hub rows. pub struct RecommendedScreen { caption_policy: plx_ui::caption_policy::CaptionPolicy, + /// The Continue Watching setting the deck's tiles were last drawn with (`step` compares it). + deck_press: plx_plex::plex::session::DeckPress, pub(super) entry: EntryId, instance: InstanceId, kind: SecKind, @@ -396,6 +398,7 @@ impl RecommendedScreen { pub fn new(entry: EntryId, instance: InstanceId, kind: SecKind) -> Self { Self { caption_policy: crate::registry::caption_policy_of(plx_plex::plex::session::UnderPosters::DEFAULT), + deck_press: plx_plex::plex::session::DeckPress::Details, entry, instance, kind, keys: KeyRegistry::default(), shelves: Vec::new(), section: None, epoch: None, query: None, shelf_publication: None, run: ShelfRun::default(), target_run: ShelfRun::default(), @@ -1124,6 +1127,14 @@ impl RecommendedScreen { impl Machine for RecommendedScreen { type Ev = ScreenEvent; fn step(&mut self, ev: &Self::Ev, cx: &Cx<'_, H>, fx: &mut Effects<'_, H>) -> Handled { + // The shelves draw the Under posters policy, and the Continue Watching deck's tile the + // Continue Watching setting; Settings changes either while it covers the page, and the + // first event after it is where the page learns (a returning page raises no damage). + let inputs = H::screen_inputs(cx); + let pressed = crate::registry::moved(&mut self.deck_press, inputs.preference::()); + if crate::registry::moved(&mut self.caption_policy, crate::registry::captions::policy_for(inputs)) | pressed { + fx.invalidate(Provenance::Nav); + } self.step_event(ev, cx, fx) } } diff --git a/rust-modules/screens/src/library/recommended_tests.rs b/rust-modules/screens/src/library/recommended_tests.rs index 09ef2dde17..a40a08f3c1 100644 --- a/rust-modules/screens/src/library/recommended_tests.rs +++ b/rust-modules/screens/src/library/recommended_tests.rs @@ -24,7 +24,7 @@ impl Host for HostFixture { } impl crate::registry::ScreenInputsLike for HostFixture { fn screen_inputs<'a>(_cx: &Cx<'a, Self>) -> &'a crate::registry::ScreenInputs { - crate::registry::empty_fixture() + crate::registry::caption_fixture() } } @@ -433,3 +433,26 @@ fn the_crumb_row_is_built_once_per_key_not_once_per_question() { for _ in 0..10 { ask(&fixture); } assert_eq!(page.probe_header_builds(), built + 1, "and the questions after it build none"); } + +/// **Recommended, covered, notices that Settings changed what its shelves draw under the posters** +/// (`step`'s head): a page returning from under a cover raises no damage of its own, and typed page +/// damage is what retakes a frozen host's snapshot. +#[test] +fn recommended_damages_the_page_when_the_under_posters_setting_moved_under_a_cover() { + use crate::registry::captions::{PolicyPin, FIXTURE_TITLE_ON}; + use plx_plex::plex::session::UnderPosters; + let _guard = plx_base::testlock::serial(); + let fixture = Fixture::shelves(&["Trending"], 6); + let mut page = fixture.screen(); + let mut uncover_under = |setting: UnderPosters| { + let _pin = PolicyPin::set(setting); + let mut out = Vec::new(); + let mut present = plx_machine::present::Present::new(); + page.step(&ScreenEvent::Uncover, &fixture.cx(None), + &mut Effects::new(&mut out, MachineId::Instance(InstanceId(19)), &mut present)); + present.page_damaged() + }; + assert!(!uncover_under(UnderPosters::DEFAULT), "control: an unchanged setting damages nothing"); + assert!(uncover_under(FIXTURE_TITLE_ON), "the Title switch moved the caption policy"); + assert!(!uncover_under(FIXTURE_TITLE_ON), "...once"); +} diff --git a/rust-modules/screens/src/library/tests.rs b/rust-modules/screens/src/library/tests.rs index 0747ccee88..35a0cca2a5 100644 --- a/rust-modules/screens/src/library/tests.rs +++ b/rust-modules/screens/src/library/tests.rs @@ -1765,3 +1765,29 @@ fn a_day_turn_changes_the_rails_labels_and_where_its_step_falls() { assert_eq!(labels_of(&page), ["Today", "2026", "2025"]); assert_eq!(rail_centres(&page, &fixture), [264.0, 304.0, 344.0], "Today and the year after it are a pitch apart, no step"); } + +/// **A grid that was covered notices that Settings changed what it draws under the posters.** A +/// page returning from under a cover raises no damage of its own (typed page damage retakes a frozen +/// host's snapshot, the cost a glass menu's BACK paid), so the Under posters policy and the sort value +/// line, which `step` reads at its head, are what the page answers with damage, once. +#[test] +fn the_grid_damages_the_page_when_the_under_posters_setting_moved_under_a_cover() { + use crate::registry::captions::{PolicyPin, FIXTURE_TITLE_ON}; + use plx_plex::plex::session::UnderPosters; + let _guard = plx_base::testlock::serial(); + let fixture = Fixture::new(); + let mut page = fixture.screen(); + let mut uncover_under = |setting: UnderPosters| { + let _pin = PolicyPin::set(setting); + let mut out = Vec::new(); + let mut present = plx_machine::present::Present::new(); + page.step(&ScreenEvent::Uncover, &fixture.cx(None), + &mut Effects::new(&mut out, MachineId::Instance(InstanceId(19)), &mut present)); + present.page_damaged() + }; + assert!(!uncover_under(UnderPosters::DEFAULT), "control: an unchanged setting damages nothing"); + assert!(uncover_under(FIXTURE_TITLE_ON), "the Title switch moved the caption policy"); + assert!(!uncover_under(FIXTURE_TITLE_ON), "...once"); + assert!(uncover_under(UnderPosters { sort_value: !FIXTURE_TITLE_ON.sort_value, ..FIXTURE_TITLE_ON }), + "the sort value line is not part of the policy, and is drawn under every card"); +} diff --git a/rust-modules/screens/src/person.rs b/rust-modules/screens/src/person.rs index 2b326045ef..195a85c3a4 100644 --- a/rust-modules/screens/src/person.rs +++ b/rust-modules/screens/src/person.rs @@ -434,6 +434,9 @@ struct Page { entry_count_c: CString, header: HeaderFlow, header_dirty: bool, + /// The Under posters policy the filmography shelves were last drawn with (`step` compares it: + /// Settings changes the setting while it covers the page). + caption_policy: plx_ui::caption_policy::CaptionPolicy, /// What the page's links are made of; the screen turns it into group ids ([`PersonScreen::links`]). reach: Reach, /// The store revision ([`PersonView::revision`](plx_data::person::PersonView::revision)) the @@ -554,6 +557,7 @@ impl Page { entry_count_c: CString::default(), header: HeaderFlow::default(), header_dirty: true, + caption_policy: crate::registry::caption_policy_of(plx_plex::plex::session::UnderPosters::DEFAULT), reach: Reach::default(), synced: None, covered_ready_c: false, @@ -1231,6 +1235,12 @@ impl PersonScreen { impl Machine for PersonScreen { type Ev = ScreenEvent; fn step(&mut self, ev: &Self::Ev, cx: &Cx<'_, H>, fx: &mut Effects<'_, H>) -> Handled { + // The shelves draw the Under posters policy, which Settings changes while it covers the page: + // noticed on whichever event comes first, and answered with page damage (a returning page + // raises none of its own). + if crate::registry::moved(&mut self.page.caption_policy, crate::registry::captions::policy_for(H::screen_inputs(cx))) { + fx.invalidate(Provenance::Nav); + } // The content the stack reads is current before it reads it for this event. let mut live = false; match ev { @@ -1540,6 +1550,32 @@ mod tests { (store, s) } + /// **A person page, covered, notices that Settings changed what its filmography draws under the + /// posters** (`step`'s head): a page returning from under a cover raises no damage of its own, + /// and typed page damage is what retakes a frozen host's snapshot. + #[test] + fn the_person_damages_the_page_when_the_under_posters_setting_moved_under_a_cover() { + use crate::registry::captions::{PolicyPin, FIXTURE_TITLE_ON}; + use plx_plex::plex::session::UnderPosters; + let _guard = plx_base::testlock::serial(); + let (store, mut s) = seed(4, 3); + let mut uncover_under = |setting: UnderPosters| { + let _pin = PolicyPin::set(setting); + let mut present = plx_machine::present::Present::new(); + let mut buf: Vec> = Vec::new(); + let mut fx = Effects::new(&mut buf, + plx_machine::machine::MachineId::Instance(plx_machine::machine::InstanceId(0)), &mut present); + Machine::::step(&mut s, &ScreenEvent::Cover, &cx(&FixtureMeasure, store.view()), &mut fx); + present.page_damaged() + }; + // Probed with `Cover`: this page still damages unconditionally on `Uncover`/`Enter` (a + // leftover), and the head compare is the same on whichever event comes first. + uncover_under(UnderPosters::DEFAULT); + assert!(!uncover_under(UnderPosters::DEFAULT), "control: an unchanged setting damages nothing"); + assert!(uncover_under(FIXTURE_TITLE_ON), "the Title switch moved the caption policy"); + assert!(!uncover_under(FIXTURE_TITLE_ON), "...once"); + } + fn focus_of(s: &PersonScreen, store: &plx_data::stores::person::PersonStore, kind: usize, col: usize) -> plx_machine::machine::FocusKey { s.page.shelf_key(store.view().current().unwrap(), kind, col) } diff --git a/rust-modules/screens/src/registry.rs b/rust-modules/screens/src/registry.rs index 0af0400f2c..7611108c24 100644 --- a/rust-modules/screens/src/registry.rs +++ b/rust-modules/screens/src/registry.rs @@ -26,7 +26,7 @@ pub use crate::family::SettingsPage; pub use crate::family::InnerViews; -pub use crate::inputs::{GrantInputs, RuntimePolicy, ScreenInputs}; +pub use crate::inputs::{moved, GrantInputs, RuntimePolicy, ScreenInputs}; #[cfg(test)] pub(crate) use crate::inputs::{capture_fixture, caption_fixture, empty_fixture, publication_fixture}; /// The stored Under posters setting as the ui caption policy: the shared door a screen outside diff --git a/rust-modules/screens/src/registry/captions.rs b/rust-modules/screens/src/registry/captions.rs index d35a92d525..e53158c05c 100644 --- a/rust-modules/screens/src/registry/captions.rs +++ b/rust-modules/screens/src/registry/captions.rs @@ -72,6 +72,12 @@ thread_local! { const { std::cell::Cell::new(None) }; } +/// A setting whose caption policy differs from the default's (the Title switch on): what Settings +/// leaves behind for a page it covered, for the tests of a page that must notice (`policy_moved`). +#[cfg(test)] +pub(crate) const FIXTURE_TITLE_ON: plx_plex::plex::session::UnderPosters = + plx_plex::plex::session::UnderPosters { title: true, ..plx_plex::plex::session::UnderPosters::DEFAULT }; + /// Pins an explicit test fixture's Under posters input until dropped. Fixture hosts capture this /// choice into ScreenInputs; production policy readers never consult it. Existing pins are retained /// and restored on drop, including during unwinding; no process-wide cell is written. @@ -80,6 +86,13 @@ pub(crate) struct PolicyPin(Option); #[cfg(test)] impl PolicyPin { + /// Pins `setting` until dropped: what Settings does to a page it covers. + pub(crate) fn set(setting: plx_plex::plex::session::UnderPosters) -> Self { + let before = TEST_UNDER_POSTERS.with(|cell| cell.get()); + TEST_UNDER_POSTERS.with(|cell| cell.set(Some(setting))); + PolicyPin(before) + } + pub(crate) fn default_setting() -> Self { let before = TEST_UNDER_POSTERS.with(|cell| cell.get()); TEST_UNDER_POSTERS.with(|cell| cell.set(Some(before.unwrap_or(plx_plex::plex::session::UnderPosters::DEFAULT)))); diff --git a/rust-modules/screens/src/search/mod.rs b/rust-modules/screens/src/search/mod.rs index 01ac4358d9..9f55fdaf54 100644 --- a/rust-modules/screens/src/search/mod.rs +++ b/rust-modules/screens/src/search/mod.rs @@ -104,6 +104,9 @@ pub struct SearchScreen { /// "did a store notice reach the top screen" probes stay readable now that `Route::Search` /// mounts this screen unconditionally. notices: u32, + /// The Under posters policy the poster rows were last drawn with (`step` compares it: Settings + /// changes the setting while it covers the page). + caption_policy: plx_ui::caption_policy::CaptionPolicy, /// The page ask last sent for each row (window start, direction, cards held), by /// [`layout::ordinal`]. Not part of the state hash. It only records the last ask so a /// `PageCancel` can name its window: every ask the shelf emits is forwarded, a repeat @@ -119,7 +122,8 @@ impl SearchScreen { recent_clear_pending: false, publication: None, content_dirty: true, fade: plx_ui::xfade::Xfade::new(), ground: plx_ui::widgets::PageGround::new(), owner_row: None, owner: String::new(), owner_alpha: Spring::at(0.0), restored: None, render: Default::default(), - notices: 0, page_sent: [None; 5] } + notices: 0, caption_policy: crate::registry::caption_policy_of(plx_plex::plex::session::UnderPosters::DEFAULT), + page_sent: [None; 5] } } fn key(&self, elem: u32) -> FocusKey { FocusKey { entry: self.entry, elem } } fn real_query(&self) -> bool { plx_data::search::terms(self.draft.query()).is_some() } @@ -341,6 +345,12 @@ impl SearchScreen { impl Machine for SearchScreen { type Ev = ScreenEvent; fn step(&mut self, ev: &Self::Ev, cx: &Cx<'_, H>, fx: &mut Effects<'_, H>) -> Handled { + // The poster rows draw the Under posters policy, which Settings changes while it covers the + // page: noticed on whichever event comes first, and answered with page damage (a returning + // page raises none of its own). + if crate::registry::moved(&mut self.caption_policy, crate::registry::captions::policy_for(H::screen_inputs(cx))) { + fx.invalidate(Provenance::Nav); + } let store_changed = matches!(ev, ScreenEvent::StoreChanged(store, _) if *store == StoreId::Search.ord()); if store_changed { self.notices += 1; } let acknowledged = matches!(ev, ScreenEvent::Mount) || store_changed; diff --git a/rust-modules/screens/src/search/tests.rs b/rust-modules/screens/src/search/tests.rs index 3bbd02f309..703bb1a71b 100644 --- a/rust-modules/screens/src/search/tests.rs +++ b/rust-modules/screens/src/search/tests.rs @@ -1684,3 +1684,27 @@ fn the_edge_glide_moves_the_results_by_poster_rows_and_a_wheel_notch_by_a_table_ assert!((screen.stack.target() - glided - plx_ui::table::ROW_H).abs() < 0.01, "a wheel notch moves one table row: {} -> {}", glided, screen.stack.target()); } + +/// **Search, covered, notices that Settings changed what its poster rows draw under the posters** +/// (`step`'s head): a page returning from under a cover raises no damage of its own, and typed page +/// damage is what retakes a frozen host's snapshot. +#[test] +fn search_damages_the_page_when_the_under_posters_setting_moved_under_a_cover() { + use crate::registry::captions::{PolicyPin, FIXTURE_TITLE_ON}; + use plx_plex::plex::session::UnderPosters; + let _guard = plx_base::testlock::serial(); + let fixture = Fixture::new(); + let mut screen = fixture.screen(); + let mut uncover_under = |setting: UnderPosters| { + let _pin = PolicyPin::set(setting); + let cx = fixture.cx(None); + let mut out = Vec::new(); + let mut present = Present::new(); + Machine::::step(&mut screen, &ScreenEvent::Uncover, &cx, + &mut Effects::new(&mut out, MachineId::Instance(INSTANCE), &mut present)); + present.page_damaged() + }; + assert!(!uncover_under(UnderPosters::DEFAULT), "control: an unchanged setting damages nothing"); + assert!(uncover_under(FIXTURE_TITLE_ON), "the Title switch moved the caption policy"); + assert!(!uncover_under(FIXTURE_TITLE_ON), "...once"); +} diff --git a/rust-modules/screens/src/watchlist/cards_harness.rs b/rust-modules/screens/src/watchlist/cards_harness.rs index d9d8579617..68225182aa 100644 --- a/rust-modules/screens/src/watchlist/cards_harness.rs +++ b/rust-modules/screens/src/watchlist/cards_harness.rs @@ -255,6 +255,16 @@ impl Harness { /// Step one event; returns the effects it queued and whether the step reported page motion. pub(crate) fn step_fx(&mut self, ev: ScreenEvent) -> (Vec>, bool) { + let (out, moving, _) = self.step_all(ev); + (out, moving) + } + + /// Step one event; whether it raised typed PAGE damage (what retakes a frozen host's snapshot). + pub(crate) fn damages(&mut self, ev: ScreenEvent) -> bool { + self.step_all(ev).2 + } + + fn step_all(&mut self, ev: ScreenEvent) -> (Vec>, bool, bool) { let mut present = plx_machine::present::Present::new(); let mut out = Vec::new(); let (_, moving) = plx_machine::motion::report::scoped_motion(|| { @@ -274,7 +284,7 @@ impl Harness { ); Machine::::step(&mut self.screen, &ev, &cx, &mut fx); }); - (out, moving || present.page_moving()) + (out, moving || present.page_moving(), present.page_damaged()) } pub(crate) fn step(&mut self, ev: ScreenEvent) -> bool { diff --git a/rust-modules/screens/src/watchlist/menu.rs b/rust-modules/screens/src/watchlist/menu.rs index 4227be60d3..936554c359 100644 --- a/rust-modules/screens/src/watchlist/menu.rs +++ b/rust-modules/screens/src/watchlist/menu.rs @@ -211,6 +211,11 @@ impl Screen for WatchlistMenuScreen { fn opener_alpha(&self) -> f32 { self.menu.popover().opener_alpha() } + /// The droplet has drained into the pill: the surface, and the lift that holds the pill above + /// it, end on this frame (`Screen::handed_back`). + fn handed_back(&self) -> bool { + self.menu.popover().handed_back() + } fn as_any(&self) -> Option<&dyn std::any::Any> { Some(self) } diff --git a/rust-modules/screens/src/watchlist/page.rs b/rust-modules/screens/src/watchlist/page.rs index f8dbf9be04..39db8f9380 100644 --- a/rust-modules/screens/src/watchlist/page.rs +++ b/rust-modules/screens/src/watchlist/page.rs @@ -828,6 +828,13 @@ pub struct WatchlistScreen { /// answers, so the page cannot refuse it: it puts the reader's focus back when it arrives /// (see [`step`](Machine::step)). stale_enters: u8, + /// The Under posters policy the tiles' captions were last drawn with: what `step` compares, as + /// Settings changes the setting while it covers the page. Decoration, never canon. + caption_policy: plx_ui::caption_policy::CaptionPolicy, + /// The page's revision ([`Page::rev`]) as `step` last saw it: a tile landing, an option change or + /// a count released moves it, and it is what the page draws that a cover can have hidden. + /// Decoration, never canon. + seen_rev: u64, } impl WatchlistScreen { @@ -905,6 +912,8 @@ impl WatchlistScreen { seat: None, own_enters: 0, stale_enters: 0, + caption_policy: crate::registry::caption_policy_of(plx_plex::plex::session::UnderPosters::DEFAULT), + seen_rev: 0, } } @@ -1515,6 +1524,16 @@ impl Machine for WatchlistScreen { type Ev = ScreenEvent; fn step(&mut self, ev: &Self::Ev, cx: &Cx<'_, H>, fx: &mut Effects<'_, H>) -> Handled { + // **The page damages itself for what it draws that moved, and for nothing else.** A page that + // comes back from under a cover (`Uncover`, `Enter(Restored)`, a focus restored onto the + // key it already holds) raises none: typed page damage retakes a frozen host's snapshot, which + // is the cost a glass menu's BACK paid. What a covered page can have missed is its tiles and + // options (`rev`, moved by `input` and the count's release) and the Under posters setting + // (`policy_for`, read at draw), and both are answered here, on whichever event comes first. + let policy = crate::registry::moved(&mut self.caption_policy, crate::registry::captions::policy_for(H::screen_inputs(cx))); + if crate::registry::moved(&mut self.seen_rev, self.page.rev) | policy { + fx.invalidate(Provenance::Nav); + } let card = match self.stack.on(&self.page, ev, cx, fx) { Some(StackEvent::Card(_, card)) => Some(card), _ => None, @@ -1562,14 +1581,25 @@ impl Machine for WatchlistScreen { self.stale_enters = self.own_enters; } } - fx.invalidate(Provenance::Nav); + // A page that ARRIVES paints. One that returns (a modal's dismissal, BACK onto it) is + // the page it was, and paints again only for what `step`'s head found moved. + if matches!(enter, Enter::Fresh { .. }) { + fx.invalidate(Provenance::Nav); + } Handled::Yes } - ScreenEvent::Uncover => { - fx.invalidate(Provenance::Nav); + // Nothing the page draws changed by being uncovered: `rev` and the policy, read above, are + // what a cover can have hidden. + ScreenEvent::Uncover => Handled::Yes, + // A focus that did not move repaints nothing: a modal's dismissal re-enters the page, and + // `FocusEngine::enter` announces the key it already holds as `from == to`. + ScreenEvent::FocusMoved { from, to, .. } => { + if from.as_ref() != Some(to) { + fx.invalidate(Provenance::Input); + } Handled::Yes } - ScreenEvent::FocusMoved { .. } | ScreenEvent::StoreChanged(..) => { + ScreenEvent::StoreChanged(..) => { fx.invalidate(Provenance::Input); Handled::Yes } diff --git a/rust-modules/screens/src/watchlist/page_tests.rs b/rust-modules/screens/src/watchlist/page_tests.rs index ae68d75edd..4fd1feebdb 100644 --- a/rust-modules/screens/src/watchlist/page_tests.rs +++ b/rust-modules/screens/src/watchlist/page_tests.rs @@ -1391,3 +1391,50 @@ pub(crate) fn watchlist_conforms() -> plx_ui::a11y::Namespaces { assert_eq!(find("grid.0"), None, "a card is `grid.card.`"); namespaces } + +/// **The Watchlist comes back from a glass menu without damaging itself.** The BACK commit +/// delivers `Uncover`, then `Enter(Restored)` and a `FocusMoved` onto the key the page already +/// holds (`FocusEngine::enter`), to the host page; page damage raised by any of them retakes the +/// frozen host snapshot on the close's first frame (14.9M GPU cycles against an 11.2M budget on the +/// TV). What a covered page can have missed is its tiles and options (`rev`) and the Under posters +/// setting (read at draw, so `step`'s head compares it): both still damage, once, and a page that +/// ARRIVES (`Enter(Fresh)`) or a focus that really moves still paints. +#[test] +fn the_watchlist_raises_no_damage_coming_back_from_under_a_cover_unless_what_it_draws_changed() { + use crate::registry::captions::{PolicyPin, FIXTURE_TITLE_ON}; + use plx_machine::machine::{Enter, FocusTarget, GroupId}; + use plx_ui::screen::{By, ScreenEvent}; + let _guard = plx_base::testlock::serial(); + let mut h = Harness::new(tiles(6)); + h.run(30); + // the account menu is opened from the profile chip, a control: focus stands on one when the + // dismissal re-enters the page (a focus held on a CARD is the grid's own `FocusMoved` damage, + // `cards::Grid::on`, which a same-key restore still raises) + h.focus_elem(PILL_ELEM, By::Dir); + h.run(30); + let held = h.focus.expect("premise: a control holds focus"); + + assert!(!h.damages(ScreenEvent::Cover), "control: a cover raises none"); + assert!(!h.damages(ScreenEvent::Uncover), "an unchanged page has nothing to redraw on Uncover"); + assert!(!h.damages(ScreenEvent::Enter(Enter::Restored)), "...nor on Enter(Restored)"); + assert!(!h.damages(ScreenEvent::FocusMoved { from: Some(held), to: held, by: By::Restore }), + "...nor for the focus it already holds"); + + // the cards moved while covered: the tiles landed through `input` + h.screen.input(WatchlistIn::Rows(tiles(7))); + assert!(h.damages(ScreenEvent::Uncover), "a tile list that changed under the cover is redrawn"); + assert!(!h.damages(ScreenEvent::Enter(Enter::Restored)), "...once"); + + // Settings changed Under posters while it covered the page + { + let _setting = PolicyPin::set(FIXTURE_TITLE_ON); + assert!(h.damages(ScreenEvent::Uncover), "a caption policy that changed under the cover is redrawn"); + assert!(!h.damages(ScreenEvent::Enter(Enter::Restored)), "...once"); + } + h.run(30); + + // a focus that really moves, and a page that arrives, still paint + let next = h.screen.elem_at(1).expect("a second tile"); + assert!(h.damages(ScreenEvent::FocusMoved { from: Some(held), to: h.key(next), by: By::Dir })); + assert!(h.damages(ScreenEvent::Enter(Enter::Fresh { focus: FocusTarget::ContainerGroup(GroupId(0)) }))); +} diff --git a/rust-modules/src/app/account_menu_route_tests.rs b/rust-modules/src/app/account_menu_route_tests.rs index b221898ba9..77b1ab4ef3 100644 --- a/rust-modules/src/app/account_menu_route_tests.rs +++ b/rust-modules/src/app/account_menu_route_tests.rs @@ -78,12 +78,14 @@ fn dim_and_morph(w: &World) -> (f32, f32) { /// What the account panel's glass is DRAWN with this frame, as the surface's own morph states it: /// `(ground_alpha, dim, content_alpha)`. The glass's `ground_alpha` is 0 on the closed frame (before -/// the first step of an open, and from the frame the droplet is handed back to the chip to the -/// surface's removal), whatever the progress says: the slower rect spring is no longer "where the -/// glass is" (the open's width waits [`plx_ui::popover_morph::WIDTH_LAG`] while the height already +/// the first step of an open), whatever the progress says: the slower rect spring is no longer "where +/// the glass is" (the open's width waits [`plx_ui::popover_morph::WIDTH_LAG`] while the height already /// extends below the chip, and a close's width is back at the chip's by ~133 ms while the slab is -/// still draining under it). The opener rect only picks the droplet's geometry, which none of these -/// three read, so the chip's resting circle stands in for the one the rig has not drawn yet. +/// still draining under it). A close's closed frame is never read off the surface: the surface is +/// retired on the frame the droplet is handed back to the chip (`Screen::handed_back`), so from that +/// frame there is no surface and all three read 0. The opener rect only picks the droplet's geometry, +/// which none of these three read, so the chip's resting circle stands in for the one the rig has not +/// drawn yet. fn glass_and_own_dim(w: &World) -> (f32, f32, f32) { let chip = plx_ui::widgets::chip_cap(0.0, 0.0); crate::app::bridge::account_menu(&w.d) @@ -166,10 +168,12 @@ fn the_dim_and_the_glass_morph_open_and_close_on_one_clock() { assert!(close[1].1 < 1.0, "the glass's slab turns round on the first close frame: {close:?}"); assert!(close.iter().any(|(dim, _)| *dim < 0.5), "the dim falls: {close:?}"); // The glass is HANDED BACK to the chip on the first close frame its `ground_alpha` is 0: the - // closed frame, after the slab has drained into it. The rect's progress is back at 0 before that - // (the slab drains on), and the dim is out no later than the glass: it follows the slab's height, - // which the drain takes to nothing a frame or two before the fold lands, so a dim left on the - // page after the droplet is gone, or one outliving it by more than the last sliver, fails here. + // closed frame, after the slab has drained into it, which is also the frame the surface is + // retired on (nothing of it stands to read, so the readings are 0). The rect's progress is back + // at 0 before that (the slab drains on), and the dim is out no later than the glass: it follows + // the slab's height, which the drain takes to nothing a frame or two before the fold lands, so a + // dim left on the page after the droplet is gone, or one outliving it by more than the last + // sliver, fails here. let handed_back = close_glass.iter().position(|(ground, _, _)| *ground <= 0.0).expect("the droplet is handed back to the chip"); let dim_gone = close.iter().position(|(dim, _)| *dim <= 0.0).expect("the dim is gone"); assert!(dim_gone <= handed_back && handed_back - dim_gone <= 2, "the dim ({dim_gone}) is out no later than the glass ({handed_back}) and within its last sliver: {close:?}"); @@ -179,55 +183,167 @@ fn the_dim_and_the_glass_morph_open_and_close_on_one_clock() { } /// **The morph begins and ends on the chip AS THE BAR DRAWS IT, on every frame the menu is up** -/// (N-b, judgment 8): opened over the Watchlist, the popover's opener is the rect the lit chip is -/// drawn at (`bar_member_rect` through the host page's tuck; the tuck itself is graded by -/// `the_chips_drawn_rect_follows_the_bars_unfurl_and_tuck`), frame by frame through the open and the -/// close; and the CLOSED frame, the one before the glass first draws and the one the droplet is -/// handed back on, is that rect with a circle's corner (the chip at rest is a round surround, +/// (N-b, judgment 8): opened over the Watchlist by keys (the chip holds focus, so it is the lifted +/// opener, as in `the_profile_chip_opens_the_account_menu_by_keys_and_back_returns_focus_to_it`), the +/// popover's opener is the rect the lit chip is drawn at (`bar_member_rect` through the host page's +/// tuck; the tuck itself is graded by `the_chips_drawn_rect_follows_the_bars_unfurl_and_tuck`), frame +/// by frame through the open and the close; and the CLOSED frame the open begins on, the one before the +/// glass first draws, is that rect with a circle's corner (the chip at rest is a round surround, /// radius = half its height). /// /// The closed frame is the frame whose `ground_alpha` is 0, not the frame whose `progress` is: the /// open's height leads while the width waits its lag, so the glass is already a drop extending below -/// the chip (`ground_alpha` 0.5, 106 px tall) at progress 0, and a close's width is back at the -/// chip's by ~133 ms while the slab still drains into it from below. Both ends are counted apart, -/// since one counter was satisfied by the open alone and the close's end was never read. +/// the chip (`ground_alpha` 0.5, 106 px tall) at progress 0. +/// +/// The close has no closed frame to read, by design: the surface hands the chip back on the frame its +/// droplet is gone (`Screen::handed_back`, which `Surface::faded` reads), so the frame the morph would be +/// closed on is the frame the surface and the opener's lift leave on, and the chrome pass draws the chip. +/// Before that fix the surface stood ~17 frames more on closed frames, the lift painting the chip on the +/// stack's latched field (a lighter body) until the container's spring came to rest, and the chip snapped +/// darker in one frame (owner film, 2026-11-18). The close's end is read on both sides of that frame +/// instead. On the last frame glass is drawn the opener's re-formed blob (`Frame::merge`) is whole on +/// the chip's rect AS THE BAR DRAWS IT (centred, bottom edge on the chip's), the slab a sliver under its +/// centre and the opener's face back, and the lift still owns the chip. From the first frame after it +/// the surface and the lift are gone, and the bar draws the chip where it did before the menu opened. +/// Both ends are counted apart, since one counter was satisfied by the open alone and the close's end +/// was never read. #[test] fn the_morph_begins_and_ends_on_the_chip_as_the_bar_draws_it() { use plx_ui::dispatch::Rig; let mut w = World::watchlist("route-account-morph-rect"); w.land_watchlist(); w.settle(30); + let page = w.d.nav.top_page().map(|e| e.id).expect("a page"); let drawn = |d: &Dispatcher, owner: &mut crate::app::runtime_owners::Harness| { let bridge = owner.bridge(); let presented = bridge.navigation_presentation(&d.nav).tucked(d.top_screen().expect("a page").chrome_tuck()); bridge.bar_member_rect(TAB_KEY_CHIP, presented).expect("the chip is a bar member") }; - crate::app::bridge::open_account_menu(&mut w.d); - // frames read, and of them the closed ones, on the way in and on the way out - let (mut read, mut closed_in, mut closed_out) = (0, 0, 0); - let mut closing = false; - let mut watch = |w: &mut World, closing: bool| { + // by keys, as a person opens it: the chip holds focus, so it is the menu's opener on the lift decision + walk_to_the_chip(&mut w); + w.settle(30); + let at_rest = drawn(&w.d, &mut w.bridge); + // frames read, the closed ones on the way in and (there must be none) on the way out, the last + // frame glass is drawn on the way out with the chip as drawn then, whether the lift still owned + // the chip then, and the frame after BACK the surface left on + let mut read = 0; + let (mut closed_in, mut closed_out) = (0, 0); + let mut last_glass = None; + let mut lift_on_last = false; + let mut left_after = None; + // `back_at`: the frame of the BACK, once the close has begun + let mut watch = |w: &mut World, back_at: Option| { w.drawn(); // the dispatcher hands the surface the rect in its draw - let Some(menu) = crate::app::bridge::account_menu(&w.d) else { return }; + let Some(menu) = crate::app::bridge::account_menu(&w.d) else { + if let Some(back_at) = back_at { + left_after.get_or_insert(w.frame - back_at); + assert_eq!(w.d.lifted_opener(), None, "frame {}: the surface is gone, so is the lift: the bar draws the chip", w.frame); + } + return; + }; let Some(from) = menu.popover().opener() else { return }; let rect = drawn(&w.d, &mut w.bridge); assert_eq!(from, rect, "frame {}: the morph's opener is the chip as drawn", w.frame); let panel = plx_ui::popover::cover_opener(from, (316.0, 400.0), plx_ui::consts::SAFE); let f = menu.popover().morph_frame(Some(from), panel, 26.0).unwrap(); read += 1; + if back_at.is_some() { + assert!(!menu.popover().handed_back(), "frame {}: the droplet is handed back and the surface still stands", w.frame); + last_glass = Some((rect, f)); + let chip = plx_machine::machine::FocusKey { entry: page, elem: TAB_KEY_CHIP }; + lift_on_last = w.d.lifted_opener() == Some((page, Some(chip))); + } if f.ground_alpha == 0.0 { - if closing { closed_out += 1 } else { closed_in += 1 } + if back_at.is_some() { closed_out += 1 } else { closed_in += 1 } assert_eq!(f.rect, rect, "frame {}: with no glass drawn the frame IS the chip's rect", w.frame); assert_eq!(f.radius, rect.h * 0.5, "frame {}: and its corner the chip's round surround", w.frame); } }; - for _ in 0..80 { w.step(vec![]); watch(&mut w, closing); } + w.tap(Key::Ok, 0); + watch(&mut w, None); + for _ in 0..80 { w.step(vec![]); watch(&mut w, None); } assert!(crate::app::bridge::account_menu_up(&w.d), "premise: the menu is up"); w.tap(Key::Back, 0); - closing = true; - for _ in 0..80 { w.step(vec![]); watch(&mut w, closing); } + let back_at = w.frame; + for _ in 0..80 { w.step(vec![]); watch(&mut w, Some(back_at)); } assert!(!crate::app::bridge::account_menu_up(&w.d), "premise: it closed"); assert!(read > 20, "the opener was read on {read} frames"); assert!(closed_in > 0, "the open began on the chip: {closed_in} closed frames before the glass first drew"); - assert!(closed_out > 0, "the close ended on the chip: {closed_out} closed frames after the droplet was handed back"); + assert_eq!(closed_out, 0, "the close ended with the surface: {closed_out} frames stood closed, the droplet handed back and the opener's lift still painting the chip"); + // the surface left with its droplet (about 15 frames after BACK), not with the container's appear + // spring (a Sheet's rest, about 31) + let left = left_after.expect("the surface left"); + assert!(left < 24, "the surface left {left} frames after BACK"); + // the close ENDED ON THE CHIP as the bar draws it: on the last frame glass is drawn, the opener's + // re-formed blob is the chip's rect (anchored on its bottom edge, the one nearest the slab), whole, + // with the opener's own face back and the slab a sliver on the chip's centre + let (chip, last) = last_glass.expect("the close drew glass"); + let blob = last.merge.expect("the droplet drains into the opener's re-formed blob"); + assert!((blob.rect.cx() - chip.cx()).abs() < 0.01, "the blob is centred on the chip: {blob:?} on {chip:?}"); + assert!((blob.rect.y + blob.rect.h - (chip.y + chip.h)).abs() < 0.01, "the blob stands on the chip's bottom edge: {blob:?} on {chip:?}"); + assert!(blob.rect.w > chip.w * 0.9 && blob.rect.h > chip.h * 0.9, "the blob is the chip, whole: {blob:?} on {chip:?}"); + assert!(blob.tint > 0.95, "the blob wears the chip's own fill: {blob:?}"); + assert!(last.opener_alpha > 0.9, "the chip's own face is back: {last:?}"); + assert!((last.rect.cx() - chip.cx()).abs() < 0.01 && last.rect.w < chip.w * 0.2, "what is left of the slab is a sliver on the chip's centre: {:?} on {chip:?}", last.rect); + assert!(lift_on_last, "the lift still owned the chip on the last frame the surface stood"); + // and from there the bar draws the chip where it did before the menu opened + assert_eq!(drawn(&w.d, &mut w.bridge), at_rest, "the chip is back where the bar drew it"); +} + +/// Walk focus to the profile chip by keys (Up to the bar, Left along it). +fn walk_to_the_chip(w: &mut World) { + for _ in 0..14 { + if w.elem() == Some(TAB_KEY_CHIP) { break; } + w.press(if w.on_nav() { Key::Left } else { Key::Up }); + } + assert_eq!(w.elem(), Some(TAB_KEY_CHIP), "premise: the chip holds focus"); +} + +/// Walk focus to the profile chip by keys and open the account menu. +fn open_account_menu_from_the_chip(w: &mut World) { + walk_to_the_chip(w); + w.press(Key::Ok); + assert!(crate::app::bridge::account_menu_up(&w.d), "premise: the account menu is up"); + w.settle(40); +} + +/// Page-scope damage raised from the frame of a BACK on the open account menu through the close, +/// counted on the owning `Present` (`page_damage_epoch` never resets, so a swap cannot hide it). +fn page_damage_on_close(w: &mut World) -> u64 { + let before = w.d.present.page_damage_epoch(); + w.tap(Key::Back, 0); + w.frames(40); + assert!(!crate::app::bridge::account_menu_up(&w.d), "premise: BACK closed the menu"); + w.d.present.page_damage_epoch() - before +} + +/// **Closing the account menu with BACK raises no page damage.** The menu is a `Style::Sheet`, which +/// freezes the page under it, and typed page damage is what retakes that snapshot on the close's first +/// frame: the page redrawn into it, the tab bar's blur re-sourced, the dim re-latched (14.9M GPU +/// cycles against an 11.2M budget on the TV, a dropped frame on every close). The dismissal re-enters +/// the covered page, which hears `FocusMoved { from: Some(chip), to: chip, by: Restore }` (a move that +/// moves nothing) after its `RestoreMemory` re-armed the saved-place jump; Home answered with `Input` +/// page damage, and the Watchlist's `Uncover`, `Enter` and `FocusMoved` each damaged unconditionally +/// (`watchlist/page.rs`); both now damage only for what changed. The page damage the close raises is +/// what this rig can see of the host's snapshot: it runs no GL, so `popover::host`'s retake itself is +/// read at the host level (`popover_host_tests`), and a close with no typed damage re-takes nothing. +#[test] +fn closing_the_account_menu_with_back_raises_no_page_damage() { + let worlds: [(&str, fn() -> World); 6] = [ + ("home", || World::home_grid("route-account-quiet-home", 3, 5)), + ("library", || World::movies_library("route-account-quiet-library", false)), + ("recommended", || World::recommended("route-account-quiet-recommended")), + ("collections", || World::collections("route-account-quiet-collections", false)), + ("episodes", || World::episodes_library("route-account-quiet-episodes")), + ("watchlist", || World::watchlist("route-account-quiet-watchlist")), + ]; + let mut noisy = Vec::new(); + for (name, build) in worlds { + let mut w = build(); + w.settle(30); + open_account_menu_from_the_chip(&mut w); + let damage = page_damage_on_close(&mut w); + if damage != 0 { noisy.push((name, damage)); } + } + assert!(noisy.is_empty(), "BACK on the account menu damaged the page under it: {noisy:?}"); } diff --git a/rust-modules/src/app/bridge_test_support.rs b/rust-modules/src/app/bridge_test_support.rs index 0870779c8f..2112ddc0b9 100644 --- a/rust-modules/src/app/bridge_test_support.rs +++ b/rust-modules/src/app/bridge_test_support.rs @@ -222,10 +222,15 @@ impl Bridge<'_> { } impl World { + /// The one entry of every constructor: the serial lock, the scratch session, and a registry and + /// collections probe reset ON ENTRY (not only on drop: a test that panics on purpose, + /// `#[should_panic]`, never reaches its own closing reset and leaves its servers for the next world). fn lock(name: &str) -> (plx_base::testlock::Serial, plx_plex::plex::session::TempSession) { let serial = plx_base::testlock::serial(); let session = plx_plex::plex::session::TempSession::new(name); session.watching(&format!("u-{name}")); + plx_plex::plex::reset_servers_for_test(); + crate::app::collections_probe::clear_seeds_for_test(); (serial, session) } @@ -246,8 +251,6 @@ impl World { /// left as a section nothing has published for yet: the Recommended page's FIRST publication. fn build_shelves(name: &str, two_libraries: bool, answered: bool, shelved: bool) -> World { let (serial, session) = Self::lock(name); - plx_plex::plex::reset_servers_for_test(); - crate::app::collections_probe::clear_seeds_for_test(); let own = plx_plex::plex::register_for_test("route-own", "127.0.0.1", 9, "synthetic", "fixture"); let shared = plx_plex::plex::register_for_test("route-shared", "127.0.0.1", 10, "synthetic", "fixture"); plx_plex::plex::set_current(own); @@ -926,3 +929,22 @@ impl Bridge<'_> { session::publish_profile_for_test(Some(user), session::current_gen().wrapping_add(1)); } } + +/// **A world starts over an empty server registry, whatever the test before it left in it.** The +/// registry is process-wide and a `#[should_panic]` test cannot reach its closing +/// `reset_servers_for_test()` (the hubs-dump discovery test registers one server and panics by +/// design), so the next world built over a scripted plex.tv (`scripted`, `watchlist_built`) used to +/// inherit that server: Home's heading rest then depended on which test won the serial lock between +/// two of `a_resting_heading_is_always_clear_of_the_chrome`'s worlds. Every constructor resets on +/// entry through [`World::lock`], and the test below leaks a server the way that test does. +#[test] +fn a_world_starts_over_an_empty_server_registry_whatever_a_panicking_test_left() { + { + let _serial = plx_base::testlock::serial(); + plx_plex::plex::reset_servers_for_test(); + plx_plex::plex::register_for_test("left-by-a-panic", "127.0.0.1", 9, "synthetic", "cid"); + assert_eq!(plx_plex::plex::server_count(), 1, "premise: a server is left registered, as a panic leaves it"); + } + let _scripted = World::home_with_disc("world-clean-start-scripted", [7; 12]); + assert_eq!(plx_plex::plex::server_count(), 0, "a world over a scripted plex.tv registers none of its own and inherits none"); +} diff --git a/rust-modules/src/app/run.rs b/rust-modules/src/app/run.rs index c757a1728a..a81b0f921f 100644 --- a/rust-modules/src/app/run.rs +++ b/rust-modules/src/app/run.rs @@ -3184,7 +3184,9 @@ pub(crate) unsafe fn draw(app: &mut App, fr: &mut Frame) -> (i32, i32, i32, i32) // is no framebuffer to snapshot. Skip the door instead of tripping the // debug assertion. A popover from this page halts the preview first, so // this frame only skips while the picture is the intended ground. - let modal = pages.modal_presentation(); + // Carrying the frame's lowest modal dim, the value `draw_scrims` is handed below: the host bakes + // a glass menu's frost body from it at the head of the frame (`begin_frame`). + let modal = pages.modal_presentation_at(bridge.navigation_presentation(&pages.nav).page_alpha); if !(player.video_plane_bound && plx_media::route::is_preview(&player.session)) { plx_base::diag::spans::span("host", || plx_ui::popover::host::begin_frame( &modal, fr.dt, fr.underlay_moving, pages.present.page_damaged())); diff --git a/rust-modules/ui/src/CLAUDE.md b/rust-modules/ui/src/CLAUDE.md index 67eda52d87..248879c8ee 100644 --- a/rust-modules/ui/src/CLAUDE.md +++ b/rust-modules/ui/src/CLAUDE.md @@ -475,13 +475,17 @@ presentation in a design pass. smaller side while small, relaxing to THE CALLER'S panel radius from ~150 ms by a spring that lands exactly, so settle does not snap; a close rounds it back), a 0.92 -> 1 fade+scale fallback (with its own 0.82 -> 1 rows spring) when the opener has no rect. The glass is laid whole at the - morphing rect, clear then frosted by ~150 ms, and the rows are laid out IN the glass: they are - magnified by the lens (their own spring: 0.65 when they first show, ~1.12 at ~167 ms, 1 by ~360 ms), - appear at ~75 ms and are opaque by ~150 ms, cut by the lens itself (its rect and radius, through + morphing rect and is FROSTED the whole way, never clear (owner, 2026-11-18: the body is the frost + under the dark face on every frame of the open and the close, until the close's hand-back; the + frost is asked for on the open's first frame, before the field has latched, so it is built at the + head of the next one, and a frame it is still owed wears the field under the heavier face), and the + rows are laid out IN the glass: they are + magnified by the lens (their own spring: ~0.2 when they first show, 0.65 at 67 ms, ~1.12 at ~167 ms, 1 by ~360 ms), + appear from the third glass frame (~33 ms) and are opaque by ~120 ms, cut by the lens itself (its rect and radius, through the shared painter's ROUNDED clip, `ClipScope::open_rounded_in`: a letter the round edge crosses is cut by the arc, not a straight edge). A close bulges ~7% by ~33 ms (width and height on their own springs, fitted to the recording's close), then the slab shrinks with its rows - and frost leaving over ~50 ms and drains into the opener (hand-back at ~233 ms; the drawn series is what the close test fits). The modal dim of a + leaving over ~50 ms (the frost stays) and drains into the opener (hand-back at ~233 ms; the drawn series is what the close test fits). The modal dim of a morphing menu FOLLOWS the morph (`Popover::dim` -> `Scrim::following`: in by ~150 ms, out with the slab), not the container's appear spring; a screen's `scrim()` returns `self.popover.dim(DIM_*)`. **The header menus' glass CONSUMES its opener (owner decision 2026-11-17, reversing design @@ -676,19 +680,26 @@ tried first. None of it is reconstructable from the code without repeating the m under the frost. The choice is explicit at each call, `widgets::Ground::Menu` or `Ground::Sheet` (`panel_ground`'s last argument, `Popover::panel`'s too); there is no global switch. A `Menu` ground's first act is `popover_glass::draw`: `fs_glass.frag`'s composite through - `gfx::draw_glass_frozen`, wearing a gradient face (`FACE_TOP`/`FACE_BOT`), the 1 px - `theme::GLASS_RIM`, the lit top edge `GLASS_RIM_LIGHT` and `GlassRim::Menu`, then a soft shadow - cut out around the panel's rounded shape. **It reads no framebuffer** (owner decision, - 2026-10-17: menus stand on main's frozen ground and never live-refract a re-rendered page). Its - body shows the latched underlay field (`ui::underlay`, the 60x32 reconstruction the modal dim - draws, reaching a surface as `DrawFrame::underlay`); its rim's lens refracts the host snapshot + `gfx::draw_glass_frozen`, wearing a gradient face (`FROST_FACE`, `theme::MENU_GLASS_TOP/BOT`, + .36/.44), the 1 px `theme::GLASS_RIM`, the lit top edge `GLASS_RIM_LIGHT` and `GlassRim::Menu`, + then a soft shadow cut out around the panel's rounded shape. **It reads no framebuffer** (owner + decision, 2026-10-17: menus stand on main's frozen ground and never live-refract a re-rendered + page). Its body is the host's FROST (`popover::host::frost`): one blur of the frozen page per + snapshot (`FrameCache::frost_build_owed`, phase `glass.frost_build`) with the frame's lowest modal + dim and `theme::FROST_BODY_CEILING` baked in (`FrameCache::frost_bake_owed`, phase `glass.bake`, on + the frames where the dim moves and never at rest), so under `PLX_FROST` the composite returns the + baked texel for the body (no `dimRGB`, no cap). Its rim's lens refracts the host snapshot (`popover::host::page_tex`, the one capture of the undimmed page) with the SAME rounded-rect SDF that rounds the panel, at `tokens::MENU_SHARP`; the frame's one modal dim (noted by - `Painter::dim`) is applied to both at composite (`u_dim`, and `u_dim_sharp` for the snapshot). + `Painter::dim`) is applied at composite to that sharp source only (`u_dim_sharp`). **The latched + underlay field** (`ui::underlay`, the 60x32 reconstruction the modal dim draws, reaching a + surface as `DrawFrame::underlay`) **under `FACE_TOP`/`FACE_BOT`** (`MENU_GLASS_FIELD_TOP/BOT`, + .78/.86) **is the FALLBACK body**, worn by a glass with no frost: before the first build, with the + variant unlinked, or after a failed build or bake (it takes the dim at composite, `u_dim`). So a menu requests no backdrop entry, runs no blur source pass (`src`, `pagex2`) and copies no - band (`glass.sharp`): its open, stay and close cost one panel quad (profiler phase - `glass.frozen`) and its shadow, and a morph or a slide moves that quad over pictures that do not - change. What the pictures do not hold, the glass does not show: an opener lifted over the dim + band (`glass.sharp`): at rest it costs one panel quad (profiler phase `glass.frozen`) and its + shadow, its open adds one frost build and the dim ramp's bakes, its close adds the bakes, and a + morph or a slide moves that quad over pictures that do not change. What the pictures do not hold, the glass does not show: an opener lifted over the dim (the item menu's card, the account chip) is absent from the lens, and a menu stacked over another surface's dim, or drawn before the field has latched (the first frames of a modal), or over the video plane, falls back to the field ground (`draw` returns `false`), windowed to the @@ -696,15 +707,20 @@ tried first. None of it is reconstructable from the code without repeating the m menu's profile chip, lifted above the dim and the panel (`widgets::lift_profile_chip`, called by the lift pass through `Rig::lift_bar_member`), is a `glass_frozen` capsule (no dim, the host snapshot behind its rim) and requests no backdrop entry or `src` pass. - **The lift owns the chip from the frame its menu mounts to the frame it is removed**: the chrome + **The lift owns the chip from the frame its menu mounts to the frame it is removed** (for a morphing menu + the frame its droplet is gone, `Screen::handed_back` -> `Popover::handed_back`: the container retires the + surface then, `Surface::faded`, not when its appear spring comes to rest, so the chip changes hands once + on the frame nothing else of the menu draws): the chrome pass leaves it out (`Rig::draw_chrome`'s `lifted`) for all of them, so the host snapshot never holds a chip the panel's rim would refract, the snapshot is re-taken on the mount and the removal and nowhere between, and the lift paints it on every one of those frames. What it stands on is chosen where it paints (`widgets::lift_ground`): the stack's latched field (`ModalStack::lift_field`) - once that has latched, the host snapshot drawn CLEAR (`GlassMorph::clear`, the morph's own opening - material) before, a flat capsule if neither exists. Only the chip on the tab strip, with no menu up, is live glass. The scrim behind a compact menu is + once that has latched, the host snapshot drawn CLEAR (`GlassMorph::clear`, which this lift alone uses now: + the morph's own glass is never clear) before, a flat capsule if neither exists. Only the chip on the tab strip, with no menu up, is live glass. The scrim behind a compact menu is `theme::underlay::DIM_COMPACT`, 30%. The face colours and shadow are theme roles - (`MENU_GLASS_TOP/BOT`, `MENU_SHADOW*`); the face fades with the panel's cascaded alpha. + (`MENU_GLASS_TOP/BOT` over the frost, `MENU_GLASS_FIELD_TOP/BOT` over the fallback field, + `MENU_SHADOW*`), so editing `FACE_TOP`/`FACE_BOT` restyles only the fallback; the face fades + with the panel's cascaded alpha. `GlassRim::Menu` over the LIVE path (`draw_blur_backdrop`) would turn on a per-frame sharp band copy; no menu takes that path any more. A source-grep test (`widgets_glass_budget_tests`) keeps `Glass` and `Painter::backdrop_blur` out of every file except the chrome list — no popover and no screen @@ -713,9 +729,10 @@ tried first. None of it is reconstructable from the code without repeating the m - **Glass over a page stands on the frozen host; the page does not move while a menu is up, except under a menu that lets it reflow.** - A menu (opening, open or closing, until it has let go of the host at `CLOSING_GONE`) stands on - the page as the host snapshot holds it (`popover.rs` module doc, "A modal stands on a page that is - not moving"): nothing on the page animates, reflows or lands under it. A layout motion a menu's + A menu (opening, open or closing, until it has let go of the host: a morphing menu on the frame + its droplet is handed back, `Screen::handed_back`; any other menu when its fade drops below + `CLOSING_GONE`) stands on the page as the host snapshot holds it (`popover.rs` module doc, "A + modal stands on a page that is not moving"): nothing on the page animates, reflows or lands under it. A layout motion a menu's choice starts (the Watchlist's Remove) and the data that would change the page (the app's `watchlist_feed`) wait until the menu is gone and start on the first frame after (the owning stack's captured `cx.modal.page_veiled()`). **The one exception is a surface whose body answers @@ -723,7 +740,8 @@ tried first. None of it is reconstructable from the code without repeating the m reflows under it, the host is drawn live while the cards move (`popover::host::set_reflow`: no per-frame capture, `page_epoch` does not move) and is retaken ONCE when they stop, the old look fading into the new ground over `host::CROSSFADE_S` from a second retained copy. The menu's glass samples only that frozen ground (above), so - even a page that did move under it would rebuild nothing for the glass. **Do not add new + while the page moves under it nothing is rebuilt for the glass (the old frost is served); each + host retake moves `page_epoch` and costs one frost rebuild and a bake. **Do not add new live-refracting glass over a page unless the owner asks.** Live glass measured about 2 to 2.6M Mali GPU cycles per frame more than frozen ground (2026-10-17, release build, mock, panel off), with the page re-drawn at quarter resolution on each frame its draws changed (the `src` and diff --git a/rust-modules/ui/src/containers/modal.rs b/rust-modules/ui/src/containers/modal.rs index cdb1247319..61ccde3934 100644 --- a/rust-modules/ui/src/containers/modal.rs +++ b/rust-modules/ui/src/containers/modal.rs @@ -15,8 +15,9 @@ //! A surface's LIFT (the element it was opened from) is drawn by the dispatcher's one lift pass //! (`Z::OPENER`), after every surface, so a panel never covers the element it grows out of. The //! host page's own opener (`Screen::opener`) is drawn in that same pass, by the dispatcher. -//! - `prune()` clears a Closing surface once its fade settles (a page opening over one retires it -//! at once instead: `Navigation::commit`), so Closing surfaces step unconditionally (the +//! - `prune()` clears a Closing surface once its fade settles, or once its body has handed its +//! opener back (`Surface::faded`, `Screen::handed_back`: a morph menu's droplet is gone) (a page +//! opening over one retires it at once instead: `Navigation::commit`), so Closing surfaces step unconditionally (the //! fade must finish whatever the host is doing) — `the_closing_phase_is_stepped_even_when_the_host_is_frozen`. //! - `on_miss(style)` is consulted only while the surface is `Open`: a click beside a Compact, //! Sheet or PlayerPanel dismisses it; an Alert ignores the miss; an Opaque surface swallows it. @@ -250,10 +251,19 @@ impl PopoverMotion { } impl Surface { - /// A menu (`Compact`) dismissed and faded past [`CLOSING_GONE`]: draws nothing, owes its host - /// no dim. Only menus: a sheet's or an opaque surface's close is decided by the spring's rest. + /// A surface dismissed and already GONE: draws nothing, owes its host no dim. Two ways: + /// + /// - a menu (`Compact`) faded past [`CLOSING_GONE`] on the container's appear spring; a sheet's + /// or an opaque surface's close is otherwise decided by the spring's rest; + /// - a surface whose body has HANDED BACK its opener ([`Screen::handed_back`](crate::screen::Screen::handed_back)): + /// the morph's droplet is gone, whatever the spring still says. The morph is not faded by the + /// container's appear (it begins and ends as the opener), so that spring's tail is a surface + /// with nothing to draw; waiting for it kept the opener's lift (frozen glass, a lighter body) + /// in the opener's place for about twice as long as the droplet's own close. pub fn faded(&self) -> bool { - self.phase == Phase::Closing && self.style == Style::Compact && self.motion.gone() + self.phase == Phase::Closing + && ((self.style == Style::Compact && self.motion.gone()) + || self.entry.inst.as_ref().is_some_and(|i| i.screen.handed_back())) } } @@ -318,10 +328,11 @@ pub const CLOSING_GONE: f32 = plx_machine::machine::MODAL_CLOSING_GONE; pub struct ModalPresentation { pub read: plx_machine::machine::ModalRead, pub reflow: bool, + /// **The frame's lowest modal dim, as a value** ([`ModalStack::first_dim`]): what the host bakes the + /// frost's body from at the head of the frame, before `draw_scrims` paints it. `None` unless the + /// owner asked for it ([`Dispatcher::modal_presentation_at`](crate::dispatch::Dispatcher)). + pub dim: Option, key: ModalCacheKey, - /// The caching layers whose style kept the host live while open ([`Self::kept_host_live`]); not - /// part of the cache key, which is identity only. - live_hosts: Vec, } /// GL snapshot signature only. Never consulted for phase, policy, veil or input decisions. #[derive(Clone, Debug)] @@ -333,37 +344,26 @@ impl ModalCacheKey { pub fn same_snapshot(&self, other: &Self) -> bool { std::sync::Arc::ptr_eq(&self.owner, &other.owner) && self.layers == other.layers } - /// The layers that STARTED closing between this key and `other`, when `other` is this key's - /// stack with the same layers, some of which started closing and none of which came or went (a - /// layer is `(entry, closing)`); `None` for any other change. What a dismissal changes and - /// nothing else. Whether the host cache may then keep the page's snapshot is not the key's to - /// say (it holds identity only): `popover::host::bind_owner` asks the presentation, through - /// [`ModalPresentation::kept_host_live`], about each layer returned. - pub fn began_closing(&self, other: &Self) -> Option> { + /// Is `other` this key's stack with the same layers, some of which STARTED closing and none of + /// which came or went (a layer is `(entry, closing)`)? What a dismissal changes and nothing + /// else: `false` for any other change. + pub fn began_closing(&self, other: &Self) -> bool { if !std::sync::Arc::ptr_eq(&self.owner, &other.owner) || self.layers.len() != other.layers.len() { - return None; + return false; } - let mut began = Vec::new(); + let mut began = false; for (a, b) in self.layers.iter().zip(&other.layers) { // the same layer, which may only have STARTED closing (never un-closed) if a.0 != b.0 || (a.1 && !b.1) { - return None; - } - if !a.1 && b.1 { - began.push(a.0); + return false; } + began |= !a.1 && b.1; } - Some(began) + began } } impl ModalPresentation { pub fn cache_key(&self) -> ModalCacheKey { self.key.clone() } - /// Did the caching layer `id` keep the host LIVE while it was open (`surface_policy(style, Open, - /// _).0 == Live`, which is `Style::Compact`)? Then the page snapshot it leaves is as current as - /// the page, and its close may keep it. A Sheet, an Alert or an `Opaque` snapshot surface froze - /// the host, which got no Tick, so what it leaves is as old as the surface. False for a layer - /// this presentation does not hold, which `bind_owner` answers with the full `invalidate()`. - pub fn kept_host_live(&self, id: EntryId) -> bool { self.live_hosts.contains(&id) } } // Veil is captured by ModalStack::presentation before pages tick. Consumers read Cx.modal; @@ -475,6 +475,14 @@ pub trait DimSink { fn in_flight(&mut self, pending: bool); /// Paint one surface's dim through `field` at `alpha`. fn dim(&mut self, field: &crate::underlay::UnderlayField, alpha: f32); + /// The frame's lowest dim as the field stands once [`ModalUnderlay::sync`] has run, i.e. the dim the + /// glass is about to composite under. The host baked a glass menu's frost body at the head of the + /// frame from a PREDICTION of it (`ModalStack::first_dim` before the sync), and a field that + /// latched in this very sync makes the prediction wrong: the glass then draws that body for one + /// frame (`popover_glass::draw_shadowed`). Nothing else presents the frame whose head bakes the right + /// one, so the sink does: on a frost baked for another dim it keeps the loop turning for exactly + /// that one frame, the way [`in_flight`](Self::in_flight) does for the read itself. + fn dim_settled(&mut self, dim: Option); } /// The production [`DimSink`]. @@ -525,6 +533,11 @@ impl DimSink for GlDims<'_> { self.present.note(plx_machine::present::PresentEvent::Wake); } } + fn dim_settled(&mut self, dim: Option) { + if crate::popover::host::frost_body_stale(dim) { + self.present.note(plx_machine::present::PresentEvent::Wake); + } + } fn dim(&mut self, field: &crate::underlay::UnderlayField, alpha: f32) { field.draw( crate::Painter::root(), @@ -689,13 +702,10 @@ impl ModalStack { veil: veil_of(&self.surfaces), }, reflow: false, + dim: None, key: ModalCacheKey { owner: self.presentation_owner.clone(), layers: self.surfaces.iter().filter(|s| holders.contains(&s.entry.id)) .map(|s| (s.entry.id, s.phase == Phase::Closing)).collect() }, - live_hosts: self.surfaces.iter() - .filter(|s| holders.contains(&s.entry.id) - && surface_policy(s.style, Phase::Open, false).0 == HostUpdate::Live) - .map(|s| s.entry.id).collect(), } } @@ -1000,6 +1010,13 @@ impl ModalStack { // surface on a frame that captured nothing still queues nothing. if !dims.is_empty() || source != Some(UnderlaySource::Page) || sink.captured() { plx_base::diag::spans::span("ulatch", || self.underlay.sync(source, sink)); + // The field may have latched in that sync, after the head of the frame predicted the dim + // the frost body was baked for: tell the sink what the glass will composite under. + // Only a page-sourced dim has a frost under it: the player's flat dim is drawn on a frame + // that never bakes one, and a frost left standing must not wake it every frame. + if let Some(&(_, a)) = dims.first().filter(|_| source == Some(UnderlaySource::Page) && !sink.video_plane()) { + sink.dim_settled(Some(self.underlay.field().dim_of(crate::theme::underlay::TINT, a))); + } } for (id, a) in dims { let index = self.surfaces.iter().position(|s| s.entry.id == id).unwrap_or(0); @@ -1009,6 +1026,16 @@ impl ModalStack { } } + /// **The frame's lowest modal dim as a value**: the first of [`scrims`](Self::scrims), resolved through + /// the stack's latched field exactly as [`draw_scrims_on`](Self::draw_scrims_on) paints it + /// (`underlay::UnderlayField::dim_of`, the one function both read), so the frost body baked from it + /// at the head of the frame is the body the glass composites under that paint. `None`: no surface + /// dims. Pure: reads the stack and its field, draws and samples nothing. + pub fn first_dim(&self, nav_page_alpha: f32) -> Option { + let (_, alpha) = *self.scrims(nav_page_alpha).first()?; + Some(self.underlay.field().dim_of(crate::theme::underlay::TINT, alpha)) + } + /// Where the stack's field inherits from: the BOTTOM surface that declares a dim — it is the /// one whose dim lies directly on the host, and every dim above it lies over the same page. /// `None` when no surface declares one. Asked whatever the surface's appear; the READ waits for diff --git a/rust-modules/ui/src/containers/tests.rs b/rust-modules/ui/src/containers/tests.rs index c5b736eaca..21a8059afa 100644 --- a/rust-modules/ui/src/containers/tests.rs +++ b/rust-modules/ui/src/containers/tests.rs @@ -267,6 +267,98 @@ fn the_chip_is_painted_exactly_once_on_every_frame_of_its_menus_open_and_close() assert_eq!(host::invalidations() - retakes, 1, "the chip changed hands back"); } +/// **A glass menu's surface, and so the opener's lift, ends on the frame its droplet is gone** (owner +/// film, 2026-11-18: the profile chip, handed back by the account menu's close, stood LIGHTER than its +/// resting look for ~300 ms and then snapped darker in one frame). The morph's close is over when the +/// slab has drained into the opener (`Morph::closed`: the frame IS the closed frame, the opener at rest, +/// no glass, no dim), but the surface was retired only when the CONTAINER's appear spring came to rest: +/// a Sheet (the account menu) about 31 frames after BACK, the droplet's hand-back about 14. For those +/// ~17 frames the lift still owned the chip and painted it on the stack's latched field (frozen glass, +/// a lighter body than the tab strip's live glass, which the chrome pass paints once the lift lets go), +/// so the one-frame step at the end of the lift was the chip changing material. +/// +/// The surface answers `Screen::handed_back` and the container retires it then, so the lift and the +/// chrome pass change hands exactly once, on the frame nothing else of the menu is drawn. The real +/// path: BACK, `NavOp::Dismiss`, `ScreenEvent::Closing`, `Popover::dismiss`, the morph's close springs +/// stepped by every `Tick`, the bar opener's rect handed in by the lift pass. +/// +/// Red on the tree where only the spring's rest retired a Closing Sheet: the surface was still in +/// the stack with its droplet gone, frame after frame. +#[test] +fn a_morph_menus_surface_and_lift_end_on_the_frame_its_droplet_is_gone() { + // the account menu is a Sheet; the Library's and the Watchlist's menus are Compact (their own + // fade retired them at `CLOSING_GONE`, still after the droplet): one rule for every style + for style in [Style::Sheet, Style::Compact] { + a_morph_surface_ends_with_its_droplet(style); + } +} + +fn a_morph_surface_ends_with_its_droplet(style: Style) { + use crate::Rect; + let _guard = plx_base::testlock::serial(); + struct PopoverOff; + impl Drop for PopoverOff { + fn drop(&mut self) { crate::fixture::modal_owns_popover(false); } + } + crate::fixture::modal_owns_popover(true); + let _off = PopoverOff; + let (mut d, mut rig, _) = booted(); + let mut ms = 16; + let mut step = |d: &mut Dispatcher, rig: &mut FixtureRig, keys: Vec<_>| { + ms += 16; + let r = d.frame(rig, tick(ms), keys, vec![], &mut NoTap); + d.draw(rig, true); + d.prune(&r.unmounted); + }; + // the chip is the page's focus when its menu opens, and BACK gives it back (the lift stands down + // for a close only once focus has moved off its opener): the fixture page's seat stands for it + let home = d.nav.top_page().unwrap().id; + let chip = 0; + d.set_focus(Some(FocusKey { entry: home, elem: chip })); + d.nav.next_style = style; + d.request(MachineId::Nav, NavOp::Present(FixtureArg::Modal)); + step(&mut d, &mut rig, vec![]); + let id = d.nav.modals.top().expect("presented").entry.id; + modal_mut(&mut d, id).bar_opener = Some(chip); + for _ in 0..90 { step(&mut d, &mut rig, vec![]); } + let panel = Rect::new(60.0, 120.0, 520.0, 400.0); + { + let pop = modal_of(&d, id).popover.as_ref().expect("the menu's popover"); + assert!(pop.appear_settled() && pop.opener().is_some(), "premise: the droplet's panel stands over a measured opener"); + assert_eq!(rig.chrome_lifted.last(), Some(&Some(chip)), "premise: the lift owns the chip while the menu stands"); + } + + step(&mut d, &mut rig, vec![key(Key::Back, tick(0))]); + assert_eq!(d.nav.modals.top().expect("still closing").phase, Phase::Closing); + // the slab is gone: the frame IS the closed one, exactly what a morph that never opened draws + // (the opener at rest: no glass, no dim, its face whole) + let droplet_gone = |d: &Dispatcher| { + let pop = modal_of(d, id).popover.as_ref().expect("the menu's popover"); + let f = pop.morph_frame(pop.opener(), panel, 24.0).expect("a morphing popover"); + Some(f) == crate::popover::Popover::new().morphing().morph_frame(pop.opener(), panel, 24.0) + }; + let mut asked = 0; + let mut left_after = None; + for n in 1..=120 { + let lifts = rig.bar_lifts.len(); + step(&mut d, &mut rig, vec![]); + asked += rig.bar_lifts.len() - lifts; + if d.nav.modals.top().is_none() { + left_after = Some(n); + break; + } + assert!(!droplet_gone(&d), "{style:?}, frame {n} after BACK: the droplet is gone and the surface still stands (the lift still owns the chip)"); + } + let n = left_after.expect("the surface left"); + // BACK to the hand-back is the droplet's own close (~233 ms, 14 frames at 60 Hz), not the container's spring's rest (31) + assert!(n < 24, "{style:?}: the surface left {n} frames after BACK"); + assert!(asked > 0, "premise: the lift painted the chip while the droplet drained into it"); + assert_eq!(rig.chrome_lifted.last(), Some(&None), "from the first frame after the surface the chrome pass paints the chip: the lift lets it go once"); + let lifts = rig.bar_lifts.len(); + step(&mut d, &mut rig, vec![]); + assert_eq!(rig.bar_lifts.len(), lifts, "and the lift is not asked again"); +} + #[test] fn a_bar_opener_does_not_draw_over_an_opaque_surface_that_is_arriving() { use super::modal::{EntryMotion, PopoverMotion}; @@ -339,6 +431,24 @@ fn the_scrim_ladder_scales_by_appear_and_the_route_dip() { assert!((d.nav.modals.scrims(1.0)[0].1 - 0.5).abs() < 1e-6); } +/// **The frame's lowest dim as a pure value** (`ModalStack::first_dim`, which the host bakes the frost's +/// body from at the head of the frame): the first of `scrims` at the same alpha, through the stack's +/// field. Nothing latched, that is the flat scrim ink at that alpha (`underlay::plan`'s contract); a +/// surface that dims nothing, or an empty stack, has none. +#[test] +fn the_lowest_dim_value_is_the_first_scrim_through_the_stacks_field() { + let (mut d, mut rig, _) = booted(); + assert_eq!(d.nav.modals.first_dim(1.0), None, "no surface, no dim"); + let id = open_modal(&mut d, &mut rig, Style::Sheet, 16); + assert_eq!(d.nav.modals.first_dim(1.0), None, "a surface that declares no dim owes none"); + modal_mut(&mut d, id).scrim_alpha = 0.5; + d.nav.modals.surface_mut(id).unwrap().motion = super::modal::PopoverMotion::at(0.4); + let dim = d.nav.modals.first_dim(1.0).expect("a ramping dim"); + assert_eq!((dim.tex, dim.tint), (0, crate::theme::scrim_black(d.nav.modals.scrims(1.0)[0].1)), "unlatched: the flat ink"); + assert!((dim.tint[3] - 0.2).abs() < 1e-6, "at the ramp's alpha, got {}", dim.tint[3]); + assert!((d.nav.modals.first_dim(0.5).unwrap().tint[3] - 0.1).abs() < 1e-6, "and the route dip rides it"); +} + // ── The inherited dim: one field per stack, latched from a page no dim has touched ──────────── /// A framebuffer that remembers what was painted on it: one grey level, darkened by every dim @@ -361,6 +471,12 @@ struct FakeFb { in_flight: bool, /// Did this frame capture the host (`DimSink::captured`)? captured: bool, + /// The dim the host's frost body was last baked for (`None`: no frost stands): what + /// `popover::host::begin_frame` bakes from `ModalStack::first_dim` at the head of a frame + /// ([`FakeFb::head`]). + baked: Option>, + /// Frames asked for because a frost body was baked for another dim (`DimSink::dim_settled`). + wakes: u32, } impl FakeFb { @@ -376,8 +492,15 @@ impl FakeFb { reduced: 0.0, in_flight: false, captured: false, + baked: None, + wakes: 0, } } + /// The head of a frame: the host bakes the frost's body from the pure prediction of the lowest dim, + /// before this frame's sync (`bake_frost`). + fn head(&mut self, d: &Dispatcher) { + self.baked = Some(d.nav.modals.first_dim(1.0)); + } /// The previous frame is swapped and the page is drawn again (live, or served from the /// snapshot) at the start of the next. fn frame(&mut self, level: f32) { @@ -424,6 +547,11 @@ impl super::modal::DimSink for FakeFb { self.events.push("dim"); self.level *= 1.0 - alpha; } + fn dim_settled(&mut self, dim: Option) { + if self.baked.is_some_and(|b| b != dim) { + self.wakes += 1; + } + } } fn two_dimming_sheets(d: &mut Dispatcher, rig: &mut FixtureRig) -> (EntryId, EntryId) { @@ -510,6 +638,85 @@ fn the_page_read_lands_a_frame_after_it_is_queued_and_holds_the_ground_until_the assert!(!fb.in_flight, "landed: the ground may be taken and the loop may rest"); } +/// **A frost body baked for a dim the field then changed is corrected by one more frame, and no more.** +/// The host bakes the body at the head of a frame from `first_dim` BEFORE the sync, and the read a +/// settled menu waits on lands inside that sync (`FIELD_READ_LAG_SWAPS`): the glass draws the old body +/// for that frame (`draw_shadowed`'s stale case, which holds the ground), and the head that bakes the +/// right one only comes if a frame is presented. Nothing else guarantees one — the appear spring has +/// rested and the keepalive is two seconds away — so `DimSink::dim_settled` asks for it, once. +/// +/// Observed RED with `draw_scrims_on` not telling the sink: `wakes` stayed 0 on the landing frame. +#[test] +fn a_frost_body_baked_before_the_field_latched_is_redrawn_once_and_then_the_loop_rests() { + let (mut d, mut rig, _) = booted(); + let _stand_in = crate::underlay::stand_in_upload_for_test(7); + let a = open_modal(&mut d, &mut rig, Style::Sheet, 16); + modal_mut(&mut d, a).scrim_alpha = 0.5; + d.nav.modals.surface_mut(a).unwrap().motion = super::modal::PopoverMotion::at(1.0); + let mut fb = FakeFb::new(0.5); + + // The capture frame queues the read; the head baked the flat ink, which still IS the dim. + fb.captured = true; + fb.head(&d); + dims_frame(&mut d, &rig, &mut fb); + assert_eq!(fb.wakes, 0, "nothing latched yet: the prediction holds"); + + // The read lands inside this frame's sync, after the head baked from the unlatched field. + fb.frame(0.5); + fb.captured = false; + fb.head(&d); + dims_frame(&mut d, &rig, &mut fb); + assert!(d.nav.modals.underlay.field().is_latched(), "the read landed"); + assert_eq!(fb.wakes, 1, "the body was baked for the flat ink and the glass drew the field's: one more frame"); + + // That frame's head bakes from the latched field: the prediction holds, and the loop rests. + for _ in 0..3 { + fb.frame(0.5); + fb.head(&d); + dims_frame(&mut d, &rig, &mut fb); + } + assert_eq!(fb.wakes, 1, "redrawn once, then quiet"); +} + +/// **The production sink's wake**: `GlDims::dim_settled` presents a frame when the host's frost body was +/// baked for another dim than the one the field now gives, and for no other reason (the fake above +/// counts by its own comparison; this one runs `popover::host::frost_body_stale` for real). +#[test] +fn the_production_sink_wakes_the_loop_only_for_a_frost_baked_for_another_dim() { + use super::modal::{DimSink, GlDims}; + use crate::frame::backdrop::Dim; + let flat = Dim { tex: 0, tint: [0.0, 0.0, 0.0, 0.3] }; + let field = Dim { tex: 7, tint: [0.35, 0.35, 0.35, 0.3] }; + let woken = |baked: Option>, now: Option| { + crate::popover::host::mock_frost_body(baked); + let mut present = plx_machine::present::Present::new(); + let _ = present.take(0); + present.acknowledge(0); + assert!(!present.changed(), "a settled gate to start from"); + GlDims::new(&mut present).dim_settled(now); + let changed = present.changed(); + crate::popover::host::mock_frost_body(None); + changed + }; + assert!(woken(Some(Some(flat)), Some(field)), "baked for the flat ink, the field's is drawn: one frame"); + assert!(!woken(Some(Some(field)), Some(field)), "the body is the one for this dim: nothing owed"); + assert!(!woken(None, Some(field)), "no frost stands: nothing to correct"); +} + +/// A frame that cannot bake a frost (a video-plane frame, a flat-ink dim) is never told to correct one. +#[test] +fn a_flat_dim_and_a_video_plane_frame_never_report_a_settled_dim() { + let (mut d, mut rig, _) = booted(); + let a = open_modal(&mut d, &mut rig, Style::Sheet, 16); + modal_mut(&mut d, a).scrim_alpha = 0.5; + d.nav.modals.surface_mut(a).unwrap().motion = super::modal::PopoverMotion::at(1.0); + let mut fb = FakeFb::new(0.5); + fb.video_plane = true; + fb.baked = Some(None); + dims_frame(&mut d, &rig, &mut fb); + assert_eq!(fb.wakes, 0, "a video-plane frame has no frost to correct"); +} + /// **The page is read on the frame that captured it, before any dim is seen.** That frame's GPU /// work is waited out before anything else presents (`gfx::snapshot_frame_begin`), so the /// reduction queued there costs no presented frame — queued a frame later, it was the GPU backlog diff --git a/rust-modules/ui/src/dispatch.rs b/rust-modules/ui/src/dispatch.rs index 0aa1702e5f..db1d610e0d 100644 --- a/rust-modules/ui/src/dispatch.rs +++ b/rust-modules/ui/src/dispatch.rs @@ -1217,6 +1217,16 @@ where captured } + /// [`modal_presentation`](Self::modal_presentation) carrying the frame's lowest modal dim + /// ([`ModalStack::first_dim`](super::containers::modal::ModalStack::first_dim)) at the route + /// transition's `nav_page_alpha`, the value `draw_scrims` is handed: what the host's frost body is + /// baked from at the head of the frame. + pub fn modal_presentation_at(&self, nav_page_alpha: f32) -> super::containers::modal::ModalPresentation { + let mut captured = self.modal_presentation(); + captured.dim = self.nav.modals.first_dim(nav_page_alpha); + captured + } + pub fn top_screen(&self) -> Option<&dyn super::screen::Screen> { self.nav.top_page().and_then(|e| e.inst.as_ref()).map(|i| &*i.screen) } diff --git a/rust-modules/ui/src/fixture.rs b/rust-modules/ui/src/fixture.rs index b306a54c38..88a57dfe64 100644 --- a/rust-modules/ui/src/fixture.rs +++ b/rust-modules/ui/src/fixture.rs @@ -987,10 +987,19 @@ impl Screen for FixtureModal { self.bar_opener } fn opener_alpha(&self) -> f32 { - self.opener_alpha + // a surface that owns a popover answers its morph's (a menu's opener is consumed by it); one + // without keeps the alpha a test states + self.popover.as_ref().map_or(self.opener_alpha, |p| p.opener_alpha()) + } + fn handed_back(&self) -> bool { + self.popover.as_ref().is_some_and(|p| p.handed_back()) } fn opener_rect(&mut self, drawn: super::Rect) { self.opener_seen.push(drawn); + // the menus' own `opener_rect`: the morph starts and ends on the opener's live drawn rect + if let Some(pop) = self.popover.as_mut() { + pop.track_opener(drawn); + } } fn draw_held(&mut self, f: &mut DrawFrame<'_, '_, FixtureHost>) { self.held_faces.push(!f.painter.records()); diff --git a/rust-modules/ui/src/lib.rs b/rust-modules/ui/src/lib.rs index 960f7cda26..811f8612f9 100644 --- a/rust-modules/ui/src/lib.rs +++ b/rust-modules/ui/src/lib.rs @@ -1973,7 +1973,8 @@ impl Painter { tint.record(data); }) { return; } if self.records() || frame::backdrop::dim_deferred() { return; } - // A menu's glass over this dim reads undimmed pictures and applies it at composite. + // A menu's glass over this dim applies it at composite to the undimmed pictures it reads (the + // rim's snapshot; the field body of a glass with no frost). A frost body has it baked in. if !plx_gfx::gfx::blur_source_pass() { crate::popover_glass::note_dim(ink); } @@ -2044,9 +2045,10 @@ impl Painter { /// program or the ground is missing — the caller's cue for its field ground. /// `crate::popover_glass::draw` is the component; reach for that. /// - /// `morph` is a morphing menu's join and clarity ([`plx_gfx::gfx::GlassMorph`]); - /// `GlassMorph::NONE` for everything else. Joined, the glass is drawn on the box around both - /// shapes, so that box (not `r`) is what the draw declares. + /// `morph` is a morphing menu's join ([`plx_gfx::gfx::GlassMorph`]; its clarity is always 0, and + /// clarity 1 is the profile chip's lift on the host snapshot); `GlassMorph::NONE` for everything + /// else. Joined, the glass is drawn on the box around both shapes, so that box (not `r`) is what + /// the draw declares. #[allow(clippy::too_many_arguments)] pub fn glass_frozen( self, @@ -2059,6 +2061,24 @@ impl Painter { rim: plx_gfx::gfx::GlassRim, face: plx_gfx::gfx::GlassFace, morph: plx_gfx::gfx::GlassMorph, + ) -> bool { + self.glass_frosted(r, rad, ground, sharp, dim, tint, rim, face, morph, plx_gfx::gfx::GlassFrost::NONE) + } + /// [`glass_frozen`](Self::glass_frozen) with the menu's FROST as the body's picture instead of + /// `ground` ([`plx_gfx::gfx::GlassFrost`]; `NONE` is the field ground, bit for bit). + #[allow(clippy::too_many_arguments)] + pub fn glass_frosted( + self, + r: Rect, + rad: f32, + ground: u32, + sharp: u32, + dim: Option, + tint: [f32; 4], + rim: plx_gfx::gfx::GlassRim, + face: plx_gfx::gfx::GlassFace, + morph: plx_gfx::gfx::GlassMorph, + frost: plx_gfx::gfx::GlassFrost, ) -> bool { let quad = morph.quad(r.x, r.y, r.w, r.h); if self.declare(quad, frame::backdrop::GLASS_FROZEN_COMMAND, |data| { @@ -2077,6 +2097,11 @@ impl Painter { // the join's colour and amount: an amount, not an opacity, so it is recorded as it is and // not through the painter's cascade (a different tint is a different draw) morph.merge.map_or([0.0; 4], |j| j.tint).record(data); + // the frost's texture, its region, its cap and the snapshot it was built from + frost.tex.record(data); + frost.rev.record(data); + frost.rect.record(data); + [frost.knee, frost.ceiling, 0.0, 0.0].record(data); }) { return ground != 0; } if self.records() { return false; } let t = self.c(tint); @@ -2085,7 +2110,7 @@ impl Painter { merge: morph.merge.map(|j| plx_gfx::gfx::GlassMerge { rect: self.place(j.rect), radius: self.px(j.radius), k: self.px(j.k), tint: j.tint }), ..morph }; - plx_gfx::gfx::draw_glass_frozen(m.x, m.y, m.w, m.h, self.px(rad), ground, sharp, dim, t.as_ptr(), rim, face, morph) + plx_gfx::gfx::draw_glass_frozen(m.x, m.y, m.w, m.h, self.px(rad), ground, sharp, dim, t.as_ptr(), rim, face, morph, frost) } /// draw text at absolute (x,y) plus the cascade translate; returns width pub fn text( diff --git a/rust-modules/ui/src/popover.rs b/rust-modules/ui/src/popover.rs index 33ecaf92b2..0b9a59aff7 100644 --- a/rust-modules/ui/src/popover.rs +++ b/rust-modules/ui/src/popover.rs @@ -39,11 +39,13 @@ //! dimmed by the live scrim drawn over it, which is the exact bug the lift exists to fix. //! - **A MENU's ground is glass on the frozen host (DS6), a sheet's ground never is glass, and //! neither reads the framebuffer.** [`crate::widgets::panel_ground`] draws `popover_glass` for a -//! [`Ground::Menu`](crate::widgets::Ground): its body shows the latched underlay field (the one -//! the modal dim draws, `ui::underlay`) and its rim refracts the page this snapshot holds, so the -//! snapshot must be the undimmed page (above); the frame's dim is applied to both at composite. -//! With no latched field it falls back to the sheet's ground — that same field sampled at the -//! panel's own rect under the frost, which constrains nothing. +//! [`Ground::Menu`](crate::widgets::Ground): its body is a FROST of this snapshot ([`host::frost`]: +//! one blur per snapshot, the frame's dim baked in) and its rim refracts the page this snapshot +//! holds, so the snapshot must be the undimmed page (above); the frame's dim is applied to the rim's +//! snapshot at composite. A glass with no frost yet wears the latched underlay field (the one the +//! modal dim draws, `ui::underlay`) as its body instead. With no latched field it falls back to the +//! sheet's ground — that same field sampled at the panel's own rect under the frost, which +//! constrains nothing. //! - **HOST DAMAGE refreshes the snapshot; the popover's OWN activity does not.** That distinction //! is typed by the owning `Present`: Page damage refreshes; Surface damage does not. //! [`own_motion`] / [`host::live`] / [`host::page_pass`] attribute only frame animation; @@ -427,7 +429,7 @@ pub(crate) struct MorphGround { pub(crate) radius: f32, pub(crate) alpha: f32, pub(crate) shadow: f32, - /// The glass's join and clarity while the morph runs (`GlassMorph::NONE` at rest). + /// The glass's join while the morph runs (`GlassMorph::NONE` at rest); its clarity is 0 always. pub(crate) morph: plx_gfx::gfx::GlassMorph, } @@ -523,6 +525,20 @@ impl Popover { } self.morph.frame(self.from, Rect::FULL, 0.0).opener_alpha } + /// **Has this morphing popover handed its opener back?** Its close is over: it stands no longer + /// ([`dismiss`](Self::dismiss) ran) and the droplet has drained into the opener, so the frame IS + /// the closed one ([`Morph::closed_for`](crate::popover_morph::Morph::closed_for): no glass, no + /// dim, the opener whole), which is also the moment [`update`](Self::update) lets the popover go. + /// What a surface owning it answers `Screen::handed_back` with: the container retires the surface + /// and the opener lift with it on this frame, instead of on the frame its own appear spring comes + /// to rest (a Sheet's, about twice as long as the droplet's close) with the opener held on the + /// lift's frozen ground the whole time. `false` for a popover that does not morph, and while it + /// is open or its close is still draining. + pub fn handed_back(&self) -> bool { + self.style == OpenStyle::Morph + && !self.open + && (!self.closing || self.morph.closed_for(self.from.is_some())) + } /// **The modal dim a surface owning this popover asks its container for** (`Screen::scrim`), at /// the role's peak `weight` (a `theme::underlay::DIM_*` row): the container's appear spring ramps /// it for every popover but a [`morphing`](Self::morphing) one, whose dim FOLLOWS the morph @@ -602,8 +618,9 @@ impl Popover { /// bar's blur and re-latches the dim field: 131% of a 60 Hz frame's GPU budget on the TV. /// Real page damage and page motion during the fade still re-take through /// [`host::begin_frame`]; the host cache's owner key treats the container's own dismissal the - /// same way (`host::bind_owner`: a live-host layer, `Style::Compact`, that starts closing drops only a ground stage), so the - /// close's first frame is not the frame that re-takes the page either. + /// same way (`host::bind_owner`: a layer of ANY style that only starts closing drops only a ground + /// stage and keeps the page snapshot), so the close's first frame is not the frame that re-takes + /// the page either. fn release(&mut self) { self.open = false; host::ground_invalidate(); @@ -816,7 +833,7 @@ impl Popover { ground: crate::widgets::Ground, ) { if let Some(g) = self.ground(r, rad) { - crate::widgets::panel_ground_shadowed(p.alpha(g.alpha), g.rect, g.radius, field, ground, g.shadow, g.morph); + crate::widgets::panel_ground_shadowed(p.alpha(g.alpha), g.rect, r, g.radius, field, ground, g.shadow, g.morph); } self.ground_done(); } @@ -833,7 +850,8 @@ impl Popover { /// by the rows' lens spring ([`popover_morph::K_LENS`](crate::popover_morph::K_LENS)), which /// overshoots to ~1.12 (the shrinking slab's height ratio on a close); /// - they are drawn at [`Frame::content_alpha`](crate::popover_morph::Frame::content_alpha), which - /// is 0 until the glass has replaced the opener's fill. A frame on which they are invisible + /// is 0 until the glass has begun to widen (the third glass frame) and never above the glass's + /// own alpha, so a row is never the surface's only content. A frame on which they are invisible /// does not draw them, except through the text recorder (a held surface's walk), which is /// what makes their text resident before the first frame that shows them. /// @@ -861,7 +879,7 @@ impl Popover { /// an opener: the morphing rect and radius, the glass AND its shadow on the fill's /// share (one ramp on an open, the opener the host lifts fading as the glass detaches; a close's /// slab is whole glass until it has drained into the re-formed opener), joined to the opener's - /// shape and clear while the morph says so ([`MorphGround::morph`]). The + /// shape while the morph says so ([`MorphGround::morph`]); frosted on every frame, never clear. The /// fallback: the glass fades in on the fill's share, its shadow whole. pub(crate) fn ground(&self, r: Rect, rad: f32) -> Option { if self.style != OpenStyle::Morph || self.morph.settled() { @@ -1041,26 +1059,28 @@ pub mod host { let key = modal.cache_key(); let (changed, began_closing) = CACHE_OWNER.with_borrow(|old| match old { None => (true, false), - Some(old) => ( - !old.same_snapshot(&key), - old.began_closing(&key).is_some_and(|ids| ids.into_iter().all(|id| modal.kept_host_live(id))), - ), + Some(old) => (!old.same_snapshot(&key), old.began_closing(&key)), }); if changed { // **A layer that only STARTED closing drops a GROUND-stage snapshot and keeps the - // page's.** A ground composite is the panel at full strength, which the fade must not be - // drawn over; the page under a fading surface has not changed (the scrim and the lift are - // drawn live above its snapshot), and real page damage and motion re-take through - // [`begin_frame`] below. A full `invalidate()` here made the close's first frame the one - // that redraws the page into the snapshot, re-sources the tab bar's blur and re-latches the - // dim field: 131% of a 60 Hz frame's GPU budget on the TV, measured on a glass menu's BACK. - // **Only for a surface that kept the host LIVE while it was open** (`Style::Compact`): a - // Sheet, an Alert or an `Opaque` snapshot surface froze the host, which got no Tick, so - // the page snapshot it leaves is as old as the surface (Settings' Under posters change - // would show the old captions through the exit fade) and this flip is the one retake. + // page's, whatever style it is.** A ground composite is the panel at full strength, which + // the fade must not be drawn over; the page under a fading surface is the page it was + // (the scrim and the lift are drawn live above its snapshot), and what changed under a + // frozen host (it got no Tick) is the PAGE's to report: typed page damage and motion + // re-take through [`begin_frame`] below, on this frame as on any other (Settings changing + // Under posters under a covered Library is the Library's damage, raised at the head of its + // `step`). A full `invalidate()` here made the close's first frame the one that redraws the + // page into the snapshot, re-sources the tab bar's blur and re-latches the dim field: 131% + // of a 60 Hz frame's GPU budget on the TV on a glass menu's BACK, and 14.9M GPU cycles + // against an 11.2M budget on the account menu's (a Sheet). // A layer that came or went, another stack, or a snapshot a navigation transition owns is // not a dismissal: all of those drop everything. - if began_closing && !TRANSITION_OWNS.load(Relaxed) { ground_invalidate(); } else { invalidate(); } + if began_closing && !TRANSITION_OWNS.load(Relaxed) { + ground_invalidate(); + } else { + invalidate(); + cache(|c| c.release_frost()); + } reset_reflow(); TRANSITION_OWNS.store(false, Relaxed); CACHE_OWNER.set(Some(key)); @@ -1147,6 +1167,46 @@ pub mod host { cache(|c| c.tex()) } + /// **A glass menu's FROST**: a retained blur of this page snapshot over the region of `panel` (the + /// settled rect, authored px), as `(texture, region rect, epoch it was built from)`, and whether a + /// (re)build is OWED. The texture lives in [`CACHE`] (`FrameCache::frost_read`), is built ONCE + /// per snapshot at the head of a LATER frame than the ask ([`begin_frame`] -> `FrameCache::frost_build_owed`; + /// the glass asks on the first frame it is drawn for, before its field has latched, so a morphing + /// menu's frost is built at the head of the second frame and stands when the glass first draws) + /// and is given back with the host. A stale one is served until its replacement lands (the + /// Watchlist reflow's retake), so the face never changes density between two looks. + pub fn frost(panel: [f32; 4]) -> (Option<(std::ffi::c_uint, [f32; 4], u32)>, bool) { + let page = held() == Held::Page; + let epoch = page_epoch(); + cache(|c| { + if page { + c.frost_want(panel); + } + (c.frost_read(), page && c.frost_possible() && !c.frost_fresh(epoch)) + }) + } + + /// Is the frost's baked body the one for `dim`, the dim a menu's glass is drawing under? See + /// `FrameCache::frost_body_for`. + pub fn frost_body_current(dim: Option) -> bool { + cache(|c| c.frost_body_for(dim)) + } + + /// Does a frost stand whose body was baked for ANOTHER dim than `dim`, the one this frame's glass + /// will draw under? The one place [`frost_body_current`]'s verdict is turned into "a frame is owed": + /// `GlDims::dim_settled` asks it once the field has latched, and answers it with a wake. `false` + /// when no frost can be drawn at all (a failed build or bake latches the frost off, and a body + /// nothing will ever rebake is not a reason to present for ever). + pub fn frost_body_stale(dim: Option) -> bool { + cache(|c| c.frost_possible() && c.frost_read().is_some() && !c.frost_body_for(dim)) + } + + /// A host test stands a frost whose body was baked for `body`'s dim (`None` takes it down again). + #[cfg(test)] + pub fn mock_frost_body(body: Option>) { + mock::FROST_BODY.with(|b| b.set(body)); + } + /// Hold off the GROUND stage for this frame. Set by `containers::modal::ModalUnderlay` while its /// field is still being read off the GPU: the ground quad bakes the dim in, so a ground taken /// now would keep the dim of the field BEFORE the read lands for as long as the panel stays @@ -1386,6 +1446,7 @@ pub mod host { GROUND_DEFERRED.store(false, Relaxed); if !modal.read.host_cached { reset_reflow(); + cache(|c| c.release_frost()); if !TRANSITION_OWNS.load(Relaxed) { invalidate(); } return; } @@ -1408,13 +1469,36 @@ pub mod host { if TRANSITION_OWNS.swap(false, Relaxed) { invalidate(); } let moving = plx_machine::motion::report::page_moving() || page_moving; CAPTURE_POINTLESS.store(modal.read.closing_only && moving, Relaxed); - // a reflowing page is drawn live: its damage is not a reason to retake the snapshot + // a reflowing page is drawn live: its damage is not a reason to retake the snapshot. The frost + // it still holds is served stale, and a closing menu's dim still ramps over it. if reflow_draws() { + bake_frost(modal); return; } if super::host_refresh(modal.read.closing_only, page_dirty, moving) { invalidate(); } + // The frost a standing glass menu is owed, once per snapshot: at the head of this frame, a + // later one than the capture, with the page held and not moving under the menu. + if held() == Held::Page && !reflow_draws() { + let epoch = page_epoch(); + cache(|c| c.frost_build_owed(epoch)); + } + bake_frost(modal); + } + + /// **The frost's body, baked at the head of the frame** (`FrameCache::frost_bake_owed`): the retained + /// blur dimmed by this frame's lowest modal dim and held under the body's ceiling, once per change + /// (every frame of the dim's own ramp, never at rest). The dim arrives as the pure value the + /// presentation carries ([`ModalPresentation::dim`](crate::containers::modal::ModalPresentation)): + /// `ModalStack::first_dim` computes it from the same scrim decision and the same field `draw_scrims` + /// paints through, so no global carries it and no draw is waited for. It is a PREDICTION of that + /// paint (the field can latch after this point, in `draw_scrims_on`'s sync): a glass that finds the + /// body baked for another dim draws it for one frame and the next head corrects it + /// ([`frost_body_current`]). The precondition is "a frost stands", not "the page is held". + fn bake_frost(modal: &crate::containers::modal::ModalPresentation) { + let (knee, ceiling) = crate::popover_glass::frost_cap(); + cache(|c| c.frost_bake_owed(modal.dim, knee, ceiling)); } /// One draw of the host page, visible or blur-source. Hold the guard for the length of the diff --git a/rust-modules/ui/src/popover_glass.rs b/rust-modules/ui/src/popover_glass.rs index 5962c383d4..c2a2d839be 100644 --- a/rust-modules/ui/src/popover_glass.rs +++ b/rust-modules/ui/src/popover_glass.rs @@ -11,19 +11,24 @@ //! stacked over another surface's dim. //! //! **The glass stands on FROZEN ground and reads no framebuffer** (owner decision, 2026-10-17). A -//! menu stands on a page that is not moving (`popover.rs`'s module doc), so its glass is fed the two -//! pictures of that page the frame already holds, through `gfx::draw_glass_frozen`: the body shows -//! the latched underlay field (`ui::underlay`, the 60x32 reconstruction the modal dim draws), and -//! the rim's lens bends the host snapshot (`popover::host::page_tex`, the one capture of the -//! undimmed page) at `tokens::MENU_SHARP` — `fs_glass.frag`'s refraction with the SAME rounded-rect -//! SDF it rounds the panel with. Both are undimmed, and the frame's one modal dim ([`note_dim`]) is -//! applied to both at composite. No backdrop entry is requested, no blur source pass runs and no -//! band is copied off the framebuffer, so the menu's glass costs one panel quad (and its shadow) on every frame of -//! its open, its stay and its close, and a morph or a slide moves that quad over pictures that do -//! not change. It replaced a live `Glass::DYNAMIC_BACKDROP` surface that re-ran the page at quarter -//! resolution as its blur source whenever the draws beneath it changed (the `src` and `pagex2` -//! spans) and composited a 5-tap blur plus a band copy every frame: about 2 to 2.6M Mali GPU -//! cycles a frame over the field ground (television, 2026-10-17). +//! menu stands on a page that is not moving (`popover.rs`'s module doc), so its glass is fed pictures +//! of that page the frame already holds, through `gfx::draw_glass_frozen`: the body is the host's +//! FROST (`popover::host::frost`, one blur of the frozen page per snapshot, built at the head of a +//! later frame, with the frame's lowest modal dim and the body's ceiling baked in), and the rim's lens +//! bends the host snapshot (`popover::host::page_tex`, the one capture of the undimmed page) at +//! `tokens::MENU_SHARP` — `fs_glass.frag`'s refraction with the SAME rounded-rect SDF it rounds the +//! panel with. The frame's one modal dim ([`note_dim`]) is applied at composite to that undimmed +//! snapshot only: the baked body already holds it. The latched underlay field (`ui::underlay`, the +//! 60x32 reconstruction the modal dim draws) is the FALLBACK body, worn under [`FACE`] by a glass +//! with no frost (before the first build, the variant unlinked, a failed build or bake); it takes +//! the dim at composite too. No backdrop entry is requested, no blur source pass runs and no band +//! is copied off the framebuffer, so the menu's glass costs one panel quad (and its shadow) at rest, +//! its open adds one frost build and the dim ramp's bakes, its close adds the bakes, and a morph or a +//! slide moves that quad over pictures that do not change. It replaced a live +//! `Glass::DYNAMIC_BACKDROP` surface that re-ran the page at quarter resolution as its blur source +//! whenever the draws beneath it changed (the `src` and `pagex2` spans) and composited a 5-tap blur +//! plus a band copy every frame: about 2 to 2.6M Mali GPU cycles a frame over the field ground +//! (television, 2026-10-17). //! //! **What it does not see**: anything drawn live above the host after its capture — an opener //! lifted over the dim (the item menu's card, the account chip) — is not in the snapshot, so the @@ -39,10 +44,11 @@ use crate::frame::backdrop::Dim; use crate::{theme, Painter, Rect}; use plx_gfx::gfx::{GlassFace, GlassRim}; -/// The face gradient's top stop: [`theme::MENU_GLASS_TOP`], the board's `rgba(58,58,64,.78)`. -pub const FACE_TOP: [f32; 4] = theme::MENU_GLASS_TOP; -/// The face gradient's bottom stop: [`theme::MENU_GLASS_BOT`], the board's `rgba(40,40,46,.86)`. -pub const FACE_BOT: [f32; 4] = theme::MENU_GLASS_BOT; +/// The face gradient's top stop over the FIELD ground (no frost to stand on): +/// [`theme::MENU_GLASS_FIELD_TOP`], the board's `rgba(58,58,64,.78)`. +pub const FACE_TOP: [f32; 4] = theme::MENU_GLASS_FIELD_TOP; +/// The face gradient's bottom stop over the field ground: [`theme::MENU_GLASS_FIELD_BOT`], `rgba(40,40,46,.86)`. +pub const FACE_BOT: [f32; 4] = theme::MENU_GLASS_FIELD_BOT; /// What the glass wears over its backdrop at full strength: the gradient face, the 1 px perimeter /// and the lit top edge — the board's `inset 0 0 0 1px` and `inset 0 1px 0`, as the shader draws @@ -55,7 +61,22 @@ pub const FACE: GlassFace = GlassFace { rim_w: theme::CARD_SHEEN_W, }; -/// The face at opacity `a`. Only the tint rides the painter's alpha cascade; a [`GlassFace`] does +/// The same, over a real FROST (owner decision, 2026-11-17: "blur + thin face .36/.44"): +/// [`theme::MENU_GLASS_TOP`] / [`theme::MENU_GLASS_BOT`]. +pub const FROST_FACE: GlassFace = GlassFace { + scrim_top: theme::MENU_GLASS_TOP, + scrim_bot: theme::MENU_GLASS_BOT, + rim: theme::GLASS_RIM, + rim_lit: theme::GLASS_RIM_LIGHT, + rim_w: theme::CARD_SHEEN_W, +}; + +/// [`FROST_FACE`] at opacity `a` (see [`face_at`]). +pub(crate) fn frost_face_at(a: f32) -> GlassFace { + crate::widgets::chip_face(FROST_FACE, a.clamp(0.0, 1.0)) +} + +/// The face at opacity `a` over the FIELD ground. Only the tint rides the painter's alpha cascade; a [`GlassFace`] does /// not, so a panel that fades (appear, close, a route change's page dip) fades its face by hand /// the way the hold hint does — otherwise a ~.8-opaque gradient and a full rim stand over rows /// that are still near 0, which is the empty glass frame the morph forbids. @@ -75,8 +96,10 @@ thread_local! { static SURFACE: std::cell::Cell = const { std::cell::Cell::new(usize::MAX) }; } -/// A modal dim was just drawn on the visible frame, under whatever surface draws next. The glass's -/// two pictures are undimmed, so it applies this at composite. +/// A modal dim was just drawn on the visible frame, under whatever surface draws next. The glass +/// applies this at composite to the undimmed pictures it reads (the rim's snapshot; the field body of +/// a glass with no frost) and checks its frost body, baked under the dim the host predicted, against +/// it ([`crate::popover::host::frost_body_current`]). pub(crate) fn note_dim(d: Dim) { let owner = DIM_OWNER.with(std::cell::Cell::get); DIMS.with(|c| c.borrow_mut().push((owner, d))); @@ -122,25 +145,59 @@ fn dims_under_surface() -> (usize, Option) { /// `false` = nothing frozen to stand on, nothing drawn. #[must_use] pub fn draw(p: Painter, r: Rect, radius: f32, field: Option<&crate::underlay::UnderlayField>) -> bool { - draw_shadowed(p, r, radius, field, 1.0, plx_gfx::gfx::GlassMorph::NONE) + draw_shadowed(p, r, r, radius, field, 1.0, plx_gfx::gfx::GlassMorph::NONE) +} + +/// The menu's [`plx_gfx::gfx::GlassFrost`]: the host's retained blur `tex` over `rect`, its body held +/// under [`theme::FROST_BODY_CEILING`] by a knee that starts at [`theme::FROST_BODY_KNEE_AT`] of it. +fn frost_of(tex: std::ffi::c_uint, rect: [f32; 4], rev: u32) -> plx_gfx::gfx::GlassFrost { + let (knee, ceiling) = frost_cap(); + plx_gfx::gfx::GlassFrost { tex, rect, knee, ceiling, rev } +} + +/// The frosted body's `(knee, ceiling)`: [`theme::FROST_BODY_CEILING`] and the knee that starts at +/// [`theme::FROST_BODY_KNEE_AT`] of it. The one place both numbers are combined: the glass's descriptor +/// ([`frost_of`]) and the host's body bake (`popover::host::begin_frame`) read it. +pub(crate) fn frost_cap() -> (f32, f32) { + (theme::FROST_BODY_CEILING * theme::FROST_BODY_KNEE_AT, theme::FROST_BODY_CEILING) } /// [`draw`] with the drop shadow at `shadow` of the painter's opacity: a morph hands the glass and /// its shadow the same fill ramp (`Popover::ground`), a fallback open keeps its shadow whole. -/// `morph` is the morph's join and clarity ([`plx_gfx::gfx::GlassMorph`], `NONE` at rest): a joined +/// `morph` is the morph's join ([`plx_gfx::gfx::GlassMorph`], `NONE` at rest; a morphing menu's +/// clarity is always 0, clarity 1 is the profile chip's lift on the host snapshot): a joined /// glass is drawn on the box around both shapes, and its shadow goes UNDER it (below). +/// +/// **The body is a FROST where the host holds one** (`popover::host::frost`, a retained blur of the +/// frozen page over `settled`'s region, built once per snapshot at a later frame's head): the face is +/// then [`FROST_FACE`] and the body, baked with the frame's dim, is capped at +/// [`theme::FROST_BODY_CEILING`]. With none (no page snapshot, the first build not done yet, the +/// variant unlinked, a failed build or bake) it is the field ground under [`FACE`], as it always was. +/// A menu stacked over another surface's dim draws no glass at all (`false`, below), so it wears +/// neither. While a frost is OWED the ground stage is held back (so a stale or missing frost is +/// never baked into it). +/// +/// **The body is never the sharp page, and a morphing menu's first frames are no exception** +/// (`ui::popover_morph`: the droplet is frosted from its first visible frame to the close's +/// hand-back). The frost is asked for ([`crate::popover::host::frost`]) on the FIRST frame the glass +/// is drawn for, BEFORE the field it stands on has latched (the field's read lands a frame after +/// the capture), so its build, which waits for a later frame's head than the ask, lands at the head +/// of the very next frame instead of the one after the first glass frame, and is there when the +/// glass first draws. A frame on which the frost still does not stand (the first frame's own +/// fallback below, a build the frame held back) wears the field under [`FACE`], never a clear body: +/// the heavier face is the one with no shapes under it to read, and the lighter one would show the +/// field's un-capped brightness (it has no [`theme::FROST_BODY_CEILING`]) as the thin face's body. #[must_use] +#[allow(clippy::too_many_arguments)] pub fn draw_shadowed( p: Painter, r: Rect, + settled: Rect, radius: f32, field: Option<&crate::underlay::UnderlayField>, shadow: f32, morph: plx_gfx::gfx::GlassMorph, ) -> bool { - let Some(ground) = field.and_then(crate::underlay::UnderlayField::ground_tex) else { - return false; - }; // The host snapshot is the page under the FIRST surface's dim. A menu over another surface // stands on that surface too, which neither picture holds: it keeps the field ground. Only the // dims at or BELOW this surface count: the whole frame's dims are recorded before any surface @@ -149,8 +206,27 @@ pub fn draw_shadowed( if dims > 1 { return false; } + // The frost is asked for BEFORE the field check: on the first frame of a menu the field has not + // latched (its read lands a frame after the capture) and this call draws nothing, yet the frost's + // build can already be owed, so that it runs at the head of the next frame, the one the glass + // first draws on, and not a frame after it. + let (read, owed) = crate::popover::host::frost([settled.x, settled.y, settled.w, settled.h]); + let Some(ground) = field.and_then(crate::underlay::UnderlayField::ground_tex) else { + return false; + }; let sharp = crate::popover::host::page_tex().unwrap_or(0); - let face = face_at(p.opacity()); + if owed { + crate::popover::host::defer_ground(true); + } + // A body baked for another dim than the one this glass draws under (the field latched after the + // frame's head predicted it) is drawn for this one frame; the ground stage waits so it is never + // baked into a snapshot, and the next head's bake replaces it. + let stale = read.is_some() && !crate::popover::host::frost_body_current(dim); + if stale { + crate::popover::host::defer_ground(true); + } + let frost = read.map_or(plx_gfx::gfx::GlassFrost::NONE, |(tex, rect, rev)| frost_of(tex, rect, rev)); + let face = if frost.tex != 0 { frost_face_at(p.opacity()) } else { face_at(p.opacity()) }; // A JOINED glass takes its shadow first: `shadow_outside` cuts only the PANEL's shape out of // the penumbra, so drawn after the glass it would darken the joined shape and the neck; drawn // before, the (opaque) glass covers it there. @@ -158,7 +234,7 @@ pub fn draw_shadowed( if joined && shadow > 0.0 { p.alpha(shadow).shadow_outside(r, radius, theme::MENU_SHADOW_BLUR, theme::MENU_SHADOW_DY, theme::MENU_SHADOW); } - if !p.glass_frozen(r, radius, ground, sharp, dim, [1.0; 4], GlassRim::Menu, face, morph) { + if !p.glass_frosted(r, radius, ground, sharp, dim, [1.0; 4], GlassRim::Menu, face, morph, frost) { return false; } // After the glass, not before: `shadow_outside` cuts the panel's own rounded shape out of the @@ -250,6 +326,41 @@ pub(crate) mod tests { }) } + /// **The dim the host bakes the frost's body from is the dim the scrim paint notes.** + /// `UnderlayField::dim_of` (what `ModalStack::first_dim` resolves through, before the paint) against + /// `Painter::dim`'s own `note_dim` (what the glass composites under), for a latched field across + /// the ramp's alphas. A drift here is a body baked for a dim nobody draws. (A host test has no GL + /// context: the field draw leaves before touching it, and the flat ink's rect would not, so the + /// unlatched field is graded against `plan`'s own answer.) + #[test] + fn the_baked_dim_value_is_what_the_scrim_paint_notes() { + let _g = plx_base::testlock::serial(); + let tex = 9_743; + let field = latched(tex); + for a in [0.285_f32, 0.2925, 0.30, 0.05] { + clear_dims(); + field.draw(Painter::root(), Rect::FULL, crate::underlay::Role::Dim { weight: theme::underlay::TINT }, a); + let noted = dims_under_surface().1.expect("the paint noted its dim"); + assert_eq!(field.dim_of(theme::underlay::TINT, a), noted, "latched field at alpha {a}"); + assert_eq!(noted.tex, tex, "through the field's texture"); + } + clear_dims(); + unlatch(tex); + let flat = crate::underlay::UnderlayField::new(); + let d = flat.dim_of(theme::underlay::TINT, 0.3); + assert_eq!((d.tex, d.tint), (0, theme::scrim_black(0.3)), "an unlatched field is the flat scrim ink"); + } + + /// The body's ceiling is one pair of numbers for the glass's descriptor and the host's bake. + #[test] + fn the_frost_cap_pair_is_the_themes_knee_and_ceiling() { + let (knee, ceiling) = frost_cap(); + assert_eq!(ceiling, theme::FROST_BODY_CEILING); + assert_eq!(knee, theme::FROST_BODY_CEILING * theme::FROST_BODY_KNEE_AT); + let f = frost_of(1, [0.0; 4], 0); + assert_eq!((f.knee, f.ceiling), (knee, ceiling), "the descriptor reads the same pair"); + } + /// The face fades with the panel, through `draw` itself: the declared glass at opacity `a` /// equals the one built from `face_at(a)` and differs from the unfaded `FACE` one. Red if /// `draw` hands `FACE` as is (the finding: a ~.8-opaque face over rows still near 0). @@ -528,6 +639,98 @@ pub(crate) mod tests { assert_eq!(face_at(0.0).rim_lit[3], 0.0); } + /// WCAG contrast of two display-code colours (the shader composites in display codes). + fn contrast(a: [f32; 3], b: [f32; 3]) -> f32 { + use plx_gfx::gfx::lin; + let rel = |c: [f32; 3]| 0.2126 * lin(c[0]) + 0.7152 * lin(c[1]) + 0.0722 * lin(c[2]); + let (x, y) = (rel(a), rel(b)); + (x.max(y) + 0.05) / (x.min(y) + 0.05) + } + + /// Do the shipped inks keep their floors (primary and secondary 4.5:1, tertiary 3:1, as + /// `underlay_tests`' contrast test states them) over the grey body `g` under the face's `stop`? + /// The composite is the shader's: `body * (1 - a) + face * a`. + fn inks_hold(stop: [f32; 4], g: f32) -> bool { + let ground = [0, 1, 2].map(|i| g * (1.0 - stop[3]) + stop[i] * stop[3]); + [(theme::TEXT_PRIMARY, 4.5), (theme::TEXT_SECONDARY, 4.5), (theme::TEXT_TERTIARY, 3.0)] + .iter() + .all(|(c, floor)| contrast([c[0], c[1], c[2]], ground) >= *floor) + } + + /// **The frost body's ceiling is the largest body the inks' floors allow.** Re-derived from the tokens: + /// over the face's thinnest stop (the top, .36) a grey body at the ceiling keeps primary and secondary + /// ink at 4.5:1 and tertiary at 3:1, and a body 2/255 brighter does not. This grades the cap alone; + /// [`the_frosted_body_keeps_the_ink_floors_through_the_dim_the_cap_and_the_face`] grades the whole sum. + #[test] + fn the_frost_body_ceiling_keeps_the_ink_floors_at_the_thinnest_face() { + let ceiling = theme::FROST_BODY_CEILING; + assert!(inks_hold(theme::MENU_GLASS_TOP, ceiling), "the ceiling holds at the thinnest stop"); + assert!(inks_hold(theme::MENU_GLASS_BOT, ceiling), "and at the bottom stop"); + assert!(!inks_hold(theme::MENU_GLASS_TOP, ceiling + 2.0 / 255.0), "and it is the derived number, not a safe one"); + let cap = frost_of(1, [0.0, 0.0, 8.0, 8.0], 0); + for page in [1.0f32, 0.0] { + let body = cap.cap(page); + assert!(inks_hold(theme::MENU_GLASS_TOP, body), "a {page} page's frost reads {body} and keeps the floors"); + } + } + + /// **The frosted body is graded with the DIM in the sum.** `fs_frost_bake.frag` dims the body first + /// (the modal dim, `mix(body, ink, alpha)`), then caps its brightest channel, and `fs_glass.frag` + /// then lays the .36/.44 face over what is left. A white page and a black page run through that + /// whole chain for every dim role and an appear spring's alpha in between, with the darkest dim + /// ink there is (black: a flat scrim) and the brightest (`TINT` of a white field: the page's own + /// light pushed down, which LIFTS a black page and is the case where the dim works against a light + /// ink), and the three inks must keep their floors over the result at both stops of the face. The dim can only lower a white page toward its + /// ink, so the cap still binds there; that it binds AFTER the dim is what the order of the sum pins. + #[test] + fn the_frosted_body_keeps_the_ink_floors_through_the_dim_the_cap_and_the_face() { + use theme::underlay as u; + let cap = frost_of(1, [0.0, 0.0, 8.0, 8.0], 0); + let roles = [u::DIM_COMPACT, u::DIM_PANEL, u::DIM_SHEET, u::DIM_DECISION, u::DIM_PLAYER, u::DIM_PROSE]; + let sweep = (0..=20).map(|i| i as f32 / 20.0); + let (mut graded, mut lifted) = (0, false); + for alpha in std::iter::once(0.0).chain(roles).chain(sweep) { + for dim_ink in [0.0, u::TINT] { + for page in [1.0f32, 0.0] { + let dimmed = page * (1.0 - alpha) + dim_ink * alpha; + let body = cap.cap(dimmed); + lifted |= page == 0.0 && body > 0.05; + for stop in [theme::MENU_GLASS_TOP, theme::MENU_GLASS_BOT] { + assert!( + inks_hold(stop, body), + "page {page}, dim {alpha} of ink {dim_ink}: the body reads {body} and an ink loses its floor over stop {stop:?}" + ); + graded += 1; + } + } + } + } + assert!(lifted, "the grid includes a black page the dim lifts, the case a bright ink works against"); + // (no dim + 6 roles + 21 sweep steps) x 2 dim inks x 2 pages x 2 face stops + assert_eq!(graded, 28 * 2 * 2 * 2, "the whole grid was graded"); + // The order is part of the sum: capped BEFORE the dim, a bright dim ink would lift the capped + // white page back over the ceiling and cost the tertiary ink its floor. + let wrong = cap.cap(1.0) * (1.0 - u::DIM_PROSE) + u::TINT * u::DIM_PROSE; + assert!(wrong > theme::FROST_BODY_CEILING && !inks_hold(theme::MENU_GLASS_TOP, wrong), "cap-then-dim reads {wrong}"); + } + + /// **A body at or below 0.9 of the ceiling is the frost as it is.** The knee used to start at 0.6 of + /// the ceiling, which squashed nearly every poster pixel (a 0.43 body came out ~0.28) and left the + /// menu a flat dark panel with no page in it. Graded through the pair the menu draws with + /// (`frost_of`: the theme's knee over `GlassFrost::cap`), so a theme edit that moves the knee down + /// again is red here, not only in the curve's own test. + #[test] + fn a_frost_body_under_the_knee_is_untouched() { + let cap = frost_of(1, [0.0, 0.0, 8.0, 8.0], 0); + let ceiling = theme::FROST_BODY_CEILING; + for share in [0.25, 0.5, 0.7, 0.85] { + let body = ceiling * share; + assert!((cap.cap(body) - body).abs() <= 1.0 / 255.0, "{share} of the ceiling is {body}, the cap makes it {}", cap.cap(body)); + } + assert!(theme::FROST_BODY_KNEE_AT >= 0.9 - 1e-6, "the knee is the last tenth of the ceiling"); + assert!(cap.cap(1.0) <= ceiling, "and a white body still lands at or under it"); + } + /// The compact-menu dim is the board's 30% scrim. #[test] fn the_menu_scrim_is_thirty_percent() { diff --git a/rust-modules/ui/src/popover_host_mock.rs b/rust-modules/ui/src/popover_host_mock.rs index 8177916ad4..545e193028 100644 --- a/rust-modules/ui/src/popover_host_mock.rs +++ b/rust-modules/ui/src/popover_host_mock.rs @@ -16,6 +16,13 @@ thread_local! { pub(super) static PREV_COPIES: std::cell::Cell = const { std::cell::Cell::new(0) }; pub(super) static PREV_RELEASES: std::cell::Cell = const { std::cell::Cell::new(0) }; pub(super) static PREV_DRAWS: RefCell> = const { RefCell::new(Vec::new()) }; + /// A frost a test stands, as the dim its body was baked for (`None`: no frost, the default). + pub(super) static FROST_BODY: std::cell::Cell>> = const { std::cell::Cell::new(None) }; + /// A frost a test says is COMING but not here (a build the head has not run yet): `frost_possible` + /// and no `frost_read`, which is what `popover_glass::draw_shadowed` reads as "owed, none standing". + pub(super) static FROST_PENDING: std::cell::Cell = const { std::cell::Cell::new(false) }; + /// The last panel a glass asked a frost for (`frost_want`), `[x, y, w, h]`. + pub(super) static FROST_ASKED: std::cell::Cell> = const { std::cell::Cell::new(None) }; } pub(super) struct FrameCache { @@ -76,6 +83,30 @@ impl FrameCache { PREV_RELEASES.with(|c| c.set(c.get() + 1)); } } + // The frost is a GL texture: a host test has none, and `frost_possible` says so, so the glass + // takes its field ground exactly as before. + pub(super) fn frost_want(&mut self, panel: [f32; 4]) { + FROST_ASKED.with(|a| a.set(Some(panel))); + } + pub(super) fn frost_read(&self) -> Option<(std::ffi::c_uint, [f32; 4], u32)> { + FROST_BODY.with(|b| b.get()).map(|_| (1, [0.0; 4], 0)) + } + pub(super) fn frost_possible(&self) -> bool { + FROST_BODY.with(|b| b.get()).is_some() || FROST_PENDING.with(|p| p.get()) + } + pub(super) fn frost_fresh(&self, _key: u32) -> bool { + false + } + pub(super) fn frost_build_owed(&mut self, _key: u32) -> bool { + false + } + pub(super) fn frost_bake_owed(&mut self, _dim: Option, _knee: f32, _ceiling: f32) -> bool { + false + } + pub(super) fn frost_body_for(&self, dim: Option) -> bool { + FROST_BODY.with(|b| b.get()).is_none_or(|baked| baked == dim) + } + pub(super) fn release_frost(&mut self) {} pub(super) fn has_prev(&self) -> bool { self.prev.is_some() } diff --git a/rust-modules/ui/src/popover_host_tests.rs b/rust-modules/ui/src/popover_host_tests.rs index e68737db23..1d9d1c4ec1 100644 --- a/rust-modules/ui/src/popover_host_tests.rs +++ b/rust-modules/ui/src/popover_host_tests.rs @@ -119,8 +119,8 @@ fn same_thread_owner_switch_never_reuses_another_hosts_frozen_pixels() { assert_eq!(a.modal_presentation().read, a_open.read, "render cache switches cannot mutate modal authority"); } -/// **The container's own dismissal of a LIVE-host surface keeps the page's snapshot.** A caching -/// surface (`Style::Compact`; the frozen styles below retake it) starting to close changes the owner's cache key (its layer is `Closing` now), and `bind_owner` +/// **The container's own dismissal keeps the page's snapshot.** A caching surface (here a +/// `Style::Compact`; a Sheet below) starting to close changes the owner's cache key (its layer is `Closing` now), and `bind_owner` /// answered with a full `invalidate()`: the close's first frame then redrew the page into the /// snapshot, re-sourced the tab bar's blur and re-latched the dim field, the 131% of a 60 Hz /// frame's GPU budget that `Popover::release` no longer costs a glass menu. A closing flip drops @@ -172,24 +172,27 @@ fn a_surface_that_starts_closing_keeps_the_page_snapshot_and_drops_only_a_ground assert!(held() == Held::Nothing, "a closing surface keeps no ground snapshot"); } -/// **Only a surface that kept the host LIVE while it was open may keep the page's snapshot when it -/// starts closing.** `surface_policy` freezes the host under a Sheet, an Alert and an -/// `Opaque { snapshot: true }` surface, and a frozen page gets no Tick: the page's snapshot is as -/// old as the surface. The full `invalidate()` at the Open -> Closing flip is the one retake after -/// that stretch: keeping the snapshot there showed the Library's OLD captions through Settings' -/// exit fade (an `Opaque` snapshot surface; Under posters changed inside it) and the page jumped -/// when the layer was pruned. Presents `styles` bottom to top (a frame each, the page -/// drawn and held in between), dismisses the TOP one and answers whether the close's first frame -/// redrew the page (the snapshot was thrown away) rather than served it. -fn the_close_retakes_the_page(styles: &[crate::containers::modal::Style]) -> bool { +/// **A closing surface keeps the page's snapshot whatever froze the host under it; the page's own +/// damage is what retakes it.** `surface_policy` freezes the host under a Sheet, an Alert and an +/// `Opaque { snapshot: true }` surface, and a frozen page gets no Tick, so its snapshot is as old +/// as the surface. What a page can have changed meanwhile is the page's to report: typed page damage +/// (`begin_frame`'s `typed_page_damage`, from the owning `Present`) retakes the snapshot, on the +/// close's first frame as on any other, and a page that reports none is the page it was (Settings +/// changing Under posters under a covered Library is the Library's damage, `step`'s head). The +/// close's cache-key flip itself is no retake: it cost a Sheet's close 14.9M GPU cycles against an +/// 11.2M budget on the TV, a dropped frame on every account menu BACK. +/// Presents `styles` bottom to top (a frame each, the page drawn and held in between), dismisses the +/// TOP one and answers whether the close's first frame, handed `page_damaged` as the page's typed +/// damage, redrew the page (the snapshot was thrown away) rather than served it. +fn the_close_retakes_the_page(styles: &[crate::containers::modal::Style], page_damaged: bool) -> bool { use crate::dispatch::NoTap; use crate::fixture::{booted, tick, FixtureArg}; use plx_machine::machine::{MachineId, NavOp}; let _serial = plx_base::testlock::serial(); let _reset = Reset::new(false); let (mut d, mut rig, _) = booted(); - let draw = |modal: &crate::containers::modal::ModalPresentation, page| { - super::begin_frame(modal, 0.0, false, false); + let draw = |modal: &crate::containers::modal::ModalPresentation, page, damaged| { + super::begin_frame(modal, 0.0, false, damaged); PIXELS.with(|p| p.borrow_mut().clear()); { let _page = page_pass(modal); ink(page); } PIXELS.with(|p| p.borrow().clone()) @@ -200,7 +203,7 @@ fn the_close_retakes_the_page(styles: &[crate::containers::modal::Style]) -> boo d.request(MachineId::Nav, NavOp::Present(FixtureArg::Modal)); ms += 16; d.frame(&mut rig, tick(ms), vec![], vec![], &mut NoTap); - assert_eq!(draw(&d.modal_presentation(), "page").len(), 1, "premise: the page is drawn under {style:?}"); + assert_eq!(draw(&d.modal_presentation(), "page", false).len(), 1, "premise: the page is drawn under {style:?}"); } assert!(held() == Held::Page, "premise: the stack froze the page"); let top = d.nav.modals.top().expect("presented").entry.id; @@ -210,31 +213,37 @@ fn the_close_retakes_the_page(styles: &[crate::containers::modal::Style]) -> boo d.frame(&mut rig, tick(ms), vec![], vec![], &mut NoTap); let closing = d.modal_presentation(); assert!(!open.cache_key().same_snapshot(&closing.cache_key()), "premise: the close changed the cache key"); - draw(&closing, "retaken") == ["retaken"] + draw(&closing, "retaken", page_damaged) == ["retaken"] } #[test] -fn a_frozen_host_surface_that_starts_closing_retakes_the_page() { +fn a_sheet_that_closes_with_no_page_damage_keeps_the_page_snapshot() { + use crate::containers::modal::Style; + assert!(!the_close_retakes_the_page(&[Style::Sheet], false), + "a Sheet froze the host, and the page reported no change: its close serves the snapshot it has"); +} + +#[test] +fn a_frozen_host_surface_that_starts_closing_retakes_the_page_after_the_page_changed_while_frozen() { use crate::containers::modal::Style; let kept: Vec