A prep entry stops naming a device, and the docs show it #422

Merged

enricobuehler merged 1 commits from worktree-prep-mode-env-example into main 2026-08-27 22:50:06 +00:00

Conversation 0 Commits 1 Files Changed 1

+64

enricobuehler commented 2026-08-27 22:49:18 +00:00

Owner

Copy Link

Copy Source

v0.32.0 (ee5e89d7, #412) gave per-app prep do/undo steps the negotiated mode —
hooks::prep_mode_env() builds PF_STREAM_WIDTH / _HEIGHT / _REFRESH / _HDR and both
serving planes pass it, adding PF_APP_ID (native) or PF_APP_TITLE (GameStream). The docs
announced the four names and left a one-liner; this adds the worked example that shows what they
are for.

docs-site/content/docs/automation.md grows a One entry, every client section: an apps.json
entry pointing at a single mode.sh, and the script itself — MangoHud capped at the refresh this
client actually negotiated, an HDR arm taken only when the session really negotiated HDR, and the
raster logged with whichever identity the plane supplied. The entry names no device, so one title
serves the 60 Hz phone and the 4K120 HDR TV from the same two lines.

The four notes under it are the things that bit me writing it, not a feature tour:

• undo sees exactly what its do saw — the values are captured once at launch and held by
  PrepGuard for the session.
• PF_STREAM_HDR is 1/0, the stream-marker file's spelling, not PF_EVENT_*'s
  true/false.
• The app identity depends on the plane, and ${PF_APP_ID:-${PF_APP_TITLE:-desktop}}'s :- also
  catches the empty string a launch with no title of its own leaves behind.
• set -u is load-bearing: an older host sets none of it, and the step then fails loudly (which
  disarms its own undo) instead of silently capping the game at fps_limit=.

Verified: the fenced sh block was extracted from the rendered doc and run under sh with
kscreen-doctor/logger stubbed — do writes the cap and takes the HDR arm, undo restores the
conf and reverses it leaving no .pf-bak, an SDR session touches HDR not at all, an empty identity
falls through to the literal, and an unset environment exits non-zero. Braces and angle brackets in
the new content are all inside fenced blocks (MDX-safe). Docs-only: no code, no schema, nothing
versioned moves.

Found while writing this, NOT fixed here — on a service-installed Windows host these variables
never arrive. The #[cfg(windows)] run_hook_process takes the env slice and then calls
spawn_in_active_session(cmdline, workdir), which has no env parameter: windows/interactive.rs
builds the block from the user's token merged with the host's own PUNKTFUNK_*/RUST_LOG
(merged_env_block), so per-call vars cannot ride along. The slice is honoured only on the
non-SYSTEM cmd.exe /C fallback (a hand-run punktfunk-host serve). That makes the paragraph's
existing rtss-cli … $PF_STREAM_REFRESH line — RTSS being Windows-only software — the one example
that does not work on the normal Windows install. The fix would be threading an extra env slice
through spawn_in_active_session into merged_env_block, which already merges one set of host
vars; left for a decision on whether to fix the code or correct that line.

v0.32.0 (`ee5e89d7`, #412) gave per-app `prep` `do`/`undo` steps the negotiated mode — `hooks::prep_mode_env()` builds `PF_STREAM_WIDTH` / `_HEIGHT` / `_REFRESH` / `_HDR` and both serving planes pass it, adding `PF_APP_ID` (native) or `PF_APP_TITLE` (GameStream). The docs announced the four names and left a one-liner; this adds the worked example that shows what they are *for*. `docs-site/content/docs/automation.md` grows a **One entry, every client** section: an `apps.json` entry pointing at a single `mode.sh`, and the script itself — MangoHud capped at the refresh this client actually negotiated, an HDR arm taken only when the session really negotiated HDR, and the raster logged with whichever identity the plane supplied. The entry names no device, so one title serves the 60 Hz phone and the 4K120 HDR TV from the same two lines. The four notes under it are the things that bit me writing it, not a feature tour: - `undo` sees exactly what its `do` saw — the values are captured once at launch and held by `PrepGuard` for the session. - `PF_STREAM_HDR` is `1`/`0`, the stream-marker file's spelling, **not** `PF_EVENT_*`'s `true`/`false`. - The app identity depends on the plane, and `${PF_APP_ID:-${PF_APP_TITLE:-desktop}}`'s `:-` also catches the empty string a launch with no title of its own leaves behind. - `set -u` is load-bearing: an older host sets none of it, and the step then fails loudly (which disarms its own `undo`) instead of silently capping the game at `fps_limit=`. **Verified:** the fenced `sh` block was extracted from the rendered doc and run under `sh` with `kscreen-doctor`/`logger` stubbed — `do` writes the cap and takes the HDR arm, `undo` restores the conf and reverses it leaving no `.pf-bak`, an SDR session touches HDR not at all, an empty identity falls through to the literal, and an unset environment exits non-zero. Braces and angle brackets in the new content are all inside fenced blocks (MDX-safe). Docs-only: no code, no schema, nothing versioned moves. **Found while writing this, NOT fixed here** — on a service-installed Windows host these variables never arrive. The `#[cfg(windows)]` `run_hook_process` takes the env slice and then calls `spawn_in_active_session(cmdline, workdir)`, which has no env parameter: `windows/interactive.rs` builds the block from the user's token merged with the host's own `PUNKTFUNK_*`/`RUST_LOG` (`merged_env_block`), so per-call vars cannot ride along. The slice is honoured only on the non-SYSTEM `cmd.exe /C` fallback (a hand-run `punktfunk-host serve`). That makes the paragraph's existing `rtss-cli … $PF_STREAM_REFRESH` line — RTSS being Windows-only software — the one example that does not work on the normal Windows install. The fix would be threading an extra env slice through `spawn_in_active_session` into `merged_env_block`, which already merges one set of host vars; left for a decision on whether to fix the code or correct that line.

enricobuehler added 1 commit 2026-08-27 22:49:20 +00:00

docs(automation): a worked example for the prep mode env ... 3b0e880b4c

v0.32.0 gave per-app prep do/undo steps PF_STREAM_WIDTH/_HEIGHT/_REFRESH/_HDR
(hooks::prep_mode_env, both serving planes), but the docs' only example was a
one-liner. Add the entry+script pair that shows the point: the prep entry stops
naming a device and reads the negotiated mode instead - an FPS cap at the
client's own refresh, an HDR arm taken only when the session negotiated it, and
the raster for whatever wants pixels.

Written so the traps are visible rather than explained: undo sees the values its
do saw, HDR is 1/0 (the marker file's spelling) not PF_EVENT_*'s true/false, the
app identity is PF_APP_ID or PF_APP_TITLE by plane, and set -u makes an older
host fail the step loudly instead of capping at 'fps_limit='.

Verified: the fenced script extracted from the doc and run under sh - do writes
the cap and takes the HDR arm, undo restores and reverses it, an SDR session
skips HDR, an empty identity falls through to the literal, and an unset
environment exits non-zero.

enricobuehler merged commit 1391de87d6 into main 2026-08-27 22:50:06 +00:00

enricobuehler deleted branch worktree-prep-mode-env-example 2026-08-27 22:50:12 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

FernandoMX FlipperDan HitFrostbite bluelightspecial enricobuehler (Enrico Bühler) kszlim luxus nannku neoney sonar

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: unom/punktfunk#422