This is the long-form architecture, build, portability, and verification reference shared by all
coding agents. The concise, always-loaded project contract is AGENTS.md; Claude imports both.
A real, native Plex client for LG webOS 4.5 TVs — built toward production quality, not a
throwaway. Build proper, reusable, well-factored components and finish them — a shortcut is
never justified by "it's only a demo." See rust-modules/ui/src/CLAUDE.md for how the UI is
expected to be built. It's cross-compiled from macOS and sideloaded onto a rooted 32-bit ARM TV,
renders an Apple-TV-style gallery/shelf UI with SDL2 + OpenGL ES 2, and plays video from a Plex
Media Server (PMS) entirely in-app.
Almost everything is Rust in rust-modules/ (UI, event loop, input, player orchestration,
the streaming/demux pipeline, and the Plex data layer), compiled to a static lib and linked in
(see the Makefile). What stays C is src/main.c — a small boot shim (the event-log
handle, stderr capture, process bring-up) that then calls the Rust plex_run() — and
src/starfish.c, the buffer-feed StarfishMediaAPIs C++ seam, and src/video_plane.c, the shared
ACB/exported-window display binding, beside src/svg.c (the nanosvg rasterizer),
src/sentry_context.c, src/exit.c, src/access.c (the key-files list below says what each does) and, since
2026-08-29, src/crashtrace.c — the async-signal-safe crash tracer, lifted out of main.c into
its own translation unit for one reason, that ci/crashtrace-test.c links it ALONE and can therefore
fault a process on purpose and check how it died. Doing that immediately found a seven-week-old bug no
log could have shown (below).
Target device: LG 49SM9000PLA, webOS 4.5, rooted, reached as root over ssh. Its address is NOT
in the repo — it comes from one line (an IP or hostname) in a gitignored file, found by ONE shared
resolver, tools/tv-config.sh (host / mac / dir / set-mac), which the Makefile's TV
and every tools/ script, tests/run.py and the wake-tv skill call instead of carrying their own
lookup. Order, first non-empty wins: the caller's environment (each tool keeps the variables it
always honoured: make TV=1.2.3.4 … for one invocation, PLX_TV_ADDR/TV/TV_HOST, TV_MAC),
then this checkout's .tv-host (.tv-mac), then the MAIN checkout's, then the per-USER file
${PLX_TV_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/plxnative}/tv-host (tv-mac). Set the
per-user pair once per machine and every checkout and linked worktree sees it: no worktree setup
hook and no copying, which would go stale the first time the address or MAC changed in one place.
The per-checkout file stays as an override. An empty or whitespace-only file counts as absent;
PLX_TV_NO_HOST_FILE=1 switches all the files off. wake-tv.sh writes a MAC it learns from ARP to
the per-user tv-mac (mode 600), so it is known the next time the set is asleep — exactly when
Wake-on-LAN needs it. A target that needs a TV with none configured fails saying so
(ci/test_tv_config.py grades the resolver and its readers; ci/test_tv_ssh.py the ssh wrapper). The ssh password
alpine lives in tools/tv-ssh, not the Makefile, and is tried only after this machine's ssh key is
refused. It is webosbrew's published dev-mode root password, identical on every rooted TV, so it
identifies nobody and removing it would break the loop for key-less machines. App id com.beb.plxnative — and since 2026-08-21 a second
install, com.beb.plxnative.debug, can sit beside it on the same set (FLAVOR, below;
docs/two-installs.md).
Every non-Rust input (FFmpeg, Sentry Native, the libass font stack, nanosvg, jsmpeg, the webOS NDK,
the webosbrew toolbox) is declared once in ci/dependencies.json: version, URLs (plus transport-only
mirrors), sha256, pinned patches, licence, and an update object saying where its releases come from
(github-release, github-tags, github-commit, listing, manual; an optional hold string freezes
the entry and is the reason). ci/deps.py reads and fetches it; nothing else writes a version or digest.
Dependabot cannot read that file, so ci/deps-update.py does its job: --report prints pinned vs
latest per entry, --bump NAME downloads the new asset, recomputes the sha256 and rewrites
the entry's version, URLs and digest (never a patch; a patch that no longer applies exits 3 and
the PR says so). .github/workflows/deps-update.yml runs weekly, opens one PR per outdated
dependency on deps/<name>-<version> and dispatches ci.yml on it (a GITHUB_TOKEN push starts no
CI by itself). Reviewing such a PR: FFmpeg, Sentry Native, curl-adjacent and NDK bumps need the
fw-compat-reviewer agent, and every bump needs a THIRD-PARTY-NOTICES.md check. The same workflow
submits the manifest to GitHub's dependency graph on every push that changes it
(deps-update.py --snapshot). Held today: webos-ndk (pinned to the TV firmware ABI) and
webosbrew-toolbox (independent release tag, package version and firmware symbol data). A new
entry needs an update object; ci/test_deps_update.py fails without one.
The Makefile is the entire dev loop. Requires the webOS NDK (install with make setup-env), the pinned stable Rust toolchain (the channel of rust-modules/rust-toolchain.toml, with the armv7-unknown-linux-gnueabi rust-std, clippy and rustfmt; make setup-rust installs it, make -s print-rust-toolchain prints it), CMake (Homebrew, for
the pinned Sentry Native cross-build), and sshpass (Homebrew; deploy/run use your ssh key first and need it only when the TV refuses the key). See the
setup-environment skill (.agents/skills/) for the full one-time setup + troubleshooting.
make setup-env— download + extract +relocate-sdk.shthe webOS NDK into$(WEBOS_SDK)(default~/webos-ndk/…). One-time; re-runrelocate-sdk.shif you move the SDK.tools/sim.ps1 setup|build|run|shot|send— Windows 11 UI/Plex simulator through the existing Ubuntu 22.04 WSLg runtime. It uses GPU-accelerated desktop OpenGL, keeps build/runtime state on WSL's Linux filesystem, and stages fonts, their notice and the bundled ASS renderer into an isolated app directory. Itsmake sim-wslbuild is optimized and deliberately skips host FFmpeg, so it covers UI, sign-in, Plex browsing, screenshots and remote commands but not demux/clock-sink playback. WSLg's non-blocking GLX swap is capped at 60 Hz in the Linux host build. The launcher also refuses WSLg'suse_gfxredir=0copy fallback, where GL swaps can remain at 60 while the Windows surface updates at only a few FPS. See theui-simskill.make— buildpkg/plxnative(the ARM binary), and, first, the FFmpeg it ships (ci/build-ffmpeg.sh; ~2 minutes on the first checkout to want that configuration, 3 seconds in every checkout after — the source and object tree is machine-wide under$PLX_BUILD_CACHE, default~/.cache/plxnative, keyed by the configure flags so a dev tree and a RELEASE tree cannot be confused for one another; only the 3.8 MB prefix is per-checkout) plus the checksum-pinned Sentry Native static libraries and out-of-process handler (ci/build-sentry-native.sh; CMake, patched for the webOS glibc-2.12/ARM32 ABI). Also compilesci/ffabi-assert.cagainstvendor/ffmpeg-prefix/include— the headers the shipped libraries were built from, installed by the same invocation that produced them — which is what provesmedia-codecs/src/ffi.rs's ABI table. One header tree per target, one FFmpeg. This line long said BOTH vendored trees (n3.3 and n4.0) and two tables, which was true while the app read the television's FFmpeg and had to select a table per firmware; bundling collapsed that into a single equality (ffabi-assert.copens by assertingLIBAVFORMAT_VERSION_MAJOR == 63), and the vendored trees are gone. Since 2026-08-28 there ARE two tables again, and the axis is POINTER WIDTH rather than version.make sim-macosbuilds the same FFmpeg 9.0 from the same component list for this Mac (HOST=1 ci/build-ffmpeg.sh→vendor/ffmpeg-prefix-host, staged intopkg/aslibavformat-plx.63.dylib) so the simulator can demux at all, andffabi-assert.c#ifs on__SIZEOF_POINTER__, each half compiled against its own build's headers. That is not the old runtime major-selected table returning: this picks between two ABIs of ONE version at COMPILE time, on evidence the compiler holds — and deriving the second half is what foundAVSubtitleRectmodelled withflagsin the wrong place.ARM_PROFILE— which cargo profile the ARM build uses. A plain localmake/make deploybuilds the staticlib and the storage helper with[profile.tvdev](inherits = "release",lto = "off",codegen-units = 16), because the fat-LTOreleaseprofile that keeps the binary underci/build-budgets.jsondoubles the local edit-rebuild. Measured on a quiet M-series Mac after touching a file inrust-modules/screens/src/:make pkg/plxnative70 s onreleaseagainst 11 s ontvdev; the unstrippedpkg/plxnativeis 14.2 MB against 21.2 MB, and the stripped onemake ipkstages is 11.3 MB against 13.5 MB, so atvdevbinary does not meet the size budget and is never graded against it. Same opt-level, panic strategy (unwind), debug info and RUSTFLAGS, so it links and passesci/check-elf.shandci/check-package.pythe same way.releaseis selected wheneverRELEASE=1,SYMBOLS=1,FLAVOR=stable|nightlyor a CI environment (CI/GITHUB_ACTIONS, which GitHub sets on every job; the workflows are untouched andci/test_arm_profile.pypins the rule).make ARM_PROFILE=release ...(or=tvdev, on the command line or in the environment) overrides it either way. Anything that measures performance on the TV (FPS, frame pacing, scroll smoothness, CPU/GPU) must useARM_PROFILE=release:tvdevloses the cross-crate inlining the per-frame UI code relies on, so its numbers are not the shipped ones. This is enforced rather than remembered:make deploywrites the profile into<app dir>/arm-profileon the set, andtests/run.py --fps/--fps-player/--graphics-profile,tools/profile-graphicsandtools/tv-sched-trace.shread it throughtools/arm_profile_guard.pyand stop with a one-line message namingmake ARM_PROFILE=release deploywhen it saystvdev(a missing record is a binary deployed before the record existed or installed from a package, both release, and is accepted asunrecorded).tests/run.py --buildbuilds both goals withARM_PROFILE=releasefor those runs only; the playback, pipeline and server cases keep the fast default. The profile is printed in the FPS suite's header and summary and written to the graphics-profile bundle'smetadata.jsonandsummary.txtand toprofile-graphics's;tests/test_arm_profile_guard.pypins the rule. Graders that only read captured evidence (tools/image-cache-stress.py,tools/analyze-*) cannot know which binary produced it: run that evidence on areleasedeploy. The staticlib lands inrust-modules/<tdir>/armv7-unknown-linux-gnueabi/<profile>/, and a non-releaseprofile adds+profile:tvdevtopkg/.build-config(nothing is added forrelease, so shipped stamps are unchanged), so switching profile relinks rather than reusing the other profile's archive.HOST_THREADS— OPT-IN: rustc's parallel front end for the local host test builds. The crate 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 hostcargo testrecipes (check-cargo-unit-default,check-cargo-unit-hostsim,test-fast,test-crate,test-hostsim,test-host-interface,build-bench) throughCARGO_BUILD_RUSTFLAGS. Measured 2026-10-05 on an M4 (10 cores) on nightly,make build-benchnon-incremental edit-rebuilds, medians of 5:plx_baseleaf 20.1 s to 17.8 s,plx_ui10.7 to 7.8,plx_screens8.3 to 5.7, app 4.8 to 2.9; the incrementaltest-fastloop is unchanged within noise. It costs about 20% more CPU-seconds to finish sooner. It used to be on by default; the host suites now run on the pinned STABLE toolchain, whose rustc rejects every-Zflag, so the default is 0 andmake RUST_TOOLCHAIN=nightly HOST_THREADS=8 test-fastis the way to ask for it. AHOST_THREADSabove 1 on a toolchain that is not nightly is a Makefile$(error), not a cargo failure mid-recipe. It is never exported, so the ARM staticlib, the simulators, clippy and the packaging steps never see it, and aRUSTFLAGSyou exported yourself wins. Artifacts built with and without it coexist in one target dir.ci/test_host_threads.pypins the scoping, the error and, when a nightly is installed, that the toolchain still accepts the spelling (rustc -Zhelpalready calls-Zthreadsdeprecated for--jobs-frontend).make deploy— ships the binary and the native crash handler through a.new+mvdance (a running process holds their inodes), the bundled FFmpeg libraries with a retirement loop for any previous major, and — since 2026-09-02 — everything else in ONE scp fromDEPLOY_FILES, which isAPP_FILES(the exact listipkstages into the.ipk) minus those three carve-outs: this flavour'sappinfo.json, both icon sizes,pkg/splash.png, the font files (UNCONDITIONALLY, including the 13 MB CJK face — the oldtest -f || scpguard on the fonts meant a changed one could never reach the TV, and a separate md5 guard on the CJK face alone had the same failure mode by omission: it keptpkg/splash.png, both icons,pkg/OFL.txtandTHIRD-PARTY-NOTICES.mdoff the deploy path for as long as this recipe spelled its file list out by hand instead of sharingipk's),pkg/OFL.txtandTHIRD-PARTY-NOTICES.md.deploy's last step is nowverify-deploy: it md5sums every shipped file on the television (ci/verify- deploy.pyagainst the local copy) and fails loudly on any mismatch or absence, which is the check that would have caught the splash regression instead of leaving a stale launch image on a debug install for weeks. Whether webOS itself also cachessplashBackgroundsomewhere outside the app directory is not settled — webosbrew's ownappinfo.jsonguide documents SAM caching the appinfo.json JSON at boot for BUILT-IN apps only ("you will likely have to restart sam"), which is a different claim (metadata, not the referenced PNG's bytes) about a different install class (built-in, not a sideloaded native app whose directorydeployoverwrites in place); no vendor or community source found describes a separate cache of the image itself. Community tier only, and unverified either way — settling it needs a real device (deploy a changed splash, relaunch without reinstalling, and see which image shows). Refuses if the flavour has never been installed, namingmake FLAVOR=… install, and refuses a dev build on the stable id (seerelease-guard).make run— close any running instance, wipe this install's event log (make -s print-eventlog), launch, keep aliveRUN_SECS(default 18s), thencatthe on-device event log back to your terminal.make check— the host unit suite, no TV, preceded bymake lint. Not a prerequisite ofall— the cross-build must never depend on a host toolchain run.checkitself is now a thin wrapper (tools/check-lock.py) around the real recipe,check-unlocked: two machine-wideflockslots bound everymake checkacross every worktree on the machine to TWO at a time, because concurrent cold builds (~1 GB RSS each) thrash far worse than queuing (measured 2026-09-28: a lone run ~10 min, seven concurrent ones stretched one run to 60 min). It was a single lock until 2026-10-06; on an Apple M4 (10 cores, 16 GB) a lone warm run was ~185-205 s (~200 s on 2026-10-07 on main b79a17de withcheck-python-reststill one serial recipe of ~200 s; ~101 s once it runs its steps concurrently,check-python-harness~85-100 s now being the long branch) and two at once finish in 0.67-0.76 of the back-to-back time (warm, cold, and cold without the seed cache; 5-6 GB peak, no swap growth, each run of a pair 1.35-1.55x slower than alone). Three at once was not measured and is expected to swap on 16 GB. A third caller waits and gets EVERY holder's pid/worktree/start time printed every 60 s rather than silently sharing the CPU/RAM. The slot files are~/.cache/plxnative/check.lock(slot 0, the historical path) andcheck.lock.1; the default is two slots on a host with at least 8 cores and 14 GiB of RAM and one otherwise,PLX_CHECK_SLOTS=Noverrides it (1is the old one-at-a-time lock),PLX_CHECK_LOCK=offbypasses the lock, a second run from the SAME checkout waits for the first whatever the slot count (check.lock.wt-<hash of the resolved checkout root>, taken before the gate and the slots; its message reads "anothermake checkis already running in this worktree"), and--timeout(passed to the wrapper directly, not throughmake) exits 75 instead of waiting forever.make build-bench/build-bench-quickpass--exclusive: the wrapper takes the intent gatecheck.lock.gateand then EVERY slot, and a check that arrives while the gate is held waits, so a benchmark waits only for the runs already going and then has the machine to itself (two benchmarks cannot deadlock; they are not ordered between themselves).check-unlockedruns two independent branches at once (tools/check-parallel.py, never more than two branches):check-cargo(clippy, both unit-test passes, the lab-diagnostics type-check and the ci/ self-tests that drive cargo) andcheck-python(every Python/shell/C gate, includingtests/test_harness.py; it never invokes cargo and modifies no source or build input; only Python bytecode caches may appear). Each branch's output is held and printed whole in that order, so the log never interleaves; a failing branch is printed first and stops the other.make check-cargoandmake check-pythonrun one half alone.check-cargois itself the serial union ofcheck-cargo-lint(clippy + the lab-diagnostics type-check),check-cargo-unit-defaultandcheck-cargo-unit-hostsim.check-pythonis likewise two branches run side by side,check-python-harness(tests/test_harness.pyalone, ~65-85 s) andcheck-python-rest(every other gate, ~70 of them).check-python-restis only the runner overci/check-python-steps.txt, the one list of those gates:tools/check-parallel.py --stepsruns them a bounded number at a time (the core count, at most 4;PLX_CHECK_STEP_JOBS=Noverrides), prints each step's whole output with its wall and CPU time when it ends, runs every step even when one fails and ends with the failed steps by name. A new gate is ONE line in that file (CI runs the same target, so there is no second place), andci/test_ci_split.pyfails on a test file that no gate runs. Because steps overlap, a step must write only to a directory it made, bind port 0 and not touch the checkout (ci/test_check_collisions.pyruns a mix of them together and scans for fixed ports); the manifest's header lists the rules. Two of those gates are registries rather than tests:ci/check-plex-requests.pymakes every request the plex layer can make say whether it pages, andci/check-list-caps.py(registryci/list-caps.ini) makes every cap-shaped bound on a collection (.take(N),.truncate, a length.min(N), aMAX/CAP/LIMITconstant, a[..N]cut) say whether it bounds work, previews a list that is reached some other way (theroute), is a format limit, or is an openreachcap on what the user can reach, which is the only class that is tracked rather than accepted;--siteslists every hit with its class. CI runs the three cargo targets plus those two as five parallel jobs (host-lint,host-unit-default,host-unit-hostsim,host-python,host-python-harness) behind an aggregator namedhost checks (NOT a device gate);ci/test_ci_split.pypins that no gate falls between them. The cargo half runscargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_shell_sdl -p plx_owpon the default feature set, and again with--features hostsimfor the crates that declare it (HOSTSIM_SUITE: all ofUNIT_SUITEexceptplx_net,plx_ui,plx_appkit,plx_screens,plx_media_codecs,plx_play_uri,plx_playback_contractandplx_owp, which have nohostsimcfg and run the same test names in both passes;ci/test_test_crate.pyfails if one gains the feature or a cfg), which is not a duplicate run. The host feed seam (play-feed/src/ffi_host.rs) exists ONLY in the hostsim configuration, so every test that drives an access unit throughsf_feedis compiled out of the default pass and cannot fail it — which is how the prime-livelock regression (player::engine::prime_livelock_tests) sat outside the gate entirely while 1398 default-feature tests passed. Cargo keys fingerprints by feature set, so the two coexist in onetarget/and the second pass costs seconds warm. See the testing section for what it does and does not cover. The per-crate test binaries (UNIT_SUITE) run side by side, not one after another.cargo testexecutes the binaries it builds serially, so after the workspace split the suite's wall time was the SUM of the per-crate times and one slow binary set it: measured 2026-10-05, 78.8 s sequential, of whichplx_mediaalone was 28.7 s becauseroute::decision::plan_tests::unconfirmed_profile_5_forbids_copy_before_mdeheldtestlock::serial()for 16 s (its mock PMS waited out an 8 s deadline per loop pass for a fourth request that never comes; every other test in that binary that takesserial()(190 call sites) queued behind it). In the single pre-split binary that wait overlapped with everything else, which is why the suite then ran in 60.5 s and the split alone cost 23 s. Every recipe that runs the suite (check-cargo-unit-default,check-cargo-unit-hostsim,test-fast,test-hostsim) therefore wraps the samecargo ... test --lib -p ...line intools/cargo-test-parallel.py($(UNIT_RUN)): it builds with--no-run --message-format=json-render-diagnostics, runs the reported test executables with a bounded job count (PLX_TEST_JOBS, defaultmin(6, CPUs); each binary gets its share ofRUST_TEST_THREADS), each in its package directory with its ownPLXNATIVE_RUNTIME_DIRsubdirectory (honoured by thehostsimpass only:paths::ENV_STEERABLEis off in the default pass, which resolves the runtime root to/tmp) and its own EMPTYTMPDIRthat the binary must leave empty (a fixture that leaks$TMPDIR/<name>-<pid>fails the run; per-process scratch usesplx_base::testscratch::process_dir, removed at exit), and prints every binary's whole output, including its literaltest result:line. It keeps the gate honest: every binary runs even after a failure (exit 101 if any failed), a package that produced no test executable, or a build that reported none, is an error, and a failed build returns cargo's status. The opt-in--require-match(onlytest-hostsimpasses it) also fails a run whose filter ran no test in any binary, because libtest prints0 passed ... filtered outand exits 0 for a mistyped name.ci/test_cargo_test_parallel.pypins those. CI is unchanged: its unit jobs call the same make targets. Measured the same day on the 10-core Mac (binaries already built): 78.8 s sequential -> 17.9 s with 4 jobs and 14 s with 6 or more, after the fixes to the 16 s test and toplx_plex's TEST-NET connect-timeout test. The remaining long pole isplx_media's chain ofserial()tests (about 12 s end to end even alone).make lint— three named clippy lints (ifs_same_cond,same_functions_in_if_condition,if_same_then_else) over the whole crate,-A clippy::allfirst so nothing else can fail the gate (rustc's own warnings still print). It exists for one bug class the unit suite cannot reach: a shadowed branch. A duplicatedelse ifwith an empty body once hid the arm that opens the player's track menu — rustc does not warn on a repeated condition, and the dispatch is inside the SDL event loop where no host test can see it. Needs the clippy component of the pinned toolchain (make setup-rustinstalls it with--profile minimal --component clippy).make test-fast [T=filter]— opt-in incremental inner loop: the same default-featurecargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_shell_sdl -p plx_owpascheck-cargo-unit-default(throwaway runtime root, telemetry env), but withCARGO_INCREMENTAL=1in its ownrust-modules/target-fast(gitignored).T=route::is the test-name filter, handed to every one of the per-crate test binaries; each prints its own libtesttest result:line (the counts are per crate, never one total), followed by the wrapper's summary line. Use it for a long series of small edits in one lane: an edit-rebuild is ~10 s against 31-32 s non-incremental, flat across leaf/mid/hub edits (measured 2026-10-01, 5 interleaved rounds; cold is 51.7 s vs 46.2 s, so it loses on a one-off run). The price is disk: the dir grows to ~2.7 GB (debug/incremental2.0 GB) against ~1.0 GB fortarget.tools/build-gc.sh --incremental(or--lanes) reclaims it, orrm -rf rust-modules/target-fast;tools/cargo-seed.pynever seeds or harvests it. Refused underRELEASE=1. Linked worktrees stay non-incremental by default (the Makefile setsCARGO_INCREMENTAL=0only when.gitis a file; the main checkout keeps its cache);ci/test_test_fast.pypins that thecheck*andlintrecipes never nameCARGO_INCREMENTAL=1ortarget-fast, and thattools/cargo-seed.pyandtools/build-gc.shtreat the dir correctly.make test-crate C=plx_ui [T=filter] [DEPS=1]— test what you touched: builds and runs only the named crate's lib tests (several crates:C='plx_ui plx_plex'; the application crate isC=app;plx_is optional) in the SAMEtarget-fasttree and with the same environment astest-fast. An edit in a low crate makestest-fastrebuild and relink every dependent's test binary; this builds the one crate.DEPS=1adds the workspace crates that DIRECTLY depend on it, read fromcargo metadata(tools/test-crate.py; no list kept anywhere). The features are the point: the application crate's defaults (devtriggers,devtools,threadcheck) are what turn on the dev surface in every layer, and cargo unifies features only across the packages it is asked to build, so a barecargo test -p plx_plexruns 458 tests where the suite runs 466. The tool reads the full suite's resolution (--unit-graph, nothing compiled) and passes each feature the full build enables on the selected crate and on the crates it names in itsCargo.tomlas explicit--features crate/featureflags. Cargo only lets--featuresaddress those, so a third-party crate that two workspace crates request different features of can still compile as a second variant the first time you switch crates; each variant is cached after that. Refused underRELEASE=1.ci/test_test_crate.pypins the command shape against a fake cargo. Measured 2026-10-05, 10-core Mac, medians of 3, one appended comment per run (the incremental tree warm; "build only" isT=naming no test): an edit inplx_basecostsmake test-fast27.2 s (10.0 s build only) andmake test-crate C=plx_base1.7 s (1.2 s build only); an edit inplx_screenscosts 22.7 s (3.4 s) and 8.3 s (3.1 s);DEPS=1onplx_basepulls in the application crate and costs 24.2 s.cargo-nextestwas measured and is not used: 33-40 s for the same suite against the wrapper's 14 s (it runs each of the 5758 tests in its own process), and one of its three runs failedaccount_to_settings_never_unfreezes_the_host, a test that fails about one run in three when started alone in a fresh process (300 runs, with a shared and with a private runtime dir) and is hidden in the suite by the tests that run before it in the same process. Adopting it would also need the tool on every machine and CI job.make test-hostsim [C=<crate>] [T=filter]— thehostsim-feature unit tests (#[cfg(all(test, feature = "hostsim"))]: the application crate'sapp/run.rslifecycle_regression_tests, the player-return rig;plx_media'splayer/engine.rs,pump.rs,route/decision.rs), whichtest-fastandtest-cratedo not build.Cnames the crate under test, spelled as fortest-crate(C=plx_media,C=media; several allowed) and defaulting to the application crate (C=app); it changes nothing else, so there is one recipe, one managed dir and one--require-matchfor all of them. It runscargo test --lib -p <crate> --features hostsimon the pinned toolchain through$(UNIT_RUN), with a freshPLXNATIVE_RUNTIME_DIR(thehostsimfeature is what makes it steerable) that the recipe removes on exit, and with--require-match: aT=that matches no test exits 1 instead of reporting0 passedand passing, which includes a correctly spelled test that lives in another crate thanC. The features are the crate's own plushostsim, not the application crate's defaults that the full suite unifies in (the gaptest-crateexists to close,plx_plex458 tests against 466): forC=plx_mediathat made no difference, 1839 passed / 60 ignored, the linemake check's hostsim pass prints for the crate (measured 2026-10-19); another crate withdevtriggers-gated tests would run fewer. It is incremental, by design, in its ownrust-modules/target-hostsim(gitignored), for the reasontest-fastis: the Makefile's measured policy keeps shared and linked-worktree builds non-incremental, and this is the same opt-in edit loop for the one test settest-fastcannot run.test-fast's measured edit-rebuild (~10 s against 31-32 s) is for the 14-crate default-feature suite, not this one-package build, and so is its ~2.7 GB; this tree was 1.7 GB after a cold build oflifecycle_regression_tests(62 tests, 31 s wall, 2026-10-19), and 2.9 GB onceC=plx_mediahad run too, because a layer crate built alone compiles a second feature variant of the shared dependencies into the same dir.make disklists the tree, andtools/build-gc.sh --incremental(cache only) or--lanes(whole tree), orrm -rf rust-modules/target-hostsim, reclaims it. It replaces the former hand-run recipe that pointedCARGO_TARGET_DIRat a/tmpdirectory: those trees were not in any checkout, so no tool counted or reclaimed them (28 of them, 45.6 GiB, were found in/tmpon 2026-10-19). Refused underRELEASE=1;ci/test_managed_targets.pypins 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'shostmodule (rust-modules/src/host.rs, the one path a platform crate names the application's types by) used from OUTSIDE the crate byrust-modules/tests/host_interface.rs, an integration test and so a crate of its own. It builds astatic Platformfrom a fakeShell,SurfaceandFrameProbe, boots it throughhost::run(the realrun_application) and asserts thatinitran beforeopen, theOpenAskthe application made, and the fake's refusal returned as the entry'sExit. The boot cannot go further: afteropenit makes real GL calls, and a fake surface has no GL context (nothing stubs GL undertest-support), so frames and the loop are graded by the in-crate tests ofmake test-hostsim, not here. It needshostsim, because only there doesPLXNATIVE_RUNTIME_DIRsteer 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 startsplxnative_modules::host(its own spelling only; the crate's surface is pinned byhost.rs's tests, whichmake test-crate C=plxnative_modulesruns). Same shape astest-hostsim: incremental inrust-modules/target-hostsim, through$(UNIT_RUN)(a--testline is passed through), refused underRELEASE=1, inSIDE_EFFECT_FREEandDISK_ENTRIES.make checkruns the same test non-incrementally as the second cargo line ofcheck-cargo-unit-hostsim(--libnever builds an integration test), pinned inci/test_ci_split.py'sGATES. The file needs no[[test]]entry (cargo findsrust-modules/tests/*.rs), so the root manifest and theci/proofscertificates that hash it are unchanged.make fuzz-hud [T=<target> ...] [SECS=60]— thecargo fuzzpackage 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),address_parse,catalog_parse(the registry index),catalog_verify(the signed index: no input is accepted under the shipped keys; the fuzzer's bytes are also signed with the data layer's TEST ONLY keys to reach what follows the signature check),catalog_cache(its cache record, verified again),ws_frame(the WebSocket codec,plx_net::ws: the server's upgrade answer and frames, split at any byte) andowp_json(the Open Watch Party reader,plx_owp::json: the scan keeps the length, and the visitor marks the same strings and numbers as the scan). Each target asserts only what its code promises (no panic, the documented bounds, round trips) and a crash fails the run, with the input infuzz/artifacts/<target>/. The package is a top-levelfuzz/with its own[workspace], so no shippedCargo.tomlnames it and no shipped build changes; it depends on the layer crates by path, withplx_media/hostsim(the host configuration of the layers below it: the stand-ins they compile in place of the television's calls, so the package links and runs on a desktop), andfuzz/build.rsreusesrust-modules/build_support/host_link.rs.tools/fuzz-hud.pyis the whole workflow (list | seed | lock | build | run): it copiesrust-modules/Cargo.lockto the gitignoredfuzz/Cargo.lock(the shared crates are exactly the shipped versions), builds with the nightly named byFUZZ_TOOLCHAIN(defaultnightly; CI names a dated one;cargo install cargo-fuzz --lockedonce) inrust-modules/target-fuzz(3.1 GiB after a cold build of the first eight targets, plus 83 MiB forws_frameand 49 MiB forowp_json;make disklists it), generates the seeds from the fixtures, the examples and the icons the repository already has plus a dictionary from the published schemas, and runs the targets one after another. A corpus is thousands of tiny files read and written all run long: on a slow or shared disk (the external one a lane may sit on) setFUZZ_WORK=<dir>to move seeds, corpora and artifacts to a fast one, or a 5 minute run spends its first two loading the corpus. Minimise a crash withcargo +nightly fuzz tmin --fuzz-dir fuzz --target-dir rust-modules/target-fuzz <target> <file>, add it as a red-first test in the owning crate, then fix the code..github/workflows/fuzz.ymlbuilds every target and runs each for 10 s on a PR that touches the package or a parser, and runs each for 5 minutes weekly, resuming from a cached corpus when the cache still holds one. Not a gate: nothing inmake checkruns it.make check-nodef— the shipping-feature-set type check,cargo check --lib --no-default-features --features play-uri,play-feed, which is the configurationRELEASE=1ships and whichmake checkdoes not cover. The backend features are part of the shipping set: both are in the application crate'sdefault, so the bare--no-default-featureswould check a build with no playback backend (PLAYBACK_BACKENDS=uri|feedchecks that one backend's set;nonechecks the bare no-backend set, which is not a television package).CARGO_INCREMENTAL=0, as every one-shot gate. It builds in the checkout's owntarget/(or theCARGO_TARGET_DIRa lane exports, asmake lintdoes) rather than a tree of its own, and restores the cargo seed first likelint. Sharing is safe because cargo hashes a unit by package, target, kind, mode, features and profile: of the 181 units this check needs, 151 third-party units matchmake lint's exactly (a--unit-graphcomparison, nothing compiled) and are reused, while the workspace units differ in features (the application crate no longer forwardsdevtools,devtriggersandthreadcheck, so the layer crates getdefaultonly) and coexist beside lint's under their own hashes;cargo checkwrites no unhashed artifact that could collide. The backend features add no third-party feature of their own: they reach only workspace crates and activateplay-feed'sdolby_visionsubtree, which lint builds with the same features. The price is cargo's build-directory lock: amake check-nodefstarted while another cargo runs in the same tree waits for it. The recipe carries neitherHOST_ENVnorTELEMETRY_ENV: both change the third-party units it shares with lint. It never touches the release binaries (SIDE_EFFECT_FREE).- CI build health — four tools keep the build from growing unnoticed, and none of them is a
device gate.
- Timings artifact.
host-unit-defaultcompiles the test binary in its own step withcargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_shell_sdl -p plx_owp --no-run --timings, thenmake check-cargo-unit-defaultruns against what that built (--timingsis not part of cargo's fingerprint: checked 2026-10-02 by building with and without it and gettingFreshforplxnative-modulesboth ways, so the step moves the compile rather than adding one). Downloadcargo-timings-host-unit-defaultfrom the run page ("Artifacts", kept 14 days) and opencargo-timing.html: it names the crates on the critical path. Locally:cd rust-modules && cargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_shell_sdl -p plx_owp --no-run --timingswritestarget/cargo-timings/cargo-timing.html. - Trends.
tools/ci-durations.py [--runs 30] [--recent 5] [--json]reads the last 30 successfulmainruns of CI and Simulator CI throughgh apiand prints, per job, the median and p90 and the median of the newest 5 runs against the 25 before them, flagging a job GROWN when the recent median is more than 20% and more than 30 s higher, plus the slowest steps. Run it on demand (or from an agent) before and after a change to the build; it is not wired into CI, and its tests (tools/test_ci_durations.py, incheck-python) use canned API output. Runner time is noisy, so a flag is a reason to read the logs, not a verdict. A job renamed or split in the window (the host jobs were one job until the split) only has the runs since. - Budgets.
ci/build-budgets.jsonholds the deterministic ceilings andci/check-build-budgets.pyenforces them: the stripped ARMplxnativethatmake ipkstages (the cross-build job, dev flavour,releaseprofile: CI selects it by itself, a localmake ipkneedsARM_PROFILE=release), the number of third-party packages in the app crate's resolved graph forarmv7-unknown-linux-gnueabi(normal + build edges, dev-dependencies excluded; asked for both with default features and with the shipping set,make RELEASE=1's--no-default-featuresplus the playback backends, read from the Makefile and not restated: that is what ships), and the number of crate names present in two versions on the normal-edge graph (whatcargo tree -d --edges normalprints). The graph budgets run inhost-lintfromcargo tree, which compiles nothing and resolves features the way a build does:cargo metadataunifies them across dependency kinds, so it counted the layer crates'test-supportoptional dependencies (rcgen, rustls, ...) that only a[dev-dependencies]entry switches on. A fourth, the line count ofrust-modules/srcand every layer crate'ssrc, only warns. Each entry records the value it was set from, the date and its declared headroom. To raise a budget deliberately, edit the json in the same PR, updatemeasured/measured_on, and justify the growth in the PR body; the failing message says the same. Run it locally withpython3 ci/check-build-budgets.py --graph --src rust-modules/srcplus one--srcper layer crate, asci.ymlspells it (add--binary <path>to grade a stripped binary);ci/test_build_budgets.pycovers pass, fail, warn and the json schema. - Live chart. https://plxnative.com/ci/ (
site/ci/index.html, noindex, not linked from the landing page) is the working instrument for what a developer waits on: a "now" block (each metric's 7-day median, its change against the previous 7 days and 30 days ago: worse ones first, then the waits, the local loop and the longest jobs; a job under a minute, a part of a whole and a healthy no-op build are behind a disclosure), the slowest CI jobs and the slowest local steps right now (two lists: the benchmark runner is not comparable with CI), any regression of the last week with the commits in it, and the time series behind them. It reads three files from the orphanci-metricsbranch (raw.githubusercontent.com):ci-history.json(runs),build-history.json(the daily benchmark, written by the benchmark workflow) andci-summary.json(derived:tools/ci-summary.pycomputes the "now" rows with their order and selection, the two slowest lists and the regressions as pure functions, so a later alerting job can reuse them; per-class thresholds and the noise they were chosen from are in its docstring). Nothing names a job: every series is derived from the rows, so a job added or removed shows as a new or ended line and a missing job in one run is a gap, not a zero..github/workflows/ci-metrics.ymlrunstools/ci-history.pyandtools/ci-summary.pyafter every finished CI / Simulator CI / Nightly run that is a push tomainor a pull request (one short ubuntu job,concurrency-collapsed,actions: read+contents: write; it checks out only three tool files (the collector, the summary and the reader it imports) plusci/flaky.txt, and never runs pull-request code, so a fork's pull request is recorded too, withpr: null). Rows carryevent(absent = a push to main), the PR number,conclusion,attempt,wall(created to last update, for a re-run: what the developer waited) and the green jobs (failednames the others); the nightly is recorded for pull requests only; cancelled runs get no row and are counted per day incancelled. Per-run rows are kept 90 days, then folded into onedailyentry per workflow, event and day. The runs listing'sstatus=successfilter is stale, so the tool filtersconclusionandeventitself, and the listing can repeat or skip a run across pages, so an occasional gap is closed withgh workflow run ci-metrics.yml -f full=true(which also fills thecancelleddays an incremental pass leaves empty, backfills a branch that does not exist yet and finds old red runs).python3 tools/ci-history.py --in <ci-history.json> --dry-run [--full]prints how many rows a real run would add and writes nothing.tools/test_ci_history.pyandtools/test_ci_summary.py, incheck-python, use a fakeghand synthetic series. To look at local data files, servesite/with the files beside the page and open/ci/?data=ci-history.json(a same-origin relative path only). - Flaky tests. The page's "Flaky tests" section lists tests that gave one job of one run both a
pass and a fail (the same commit and build, in practice a re-run attempt). Both host unit jobs of
ci.ymlruntools/ci-test-results.pyover the log of theirmake check-cargo-unit-*(stable libtest has no JSON output, so it reads thetest <name> ... ok|FAILEDlines under eachRunning unittestsheader) and uploadtest-results-<job slug>-<run_attempt>(14 days). For every new or re-runcirun that failed or has attempt > 1, and whose head repository is this one (a fork's workflow file is its own, so its artifacts are never read),tools/ci-history.pydownloads those artifacts in memory and stores one event per flaky (job, test) underflakyinci-history.json(never the thousands of passes; 90-day retention, at most 100 events per run). Jobs are never compared with each other: the default-feature andhostsimjobs are different builds.tools/ci-summary.pyderivesflakyinci-summary.json: per (job, test) first and last seen, number of runs, status Active, Quarantined (listed inci/flaky.txt) or Fixed (no flake for 30 days), andnewfor a first flake within 24 hours.ci/flaky.txtis the quarantine list (test<TAB>reason, a# count:header, it only shrinks likeci/allow/layers.txt); it is read frommainby both writers of the summary and today only changes a test's status on the page: nothing skips a quarantined test and nothing blocks on a new flake. Not covered: the Python gates and the simulator jobs.
- Timings artifact.
make build-bench [ARGS='--runs 5 --json out.json']/make build-bench-quick— the repeatable local build benchmark (tools/build-bench.py), so a build-affecting change pastes a before/after table instead of an ad-hoc scratch-script number. It prints a Markdown table (median / min / max over--runs, default 3, the scenarios interleaved round by round) and, with--json, a machine-readable document (git sha,rustc -Vof the pinned toolchain, host, per-run load and swap). Rows: a no-op host test build (cargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_shell_sdl -p plx_owp --no-run; it reports from cargo's JSONfreshflag whether the app crate was rebuilt and flags a recompile as UNEXPECTED, theci/test_build_not_always_dirty.pyhazard); an edit-rebuild after appending a comment to a leaf file of each crate (plx_base'scbuf.rs,plx_machine'slandgate.rs,plx_os'sdevcaps.rs,plx_gfx'soverdraw.rs,plx_net'sstream_redirect.rs,plx_ui'sdwell.rs,plx_plex'sretry.rs,plx_telemetry'swindow.rs,plx_data'stape.rs,plx_session'sscripted.rs,plx_media'sunits.rs,plx_appkit'sskip_pill.rs,plx_screens'sclock_readout.rs, the application'scoldstart.rs) and to a hub (plx_ui'slib.rs), non-incremental (CARGO_INCREMENTAL=0, the defaulttarget) and incremental (CARGO_INCREMENTAL=1,target-fast; skipped with a note when that tree is absent unless--cold); the unit suite run on a warm tree, through the sametools/cargo-test-parallel.pywrapper the Makefile's recipes use (UNIT_RUNinprint-bench-config), with itstest result:counts; the ARM staticlib line after touchinglib.rs(in the profilemakeselects, sotvdevunlessARM_PROFILE=releaseis passed) plus the archive's size and sha256 (skipped with a note when no ARM archive exists in this checkout, and it never starts the FFmpeg build); and the sizes ofrust-modules/target*.build-bench-quickis no-op + leaf edit + sizes at one run;ARGS='--only noop,leaf --runs 5'selects any subset. The toolchain, target dirs, feature flags and RUSTFLAGS come frommake -s print-bench-configand the environment is the onemake test-fastgives cargo (includingHOST_THREADS's-Zthreads; the table's header line saysrustc front end: N threadsorserial, andmake build-bench HOST_THREADS=0is the serial baseline), so a bare invocation of the script (which warns) is not comparable to amakeone. It runs under the same machine-wide lock asmake check, EXCLUSIVELY (it waits for every running check, and no newmake checkstarts while it waits or runs, so its numbers never share the machine), refusesRELEASE=1, never touches the TV and never cleans a target dir. It editscbuf.rsandplx_ui'slib.rsonly while a row is being timed, refuses to start if either has uncommitted changes, restores the original bytes and mtime in afinallyand verifies withgit diff --quietat the end (exit 3 if not); a cargo failure stops the run, prints the table so far and exits 1. A first run in a fresh checkout includes an untimed warm-up build per tree. When to run it: every PR that touchesMakefile,Cargo.toml,Cargo.lock,build.rs,build_support/, a.cargo/config.toml,.github/workflows/, or the module layout (moving, splitting or merging files underrust-modules/src/) pastes the table frommake build-benchtaken on the base commit and on the change, on the same machine in the same sitting. Dependabot PRs are exempt (a bot cannot run it): the maintainer who merges a grouped bump measures first when it moves the toolchain or the compiled dependency set, and a bump of the Cargo dependencies also needsmake notices(THIRD-PARTY-NOTICES.md section 2.4 is generated fromCargo.lock;make checkfails until it is regenerated; on a Dependabot PR.github/workflows/dependabot-notices.ymldoes it and pushes the commit when only versions moved, and leaves the PR red naming the crate when the bump added one that needs a row or anot_shippedentry). A Dependabot bump of the pinned Rust toolchain (rust-modules/rust-toolchain.toml) goes the same way: the workflow installs the release with rust-src, runsci/gen-third-party-notices.py --derive-toolchainto rewrite the std snapshot inci/third-party-crates.json, regenerates the section and pushes both files (a crate newly in std's lock stays red for a licence decision); the maintainer still measuresmake build-benchbefore merging it. Reading noise: before every run the script samples the 1-minute load average (uptime) and swap (sysctl vm.swapusage) and printsWARNING: <scenario> run N: load X > <cores> coresorswap N% usedwhen load exceeds the core count or swap is over 90% full; this Mac is shared with other sessions and its swap is often full, so such numbers are noisy. A warning does not invalidate a before/after pair, but a delta inside the min-max spread is not a result; rerun with a higher--runswhen the box is quiet. Load sampled after the first round includes the benchmark's own previous build, so a load warning from round 2 on is a hint, not a verdict.ci/test_build_bench.py(a fake cargo, a scratch repository) pins the table and JSON shape, the restore-on-failure and dirty-target refusal, the skips, and that the mirrored cargo subcommand skeletons still equal the Makefile's recipes.- The daily build-time series (
.github/workflows/build-bench.yml,tools/build-history.py). Every day at 04:17 UTC, and ongh workflow run build-bench.yml(a same-day run replaces that day's record;-f only=noop,leafnarrows it), GitHub-hosted macOS runners build main's tip and time, with this benchmark, on three runners side by side: thebaseleg (a no-op host build and the edit-rebuild ofplx_baseandplx_ui), thetopleg (the edit-rebuild ofplx_screensand the app crate, and the unit suite), each the median of 3 runs with min and max, and thegatejob,make checkonce with its cargo and python branches (the opt-in scenario:make build-bench ARGS='--only check --runs 1'times it locally; it runscheck-unlocked, because the benchmark already holds the check lock). The legs exist because one runner took 29 of its 35 minutes on the first run: 11 of them were untimed rebuilds that followed every edit row, since putting the edited file back with the time of the put-back made cargo (which judges a path package by mtime) see it as changed. The benchmark now restores the file's original mtime, so only the first build of a run is an untimed warm-up. One record per day is appended tobuild-history.jsonon theci-metricsbranch (the same branch asci-history.json, pushed with a retry becauseci-metrics.ymlwrites it too) and summarised intoci-summary.jsonbeside it; the page at plxnative.com/ci/ reads those files. The numbers are for the trend of one runner type (3 vCPUs of a shared Apple M1 virtual machine; the record names it and the page prints that next to the charts), not the absolute time on a dev Mac. Failures are loud and cost only their own rows. A build that failed, or a leg that left no document, records nothing. A redmake checkmakes thegatejob, and so the run, red (nocontinue-on-error; the failing steps' own output is in the job log), and a red unit suite makes its leg red, but the record still files the day's other rows and listscheckortestsinfailedwith a one-linefailure_notesreason, which the page prints ("make check failed on the runner on "). Noise is a property of a row, judged bytools/build-history.pyfrom the row's own runs:spread= (max - min) / median,noisywhen it is above 0.5 and the runs differ by at least 2 s (provisional: the first record's rows spread 26% to 57% because each row's first round ran 40-55% slower than the other two; a one-run row has no spread). The load and swap warnings are kept as the raw countwarningsand decide nothing, because a 3-core runner running a parallel build always exceeds its core count. The rule is applied again to every stored row on each write, so retuning the constants retunes the history.ci/test_build_history.pypins the record, the rule and the merge,ci/test_build_bench.pythe restore and the failure reports, andci/test_ci_workflows.pythe workflow's triggers (no pull-request trigger), guards, permissions, legs and timeouts. - How the site demo video updates itself (
.github/workflows/site-video.yml, the last job ofrelease.yml,site_video.py'srelease-ref/needs-render/adopt). The film refreshes AFTER A STABLE RELEASE and after nothing else:release.yml's final job (site-video,continue-on-error,actions: writeas its only write scope) dispatchessite-video.ymlON THE NEW TAG (gh workflow run site-video.yml --ref vX.Y.Z) once the release is published (aworkflow_dispatchis the one event aGITHUB_TOKENmay start a run with). There is no schedule and no pull-request or push trigger; a release candidate, a nightly, a branch or a commit are refused byrelease-ref(tests/test_site_video.py,ReleaseRefGuard, holds the repository's real tags), and a maintenance-line patch (not on main) is skipped by the hook and refused by the workflow. The workflow renders its own checkout and no input names a ref: a run on a tag has caches of its own (a cache is restorable only by runs of the ref that wrote it and the branches below it, never by main), so the cache steps that restore into the tree being rendered cannot poison anything main runs (CodeQL reads a checkout of a ref an input names, followed by cache steps, as "cache poisoning via execution of untrusted code"). Five jobs (stills, the film's sibling, is the next bullet).decide(contents: read) readsgithub.ref: a tag must be a stablevX.Y.Zwhose commit is an ancestor of main for the run to publish,refs/heads/main(a maintainer's manual dispatch) may publish, and a branch renders as a dry run only (a tag that is not a stablevX.Y.Zon main failsdecideat once, before any rendering, unless-f publish=falsemakes it a dry run too); it then asksneeds-render: if the git trees of everything that can change a pixel (TREE_PATHS) equal thetree_hash.combinedrecorded in the committedsite/media/feel.manifest.jsonAND the stills' inputs equal their own committed manifest, the run ends GREEN without rendering.render(contents: read) renders the checkout and applies every gate below; any failure leaves the site as it was and the run red.publish(contents: write, the only write token in the workflow) checks outmain(a literalref: main; a dry run checks out the dispatched ref instead and keeps no credential), downloads the artifact (data) and runs MAIN's tool, never the rendered ref's code:site_video.py adopt <artifact dir> --write --derive --expect-rev <sha>. It verifies the artifact (linux-ci, sha256s, gates passed, clean tree, and that it was rendered from that commit's inputs), and when the six media files differ from main's it copies them with the manifest, regenerates the feel glows and the credits page, REWRITES thecodecs=strings ofsite/index.htmlfrom the new files' ownavcC/av1Cboxes (a re-encode that moves a profile or level must not leave the page declaring the old one, whichCommittedSiteMediawould catch on main), checks that only the film's and the stills' files changed, and commits as github-actions[bot] (Site: demo video re-rendered for vX.Y.Z, ordemo video and stills/stillsfor what changed,main@<sha>for a manual dispatch; the body carries the gates' summary and the run URL), rebasing onto the tip of main and retrying the push (never forcing). A film byte-identical to the committed one commits nothing and writes nothing, the manifest included, so the manifest keeps naming the tree the film was last rendered for (the next release with changed inputs renders again; a release rarely comes twice a week).pagesDISPATCHESpages.ymlon main (gh workflow run pages.yml --ref main): a push withGITHUB_TOKENdoes not start it, and thegithub-pagesenvironment admits deployments from themainbranch only, so a run on a tag cannot call it; the deploy is its own run ("Deploy landing page"), where a failed deploy shows. It never blocks a release: it is a separate run, dispatched after the release exists; if it fails the release stays, the site keeps what it had (a failedrenderkeeps the old film; a failedstillswith a greenrenderlands the film and keeps the old stills), and the red "Site video" run is the notice. Taste is not gated: the gates prove the film is deterministic and well encoded, not that it is good, so look at the site after a release. Operate it: re-run for a taggh workflow run site-video.yml --ref vX.Y.Z; render anyway (and publish)gh workflow run site-video.yml --ref main -f force=true; a dry run (everything but the push and the deploy, printing thegit diff --statit would commit)-f publish=false, which is how a change to the workflow is proved from its branch (--ref my-branch; a branch never publishes whateverpublishsays); a bad film isgit revert <the bot's commit>(it takes the stills with it) and a push to main (the push triggerspages.yml). Turn it off by deleting thesite-videojob at the end ofrelease.yml. A render costs about 55 runner minutes (measured on run 37805253785). - How the site's stills update themselves (
site-video.yml'sstillsjob,tools/site_stills.py,tests/test_site_stills.py; the same run, workflow and bot commit as the film above, not a second workflow). Every still a SIMULATOR makes, found by reading the generating tools (site_stills.py fileslists them:tests/screenshots/scenes.json's outputs with theirCREDITS.md, then the WebP and phone copies ofrender-site-variants.pyand the glows ofrender-site-glows.py), refreshes after a stable release when the git objects of their inputs (TREE_PATHS, recorded astree_hash.combinedinsite/media/stills.manifest.json) moved, or onforce; an app whose inputs did not move renders nothing and commits no stills, whatever the renderer's noise.decideasksneeds-render;stills(contents: read, its own checkout, the pinnedubuntu-24.04, Xvfb, llvmpipe, the host FFmpeg built withHOST=1 ci/build-ffmpeg.shand copied intopkg/AFTERmake screenshots-sim(on a fresh checkout the Makefile'sRUST_CFGstamp deletespkg/lib*-plx.so.*while parsing, and without themff.rsfinds no FFmpeg and every stream ends at once: the player scenes' "EOS pushed at true EOF"), the BtbN ffmpeg fromsite_video.py ffmpeg-fetchfirst on PATH as the ONE encoder,CHROME_ARGS=--no-sandboxfor the runner's Chrome that composes the link card) renders every scene withtools/screenshots.py --check-determinism --retry-unstable --report: each scene is captured TWICE and the second must agree with the first within the scene's noise bound; the first is adopted. The bound is "stable", not "byte-identical": llvmpipe's blur and glass passes round differently from run to run (a handful of scenes differ on a few to a few hundred pixels, by one level), so demanding identical bytes fails nearly every run. The bound is the scene manifest'smax_delta(default 1,site-up-next2, each with itstolerance_reason) on the raw PNG captures, where one level of rounding is one level (a JPEG spreads it over a block, up to 6 levels). Measured on the runner (4 full renders, 16 scenes, and 28 isolated pairs ofsite-tiles): every pair within 1 level on 0 to 498 pixels, except that in two of the four full renders ONE 3x scene (site-tiles, thensite-glass) had a capture that settled 2 to 4 s late and differed by 13 levels on 364 thousand of its 18.7 million pixels (a stalled runner, caught mid-fade). So a pair that disagrees takes a THIRD capture and the first capture another agrees with is adopted (stable_capture); three that never agree in any pair fail the job. A missing poster, a card that popped late or a different row is tens of levels off in every capture that has it (tests/test_site_stills.pyproves the bound on synthetic captures). A failedstillsjob names the scene and its files, leaves the run red, does not block the film'spublish(a failed film blocks everything), and the committed stills stand; re-run it.publishruns main'ssite_stills.py adopt DIR --write --expect-rev(refuses a non-linux-ciplatform, a set that is not exactlyoutput_files(), a wrong sha256, a missing or over-bound verdict for any scene (the bound re-read from main'sscenes.json), other inputs), checks the path allow-list, and makes ONE commit with the film. Identical output commits nothing, the manifest included. Every simulator scene is automated, the two player scenes included.docs/screenshots/navblur-transition.jpgis a photograph of the panel and is regenerated by nobody.MANUAL_SCENESstays as the place to put a scene the runner cannot make, with its reason. Operate as the film:gh workflow run site-video.yml --ref my-branch -f publish=false -f force=trueis the dry run. - The site demo video's render (
.github/workflows/site-video.yml,render;contents: read, one artifact kept 30 days). It is the CANONICAL render:ubuntu-24.04(pinned, never-latest), the same libass caches and./.github/actions/apt-installaction assimulators.yml's Linux job, with that job's SDL/GL/Xvfb package list plusmesa-utils(glxinfo, which the manifest reads) and, in a second step, the aptffmpegandpython3-pilthat derive the demo art. It renders under Xvfb 1920x1080 on Mesa llvmpipe (LIBGL_ALWAYS_SOFTWARE=1,GALLIUM_DRIVER=llvmpipe,LP_NATIVE_VECTOR_WIDTH=256,LC_ALL=C,TZ=UTC). It buildsmake site-video-sim, fetches and derives the demo library (tools/demo_library.py fetch+derive, the sources cached on the hash ofassets.json,deriverun cold every time;fetchbacks off on a wikimedia 429), fetches the pinned tool ffmpeg, runssite_video.py render --storyboard(the film below) TWICE in separate processes, fails unless the twoframes.tsvagree in columns 1-4 AND the two masters decode to the same frames (aframemd5list; container byte equality is reported beside it), runssite_video.py hold-gate --storyboard(the film with and without seeded extra held repeats, two more renders, their masters deleted at once), rescans for the sentinel, thenencode,contact-sheet,gatesandmanifest. The manifest'senvironmentrecords the runner image version, OS, CPU model, Mesa and LLVM versions (glxinfo -B), the packages behind them and the variables above, because the video is defined as what this pinned stack renders; a new image is a new fingerprint, not a failure.adopttakes the artifact (a zip, or the directorydownload-artifactunpacked;--derivealso regenerates the feel glows and the credits page). It reads no private file and holds no secret beyond the run'sGITHUB_TOKEN. - What the site demo video films, and how to make it. One command, after
make site-video-simandpython3 tools/demo_library.py fetch derive:python3 tools/site_video.py render --out DIR --storyboard, thenencode,gates(see the workflow above for the full sequence). A macOS render is a preview; only the Linux workflow's artifact is adoptable. The film istests/video/feel.json: positions and durations, never titles (the demo catalog's order,tests/demo_library/catalog.json, decides what is under each position). The demo mock's rows carry theImage[]a modern PMS sends (CatalogLibrary._image_list: a stampedclearLogoonly where the catalog has a logo, an episode's or a season's naming its show's). A row with no list reads as an older server's and gets the legacy/clearLogolookup, a 404 for eachlogo_none_approvedtitle (Metropolis, in the Continue Watching deck), and the frame dump ends the run on a failed art request. It is the Home hero held under a second,rightto the hero's Info button,rightagain (the carousel turns forward to the second page),leftto Continue andleftagain (back to the first page),downonto the Continue Watching row,righttwice to its third card andokfor that title's Detail (the shelf'sokopens details, the default Continue Watching setting; nothing plays),downto its Cast & Crew row (a portrait for each of the seven performers, from the catalog'speople: an openly licensed photograph of the actor or a frame of the film,tools/demo_library.py, "People"), four moredowns through the rest of the page (the title's collection, its linked heading a stop of its own, then More Like This) to the About section at its foot, with nookanywhere on the page (each one there opens another page or a reader),back(the shelf, that card focused; Detail'sbackleaves the page from wherever it is scrolled),upupto the Home pill (Up lands on the page's own pill; the profile chip is oneleftaway, off this route) andrighton to the Movies tab,okfor the Movies library. The film's Movies leg predates the Library redesign: the page is now one header row over the full poster grid, with no shelves and no All heading, so the recorded presses through shelves to Type and Filter chips no longer match it andfeel.jsonneeds a re-walk (header row, thendowninto the grid and a few moves inside its columns, then back to the top) before the film is re-rendered (the Library'sbacktakes one region a press, grid top, header, tab bar, then Home, so the leg's singlebackreturns Home only from the bar); the page is left that way, thendownonto Continue, about 30 s. Abackpressed lower on the Movies page jumps it to its top first; that jump is NOT filmed, because its first Linux render wrote different frames under the hold-injection gate (104 of 1734, from the press to the end of the return Home), so it is a motion the dump cannot yet vouch for. Keys of one gesture share a beat and are pressed 230 to 380 ms apart, faster than the springs settle: only a beat's END is held to rest. The Movies page is walked with arrows only (nook, so a miscounted press cannot open anything there) and never reaches the grid's sixth column, whoserightis the letter rail. The beat rests were set from the settle times measured on the previous film's frames (a hero page turn about 1.15 s, a page scroll about 1.1 s, a card move about 0.7 s, a page push about 0.9 s) plus a quarter second; the grid's and the Detail's scrolls are new and unmeasured until their first render. The last frame equals the first to within 1/255 per channel (storyboard.loopinrender.jsonandfeel.manifest.jsoncounts the pixels that differ). Every hero page it shows passesdemo_library.py hero-reportand is notnot_in_video, and the title whose Detail it opens is not one whose hero page it shows. NOT filmed: anything opened from Detail, any popover or modal, any title flaggednot_in_videoopened (gateschecks the mock's request log, and that no stream, transcode, timeline, scrobble or play-queue request was made), and the hold-hint capsule: the film is shot with the hint taught. The capsule is a one-time teaching overlay (it stands after 1.5 s of rest on a card, once per install across every card screen, Home included, and once more on the Detail season pill after a shorter rest). A hidden hint also appears after 200 ms of anokhold, with a fill in its cap; a short click leaves it hidden. A film has no viewer to teach, sorender --storyboardwrites theplxnative-hintofftrigger (HINT_OFFinsite_video.py; the app reads it once at boot, indevtriggersbuilds only, and callshold_hint::teach_all_for_dev, which marks the hint learned and both of its showings spent for the run) andrender.jsonrecordshold_hint: suppressed. The hint's own timing is unchanged, and no card rest in the film is capped by it.upfrom the hero lands on the Home pill, oneleftshort of the profile chip, so the film as walked no longer passes the chip; the launcher still runs, before the film boots, a prep boot of the simulator with theplxnative-logintrigger: the app's own QR sign-in completes against the mock (served withauthorize_after=2) and stores a "Demo" account, which is what the chip reads when focus passes it (never "Sign in"), should a beat pressleftthere. Gates specific to the film:storyboard/rest(every beat's last 12 frames differ from the first of them by at most 3/255 in every channel, or by more in at most 0.01 % of the pixels; the spring tails),storyboard/opened,storyboard/no-playback,storyboard/loop(read fromend.match_first_frameinfeel.json: the last frame differs from the first by at most 1/255 in every channel;storyboard.loopin the manifest records the count) andhero-pool(fail closed: every hero page the film SHOWED, read from the app's event log (home: hero page slot N rk=R, one line per page turn, plus the pinned page), is in the hero-report pass set and notnot_in_video;render.jsonrecords them underhero_pool). The size gate compares each file with the committed one (1.25x); a render whosestoryboard_sha256differs from the committed manifest's is another film, so its four videos are held to thesize_new_film_bytesceilings instead, once, and the ratio governs again after that film is committed. The H.264 encodes pin the last frame's QP with a one-frame x264 zone (zones=LAST,LAST,q=H264_LAST_FRAME_QP): mbtree gives the never-referenced last frame a coarse QP andseam/*compares it with the heavily referenced first frame (0.9947 against the 0.995 floor on the 29 s film; forcing an IDR there measured worse, 0.9903). A page push or pop dips through about three flat frames of the backdrop between the outgoing fade and the incoming one: that is the app's own page transition, not a hold. The AV1 encodes use CRF 22 with a keyframe every 8 s (AV1_CODEC; the 720p one every 12 s,AV1_720_GOP, to stay under the 1.25x size limit). They were re-tuned for HEADROOM after the first Linux render read min VMAF 79.69 against the 80.0 floor on the 1080p one (macOS 80.10, at CRF 28 / 2 s; the 720p one, at CRF 25 / 4 s, read SSIM min 0.9709 against 0.97): the macOS preview then read VMAF min 84.5 and 85.3, SSIM min 0.9796 and 0.9746; the committed Linux film's own numbers are thevmaf/*andssim/*gates insite/media/feel.manifest.json. The floors did not move; a lower CRF is paid for by the longer GOP, never by a looser gate. The H.264 encodes declare the lowest level their picture needs (H264_LEVELS: 720p60 High@3.2 with 5 refs, 1080p60 High@4.2 with 4), because x264's veryslow preset uses 16 reference frames and left to itself writes High@5.0 / High@5.1, which several phone decoders refuse and which is the fallback path where AV1 is missing. Measured on the macOS master: the capped files are 1.2 % and 0.8 % larger and read the same quality (VMAF mean 97.10 / 97.10, min 89.34 / 89.96 against the floors 93 / 80; SSIM min 0.9857 / 0.9853 against 0.97).adopt --writerewrites thecodecs=strings ofsite/index.htmlfrom the adopted files' boxes, so the page follows the files. The SSIM and VMAF gates pair frames by index in ONE time base (BY_INDEX,settb=1/60,setpts=N): pairing in each file's own time base rounded two frames of this film onto their neighbours and read them as SSIM 0.66 and VMAF 0. A page pushed in a dump is never a held image: the dip re-captures it every frame and it is live the frame the dip ends (PageImage::step_filmed), so the Library's cards pop and its focused caption fade in under the dip, with no cut at the end of it. make test—deploythenrun(the normal iteration command).make kill— close the app on the TV.make SYMBOLS=1 symbols— build with DWARF and split it intopkg/plxnative.debug, the file that turns an address in a stranger's crash report into a source line. The binary users get is stripped, so the only thing that can pair the two is the GNU build id — an allocated note that-Wl,--build-id=sha1puts on every link (unconditionally; it costs 20 bytes andstrippreserves it). Verified end to end 2026-08-29: the full binary, the.debugand the stripped one all carry the same id, andaddr2line -e pkg/plxnative.debugresolves an address the stripped binary answers?? ??:0for. It is opt-in for one reason and it is not build time — a debuginfo cross build is 30 s cold and the artifact that SHIPS is unchanged (6.93 MB stripped when measured 2026-08-29, a hair smaller than without; the absolute has since grown — a RELEASE=1 stripped binary was 10.11 MB on 2026-10-01 with--gc-sections) — but its target dir is 356 MB, and this repo already keys a separaterust-modules/target*per configuration and multiplies that again per worktree. (make diskis how you see what that has come to, across every checkout at once, andtools/build-gc.sh --incremental|--lanes|--stale|--worktrees|--all(or a planner-chosen--evict PLAN, below) is how you get it back — every mode there except--worktreesdeletes only rebuildable output;--worktreesremoves finished lane checkouts, and with them their ignored files (-nlists the ones that are not build output;--autokeeps a lane that holds any). The MAIN checkout is reached only narrowly:--stalesweeps the superseded hashes in itsdeps/(age-gated only there, never the newest hash per crate),--incrementaland--allclear its incremental dirs,--evicttakes those only as rung 6 (the planner's last), and none of them removes itstargetdir itself. The--stalereach exists because cargo keeps every superseded metadata-hash's binary and*.rcgu.oobjects forever — 6416plxnative_modules-*files across 6 dead hashes, 5.5 GB, all last written 2026-09-17. Measured 2026-09-03, twelve lanes in: 45 GB across the family with 3.2 GiB free on the volume — of which the cargo incremental cache alone was 24 GB and FFmpeg, the usual suspect, was 2.6 GB. A linked worktree is not supposed to write an incremental cache at all (the sanctioned exceptions are the opt-inmake test-fastandmake test-hostsim) — the Makefile says so besideRUST_FEATFLAGS, but it can only say it to the cargo runsmakelaunches, and a directcargo test/cargo checkin a lane wrote one anyway: 12.9 GB of them, measured 2026-09-17.tools/build-gc.shnow installs.claude/worktrees/.cargo/config.tomlwithincremental = false, which every cargo reads and which stops above the main checkout. Since 2026-09-18 the same file also sets[profile.dev] debug = "line-tables-only"anddebug = falsefor third-party packages in lanes (main keeps full DWARF fordev: the simulator, clippy andcargo check). A hostcargo testbuild is thetestprofile, whose line tablesrust-modules/Cargo.tomlsets for every checkout, main included; a debugger on a host test needsCARGO_PROFILE_TEST_DEBUG=2. A lane's target dirs are also no longer all built from scratch: in a linked worktree the Makefile seeds an ABSENT target dir with an APFS clone of the third-party output (registry crates, once also the build-std sysroot, about 40% of a lane's target bytes then) from~/.cache/plxnative/cargo-seed/, viatools/cargo-seed.py; the app crate is stripped from the seed, builds stay per-checkout, andPLX_CARGO_SEED=offdisables it. Because a clone shares blocks,du(and somake disk's per-checkout numbers) counts them in full:dfis what is really free. None of this reclaim has to be run by hand anymore:tools/build-gc.sh --autoreclaims on its own, gated by free-space pressure, from aSessionEndhook and the per-user launchd agentmake disk-watchinstalls —--orphans, then--worktreesfor lanes idle pastPLX_GC_IDLE_MINand holding no non-build ignored file, then the planner's order — andmake diskremains the report to read before deciding whether to intervene yourself. Its last section is the disk budget (tools/disk-budget.py report,docs/disk-budget.md): each tree's PRIVATE bytes, which is what deleting it really frees and not whatdusays, the PlxNative cargo trees under/tmpthat nothing above can see, and the order a reclaim would take them in. The report is read-only.tools/disk-budget.py reclaim --to GIB --emitwrites that order as a plan file andtools/build-gc.sh --evict PLANdeletes what it names — and only that: every path is re-derived from the machine (a derived PlxNative build tree, a rung the ladder makes from that kind of tree) and re-probed for liveness (builder in the checkout, cargo ormake checklock, open files, the idle window, a/tmptree's ctime) immediately before it is renamed away. It does not stop for a held FFmpeg cache lock the way the other modes do, it never evicts the cargo seed, and-npreviews it. Tests may run it only against fixtures. Every build entry runs the same planner first:make disk-preflight(python3 tools/disk-budget.py preflight --tree <the tree this target builds into>) is an order-only prerequisite of each cargo-running target in the Makefile'sDISK_ENTRIES(make -s print-disk-entries). At or abovePLX_GC_MIN_FREE_GIB(20) it is onestatvfs(a median 21 ms with the interpreter start, measured 2026-10-19); below it, it plans a reclaim to that line, sparing the tree it is building and every live tree (the current checkout's incremental dirs in its other trees are rung 6, taken only when rungs 0-5 cannot cover the build), hands the plan to--evict, and re-measures; it refuses (exit 1, naming what it kept and why) only when rungs 0-6 cannot cover the target's estimated need plus thePLX_MIN_FREE_MBreserve (3072;0turns the preflight off). Its wait on a lock is bounded: a heldbuild-gcauto lock is waited on for up to--wait-secs(60) and the wait ends the moment the build fits; the eviction itself is not short (a few multi-GiB deletions,build-gc.sh --evictcapped at 900 s), so a target below the comfort line can spend real time in the preflight before cargo starts. A recursive$(MAKE)inside an entry passesPLX_DISK_BUDGET_DONE=1, which every nested preflight honours. The inventory is cached for 10 minutes under$PLX_BUILD_CACHE/disk-budget/and dropped after an eviction.)SYMBOLSis in theRUST_CFGstamp besideRELEASE, and it has to be: a debuginfo build and a plain one produce different build ids from identical sources, so without the stampmake RELEASE=1 ipkfollowed bymake RELEASE=1 SYMBOLS=1 symbolswould hand you a.debugmatching nothing that was ever shipped. Cut both in one invocation:make RELEASE=1 SYMBOLS=1 ipk symbols.make symbolswithout the flag REFUSES rather than writing the empty shellobjcopy --only-keep-debugproduces from a binary with no DWARF.SYMBOLS=1is sticky the wayRELEASE=1is: pass it to EVERY invocation in the session. It is in the stamp, so a baremake deployaftermake SYMBOLS=1 deploydeletespkg/plxnativeat parse time and leaves you unable to symbolize the crash you just captured — the stamp working as designed, but it costs a rebuild to notice. (Goals that build, read and ship none of the stamp's artifacts are inSIDE_EFFECT_FREEand leave the stamp and the binary alone whatever the last build was: the goals that only drive the TV —kill,run,run-stream,verify-deploy,uninstall,fetch-profile,softfloat-probe, sotv-session.shandtests/run.pycan run them — and the host-only ones —test-fast,test-crate,test-hostsim,lint,check-nodef, the print queries and the set-up and fixture tooling, so a unit-test loop after amake ARM_PROFILE=releasebuild does not cost the binary.make checkis NOT among them: its own steps dry-run the ARM goals. The Makefile comment aboveSIDE_EFFECT_FREEhas the rule and the goals deliberately left out, andci/test_arm_profile.pypins both.) Device-verified end to end 2026-08-29: a deliberate SIGSEGV on the set resolved throughpkg/plxnative.debugtodev::crash_on_purpose at rust-modules/src/dev.rs:218— file and line, from a binary the television runs, matched by build id alone.make SYMBOLS=1 sentry-symbolsadditionally runs Sentry CLI's local DIF check and uploads that exact binary/debug pair with source context; it requiresSENTRY_AUTH_TOKEN. The release workflow treats a missing token, unusable DIF or failed upload as a release failure, because an accepted native event with no matching DIF is not a working crash report.make symbols-libsdoes the same for the bundled shared objects (the FFmpeg libraries and libass, which ship stripped):pkg/symbols/<soname>.debug, extracted from the unstripped link output (vendor/ffmpeg-prefix/lib/unstripped/,vendor/libass-prefix/lib/). Their links carry-Wl,--build-id=sha1too, andci/extract-so-symbols.shrefuses a library without one, a.debugwhose id differs, or one with no.symtabfunction symbols;ci/check-debug-files.py(used bysentry-symbolsand the release workflow) then requiressentry-cli debug-files checkto reportdebugorsymtabfeatures on each file, because that command exits 0 for a symbol-less object.sentry-crashis not uploaded: it never sends a report, so no event frame lands in it. Independent ofSYMBOLS=1.make ipk— repackage the installablepkg/<app id>_<version>_arm.ipk. The version comes frompkg/appinfo.json(the single source;ci/check-package.pyasserts the control file agrees), and the archive is reproducible —ci/mkipk.pynormalises tar identity and the gzip header and writes thearcontainer itself. Two builds of one commit produce the same sha256, which is what makes the manifest hash the TV verifies at install meaningful. Two things here are counter-intuitive and were both shipping broken until 2026-08-02 (found the first time anyone actually installed an ipk — the dev loop ismake deploy, which scp's into an already-registered app dir and so never exercises the package). (1) webOS needs two descriptors:usr/palm/applications/<id>/appinfo.jsonANDusr/palm/packages/<id>/packageinfo.json. Without the second,appinstalldregisters nothing. (2) GNUarproduces an ipk the TV rejects — it suffixes short member names with/, andappinstalldlooks them up verbatim, failing the whole package witherror_code -5, "Failed to extract package". Somkipk.pywrites baredebian-binary/control.tar.gz/data.tar.gzheaders by hand. Neither bug is visible from the other's side:webosbrew-ipk-verifyreads a GNU-named archive fine, and the TV never gets far enough to miss a descriptor.check-package.pynow asserts both. Full account:docs/distribution.md§9.make macapp/make macapp-zip—pkg/PlxNative.app: the app as a self-contained macOS application, for sending to somebody who has none of this installed. Samehostsimcore the simulator runs, built--release --no-default-features(so no dev counter, no/tmptrigger surface, no FIFO, no capture listener), with every non-system dylib copied in and rewritten to@rpath, ad-hoc codesigned. It signs in with the real QR flow and browses a real server; it cannot play video — the Starfish/ACB seam does not exist off-device, so Play lands on the app's failure read-out, exactly as in the simulator. Apple Silicon only, LAN only.ci/mkmacapp.pyis the recipe (its module doc names the three ways a Mac bundle silently ships broken);docs/macos-app.mdis the design note, anddocs/macos-app-readme.mdis what ships beside the zip for the recipient.FLAVORselects WHICH INSTALL every TV-facing target talks to. Three builds live on one television:stable(com.beb.plxnative— the app users install, the id in every release, manifest and channel listing),debug(com.beb.plxnative.debug— the day-to-day developer build beside it, with its own launcher tile, its own sign-in and its own runtime root), andnightly(com.beb.plxnative.nightly— a third install beside both, tile "PlxNative Nightly", own sign-in, own runtime root, but ALWAYS aRELEASE=1build —release-guardrefuses one without it, with noALLOW_DEV_ON_STABLE-shaped hatch, because nightly ships no dev-trigger surface ever).FLAVOR ?= debugin the tracked Makefile, andstable/nightlyhave to be TYPED. That asymmetry is the safety argument, not a preference: every command in this repo's muscle memory is spelledmake deploy/make run/./tests/run.pywith no flavour, and each one used to overwrite the only install there was — retyping one command is not comparable to destroying the install the household watches with, possibly mid-film, with no undo. Tracked rather than a gitignored dotfile because a fresh clone or worktree has none, so the dangerous default would be inherited invisibly by exactly the checkouts nobody is watching. An unknown value is a parse-time$(error)rather than a fourth registered app on the television. A flavour must be installed ONCE beforedeploycan reach it —make FLAVOR=debug installbuilds its .ipk,dev/installs it and then deploys into it (appinstalld replacesapplications/<id>/WHOLESALE, so stopping at the install leaves the packaged binary behind);make FLAVOR=debug uninstallremoves one and refuses the stable id.deploy/ipkon the stable id refuse a dev build unlessALLOW_DEV_ON_STABLE=1;deploy/ipkon the nightly id refuse a dev build outright, with no override. FLAVOR is NOT a codegen input for stable/debug, which is what makes flipping between them cheap: the app reads its id from the INSTALL DIRECTORY at runtime (paths::app_id, via/proc/self/exe), so no rebuild, no second--target-dir, no FFmpeg rebuild, onepkg/plxnative. Nightly is the one exception: the Makefile derivesPLX_CHANNEL=nightlyfromFLAVOR=nightlyand exports it (UNSET for the other two: cargo fingerprints blank differently from unset, so a blank export would make every barecargorecompile the crate after amake), andrust-modules/build.rsreads it to decide whatPLX_VERSIONthe binary reports — a REAL codegen input, so switching to or fromFLAVOR=nightlydoes trigger cargo'srerun-if-env-changedand relinks.PLX_NIGHTLY_DATE(YYYYMMDD, defaulted to today's UTC date by the Makefile) rides the same mechanism and is what turns the reported version intoX.Y.Z-nightly-YYYYMMDDrather than plainX.Y.Z-dev; a nightly package's OWNappinfo.json/controlversionalso moves ahead — to the same nextX.Ywith the cut date as its patch,X.Y.YYYYMMDD(seeci/flavor.py::appinfo_for's nightly arm andci/version_rule.py::nightly_package_triplet; the Makefile handsPLX_NIGHTLY_DATEto theIPK_VERSIONshell call explicitly and keys the generated descriptor on a per-date stamp). The date patch is what makes Homebrew Channel, which offers an update only when the version STRING differs, offer one nightly after another; it is why nightly is the one flavourci/flavor.py --selftestallows to moveversionat all. Ask the seven query targets for any of it (they compose — several goals on one command line print several lines):make -s print-flavor print-appid print-appdir print-rundir print-eventlog print-appport print-tv FLAVOR=<f>.print-appportis the newest and the least obvious: the capture listener's TCP port MOVES with the flavour (8910 stable, 8911 debug, 8912 nightly), because two installs cannot both bind one and both halves of that failure are silent — see the capture trigger below. Nevermake -p/make -pn, which prints a recursive variable's UNEXPANDED definition, soTVcomes back as the literal$(strip $(shell tools/tv-config.sh host …))and every ssh built from it fails against a live television. Full account (predates nightly):docs/two-installs.md.RELEASE=1drops all three default cargo features:devtools(the on-screen counter — the last completedfps=present window, held until an ordinary present repaints it; the feature is contracted to be draw-only and never wakes an idle screen) anddevtriggers(the whole/tmpsurface, the remote FIFO and the capture listener — seerust-modules/src/dev.rs), plusthreadcheck(the main-thread violation checker). It also decides WHICH VERSION THE BINARY SAYS IT IS: the Makefile exportsPLX_RELEASE, andrust-modules/build.rspublishesPLX_VERSIONas theCargo.tomlversion exactly for a release build and as the next MINOR plus-devfor every other one —0.6.0published,0.7.0-devin the tree. The minor rather than the patch because development is TRUNK-BASED here: features land on main, so the next release cut from it is a minor (or a major, which no build script can predict); a patch is cut from an existing minor's own line, where trunk's number is not the question — this remains exactly true for a checkout ofmainitself, with no marker file. A checkout of a maintenance line has that input now, andbuild.rsnames the next PATCH there instead: a trackedRELEASE_LINEmarker at the repo root (X.Y, e.g.0.6) says "this checkout IS that line, not trunk", so0.6.0inCargo.tomlplus a presentRELEASE_LINEreports0.6.1-devrather than0.7.0-dev. The file's absence is unconditionally the trunk behaviour above — nothing about amaincheckout changes. It also makes the semver ordering mean something —0.7.0-devprecedes0.7.0. That is the string every surface reports (X-Plex-Version, the Sentry release, PostHog'sapp_version, the lab snapshot, the photographed diagnostics panel); before it, a release commit left the whole tree claiming to BE the release it had just cut, and nothing downstream could separate a working tree from the shipped artifact. The suffix never reachespkg/appinfo.jsonor the control file —ares-packageaccepts three integers and nothing else, andci/check-package.pyholds every package to that (whether the television's own installer is stricter is not proven) — so a developer flavour's package is labelled0.6.0while its binary says0.7.0-dev, deliberately;ci/check-package.pygrades both directions on the packaged bytes. It must be on EVERY invocation that produces or ships the binary (make RELEASE=1 deploy, notmake RELEASE=1 && make deploy, which rebuilds as dev and ships that).deploy/ipkecho which configuration they shipped. Switching configuration DELETESpkg/plxnativeat Makefile parse time — deliberately: make 3.81 on macOS compares mtimes at one-second granularity and decides staleness from a stat taken before prerequisites run, so no stamp-mtime scheme works. Each feature set also gets its own--target-dir, because cargo does not hash its output and would otherwise report the dev build fresh while the release.asat at that path.make checkcannot see a break in this configuration — it builds the default feature set — but the PR gate now can:.github/workflows/ci.ymlrunsmake check-nodef(the shipping set:--no-default-featuresplus the playback backends) and type-checks bothhostsimconfigurations on every push. Until that landed, the shipping set was first compiled during a release cut, i.e. after the change had merged. ThePostToolUsehook (.claude/hooks/release-config-check.py) stays and is now the fast path rather than the only one — it catches the break before the push, and CI does not run in somebody else's checkout. It type-checks the bare--no-default-featuresset, which dropsplay-uriandplay-feedtoo (a build with no playback backend), so it does not replacemake check-nodef, which passes the Makefile'sRUST_BACKEND_FEATURES. It type-checks after every edit to arust-modules/src/**.rsor one of the fourteen layer crates it lists (it does not watchplayback-contract,media-codecs,play-feedorplay-uri, for whichmake check-nodefis the only gate that compiles them in the shipping set, norowp, which the application does not link yet); it costs well under a second warm, because cargo keys fingerprints by feature set and the two configurations coexist in onetarget/. The hazard it guards is hand-written#[cfg(feature = "devtriggers")]PAIRS, where a spliced-in function swallows a neighbour's attribute —devtrig::latched_flag!exists to avoid most of them.LAB=1adds a THIRD cargo feature,lab-diagnostics— the Cloud Lab bridge that gets logs off and app-level commands onto a television in LG Cloud Test Lab, where there is no ssh, no console, no stdout and no way to download a file, so the entire/tmptrigger surface and every recipe in this file is unreachable. In a lab buildplx_base::eventlog::logalso feeds a bounded in-memory ring (4000 records / 768 KiB), a configured remote key or a Send diagnostics row in the account / player-overflow menu snapshots it together withplayer::Diag,webosanddevcaps, scrubs it again, gzips it and POSTs it over pinned TLS totools/plxnative-labon the dev Mac. An opt-in outbound HTTPS long poll carries the same bounded synthetic-input token grammar back to the app's SDL main thread;tools/plxnative-lab send down ok wait:1000 diagqueues and waits for delivery acknowledgements. It adds no dependency and cannot run a shell or control another webOS process. Unlikedevtools/devtriggersit is not in the default set at all, so it cannot ship by forgetting a flag — andmake LAB=1refuses the stable id, and refuses to build without the session filepkg/lab.json(gitignored, a live secret, inoutbound-guard.py'sPRIVATE_FILES;ci/check-package.pyrefuses any non-LAB package that carries it). The receiver logs the PEER ADDRESS of every request, which is the only thing that tells "the television reached me from the internet" apart from "something on the LAN hairpinned". It composes withRELEASE=1and withmake sim-macos, each getting its own--target-dirfor the reason every other feature set does. Full account:docs/lab-diagnostics.md. The trigger is a code LIST in that file rather than a constant, and the reason is worth carrying: the colour buttons arewcode486 RED / 487 GREEN / 488 YELLOW / 489 BLUE (device-measured 2026-08-26), while the STANDARD evdev colour codes are a dead end on this firmware —KEY_RED/KEY_YELLOW/KEY_BLUEtranslate to nothing at all andKEY_GREENto a 504 this remote never sends. The one answer that looked derivable offline was derivable WRONG;docs/remote-keys.md§9 is the record.- Override the TV IP with
make TV=1.2.3.4 …; the run duration withmake run RUN_SECS=30.
Cross-compile toolchain: the webosbrew native-toolchain buildroot NDK —
arm-webos-linux-gnueabi-gcc (GCC 12, glibc 2.12, armv7-a soft-float; default cortex-a9
codegen, so we do not pin -mcpu). It ships a sysroot with the TV's own SONAME'd libs,
which the Makefile links against. Rust is a static lib built on the pinned STABLE toolchain with cargo +$(RUST_TOOLCHAIN) rustc --lib --crate-type staticlib --target armv7-unknown-linux-gnueabi (the crate itself declares
rlib only; a staticlib needs no linker, so no external
cross-linker). The target is load-bearing: armv7-unknown-linux-gnueabi ships a prebuilt ARMv7 std,
where the old arm-unknown-linux-gnueabi std was ARMv6 and carried the CP15 barrier that SIGILLs on
the A53 (that is what -Z build-std on nightly used to rebuild away). So are the codegen flags
(-C target-cpu=cortex-a9 -C target-feature=-neon,-soft-float): -soft-float is an UNSTABLE
target feature on stable rustc, and ci/check-vfp.py (make check, CI host-lint) fails if a rustc
stops honouring it; see the Makefile comment). Headers
come from include/ (the TV's SDL2 2.0.x-fork headers, kept ahead of the sysroot's newer copies
so we compile against the ABI the TV runs). The ipk needs no ar at all — ci/mkipk.py writes
the archive itself; this line used to say the opposite ("uses the NDK's ar (GNU format; macOS BSD
ar won't work)") and had it exactly backwards, see the ipk bullet below. The old zig cc path is
gone.
Most of the app links against the real sysroot libraries (SDL2, SDL2_ttf, GLESv2,
wayland-client, glib-2.0, luna-service2, and LG's proprietary libplayerAPIs / libpf-1.0 — all
bundled in the NDK), so the Starfish C++ calls get real link-time symbol checking. Every one of
those has the same SONAME on every webOS release from 2.2.3 to 11.2.0, which is what makes
linking them normally the right call — check any of it with tools/fwcompat.py --inventory.
PLAYBACK_BACKENDS=uri omits the Feed Starfish objects and the libplayerAPIs / libpf-1.0
imports. Grade that artifact with PLAYBACK_BACKENDS=uri ./ci/check-elf.sh pkg/plxnative (or pass
uri as the script's second argument). The gate requires the Feed callback hook and the full
ci/expected-dt-needed.txt set for the default both and explicit feed modes; URI mode
requires the hook and both Feed imports to be absent and matches the exact
ci/expected-dt-needed-uri.txt set. A bare ci/check-elf.sh grades the default both artifact.
Two families are deliberately NOT linked because their SONAME MOVES: libcurl
(.so.5→.so.4) and libAcbAPI (deleted outright at webOS 5.0). A DT_NEEDED entry is a hard
requirement for one exact name, which cannot express "either of these", and a name the device lacks
kills the process at exec() — before main, before the event log exists. So they are
dlopen'd by SONAME candidate list:
rust-modules/base/src/dynlib.rsis the one door.dynlib!takes a block shaped exactly like theextern "C"block it replaces and emits same-named wrappers, so call sites don't change. Loading is all-or-nothing — every symbol resolves or the table stays empty and the missing names go to the event log. Read that module's doc before adding a library to it; the rule is only when the version actually varies, because moving a library there trades link-time symbol checking for version tolerance.src/video_plane.cresolves ACB and the webOS 5+ SDL exported-window API the same way, and picks between them (vp_mode()). The two are complementary across all 14 firmwares.- Adding a new FFmpeg/curl call means adding it to the
dynlib!block. There is no link error to catch you any more — the failure is a loggedIncompleteat boot and a refusal to demux. - A VARIADIC C function keeps its
..., in the positioncurl.hputs it —fn curl_easy_setopt_ptr = "curl_easy_setopt"(h: *mut CURL, opt: c_int, ..., v: *const c_void). Naming the trailing argument's concrete type is right and is how one C symbol is bound as more than one wrapper; moving it before the ellipsis is a different CALLING CONVENTION, because Apple's ARM64 ABI passes variadic arguments on the stack while named ones go in registers. ARM32 and x86-64 pass both ways identically, so this compiles, passesmake check, runs on the television — and SIGSEGVs inside libcurl'sstrlenon a Mac, at the first plex.tv call. It was the shape the macro emitted until 2026-08-16;docs/macos-app.md§2 is the account.
FFmpeg is a third unlinked family, and it is no longer a version question at all: the app BUNDLES
its own and PINS it. This doc used to file FFmpeg beside curl and ACB as "SONAME moves,
55→57→58→59→60", which is the wrong mental model to carry into any FFmpeg change today.
ci/build-ffmpeg.sh cross-compiles FFmpeg 9.0 with the NDK — shared, LGPL-clean (no
--enable-gpl), under a -plx build suffix: libavutil-plx.so.61, libswresample-plx.so.7,
libavcodec-plx.so.63, libavformat-plx.so.63, plus libswscale-plx.so.10 in dev builds only. make deploy/make ipk
ship those .so files beside the binary, and media-codecs/src/ffi.rs::load_libraries opens them by absolute
path out of paths::app_dir(), in dependency order under RTLD_GLOBAL (they carry no rpath —
FFmpeg's configure evals its flags and $ORIGIN does not survive), after which boot() refuses to
demux unless the majors are exactly avformat 63 / avcodec 63 / avutil 61 / swresample 7 (libswresample
is checked although libavcodec's DT_NEEDED names it, because the audio converter calls it directly). Both the suffix and the absolute path are
load-bearing: webOS 11.2.0 ships FFmpeg 6 itself, so a bare SONAME could open the television's
copy, and "which libavformat did we actually get" is precisely the question that cannot be answered
over ssh. The reason to bundle was never the SONAME drift, which was survivable — it is that
demuxers, parsers and bitstream filters live in a registry, as data, so no symbol table and no
firmware inventory can answer "does this set's libavcodec have h264_mp4toannexb". Bundling makes
both halves compile-time facts, and it is also webosbrew's published guidance.
One consequence settles a question that keeps getting re-opened: our FFmpeg has NO network. It
is configured --disable-network with --enable-protocol=file as the only protocol, so it
cannot open a URL — http or https, on any firmware. Every byte reaches the demuxer through the
custom AVIO, whichever transport happens to be under it (stream.rs for http, net::range_io through media's credential facade for
https), and that is not an accident of the current pipeline but a build-time fact you cannot route
around. "Does the TV's FFmpeg have https?" is therefore not
something to go and probe on a device; it is decided, and the answer is that no FFmpeg in this app
has any transport of its own.
This replaced the old stub-.so trick, and stub/ is deleted. Empty .so files carrying the
TV's SONAMEs got the link to succeed, but in doing so pinned the binary to webOS 4.x: on anything
newer the loader killed the process at exec(), before main, before the event log existed. That
was the entire portability problem. Full account: docs/webos5-port.md.
- The C++
StarfishMediaAPIsmethods are still called from C viaextern … __asm__("<mangled name>")declarations (insrc/starfish.c), resolved against the reallibplayerAPIs. All 15 are present unchanged from webOS 4.4.2 through 11.2.0. - The gitignored
sysroot/usr/lib/(a few real TV.sofiles pulled off the device) is only for reference/inspection; the build uses the NDK's sysroot, not that directory.
tools/fwcompat.py resolves the built ELF's DT_NEEDED and undefined symbols against
webosbrew's firmware inventories — for 14 real LG images, every library, its DT_NEEDED, and
its full exported-symbol list, keyed by webOS release. It runs on the dev Mac, offline, in under a
second, and it reproduces webosbrew-ipk-verify's verdict exactly. Run it after any change to
linkage or FFI.
tools/fwcompat.py # the matrix: OK/FAIL per release
tools/fwcompat.py --release 5.3.1 # one release, listing what is missing
tools/fwcompat.py --inventory libAcbAPI libavformat libcurl
tools/fwcompat.py --lib libSDL2-2.0.so.0 --grep webOSIt grades whether the app STARTS, and nothing else. A firmware can export every ACB entry point
and still refuse to put a picture on the video plane. Today: OK on releases 4.4.2 through 11.2.0;
playback is device-verified on 4.10.0 (the dev set) and 6.5.2 (the webosbrew reviewer's set,
issue #22 — the VP_EXPORTED path works); opt-in PostHog playback.started events (2026-09)
additionally show direct and transcoded starts on field sets from 4.4.2 to 11.2.0, including
10.3.1 transcodes, while 3.9.3 sets have requests and no outcome (#249); and docs/webos5-port.md §4 is the list of what
webOS 5+ still needs a human with a television to settle.
The inventories are SYMBOL LISTS — name, package, needed, symbols, and nothing else.
So fwcompat.py answers "does this release export that function" and cannot answer anything about
strings, struct layouts or code. A JSON payload key like
option.externalStreamingInfo.contents.DolbyHdrInfo lives in .rodata, so it is invisible here —
proving one of those across releases needs the actual .so files, not this database. For our own
set, .agents/skills/decompile-tv-lib/ harvests and decompiles them; for OTHER releases we have no
binaries at all today, which is exactly the gap to state out loud rather than infer past.
Before pushing a change that touches FFI, linkage or dynlib!, hand it to the
fw-compat-reviewer subagent. It runs the matrix above and reads the new declarations against
the rules the matrix cannot express — variadic placement, the all-or-nothing loading contract, and
whether a new DT_NEEDED names a library whose SONAME actually holds still. CI gates the same
check, so the value is catching it here, before the runner and before a television refuses to
exec() the process.
Almost nothing about webOS native app development is in anyone's training data, and much of what is there describes the web-app stack, which is a different world from ours. Search the internet proactively — do not reason from a symbol name, a header found once, or another client's source and call it settled.
- https://www.webosbrew.org/develop/ is the reference for homebrew/native development on
these sets: the NDK we build with, the app/package model, jail profiles and install prefixes,
and the Homebrew Channel.
https://www.webosbrew.org/webos-userland/additionally publishes Doxygen for LG's own headers (StarfishMediaAPIs.hamong them) — a header, not documentation, but often the only public statement of a signature. - Also worth searching, in roughly this order of authority: LG's own published docs;
source of other clients that drive the same API (Kodi's webOS port is the closest analogue —
it drives StarfishMediaAPIs in the same
BUFFERSTREAMmode; jellyfin-webos and Plex's own webOS app are NOT analogues, they hand the TV a URL, which is a different pipeline and their results do not transfer); vendor specs for formats (Dolby, ITU, RFC); the openlgtv / webosbrew community; and the FFmpeg source we vendor. - Grade what you find. Vendor doc, a spec, or source you can read beats a forum post, which
beats a recollection. Say which tier a claim came from. And prefer the
find-docsskill /ctx7for library and SDK documentation over a raw web search. - Nothing external is authority over THIS firmware. Another client's source proves what some
webOS does; only the binaries on the shelf prove what ours does. When the two disagree, or when
the answer decides a device session, settle it with
.agents/skills/decompile-tv-lib/.
Two planes are composited by the TV: the app's GLES/graphics plane (UI, drawn by us) sits over the hardware VIDEO overlay plane (decoded frames). The UI plane is made non-opaque so video shows through.
UI (the Rust app core — the frame loop in app/run.rs::run, entered via plex_run() in port.rs, which passes the platform (app::platform::Platform) to app::run_application, after app/boot.rs::boot()): SDL2 window + GLES2
context. All UI is drawn with two tiny shaders — an SDF rounded-rect/triangle shader (cards, focus
glow, HUD widgets, seven-segment FPS) and a text shader that samples glyph
textures (cached by string+size): SDL2_ttf renders every run except Arabic and Hebrew, which libass-plx
shapes and rasterizes into the same texture (gfx/src/rtl.rs).
Critically-damped springs animate focus scale and shelf scroll.
Fonts are the appfont*.ttf faces deployed next to the binary, in the fallback chain gfx/src/text.rs opens (Inter, CJK, emoji, Arabic, Hebrew; Inter, Arabic and Hebrew with bold cuts; ci/test_shipped_faces.py holds every staging list to it), so a missing libass-plx costs Arabic and Hebrew UI text as well as text subtitles; the subtitle renderer additionally loads the per-script Noto faces from fonts/subs/ (docs/ass-subtitles.md, cut by tools/cut-noto-subs.py, staged by SUBS_FONT_FILES in the Makefile). (The SDL window, the event decode and the text-input calls live in
rust-modules/shell-sdl/ (crate plx_shell_sdl), the Wayland surface setup in system.rs, and the key ladders in
app/events.rs + app/input.rs, not the C shim — see the gotchas below.)
Video playback (summary — rust-modules/media/src/player/CLAUDE.md is the deep-dive: pipeline,
threading model, the Starfish/ACB ABI + bind-order gotchas, seek/PTS rebase. Read it before
touching playback): LG's in-process StarfishMediaAPIs (libplayerAPIs.so) in
BUFFERSTREAM buffer-feed mode, the decoded sink bound to the hardware video plane via
libAcbAPI (ACB). Normal playback uses this in-process buffer-feed path; the controlled
URI experiment also displayed its SDR720p24 fixture
through ACB on the webOS 4.5 dev set, with and without connectDass. The normal media pipeline
is all Rust: PMS HTTP GET → demux (ff.rs, over a custom AVIO on the
FFmpeg the app BUNDLES — not the television's; see the linking section, and note ours is built
--disable-network, so the AVIO is the only way bytes reach it) → AU queues with backpressure
(play-feed/src/aq.rs) → the pump Feed()s the Starfish
pipeline. Worker threads (demux, media/load, and sf-unload for a real stop's Unload) sit
beside the main loop, which owns every other ACB/Starfish control call
(rust-modules/media/src/player/CLAUDE.md, threading model). That GET has TWO transports and the part URL's SCHEME picks one,
once, in ff::demux: http reads through stream.rs's raw socket, https through
net::range_io (through media's credential facade) — libcurl's multi interface behind a read/seek/size/status/abort pull
source, so ff.rs never learns curl-multi mechanics. It exists because LG's reviewers have no PMS
on their LAN and stream from the public internet, which stream.rs cannot reach: it speaks
cleartext. So libcurl is used by three modules for three jobs — net.rs for plex.tv plus HTTPS PMS
control calls, net::range_io for the media bytes, net::connect_only for the WebSocket's socket —
and each binds its own dynlib! table,
which the linking section explains is load-bearing rather than tidy.
Subtitles (summary — docs/ass-subtitles.md is the deep-dive; rust-modules/media/src/player/CLAUDE.md
has the producers). The client draws subtitles itself; the TV's subtitle engine is unreachable in
buffer-feed. Every TEXT subtitle renders through the one bundled libass renderer (player::ass: a
primary worker, plus up to two helpers while a moving cue is pipelined, each with its own libass instance),
whether it is authored ASS/SSA, an embedded SubRip/WebVTT/mov_text/SAMI track or a sidecar .srt/.vtt:
a text track gets a header text_ass::header synthesizes from the viewer's size, position and colour picks, and
its cues become ASS events (text_ass::convert, ass_source::push_text). Such a source has
Origin::Text: it renders into the full logical screen, the screen lifts its bottom-anchored regions
clear of the transport, and a change of the size, position or colour pick restyles it (a change among white and the grays does not: a gray is a draw-time tint). An authored ASS source is
never moved. The old caption path is gone (CaptionPlan, draw_subtitles, the SHARED.sub_cues
store, active_subtitle*): do not look for a second text renderer. Image subtitles
(PGS/VobSub) keep their bitmap path. The one text the sidecar still draws itself is its failure notice
(sidecar::notice()), drawn by the player screen with appkit::player_hud::draw_subtitle_message.
Fonts are bundled Inter plus per-script Noto Bold faces; because libass runs with no font provider, a
missing or unloadable libass removes every text subtitle and the screen draws the libass fault message
(ass::Fault::message, via AssSubtitles::error) instead; the sidecar's own failure notice
(sidecar::notice()) is only for a sidecar that fetched or converted to nothing.
The intended layering is gfx/text/i18n < ui < screens < app and plex < route/player < app
(ci/module-layers.ini is the full target, gated per reference by ci/check-module-layers.py). A
few thin upward references once closed one strongly connected component of top-level modules
holding 44 of them; the module-layer migration (docs/module-layers.md) cut it to 13 by step L14
(ci/module-cycle-baseline.json has the current set), which is this tool's coarse view of edges
the layer gate allows: it sees diag as one node, while diag::{zlib,spans,heartbeat} sit in a lower
layer (ui left this graph when it became plx_ui). The gate does not untangle it; it stops it absorbing more modules. It builds the module graph from production code only (the
module tree walked from lib.rs, #[cfg(test)] items and test-only files skipped, comments and
strings blanked; the docstring lists what it cannot see), compares the cycle's members with
ci/module-cycle-baseline.json, and fails when a module outside the baseline lands on a cycle
- a new upward
crate::xreference, or a new top-level module that lands inside the cycle - printing thefile:linereferences into and out of that module. A member leaving the cycle only prints a notice. It holds the cycle's membership, not its edges: a further upward reference between two modules already on the cycle (anotherapp->dev) does not fail it. It runs inmake check-python(so CI'shost-pythonjob, viacheck-python-rest), tested byci/test_module_cycle.py.
To fix a failure, remove the new path back: move the shared type down a layer, pass the value in as
an argument, or invert the dependency behind a trait or callback owned by the lower layer. When
the growth is deliberate (or after the cycle shrank), run ci/check-module-cycle.py --update-baseline
and commit the JSON with the change. --report prints the cycle, the heaviest mutual pairs and
every thin back-edge with file:line (the work list for breaking it up); --dot emits graphviz.
Makefile— build/deploy/run/ipk; toolchain, the bundled-FFmpeg build + staging + its ABI gate (one header tree, not the old dual one), TV ssh creds.src/main.c— the boot shim (event-log/stderr setup, process bring-up); calls the Rustplex_run()(rust-modules/src/port.rs, which runsapp::run_application).src/crashtrace.c(+crashtrace.h) — the fatal-signal tracer, its own TU so the signal path can be tested;src/crashfmt.his its pure half. Both halves are host-tested inmake check—ci/crashfmt-test.cgrades the parsing,ci/crashtrace-test.ccrashes seven processes on purpose and checks the record AND the exit status, and probes another with the freeze signal (SIGUSR2) to check it records and survives.src/starfish.c— the buffer-feed StarfishMediaAPIs C++ seam.src/video_plane.c— shared ACB/exported-window binding.src/svg.c— nanosvg rasterizer.src/sentry_context.c— the narrow C wrapper that keeps Sentry's opaque by-value object ABI out of Rust.src/exit.c— libcexitdefined in the executable (and exported by the link), so a shared library'sexit()ends the process throughplx_exit_recordinsrc/crashtrace.c(an async-signal-safe record, in the event log and the crash log, naming the thread and the calling library, then theexit_groupsyscall, or a park while a fatal signal's handler is running, which lets that crash end the process; not through Rust'sexit_now, which flushes under locks);ci/exit-interpose-test.cgrades it on Linux.src/access.c— libcaccessdefined the same way (exported by the link, so a shared library'saccessbinds to it): the GPU driver probes four/tmpdebug-switch paths (API_PRINTat the top of every GL call,SKIP_PRINTin each draw and swap,GM_FPS_PRINTonce per swap,SHADER_PRINTfromglUseProgram), each failing lookup costs ~8.5 us of kernel time on the webOS 5.6.2 TV, so those paths are answered "absent" in user space and every other path gets the kernel's own answer;ci/access-interpose-test.cgrades it on Linux. These eight are the entire normal C side (gpdebug.cis an opt-in allocator instrument). Reach for/tmp/plxnative-crashtest=<segv|abrt|bus|ill|trap|panic|unwind>to fault the app deliberately ON the television —segvis a real null write,abrt/bus/ill/trapareraise,panicpanics inside anextern "C"callback, andunwindpanics straight incrash_on_purposeso the unwind crossesplex_run's own frame (rust-modules/src/dev.rs'scrash_on_purposedoc comment has the detail)./tmp/plxnative-freeze=<seconds>(1 to 120) stalls the MAIN thread on purpose, once, on the eighth heartbeat, to exercise the freeze probe (dev::freeze_on_purpose; the trigger file is removed when it fires). A real freeze is a 5 s stall of the loop in the foreground: the watchdog (plx_base::task::watchdog) sendsSIGUSR2to the main thread,freeze_handlerinsrc/crashtrace.cwrites a*** FREEZErecord, the observer thread appendsfreeze-at: seq=<n> leg=<word>to the crash log (the loop leg the main thread was in, one ofLoopPhase::word's eleven words;LoopPhases::enterstores seven of them andspan_leg, called bydiag::spans::span, the other four for the span's duration (scen,pump,land,dframe; restored on return or unwind), in every build,threadcheckor not and the frame instrument armed or not, so a release report says where the loop stood, a freeze inside the playback pump included; the importer joins the two lines by probe number whichever came first), and the next launch reports it (telemetry::crashreport). The app is never stopped. A default (threadcheck) build aborts the stalled main thread at 2 s, before the 5 s probe, unless/tmp/plxnative-guardcontainslog: writelogthere before launching, or no freeze report is produced. Anexit()made by a firmware library (src/exit.c) writes a*** EXIT status=<n> caller=0x…record to the event log and the crash log, and the next launch reports it as anerrorevent that is not a crash (telemetry::crashreport). An exit made in the foreground leaves its sessionabnormal, like a freeze's; one made after backgrounding (the PLX-NATIVE-1P shape) finds no open session, because backgrounding already ended itexited(telemetry::session), so only theerrorevent exists.rust-modules/src/— the app core (Rust):app/(mod.rstherun_applicationshim +struct App,boot.rsthe bring-up,run.rsthe frame loop and its phase functions,events.rs/input.rsthe input decode and key ladders,lifecycle.rs,playback.rs,content.rs,bridge.rsthe seam onto the container and the ONE navigation vocabulary,words.rsthe heartbeat'sroute=/overlay=alphabet —nav.rsis gone withenum Routesince restructure phase 12),system.rs(wayland),rust-modules/shell-sdl/(crateplx_shell_sdl:SDL_Init, the window, the GL swap, the event decode and the text-input calls, whichapp/platform.rs'sShellopens as theSurfacetheAppowns (ShellandSurfaceare reachable from outside the crate only throughplxnative_modules::host;HostEventstays app-private)), and, in the media layer (rust-modules/media/, crateplx_media, which the application links),player/(buffer-feed engine + worker threads —rust-modules/media/src/player/CLAUDE.mdis the playback deep-dive; read it before touching playback),abr/androute/, andff.rs, which re-exportsplx_media_codecs' FFmpeg bindings and holds the integration fixtures.play-feedowns the feed demuxer (play-feed/src/ff.rs,plx_play_feed::demux, over the bundled, pinned libavformat shipped beside the binary, not the TV's), the AU queues and the HLS parser;media-codecsowns the FFmpeg ABI and encoder;net::range_ioowns interruptible HTTPS byte ranges while media supplies credential authorization. The Plex layer (rust-modules/plex/, crateplx_plex:plex/andhttp.rs— its ownrust-modules/plex/src/plex/CLAUDE.md, which the rest of this file never pointed at: read it before adding a PMS query, and before assuming there is one server. There is a REGISTRY behindclient()now — the app can hold a friend's shared server beside your own, each with its own token,ratingKeyspace and watch state.docs/shared-servers.mdis the design note).rust-modules/ui/src/(workspace crateplx_ui) — the UI, as a shared design system:theme.rstokens, the retui core (lib.rsPainter/View), reusable components (widgets.rs/table.rs/label.rs/icons.rs), and, since phase 9 (Player was the last), no legacy screens at all — every route mounts an owned screen underscreens/(rust-modules/screens/src/, workspace crateplx_screens). The player's drawing/state modules (appkit/player_hud/,track_menu.rs,info_panel.rs,chapters_panel.rs,up_next.rs,more_menu.rs,timing_capsule.rs,skip_pill.rs) and the Sources row model (appkit/source_list.rs) live inrust-modules/appkit/src/(workspace crateplx_appkit), the layer betweenui/andscreens/for widgets several screens share — they name application types, so notui/, and thesiblinggate keeps them out ofscreens/.rust-modules/ui/src/CLAUDE.mdis the contribution guide — read it before touching UI: use tokens + components, never inline colors, never raw font sizes (ALL text in the UI takes its size from thetheme::sizetoken scale — add a documented rung when a new role needs one), never hand-place text. Full design/status:docs/ui-system-migration.md. (rust-modules/net/src/stream.rs— blocking HTTP/1.1 over a raw TCP socket: hostname or IPv4/IPv6 address, and a body delimited byContent-Length, by close, or byTransfer-Encoding: chunked, which it does decode (HttpStream'schunked/chunk_left, the header match inhttp_open, andhs_next_chunk). This line claimed "no chunked decoding" long after that stopped being true, which makesstream.rsread as less capable than it is and sends work tonet.rsthat it would have handled — its remaining transport disqualifier is TLS: it resolves throughgetaddrinfo, walks either address family, and speaks cleartext.aq.rs— one-producer/ one-consumer AU FIFO with byte-cap backpressure. Both are Rust ports of the deleted C headers; the hand-rolledmkv.rsdemuxer they fed is retired —ff.rsis the only demux path.)rust-modules/base/src/eventlog/(scrub.rs,ring.rs) withrust-modules/telemetry/src/diag/(crateplx_telemetry) — the redaction pass and the diagnostic plumbing every off-device report shares.scrub.rsis the one that matters and it is UNGATED:plx_base::eventlog::logrunsscrub_localon every line in every build, so credentials, hosts, bare addresses, Plex GUIDs, search queries and this household's names are rewritten before the write, not on the way out. Two exits, differing in exactly one respect —scrub(network) may DROP a line it cannot make safe;scrub_local(disk) may only rewrite one, because a line silently vanishing from the primary debugging surface is worse than a leaky one.eventlog/ring.rsanddiag/zlib.rs(both inplx_base) stay feature-gated to their consumer. Lifted out oflab/on 2026-08-29 — which also fixed the fact that the 31 assertions guarding this function never ran inmake check,lab/being wholly behind a feature the default gate does not build. A title cannot be scrubbed (nothing distinguishes it fromtask: spawn 'labup' REFUSED), so the mechanism for viewing content is that call sites do not write it, pinned by a test that greps the tree — seeno_log_call_site_interpolates_viewing_content. Adding alog(&format!(…))that interpolates an item title, a search query or subtitle text will failmake check. Identities come fromplex::session::publish_identities, PUSHED on load/save; the scrubber must never callsession::peek()from the log path.peek()is a pure read of the cache (it submits nothing, so it can no longer reachstorage_workerfrom a log line), and the refill that once hid behind it is the session owner'sRefreshCacheeffect; but worker startup holdsstorage_worker::SHAREDacrosstask::spawn, whose refusal logs, so a log line must not grow a path back into the queue, and the scrubber stays fed by the pushed identities.rust-modules/base/src/task/blocking.rs/watchdog.rs— frame scopes reject synchronous work. Tests keep catchable panics. Release guards log elapsed time once per label; the watchdog logs once above 250 ms and once on recovery, polling every 100 ms after the first present. Developer builds (threadcheck) write the fatal guard log and abort before an unallowed call executes. The watchdog publishes a purple warning, painted only when the frame thread can draw, lingering three seconds after recovery. Controlled recording/replay boots suppress only this warning's forced presents and pixels; checker logs and fatal enforcement remain active. At >=2000 ms it sends SIGABRT once to the main pthread captured at loop start, preserving the interrupted thread's registers. Guardabort()records the abort path instead; the label identifies its guarded call. The host harness never starts the observer. Developer draw/swap scopes label stallsframe draw/gl presentwithout invoking or bypassing the blocking guard; slow GPU frames still count toward the two-second fatal limit on hardware GL. WhenGL_RENDERERnames a CPU rasterizer (Apple Software Renderer, llvmpipe, softpipe, swrast, SwiftShader, WARP — the CI simulator), time in those phases and ingl readbacklogs and warns but does not count toward the kill; two seconds outside them and the blocking guard stay fatal (task/runtime_check.rs). A watchdog poll gap >400 ms discards the uncertain interval, clears warnings and rebases the stall timer and fatal latch: a stopped or starved observer is not evidence against the main thread. Escape hatch: writeloginto/tmp/plxnative-guardbefore launch (sim: instance runtime root). This boot-latched DIAG trigger requiresdevtriggers, keeps the picker unchanged and downgrades both fatal paths to logs plus warnings. Release builds contain none of these new dev paths.rust-modules/data/src/stores/(crateplx_data) — the data stores behind ONE vocabulary and ONE step (restructure phase 4, 2026-09-07;docs/stores-as-machines.md):StoreCmdis the complete set of mutations ofbrowse/pms/metadata/search/person/viewstate. Browse, Hubs, Metadata, Person, Search and ViewState are physically owned perBridgebyStores:BrowseStoreowns its state/adapter/notice,HubsStoreowns itsPmsState/Arc<PmsAdapter>/notice,MetadataStoreowns its state/Arc<MetadataAdapter>/notice,PersonStoreowns its model/generation/retry state plus a rotated indexed fetch adapter,SearchStoreowns its state/adapter/notice with a rotated adapter, andViewStateStoreowns its queue, in-flight request, retry/refresh latches, rotated worker adapter and notice. ViewState completions carry a monotone request ID and only the exact in-flight identity lands; a landed read-back re-reads every Detail page naming the item, its season or its show (AppMsg::DetailReconcile: the top page Requested, a covered one Deferred until uncover; it carries only the obligation, no address and no episode). Owned screens emitAppFx::Store, andapp/bridge.rsdelivers it to the owning machine. A command that changes observable state raises the store's notice. Browse has no active-owner compatibility reads and nostores::browse::apply(Cmd)shim: consumers receive per-owner retainedDirectoryView/ListingView/HubsViewpublications, and fixtures own aBrowseStoreorStoresbefore capturing those publications. Person's borrowedPersonViewreaches its three live readers throughAppViews/Cx, never a free selector. The aggregate notice drain inapp/bridge.rsdeliversStoreChangedto live pages;metadatareads go throughMetadataView, which borrows from the owner (&'a), not a compatibility global or mailbox.rust-modules/base/src/dynlib.rs— the runtime library binder (dlopen, by SONAME candidate list or by absolute path). Its callers (git grep -l 'dynlib! {' -- rust-moduleslists them), each for its own reason:net.rsbinds curl by candidate list because its SONAME moves between releases;media-codecs/src/ffi.rsbinds the bundled FFmpeg by absolute path because ours ships beside the binary, on no library search path — not because any version varies;player/ass.rsandgfx/src/rtl.rsbind the bundled libass-plx the same way, the subtitle surface and the UI text surface in two tables, each checking the facade ABI against its ownNATIVE_ABI, so a facade bump edits both; andnet::range_iobindscurl_multi_*in a SECOND table of its own, from the same candidate list, becauseload_intois all-or-nothing and a set missing one multi symbol must still be able to SIGN IN. That table is frozen to the oldest supported set:curl_multi_poll/curl_multi_wakeupresolve on the dev Mac, are absent on the dev television, and first appear at webOS 7.4.0 — so binding them would have emptied this table on four of the nine gated releases.net::connect_onlybindscurl_easy_send/curl_easy_recv/curl_easy_getinfoin a THIRD libcurl table, from the same candidate list, so a libcurl without them loses only the WebSocket. Another isplx_base::diag::zlib(rust-modules/base/src/diag/zlib.rs), which binds one symbol —compress2— in a table of its own so that a television without libz degrades to an uncompressed upload rather than emptying anybody else's table; it exists only in alab-diagnosticsbuild, which is not the default set. (ACB is the same idea but not this module:src/video_plane.cis C and does its owndlopen.) Replacedstub/, which is deleted.tools/fwcompat.pygrades the result;docs/webos5-port.mdis the full account.docs/release-notes/+docs/release-audits/— the two halves of a release, split 2026-08-29: the note is the body CI publishes, written for a television owner and deliberately short; the audit is the evidence (package facts, hashes,DT_NEEDED, payload inventory, provenance, firmware matrix, LGPL position), whose measurable halfci/gen-release-audit.pyREADS OUT OF THE .ipk during the release run rather than anyone typing it. Each directory carries its own standard as a README, andci/check-package.pygates both documents — including, for notes, that prose is NOT hard-wrapped and every link is absolute, because a release body is rendered at a width nobody controls and resolves no repo-relative path. Thecut-releaseskill is the procedure.docs/install-finnative.md— FinNative's invariant half a release note used to repeat every time: which asset is which, the one install route (Dev Manager; FinNative is not in the Homebrew Channel catalogue yet), how to check the sha256 per platform, and what the app writes, reads and reaches on your television.docs/install-and-verify.mdanddocs/troubleshooting.mdare PlxNative's, kept as upstream wrote them;docs/troubleshooting-finnative.mdis FinNative's troubleshooting guide.site/— the landing page (index.html/styles.css/site.js/CNAME);.github/workflows/ pages.ymlstages its screenshots, logo and fonts from their existing README/app locations rather than copying them intosite/. The close-up stillssite/media/closeup-*.jpgand the link-preview cardsite/media/og-card.jpgaremake screenshotsoutputs (the page showscloseup-glassandcloseup-tilesin its Features look panels; phones crop the widecloseup-glassrather than usecloseup-glass-narrow;closeup-playerand the narrow glass cut are no longer referenced, though still rendered and staged; the page's four app screenshots aredocs/screenshots/{home,library,search,player}.jpg, staged bypages.yml) (ui-simskill, "Documentation screenshots"): the card issite/og/card.html(not deployed) rendered around the home figure bytools/render-og-card.sh; re-render after editing the card. Their WebP and phone (-narrow) copies come from those JPEGs throughtools/render-site-variants.py, and the glows behind them throughtools/render-site-glows.py: run both, in that order, after a re-render.pkg/— deployable payload:appinfo.json(native app manifest),plxnativebinary, icons,appfont*.ttf, and the prebuilt.ipk.ipkroot/— ipk staging (ctl/control,data/,debian-binary); assembled bymake ipk.tools/capture-screen.sh— pull the TV screen (incl. video plane) to a local image.tools/plxnative-lab— the Cloud Lab diagnostics/control receiver (host-side, python3 stdlib only):startmints a session (id, bearer secret, self-signed certificate, SPKI pin), writespkg/lab.jsonformake LAB=1, listens on TLS and opens a TEMPORARY UPnP IGD mapping on the router for a fixed external port;status --jsonis what an agent polls (receiver, mapping, last-upload age, control-poll age, the webOS/board/model/version of the set that uploaded);send <tokens...>queues bounded app-input commands and waits for their acknowledgements;clearcancels stale queued/in-flight input before a disconnected TV comes back;logs [--follow] [--since 5m]prints snapshots as JSONL;stopremoves the mapping and VERIFIES it is gone. The public routes arePOST /v1/diagandPOST /v1/control/poll; enqueue/status are loopback-only even to a caller holding the session secret. Auth precedes body reads, every body and queue is capped, and there is no filesystem serving or subprocess.tools/plxnative-lab selftestproves upload, ordered redelivery/ack and refusal paths on loopback with no television, and runs insidemake check.tools/hud-dev— Player HUD authoring server (host-side, python3 stdlib only; on a Mac run it with/usr/bin/python3, the interpreter the application firewall allows by default; any other python is dropped silently until its "allow incoming connections?" prompt is clicked, as fortools/netcond.pybelow):tools/hud-dev SOURCE --sim PATH [--port N]packs a HUD source folder or.plxhudwithtools/hud_package.py(the simulator's--hud-pack), lints it with--hud-linton every mtime change, serves the last CLEAN bundle on0.0.0.0at ahttp://<RFC 1918 address>:<port>/<name>.plxhudit prints (and refuses to start without such an address), and raises the served patch version on every clean change (numericMAJOR.MINOR.PATCHis all the store compares). It touches no TV: the TV side is Settings > Player HUD > Install from address, then Play on the HUD's row to fetch the next build.tests/test_hud_dev.py(a stub simulator, loopback port 0) is inci/check-python-steps.txt; the recipe issite/hud/AUTHORING.md, "Developing a HUD on the TV".tools/netcond.py— network-conditioning TCP proxy (host-side), for the failures a healthy LAN cannot produce. Sits between the TV and the PMS (--listen 32499 --target 127.0.0.1:32400 --allow-client <TV_IP>; the PMS runs on the dev Mac) and makes the server misbehave on demand via/tmp/netcond.mode. A non-loopback listener refuses to start without an allowlisted client: PMS request URLs carry credentials, so a LAN-wide forwarding proxy may never be open by default. Modes:pass/stall(accept, hold open, answer nothing — the case that turns a join into a parked frame loop) /blackhole/reject/delay:<ms>/rate:<kbps>. Any mode scopes to matching requests —stall@/:/timelinefreezes the progress reporter while video keeps streaming, which is what makes a clean experiment possible. That sentence was FALSE for as long as it existed and became true on 2026-08-23:serve_connconsulted the scope-awareapplies()to decide reject/blackhole, then handedrelaya bareMode.split, which throws the scope away — so a scoped mode really applied to every open connection, media stream included, which is the exact opposite of what a scope is for. Both halves are scope-aware now andtests/test_harness.pypins it. Modes apply to connections ALREADY OPEN, so a POST can be frozen mid-flight.rate:is the newest and it is a SPEED rather than a fault: one token bucket for the whole proxy (a link is shared), decimal kilobits, live under an open transfer, so the four legs of LG checklist item #43 CASE1 — 512 Kbps → 1 Mbps → 7 Mbps → 17.5 Mbps — are one scripted run instead of four launches, and #14's degrading link is measurable rather than anecdotal.tools/netcond.py --selftestproves the shaper against a loopback transfer with no television in the room. Point the app at it by editingPMS_PORTin the gitignoredsrc/config.local.handmake deploy(host/port are compiled intomain.c). Pick a port Plex is not already on — it binds127.0.0.1:32401itself, and the more specific bind wins, so the proxy is silently bypassed. And the macOS application firewall silently drops the TV's connections to the ad-hoc python listener (verified 2026-08-11: netcond up, mode armed, zero requests logged, the TV's probe gets an empty read) — the "allow incoming connections?" GUI prompt must be clicked once per python path, so start netcond BEFORE going headless, and treat "netcond logs nothing" as this, not as a quiet TV.tests/run.pyowns one for the whole SERVER tier since 2026-08-27, so a case can declare alink_profile— legs of{"at_s": …, "mode": …}anchored at the app's first log line — and be graded over a link the harness controls rather than over whatever the LAN was doing. It is fail-closed and has to be: the app's primary server isplex_run(PMS_HOST, PMS_PORT)plus the injectedplxnative-token(plxnative-serversis strictly ADDITIVE and cannot move the primary), so the link is conditioned only if the DEPLOYED BINARY was built withPMS_PORTpointing at the proxy — which the harness can read out ofsrc/config.local.hbut never arrange. When it cannot bind, or when the binary talks to the server directly, every case naming alink_profileSKIPS with that reason in the summary, because a shaped assertion on an unshaped link is a false pass. Alink_profilealso disables early exit: the interesting leg is never the first. Measured with it 2026-07-29: teardown's join of the/:/timelinereporter parked the main loop 6974 ms; after moving that join onto the scrobble worker, BACK→teardown is 0.5 s. That run was taken while the scope bug above was live, so the proxy was stalling EVERY connection and not only the reporter's — and the number and the conclusion both survive it, for a reason worth writing down rather than re-deriving. The finding was recorded asTHREADJOIN timeline 6974ms(task::joinemits one NAMED line per join), so the attribution came from the instrument and not from inferring a total; andtimelineis the only join that COULD have parked whatever else was stalled, becauseroute_start::teardown's step 1 deliberately wakes the other two before joining them —http_shutdownon the demux socket,aq_aborton both AU lanes — while the reporter's POST had no such wake,stream's one-shot wrappers boxing their socket privately. The before and after were taken the same way, so the 14x is apples-to-apples. What CANNOT be claimed from that session is the thing the scope sentence promises — that video kept streaming while the reporter was frozen. It is a property of the tool today and was not a property of that run; re-running it scoped (and seeingdemux/mediaat 0 beside it) is a device job nobody has done. NB a request occasionally fails through the proxy that succeeds direct (seen once onPOST /playQueues) — confirm any new failure against a direct run before believing it.tools/tv-session.sh wan off [TTL]|on|status— cut the TELEVISION's uplink, LAN intact (2026-09-05). The offline-mode test condition, in two halves because the firmware has one tool of the two (probed that day): a netfilter chain on the set's own OUTPUT (iptables 1.6, filter table loaded) rejects every v4 packet not bound for the LAN and every DNS query, and — there being NOip6_tablesmodule, soip6tablescannot even open its filter table — anunreachable 2000::/3route cuts public v6 while the on-link /64s keep LAN v6 and neighbour discovery intact (more specific than either default route, so no metric contest; note that the kernel maps an IPv6 route metric of 0 to 1024, which is why a metric trick was not the answer).offproves both halves from the set's own tables or fails.offwrites the restore script ON the set and starts a watchdog there, so a dead harness or a sleeping Mac cannot leave the household offline past the TTL;onrestores at once.tests/run.pydrives it from a case's"wan": "off", restores in the case'sfinallyand again inteardown(). Two more case attributes came with it:"session": "stored"boots from the install's OWN sign-in instead of the injected token (the injected path installs a plaintext origin and never touches theplex.directname a real sign-in persists, so an offline case through it is a false pass by construction; the case refuses when the install holds no sign-in), and"primary_ipv6": truere-points the primary onto its IPv6plex.directorigin read off plex.tv, with itspin.offline_playandoffline_play_v6are the cases, andexpect.resolve_pin/expect.offlineare their assertions (the latter keyed on the slot the play was dispatched on, requiring that slot'shubs: source N ok, with the negative control being any plex.tv refusal the app logged OR — when a managed profile is active and the boot makes no plex.tv call at all — the tool's ownresolve plex.tv -> FAILprobe from the set; the former, forv6, also requires the v6 re-point line to PRECEDE the play start, since the scrubber turns every host into<host>and the pin line itself names only the family — a dashedplex.directlabel is a LAN address spelled sideways and is never logged). Both PASSED on the dev build, real cut, 2026-09-05 (docs/measurements/offline-wan-cut-tv-2026-09-05.log). The release build cannot be a harness case —run.pyrefuses a release binary and its key injection needs the dev-only FIFO — so the store configuration is proven by hand:make RELEASE=1 FLAVOR=debug deploy,tools/tv-session.sh wan off 900, launch, pick the profile with the physical remote, browse, play, then readtv-session.sh log 'resolves|hubs: source|curl rc'andwan on. Done 2026-09-06 by the owner, with the router's uplink really down — and it FAILED at the picker: the origin was pinned and the roster restored, but every profile pick went to plex.tv's/switchand timed out (docs/measurements/offline-picker-red-tv-2026-09-06.log; the active profile is the PIN-protected admin, which the one no-network shortcut excluded). The fix caches each profile's credentials at its ONLINE seating (Session::profiles, a PIN as a local verifier) and seats from that when plex.tv does not answer —plex/CLAUDE.mdhas the mechanism,offline_pick_cachedis the harness case (itsprime_onlinestep seats the tile once with the link up, so the cache is the case's own doing), and the PIN half is proven on the simulator (offline-picker-sim-green-2026-09-06.log) because the harness cannot type a PIN it does not know. The by-hand release-build proof is owed AGAIN for the fixed build: it was deployed to the debug install the same day and awaits the owner's next real cut. The router-side alternative (Keenetic's per-client "No Internet access" policy) is manual and was not needed.tools/sockprobe.c— standalone ARM diagnostic (make sockprobe, scp, run, delete) for socket semantics the host suite cannot answer:cargo testruns on Darwin, the app on Linux, and they disagree. Measured 2026-07-28: on this kernelshutdown(2)does abort aconnect(2)in progress (rv=0, handshake dies at once) — which is whystream.rs::http_openpublishes its fd atsocket(). On Darwin the same call instead makesconnect_timeoutreport success on a socket that never connected. Reach for this before asserting any syscall behaviour from memory.tools/logmprobe.c— standalone ARM diagnostic (make logmprobe, scp, run, delete) for LG's KADP log masks, on a RUNNING app. It exists because of one specific trap that cost a day:KADP_LOGM_WriteLoggates BITWISE, not by threshold —(1 << level) & rec[0x20] & ~rec[0x24]— andkad-hdrships withenable=0x0000000b, i.e. levels 0/1/3 with bit 2 clear. SoDOVI_MDAsync_WriteOTTMetaData's only unconditional line is invisible, a perfectly healthy metadata writer logs NOTHING, and "it never appears in the log" is not evidence it never ran. The mask table is mmap'dMAP_SHAREDfrom/dev/lg/logm, so it is shared by every process and can be flipped from a SECOND ssh session mid-playback — no rebuild, no relaunch, no perturbation of the session being measured. Read-only unless givenset/clear. This is what ended the Profile 5 investigation (2026-08-21) in one run, and the general rule it teaches is in[[silent-instrument-trap]]: prove the instrument can see the thing before reading its silence. Two more instruments here are silent by construction — the heartbeat'svtick=/vgap=count a 5 Hz position callback, not presented frames, and read a flatvgap=201msstraight through a visible stutter (and the diagnostics panel's "Picture … fps" is the PIPELINE'S OWN CLAIM from itssourceInfo, which on 2026-09-03 read "30 fps" over a 24p stream it was judder- presenting on a 30 fps lattice — the row now says whose number it is). The instrument that CAN see presented frames, since 2026-09-03: the app'ssink: displayed=line (raw callback 47 on webOS 4, 49 on 5+), the video sink'snon-flushable-displayed-framesread by libpf every 200 ms once the Load payload saysstreamQualityInfoNonFlushable(type 46 isdropped-frames, only when non-zero); the harness'spresented:characterisation line is that counter as a rate, and it measured the 30-lattice case at 13.0 fps presented vs 24.1 with the rate declared correctly; and LG'sGST_DEBUGwas long avoided as perturbing, which is true ofdualsequencer:9and false of:6(same scene, 123 misses uninstrumented vs 122 traced) —:6is the only per-frame cadence instrument this project has.tools/tv-capture-bench.c— staged standalone ARM benchmark (make tv-capture-bench, scp, run, delete) for a prospective hardware screen recorder. Itsvtmmode measures the real rotating video DMA-buffer cadence without mapping or copying the plane,osdtimes graphics-framebuffer descriptor access, andvencfeeds synthetic NV12 frames to the firmware H.264 encoder. Itsstreammode uses the source-video SCALER plane (DISPLAY advances but is blank here), maps each/dev/memY/UV plane read-only, and serves firmware Annex-B H.264 over TCP. On the development TV on 2026-09-07, a current YouTube picture reached the Mac as 300 decodable 1280x720 frames in 4.99 s (60.08 fps, 6.74 Mbit/s; encode p95 12.22 ms, send p95 1.36 ms) without stopping playback. The TV firewall refused a direct new LAN port, so that proof reached the probe's TCP listener through an SSH local forward targeting the TV's loopback interface. The memory-input encoder rejected every tested size above 1280x720, including 1920x1080. This benchmark therefore proves a 720p60 video-only path; it does not yet prove full-plane OSD composition, audio, reconnect/backpressure policy, or a 1080p60 encoder path.tools/threadprobe.c— standalone ARM diagnostic (make threadprobe, scp, run as root, delete): spawns under the app's uid untilpthread_createrefuses. Measured 2026-07-28 — 2 MB stacks die at 2043 threads onRLIMIT_AS(the full AArch32 4 GB), 256 KB stacks at 3745 onRLIMIT_NPROC(3746), both EAGAIN, against the app's 31 threads at playback peak. Which limit binds depends on the stack size; that is whytask::spawn_smalluses 256 KB.docs/lab-diagnostics.md— the Cloud Lab bridge, end to end: diagnostics, authenticated long-poll commands, topology through the router, wire formats, redaction, pinning, receiver hardening, theLAB=1loop, the measured colour-key table, and — §11 — exactly what has been proven on the host and what still needs hardware.docs/dolby-vision.md— Dolby Vision + Dolby Atmos, end to end: what ships per profile, the two Load-payload nodes and the binaries they were recovered from, the ACB Atmos forward and theSOUND_ERROR_019rule it retired, the Profile 5 one-tick stutter with the six hypotheses that were wrong first, the three instruments that were silent by construction, and what the Dolby specifications do and do not require (with page citations). Read it before touchingDovi::presentation,with_dolby_hdr_info,with_immersive,acb_send_atmosorpts_nudge_ns.docs/two-installs.md— why two builds live on one television and what they do and do not share: theFLAVORaxis and its seven query targets, the identity model (the app id is the install DIRECTORY's name, read from/proc/self/exe, so nothing about it reaches codegen), the shared-resource inventory (separate: runtime root and everything in it, session file, plex.tv device name, launcher tile, the Load payload'soption.appIdand the ACB id — still shared: the jail template, the ONE video plane,/media/developer,splash.png, therequiredMemorybudget), the two name traps, and the ordered list of what only a television can settle. Read it before adding anything per-install, and before assuming a log came from the install you meant.docs/pms-api.md— verified PMS REST reference (sections, hubs, metadata, image transcode, direct-play URLs, timeline). The authoritative spec for the data layer.docs/buffer-feed-plan.md— historical design note for the buffer-feed pivot (partly outdated).
-
This repository is PUBLIC, and some of the data in this working copy is not the maintainer's to publish. Several paths are gitignored for that reason —
.tv-host,.tv-mac,src/config.local.h(a live Plex token),tests/manifest.local.jsonandpkg/auth.jsonamong them — and the per-user~/.config/plxnative/tv-host/tv-mac(outside every checkout, so not gitignored, but the same values and guarded the same way:USER_TV_FILESin the hook,PRIVATE_NAMESinci/source_bundle.py); the LIST isPRIVATE_FILESin.claude/hooks/outbound-guard.py, not this sentence, which is why no count is given here. The rule for anything leaving the machine is placeholders, always — a PR body, an issue comment, a release note, a commit message — anddocs/shared-servers.mdcarries the stand-in table this repo actually uses. It has already failed once as a convention, in these words. A batch of subagents told to write device recipes "executable without me" each did the obviously helpful thing and pasted a friend's real server address, port,machineIdentifierand handle into four PR bodies (#28-31) on 2026-08-14. All four were redacted; GitHub keeps PR-body edit history, so those values are permanently public, and they were the FRIEND's rather than this project's to give. Since then aPreToolUsehook (.claude/hooks/outbound-guard.py) refuses any publishing command whose text carries one of those values — including a heredoc body and a--body-file, which are how a PR body of any length is actually passed. It never prints the value it matched, since that is the same leak by a shorter route. The escape hatch is a prefix on the command, and an agent reaching for it is doing the thing the hook exists to prevent. -
LG's SDL fork has a shifted
SDL_KeyboardEvent.e.key.keysymis unreliable; the handler (rust-modules/shell-sdl/src/event.rs, viard_u32) reads raw bytes off the event:+16= state (u32),+20= webOS keycode (u32),+24= sym (u32). State low byte = pressed(1)/released(0); bit0x100= auto-repeat. Magic-Remote buttons are matched by thesewcodes (e.g. PAUSE=72, PLAY=450, BACK=461/482, stop=413, D-pad L/R alt 412/417; the wcodes live inui/consts.rs, asWCODE_*— true of the L/R pair only since 2026-08-15, when it was named; until then it was five bare literals inapp.rsand this sentence was false. One literal is left, and deliberately: BACK's secondary 461 is written out insideis_back, inconsts.rsitself, beside the constant and the comment explaining it). Preserve this raw-offset reading if you touch input. -
Starfish/ACB ABI + bind-order rules (the C++-from-C mangled-symbol seam,
Loadwithuid=NULL, the exact ACB bind sequence, buffer-feed sourceInfo-verbatim (PQ VP9 is rewritten to HDR10; the developer URI ACB fixture uses a separate experimental descriptor), never feed audio to ACB, the 3-arg taskId ABI) — moved torust-modules/media/src/player/CLAUDE.md; read it before touching playback orsrc/starfish.c. -
Wayland transparency (
system.rs): the UI surface is forced to a 32-bit RGBA config and made non-opaque by driving the wayland proxy directly (wl_proxy_marshal(surface, 4, NULL)= set_opaque_region NULL), re-asserted each frame while playing, so the video plane shows through. The dev TV reports SDL 2.0.5 (no transparency hint).sys_grab_waylandover-allocates theSDL_SysWMinfobuffer because the fork writes a larger struct than the headers declare. Background notifications revoke the borrowed Wayland handles and block presentation, including idle keepalives and queued uploads. DID foreground reacquires the handles and invalidates the UI before rendering resumes. A failed or non-Wayland query leaves both handles null. -
The compositor multiplies our surface by its alpha, so the frame over the bound video plane is straightened (
rust-modules/gfx/src/gfx/straighten.rs, the module doc has the measurement, the buffer-age argument and the cost). The framebuffer holds PREMULTIPLIED colour over the player's transparent clear; the platform composites it asui.rgb * ui.a + video * (1 - ui.a). So the frame's last draw on a frame that drew anything whilePlayer::video_plane_boundisrgb / a(alpha unchanged, blending off) over the boxes of the surface the frame drew into and nowhere else (every draw call in gfx declares its extent,Extent; a draw with none is the whole surface; at most 16 disjoint boxes, because a pixel two quads cover would be divided twice), in place throughGL_ARM_shader_framebuffer_fetch/GL_EXT_shader_framebuffer_fetchand through a copy of the frame when the driver has neither (the simulator):present_and_swapcalls it after the dev capture's read and before the swap. A bound frame must therefore stay a COMPLETE redraw from a clear: nothing may blend premultiplied colour over pixels a buffer kept. The simulator stands in for the compositor (draw_under, straight alpha, over the decoded picture or black) on those frames. The boot log'sstraighten:line says which program the device took. -
Deploy uses a tmp+mv dance (
plxnative.new→mv) so scp succeeds while the old binary is still executing (avoidsETXTBSY). The TV drops to standby after a few idle minutes, so a deploy can die mid-scp — when scripting aroundmake deploy, md5-compare local vs on-TV binary after (and wake the TV with WoL first). -
Text/icon crispness contract: all 1:1-texel content (glyph strings, icon masks) snaps its composited origin to whole pixels via
gfx::snap(a fractional origin + GL_LINEAR smears strokes), and fonts open with FreeType light hinting (text.rs::font_at— the default NORMAL hinting lets Arial's bytecode round horizontal bars up a pixel, inverting stem/bar weights). Never snap scaled content (posters). Full rationale: the "Rasterization contract" note above the size ladder ingfx/tokens.rs(theme::sizere-exports it); after a font swap re-verify withtools/font-hint-audit.py(host-side, freetype-py). -
SAM keeps stale "running" state after a hard kill, so a launch is a silent no-op relaunch unless you close-first —
make run/killdo thecloseByAppIdfirst (andluna-send -imust stay subscribed for the launch to take). -
App-switch lifecycle (was a black-screen bug), handled in
app/run.rs(the0x103–0x106arms of the frame loop): the TV sends SDL app events —0x103/0x104(will/did enter background) and0x105/0x106(will/did enter foreground). On background during playback the loop suspends the buffer-feed (preserving the session) and PARKS the page stack:Dispatcher::suspend, which sendsScreenEvent::Suspenddown every mounted body and moves nothing. It used to drop to Home and that was a bug, fixed by restructure phase 12 (D1): writingroute = Hometurned into aRoot(Home)that RETIRED the player entry and the page it was launched from, so0x106minted a fresh player over a stack that was now just Home. Nothing noticed while the two things that would have — the playback session and the player's return target — lived outside the tree; the return target is anEntryIdon the page beneath the player now, so destroying entries destroys the way back. Consequence when reading a log: the heartbeat reportsroute=playerwhile the app is backgrounded, notroute=home. On foreground0x106it un-parks (Dispatcher::resume, called on both edges because it is idempotent and webOS promises nothing about their order); the player is still the top entry, because the park moved nothing, so theshow_page(Player)beside the reload is ordinarily a no-op and is written out only so that a foreground finding the player gone puts it back rather than resuming a session with nothing on screen. It then tracks one exact Load attempt at a time, follows reducer-approved superseding or rollback attempts, retries an exact failure without repeating route preparation, and issues the clock's native Play only afterStarted(a Playing restore over a standing pause publishes the viewer's resume BEFORE the Load, so the Load is not armed under it). In-app Home/Settings are overlays and do not fire these — only a real OS app-switch does. Preserve the suspend/reload pairing if you touch playback or routing. -
Crash forensics has two layers. With error-report consent and a compiled Sentry endpoint, Sentry Native's patched ARM32 backend replaces the signal disposition and wakes the shipped
sentry-crashdaemon. The dying process stays stopped while the daemon copies itsucontextand walks the crashed thread's APCS frame chain out of a copy of its stack; for every other Linux LWP in/proc/<pid>/taskitPTRACE_ATTACHes, unwinds remotely through libunwind's ptrace accessors (DWARF, withfunctionnames from the ELF symbol tables), and detaches — that is upstream sentry-native's own machinery since 0.16 (#1747), and it replaced a hand-written suspend/PTRACE_GETREGS/frame-walk block this repo carried against 0.13.9 until 2026-09-02. The crashed thread keeps up to 128 frames and each other thread up to 32 to reduce pressure on the 256 KiB durable-record ceiling; the importer still rejects an oversized envelope rather than claiming a bound for an arbitrary 256-LWP process. The JSON therefore carries ARM registers and real multi-frame stacks for all successfully captured threads, plus modules and both Linux-kernel and webOS firmware context. The pin is the Sentry Native entry inci/dependencies.json. The ARM32 registers-in-the-event and dual-frame-record walk (GCC leavesfpon the LR slot ([fp-4]/[fp]), rustc/LLVM on the saved-fp slot ([fp]/[fp+4]), and one process here holds both) and the pointer-width stack reads that make the walk safe on a 32-bit target are now upstream (getsentry/sentry-native#2052 and #2053, contributed from this repo, merged 2026-09-03/04, released in 0.16.6) — the patch beside the pin (ci/patches/sentry-native-0001-webos-arm32.patch) carries neither any more and is down to what upstream still does not do: aprocess_vm_readvwrapper for glibc 2.12, the 32-frame cap for non-crashed threads, the 30 s handler budget, and two webOS-only escapes in the signal handler (no in-process libunwind, no SDK hooks — both reproduced a recursive SIGSEGV throughgetenv). The SDK has no HTTP transport and writes no minidump: it launches the sameplxnativebinary in spool-only mode, which moves the bounded envelope into the install's runtime root. A healthy launch strips path prefixes, rejects request scope and everyuserfield butid— which it keeps ONLY when it has the 32-hex shape of the app's own crash-report identifier, theerrors_idthatsdk::startputs on the SDK scope asuser.idright after init so the daemon's base event carries it — and queues the event through the existing consent-aware sender. That id is what makes Sentry's "users affected" a count of Crash report IDs — one per uninterrupted opt-in — rather than of events; it is minted on crash-report opt-in, destroyed on withdrawal and on sign-out (the decision belongs to the account that gave it, so the next account is asked afresh), and never the PostHog analytics id (docs/../PRIVACY.md, and the two-identifier note intelemetry/consent.rs).-fno-omit-frame-pointer/ Rustforce-frame-pointers=yesare therefore crash-reporting ABI, not optional debug flags.The patched ARM handler waits up to 30 seconds for that walk. The upstream 10-second budget was too short for the first cold crash on this Cortex-A9: the parent died while the daemon was still opening
/proc/<pid>/maps, producing an accepted envelope with no modules and therefore no symbolication. Warm crashes usually finish within the original budget; the longer ceiling is a failure bound, not an added delay after a completed report.The always-armed fallback is still the C tracer (
main.c). It writes a startupimg:marker (build id, load address, mapped size), then on a fault logs PC/LR, the ARM registers around them and the/proc/self/mapsline(s) containing either. Native always chains this saved handler after the daemon's attempt (and immediately when the daemon is unavailable), so the bounded local record survives even a daemon that reachesDONEafter failing to write its envelope. On the next healthy boot the native envelope is imported first; a matching local record is consumed by build id + signal, so one process death still becomes one Sentry event. Closing or withdrawing consent restores the tracer as the primary handler. It re-raises toSIG_DFLso SAM sees a real signal death (exit_status: 11for a SIGSEGV — device-verified 2026-08-29). This fallback does NOT also get a system crashd backtrace, and this line used to say it did:core_patternon this firmware is the bare stringcore, so the report chain starts from a core FILE, andsetrlimit(RLIMIT_CORE, 0)means none is written. Two deliberate SIGSEGVs produced the signal status and no/var/log/reports/librdx/entry. Suppressing cores stays right — 615.6 MB shared partition, 125.9 MB free, ~200 MB core — so the two are simply exclusive, and the fallback evidence is its own fault event plus SAM's status. Call that local C record a fault event, not a backtrace —backtrace()is not async-signal-safe and ARM unwinding in the crashing process commonly stops atgsignal(), so two frames plus registers plus the faulting module is the honest ceiling. Two things about it were broken until 2026-08-29 and neither was visible in a log — and the first of them had been written down and left undone for five weeks, as finding C3 ofdocs/architecture-review-2026-07-26.md, which named the same six unsafe calls and prescribed the same fix ("usewrite(2)into a pre-opened fd with a preformatted buffer"). It was filed medium / Wave 1. Worth knowing when reading either: only the SECOND was a discovery. (1) The handler was not async-signal-safe: it calledfprintf/fopen/fgets/sscanf/fclose, none of which is on POSIX's list, so a fault inside the allocator or while another thread held a stdio lock could have deadlocked or refaulted and lost the report — in the crash class most worth having one for. It is nowopen/read/writeand hand-rolled formatting, with both descriptors opened beforesigactionarms it. (2) THE RE-RAISE DID NOT RE-RAISE, from the day it was added (2026-07-09) until then, so every sentence anywhere in this repo claiming crashd captured a backtrace for this app was FALSE for seven weeks.sigactionwithoutSA_NODEFERmasks the signal for the duration of its own handler, soraise(sig)only marked it pending, returned 0, and fell through to the_exit(128 + sig)beneath it — commented "only reached if raise() somehow returns", and reached every single time. The result was a CLEAN EXIT: no core, no/var/log/reports/librdx/report, andWIFEXITEDrather thanWIFSIGNALEDfor SAM. The commit that introduced it was fixing this same failure in an earlier form (a bare_exit(3)) and swapped one clean exit for a more plausible-looking one. The fix is asigprocmask(SIG_UNBLOCK)before theraise. Consequence for anyone reading an OLD device log: a SAMexit_statusof 35584 (139 << 8) is a SIGSEGV, not an exit — and there will be no crashd report beside it to find. The PURE half (record formatting, and deciding what a maps line means) lives insrc/crashfmt.hso thatmake checkcan compile and RUN it on the Mac —ci/crashfmt-test.c, which is where the parsing bugs of this tracer have historically been, and which on being written by watching it fail disproved a justificationmain.chad carried since the tracer existed. Two logs, both in the install's runtime root (/tmp, or/tmp/<app id>for a flavoured install):plxnative-events.logis truncated each launch;plxnative-crash.logis append-only and survives the relaunch — read it after a crash+restart. Note pmlog's wall clock is ~3h skewed on this TV, so correlate by monotonicSDL_GetTickstimestamps (and the SAMexit_status), not pmlog time. -
Storage diagnostics: every flavour publishes
plxnative-diag.login its runtime root. This is a schema-versioned, at-most-16-KiB snapshot, atomically replaced at mode 0640; events, crash and stderr are 0640 too (owner rw, the app's group r, never world-readable —src/main.c'sopen_fd_logandeventlog::open_log_append; they were 0600 until 2026-10-04, and a Developer Mode user on an unrooted set could not fetch them with webOS Dev Manager at that mode;docs/distribution.md§4 and §6.9 hold the reasoning and the residual risk). It contains build/uid/gid identity, supplementary groups, fixed-label directory probes, activation status and the latest helper stage outcome. Activation is only the best-effort LS2 wake hint:activation-rejected,activation-timeoutor an activation setup stage does not mean storage failed whenhelper stage=complete; the authenticated helper transaction is authoritative. Probe files are hidden, exclusive creates, one byte, immediately removed; session files are never opened by diagnostics. No paths, helper payloads, account data or raw error text enter this file or telemetry. A dedicated worker retains boot evidence and suppresses semantically duplicate outcomes.truncated value=truemarks a size cap;history_truncated=truemarks a bounded helper-outcome history. A failed publication leaves the previous snapshot in place, so check the build identity and sequence when interpreting a file after a relaunch. The group-read bit only helps a shell sharing the file's actual gid; the snapshot does not claim universal SSH access.identity schema=1 seq=2 app_id=com.beb.plxnative flavour=stable version=0.6.0 uid=6303 euid=6303 gid=5000 egid=5000 groups values=29,44,505,509,777,5000 errno=0 truncated=false dir label=tmp uid=0 gid=0 mode=1777 readonly=false open_errno=0 stat_errno=0 mount_errno=0 create_errno=0 write_errno=0 close_errno=0 unlink_errno=0 dir label=runtime uid=6303 gid=5000 mode=0700 readonly=false open_errno=0 stat_errno=0 mount_errno=0 create_errno=0 write_errno=0 close_errno=0 unlink_errno=0 activation stage=activation-rejected error_code=-1 elapsed_ms=19 helper stage=complete errno=- code=- start_timeout=false activation_stage=- activation_error_code=- reported_stage=- reported_code=- wire_code=- attempts=1 elapsed_ms=31 history_truncated=false history stage=complete errno=- code=- start_timeout=false activation_stage=- activation_error_code=- reported_stage=- reported_code=- wire_code=- truncated value=false -
The app's own files are located at RUNTIME (
paths.rs), never by literal. webOS picks one of two install prefixes —/media/developer/apps/…(Developer Mode) or/media/cryptofs/apps/…(Homebrew Channel) — and the two jail profiles disagree about which directories are WRITABLE:jail_native_devmode.confmounts/media/developerrw and/media/internalro, andjail_native.confdoes the opposite with no/media/developerat all. Resolve viaread_link("/proc/self/exe"), not$HOME(LG's conf sets HOME twice and which wins differs by profile). The session file is a probed SEARCH ORDER for the same reason. Both failures were silent before: fonts fell through to DroidSans whileinit_textstill loggedok=1, and the session write dropped ENOENT into a best-effort save. Both now log loudly. -
Three resolutions, and they are not the same number. The UI is authored at a fixed logical
1920x1080(SCR_W/SCR_H) and the video track is full-panel1920x1080. The drawable — what GL renders into — is read back at boot byrust-modules/base/src/surface.rsand is whatglViewportuses; it is 1920x1080 1:1 unless a webOS 1-3 owner picks a smaller Interface resolution (Settings > System, applied at the next launch; the row and the boot read are webOS 1-3 only) or the debug drawable trigger asks for one, in which casesurface::scale()is below 1.0 and the compositor fills the panel. The debug-only boot trigger/tmp/plxnative-drawable=<W>x<H>(bounded 640x360..=1920x1080) asks for a size directly and outranks the setting. The panel is a third number entirely:SDL_webOSGetPanelResolutionreports3840x2160on the dev TV, whose UI surface is 1080p. It is a diagnostic — never a layout input, since sizing the UI from it renders a 4K interface into a 1080p buffer. The boot log prints all three on onesurface:line. Do not render at panel resolution even if a set offers it: 4x the fill rate through shaders that needed work to reach 60 fps at 1080p, versus a free hardware upscale.
Two skills sit on top of this section; reach for them before reading it end to end.
which-tier decides which tier a given change actually needs and — the half that gets skipped
— which tiers are structurally blind to it, routing by what the change touched. This section
documents what each tier IS; that skill decides which to run. doc-claim-auditor (a subagent)
answers the other post-change question: did this change make any claim in the prose FALSE. That one
exists because nothing compiles this Markdown, which is why the paragraph below has to open by telling
you its own numbers are wrong.
FIXING A REPORTED BUG STARTS WITH A TEST THAT REPRODUCES WHAT WAS REPORTED, AND YOU MUST WATCH IT FAIL.
The first artifact is not the fix. It is a failing test that reproduces the SYMPTOM AS DESCRIBED — the maintainer's own words, their scenario, their sequence — and you have to see it red against the broken build before you touch anything. A test written after the fix and green on the first run is evidence about nothing: it proves the code does what it now does.
This is not a style preference; it has already failed here in exactly the way it always fails. On 2026-08-29 a client-side bug killed a playback after a seek. The fix was landed first and the regression case written after it, and the case was green on the television — so it looked done. Replayed against the log of the BROKEN build, that case scored five green assertions out of five on a run that died with
HLS segment was not produced in time. Two separate reasons, both of which generalise: the globaltimeline_climbcounted the seek DISCONTINUITY as 313 s of progress, andno_playing_errorgreps the Starfish error surface, which a death on the acquisition side never reaches. It tookno_demux_failureplus a post-target progress floor (min_climb_after_s) to make the case discriminate — and only the replay against the broken log could have shown that, because on the fixed build every version of the case looks identical.So, in order: reproduce → watch it fail → fix → watch it pass → keep the failing artifact. Two rules fall out of it.
- A test you cannot run against the broken code is not yet evidence. Sometimes the fix changes the signature the test calls (it did here:
primelost itsgenerationparameter, so the unit test cannot compile against the old code). Then simulate the defect narrowly, watch the test go red, and say in the commit that the red was simulated rather than historical — it is a weaker claim and must not be reported as the stronger one.- Keep the broken run's log. It is the only thing that can answer "would this test have caught it", and that question cannot be asked of a fixed build at all. Replaying a case's real assertions over a saved failing log costs seconds (
run.evaluate(case, lines)off a savedplxnative-events.log) and is the cheapest audit in this repo.The host simulator makes the whole loop cheap and takes no television:
tools/abr-scenario.shbuilds and runs one scenario end to end, so an A/B of two builds over one scenario is minutes, not a device session.
Check the rendering path as well as the picture. PR #161's sign-in cards looked complete in
a simulator whose frame cache: CopyTexSubImage error=0x500 — cache off log meant it never
exercised cached modal ground. ui/popover_host_tests.rs now runs the production host-cache
protocol with CPU framebuffer copies: a newly captured ground must not be replayed over an
embedded alert's foreground by a later container scope. Those tests prove draw order and freeze
behaviour; real GL copies, glyphs and presentation still need a device capture with caching enabled.
There is exactly one dev set, one app instance on it, and webOS enforces nothing: two
tests/run.pyruns, or a run plus amake deploy, or a capture session plus either, kill each other's app. The damage is not a clean failure — it is plausible wrong data: bogustimeline_climbfailures, an fps number measured while somebody else's binary was being deployed underneath, a capture of a screen the other job navigated away from. You cannot tell those from a real regression by looking at them.Since 2026-08-22 there IS a lock, and it is enforced.
tools/tv-lock.shholds a lease in a directory ON THE TELEVISION (/tmp/plx-tv.lock, so it spans worktrees and machines, and outside theplxnative-*prefix so it neither tripsdev::any_trigger_presentnor gets swept by a teardown). Thetv-lockskill is the workflow — acquiring and queueing, what the lock CANNOT see (a job started from a checkout without these tools, and a human watching television) and the pre-flight that partly makes up for it:fuserper install, an ssh count, and an IDLE / IN USE / UNKNOWN verdict from the foreground app, and when a lease is safe to break. AnIN USE:line fromacquireorstatusis a warning to stop and tell the owner;tv-lock.sh withandtests/run.pyrefuse to start on it unlessPLX_TV_IN_USE_OK=1(only after the owner said go).You cannot skip it.
tv-session.sh(up/key/click/shot/down),make deploy/run/run-stream/kill/install/uninstall,tests/run.pyandtools/capture-screen.shall take it, and aPreToolUsehook (.claude/hooks/tv-lock-guard.py) refuses any Bash command that reaches the set without a lease — including a rawssh root@…, anscpinto the app directory and asshpassone-liner. Read-only diagnostics are deliberately not blocked:tv-session.sh log|status|fg,tools/crash-report.sh,make -s print-*, andtests/run.py --list(it returns before the lock, before any trigger is armed and before anything is deployed, so the guard treats it as a status read — since UI-restructure phase 11). With nobody holding the set a single command takes a short implicit lease rather than failing; a SESSION should take a real one, because the gap between two of your own commands is exactly where another lane lands.Running SEVERAL agents at once is a PLANNING problem, not a locking one, and it has its own skill:
fleet-plan. The lock schedules; it does not plan — two lanes that both want the set still run in series, and that queue is invisible in the plan you wrote. The one line to carry without opening it: the television is the scheduling constraint, a lane is a CHECKOUT (so a second worktree on the same Mac is a second lane, however the prompt describes it), give device access to at most one and send every other lane tomake sim-macosortools/sim.ps1. Telling two prompts "you own the television exclusively" is not a mutex — each is true when written and false the moment the second one starts, which is the 2026-08-21 collision that was caught by luck rather than by anything failing loudly. A subagent names which lane it is by prefixingPLX_TV_LOCK_LANE=<its worktree path>on the device commands it runs, not by exporting the variable once — the harness reports the SESSION's own checkout as a plain subagent'scwdregardless of which worktree the agent is actually in (only anisolation: worktreesubagent reports its own), sotools/tv-lock.sh(which already readsPLX_TV_LOCK_LANE) and thePreToolUseguard have to agree on the lane. The guard'sdecide()gives each device segment the first of: that prefix, the variable in the hook's own environment, the segment's absolutetools/ortests/script path (ormake -C <dir>), an absolutecd <dir>the shell certainly kept, thencwd's checkout; a lane read from a path or acdthat is not thecwd's own also needs the caller's session in the lease'sSESSIONS. The prefix is always correct and the one source for a relative script path or acd "$W"; a lane of its own per subagent is what lets several of them multiplex the one set through the lock, onetools/tv-lock.sh with --ttl N --wait S -- <one test>lease per test run.The skill carries the rest: the shared stash stack that hands one lane another lane's work, what a second build tree costs on disk, cutting a worktree from the right base, the gitignored files a lane has to be seeded with, the worker-prompt block, and the collision recovery — stop one job, re-run it from scratch, and treat anything measured during the overlap as contaminated whether or not it looks fine.
There is a host unit suite, and it is not the real gate — both halves matter, and conflating them is how this section used to be wrong in three files at once.
Tier 1 — make check (host). cd rust-modules && cargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_shell_sdl -p plx_owp (a bare cargo test --lib runs the application crate only and skips every layer crate: plx_base, plx_machine, plx_os, plx_gfx, plx_net, plx_ui, plx_plex, plx_telemetry, plx_data, plx_session, plx_media, plx_appkit, plx_screens, plx_shell_sdl) runs the whole
host suite on the dev Mac, no TV involved — and make check runs the crates that declare hostsim
(HOSTSIM_SUITE, a subset of that list) a SECOND time under --features hostsim, because the host
feed seam only exists there and the tests that need it are compiled out of the first pass (the build
section's paragraph on the two passes says which crates are left out and why). Treat every test COUNT in this section as
already wrong, including the one in this sentence. 386 measured 2026-08-13; 284 on 2026-08-02; a
documented 59 before that, which was five times stale before anyone noticed — and the first version
of this paragraph was stale within one commit, because two agents were adding tests to the same
batch that documented it. Three numbers have now rotted here, so do not add a fourth: the only
count worth having is the one you take yourself, with
cd rust-modules && cargo test --lib -p plxnative-modules -p plx_base -p plx_machine -p plx_os -p plx_gfx -p plx_net -p plx_ui -p plx_plex -p plx_telemetry -p plx_data -p plx_session -p plx_media -p plx_playback_contract -p plx_play_uri -p plx_play_feed -p plx_media_codecs -p plx_appkit -p plx_screens -p plx_shell_sdl -p plx_owp -- --list | grep -c ': test'. The per-module counts
below have the same disease and are worse, because a stale one reads as precise rather than round
— several were written when the module was a third its present size, and two bullets have now
outlived the file they named: ui/home.rs (retired to screens/home/) and route.rs (split in
phase 9 into route/plan.rs + route/decision.rs, below). Read those bullets as what each module covers,
which is stable and is why they are here, and never as a census. Run it with the same toolchain
the Makefile does. From the repository root a bare cargo test uses your default toolchain, while
make check uses cargo +$(RUST_TOOLCHAIN), the pin in rust-modules/rust-toolchain.toml (inside
rust-modules/ a bare cargo honours that file too, but cargo +x on the command line outranks it).
The two used to disagree — task.rs's refused-spawn test passed 284/284 on stable while panicking
inside std on nightly, which read as flakiness and was not — back when nightly shipped. One pinned
release now serves the ARM build and the host gates, so the pin is the gate. make check is that command plus make lint (three
named clippy lints, see the build section — the shadowed-branch gate, ~1s warm); it is deliberately
not a prerequisite of all, so an ordinary make still cross-compiles without ever invoking a
host toolchain run. Run it before make test — it is free by comparison, and it is the only signal
you get without waking a television. What it covers today, by module:
stream.rs(10) — socket semantics against real loopback sockets, plus response-header parsing:connect(2)giving up on its deadline (RFC 5737 TEST-NET black hole), a refused connect failing fast rather than reporting success, every failed open retiring its fd (asserted by counting/dev/fd),shutdown(2)waking a reader already blocked inrecv, the fd being claimable exactly once — and, since headers are parsed as bytes rather than strict UTF-8, that one non-UTF-8 byte cannot turn a good 200 into a transport failure, that a status line straddling the status offset is rejected rather than fatal, and that header names are found whatever their casing.remote.rs(3) — the remote-FIFO token framing: complete tokens fire while a partial trailing one is held over to the next drain, and a multi-byte whitespace separates tokens without panicking the tokenizer (the separator search is ASCII-only because the split that follows is by BYTE index). The FIFO is world-writable in/tmpand drained every frame on every boot, so a panic here unwinds out of the SDL loop and kills the app.ff.rs(11) — the pure demuxer logic: thenal_end32-bit bounds guard, AVCC→Annex-B conversion (keyframe detection, parameter-set prepending, truncation instead of panic), and the AVIO abort guards (a seek after teardown must not open a second connection — graded on an accept COUNT from a counting listener, not a return value).route/plan.rs(8) — direct-play vs transcode selection policy: track fallbacks, a real server pick and a show's language over the file's default, the flagged default, part-id parsing, mkv-only direct play.screens/home/tests.rs+ui/card_row.rs— focus/geometry/spring math: every strip element decoding to exactly one destination, row stepping staying inside the shelf array, the pointer hit column matching the drawn card at every snap phase, and the shelf heading's clearance behaviour frame by frame. (This bullet readui/home.rs(5) until that file was retired; the contracts moved to the owned screen with the screen — the ledger isdocs/measurements/home-legacy-contract-ledger.md.)metadata.rs(2) +browse.rs(2) — async landing/mailbox invariants: a detail or season response only installs while it is still the one being awaited (a failed/childrenmust not land as an empty season), andresetclearing the single-flight flags and retry backoff.task.rs(3) — threading invariants: a refused spawn is a return value not a panic, and theMainThreadtoken cannot cross a spawn (an absent!Sendimpl is invisible to ordinary code, so it is detected via inherent-vs-trait const resolution, with aSendcontrol case).
Three structural limits, all deliberate and all worth knowing before you trust a green run.
(1) It cannot run the native libraries, and it no longer fails by FAILING TO LINK. ff.rs
used to carry four cfg_attr(not(test))-gated #[link] directives, so a host test that called
FFmpeg died at link time; those directives are gone (everything goes through dynlib! now), the
crate links unconditionally, and such a test instead takes dlopen's None branch on Darwin.
Same boundary, quieter failure — a test that "passes" having never entered FFmpeg or GL is the
shape to watch for. (2) It runs on Darwin; the app runs on Linux, and they disagree
— see tools/sockprobe.c above, where shutdown-during-connect behaves oppositely on the two
kernels. A socket assertion that passes here is evidence about macOS, not about the TV.
(3) Some app async seams remain process-wide, so some tests are serialized rather than parallel:
metadata.rs's test that drives set_current_for_test still takes
plx_base::testlock::serial() (one lock per test binary: plx_data's tests and the application's each have their own) — not because its own state is global any more (MetadataState and
MetadataAdapter, detail and season mailboxes included, are per-owner fields now, like the other
five stores), but because set_current_for_test's assert_held enforces the SAME
lock the genuinely-still-global seams (route's play mailbox, the Feed backend's FEED_SHARED block) also
take, and the convention is one lock, not one per module. Browse, Hubs, Metadata, Person, Search
and ViewState are all owned now: a production Bridge owns each store's state, adapters and
notices, so separate owners share neither state nor landings; their fixtures use explicit
Stores owners. Those locks are load-bearing for the remaining globals, not incidental
— hold one for anything that touches the shared registry, compatibility state or the app frame.
Since 2026-09-10 the lock also records WHICH THREAD holds it, and the stores ASSERT it. A
mutex nobody is obliged to take is a convention, and a convention broken by one test in two
thousand does not fail — it hands some other module's test a wiped store, at a rate that reads
as flakiness. Browse's owned reset path (BrowseCmd::Reset), plex::servers::reset_for_test
and the whole app frame
(app::bridge::frame_with_results, which drains the aggregate notices and pumps every store)
call testlock::assert_held, so an unguarded write is now a deterministic panic in
the culprit rather than an intermittent failure in a bystander. That is how
app::chrome::four_libraries_on_two_servers_publish_two_type_destinations was finally
attributed: it lost both library destinations about one full-suite run in six, and the cause was
three app::heartbeat_word_tests cases that took no lock and derived their word alphabet by
running real frames — whose Browse owner reaches sync_roster, which resets that owner's table
on any source the live registry does not hold, i.e. on every Browse fixture in the suite.
Tier 1.5 — the desktop simulator (make sim-macos or tools/sim.ps1), which DOES draw pixels
on the host. This tier
did not exist before 2026-08-14, and the line below used to read "there is no host runtime" flatly
— that is now wrong for the UI half and right for everything else. plxnative-sim is the same app
core built with --features hostsim and linked against desktop SDL2 + desktop GL 4.1 core: it
renders the real interface against a real PMS, boots to a screen with the same plxnative-*
triggers, is driven by the same remote-FIFO tokens, and screenshots itself. The
ui-sim skill is the loop. It exists because the TV is a mutex — one set, one app instance, two
harness jobs kill each other — while N simulators run side by side, each pointed at its own
instance root (PLXNATIVE_RUNTIME_DIR, which is where the triggers, FIFO and event log now come
from; unset it and everything resolves to /tmp exactly as before). It answers layout, focus,
navigation, every screen, and the whole Plex data layer.
On macOS, since 2026-08-28 it STREAMS — real HTTP, real demux, real HLS, the real adaptive
controller. make sim-macos builds a HOST copy of the same bundled FFmpeg 9.0 from the same
ci/build-ffmpeg.sh component list (HOST=1, into vendor/ffmpeg-prefix-host, staged into
pkg/ as libavformat-plx.63.dylib beside the ARM .so.63), and media-codecs/src/ffi.rs carries a second ABI
table selected on target_pointer_width with ci/ffabi-assert.c holding both. Arm
plxnative-clocksink (play-feed/src/ffi_host.rs — AUs accepted and discarded, a presentation clock
clamped to the last fed PTS, position reported at the television's measured 5 Hz) and the whole
pipeline between the socket and the decoder runs on the Mac: both AVIO transports, ff.rs's
demux, the AU queues and their byte-cap backpressure, the feed-ahead throttle, rung transactions,
seek. The Windows sim-wsl target deliberately omits FFmpeg and stops at the host no-video seam.
Measured the day the macOS path landed: 94 abr: lines and a rung commit in one 30 s host run against
tests/serve_fixtures.py. Until then this half was device-only and make sim-macos said so
(ff: FFmpeg unavailable — the app runs, playback will refuse), which is why the ABR work was
pinned to the one-television mutex.
It still CANNOT answer frame rate (different
GPU — every simulator heartbeat carries sim=1 so a pasted log cannot be mistaken for a
device measurement), text rasterization, the cached modal ground (its frame cache is off —
frame cache: … cache off), or anything about LG's decoder — resource-allocation
refusals, the ACB video-plane bind, the Load payload's Dolby declaration, SOUND_ERROR_019, frame
pacing, which codecs the panel takes. Nothing decodes: the clock sink throws every AU away, and a
Mac decodes things that television will not and the reverse. Without the trigger, Play still lands
on the real failure read-out, which is what the UI work wants to see.
Bugs it has already found in DEVICE code: the glyph upload
ignored SDL_Surface::pitch (text.rs), dev/remote/log all hardcoded /tmp, and — from
deriving the ABI table at a second pointer width — AVSubtitleRect was modelled with flags
last where the header puts it before type, so type_ read flags and on 64-bit flags landed
one word past the end of the struct.
Two macOS-host traps that read as your change being broken. (1) make sim-macos-shot HANGS on a
settled screen — SIM_FRAME is a count of presented frames (shot.rs, and app.rs says the
same at the shot token: "presented frames only accrue when something repaints"), and plx_machine::idle
gates presents, so a screen that settles before frame N never reaches N. Arm
plxnative-noidle in the instance root first; three agents lost time to this in one day. (2) macOS
libSDL2 is sdl2-compat forwarding into SDL3, so pushing a synthetic SDL_TEXTINPUT through
SDL_PushEvent SIGSEGVs inside SDL — SDL3's text event carries a char *text where SDL2 carries
an inline char[32], and the shim dereferences it. No Rust panic, no log line, the process is just
gone. The remote FIFO's key and ck: tokens are safe because every field they set is a scalar; see
docs/search.md §3.
Tier 2 — the device, which is still the real gate. Nothing on the host decodes a frame or talks
to Starfish/ACB, so playback correctness — and every pixel-level and perf question — is only
observable as behavior on the TV. Wake the TV first (wake-tv skill) — asleep, every assertion
fails as "no line found", which reads exactly like a total regression. The panel rule (the
owner's standing directive, amended 2026-10-24): the sound is OFF (muted) for EVERY device run,
and the panel is OFF by default for every device run, --fps* and profile-tv included (the set
is in a living room). The panel is only the backlight: turnOffScreen darkens the picture and the
app keeps presenting at full rate. Nothing in the app reads the panel state (a search of
rust-modules/ and src/ for tvpower, turnOffScreen, screenOn and getPowerState finds no app
code), and plx_machine::idle gates presents on the UI's own changes ("nothing on screen changed, so
don't repaint it"), not on the physical panel. The owner on 2026-10-24: "This is just a backlight …
keep the screen off". Measured that day on the dev TV (Home grid-pong fps scene, release build):
panel OFF gave 73 presented frames per cycle at 59.9 fps and 9 missed refreshes in cycles 2-60;
panel ON controls gave 73 frames per cycle at 59.6-59.9 fps and 8, 13 and 14 misses, so the panel
state changes neither pacing nor misses. tests/run.py --fps --mock therefore asserts screen off
before every scene (--panel on lights it for a run someone wants to watch). This replaces the
2026-10 form ("ON for every smoothness / fps run, because a dark panel lets plx_machine::idle hold
presents back"), which that measurement contradicts, and the 2026-09-07 form before it ("panel OFF for fps
too, rendering continues with the LCD off"), which named the same-session screen-on vs screen-off
fps= comparison as owed — the 2026-10-24 measurement is that comparison. Capture with the panel
off: shot (the DISPLAY compositor read) is on record as working: docs/measurements/ tv-session-7-2026-09-10.md ran screen off first and got a 1920x1080 DISPLAY capture with real
pixel values (opener p95 246.9 against a row-mate's 167.0), and docs/measurements/ library-all-types-and-fps-2026-09-26.md checked native captures with the panel off. Not on
record: the live capture stream (/tmp/plxnative-capture, the app's own GLES frames) with the
panel off; check its first frame instead of assuming either way. The command is tools/tv-session.sh screen off|on (a PANEL state, not an app state —
the app keeps running and playback keeps decoding). The sound half is now the same shape of
command: tools/tv-session.sh sound off|on|status calls com.webos.service.audio/setMuted and
reads getVolume back to confirm — this is the sanctioned path, so no lane needs
PLX_TV_LOCK_BYPASS to mute the television. The two luna calls were exercised by hand on the set
(2026-09-19); the subcommand wrapping them is host-tested only and still owes a first device run.
The tv-session skill is
the bring-up/observe/drive loop; profile-tv handles a live but slow or stuck process and the
three-layer graphics profile; crash-triage handles a death; bind-tv-lib-abi covers new
FFI into the TV's own libraries. ./tests/run.py needs a gitignored tests/manifest.local.json
— manifest.json holds only the installation-INDEPENDENT case definitions, and each case names the
SHAPE of item it needs (item: "movie_h264_ac3_1080p"); the overlay maps that to a ratingKey on
this server and supplies the PMS host, TV address and test user. Copy
tests/manifest.local.json.example and fill it in; the runner refuses to start without the FILE, and
without pms.host / tv / test_user.id. An item key it cannot resolve is a SKIP, not a
death (since 2026-08-22) — absent or left as the example's <ratingKey>, it skips the cases and
fps scenes naming it, prints the reason in the summary and in --list, and runs the rest. The
matrix is a SUPERSET of what any one library holds (it names 4K DoVi P8, TrueHD, PGS, AV1-with-no-
DP-audio), so before that change the suite ran for exactly one library in the world; one ordinary
h264/ac3 movie now gets a stranger every playback case and fps scene naming that shape or no item
at all — count it with ./tests/run.py --list, never from here. Consequence when
reading a result: the pass count is meaningless without the skip count beside it — 16 passed
can mean sixteen of the shapes that installation happens to own. Resolution happens once at load and
writes rk back for the resolvable ones, so everything downstream still reads case["rk"]; a
skipped case has NO rk at all and is partitioned out in main() before anything subscripts it.
tests/test_harness.py (in make check) pins that partition, because the maintainer's own overlay
resolves every key and so never enters the path. The full on-device suite is ./tests/run.py
(count it with --list --server, never from here; --fps for the perf gates), and make test = deploy + run.
Tier 2 is TWO SUITES on one television, and since 2026-08-22 the DEFAULT IS THE SYNTHETIC ONE.
A bare ./tests/run.py now runs the SYNTHETIC tier (generated clips, no Plex — take the count
yourself with ./tests/run.py --list, which is the only census that cannot rot; the number written
here went stale inside the branch that wrote it, in one commit); the
library-backed cases everything above describes are ./tests/run.py --server, and --fps /
--fps-player imply --server (not with --mock, which refuses --server and runs the scenes against tests/mock_pms.py) because those scenes navigate a real signed-in Home. --pipeline
still parses (it names the default); pairing it with --server/--fps is refused rather than
silently resolved. The inversion is about what the obvious command should mean: the default has to
be the thing that runs for everybody, needs no credentials, touches nobody's watch history, and
answers "is the PLAYER broken" — charging a PMS, a token and a filled-in overlay for typing
./tests/run.py meant most people could not type it at all. Never ship on the default alone
(what it cannot see is three paragraphs down). The server tier is still the right shape for what it
grades — SELECTION: /decision, direct-play vs transcode, track menus from PMS metadata, markers,
resume, the /:/timeline reporter — which is also why it needs somebody's library.
The synthetic tier is the PLAYER PIPELINE, with no Plex anywhere. A generated clip (make fixtures-pipeline, ~0.9 GB flat in
$FIXTURES_OUT/pipeline) is served off the dev Mac by tests/serve_fixtures.py and played through
/tmp/plxnative-playurl, one JSON object carrying the URL and the Load payload declaration.
It needs a TV address and nothing else — no token, no ratingKey, no manifest.local.json, no
sharing — so it is the only tier a stranger can run, and it is what separates "the player is
broken" from "the library layer is broken" when a server case fails. What it covers, precisely:
the player feeds {h264,hevc} (plus av1 / vp9 on a set whose codec table lists that decoder's row) × {aac,ac3,eac3,dts} (plus flac, alac and pcm, decoded in the app and fed as PCM) in mkv/mp4/m4v. Auto intersects this
software set with the device table, per-codec channel ceilings and a 48 kHz sample-rate ceiling on the
codecs devcaps::audio_rate_bounded names (devcaps::AUDIO_RATE_CEILING, #951; not DTS, TrueHD, nor FLAC, ALAC and LPCM,
which the app resamples to 48 or 44.1 kHz itself, devcaps::pcm_load_rate; a 5.1 hi-res track still converts on the server); DTS requires a measured
DTS row and feeds only the DTS core when an HD extension is present. PMS names DTS dca:
devcaps::audio_codec_id folds it (and ec-3) onto the pipeline's dts at membership and at
the Load payload, and the profile sends dca (transcoder.rs::profile_codec_name). Force
Direct Play admits DTS natively only when the table has a DTS row with channels (Caps::forced_admits_dts)
but skips the channel ceiling; where the set has no native path for a lossy track whose row has TV evidence
(devcaps::AppDecoded::measured: DTS), Force Direct Play decodes it in the app instead, as stereo, for a track
of at most two channels only: the app never mixes a source of more than two channels down to stereo by default, so a
surround track there is refused like any unplayable one (Caps::app_decodes_lossy_track, Caps::app_may_mix_down,
devcaps::app_decode_mixes_down). The implemented Load
strings are H264/H265/AV1/VP9 (AV1 and VP9 only on a set whose table lists that decoder; elsewhere the Load is refused) and AC3/AC3 PLUS/AAC/DTS, plus PCM for FLAC, ALAC and LPCM decoded in the app (and for the lossy rows the attempt decodes in the app: DTS where Force Direct Play has no native path (a stereo track only) or the failed-open ladder's last rung asks for it (a surround track only after the server conversions, the manual encode included, were refused), and every lossy row, MP3, Vorbis and TrueHD included, on a debug build with /tmp/plxnative-appdecodelossy; those three have no TV measurement, so a release build does not offer them); these are not the firmware's whole
vocabulary. The six AC3/EAC3/AAC combinations and H264/DTS are covered
here, plus DV 8.1, both containers, in-place seek in each, and the FRAME-RATE axis added the same
day (pipe_h264_1080p5994 is the only fixture that reaches fps_rational's 1001-denominator
branch — device-verified esInfo: videoFps 60000/1001 — and pipe_hevc_4k_60fps is 4K60 HEVC;
every other fixture in both packs is 24p), and — since 2026-08-23 — the RESOLUTION x CODEC
matrix LG checklist #50/#51 is graded as: SD 720x480 / HD 1280x720 / FHD 1920x1080 / UHD
3840x2160 x {h264, hevc}, eight cells, one audio codec per column so a row-to-row difference is the
raster alone, each grading expect.video_size EXACTLY out of the ff: line rather than a width
floor — which is what stopped the item being answerable only as "pieces are covered", and which
closed the 4k-h264 library gap on this tier (8-bit-hevc was already closed by
pipe_hevc_aac_mp4 and the gap list had not caught up; a generated clip closes neither gap's real
half, which is a PMS DECISION on such an item). The same day added the first clip in
either pack that is MEANT to run out (pipe_finish_eos and pipe_replay_after_eos, 20 s), which
is #46 END TO END — the second of those restarts the finished stream through
/tmp/plxnative-replay[=N], a bounded counter re-arming app.rs's one-shot autoplay latch, and
grades the re-entry COUNT, a second load: line, a second fetch off the fixture server and a
media position that falls and then climbs. A second such clip followed for #865,
pipe_h264_ac3_audio_tail (a film whose audio outlasts its picture, ended by the pipeline's own
end-of-stream; pipe_finish_audio_tail). Still
uncovered: HLG, HDR10+, DV P5/P7, Atmos, the
4096-wide edge and any refusal above it, a USER-driven replay (a Play control on a detail page is
server-tier by construction), and the transcode INPUT space
(three server cases on one AV1 item stand in for 17 codecs). One of those is an app gap, not a test
gap — devcaps reads the table's maxFrameRate only into the per-codec rows the Starfish Load
envelope clamps against (since 2026-09-03), so the profile sent to PMS still bounds no frame rate
at all. Three things about it
are worth knowing before reading a result. (1) The declaration is the interesting half and the
main false-PASS risk: an unrecognised AUDIO codec ("" included) no longer defaults to "AC3"
(plx_play_feed::audio_payload_codec's _ => None arm gives it no payload name, and the Load is refused with an
unsupported audio codec log line), and the video side no longer defaults either: LoadVideo::of_stream is case-insensitive, "" and h264 are the only H264, hevc/h265, av1 and vp9 get their own
payloads (av1 and vp9 only where the device's codec table lists the row, otherwise the Load is refused), and any other vcodec in a
playurl declaration refuses the Load with a log line naming it. So a trigger that was never read ("") declares H264 and is refused
at the audio step, and the matrix carries cases expecting
"AC3 PLUS" and "AAC" because the declaration decides those names; the engine now logs one load: v=… a=… fps=… dv=… atmos=… line
per streamed playback (the only place an event log says what the app told the television the stream
WAS, as opposed to what the demuxer found in it). (2) python3 -m http.server is DISQUALIFIED
and the failure is silent: the AVIO seeks by reopening with Range: bytes=N-, stream.rs accepts
any 2xx, and a server that ignores the header answers 200 from byte zero while the demuxer believes
it is at N. serve_fixtures.py answers 206 or 416, never 200-with-a-Range, and the suite asserts
the ranged-open COUNT off the server itself — the one assertion no log line can give. (3) It
cannot prove that the declaration it feeds is the one a real item would produce: it writes those
five route fields itself, so metadata → plan → apply_plan is bypassed and a regression there
passes it green. It also reaches no resume, marker, Up Next, timeline, track-SELECTION or transcode
path. Never run only this one before a release. tests/README.md has the tier table.
- Event log: the app writes
plxnative-events.login its runtime root on the TV (LS2/ACB/ Starfish replies, feed stats, seek/bind steps, key raw bytes, crash tracer) —/tmpfor the stable install,/tmp/<app id>for a flavoured one;make -s print-eventlog FLAVOR=<f>resolves it.make runfetches it automatically; it's the primary debugging surface. stderr goes toplxnative-stderr.logbeside it. Its FIRST line names the install —install: id=… flavour=… runtime=… features=dev|release APPID_env=…(withappdir:on the next line, fromapp_dir()'s own provenance-carrying log), written before anything can fail. It is the only witness that says which of two binaries both namedplxnativeproduced a log (pidofcannot tell them apart, andpkg/plxnativeis a path every configuration writes, so an md5 proves only "some flavour of some configuration"), so read it before grading anything.APPID_env=is evidence rather than configuration: nothing off a desk says whether SAM exportsAPPIDto a native app on this firmware, and this answers it for free on every run. - A case's
run_secsis a CAP, not a runtime.tests/run.pylaunches viamake run-stream(tail -F over ssh) and re-grades the log as each line arrives, ending the case the moment every assertion passes — so a passing case costs what it needs. A failing one burns the fullrun_secsunless its verdict is already settled (failed_for_good: aPlaying error, or a rapid-seek burst that escalated toreload_at: fresh Load— lines that never un-appear), since every other failure means "not appeared YET", which more time could still fix. Sound because assertions are monotone once satisfied, with two ABSENCE-check exceptions that can only flip the other way —no_errorandop_seek_rapid'sreload_at: fresh Load; adding a third means re-readingstream_case's soundness note.--no-earlyrestores the old fixed window when you want the longer look at a late error. The cap is measured from the app's FIRST LOG LINE, not from ssh start, so it keeps meaning app runtime the waymake run RUN_SECS=did. Two more consequences when editing the harness: raising a manifestrun_secsno longer slows the suite down, and never pre-create the event log on the TV — the app runs jailed under its own uid, so a root-owned file left in place is one it cannot write (log stays 0 bytes, every assertion reads as a total regression).make runkeeps the old sleep-then-catshape because the FPS scenes need a fixed sampling window; both shareBOOT_SH. - A case's start position is server state, so the harness resets it every time. The resume
point (
viewOffset) lives on the PMS, outlives the run, and the app's timeline reporter posts progress every 10s while playing — so before this was fixed, a case inherited wherever the previous case or the previous run stopped (rk=4is shared by five cases,rk=1804by three), andresume_nsresumes anything past 10s. "Play from the start" was silently a resume test. Nowrun_casealways clears first, then seedssetup.viewOffset_msif the case declares one. The reset must be/:/unscrobble— aPUT /:/progress?time=0returns 200 and changes nothing (verified live;time=1too), which is exactly what makes this look already handled. Don't make the reset conditional again to save the pre-seed close: the wandering seek-tier failures were this, not the player. - A settled non-player screen STOPS PRESENTING (
plx_machine::idle, the whole-frame present gate). The loop keeps running at full rate — input, pumps and every*_updateare untouched, so key latency and timers are unchanged — butglViewport…SDL_GL_SwapWindowis skipped while nothing is moving, and a 2s keepalive bounds staleness. This is NOT the dirty-RECTANGLE trackingplx_ui'slib.rsrejects: when a frame does run it is the same immediate-mode full redraw it always was. Motion is detected exactly (bothgfx::spring*integrators report), and discrete changes callplx_machine::idle::invalidate()— a new async landing that repaints must add a call there, or it arrives invisibly until the next keypress. So must anything that animates from a CLOCK rather than a spring — a millisecond ramp, a phase, a countdown — sincenote_springcannot see it, through one of two doors:idle::invalidate()when what it changes is content,idle::note_motion()when it is a time-driven decoration (the tab pulse) — under a standing popoverinvalidateis page damage and re-captures the frozen host every frame.Xfade::tick(the CONTENT cross-fade — the Library's grid and page, Search's results, Filmography's preview; it was the ROUTE dip too until restructure phase 12 moved that toui::containers::transition::PageDip, which reports from inside its owntickby construction) andSpinner::draw(every loading read-out) both shipped FROZEN before they were made to report, and no fps scene caught it because those gradeloop=. The rest test is visibility — magnitude-relative, capped under a quarter pixel, velocity judged asvel*dt(the travel this frame) — not a bare epsilon. Measured 2026-07-31 on a still Home grid: 39.6% → 1.67% of one core (ours 15.4→1.05,surface-manager24.2→0.62). Consequences for anyone reading a log: the heartbeat carries two different rates and they are easy to swap —fps=<n>is frames actually swapped that second (the real frame rate, what this gate moves) whileloop=<n>counts LOOP iterations — soloop=62 fps=0is a healthy settled screen,loop=0is an app in trouble, andfps=0on its own is not a fault at all; the on-screen counter draws the last completedfps=window and HOLDS when idle (it is drawn, so it can only update on an ordinary present) and that is expected, not a hang; and an fps floor taken on a static screen now grades nothing, which is whyfps:home-gridarmsplxnative-homeoscand the still case is gated byfps:home-idle'sfps_ceilinginstead./tmp/plxnative-noidleturns the gate off (DIAG-exempt, so an A/B does not also change which screen you boot to), and/tmp/plxnative-nobudgetis its twin for the FRAME BUDGET (DIAG for the same reason): admission as it was before phase 11 — the poster quota of three per frame, no time ceiling and no solo frame — so an A/B leg prices the admission rule rather than two builds. The exclusion is the bound video plane, not the player route — pre-bind (the Resolving/Loading spinner) and post-unbind (the failure read-out, teardown) player frames are gated exactly like Home, which is whyPlayerScreen::clock_fingerprintexists: every clock-driven player animator reports motion through it once the route no longer gets a free pass. - The heartbeat's WIRE ORDER, since phase 11 (
rust-modules/base/src/diag/heartbeat.rs::heartbeat_tailis the one definition; anything here that disagrees with it is this file being stale):loop= route= [overlay=] [section=] [pos= play=] [vtick= vgap=] fps= [load= snap= period=] [worstframe= worstprep=] carried= dropped= budget=<admitted>/<refused>[/solo:<class>] evicted_hot= [rec=] [sim=1]. Nothing may be inserted ahead offps=orworstframe=—tests/run.py'sFPS_REandWORST_REanchor onloop=/route=/overlay=and then reach forward with a lazy.*?, so appending is free and inserting is not.section=<chapters|info|chapters_info>is the player page's open HUD section (app/words.rs::section_word), printed right afteroverlay=only while one is open; a section is the page's state and not a surface, sooverlay=stays the topmost modal surface's name (noneover a bare player) and a scene that needs a section carries its own"section"key (tests/run.py::select_section). The bracketed pairs are conditional;worstframe=/worstprep=needplxnative-framedrop, and the four frame-plan fields do NOT — they print in every build, because each is a counter its owner already keeps rather than a measurement anybody pays for.budget='s/solo:<class>third field appears only when a solo take was admitted in that second, so its PRESENCE is the event. There is deliberately noallocs=: the restructure spec names one forhostsim, this crate has noGlobalAlloc, and a counting allocator was not invented to fill a field. Beside the heartbeat, and not on it:coldopen screen=<name> ms=<n> prepared=<bool>, one line per screen MOUNT, unarmed.msis from the frame that mounted the body to the first frame it both prepared and DREW — so a mount and a first draw in one iteration readsms=0, which is the honest answer and not a broken instrument;preparedis whether that frame's budget refused nothing. This paragraph's reason for excepting the player is now FALSE and unverified in its replacement, both worth stating plainly: it used to except the PLAYER on the grounds that its page answeredFocusSource::Legacyand was therefore drawn by the loop rather than by the container; restructure phase 12 (D2) convertedPlayerScreentoFocusSource::Engine, so that reason is gone. Whethercoldopennow actually fires on a player mount was NOT re-measured by the package that made this change (make check's device/full-suite paths were unavailable in its environment). D1 has since retired the loop's own page dispatch — there is noRouteand no hand-rolled player draw arm left inapp/run.rs, so the structural reason to doubt it is gone too — but that is an argument, not a measurement: whethercoldopenactually fires on a player mount has still not been observed. This is owed to TV session 8 (phase 12's device pass): boot into the player route and read the heartbeat before trusting either answer. - The heartbeat fields were RENAMED 2026-08-01 and the old name was REUSED, so a log or doc
predating that reads as the opposite of what it says. Old
FPS=is today'sloop=(loop iterations); oldpres=is today'sfps=(frames presented). An oldFPS=60says nothing about frames at all. The manifest gates moved with them:floor→loop_floor,present_floor→fps_floor,present_ceiling→fps_ceiling. Both harness regexes were made to match the NEW names only, so an old log fails loudly as "no samples" rather than silently grading a loop rate as a frame rate. Analysis docs underdocs/still quote the old names against the line numbers of their day and carry a mapping banner instead of being rewritten. - The once/sec
loop=heartbeat carriespos=<s>while frames are presenting — the sameFEED_SHARED.playpos_nsthe 10s/:/timelinereporter posts, sampled at 1 Hz. The harness grades playback progress from it (progress_secs), because observing a 15s climb through 10s samples costs ~30s of playback. It is gated onplayer::is_playing(), notis_started(): both resume paths seed the playhead with their target before the first frame (arm_openfor direct play,Rebasefor a transcode), so the pre-roll reads the target, and only a presented frame vouches that playback got there; ungated, a resume or seek that never lands would read as playback that climbed — a false PASS. Beside it since 2026-08-27 isplay=<pm>: media time advanced per WALL millisecond, in per mille — 1000 is the film running at speed and 670 is it crawling — and it is the ONLY field on that line that can see a slow film.fps=counts our GL swaps and sits at 60 through a stream the television is decoding at two-thirds speed; every buffer number the adaptive controller reads is a RESERVE, and a reserve is media time measured against the same playhead, so when the playhead slows the reserve stops draining andslope,min_buf_msanddraining()all read healthy at exactly the moment the picture is worst.max_stall_sis blind from the other side — it grades the clock STOPPING, and this is the clock advancing too slowly. The harness derives the same quantity frompos=alone (playback_rate, reported on every case'stimeline_climbevidence, asserted only where a case declaresmin_play_rate_pm), so an old log is still readable. There is deliberately no magnitude gate onplay=: a seek reads as a huge or negative value and a catch-up leg as something above 1000, and both are real observations.docs/measurements/local-original-blind.mdis what it found first. - Since 2026-09-03 every playback case in BOTH tiers also grades
presented_rate: the frame rate the video sink PRESENTED against the rate the app DECLARED on theload:line. The instrument is the sink'snon-flushable-displayed-frames, polled by libpf every 200 ms once the Load payload carriesstreamQualityInfoNonFlushable(decompiled from libpf;player/CLAUDE.md) and logged by the app assink: displayed=<n>— normalised for the webOS 4→5 callback-numbering shift (raw type 47 here, 49 there) — summed per healthy wall second (position advanced,play=at real time) and compared as a median within ±6 % plus a one-in-five floor at 85 %. It exists because a 4K H.264 24p stream declared atmaxFrameRate: 60was presented at 13 fps whileplay=read 1000 pm,fps=read 60 and the sink's own drop counter (type 46) read 0 — three healthy instruments over a picture the maintainer could see was wrong. A transcode declares no rate and is skipped, said so in the evidence;expect.presented_rate: falseopts out. Replayed over the saved logs it fails the 60-declared run at a median of 14 and passes the 24-declared one. tests/run.pyalways cleans the TV on exit — pass, fail, Ctrl-C,kill, or crash: it closes the app, clears everyplxnative-*trigger in that install's runtime root including the injected PMS token, and reaps stray ssh clients. Runtime*.logfiles survive, including the storage diagnostics snapshot. Nothing did this before 2026-07-28 except the normal path, so an interrupted run left the app playing (scrobbling a resume point the next run then inherited) and a live per-server token in world-readable/tmp. The teardown is armed at the moment the harness commits to driving the TV, so--listand a no-match--filterstill exit without closing an app you are watching.ps | grep plxnativefinds NOTHING on this TV even while the app is running — busyboxpshere shows neither the path nor the argv. Usefuser $(make -s print-appdir)/plxnativefor liveness: it is INODE-scoped, so it answers about exactly ONE install — which is the right question here, where you are asking whether the install you are driving is up, and so the bare form (noFLAVOR, i.e. the flavour everything else in your session is using) is the correct spelling. It is the mutex pre-flight above that has to run this once per flavour, because that one asks the opposite question — is anybody else on the set.pidof plxnativeis NAME-scoped, and since the flavour split it matches BOTH installs: two binaries, one name. It returns two pids in an order busybox does not promise, so it cannot say which install it found. When you need the pid itself, resolvereadlink /proc/<pid>/exeper pid. A liveness check built onpsreads exactly like "the app is closed", which will cheerfully confirm whatever you were hoping to prove.- Screen capture:
tools/capture-screen.sh [out.png] [DISPLAY|VIDEO|GRAPHIC]grabs the panel output.DISPLAY= video plane + UI composited (use this);VIDEO-only failing with "no signal state" is itself a diagnostic that nothing is decoded on the video plane.GRAPHICof a frame over the bound video plane holds STRAIGHT colour (the straighten pass divided it by its alpha, so a translucent pixel reads brighter than what the app drew); onlyDISPLAYis the picture. - Perf gates:
./tests/run.py --fpsruns the UI-tier FPS regression scenes (gates per scene intests/manifest.json;--fps-playeradds the player tier), asserting the app's once/sec heartbeat. Six assertions in three families. Three RATE gates — and picking the wrong one is how a frozen animation ships:loop_floorgradesloop=, which counts LOOP iterations — it proves the app is alive, and cannot see a stopped animation at all;fps_floorgradesfps=and is what proves an animation still RUNS (login-spinner, the two*-navscenes,search-type);fps_ceilinggradesfps=from the other side and proves a still screen stops (home-idle,search-idle). And two FRAME-TIME gates (2026-09-06) —worst_ceiling_ms(the 2nd-highest post-warmupworstframe=) andstall_ceiling_ms(the largestFRAMEDROPtotal on the route, warmup INCLUDED) — which armplxnative-framedropthemselves and answer what no rate can: one 80 ms frame under a healthy median. And, since phase 11, one MOUNT gate:coldopen_ceiling_ms, the slowestcoldopen screen=<word> ms=<n>of the scene's screen. It exists becausestall_ceiling_msCENSORS ITS OWN SAMPLES and could not simply be re-pointed: the frame-drop detector prints only above the thresholdframe_ceiling_thresholdarmed it with, so a cold open FASTER than the ceiling leaves no line andgrade_frame_ceilingspasses it as "no FRAMEDROP line" — five runs ofcold-openin TV session 5 read "no-line PASS, 208.5, no-line PASS, 191.4, 227.8", in which a 30 ms open and a 159 ms one are the same output. Thecoldopenline is UNARMED and unconditional, so one mount is one sample and an absent line fails. Its value oncold-openis PROVISIONAL until TV session 7 leg 6 measures it, and the scene's_coldopen_notesays so. And, since 2026-09-19, one STRESS family —bench_missed_max(missed display refreshes summed over the run, default 0: each present interval, or the first frame's Top->Swap after idle, costsmax(0, round(ms/16.67) - 1), so a frame is a drop once it spans 1.5 refreshes; Top->Swap alone is not graded because it includes the vsync wait. A loop iteration the capture fence DEFERRED (Frame::deferred:snapshot_pending()was the only thing holding a present) keeps the present-to-present interval, so the next frame's interval spans it and counts; an idle skip still resets it. Deferrals before a half's first presented frame are input-to-first-frame latency, logged asdefer_first:<n>in the half and never inmissed. A scene may also setbench_iv_max_ms, a ceiling on the worst present-to-present interval from the half'siv:field),bench_drift_ms, andbench_rss_growth_kbforpush-100/modal-100; for the DEEP-stack scene,bench_depth_rss_kb(deepest point minus the unwound root, so retained per-level state) andbench_root_rss_kb(an absolute ceiling on the unwound root) instead of a growth figure measured from a step-10 baseline that moves. It does not compose with the six: a scene carrying abenchkey (every one intests/manifest.json) is graded entirely byrun.py'sgrade_bench/grade_deep_bench(deeponly for the latter) and never reaches the rate, frame-time or mount gates, so "six" counts the gates of an ordinary scene. The Search pair is the clearest illustration that these are two halves of ONE question — same screen, same trigger, the oscillator added or taken away. A scene with no motion and only aloop_floorgates nothing —home-herocarries an_idle_gate_notesaying exactly that, and it is the only one left; this line said "three" long after the other two (home-grid,library-scroll) were given oscillators and realfps_floors, which is the fix that note asks for. The otherloop_floor-only scenes need no note: the video plane stays bound for the whole scene, sofps=grades neither an animator nor an idle screen. Take the list from./tests/run.py --list --server, not from here. Among them,info-panelandchapters-panelare HUD sections of the player page (they pinoverlay=noneand asectionword), andtrack-menuis still an overlay. Every run also reportsdrift(last-third minus first-third mean): sorting used to destroy sample ORDER, so a monotone 60→53 decay and a flat 53 were byte-identical output. It is reported, never asserted — 18–36 s is far too short to gate a thermal ramp on, and the "the panel thermally throttles" story is MEASURED AND REFUTED (2026-08-19): a control leg holds 60/60/60 across six runs on a set up 2 h 15 m under continuous load, and what actually produces a 50 fps reading is arming a profiler —frame.uibrackets every frame with twoglFinishes and drops a 60 fps leg to 45. Never quotefps=from a run with/tmp/plxnative-profile,/tmp/plxnative-hwcntor the recorder (/tmp/plxnative-rec, whoserec=<n>usheartbeat field makestests/run.pyrefuse to gradefps=/worstframe=at all) armed; take pacing in a separate unarmed run. What this hardware WILL give you, priced in frames and milliseconds for design rather than in cycles, isdocs/glass-hardware-budget.md; the instruments and their structural blind spots aredocs/backdrop-blur-profiling.md. A third profiler mode,/tmp/plxnative-cpuprof(2026-09-02), times everygfx::profile::phase(spelledui::profile::phaseat most call sites;uire-exports it since module-layers step L5) on the RENDER THREAD — inclusive wall time, every phase at once, noglFinish, a~srcsuffix for the blur source pass's copy of a phase — and it is the one that can read a frame the frame-drop detector reports asdraw=24ms swap=0.3ms: on this driver the wait for the GPU lands in the frame's FIRST framebuffer-0 command, i.e. insidehm.clear, so a fatdraw=is not CPU work until this mode says which phase holds it. That is how the Home hero regression was read (docs/backdrop-blur-profiling.md, the 2026-09-02 section): 26 ms inhm.clear, 2 ms in everything Home actually computes. For by-hand judder hunts:/tmp/plxnative-framedroplogs any frame over 22ms (or over N ms — the file's content) with an EIGHT-PHASE breakdown —ingest results tick_drain navcommit prepare draw capture swap, the frame algorithm's names, timed from the TOP of the iteration since 2026-09-06 (it used to start after the input half, so a slow key handler was invisible) — plusup=/px=/cards=/off=, which are THAT FRAME's counts since phase 11 and were not before: their only drain was the closure the instrument calls after the threshold check, so a slow frame's counts covered every frame since the previous slow one (theup=9indocs/measurements/tv-session-5-2026-09-10.mdis a reading of the old behaviour). It addsworstframe(the whole iteration, presented frames only) andworstprep(the prepare phase, timed on EVERY iteration) to the heartbeat;/tmp/plxnative-homeoscsweeps the grid focus top↔bottom perpetually to reproduce scroll judder headlessly. For a reproducible three-layer account of one FPS scene use./tests/run.py --fps --only <scene> --graphics-profile --profile-phase <phase>: it preserves one unarmed pacing leg, samples global Mali IRQ activity with the selected install closed, then runs HWCNT separately and labels that leg's FPS invalid.tools/profile-graphicsattaches active present/IRQ observation to an already-running app, with no baseline; it checks profiler triggers and labels pacing invalid when one is armed. For a live freeze usetools/plxnative-sample; unlike the shipped crash path itswatchmode is a foreground developer command and sends nothing. - Poster-upload pacing, since 2026-10-08: a scene may set
upload_per_frame_min,upload_late_share_maxandupload_frames_min(default 15). Over the frames that uploaded posters (mean upload at most 120 000 px, so a backdrop never counts), uploads per such frame must be at or over the floor and the share whose present-to-present interval was >= 22 ms at or under the limit. The armed heartbeat carries it aspupf=<frames> pupf_ge22=<late> pup=<uploads>(diag::heartbeat, present only in a second that uploaded posters), summed over the whole run; the scene armsplxnative-framedropat a threshold nothing reaches, so there is no per-frame log.library-scrollcarries a floor of 1.25 and a share backstop of 0.35, measured on the television 2026-10-09 (8 runs withwarm_texdrawing to framebuffer 0, 22 with it offscreen): uploads per upload frame 1.00 exactly against 1.41-1.85, which separates every run; the single-run late share does not (0-30 % against 30-51 %), hence only a backstop. The prepare budget is priced from the same measurement:Poster2500 us under a 5000 us ceiling (ui/src/frame/budget.rs). - Dev trigger files (read once at boot, in the install's RUNTIME ROOT). There are ~40; this
lists the ones worth knowing by name. The ROOT is
/tmp/<app id>: FinNative puts every install's files there, stable included (the bare/tmpis a stable PlxNative's), so read each/tmp/plxnative-*path written out below with the SAME name under/tmp/<app id>(/tmp/io.github.tiper.finnative.debug/plxnative-library). Nothing was renamed — not the ~40 triggers, not theplxnative-remoteFIFO, not the runtime logs, notdev::DIAG; only the directory they sit in.make -s print-rundir FLAVOR=<f>is how a tool asks rather than restating the rule, and the root is created 1777, mkdir THEN an explicit chmod (umask masks mkdir's mode) because root arms triggers there over ssh before the jailed app has ever booted, and an owner-only mode locks one of the two out — a 0-byte event log, which every tool here reports as "no line found", i.e. exactly like a total regression. Why any of it:docs/two-installs.md. The catalog is the source, not this list — get the real one with{ grep -rhoE '/tmp/plxnative-[a-z0-9]+' rust-modules/src rust-modules/*/src src | sed 's|.*/||'; grep -rhoE 'devtrig::(flag|read)\("[a-z0-9]+"' rust-modules/src rust-modules/*/src src | sed 's/.*("/plxnative-/;s/"$//'; } | sort -u. Both halves are needed: a path literal only ever appears in a COMMENT now, and four triggers (grid,h265,playidx,ptype) are named nowhere but theirdevtrig::flag/devtrig::readcall, so the path grep alone silently under-reports. This line carried that grep alone and called it complete. Since UI restructure phase 10 the ARMS live inrust-modules/src/dev/scenarios.rs, not scattered throughapp/{boot,run,content,mod}.rs—rust-modules/base/src/devtrig.rsis the one door onto/tmpitself (a base-layer module;dev.rskeeps the application-layer half), and the catalog command above names itsdevtrig::flag/devtrig::readcalls. Every read goes throughrust-modules/base/src/devtrig.rs, gated on thedevtriggerscargo feature — read that module's doc (anddev.rs's) before adding a trigger, and never open a/tmppath directly. Default builds are unchanged;RELEASE=1drops the feature, and thendevtrig::flagisfalseanddevtrig::readisNoneat COMPILE time, so a public binary opens nothing under/tmpbut its own logs (capture::initis compiled out, so there is no listener on ANY port — a compile-time fact; device-verified on the stable install: no FIFO and nothing on:8910. This line used to assert the device measurement alone, which could only ever have probed the one port it knew about). The same feature gatesRemote::openandcapture::init— those are structural surfaces with no path literal, which is also whydev::any_trigger_present(the whole-/tmpscan behind the picker suppression) lives there rather than being greppable. The harness is unaffected:tests/run.pybuilds with plainmake. Two behaviours bite:make runclears ONLY the event log (unliketests/run.py, which glob-clears triggers), so a by-hand run inherits whatever the last session armed; and any non-DIAG trigger left behind also suppresses the who's-watching picker, silently changing which screen you boot to. Thetv-sessionskill drives all of this (clear → arm → launch → assert) and owns the screen-to-trigger recipes./tmp/plxnative-storepolicygives a developer build the STORE's credential policy (CredentialPolicy::HttpsOnly,plex/origin.rs) for the whole launch: everydevtriggersbuild otherwise lets a token ride plaintext, so the PLX-NATIVE-10 "Connect without encryption?" flow — reachable only when plaintext needs a consented grant — cannot be reached in the sim or on the TV without it. It only tightens, and a store build has no trigger to read. The end-to-end reproduction againsttests/mock_pms.py --plaintext-only-lanis in the mock's--help. Controlled-bootstrap update:plxnative-recandplxnative-recplaysupport Home, Settings, and typed Flow 12 content with typed pre-effect initialization, explicit recorded Client bindings, recorded Home/Browse and Detail/Person results, and exact request admissions. Replay denies content resource execution and compares supported effects as well as state; malformed/unsupported input fails closed before resource activation. Page-capture GPU readiness is sampled before dispatch and replayed as an input; final present decisions are still computed and graded, with live physical-window protection.AppFrameV4includes physical Consent and the initial-input digest. Private recordings can contain credentials in typed initialization/effects: only explicitly synthetic inputs may become fixtures.tests/controlled_bootstrap.pyexercises this representative production path with fresh/contrasting roots and outbound IO denied. Blobs, cross-target operation and unsupported domains remain unsupported/open; controlled product replay supports both Targets and Resolve modes. The following phase-11/12 description is historical, not a claim that current replay falls back to live stores. Named historical highlights:/tmp/plxnative-rec[=blobs](the RECORDER of the UI restructure, spec §5.3 — every frame's tick and present bit, every input the loop acted on and, on each event frame, the hash of the covered logical state: the press machine, the route and overlay words, the focus fingerprint, the container-tree hash and Session's cached logical digest. The digest adds no raw Session credentials; it does not supply Session restoration from AppInit or complete all-domain replay. It writesplxnative-recordings/latest/in the runtime root — a DIFFERENT name from the trigger file, which is why the directory is notplxnative-rec/— private, gitignored and refused by the outbound guard;tests/focusfp.sh --recrecords a flow andtools/plxnative-rec importturns a recording taken againsttests/mock_pms.pyinto a committed fixture),/tmp/plxnative-recplay=<dir>(REPLAY that recording: the loop runs on the recorded ticks throughapp::clock, re-injects each frame's inputs through the remote FIFO's own synthesis, grades the state hash frame by frame — every mismatch is its ownreplay: divergeline and the run continues — and ends with onereplay: done … verdict=SAME|DIVERGEDline;tests/focusfp.sh --targets(--replay) and--resolvedrive it over committed product fixtures. Supported stores receive recorded results with resource execution denied; unsupported domains fail closed. The historical phase-11 driver instead fetched live while constraining the frame a result was OBSERVED on (plx_machine::landgate, spec §3.3 step 3): every landing SITE — Home's hubs and each legacy pump's mailbox take — consumes through a schedule of(frame, arrivals)pairs per store, an early arrival WAITS for its frame, the due frame polls for a bounded moment, and late/extra/missing ride the summary asland_diffs. Before it, flow 12's one recorded landing sat on frame 1 and every replay observed it on frame 0, which — a spring started a frame early never re-converging bit for bit — diverged 927 of 928 frames. The current schema writes exactly one finalfofocus record after all drains in every product frame and orderedrsrecords for each resolution point, of three families: Focus (the engine's focus), Hit (a pointer's hit map) and Id (a by-idfocus:/press:token). Product replay has two modes: Targets feeds recorded answers; Resolve computes and compares the real engine/hit-map/id answers pointwise, incrementsfocus_diffs(Focus) orhit_diffs(Hit and Id; theresolution=focus|hit|idword of thereplay: input divergeline says which), and then continues from recorded answers. A typed, bit-exact Width/Cap/Line table prevents replay from consulting a live font. Both names aredev::DIAG, so neither moves the boot screen; both armed at once is refused),/tmp/plxnative-softfloat(the host↔ARM soft-float differential table, spec §4.2: logssoftfloat: … MATCH|DIVERGEagainst the host's pinned hash and writes the table beside it;make softfloat-probefetches it),/tmp/plxnative-subside(content = the 0-based position of an embedded subtitle stream; read at each playback start, no relaunch: while a plain remux plays with no subtitle selected, a side reader demuxes the Part's subtitle packets over a fresh-session range read and the client renderer draws that track; logssubside: open|anchor|reopen|failed|stop …, never a URL, token or session;plx_play_feed::side_reader,media::player::subside,ff_subside.rs),/tmp/plxnative-uriprobe[=load|late|none|drive](the webOS 5+ URI-mode probe, issue #1064: the next Play hands its stream URL tocom.webos.mediaover the platform bus instead of building an Engine, to learn whether the exported window id is honoured and where it may go. The content picks the variant: empty orloadputswindowIdin theloadpayload,latesends it withsetWindowIdafterloadCompleted,nonesends no window at all, anddrivebinds likeloadand then exercises the transport — pause, resume, a seek 20 s ahead, a text and an audioselectTrack,setSubtitleEnable— logging the position before and after each, so the summary says whether the pipeline accepts them; text naming no variant leaves the probe unarmed and the play normal. After the variant,bpsstart=N,bpsmax=Nandbpsmin=N(bit/s, each 1 to 1000000000, at most once, space separated, e.g.load bpsmax=720000) put the native adaptive-streaming seed and limits into theloadoption asadaptiveStreaming.bps.{start,maximum,minimum}and onto thearmedline; any other token leaves the probe unarmed. Read at each playback start, no relaunch; skipped for a hero preview. No Engine runs, so nothing is reported to Plex (no timeline, scrobble or unscrobble). The event log getsuriprobe: …lines ending in onesummaryline, never the URL, token, host or a service payload; a tester sends those lines and removes the file.dev::DIAG, so it does not move the boot screen; the play-uri crate'suriprobe(the machine),dev::uriprobe(the application's driver over it),media::player::uriprobe_drive(its route half and port)),/tmp/plxnative-url(override the streamed part URL) and/tmp/plxnative-playurl(the same, plus the LOAD DECLARATION — one JSON object,{"url":…,"vcodec":…,"acodec":…,"fps":…,"dovi":{…},"atmos":…}, which is what the pipeline test tier drives and the only way to declare HEVC /"AC3 PLUS"/ Dolby for a stream no PMS chose; it also ENTERS the player on its own from a boot with no session, since there is no home grid to press OK on),/tmp/plxnative-replay[=N](once aplayurlstream reaches EOS, start it AGAIN, N times — LG checklist #46's replay half; a COUNTER rather than a lifted latch becauseauto_triedalso guards the autoplay+playidx arm, which fetches a catalog item, so an unconditionally re-armable latch would loop a real playback forever. Absent = 0 = the one-shot behaviour every other boot has),sample.h264/sample.h265(feed the player a local raw Annex-B sample instead of streaming — the two names that predate theplxnative-prefix, and since the flavour split the last two runtime surfaces to stop being pinned to a shared/tmp: they resolve through the install's own root like everything else,$(make -s print-rundir)/sample.h264),/tmp/plxnative-autoplay(auto-press OK for headless capture),/tmp/plxnative-autoseek(empty = one seek to 140s; else a seek script: optionalgap=<ms>+ comma steps, absolute120or tap-relative+10/-10— rapid-burst seek testing),/tmp/plxnative-ptype(ACB playerType bisect knob for Feed's handle; the URI engine's handle is always player type 0),/tmp/plxnative-holdload[=ms](sleepms— default 30000 for a bare/empty trigger — onnative_load::load_threadright after the realsf_loadcall returns and BEFORE the Load-returned flag publishes, making issue #74 D.1's budget observable on demand: the pump'sdeferringline, then, pastNATIVE_LOAD_BUDGET, the failure read-out; NOTDIAG, since it changes playback behaviour),/tmp/plxnative-marker[=intro|credits](once playing, seek to 5s before that server marker — the only practical way to reach the Skip Intro / Skip Credits pill, and, via afinalcredits marker, the whole finish → Up Next → auto-advance chain, without playing 50 minutes of episode first),/tmp/plxnative-nowan[=slow](the OFFLINE reproduction: every name that would have gone to a resolver — plex.tv, discover, an UNPINNEDplex.directorigin — fails as it does on a LAN whose uplink is down, while a literal or a pinned name is untouched;slowfirst spends the connect budget a dead resolver would have cost. It is howplex::ResolvePin, the fix that dials the household's ownplex.directname at the address plex.tv advertised beside it, is shown red and green on the simulator with a stored session; pair a/tmp/plxnative-serversentry's"scheme":"https"with its new"pin":"<address>"field to put a pinned TLS origin through the registry headlessly),/tmp/plxnative-failtest[=verdict|audio|novideo|stream|connection|tv|jail|none](force one variant of the full-screen failure read-out — the one screen that cannot be reached on purpose, since it needs a server that refuses, and the one most meant to be LOOKED at: it is shaped to survive a phone photograph in an issue thread. Live-read, so arming it mid-playback swaps the frame at once;stream,connection, andtvexercise the runtime media-source, interrupted-transfer, and native-pipeline reasons;jailforces the missing-/dev/rtkmemread-out regardless of the real device probe, since most dev machines are not an affected SoC; pairaudiowith/tmp/plxnative-nopassfor the PLEX PASS capsule line. Every arm butjailfeeds the realplayer::error_shape(jailis the oneErrorShapeerror_shapenever produces, so it calls the siblingjail_error_shapedirectly instead), and forces the STATE only atappkit::player_hud::busy— never atplayer::state(), which the pump acts on),/tmp/plxnative-testpat=<spec>— replace the page's picture with a SYNTHETIC ground (flat:<L*>,ramp,edge,checker:<px>,lines:<px>,hbars:<px>,hue[:L*],rainbow[:L*],solid:<deg>[:L*]), drawn as page content so it is exactly what the tab track samples and what the backdrop blur sources. The remote tokenpat:<spec>changes it live, which is what makes a graded ladder one scripted run instead of a dozen launches that each land on a different hero;tools/glass-patterns.pydrives that ladder and assembles the contact sheets. It exists because judging a glass material against whatever poster the hero happened to be showing is not repeatable — the hero advances on its own clock and two simulators launched together drift apart within seconds — and two comparisons were silently mis-paired that way before it did. And the Library browse set:/tmp/plxnative-library[=N](boot straight into the library on section N),/tmp/plxnative-libosc(a perpetual focus sweep of that library's whole DOCUMENT — the favorite library strip and persistent Library options at the head, each published shelf, the grid's control row, then the poster grid — reversing at the document's own ENDS rather than on a clock, which is the one oscillator here that does. The owned Library handlesLibraryCmd::Sweep; the rule dates to 2026-09-05: at the shared 350 ms cadence a clock reversing every 3 s gives about eight presses a leg, and a twelve-shelf library spends more than four of those seconds just reaching the grid — sofps:library-scroll, whose whole purpose is to sweep the seam between the last shelf and the poster wall, graded a sweep that could not reach it), and/tmp/plxnative-libswitch(cycle every switch: tabs, sort menu, unwatched, filter→genre), the three Settings-family scene triggers added 2026-09-06 for the frame-TIME gates (worst_ceiling_ms/stall_ceiling_ms, graded fromworstframe=andFRAMEDROP):/tmp/plxnative-modalosc(withplxnative-settings=root, open and dismiss Settings every 1.5 s —fps:modal-ramp),/tmp/plxnative-legaldoc(with=legal, one OK on the index so the boot lands on a pushed document —fps:legal-document) and/tmp/plxnative-alert(with=privacy, open the "Delete all local data?" decision alert, deleting nothing —fps:decision-alert); and the Search pair:/tmp/plxnative-search[=<query>](boot straight into Search with the field already holding<query>— the seed is not a convenience, since neither the harness norsim-shotcan type and the TV's own keyboard is raised by a user, so without it every headless look at this screen is the empty state) and/tmp/plxnative-searchosc(sweep the result shelves' focus down↔up perpetually, 350 ms per step reversing every 3 s — the same cadence and the same CLOCK reversal ashomeosc;liboscshares the cadence and reverses at its document's ends instead, above). The oscillator does NOT reach the screen on its own: pair it withplxnative-search, and with a query the library actually matches, orfps:search-typehas no shelves to sweep. Design, and the on-screen-keyboard research behind the field (three traps, two dead ends):docs/search.md. Plus/tmp/plxnative-navosc[=<ratingKey>](bounce the ROUTE every 1400 ms through the real press path — the only scenes that change route, and so the only ones that sample the whole-screen page cross-fadeui::navdraws. EMPTY = Home↔the first library section, the two pages that SHARE the top tab bar (fps:home-library-nav); a ratingKey = Home↔that item's DETAIL page instead, which has no shared chrome, a hero backdrop and ambient ground on the far side, and a real teardown at the fade floor (fps:home-detail-nav). Both boot to Home). The COUNTED stress-bench twins of the two above:/tmp/plxnative-pushbench[=<n>[,<ratingKey>]](n push→settle→pop cycles rotating Detail/Person/Library, default n=100 —fps:push-100) and/tmp/plxnative-modalbench[=<n>[,<ratingKey>]](n present→settle→dismiss cycles rotating every modal Style reachable without a TV-only gesture —fps:modal-100); both log onebench:line per cycle (worst-frame ms, presented frames, RSS, first-frame ms, missed refreshes per half) and abench: ... doneline once, then go idle, graded bytests/run.py'sgrade_bench. A third,/tmp/plxnative-deepbench[=<depth>[,<ratingKey>]](default depth=100 —fps:deep-100), does not round-trip: it pushesdepthpages with NO pop in between, rotating Detail/Person only (never Library — its only entry point is a peer swap,NavOp::SelectTab, that would collapse the very depth this scene builds, seedev::scenarios::bench::DeepBench's doc), then pops all the way back to the root one page at a time —2*depthbench: kind=deeplines, each ONE nav op (dir=push|pop, plusdepth=), and abench: kind=deep done … rss_root_kb=<r>line once, graded bygrade_deep_bench(addsbench_depth_rss_kb/bench_root_rss_kbto the STRESS family, above). Seedev::scenarios::bench's module doc. Plus/tmp/plxnative-itemmenu(snap into the grid, then open the press-and-hold card context menu on the focused card —route=home overlay=itemmenusince UI-restructure phase 10, when the menu became aModalStacksurface androute=itemmenustopped existing; the interactive path is a real ≥500 ms hold, which no boot trigger can express). Note/tmp/plxnative-pressis its TAP twin: it now schedules its own release ~150 ms in, because a down with no up is pastpress::LONG_MSand is a HOLD, not a tap./tmp/plxnative-holdbench[=<n>[,<period_ms>[,tap]]]is the counted twin of both (dev::scenarios::bench::PressBench; default n=100, period 1500 ms hold / 350 ms tap, a tap is capped underLONG_MS): a REAL press on the focused card through the remote's key path, so the card's press-in, the hold capsule's fill, the item menu's open and its dismissal are inside the graded halves, whichitemmenu(a directrequest_home_menu, graded after a 6 s warmup) never covers. Hold: OK-down and nothing else (never a key-up, and no OK is queued while a menu is up, since a hold menu opens on its Play row), then Back only while the menu is up.tap: OK-down, then a direction key before the threshold, which is the app's real press-cancel path (no activation, one-card focus move, right then left). Works on a Home card (pair withplxnative-grid), a Library card and a Collection page card (plxnative-collection=<rk>; it seats the first card with one Down if the page opened on the header). Onebench: kind=hold ... target=<home|library|collection>line per cycle,targetsuffixed-nocard/-nomenuwhen the cycle pressed nothing or opened no menu, whichgrade_benchfails; fps sceneshome-hold,collection-hold,home-tap,collection-tap, all--mock-runnable and measured on the television on 2026-10-08 (one run each, debug build withARM_PROFILE=release, mock, panel on): home-holdbench_missed_max110 /bench_iv_max_ms55 (fixed build read 81, iv 46.7), collection-hold 60 / 50 (41, 42.6), home-tap and collection-tap 8 / 40 withbench_drift_ms4.0 (4 and 3 missed). A tree WITHOUT the item-menu opener-lift fix (PR #561) reads 525 / 498 / 12 missed on home-hold / collection-hold / home-tap, so the hold scenes FAIL there and depend on #561 being on main. Remote-driving:/tmp/plxnative-remoteis not a trigger — the app mkfifos and drains it every frame on every boot (so it never affects the picker; its DIAG entry is a permanent requirement, not an exception). Write key tokens likedown/ok, or pointer clicksck:X,Yin authored 1920x1080 coords, and they replay through the real key/pointer handlers.okis a TAP (both edges at once);okdown/okupare the split halves, which is the only way to drive a press-and-hold —okdown, sleep pastpress::LONG_MS(500 ms),okupopens the item context menu; a debug build also takesfocus:<id>,press:<id>[@<ratingKey>]andstate:<nonce>(the structured readbackplxnative-a11y.json, besidefocusprobe's fingerprint), viatools/tv-session.sh focus|press|stateortools/a11y.py. A press of an element that ACTS ON a title it names (it plays, restarts, finishes or retries it, marks it watched or unwatched, bookmarks it, or opens that title's own page or menu where the title can change under the press, as a card, a credit or the Home carousel's Info do) names the title:--rk <ratingKey>ontv-session.sh press,--subject <ratingKey>ona11y.py press(send press:<id>@<ratingKey>), the ratingKey of the title the press acts on, whichstateprints as the element's subject. Those THREE command lines refuse the unnamed press (exit 2, nothing sent); only a control whose target the page fixes (Go to Show, Also available, the Play Version opener, More, a panel opener, a seek) is pressed bare, andSUBJECT_BEARINGintools/a11y.pyis the one list of the ids. The guard is on the command lines only: the library functionsa11y.press()anda11y.press_token()are unguarded on purpose, for scripts that drive the mock, so a script that imports them against a real server has no check at all.tv-session.sh keyanda11y.py sendare not a way round that:keyrefuses afocus:,press:orstate:word (the three verbs are the one door for them), and both refuse a word with whitespace in it (the app cuts the FIFO at any whitespace, soback press:<card>would be a second, unchecked token). Prefer them over a key walk to a target; walks remain for tests whose subject is travel (fps walks, focus fingerprints); Withdevtriggers,hang:<ms>stalls the frame thread under thedev hang probeguard andhang-raw:<ms>sleeps without a label; both accept unsigned decimal u64 milliseconds capped at 5000, viatools/tv-session.sh key hang:1000orkey hang-raw:1000with the existing TV lock. Withthreadcheck,hangaborts before sleeping;hang-rawwarns above 250 ms and signals the main thread at >=2000 ms. Writeloginto/tmp/plxnative-guardbefore launching to disable both fatal paths while retaining logs and warnings (guard=logis file-content notation).tools/stream-screen.pyis the host driver — its page maps browser clicks on the streamed picture tock:tokens (hover is deliberately NOT forwarded — it used to park app focus on a tab pill so the next ENTER opened the library). The one real trigger here is/tmp/plxnative-capture[=port](the in-app live UI capture stream: the app's own GLES frames over TCP — :8910 stable, :8911 debug, :8912 nightly when the trigger names no port (capture::default_port;make -s print-appportis the same rule for the shell, and is whattools/tv-session.shhandsstream-screen.py --app-port). Two installs cannot both bind one port and neither side says so: the secondbindwrites one line into a log nobody is tailing, and the operator then watches ONE install's picture while every key they type goes into the OTHER's FIFO. UI plane only, the video overlay is invisible to it, so the service capture stays the only way to see real playback. Two hello-selected wire modes, MPEG1-in-TS (default) and JPEG/PXFR (fallback);stream-screen.py --source app|autoconsumes either and its page switches itself. Both encoders and the measured numbers are documented where they live —capture.rs's module doc (slots, wire formats, fd ownership) andmedia-codecs/src/venc.rs(usingmedia-codecs/src/ffi.rs's verified FFmpeg ABI offsets and the RGBA→NV12-NEON colorspace path).make deployalso ships the NDK's NEON libjpeg-turbo next to the binary best-effort, which JPEG mode dlopen's). Anyplxnative-*file in the install's runtime root marks the boot as automated and suppresses the boot who's-watching picker unless it is EXEMPT — and the exemption list isdev::DIAGinrust-modules/src/dev.rs, and only that. This line used to transcribe it as the logs plus five names, and the array had already grown well past that — the GPU-time log, the hardware-counter pair, the GStreamer pair and the focus probe are exempt as well. A transcribed list, or a count, rots here without anything failing, because nothing compiles this file. Read the array; its doc comment carries the reasoning per entry, and it is the thing to extend when a new diagnostic must not move the boot screen out from under the very session it was armed to watch./tmp/plxnative-tokenbeats the stored session entirely — so headless runs always land on a deterministic Home./tmp/plxnative-pickuser=<index>forces the picker anyway and auto-picks that roster tile. /tmp/plxnative-consentis the same escape hatch for the CONSENT question, and it exists because that screen is suppressed BY the presence of any trigger — so without an override it is the one screen in the app that cannot be reached headlessly at all: arming anything to reach it is what hides it. It forces the question regardless of a stored decision, so it is also how the screen is re-examined after answering once.- The binary carries no credential that grants access to anything of YOURS — no compiled PMS
token, no demo URL, and never the Sentry auth token, which can read and delete the project and
lives only as a GitHub secret. A RELEASE build does carry two write-only ingest credentials
(
PLX_SENTRY_DSN,PLX_POSTHOG_KEY, compiled in viaoption_env!): they permit sending to a project and reading nothing from it,stringsfinds them,ci/gen-release-audit.pyprints them into the audit on purpose, andrelease.ymlREFUSES to publish without them. (FinNative's release, rc and nightly build withtelemetry: noneinstead: no credential is compiled in, andbuild-package.ymlasserts the binary carries none.) The distinction is the point, and this line read "NO credentials" flatly — which stops a reader before they reach it. A build with no credential compiled in cannot report at all, which is the guarantee that replaced the cargo feature that used to claim it. PMS access comes from the signed-in session (QR login) or, for automated runs only,/tmp/plxnative-token— whichtests/run.pyalways injects (it reads the owner token from the gitignoredsrc/config.local.hon the HOST; that macro is never compiled in). An interactive boot with no session lands on the QR sign-in screen. - Normal interactive flow: who's-watching picker (multi-user, unless Automatically Sign In is on) → Home; D-pad/pointer to focus a
card → OK opens the detail page → Play starts playback; OK toggles play/pause, LEFT/RIGHT
scrub-seek, BACK/Stop returns. The strip's last pill is Search (a mark, not a word) — a
peer of Home and the Library, not a page stacked over them, so BACK from it returns to Home. BACK
at Home's own root is the end of that chain and hands the screen back to the TELEVISION
(
app::input::back_at_root→tv::home::go_home), with the app still running — which is what the platform itself does at an app's entry page on this firmware, and what LG's submission rules require. The same rule covers three roots — Home, the who's-watching picker and the QR sign-in — which is what issues #16–#18 were: the latter two used to DROP a root BACK, because both handed it toauth::canceland ignored itsfalse. The first-run consent question was a fourth root and was NOT covered until phase 5b (2026-09-07), and the fix confirms what this section used to say about the shape of the gap: it needed a screen change, not a BACK-arm one. While the question was aPopover(ui/consent.rs),on_backwas a bareboolthat could not distinguish "stepped back a stage" from "the platform took the screen" — so the loop's BACK arm had nothing to key the root press on. The owned replacement (screens::consent.rs) answers with a request instead of a bool: BACK at the first stage asks the loop forLoopReq::BackAtRoot(app::input::back_at_root→tv::home::go_home, the same call the other three roots use) rather than stepping or dismissing, and doing so does NOT answer or dismiss the question — selecting the app's tile again lands straight back on it, exactly as Home, the picker and QR sign-in do at theirs (app/bridge.rs'sback_at_the_first_consent_stage_is_the_root_press_and_leaves_the_question_uppins both halves). BACK is no longer a quit anywhere — the remote's EXIT key still is, andcloseByAppIdis still howmake kill,tests/run.pyandtools/tv-session.shclose the app — so the/tmp/plxnative-noexitconfirmbypass went with the "Exit PlxNative?" alert it existed for (both retired 2026-09-03). Text entry is the television's own keyboard, raised by plainSDL_StartTextInput— the backend is in LG's Wayland driver, not the webOS extension API, which is whySDL_webOS.hlooks like it has no keyboard. The field, shelves, test seams and every trap in that path are documented indocs/search.md. Search is server-only by decision — Plex Discover / Watchlist catalog results are out of scope.