diff --git a/.agents/agents/fw-compat-reviewer.md b/.agents/agents/fw-compat-reviewer.md index 30f2bd3af..408369885 100644 --- a/.agents/agents/fw-compat-reviewer.md +++ b/.agents/agents/fw-compat-reviewer.md @@ -128,7 +128,7 @@ into `dynlib!` **trades link-time symbol checking away** for version tolerance a it where the version actually varies. If a diff moves a stable library there, push back and ask for the `--inventory` output that justifies it. The precedent for the other direction is `rust-modules/shell-sdl/src/sys.rs`: plain `extern "C"` (the `SDL_*TextInput*` calls among them), -justified in its module doc by all 14 inventories exporting the whole SDL2 family it names. +justified in its module doc by all 14 inventories exporting every name outside its `hostsim` block. ## WHAT `fwcompat.py` NEEDS BEFORE IT WILL ANSWER — settle this first, not at your third command diff --git a/Makefile b/Makefile index 53d366323..1be253749 100644 --- a/Makefile +++ b/Makefile @@ -581,8 +581,8 @@ ARM_PROFILE_FLAG = $(if $(filter release,$(ARM_PROFILE)),--release,--profile $(A # make RUST_TOOLCHAIN=nightly HOST_THREADS=8 test-fast # # A HOST_THREADS above 1 on a non-nightly toolchain is a hard error here rather than a cargo failure -# in the middle of a recipe. Which recipes: ONLY the host `cargo test` / `check-cargo-unit-*` builds, -# `test-fast`, `test-crate`, `test-hostsim` and `build-bench` carry `$(HOST_ENV)`. It is NOT exported, so the ARM +# in the middle of a recipe. Which recipes: the host `cargo test` builds and nothing else +# (`grep -n HOST_ENV Makefile` is the exact set; `ci/test_host_threads.py`'s `HOST_RECIPES` pins it). It is NOT exported, so the ARM # staticlib recipes (which set RUSTFLAGS themselves), the simulators' builds, clippy and the package # steps never see it (ci/test_host_threads.py pins both). 0 and 1 mean the serial front end. A # RUSTFLAGS the caller exported wins over it (cargo reads CARGO_BUILD_RUSTFLAGS last). @@ -854,8 +854,8 @@ RUST_CFG = features:$(RUST_FEATFLAGS)$(if $(filter-out release,$(ARM_PROFI # it from the recipe AND its prerequisites, never the name (`check-ass` is a test goal and stages the # host libass into `pkg/`). Two kinds qualify: # -# * HOST-ONLY goals: the unit-test loops, the fuzz runs and the lint pass (`test-hostsim`, `check-nodef`, -# `test-fast`, `test-crate`, `fuzz-hud`, `lint`, `build-bench`), the pieces of `check` that are plain host work +# * HOST-ONLY goals: the unit-test loops, the fuzz runs and the lint pass (`test-hostsim`, `test-host-interface`, +# `check-nodef`, `test-fast`, `test-crate`, `fuzz-hud`, `lint`, `build-bench`), the pieces of `check` that are plain host work # (`check-cargo-lint`, `check-cargo-unit-hostsim`, `check-localization`, `check-c-unit`, # `check-python-harness`), the notices tables, and the set-up and local tooling that writes outside # `pkg/` (a toolchain install, the disk-watch agent, the test media, the demo library, the @@ -880,7 +880,7 @@ RUST_CFG = features:$(RUST_FEATFLAGS)$(if $(filter-out release,$(ARM_PROFI # goal in the two kinds above resets nothing under a dry run, and every goal named as NOT here stays out # of the list. The list is ONE line on purpose (`grep '^SIDE_EFFECT_FREE' Makefile` is the exact set, # and several tests read it that way). -SIDE_EFFECT_FREE = $(QUERY_GOALS) release-guard lab-guard disk disk-preflight build-bench build-bench-quick test-hostsim check-nodef test-fast test-crate fuzz-hud lint check-cargo-lint check-cargo-unit-hostsim check-localization check-c-unit check-python-harness notices notices-verify setup-rust setup-env disk-watch disk-watch-uninstall fixtures fixtures-quick fixtures-pipeline demo-library sim-token sim-macos-token sim-clean sim-macos-clean kill run run-stream verify-deploy uninstall fetch-profile softfloat-probe tv-lock-require +SIDE_EFFECT_FREE = $(QUERY_GOALS) release-guard lab-guard disk disk-preflight build-bench build-bench-quick test-hostsim test-host-interface check-nodef test-fast test-crate fuzz-hud lint check-cargo-lint check-cargo-unit-hostsim check-localization check-c-unit check-python-harness notices notices-verify setup-rust setup-env disk-watch disk-watch-uninstall fixtures fixtures-quick fixtures-pipeline demo-library sim-token sim-macos-token sim-clean sim-macos-clean kill run run-stream verify-deploy uninstall fetch-profile softfloat-probe tv-lock-require PURE_QUERY := $(if $(MAKECMDGOALS),$(if $(filter-out $(SIDE_EFFECT_FREE),$(MAKECMDGOALS)),,yes),) # `PLAYBACK_BACKENDS=none` builds no television package. It is refused HERE, at parse time and before # the stamp reset below: a recipe-level refusal ran after that reset, so a mistyped @@ -1583,7 +1583,7 @@ test: deploy run # it is not the table's value for that dir's name (tools/disk-budget.py NEED_GIB). `ci/test_disk_preflight.py` # finds every target whose recipe runs cargo and fails when one is missing from this list. DISK_ENTRIES = check check-replay check-cargo-lint check-cargo-unit-default check-cargo-unit-hostsim lint \ - test-fast test-crate test-hostsim check-nodef check-ass check-ffmpeg sim-macos sim-linux screenshots-sim site-video-sim \ + test-fast test-crate test-hostsim test-host-interface check-nodef check-ass check-ffmpeg sim-macos sim-linux screenshots-sim site-video-sim \ $(RUST_LIB) pkg/plxnative-storage macapp macapp-zip build-bench build-bench-quick fuzz-hud $(DISK_ENTRIES): | disk-preflight @@ -1591,7 +1591,7 @@ $(DISK_ENTRIES): | disk-preflight DISK_TREE = $(if $(CARGO_TARGET_DIR),$(if $(filter /%,$(CARGO_TARGET_DIR)),$(CARGO_TARGET_DIR),$(CURDIR)/rust-modules/$(CARGO_TARGET_DIR)),$(CURDIR)/rust-modules/target) DISK_NEED = test-fast test-crate: DISK_TREE = $(CURDIR)/rust-modules/$(TEST_FAST_TDIR) -test-hostsim: DISK_TREE = $(CURDIR)/rust-modules/$(TEST_HOSTSIM_TDIR) +test-hostsim test-host-interface: DISK_TREE = $(CURDIR)/rust-modules/$(TEST_HOSTSIM_TDIR) # The fuzz tree (ASan + coverage, release with debuginfo, ten binaries): 3.1 GiB measured after a cold build # of the first eight; the ninth, `ws_frame`, adds 83 MiB, and the tenth, `owp_json`, 49 MiB with `plx_owp` # (measured on Linux x86_64). @@ -1646,9 +1646,10 @@ check: # best. A bare `cargo test` builds for the host triple, which is exactly what we want — and it is # also why this suite cannot cover anything that links the TV's own libraries: media-codecs/src/ffi.rs gates its four # `#[link]` directives out of cfg(test) so the crate's pure logic stays host-testable, and a test -# that actually calls into FFmpeg or GL fails to link by design. --lib keeps it to the crate's own -# `#[cfg(test)] mod tests` blocks (there are no integration tests in tests/ — that directory is the -# on-device Python harness, a different thing entirely). +# that actually calls into FFmpeg or GL fails to link by design. --lib keeps it to the crates' own +# `#[cfg(test)]` blocks. The one integration test, `rust-modules/tests/host_interface.rs`, needs `hostsim` +# and runs in `check-cargo-unit-hostsim` (and `make test-host-interface`), not here; the repo-root `tests/` +# is the on-device Python harness, a different thing entirely. # NB the suite APPENDS to `/tmp/plxnative-events.log` on the dev Mac, and deliberately cannot be # pointed elsewhere. Since 2026-08-15 enough of the tree logs its failures (stream, posters, img, # account, remote) that host tests exercising those paths write real lines. `PLXNATIVE_RUNTIME_DIR` @@ -1807,11 +1808,19 @@ check-cargo-unit-hostsim: @# was invisible to all 1398 default-feature tests because the seam it needs was not there. @# Cargo keys fingerprints by feature set, so the two configurations coexist in one target/ and @# this costs a few seconds warm rather than a rebuild. + @# The second cargo line is W7a's gate and a test executable of its own (`--lib` never builds an integration test): + @# `rust-modules/tests/host_interface.rs` uses the application crate's `host` module from outside the crate and boots + @# a fake platform to its shell's refusal. It needs `hostsim` and a throwaway runtime root, which this pass has; + @# `make test-host-interface` is the same line as an incremental loop. @set -e; d=$$(mktemp -d /tmp/plxnative-check.XXXXXX); trap 'rm -rf "'"$$d"'"' EXIT; \ cd rust-modules && PATH="$$HOME/.cargo/bin:$$PATH" PLXNATIVE_RUNTIME_DIR="$$d" \ $(TELEMETRY_ENV) \ $(HOST_ENV) \ - $(UNIT_RUN) -- cargo +$(RUST_TOOLCHAIN) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_play_feed -p plx_shell_sdl --features hostsim + $(UNIT_RUN) -- cargo +$(RUST_TOOLCHAIN) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_play_feed -p plx_shell_sdl --features hostsim; \ + PATH="$$HOME/.cargo/bin:$$PATH" PLXNATIVE_RUNTIME_DIR="$$d" \ + $(TELEMETRY_ENV) \ + $(HOST_ENV) \ + $(UNIT_RUN) -- cargo +$(RUST_TOOLCHAIN) test -p plxnative-modules --test host_interface --features hostsim # OPT-IN incremental inner loop: the default-feature unit suite (the same `cargo test --lib` as # `check-cargo-unit-default`, same throwaway runtime root and telemetry env) with @@ -1906,6 +1915,25 @@ test-hostsim: $(HOST_ENV) \ $(UNIT_RUN) --require-match $(if $(T),--filter '$(T)') -- cargo +$(RUST_TOOLCHAIN) test --lib $(addprefix -p ,$(HOSTSIM_PKGS)) --features hostsim +# `make test-host-interface` -- W7a's gate (docs/platform-ports.md, Target shape 8): the application crate's `host` +# module used from OUTSIDE the crate. `rust-modules/tests/host_interface.rs` is an integration test, a crate of its own +# that can name only the `pub` items of `plxnative_modules`. It builds a `static Platform` from a fake `Shell`, `Surface` +# and `FrameProbe` and boots it through `host::run` to the fake shell's refusal of the window (the boot cannot go +# further without a GL context). It needs `hostsim`: only there is the runtime root steerable, so the boot's logs land +# in the throwaway directory below. The incremental loop, in `rust-modules/$(TEST_HOSTSIM_TDIR)` beside `make test-hostsim` +# (same feature set, same tree); `make check` runs the same test non-incrementally in `check-cargo-unit-hostsim`. +# Refused under RELEASE=1 like `test-hostsim`. +.PHONY: test-host-interface +test-host-interface: + @$(if $(RELEASE),echo "make test-host-interface: refused under RELEASE=1 -- it runs the default-plus-hostsim feature set incrementally; RELEASE=1 is the shipping feature set (use make check-nodef for that)." >&2; exit 1,:) + @echo "test-host-interface: the host interface test of plxnative-modules in rust-modules/$(TEST_HOSTSIM_TDIR) -- see 'make disk'" + @set -e; d=$$(mktemp -d /tmp/plxnative-check.XXXXXX); trap 'rm -rf "'"$$d"'"' EXIT; \ + cd rust-modules && CARGO_INCREMENTAL=1 CARGO_TARGET_DIR=$(TEST_HOSTSIM_TDIR) \ + PATH="$$HOME/.cargo/bin:$$PATH" PLXNATIVE_RUNTIME_DIR="$$d" \ + $(TELEMETRY_ENV) \ + $(HOST_ENV) \ + $(UNIT_RUN) -- cargo +$(RUST_TOOLCHAIN) test -p plxnative-modules --test host_interface --features hostsim + # `make fuzz-hud [T=] [SECS=60]` -- the `cargo fuzz` package over every parser a HUD package or the # registry reaches (`fuzz/`: its own workspace, outside rust-modules, so nothing shipped names it). T is one # or more targets (`python3 tools/fuzz-hud.py list`), default all; SECS is the time per target, run one after diff --git a/ci/module-layers.ini b/ci/module-layers.ini index c51584367..469398249 100644 --- a/ci/module-layers.ini +++ b/ci/module-layers.ini @@ -201,11 +201,12 @@ uses = base machine os gfx net plex telemetry ui data session media appkit play_ members = screens [app] -# The loop, its adapters and every dev/diagnostic surface; lib.rs's own items are the facade. +# The loop, its adapters and every dev/diagnostic surface; lib.rs's own items are the facade. `host` is the +# one doorway a platform crate names (re-exports of the construction interface, and `run`). uses = base machine os gfx net plex telemetry ui data session media appkit screens shell_sdl playback_contract play_uri play_feed media_codecs members = crate app dev lab capture remote focusprobe hud_cli hud_tools shot coldstart textinput system release_line port - platform_desktop + platform_desktop host [platform webos] # Not a layer: the modules that exist only because the target is webOS. Identity, capability and diff --git a/ci/test_arm_profile.py b/ci/test_arm_profile.py index b92b646a7..644dd6d5a 100644 --- a/ci/test_arm_profile.py +++ b/ci/test_arm_profile.py @@ -110,7 +110,7 @@ def test_the_profile_is_part_of_the_stamp_only_when_it_is_not_release(self): # `check-cargo-unit-hostsim` and `check-python-harness` (tests/test_harness.py alone). `test-hostsim` # and `check-nodef` were the first two to be listed. `fuzz-hud` runs tools/fuzz-hud.py (a cargo tree # under rust-modules/ and files under fuzz/); it reads nothing the stamp guards. - "test-hostsim", "check-nodef", "test-fast", "test-crate", "fuzz-hud", "lint", "check-cargo-lint", "check-cargo-unit-hostsim", + "test-hostsim", "test-host-interface", "check-nodef", "test-fast", "test-crate", "fuzz-hud", "lint", "check-cargo-lint", "check-cargo-unit-hostsim", "check-localization", "check-c-unit", "check-python-harness", # the documentation tables "notices", "notices-verify", diff --git a/ci/test_ci_split.py b/ci/test_ci_split.py index 173fb1ebd..113602ecf 100644 --- a/ci/test_ci_split.py +++ b/ci/test_ci_split.py @@ -64,7 +64,11 @@ def rule(target): r"ci/test_no_host_staticlib\.py", r"ci/test_build_not_always_dirty\.py", ], - "check-cargo-unit-hostsim": [r"cargo \+\$\(RUST_TOOLCHAIN\) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_play_feed -p plx_shell_sdl --features hostsim"], + "check-cargo-unit-hostsim": [ + r"cargo \+\$\(RUST_TOOLCHAIN\) test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_play_feed -p plx_shell_sdl --features hostsim", + # W7a: the `host` module used from outside the crate (`make test-host-interface` is the same line) + r"cargo \+\$\(RUST_TOOLCHAIN\) test -p plxnative-modules --test host_interface --features hostsim", + ], } diff --git a/ci/test_host_threads.py b/ci/test_host_threads.py index 740ca0d7e..406592be3 100644 --- a/ci/test_host_threads.py +++ b/ci/test_host_threads.py @@ -16,7 +16,7 @@ nightly toolchain: asking for more than one thread on the stable pin is a Makefile error that names the fix, rather than a cargo failure in the middle of a recipe; * the flag reaches exactly the host test recipes (`check-cargo-unit-default`, `-hostsim`, - `test-fast`, `test-crate`, `test-hostsim`, `build-bench`) when it is on, and NO recipe when it is off, so a CI + `test-fast`, `test-crate`, `test-hostsim`, `test-host-interface`, `build-bench`) when it is on, and NO recipe when it is off, so a CI recipe is the command it always was; * it is never exported and no ARM, simulator, clippy or package line, and no workflow, names it, so a release or simulator build cannot pick it up; @@ -39,7 +39,7 @@ "GITHUB_ACTIONS", "ARM_PROFILE", "HOST_THREADS") FLAG = "CARGO_BUILD_RUSTFLAGS" HOST_RECIPES = (("check-cargo-unit-default",), ("check-cargo-unit-hostsim",), ("test-fast",), - ("test-crate", "C=plx_base"), ("test-hostsim",), ("build-bench",)) + ("test-crate", "C=plx_base"), ("test-hostsim",), ("test-host-interface",), ("build-bench",)) def make(*args: str, env: dict[str, str] | None = None) -> str: @@ -109,7 +109,7 @@ def test_off_means_no_recipe_names_it(self): ("RELEASE", ["RELEASE=1"], None), ("stable", ["FLAVOR=stable"], None)): # those goals refuse RELEASE=1 outright goals = [goal for goal in HOST_RECIPES - if not (goal[0] in ("test-fast", "test-crate", "test-hostsim", "build-bench") and what in ("RELEASE",))] + if not (goal[0] in ("test-fast", "test-crate", "test-hostsim", "test-host-interface", "build-bench") and what in ("RELEASE",))] with self.subTest(f"{what}: {', '.join(goal[0] for goal in goals)}"): out = make("-n", *[word for goal in goals for word in goal], *args, env=env) self.assertNotIn(FLAG, out) @@ -125,7 +125,8 @@ def test_the_arm_and_simulator_recipes_never_name_it(self): self.assertNotIn(banned, line, f"Makefile:{lineno} puts the host flag on a non-host line") # ...and the lines that DO carry it are the host test recipes, nothing else. users = [l for l in text.splitlines() if "$(HOST_ENV)" in l and not l.lstrip().startswith("#")] - self.assertEqual(len(users), len(HOST_RECIPES), users) + # `check-cargo-unit-hostsim` carries it on two cargo lines (the `--lib` suite and W7a's `--test host_interface`). + self.assertEqual(len(users), len(HOST_RECIPES) + 1, users) def test_no_workflow_names_it(self): # Workflows and composite actions only: ci.yml's `paths` filter skips pushes that touch only diff --git a/docs/agent-reference.md b/docs/agent-reference.md index e66f45810..47802e741 100644 --- a/docs/agent-reference.md +++ b/docs/agent-reference.md @@ -138,7 +138,7 @@ the pinned Sentry Native cross-build), and `sshpass` (Homebrew; deploy/run use y stack is mostly a chain, so cargo has little to run side by side and the front end (parse, type-check, borrow-check) is single-threaded per crate by default. `-Zthreads=N` (N = the core count, capped at 8) parallelises it for the host `cargo test` recipes (`check-cargo-unit-default`, - `check-cargo-unit-hostsim`, `test-fast`, `test-crate`, `test-hostsim`, `build-bench`) through + `check-cargo-unit-hostsim`, `test-fast`, `test-crate`, `test-hostsim`, `test-host-interface`, `build-bench`) through `CARGO_BUILD_RUSTFLAGS`. Measured 2026-10-05 on an M4 (10 cores) on nightly, `make build-bench` non-incremental edit-rebuilds, medians of 5: `plx_base` leaf 20.1 s to 17.8 s, `plx_ui` 10.7 to 7.8, `plx_screens` 8.3 to 5.7, app 4.8 to 2.9; the incremental `test-fast` loop is unchanged @@ -333,6 +333,25 @@ the pinned Sentry Native cross-build), and `sshpass` (Homebrew; deploy/run use y `CARGO_TARGET_DIR` at a `/tmp` directory: those trees were not in any checkout, so no tool counted or reclaimed them (28 of them, 45.6 GiB, were found in `/tmp` on 2026-10-19). Refused under `RELEASE=1`; `ci/test_managed_targets.py` pins that the target dir is inside the checkout. +- `make test-host-interface` — W7a's gate (`docs/platform-ports.md`, Target shape 8): the application crate's + `host` module (`rust-modules/src/host.rs`, the one path a platform crate names the application's types by) used from OUTSIDE the crate by + `rust-modules/tests/host_interface.rs`, an integration test and so a crate of its own. It builds a `static + Platform` from a fake `Shell`, `Surface` and `FrameProbe`, boots it through `host::run` (the real + `run_application`) and asserts that `init` ran before `open`, the `OpenAsk` the application made, and the fake's + refusal returned as the entry's `Exit`. The boot cannot go further: after `open` it makes real GL calls, and a fake + surface has no GL context (nothing stubs GL under `test-support`), so frames and the loop are graded by the + in-crate tests of `make test-hostsim`, not here. It needs `hostsim`, because only there does `PLXNATIVE_RUNTIME_DIR` + steer the runtime root, so the boot's event log and crash log land in the recipe's throwaway directory; the boot + replaces the process's panic hook (`install_panic_logger`, which wraps the previous hook and also writes the + event and crash logs), and only one test in the file boots, because the platform's services install once per + process. The file also holds a source scan that every path into the application crate starts + `plxnative_modules::host` (its own spelling only; the crate's surface is pinned by `host.rs`'s tests, which + `make test-crate C=plxnative_modules` runs). Same shape as `test-hostsim`: incremental in `rust-modules/target-hostsim`, through + `$(UNIT_RUN)` (a `--test` line is passed through), refused under `RELEASE=1`, in `SIDE_EFFECT_FREE` and + `DISK_ENTRIES`. `make check` runs the same test non-incrementally as the second cargo line of + `check-cargo-unit-hostsim` (`--lib` never builds an integration test), pinned in `ci/test_ci_split.py`'s `GATES`. + The file needs no `[[test]]` entry (cargo finds `rust-modules/tests/*.rs`), so the root manifest and the + `ci/proofs` certificates that hash it are unchanged. - `make fuzz-hud [T= ...] [SECS=60]` — the `cargo fuzz` package over every parser a HUD package or the registry reaches (`docs/hud-plugins.md`, threat model): `admit` (the whole admission path), `bundle_read`, `archive_read` (the 1.0 ZIP container), `svg_check` (the SVG gate in front of nanosvg), @@ -1263,7 +1282,7 @@ every thin back-edge with `file:line` (the work list for breaking it up); `--dot `abnormal`, like a freeze's; one made after backgrounding (the PLX-NATIVE-1P shape) finds no open session, because backgrounding already ended it `exited` (`telemetry::session`), so only the `error` event exists. -- `rust-modules/src/` — the app core (Rust): `app/` (`mod.rs` the `run_application` shim + `struct App`, `boot.rs` the bring-up, `run.rs` the frame loop and its phase functions, `events.rs`/`input.rs` the input decode and key ladders, `lifecycle.rs`, `playback.rs`, `content.rs`, `bridge.rs` the seam onto the container and the ONE navigation vocabulary, `words.rs` the heartbeat's `route=`/`overlay=` alphabet — `nav.rs` is gone with `enum Route` since restructure phase 12), `system.rs` (wayland), `rust-modules/shell-sdl/` (crate `plx_shell_sdl`: `SDL_Init`, the window, the GL swap, the event decode and the text-input calls, which `app/platform.rs`'s `Shell` opens as the app-private `Surface`), +- `rust-modules/src/` — the app core (Rust): `app/` (`mod.rs` the `run_application` shim + `struct App`, `boot.rs` the bring-up, `run.rs` the frame loop and its phase functions, `events.rs`/`input.rs` the input decode and key ladders, `lifecycle.rs`, `playback.rs`, `content.rs`, `bridge.rs` the seam onto the container and the ONE navigation vocabulary, `words.rs` the heartbeat's `route=`/`overlay=` alphabet — `nav.rs` is gone with `enum Route` since restructure phase 12), `system.rs` (wayland), `rust-modules/shell-sdl/` (crate `plx_shell_sdl`: `SDL_Init`, the window, the GL swap, the event decode and the text-input calls, which `app/platform.rs`'s `Shell` opens as the `Surface` the `App` owns (`Shell` and `Surface` are reachable from outside the crate only through `plxnative_modules::host`; `HostEvent` stays app-private)), and, in the media layer (`rust-modules/media/`, crate `plx_media`, which the application links), `player/` (buffer-feed engine + worker threads — **`rust-modules/media/src/player/CLAUDE.md` is the playback deep-dive; read it before touching playback**), `abr/` and `route/`, and `ff.rs`, which diff --git a/docs/module-layers.md b/docs/module-layers.md index 5091866d8..704e5e6ff 100644 --- a/docs/module-layers.md +++ b/docs/module-layers.md @@ -136,7 +136,7 @@ base | media | `ff` (a facade over `play_feed`'s demuxer) `abr curlio player route speed_audio`; `aq` and `hls` moved to `play_feed` | 56k | 49% | | appkit | `appkit` (the player panels and the Sources row several screens draw) | 13k | 32% | | screens | `screens` | 54k | 28% | -| app | `crate app dev lab capture remote focusprobe shot coldstart textinput system release_line port` | 42k | 12% | +| app | `crate app dev lab capture remote focusprobe shot coldstart textinput system release_line port host` | 42k | 12% | "Prod lines" counts files that are not wholly `cfg(test)`, measured after L14. The last column is the share of all production lines in that layer plus every layer above it. Line counts stand in @@ -207,7 +207,7 @@ on the device, stock SDL2 under `hostsim`), the synthetic key, pointer, wheel an into the queue (a text event is built as bytes and handed to the decode, never pushed: pushing one crashes the Mac's SDL), and the text-input calls. The LG half does not move: the `SDL_SysWMinfo` buffer, the `wl_proxy_marshal` opaque region and the LS2 pump stay in `system.rs`, a member of `[platform webos]`, and a pin in the crate's `lib.rs` fails if the crate names the query that overruns it. The application reaches it through `app/platform.rs`, whose `Shell` opens a -`Surface` over the crate's `Window`; `Shell`, `Surface` and `HostEvent` stay application-private until W7a. +`Surface` over the crate's `Window`; `HostEvent` stays application-private, and `Shell` and `Surface` are reachable only through the application crate's `host` module (W7a). `ci/check-deps.sh` reads the whole crate for the same clock, statics and thread gates as every other layer, and not as one of the sans-IO areas: the shell is an IO crate by definition. @@ -347,8 +347,8 @@ proves the references are gone and nothing more; L15b is open. | **L15b** the OS-neutral port — **open** | — | An OS-neutral video sink with the ACB bind sequence behind it and the webOS facts the gate cannot see; the simulator became its own platform in W4. See below. | | **L15c** the platform value and the three contracts — **done** | — | Wave R (the rename that gave this page `os` and `[platform webos]`) landed as #1474; W2 landed (`tv::Port` became `tv::Services`, with four groups of hooks; the shell and the frame probes moved to `app::Platform`), and so did the three contracts, W3a to W3c: who may persist credentials (#1477), what evidence admits a URI player (#1478), who ends the process (#1479). See "L15c to L15h" below. | | **L15d** neutral types and the simulator as its own platform (L15b item 2) — **W3d and W4 landed** | — | W3d landed (the opaque `Backend` tag, `sandbox` to `native_video`, identity publishes a platform name and version, `device::Info` keeps its webOS fields in `WebosDetail`, and `devcaps` reads its files through the platform), and so did W4: `platform_desktop` (`rust-modules/src/platform_desktop.rs`, a second fence section, `[platform desktop]`) is the simulator's and the macOS app's own platform value, which `src/bin/sim.rs` enters through; the `hostsim` terms of the television's fence are gone, so the television's code is compiled into every build and the linker drops it from a desktop executable (`simulators.yml` links the macapp feature set to guard that until W7), and the stand-ins in `webos` and `keymanager` are test seams, compiled for tests and `test-support` (`docs/platform-ports.md`, W4). The desktop platform is the second implementation. | -| **L15e** events, the shell and composition — **W5a to W5c, W6 and W6b landed** | — | W5 (`HostEvent` with `Option`) landed in three PRs, lifecycle and quit (W5a, #1484), keys and text (W5b, #1487) and the pointer and wheel (W5c, #1492), and so did W6b (platform-supplied composition in two boot phases, #1489) and W6 (`plx_shell_sdl`, a `[shell_sdl]` layer: SDL's bring-up, the window, the swap, the event decode and the text-input calls moved out of the application behind its private `Shell` and `Surface`, and the LG half stays in `system.rs`). W6c (a URI-only and a two-driver composition play an ordinary title) is planned. | -| **L15f** extract the platform crates — **planned** | — | W7: a narrow public `host` module in the application crate, `rust-modules/platform-webos` and `platform-desktop` as crates above `app`, and the gate learning "a platform is a crate above `app`". After L15d, before L15g and L15h (the storage-authority part of W8a, #1488, #1490 and #1491, landed ahead of W7; the rest of W8 still follows W7). | +| **L15e** events, the shell and composition — **W5a to W5c, W6, W6b, W6c and W7a landed** | — | W5 (`HostEvent` with `Option`) landed in three PRs, lifecycle and quit (W5a, #1484), keys and text (W5b, #1487) and the pointer and wheel (W5c, #1492), and so did W6b (platform-supplied composition in two boot phases, #1489) and W6 (`plx_shell_sdl`, a `[shell_sdl]` layer: SDL's bring-up, the window, the swap, the event decode and the text-input calls moved out of the application behind its private `Shell` and `Surface`, and the LG half stays in `system.rs`). W6c (a URI-only and a two-driver composition play an ordinary title) landed (#1494), and W7a published the construction interface through `plxnative_modules::host` alone (`rust-modules/src/host.rs`, tested from outside the crate by `rust-modules/tests/host_interface.rs`, `make test-host-interface`). | +| **L15f** extract the platform crates — **planned** | — | W7b: `rust-modules/platform-webos` and `platform-desktop` as crates above `app`, over the narrow public `host` module W7a already published (the row above), and the gate learning "a platform is a crate above `app`". After L15d, before L15g and L15h (the storage-authority part of W8a, #1488, #1490 and #1491, landed ahead of W7; the rest of W8 still follows W7). | | **L15g** the webOS facts and the remaining `hostsim` (L15b item 3) — **W8a started** | — | W8a has begun: the platform states where the account's records live (`tv::Services.storage`, #1488), and telemetry's consent store (#1490) and plex's session persistence (#1491) follow it instead of the `target_arch = "arm"` fence. Still planned: the rest of W8a, one PR per directory (`os`, `src`, `base`, `storage` and `play-feed`; telemetry's nine `target_arch = "arm"` lines in `telemetry/src/telemetry/native.rs`, the Sentry Native crash capture, are not among them and no step owns them yet, the follow-up for Tizen ARM retail builds that #1490 names), sorting the `target_arch = "arm"` and `target_os = "linux"` sites into "is webOS" (a platform value or runner) and "is 32-bit ARM" or "is Linux" (stays); then W8b, the library name lists, `paths` and the packaging, and W8c, the `feature = "hostsim"` lines left in the tree (none of them in the fence now; `git grep -h 'feature = "hostsim"' -- '*.rs' | wc -l` counts them). | | **L15h** the OS-neutral Feed sink (L15b item 1) — **planned** | — | W11: `plx_acb` (an `[acb]` layer) takes the ACB plane owner and the URI media verbs out of `os`, the Feed-side ACB results become neutral, and the bind sequence moves behind a neutral sink. Needs the television. | diff --git a/docs/platform-ports.md b/docs/platform-ports.md index c236b7001..2ce14a879 100644 --- a/docs/platform-ports.md +++ b/docs/platform-ports.md @@ -894,17 +894,20 @@ There is no `default_backend` (review M8, critic M1): the backend set is derived `Shell` (the factory) opens the loop's `Surface`: `create_surface`, `make_current`, `swap`, `drawable_size`, `gl_proc_address`; `release`/`reacquire` around background; `video_hole(Option)`, which replaces `arm_opaque_region`, `opaque_route` and `clear_opaque_region`; `pump()`, which replaces `pump_bus`. The trait doc -states which thread runs each call (Target shape 7). `Shell`, `Surface` and `HostEvent` stay app-private until -H1 and H2 return (critic M5; H3, H4 and H5 returned on the emulator only, E6, E8, E10; Decision 3, A): code moves -now, but no type a Samsung shell must match leaves the app crate; Target shape 8 is the one narrow, public -construction interface. The dispatcher's rig hooks (`ui/src/dispatch.rs:728-730`) keep delegating through -`run::rig_*`. +states which thread runs each call (Target shape 7). `Shell`, `Surface` and `HostEvent` stayed app-private until +H1 and H2 return (critic M5; H3, H4 and H5 returned on the emulator only, E6, E8, E10; Decision 3, A). The owner then +ruled (2026-11-21, Decision 3 amended) that `Shell` and `Surface`, with the rest of the construction interface, +are reachable ONLY through `plxnative_modules::host` (Target shape 8), never as general `pub` items of the +application crate; `HostEvent` stays app-private, and a platform reports input through `EventSink`. W7a publishes +today's `Shell` (12 methods) and `Surface` (5, plus `deliver`) as they are; the fold toward the shape above (one +`Surface`, `video_hole`, `pump`) is W9's, which is the first change with a second implementation to fold toward. +The dispatcher's rig hooks (`ui/src/dispatch.rs:728-730`) keep delegating through `run::rig_*`. ### 2. Input and lifecycle: canonical actions (review M6, C8; critic F11) This replaces two earlier designs, "`HostEvent::Key` carries SDL keycodes plus LG scancodes" and critic M7's "map Ecore names to `remote_token_key` pairs". -- `HostEvent` (app-private, like `Shell`) has: +- `HostEvent` (app-private; `Shell` is published through `host` only, Target shape 8) has: - `Key { action: Option, edge: Edge, raw: Option }`, `Edge` being `Down | Repeat | Up` as in `InputKind::Key` (F33). `action` is `Option` because unbound keys flow today as raw pairs (`k:0,269` HOME, `app/events.rs:202-212`), the configurable lab trigger consumes pairs no `Action` names, and the recorder @@ -1177,23 +1180,52 @@ Ecore names to `remote_token_key` pairs". (`src/lib.rs:17`), so a sibling cannot name `app::Platform` or implement a crate-private `Shell`; and a `static PLATFORM` must be `Sync`, while window state is thread-affine (`MainThread` is `!Send + !Sync`, `base/src/task.rs:129`). -- The interface. One narrow public module, `plxnative_modules::host`, of re-exports only: `Platform`, `Services`, - `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit`, `Release` and an `EventSink` trait. The - split is by thread: registration data (the `static PLATFORM`: function pointers and `&'static dyn` of `Sync` - types, `Shell` included as a factory) is `Sync` and shared; thread-affine state (window, GL context, the - Ecore handles) lives only in a `Surface` that `Shell::open(&self, &MainThread)` returns on the loop thread and - that the app owns inside `App`. The platform reports input through `EventSink` (`key(Option, - Option, Edge)`, `text`, `pointer`, `wheel`, `lifecycle`, `quit`, ...); the APP converts to its private - `HostEvent`, so the owner's decision that the event API stays private holds. `Action`, `RawKey` and `Edge` - are already public lower-layer types. -- Gate. Before extraction, a desktop-shaped root is compiled against `host` alone: an integration test +- The interface. One narrow public module, `plxnative_modules::host`: re-exports, and ONE function, `run(&'static + Platform, &CStr, u16) -> Exit`, which forwards to `run_application` (the single exception to "re-exports + only": the entry is `pub(crate)`, and a platform crate has nothing else to call). The re-exports are `Platform`, + `Services`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, `Composition`, `Exit`, `Release` and an `EventSink` + trait, with the vocabulary their signatures use: `MainThread`, `OpenAsk`, `Placement`, `Lifecycle`, `PointerEdge`, + `Action`, `RawKey` and `Edge`. The eight application-crate items (`Platform`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, + `Composition`, `Exit`, `Release`) are reachable ONLY through `host` (owner ruling, 2026-11-21; Decision 3, amended): + `Exit` and `Release` are `pub` inside the private `app`, and `Platform` and the traits are `pub` in a private + module, so no path outside `host` names them. `Services` is not one of the eight: it stays `plx_os::tv::Services`, + already a `pub` type of a lower crate, which `host` re-exports beside them. A platform crate names the APPLICATION + crate's types through `host` alone, but not everything it builds is the application's: a `Services` is built from + the hook tables of `plx_os::tv` (`IdentityHooks`, `SecureHooks`, `SystemHooks`, `StorageHooks`, `LegacyWebosMedia`, + `LocaleReply`) and `MediaBoot::compose` takes `plx_media::player::adapter::PlayerAdapter`, so a platform crate + depends on `plx_os` and `plx_media` directly, as well as on the application crate. `host` does not re-export them. + The split is by thread: registration data (the `static + PLATFORM`: function pointers and `&'static dyn` of `Sync` types, `Shell` included as a factory) is `Sync` and + shared; thread-affine state (window, GL context, the Ecore handles) lives only in a `Surface` that + `Shell::open(&self, &MainThread, &OpenAsk)` returns on the loop thread and that the app owns inside `App`. +- Events. The platform reports input through `EventSink` (`key(Option, Option, Edge) -> bool`, `text`, + `pointer`, `wheel`, `lifecycle`, `quit`); the APP converts to its private `HostEvent` (a private `HostQueue`, the + one place), so the owner's decision that the event API stays private holds. `Action`, `RawKey` and `Edge` are + lower-layer types: `RawKey` moved to `plx_ui::consts` beside `raw_pair` and `action_of` (a `pub(crate) use` keeps + the app's old path). `Surface::deliver(&self, &mut dyn EventSink)` is ADDITIVE, beside `Surface::poll`: `deliver` is + required, `poll` is defaulted to `false` and `#[doc(hidden)]`, and the loop's `drain_sdl` drains `poll` as before and + then calls `deliver` once. The SDL shells deliver nothing through the sink, so every SDL event still comes through + `poll` (a unit test pins both). `poll` is RETIRED once the SDL shells deliver through the sink, W9 at the latest. +- Gate. Before extraction, a platform is compiled against the application crate through `host` alone (and against + `plx_os` and `plx_media` for the hook tables and `PlayerAdapter` it names): an integration test (`rust-modules/tests/host_interface.rs`, a separate crate that can name only `pub` items) builds a - `static PLATFORM` with a fake `Shell` and boots it under `hostsim`. W7b extracts only after it passes. -- Runner (G8; F52). No target runs it today (every one is `cargo test --lib`; `rust-modules/tests/` does not - exist), so a test file alone would be a gate nobody runs. W7a adds (1) `make test-host-interface`: `cargo + `static PLATFORM` from a fake `Shell`, `Surface` and `FrameProbe` and boots it through the real `run_application` + (`host::run`) to the fake `Shell::open`'s refusal, under `hostsim` and a throwaway `PLXNATIVE_RUNTIME_DIR`. It + asserts `init` before `open`, the `OpenAsk` the application means to make, and the refusal returned as the entry's + `Exit`. It cannot run frames, and no fake `Surface` could take it further: after `open` the boot makes real GL calls + (`init_gl` links the renderer's programs), which need a current GL context, and nothing stubs GL under + `test-support`. The loop's fake-surface tests stay in the crate (`make test-hostsim`). The test's one source rule is + that every path into the application crate begins `plxnative_modules::host`; the lower-layer crates a platform + lists as its own dependencies (`plx_os`, `plx_media`) are fair to name, and it must, as above. That rule holds + only this file's own spelling. The crate's SURFACE is held by an in-crate source pin in `host.rs`'s tests (`make + test-crate C=plxnative_modules`): the crate root's `pub` items are `host` plus the `hostsim`-only simulator + doors (each confined to `hostsim`, or `test`, by its `cfg`), and `host.rs` is the only `pub use` whose tree names `app` (as `crate::app`, `super::app`, `self::app` or in a group), apart from the root's `hostsim`-only + `synthetic_home_initial`. W7b extracts only after it passes. +- Runner (G8; F52). As of `e9924f0f9` no target ran it (every one was `cargo test --lib`; `rust-modules/tests/` did not + exist), so a test file alone would have been a gate nobody ran. W7a added (1) `make test-host-interface`: `cargo test -p plxnative-modules --features hostsim --test host_interface`, incrementally in `target-hostsim` like - `make test-hostsim`, through `$(UNIT_RUN)` if it accepts `--test` (UNVERIFIED: F52) and as a plain `cargo test` - otherwise; it is a cargo-running target, so it joins `DISK_ENTRIES` (with its `DISK_TREE` line) or + `make test-hostsim`, through `$(UNIT_RUN)` (it accepts `--test`: it passes the cargo line through and requires one + executable per `-p`, which one integration test is); it is a cargo-running target, so it joins `DISK_ENTRIES` (with its `DISK_TREE` line) or `ci/test_disk_preflight.py` fails; and (2) the same invocation as a recipe line of `check-cargo-unit-hostsim`, the `host-unit-hostsim` CI job's target, so `make check` and CI run it, pinned in `ci/test_ci_split.py`'s `GATES`. @@ -1649,26 +1681,41 @@ W3d. Neutral types (L15b item 2 prerequisites; part of item 3). hidden W10 work critic M1 named, and they land here. ### W7 (N, accepted T). Extract the platform crates (W7a -> W7b) -- W7a: the interface of Target shape 8: `pub mod host` in `src/lib.rs`, `host_interface.rs`, a desktop-shaped root - compiled against it. W7b: `[platform webos]` becomes `rust-modules/platform-webos` and `[platform desktop]` +- W7a: the interface of Target shape 8: `pub mod host` in `src/lib.rs`, `host_interface.rs`, a fake platform compiled + against it and booted to its refusal. W7b: `[platform webos]` becomes `rust-modules/platform-webos` and `[platform desktop]` becomes `rust-modules/platform-desktop`. `RUST_LIB` (`Makefile:882`) archives `plx_platform_webos`; the gate learns "platform as crate above app". `tv/plane.rs` and `tv::uri` stay in the bottom layer until W11a. - Order: after W0, W4, W6, W6b, W6c and Wave R. W0's reading (the desktop counts as the second implementation) reverses `docs/module-layers.md:22-24`; the owner's yes is Decision 3, A. The owner's condition was H1-H4 from the emulator or a set: H3 and H4 returned on the emulator (E6, E8) and are recorded as answered on the emulator only; H1 and H2 are open (E9), recorded as open, and gate a retail set, not W7 (nor the emulator MVP of W9, - Decision 8). `HostEvent` and `Shell` stay app-private. + Decision 8). `HostEvent` stays app-private; `Shell` and `Surface` are reachable only through `host` (Decision 3, + amended 2026-11-21). - The Cargo mechanism of the PLATFORM axis lands here: the ARM recipe passes `RUST_FEATFLAGS` (`Makefile:1023-1024`), so each platform crate depends on the app with `default-features = false` and forwards - every app feature the Makefile passes (`rust-modules/Cargo.toml:78-82`), same defaults. -- Files: `src/lib.rs`, `rust-modules/tests/host_interface.rs`, `rust-modules/Cargo.toml`, the `Makefile` `RUST_LIB` + every app feature the Makefile passes (`rust-modules/Cargo.toml:78-82`), same defaults. W7b's platform crates + also depend on `plx_os` and `plx_media` directly: the hook tables of `Services` and `PlayerAdapter` are theirs, and + `host` does not re-export them (`rust-modules/tests/host_interface.rs` shows what a platform crate names). +- Files: `src/lib.rs`, `src/host.rs`, `rust-modules/tests/host_interface.rs`, `rust-modules/Cargo.toml`, the `Makefile` `RUST_LIB` and `cargo rustc` lines and (W7a, G8; F52) the new `test-host-interface` target with its `DISK_ENTRIES` entry and a line in `check-cargo-unit-hostsim`, `ci/test_ci_split.py` (its `GATES`), `ci/check-staticlib-artifact.py` (`CRATE`, F25), `ci/check-module-layers.py`, `ci/module-layers.ini`, `docs/module-layers.md`, `ci/build-budgets.json` (re-measure; no raise), and the bottom layer's `src/lib.rs` (drops `pub mod keymanager;` and `pub mod webos;`) with its `Cargo.toml`: both pinned, a reviewed certificate change (F25). -- Test: `make test-hostsim` and `make test-host-interface` (the integration test, run by no target today; `ci/ +- As landed (W7a): the interface, not the move. `src/host.rs` is the one public module of a television build (re-exports and `run`; a `hostsim` build keeps the simulator binary's own doors), the + eight application-crate items of the owner's ruling are reachable through it only (`Services` is `plx_os`'s own `pub` type, re-exported), and `rust-modules/tests/host_interface.rs` builds + a `static Platform` from fakes and boots it through `host::run` to the fake shell's refusal, with a source scan + that holds every mention of the application crate in that file to `plxnative_modules::host`; the crate's own + surface is held by a source pin in `host.rs`'s tests. A platform crate depends on `plx_os` and `plx_media` as well as + the application crate. The test has no `[[test]]` + entry (cargo discovers `tests/*.rs`), so no `Cargo.toml` and no `ci/proofs` certificate changed. `make + test-host-interface` is the incremental loop and `check-cargo-unit-hostsim` runs the same line, pinned in + `ci/test_ci_split.py` (`GATES`). `Surface::poll` and `Surface::deliver` coexist until W9 retires `poll`; the SDL + shells' `deliver` delivers nothing. `sdl_init` and `sdl_open` are not published: W7b decides what the two real + platform crates need of them. The W6 minors rode along (the reviewer note's inventory claim, and the SDL crate's + source-file pin reading only `*.rs` entries). +- Test: `make test-hostsim` and `make test-host-interface` (the integration test; run by both since W7a; `ci/ test_disk_preflight.py` and `ci/test_ci_split.py` pass with it); W7a changes the `Makefile`, so its PR carries a build-bench table as well as W7b's; `ARM_PROFILE=release` size within budget; every undefined symbol of the C objects (`main.c`, `crashtrace.c`, `sentry_context.c`, `starfish.c`, @@ -1831,8 +1878,18 @@ emulator runs E11 and E12); they are recorded below and the body follows them. - 2026-11-20, Decision 3 (W7 gate): A. W7 may start. H3 and H4 recorded as answered on the emulator only; H1 and H2 stay open and gate W9, not W7. `Shell` and `HostEvent` stay app-private. Read with Decision 8: the emulator MVP of W9 does not wait for H1 and H2 either. +- 2026-11-21, Decision 3 amended (owner): the EIGHT application-crate items `Platform`, `Shell`, `Surface`, + `FrameProbe`, `MediaBoot`, `Composition`, `Exit` and `Release` are reachable only through `plxnative_modules::host`, + never as general `pub` items of the application crate. `Services` is not one of the eight: it is + `plx_os::tv::Services`, already a `pub` type of a lower crate, which `host` re-exports beside them. A platform + crate names the application crate's types through `host` alone; the hook tables a `Services` is built from + (`plx_os::tv`) and `PlayerAdapter` (`plx_media`) come from their own crates, which it depends on directly. + `HostEvent` stays app-private, and `EventSink` is the public face of input (it too is + reachable only through `host`). This replaces "`Shell` and `HostEvent` stay app-private" above for `Shell` and + only `Shell`. - 2026-11-20, Decision 4 (order): A. The three contracts (W3a-c) first, then the rest, the Samsung-facing types - app-private. Cut into the waves of "Workstreams". + app-private (`Shell` and `Surface` are published through `host` only, by the 2026-11-21 amendment to Decision 3). + Cut into the waves of "Workstreams". - 2026-11-20, Decision 5 (probes): go. H5 was built on `samsung/hello-tpk` for the emulator and passed there (E10, `64c609a46`); the tester request on #1460 for H1, H2 and H6 is posted only with the owner's approval; the tester build with an on-screen diagnostics and key-code panel ran on the emulator (E11) and is the diff --git a/rust-modules/shell-sdl/src/lib.rs b/rust-modules/shell-sdl/src/lib.rs index 507abe9c3..ee0d734fb 100644 --- a/rust-modules/shell-sdl/src/lib.rs +++ b/rust-modules/shell-sdl/src/lib.rs @@ -11,8 +11,8 @@ //! as two plain function pointers the television fills and a desktop leaves empty. //! //! The crate is a mounted module of the `shell_sdl` layer (`ci/module-layers.ini`), which may use -//! `base`, `machine` and `os`; the crate names `base` alone. The application's `Shell` and `Surface` traits and its `HostEvent` stay app-private -//! (`docs/platform-ports.md`, Target shapes 1 and 8); [`window::Window`] is the one SDL +//! `base`, `machine` and `os`; the crate names `base` alone. The application's `HostEvent` stays app-private, and its `Shell` and `Surface` traits are reachable only through +//! the application crate's `host` module (`docs/platform-ports.md`, Target shapes 1 and 8); [`window::Window`] is the one SDL //! implementation of that `Surface`, and [`event::Decoded`] is the neutral value the application maps //! onto its own event type. //! @@ -57,9 +57,12 @@ mod pins { #[test] fn every_source_file_is_scanned() { + // `*.rs` files and directories only: an editor's swap file or a `.DS_Store` is not source. let mut on_disk: Vec = std::fs::read_dir(concat!(env!("CARGO_MANIFEST_DIR"), "/src")) .expect("the crate's src directory") - .map(|e| e.expect("a directory entry").file_name().to_string_lossy().into_owned()) + .map(|e| e.expect("a directory entry")) + .filter(|e| e.path().is_dir() || e.path().extension().is_some_and(|x| x == "rs")) + .map(|e| e.file_name().to_string_lossy().into_owned()) .collect(); on_disk.sort(); let mut listed: Vec<&str> = SOURCES.iter().map(|s| s.0).collect(); diff --git a/rust-modules/src/app/events.rs b/rust-modules/src/app/events.rs index d6db179e4..375428525 100644 --- a/rust-modules/src/app/events.rs +++ b/rust-modules/src/app/events.rs @@ -10,6 +10,8 @@ use super::*; use plx_machine::machine::Edge; +// `RawKey` is `plx_ui::consts`' (a platform crate names it through `host`); this is the application's spelling. +pub(crate) use plx_ui::consts::RawKey; use plx_ui::consts::{action_of, raw_pair, Action}; /// Preserve one IME commit and its place among key events. Desktop text does not imply an @@ -75,9 +77,10 @@ pub(crate) fn host_wcode(sym: u32) -> u32 { } /// What the platform tells the loop: a key press, a text commit, the pointer, the wheel, the window -/// leaving or returning to the screen, and the host asking the application to end. App-private, like -/// [`Shell`](super::platform::Shell): no platform reaches it by a type of its own until the -/// platform contract is settled (`docs/platform-ports.md`, Target shape 2). +/// leaving or returning to the screen, and the host asking the application to end. App-private, unlike +/// [`Shell`](super::platform::Shell) and [`Surface`](super::platform::Surface), which `host` publishes: a +/// platform reports input through [`EventSink`](super::platform::EventSink) and the application converts it +/// to this type in [`HostQueue`] (`docs/platform-ports.md`, Target shapes 2 and 8). /// /// The SDL drain decodes SDL's events into it ([`decode_host_event`]) and the loop consumes it in /// ONE function (`run::ingest_host_event`), so a host that stops the application without SDL @@ -128,17 +131,6 @@ impl HostEvent { } } -/// The raw `(sym, wcode)` pair a key arrived as. Kept beside the [`Action`] because three things -/// still read it: a press with no action (an unsupported key flows on as exactly the pair it was), -/// the lab trigger key (named by `lab.json`, not by an action), and the recorder's tape, whose -/// format IS the pair. A platform with no SDL pair sends none, and the loop builds -/// [`raw_pair`] for its action. -#[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub(crate) struct RawKey { - pub sym: c_uint, - pub wcode: c_uint, -} - /// One edge of one key, as a platform hands it to the loop: the canonical [`Action`] where the key /// has one, the [`Edge`], and the raw pair where the platform has one. /// @@ -253,6 +245,44 @@ fn host_event(decoded: Decoded) -> Option { }) } +/// What a platform's [`EventSink`](super::platform::EventSink) calls become: the [`HostEvent`]s the loop +/// ingests, in the order the platform made them. The one place a non-SDL platform's events become the +/// application's own type, beside [`host_event`] for SDL's (the two are the only constructors of a +/// [`HostEvent`], so the private event type has exactly two doors). A key goes through [`KeyPress::new`], +/// which refuses what is neither an action nor a pair, or an action and a pair that name two keys. +#[derive(Default)] +pub(crate) struct HostQueue(Vec); + +impl HostQueue { + /// The queued events, oldest first. + pub(crate) fn into_events(self) -> Vec { + self.0 + } +} + +impl super::platform::EventSink for HostQueue { + fn key(&mut self, action: Option, raw: Option, edge: Edge) -> bool { + let Some(press) = KeyPress::new(action, edge, raw) else { return false }; + self.0.push(HostEvent::Key(press)); + true + } + fn text(&mut self, text: &str) { + self.0.push(HostEvent::Text(text.to_owned())); + } + fn pointer(&mut self, x: f32, y: f32, edge: PointerEdge) { + self.0.push(HostEvent::Pointer { x, y, edge }); + } + fn wheel(&mut self, dy: i32) { + self.0.push(HostEvent::Wheel { dy }); + } + fn lifecycle(&mut self, edge: Lifecycle) { + self.0.push(HostEvent::Lifecycle(edge)); + } + fn quit(&mut self) { + self.0.push(HostEvent::Quit); + } +} + /// **One native key edge as the loop hands it to the tree**, for the effect-level guards (W5b): the /// SDL bytes a television or the simulator delivers for the pair `(sym, wcode)` (the literals a /// test writes down, never an `Action`'s `raw_pair`), decoded by [`decode_host_event`], and the @@ -1214,3 +1244,84 @@ mod key_event_tests { assert_eq!(text(b""), Some(HostEvent::Text(String::new()))); } } + +/// A platform's `EventSink` calls become the same `HostEvent`s the SDL decode makes of the same events +/// (the one conversion a non-SDL platform's input goes through), in the order they were made, and a key +/// the application cannot name is refused, not queued. +#[cfg(test)] +mod host_queue_tests { + use super::super::platform::EventSink; + use super::{decode_host_event, encode_key, Action, Edge, HostEvent, HostQueue, KeyPress, Lifecycle, PointerEdge, RawKey}; + use plx_ui::consts::raw_pair; + + fn event_of(code: u32) -> [u8; 128] { + let mut ev = [0u8; 128]; + ev[..4].copy_from_slice(&code.to_ne_bytes()); + ev + } + + #[test] + fn quit_and_the_lifecycle_edges_queue_what_the_sdl_decode_makes_of_their_events() { + let mut queue = HostQueue::default(); + queue.quit(); + queue.lifecycle(Lifecycle::WillBackground); + queue.lifecycle(Lifecycle::DidBackground); + queue.lifecycle(Lifecycle::WillForeground); + queue.lifecycle(Lifecycle::DidForeground); + let decoded: Vec = + [0x100, 0x103, 0x104, 0x105, 0x106].iter().map(|&code| decode_host_event(&event_of(code)).expect("decoded")).collect(); + assert_eq!(queue.into_events(), decoded); + } + + #[test] + fn a_raw_pair_with_or_without_its_action_queues_the_press_the_sdl_decode_makes_of_those_bytes() { + let (sym, wcode) = raw_pair(Action::Ok); + let pair = RawKey { sym, wcode }; + let Some(decoded) = decode_host_event(&encode_key(sym, wcode, true)) else { panic!("a key event") }; + let mut queue = HostQueue::default(); + assert!(queue.key(None, Some(pair), Edge::Down), "a pair alone is a press"); + assert!(queue.key(Some(Action::Ok), Some(pair), Edge::Down), "and so is the pair with the action it names"); + assert_eq!(queue.into_events(), vec![decoded.clone(), decoded]); + } + + #[test] + fn an_action_alone_queues_a_press_whose_pair_is_the_one_a_remote_sends() { + let mut queue = HostQueue::default(); + assert!(queue.key(Some(Action::Back), None, Edge::Up)); + let want = KeyPress::new(Some(Action::Back), Edge::Up, None).expect("Back names a key"); + let events = queue.into_events(); + assert_eq!(events, vec![HostEvent::Key(want)]); + let HostEvent::Key(press) = &events[0] else { panic!("a key") }; + assert_eq!(press.pair(), RawKey { sym: raw_pair(Action::Back).0, wcode: raw_pair(Action::Back).1 }); + } + + #[test] + fn a_key_the_application_cannot_name_is_refused_and_queues_nothing() { + let (sym, wcode) = raw_pair(Action::Ok); + let mut queue = HostQueue::default(); + assert!(!queue.key(None, None, Edge::Down), "neither an action nor a pair"); + assert!(!queue.key(Some(Action::Digit(10)), None, Edge::Down), "no pair spells Digit(10)"); + assert!(!queue.key(Some(Action::Back), Some(RawKey { sym, wcode }), Edge::Down), "an action and a pair of two keys"); + assert!(queue.into_events().is_empty()); + } + + #[test] + fn text_pointer_and_wheel_queue_as_given_and_keep_their_order() { + let mut queue = HostQueue::default(); + queue.text("wal"); + queue.pointer(960.0, 540.0, PointerEdge::Down); + queue.wheel(-2); + queue.text(""); + queue.pointer(1.0, 2.0, PointerEdge::Up); + assert_eq!( + queue.into_events(), + vec![ + HostEvent::Text("wal".into()), + HostEvent::Pointer { x: 960.0, y: 540.0, edge: PointerEdge::Down }, + HostEvent::Wheel { dy: -2 }, + HostEvent::Text(String::new()), + HostEvent::Pointer { x: 1.0, y: 2.0, edge: PointerEdge::Up }, + ] + ); + } +} diff --git a/rust-modules/src/app/exit.rs b/rust-modules/src/app/exit.rs index f0ff5bf38..fbf5729d8 100644 --- a/rust-modules/src/app/exit.rs +++ b/rust-modules/src/app/exit.rs @@ -54,7 +54,7 @@ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; /// Whether the application gave back every native resource it held before it returned. #[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub(crate) enum Release { +pub enum Release { /// The teardown ran to its end and released the window and the GL context. Complete, /// Something is still held: a native worker is inside firmware, or the boot refused before any @@ -65,15 +65,15 @@ pub(crate) enum Release { /// What `run_application` returns to its entry. #[derive(Clone, Copy, Debug, PartialEq, Eq)] -pub(crate) struct Exit { +pub struct Exit { /// The process exit status: `1` after a failed recording or a refused boot, else `0`. - pub(crate) code: c_int, - pub(crate) release: Release, + pub code: c_int, + pub release: Release, } impl Exit { /// An early-boot refusal. Nothing was torn down, so nothing is released. - pub(crate) const fn refused(code: c_int) -> Self { + pub const fn refused(code: c_int) -> Self { Self { code, release: Release::Retained } } diff --git a/rust-modules/src/app/mod.rs b/rust-modules/src/app/mod.rs index 657912679..71fa616fa 100644 --- a/rust-modules/src/app/mod.rs +++ b/rust-modules/src/app/mod.rs @@ -78,7 +78,9 @@ mod hint_taught; mod recorder; mod window_activity; mod exit; -pub(crate) use exit::Exit; +// `pub`, not `pub(crate)`, because `host` re-exports them: a `pub use` cannot re-export a binding the crate +// only sees, and `app` itself is private, so this reaches no further than `host`. +pub use exit::{Exit, Release}; pub(crate) mod events; pub(crate) mod lifecycle; pub(crate) mod playback; diff --git a/rust-modules/src/app/platform.rs b/rust-modules/src/app/platform.rs index 7ff3228b1..d759fbe51 100644 --- a/rust-modules/src/app/platform.rs +++ b/rust-modules/src/app/platform.rs @@ -20,12 +20,17 @@ //! platform composed through [`publish_composition`], the one function that does, so the set of //! installed drivers and the resolver the planner reads cannot disagree. //! -//! `Shell`, `Surface`, `FrameProbe` and `Platform` are app-private on purpose: no type a platform's shell has -//! to match leaves the application crate until the platform contract is settled. The webOS value is -//! built by `port.rs`; `ci/check-deps.sh`'s `frame` gate pins the call text of the three +//! These types are reachable from outside the application crate ONLY through the narrow `host` module +//! (`crate::host`, `docs/platform-ports.md`, Target shape 8), which re-exports them for a platform crate +//! to build its `static` `Platform` against: the application's general API stays private, and so does +//! `HostEvent` (a platform reports input through [`EventSink`], which the application converts). The webOS +//! value is built by `port.rs`; `ci/check-deps.sh`'s `frame` gate pins the call text of the three //! privileged calls (`pump_bus`, `opaque_route`, `clear_opaque_region`) to `app/run.rs`. use super::Exit; use plx_base::task::MainThread; +use plx_machine::machine::Edge; +use plx_shell_sdl::event::{Lifecycle, PointerEdge}; +use plx_ui::consts::{Action, RawKey}; use plx_media::player::adapter::PlayerAdapter; use plx_media::route::uri_preflight::ResolvePort; use plx_media::route::PlaybackSession; @@ -34,8 +39,8 @@ use std::os::raw::c_void; /// What a platform's boot asks of SDL, as plain data: [`InitHooks`] (the two steps a platform runs /// around `SDL_Init`), and [`OpenAsk`] with its [`Placement`] (the window's title, place and size). The -/// shell crate's own types, re-exported rather than copied: they hold no SDL type, and W7a, which -/// publishes `Shell` and `Surface`, is where a platform-neutral spelling of them is decided. +/// shell crate's own types, re-exported rather than copied: they hold no SDL type. `host` re-exports +/// `OpenAsk` and `Placement` for a platform crate (`InitHooks` stays here: only the SDL helpers below take it). pub(crate) use plx_shell_sdl::{InitHooks, OpenAsk, Placement}; /// The platform's window, bus and pointer, as the application drives them: the SDL window and its @@ -48,7 +53,7 @@ pub(crate) use plx_shell_sdl::{InitHooks, OpenAsk, Placement}; /// request first, the session read, then the window. That is the order boot has always had, and /// `app::boot` pins it. A platform whose surface is not SDL's states its own pair; every SDL one is the /// shell crate's (`plx_shell_sdl`), reached through [`sdl_init`] and [`sdl_open`]. -pub(crate) trait Shell: Sync { +pub trait Shell: Sync { /// Bring the platform's windowing up and ask for the GL context, once, FIRST: before the stored /// session is read and before [`open`](Shell::open). A refusal ends the boot with that `Exit`. fn init(&self, mt: &MainThread) -> Result<(), Exit>; @@ -88,24 +93,36 @@ pub(crate) trait Shell: Sync { } /// The window the application presents to and reads events from, owned by `App` for the rest of the -/// process. App-private and thread-affine (not `Sync`) like [`Shell`], and for the same reason: no -/// type a platform has to match leaves the application crate until the platform contract is settled -/// (`docs/platform-ports.md`, Target shapes 1 and 8, which W7a publishes as `host`). +/// process. Thread-affine (not `Sync`, unlike [`Shell`], which returns it from [`Shell::open`] on the loop +/// thread). Published only through `host` (`docs/platform-ports.md`, Target shapes 1 and 8). /// /// `window` is the raw handle the [`Shell`]'s per-window calls still take (`bind_window`, /// `grab_surface`, and `textinput`'s focus read), so every call site the `frame` gate pins stays where -/// it is; W7a folds those into this trait. `poll` is SDL-shaped bytes until the platform's own event -/// sink replaces it. There is no destructor: the `App` is leaked at exit and a worker may still hold -/// the handle, so the end is the explicit, decided [`quit`](Surface::quit). -pub(crate) trait Surface { +/// it is; W9 folds those into this trait (plan, §1). **Two event paths, one of them temporary:** a +/// platform delivers its events through [`deliver`](Surface::deliver) and [`EventSink`]; the SDL shells +/// still deliver through [`poll`](Surface::poll), SDL-shaped bytes, and their `deliver` delivers nothing. +/// `poll` is retired once the SDL shells deliver through the sink (W9 at the latest). There is no +/// destructor: the `App` is leaked at exit and a worker may still hold the handle, so the end is the +/// explicit, decided [`quit`](Surface::quit). +pub trait Surface { /// The raw window handle, null for a surface that has none (the rig's). fn window(&self) -> *mut c_void; /// Present the frame. The compositor commit of the opaque-region request just made is this call's. fn swap(&self); /// 1 locks the frame rate to the panel's refresh, 0 uncaps it; the application computes which. fn set_swap_interval(&self, interval: i32); - /// Take the next event off the platform's queue into `ev`; `false` when there is none. - fn poll(&self, ev: &mut [u8; 128]) -> bool; + /// Take the next event off the platform's queue into `ev`; `false` when there is none. SDL's bytes: + /// only the SDL shells have a queue of that shape, so it is hidden and defaults to none. Retired with + /// the second path ([`deliver`](Surface::deliver) is the one that stays). + #[doc(hidden)] + fn poll(&self, _ev: &mut [u8; 128]) -> bool { + false + } + /// Hand the platform's pending input and window events to `sink`, in order, on the loop thread: called + /// once per drain, after [`poll`](Surface::poll) has been emptied. A platform whose callbacks arrive on + /// another thread queues them and delivers them here. Required: a surface with nothing to deliver + /// states it, as the SDL one does (its events still come through `poll`). + fn deliver(&self, sink: &mut dyn EventSink); /// End the platform's windowing for the process. /// /// # Safety @@ -130,11 +147,36 @@ impl Surface for plx_shell_sdl::Window { fn poll(&self, ev: &mut [u8; 128]) -> bool { plx_shell_sdl::event::poll(ev) } + /// Nothing: every SDL event, a synthetic one the dev tooling pushed included, still comes through + /// [`poll`](Surface::poll) exactly as before, so the SDL event path is unchanged. + fn deliver(&self, _sink: &mut dyn EventSink) {} unsafe fn quit(&self) { plx_shell_sdl::init::quit() } } +/// What a platform reports to the loop through [`Surface::deliver`]: the public face of the application's +/// input vocabulary, whose own event type (`HostEvent`) stays private. Every call runs on the loop thread, +/// in the order the platform saw the events. The application converts each into its event, so a platform +/// names no application type beyond these. +pub trait EventSink { + /// One edge of a key: its canonical [`Action`] where it has one, the raw pair where the platform has + /// one, and the [`Edge`]. A platform that is not SDL sends the action alone. `false` when the press is + /// refused and dropped: it carries neither field, or an action that is not what the pair names, or an + /// action no pair spells (`Action::Digit` above 9). + fn key(&mut self, action: Option, raw: Option, edge: Edge) -> bool; + /// One commit from the platform's text input, possibly empty. + fn text(&mut self, text: &str); + /// One pointer event at authored 1920x1080 coordinates. + fn pointer(&mut self, x: f32, y: f32, edge: PointerEdge); + /// One tick of the wheel, in signed whole ticks. + fn wheel(&mut self, dy: i32); + /// The window left or came back to the screen. + fn lifecycle(&mut self, edge: Lifecycle); + /// The host asks the application to end. + fn quit(&mut self); +} + /// [`Shell::init`] for an SDL platform: SDL up with the platform's two steps around `SDL_Init`, then the /// GL context request. `SDL_Init` refused ends the boot (`Exit::refused(1)`, the status it always had). /// @@ -165,7 +207,7 @@ pub(crate) fn detached_surface() -> Box { /// The dev frame probe (`/tmp/plxnative-framecb`): the platform's presentation-callback clock, read /// by the loop and by the renderer's clear hook. Unarmed, every call is a latched flag read. -pub(crate) trait FrameProbe: Sync { +pub trait FrameProbe: Sync { /// Ask for this frame's presentation callback. Call on a PRESENTING frame, before the swap. fn request(&self); /// `prepare_window` is next: starts the frame's `p` stretch. @@ -186,20 +228,20 @@ pub(crate) trait FrameProbe: Sync { /// /// `Composition::default()` is a platform that composed no URI driver (the Feed or nothing): no resolver. #[derive(Default)] -pub(crate) struct Composition { - pub(crate) resolver: Option, +pub struct Composition { + pub resolver: Option, } /// A platform's two playback steps at boot. Both are plain functions: the platform's entry states /// them once, in its `static`, and the boot calls them through [`Platform::media`]. -pub(crate) struct MediaBoot { +pub struct MediaBoot { /// Before the first adapter exists, once per process. The caller runs it only on a boot that /// touches the television (not a controlled one), so a platform's body never asks. - pub(crate) early_init: fn(&MainThread), + pub early_init: fn(&MainThread), /// Install this platform's drivers on the adapter, and return what the session must also be told. /// `controlled` is a replay or scripted Home, which touches no native port and so installs no /// native driver. It takes no session and publishes nothing: [`publish_composition`] does that. - pub(crate) compose: fn(&mut PlayerAdapter, controlled: bool) -> Composition, + pub compose: fn(&mut PlayerAdapter, controlled: bool) -> Composition, } /// Tell the route session what the platform composed: the resolver first, then the backend set the @@ -234,7 +276,7 @@ pub(crate) fn publish_composition( /// functions put their guards around them (`sound::output`'s blocking check, `secure`'s test store, /// `home`'s request counter). The one thing the application does with it is /// [`install_services`](Platform::install_services); nothing in `app` can call a hook directly. -pub(crate) struct Platform { +pub struct Platform { services: &'static Services, pub(crate) shell: &'static dyn Shell, pub(crate) diag: &'static dyn FrameProbe, @@ -243,7 +285,7 @@ pub(crate) struct Platform { impl Platform { /// A platform's entry states its four parts once, in a `static`. - pub(crate) const fn new( + pub const fn new( services: &'static Services, shell: &'static dyn Shell, diag: &'static dyn FrameProbe, @@ -469,6 +511,52 @@ mod tests { assert!(!other.shell.release_surface(), "the rest of the shell answers as the host-test one does"); } + /// **The SDL surface delivers nothing through its sink, so on the television and a desktop every event + /// still comes through `poll`, exactly as before.** An SDL key is pushed onto SDL's queue; the surface's + /// `deliver` reports none of it (the sink is called zero times), and `poll` still returns it. The + /// two-path drain therefore changes nothing for an SDL platform. + #[test] + fn the_sdl_surface_delivers_nothing_and_its_events_still_come_through_poll() { + #[derive(Default)] + struct Count(usize); + impl EventSink for Count { + fn key(&mut self, _: Option, _: Option, _: Edge) -> bool { + self.0 += 1; + true + } + fn text(&mut self, _: &str) { + self.0 += 1; + } + fn pointer(&mut self, _: f32, _: f32, _: PointerEdge) { + self.0 += 1; + } + fn wheel(&mut self, _: i32) { + self.0 += 1; + } + fn lifecycle(&mut self, _: Lifecycle) { + self.0 += 1; + } + fn quit(&mut self) { + self.0 += 1; + } + } + let _serial = plx_base::testlock::serial(); + let _events = plx_shell_sdl::testing::EventsOnly::init(); + let surface = detached_surface(); + let mut ev = [0u8; 128]; + while surface.poll(&mut ev) {} + plx_shell_sdl::inject::synth_key(plx_ui::consts::SDLK_UP, 0); + let mut count = Count::default(); + surface.deliver(&mut count); + assert_eq!(count.0, 0, "an SDL surface delivers nothing through the sink"); + // `synth_key` pushes the two edges of a tap, down then up: both are still the queue's. + for edge in ["down", "up"] { + assert!(surface.poll(&mut ev), "the pushed key's {edge} edge is still the queue's, through `poll`"); + assert!(plx_shell_sdl::event::decode(&ev).is_some(), "and it decodes as before ({edge})"); + } + assert!(!surface.poll(&mut ev), "and the queue is empty after them"); + } + /// **The SDL calls the application still declares are the two that stay.** Everything SDL-shaped /// that is the stock shell's (the window, the GL context, the queue, the text-input panel) is /// `plx_shell_sdl`'s; what remains is `system.rs`'s `SDL_GetWindowWMInfo` handshake (the television's diff --git a/rust-modules/src/app/run.rs b/rust-modules/src/app/run.rs index 2ef8d7fb0..891c4cf12 100644 --- a/rust-modules/src/app/run.rs +++ b/rust-modules/src/app/run.rs @@ -1071,6 +1071,21 @@ unsafe fn drain_sdl(app: &mut App, fr: &mut Frame) { while app.surface.poll(&mut app.ev) { ingest_sdl_event(app, fr); } + // The second path: what the platform's surface delivers through its sink. An SDL surface delivers + // nothing here (every SDL event came through `poll` above), so on the television and a desktop this + // is an empty queue; a surface that is not SDL's has no `poll` and only this. `poll` is retired once + // the SDL shells deliver through the sink (W9 at the latest, `docs/platform-ports.md`). + deliver_events(app, fr); +} + +/// Take what the surface delivers through its sink into the loop, in the order the platform made it. +unsafe fn deliver_events(app: &mut App, fr: &mut Frame) { + let mut queue = super::events::HostQueue::default(); + app.surface.deliver(&mut queue); + let shell = app.platform.shell; + for event in queue.into_events() { + ingest_host_event(app, fr, event, |win| shell.grab_surface(win)); + } } unsafe fn ingress_token(app: &mut App, fr: &mut Frame, token: &str) -> bool { @@ -4267,6 +4282,36 @@ pub(in crate::app) mod lifecycle_regression_tests { assert_eq!(second.runtime.bridge(&mut second.bridge).consent_subhash(), second_consent); } + /// A surface that is not SDL's: it has no queue to `poll` and delivers its one event, the host's + /// request to end, through the sink it is handed. + struct SinkSurface; + + impl crate::app::platform::Surface for SinkSurface { + fn window(&self) -> *mut c_void { + std::ptr::null_mut() + } + fn swap(&self) {} + fn set_swap_interval(&self, _interval: i32) {} + fn deliver(&self, sink: &mut dyn crate::app::platform::EventSink) { + sink.quit(); + } + unsafe fn quit(&self) {} + } + + /// **The loop drains a surface's sink**: `drain_sdl` hands the surface a sink, and what it delivers + /// is ingested like any event (here the host's request to end, `HostEvent::Quit`, which stops the loop). + /// A surface with no `poll` of its own reaches the loop only through this call. + #[test] + fn a_surface_that_delivers_through_its_sink_reaches_the_loop_through_drain_sdl() { + let _serial = plx_base::testlock::serial(); + let mut app = app(); + app.surface = Box::new(SinkSurface); + let mut fr = Frame::begin(&app.player.session, app.runtime.metadata_view()); + app.running = true; + unsafe { drain_sdl(&mut app, &mut fr) }; + assert!(!app.running, "the delivered quit ended the loop"); + } + fn frame(app: &mut App, now: u32) { super::super::bridge::app_frame( app, diff --git a/rust-modules/src/host.rs b/rust-modules/src/host.rs new file mode 100644 index 000000000..d68f91eb4 --- /dev/null +++ b/rust-modules/src/host.rs @@ -0,0 +1,240 @@ +//! The cross-crate construction interface: what a platform crate needs to build its `static` [`Platform`] +//! and hand it to the application (`docs/platform-ports.md`, Target shape 8). +//! +//! The application's modules are private (`mod app;`), so a crate that is a sibling of this one cannot +//! name `app::Platform` or implement a crate-private `Shell`. This is the one narrow public face: re-exports +//! of the types a platform builds or implements, an [`EventSink`] through which it reports input, and +//! [`run`], the one function in here (it hands the platform to the application's entry). No other module of the +//! application is public to a television build. A `hostsim` build also keeps the simulator binary's own doors, +//! each behind `feature = "hostsim"` in `lib.rs` (`grep -n 'feature = "hostsim"' rust-modules/src/lib.rs`): +//! `platform_desktop::run`, `hud_cli`, `sim_runtime_dir`, `sim_events_log`, `publish_sim_webos_major` and +//! `synthetic_home_initial`, the one `app` item re-exported at the crate root. `HostEvent`, the loop's own event type, stays +//! private: a platform reports input through [`EventSink`] and the application converts it. The owner's ruling (2026-11-21, Decision 3 +//! amended): the eight application-crate items `Platform`, `Shell`, `Surface`, `FrameProbe`, `MediaBoot`, +//! `Composition`, `Exit` and `Release` are reachable only through this module. `Services` is not one of the eight: +//! it is `plx_os::tv::Services`, already a `pub` type of a lower crate, which this module re-exports beside them. +//! A platform crate names the application crate's types through `host` alone; the hook tables a `Services` is +//! built from (`plx_os::tv`) and `PlayerAdapter`, which `MediaBoot::compose` takes (`plx_media`), come from +//! their own crates, which it depends on directly. +//! +//! The split is by thread. A [`Platform`] is registration data in a `static`: function pointers and +//! `&'static dyn` of `Sync` types, [`Shell`] included as a factory. The thread-affine state (the window, +//! the GL context, a toolkit's handles) lives only in the [`Surface`] that [`Shell::open`] returns on the +//! loop thread and that the application owns from then on. +//! +//! Beside the platform's own types, the vocabulary their signatures name is re-exported from the lower +//! layers it lives in ([`MainThread`], [`Action`], [`Edge`], [`RawKey`], [`Lifecycle`], [`PointerEdge`], +//! [`OpenAsk`], [`Placement`]), so a platform crate names the application crate's types, and the vocabulary they use, through `host` alone. +//! The two SDL helpers (`sdl_init`, `sdl_open`) are not here: W7b publishes what the two real platforms need. +use std::ffi::CStr; +use std::os::raw::c_int; + +pub use crate::app::platform::{Composition, EventSink, FrameProbe, MediaBoot, Platform, Shell, Surface}; +pub use crate::app::{Exit, Release}; +pub use plx_base::task::MainThread; +pub use plx_machine::machine::Edge; +pub use plx_os::tv::Services; +pub use plx_shell_sdl::event::{Lifecycle, PointerEdge}; +pub use plx_shell_sdl::{OpenAsk, Placement}; +pub use plx_ui::consts::{Action, RawKey}; + +/// Boot the application on `platform` and return the status it ended with: the application's entry +/// (`run_application`), which installs the platform's services, brings the window up through its +/// [`Shell`], runs the loop and tears down. Ending the process is the caller's, as for the television's +/// and the desktop's own entries: a process that hosts the application never does. +/// +/// `pms_host` and `pms_port` are the pair `plex_run` hands the entry and `platform_desktop::run` takes. +pub fn run(platform: &'static Platform, pms_host: &CStr, pms_port: u16) -> Exit { + crate::app::run_application(platform, pms_host.as_ptr(), c_int::from(pms_port)) +} + +/// **The owner's ruling, held in the source.** `tests/host_interface.rs` is a separate crate and reads only its own +/// spelling, so nothing there stops `lib.rs` from growing `pub mod app;` or `pub use app::platform::Shell;`: every +/// test would still pass. These pins read the crate's own source, in the style of the `include_str!` pins of +/// `port.rs` and `app/boot.rs`, and fail on that edit. The reason is Decision 3's amendment of 2026-11-21 +/// (`docs/platform-ports.md`): `host` is the only way a platform crate reaches the application's types. +#[cfg(test)] +mod surface_pin_tests { + use std::path::Path; + + /// What the crate root may make `pub`, by the head of the item: `host`, and the simulator binary's own doors + /// (a separate crate, so they must be `pub`), each existing only under `feature = "hostsim"`. `host` alone is + /// open to a television build. + const ROOT_ITEMS: [(&str, bool); 7] = [ + ("pub mod host", false), + ("pub mod hud_cli", true), + ("pub mod platform_desktop", true), + ("pub fn sim_runtime_dir", true), + ("pub fn publish_sim_webos_major", true), + ("pub fn sim_events_log", true), + ("pub use app::synthetic_home_initial", true), + ]; + + const HOW_TO_PROCEED: &str = "The application is reachable only through `host`, because the owner's 2026-11-21 amendment to \ + Decision 3 (docs/platform-ports.md) makes `host` the only way a platform crate reaches it. To publish an \ + application item (W7b's `sdl_init` and `sdl_open`, say), re-export it from host.rs, which the second pin allows. \ + Only a new simulator door that is NOT an application item, existing only under `feature = \"hostsim\"`, extends \ + ROOT_ITEMS in this test, and the reason is recorded in that amendment."; + + /// The text of an item's head: up to its first `;`, `{`, `(` or `<`. + fn head(line: &str) -> &str { + let end = line.find([';', '{', '(', '<']).unwrap_or(line.len()); + line[..end].trim() + } + + /// `(can be true, can be false)` for the cfg predicate at the start of `s` (whitespace removed), in a build with + /// neither `hostsim` nor `test` and whatever else set; also returns the rest of `s`. Any other predicate may be + /// either, so an `any(...)` naming another feature (`devtriggers` is on by default) can be true. + fn can_be(s: &str) -> ((bool, bool), &str) { + let end = s.find(|c: char| !(c.is_alphanumeric() || c == '_')).unwrap_or(s.len()); + let (name, rest) = s.split_at(end); + if let Some(mut rest) = rest.strip_prefix('(') { + let mut parts = Vec::new(); + while !rest.starts_with(')') { + assert!(!rest.is_empty(), "an unbalanced cfg predicate"); + let (part, after) = can_be(rest); + parts.push(part); + rest = after.strip_prefix(',').unwrap_or(after); + } + let result = match name { + "any" => (parts.iter().any(|p| p.0), parts.iter().all(|p| p.1)), + "all" => (parts.iter().all(|p| p.0), parts.iter().any(|p| p.1)), + "not" => (parts[0].1, parts[0].0), + other => panic!("an unknown cfg combinator `{other}`"), + }; + return (result, &rest[1..]); + } + if let Some(value) = rest.strip_prefix("=\"") { + let (value, after) = value.split_once('"').expect("a closed string"); + let never = name == "feature" && value == "hostsim"; + return ((!never, true), after); + } + (((name != "test"), true), rest) + } + + /// Whether the attribute `attr` (whitespace removed) is a `cfg` under which the item cannot exist without + /// `hostsim` or `test`: `feature = "hostsim"`, an `any` of those two, or an `all` with `hostsim` among its members. + fn confines_to_hostsim(attr: &str) -> bool { + let predicate = attr.strip_prefix("#[cfg(").and_then(|a| a.strip_suffix(")]")); + predicate.is_some_and(|p| !can_be(p).0 .0) + } + + /// The `pub` items of `source` (not `pub(crate)`, which has no space after `pub`) as `(line, head, confined)`. + /// An attribute may span lines, so each is read to its closing bracket and joined before it is judged. + fn public_items(source: &str) -> Vec<(usize, String, bool)> { + let mut found = Vec::new(); + let mut attrs: Vec = Vec::new(); + let mut lines = source.lines().enumerate(); + while let Some((at, line)) = lines.next() { + let line = line.trim(); + if line.is_empty() || line.starts_with("//") { + continue; + } + if line.starts_with("#[") { + let mut attr = line.to_string(); + while attr.matches('[').count() > attr.matches(']').count() { + match lines.next() { + Some((_, more)) => attr.push_str(more.trim()), + None => break, + } + } + attrs.push(attr.split_whitespace().collect()); + continue; + } + if line.starts_with("pub ") { + found.push((at + 1, head(line).to_string(), attrs.iter().any(|a| confines_to_hostsim(a)))); + } + attrs.clear(); + } + found + } + + #[test] + fn the_crate_root_publishes_host_and_the_simulators_hostsim_doors_and_nothing_else() { + let source = include_str!("lib.rs"); + let items = public_items(source); + for (at, item, confined) in &items { + let Some(&(_, hostsim_only)) = ROOT_ITEMS.iter().find(|&&(known, _)| known == item.as_str()) else { + panic!("lib.rs line {at} makes `{item}` public. {HOW_TO_PROCEED}"); + }; + assert!( + !hostsim_only || *confined, + "lib.rs line {at}: `{item}` is a simulator door and must exist only under `feature = \"hostsim\"` (with \ + `test` or `all(..)` at most): an `any(..)` naming another feature, `devtriggers` being on by default, \ + ships it in a television build. {HOW_TO_PROCEED}" + ); + } + for (known, _) in ROOT_ITEMS { + assert!( + items.iter().any(|(_, item, _)| item == known), + "lib.rs no longer makes `{known}` public: update ROOT_ITEMS to match. {HOW_TO_PROCEED}" + ); + } + // An exported macro is a public path into the crate that a `pub ` line scan cannot see. + assert!(!source.contains(concat!("#[macro_", "export")), "lib.rs exports a macro. {HOW_TO_PROCEED}"); + } + + /// `pub use` statements of `text`, each as `(line number, its text after `pub use` with whitespace removed)`. + /// A statement runs to its `;`, so a `{ ... }` list over several lines is one. + fn pub_uses(text: &str) -> Vec<(usize, String)> { + let mut found = Vec::new(); + let mut lines = text.lines().enumerate(); + while let Some((at, line)) = lines.next() { + let Some(rest) = line.trim_start().strip_prefix("pub use ") else { continue }; + let mut statement = rest.to_string(); + while !statement.contains(';') { + match lines.next() { + Some((_, more)) => statement.push_str(more), + None => break, + } + } + found.push((at + 1, statement.split_whitespace().collect())); + } + found + } + + /// Whether a `pub use` tree has `app` as a path segment anywhere: `crate::app::X`, `super::app::X` (from a module + /// directly under `src/`), `self::app::X` (from `lib.rs`), `app::X` and `crate::{host, app::X}` all do. + fn names_the_application(statement: &str) -> bool { + statement.split(|c: char| !(c.is_alphanumeric() || c == '_')).any(|segment| segment == "app") + } + + fn rust_sources(dir: &Path, root: &Path, out: &mut Vec<(String, String)>) { + let mut entries: Vec<_> = std::fs::read_dir(dir).expect("the source directory").map(|e| e.expect("an entry").path()).collect(); + entries.sort(); + for path in entries { + if path.is_dir() { + rust_sources(&path, root, out); + } else if path.extension().is_some_and(|e| e == "rs") { + let name = path.strip_prefix(root).expect("under the root").to_string_lossy().into_owned(); + out.push((name, std::fs::read_to_string(&path).expect("a source file"))); + } + } + } + + #[test] + fn host_is_the_only_place_that_re_exports_the_application() { + let root = Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/src")); + let mut files = Vec::new(); + rust_sources(root, root, &mut files); + assert!(files.iter().any(|(name, _)| name == "host.rs"), "the scan did not read this crate's own sources"); + let mut in_host = 0; + for (name, text) in &files { + for (at, statement) in pub_uses(text) { + if !names_the_application(&statement) { + continue; + } + if name == "host.rs" { + in_host += 1; + } else { + // The one other: the root's `hostsim`-only `synthetic_home_initial`, which the simulator binary calls. + assert!( + name == "lib.rs" && statement == "app::synthetic_home_initial;", + "{name} line {at} re-exports from the application (`pub use {statement}`). {HOW_TO_PROCEED}" + ); + } + } + } + assert!(in_host >= 2, "host.rs re-exports the application's types: the scan found {in_host} `pub use` of `app`"); + } +} diff --git a/rust-modules/src/lib.rs b/rust-modules/src/lib.rs index f1fe806ea..2d621e9d9 100644 --- a/rust-modules/src/lib.rs +++ b/rust-modules/src/lib.rs @@ -19,6 +19,11 @@ mod capture; // dev live UI capture stream: own-GLES-frame grab → MPEG1/TS or mod coldstart; // retires old last-page bookmarks; authenticated cold boots now stay on Home mod dev; // the /tmp/plxnative-* trigger surface, behind one `devtriggers` feature — read it before adding a trigger mod focusprobe; // dev: one diffable line naming everything app.rs's key ladder can move, logged when it changes +/// The one narrow public face of the application for a platform crate: the types it builds and implements +/// (`Platform`, `Shell`, `Surface`, `EventSink`, ...) and the entry `run`, as re-exports. Every other module of +/// the application stays private to a television build (`docs/platform-ports.md`, Target shape 8; a `hostsim` +/// build also exposes the simulator binary's own doors below). +pub mod host; // The simulator's HUD tools (`--hud-lint`, `--hud-schema`, `--hud-export`): a library function the thin // `src/bin/sim.rs` calls before it reads a PMS host. `pub` because that binary is a separate crate; absent // from the television build, which has no use for a linter and no argv to read it from. diff --git a/rust-modules/tests/host_interface.rs b/rust-modules/tests/host_interface.rs new file mode 100644 index 000000000..b751cc798 --- /dev/null +++ b/rust-modules/tests/host_interface.rs @@ -0,0 +1,313 @@ +//! W7a's gate: a platform built against the application crate through `plxnative_modules::host`, with the hook +//! tables of `plx_os::tv` and `plx_media`'s `PlayerAdapter` from their own crates (`docs/platform-ports.md`, +//! Target shape 8). +//! +//! This is an integration test, a separate crate that can name only the `pub` items of the application +//! crate, which is the point: a platform crate that is a sibling of the application has the same view. It +//! builds a `static PLATFORM` from a fake `Shell`, `Surface` and `FrameProbe` and boots it. +//! +//! **What "boots it" can mean here.** The real `run_application` runs, through [`host::run`], up to the +//! fake's `Shell::open`, which refuses: the boot ends with that `Exit`. It cannot go further, and no +//! fake could take it further: after `open` the boot makes real GL calls (`init_gl` links the renderer's +//! programs), which need a current GL context, and a surface that is not a real window has none. So this +//! test proves the construction interface and the boot order (the services installed, `init` before +//! `open`, `open` asked for the window the application means to ask for, the refusal returned as the +//! entry's `Exit`), not the loop. The loop's own fake-surface tests are in-crate (`make test-hostsim`). +//! +//! **The boot test needs `hostsim`** (the recipe `make test-host-interface` passes it): only there is the +//! runtime root steerable by `PLXNATIVE_RUNTIME_DIR`, so the boot's event log, crash log and diagnostics +//! land in a throwaway directory and not in a real install's. It refuses to run without that variable. +//! The rest of the file compiles in every configuration (`make lint` and `check-cargo-lint` build it), +//! which type-checks the interface from outside in the default non-hostsim feature set too. +//! +//! The application replaces the process's panic hook while it boots (`install_panic_logger`): it wraps +//! the previous hook, so a panic still reaches the test harness, and additionally writes one line to the +//! event log and the crash log in the runtime root. Only one test here boots, because the services are +//! installed once per process. +#![cfg_attr(not(feature = "hostsim"), allow(dead_code))] + +use plxnative_modules::host::{ + Action, Composition, Edge, EventSink, Exit, FrameProbe, Lifecycle, MainThread, MediaBoot, OpenAsk, Placement, + Platform, PointerEdge, RawKey, Services, Shell, Surface, +}; +#[cfg(feature = "hostsim")] +use plxnative_modules::host::Release; +use std::ffi::c_void; +#[cfg(feature = "hostsim")] +use std::ffi::CString; +use std::sync::Mutex; + +/// The refusal the fake `open` ends the boot with: a status no real refusal uses. +const REFUSAL: i32 = 73; + +/// Fake services: the production tables' `NONE` groups, and one hook of its own, so the test can see that +/// the platform's table was the one installed. +static SERVICES: Services = Services { + identity: plx_os::tv::IdentityHooks { system_locale: fake_locale, ..plx_os::tv::IdentityHooks::NONE }, + secure: plx_os::tv::SecureHooks::NONE, + system: plx_os::tv::SystemHooks::NONE, + storage: plx_os::tv::StorageHooks::NONE, + legacy_webos_media: plx_os::tv::LegacyWebosMedia::NONE, +}; + +fn fake_locale() -> plx_os::tv::LocaleReply { + plx_os::tv::LocaleReply::Reply("fake-host-locale".into()) +} + +/// A `Shell` of `Sync` state alone: an ordered call log and the window it was asked to open. +struct FakeShell { + log: Mutex>, + /// The window `open` was asked for: its title, placement and HiDPI flag. + asked: Mutex>, +} + +impl FakeShell { + fn note(&self, what: &'static str) { + self.log.lock().unwrap().push(what); + } +} + +impl Shell for FakeShell { + fn init(&self, _mt: &MainThread) -> Result<(), Exit> { + self.note("init"); + Ok(()) + } + fn open(&self, _mt: &MainThread, ask: &OpenAsk) -> Result, Exit> { + self.note("open"); + *self.asked.lock().unwrap() = Some((ask.title.to_string_lossy().into_owned(), ask.placement, ask.high_dpi)); + Err(Exit::refused(REFUSAL)) + } + fn bind_window(&self, _win: *mut c_void) { + self.note("bind_window"); + } + fn grab_surface(&self, _win: *mut c_void) { + self.note("grab_surface"); + } + fn release_surface(&self) -> bool { + self.note("release_surface"); + false + } + fn arm_opaque_region(&self) { + self.note("arm_opaque_region"); + } + fn opaque_route(&self, _player: bool) { + self.note("opaque_route"); + } + fn clear_opaque_region(&self) { + self.note("clear_opaque_region"); + } + fn pump_bus(&self) { + self.note("pump_bus"); + } + fn hide_pointer(&self) { + self.note("hide_pointer"); + } + fn show_pointer_after_motion(&self) { + self.note("show_pointer_after_motion"); + } + fn hide_is_cursor_swap(&self) -> bool { + false + } +} + +static SHELL: FakeShell = FakeShell { log: Mutex::new(Vec::new()), asked: Mutex::new(None) }; + +struct FakeProbe; + +impl FrameProbe for FakeProbe { + fn request(&self) {} + fn prepare_begin(&self) {} + fn prepare_end(&self) {} + fn waiting(&self) {} + fn acquired(&self) {} + fn fields(&self) -> String { + String::new() + } +} + +/// A surface that is not SDL's: it has no queue of bytes (`poll` is left at its default) and delivers its +/// events through the sink. Thread-affine state is its own (`!Sync`: a `Cell`), as a toolkit's would be. +struct FakeSurface { + frames: std::cell::Cell, +} + +impl Surface for FakeSurface { + fn window(&self) -> *mut c_void { + std::ptr::null_mut() + } + fn swap(&self) { + self.frames.set(self.frames.get() + 1); + } + fn set_swap_interval(&self, _interval: i32) {} + fn deliver(&self, sink: &mut dyn EventSink) { + sink.lifecycle(Lifecycle::DidForeground); + sink.pointer(10.0, 20.0, PointerEdge::Move); + sink.wheel(-1); + sink.text("ok"); + assert!(sink.key(Some(Action::Ok), None, Edge::Down), "an action alone is a key"); + assert!(!sink.key(None, None, Edge::Down), "a key of neither action nor pair is refused"); + sink.quit(); + } + unsafe fn quit(&self) {} +} + +fn early_init(_mt: &MainThread) {} + +fn compose(_adapter: &mut plx_media::player::adapter::PlayerAdapter, _controlled: bool) -> Composition { + Composition::default() +} + +/// The platform, as a sibling crate states it: a `static`, so every part of it is `Sync`. +static PLATFORM: Platform = + Platform::new(&SERVICES, &SHELL, &FakeProbe, MediaBoot { early_init, compose }); + +fn assert_sync(_: &T) {} + +/// The registration data is `Sync` (a `static` of it compiles), and the thread-affine surface is not +/// required to be: a `Surface` holding a `Cell` is accepted as `Box`. +#[test] +fn the_platform_is_registration_data_and_the_surface_may_be_thread_affine() { + assert_sync(&PLATFORM); + let surface: Box = Box::new(FakeSurface { frames: std::cell::Cell::new(0) }); + surface.swap(); + surface.set_swap_interval(1); + assert!(surface.window().is_null()); + let mut ev = [0u8; 128]; + assert!(!surface.poll(&mut ev), "a surface with no SDL queue has nothing to poll"); +} + +/// What a fake surface delivers is what its `EventSink` receives, in order, from outside the crate: the +/// sink is implementable here with the public vocabulary alone. +#[test] +fn an_event_sink_is_implementable_from_outside_and_receives_a_surfaces_events_in_order() { + #[derive(Default)] + struct Recorder(Vec); + impl EventSink for Recorder { + fn key(&mut self, action: Option, raw: Option, edge: Edge) -> bool { + self.0.push(format!("key {action:?} {raw:?} {edge:?}")); + action.is_some() || raw.is_some() + } + fn text(&mut self, text: &str) { + self.0.push(format!("text {text}")); + } + fn pointer(&mut self, x: f32, y: f32, edge: PointerEdge) { + self.0.push(format!("pointer {x} {y} {edge:?}")); + } + fn wheel(&mut self, dy: i32) { + self.0.push(format!("wheel {dy}")); + } + fn lifecycle(&mut self, edge: Lifecycle) { + self.0.push(format!("lifecycle {edge:?}")); + } + fn quit(&mut self) { + self.0.push("quit".into()); + } + } + let surface = FakeSurface { frames: std::cell::Cell::new(0) }; + let mut sink = Recorder::default(); + surface.deliver(&mut sink); + assert_eq!( + sink.0, + [ + "lifecycle DidForeground", + "pointer 10 20 Move", + "wheel -1", + "text ok", + "key Some(Ok) None Down", + "key None None Down", + "quit", + ] + ); +} + +/// **The one source rule of this file**, and it holds this file's own spelling only: every path into the +/// application crate starts `plxnative_modules::host`. What the crate itself makes reachable is not read here; +/// that is pinned in-crate, by the source pins in `host.rs`'s tests (the crate root's `pub` items, and `host.rs` as +/// the only `pub use` that names `app`). The lower-layer crates a platform crate lists as its +/// own dependencies (`plx_os`, `plx_media`) are fine to name, and this file must (a `Services` is built from +/// `plx_os::tv`'s hook tables, `MediaBoot::compose` takes `plx_media`'s `PlayerAdapter`); an edit to this file that +/// names the application crate any other way fails here. +#[test] +fn every_path_into_the_application_crate_goes_through_host() { + let source = include_str!("host_interface.rs"); + // Split, so this test's own text never matches. + let needle = concat!("plxnative_", "modules"); + let mut seen = 0; + for (at, _) in source.match_indices(needle) { + seen += 1; + let line = source[..at].matches('\n').count() + 1; + assert!( + source[at + needle.len()..].starts_with("::host"), + "line {line}: a name of the application crate that is not a path into `host`" + ); + } + assert!(seen > 0, "the scan found no path at all: it is not reading this file"); +} + +/// The entries of `dir` whose name starts with `plxnative-`, sorted. +#[cfg(feature = "hostsim")] +fn plxnative_entries(dir: &std::path::Path) -> Vec { + let mut names: Vec = std::fs::read_dir(dir) + .map(|rd| { + rd.filter_map(|e| e.ok()) + .map(|e| e.file_name().to_string_lossy().into_owned()) + .filter(|n| n.starts_with("plxnative-")) + .collect() + }) + .unwrap_or_default(); + names.sort(); + names +} + +/// **The boot of the fake platform, to its refusal.** The real `run_application` runs on `PLATFORM`: +/// it installs the platform's services, brings the shell up (`init`), reads the stored session, then asks +/// the shell for the window (`open`), which refuses. The test asserts the order, the window asked for, the +/// installed services and the returned `Exit`, and that the boot's event log landed in the throwaway runtime root. +/// It also PRINTS the `plxnative-*` entries of `/tmp` (where a device's trigger files live) and of the runtime root +/// before and after, for a reader of `--nocapture`; it does not assert on `/tmp`, which other checkouts' test runs +/// write under concurrently. +#[cfg(feature = "hostsim")] +#[test] +fn run_boots_the_fake_platform_through_init_then_open_and_returns_the_refusal() { + let runtime = std::env::var_os("PLXNATIVE_RUNTIME_DIR").map(std::path::PathBuf::from).expect( + "PLXNATIVE_RUNTIME_DIR must name a throwaway directory: this test boots the application, which writes \ + its logs and reads its triggers under the runtime root (`make test-host-interface` sets it)", + ); + assert!(runtime.is_dir(), "the runtime root {} is not a directory", runtime.display()); + let tmp = std::path::Path::new("/tmp"); + // The recipe's own throwaway directories (`plxnative-check.XXXXXX`) come and go with other runs. + let outside = |names: Vec| -> Vec { + names.into_iter().filter(|n| !n.starts_with("plxnative-check.")).collect() + }; + let tmp_before = outside(plxnative_entries(tmp)); + let runtime_before = std::fs::read_dir(&runtime).map(|rd| rd.count()).unwrap_or(0); + + let host = CString::new("127.0.0.1").unwrap(); + let exit = plxnative_modules::host::run(&PLATFORM, &host, 32400); + + assert_eq!(exit, Exit { code: REFUSAL, release: Release::Retained }, "the fake's refusal is the entry's Exit"); + assert_eq!(*SHELL.log.lock().unwrap(), ["init", "open"], "init, then open, and nothing after the refusal"); + let (title, placement, high_dpi) = SHELL.asked.lock().unwrap().clone().expect("open was asked for a window"); + assert_eq!(title, "PlxNative", "the title a hostsim build asks for"); + assert_eq!(placement, Placement::Desktop, "a hostsim build asks for the desktop placement"); + eprintln!("open was asked for: title {title:?}, {placement:?}, high_dpi {high_dpi}"); + assert!( + matches!(plx_os::tv::system_locale(), plx_os::tv::LocaleReply::Reply(ref l) if l == "fake-host-locale"), + "the services the application installed are the platform's own table" + ); + + let tmp_after = outside(plxnative_entries(tmp)); + let runtime_after: Vec = std::fs::read_dir(&runtime) + .unwrap() + .filter_map(|e| e.ok()) + .map(|e| e.file_name().to_string_lossy().into_owned()) + .collect(); + eprintln!("/tmp/plxnative-* (outside plxnative-check.*) before: {tmp_before:?}"); + eprintln!("/tmp/plxnative-* (outside plxnative-check.*) after: {tmp_after:?}"); + eprintln!("runtime root {}: {runtime_before} entries before, after: {runtime_after:?}", runtime.display()); + assert!( + runtime_after.iter().any(|n| n == "plxnative-events.log"), + "the boot's event log is not in the runtime root {}: {runtime_after:?}", + runtime.display() + ); +} diff --git a/rust-modules/ui/src/consts.rs b/rust-modules/ui/src/consts.rs index 69a25e4a3..131c86548 100644 --- a/rust-modules/ui/src/consts.rs +++ b/rust-modules/ui/src/consts.rs @@ -491,6 +491,21 @@ pub fn is_remote_bound(sym: c_uint, wcode: c_uint) -> bool { action_of(sym, wcode).is_some() } +/// The raw `(sym, wcode)` pair a key arrived as. Kept beside the [`Action`] because three things +/// still read it: a press with no action (an unsupported key flows on as exactly the pair it was), +/// the lab trigger key (named by `lab.json`, not by an action), and the recorder's tape, whose +/// format IS the pair. A platform with no SDL pair sends none, and the loop builds [`raw_pair`] +/// for its action. +/// +/// It lives here, beside [`raw_pair`] and [`action_of`] whose pair it names, so a platform crate +/// reaches it without the application's private events module (`docs/platform-ports.md`, Target +/// shape 8: `host::EventSink::key` takes one). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct RawKey { + pub sym: c_uint, + pub wcode: c_uint, +} + /// **A key press by what it MEANS, with no SDL in it** — the vocabulary a platform that has no SDL /// key pair hands the loop (`HostEvent::Key`'s `action`), and the one the screens move onto when /// they stop reading `(sym, wcode)` themselves.