Decky, slimmed: a thin Gaming-Mode wrapper around the client #46
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: unom/punktfunk#46
Reference in New Issue
Block a user
Implements
decky-slim-rework{,-implementation-plan}.md— M1 through M4. M5 (the on-glass gate) has not run: the Deck was offline the whole session, so nothing here has been seen on one. See What is still owed at the bottom before merging.The Decky plugin was a second client: its own mDNS discovery, its own host-store editor, its own settings UI over the entire client settings store, its own per-game pin store and picker, its own fullscreen route with three tabs. Every one of those was a copy — in Python and TypeScript — of a rule that already lives in Rust, and each drifted from the original. They existed because when the plugin was written there was nothing headless to ask. There has been since v0.22.0.
5,340 → 2,830 lines. What is left is what only a Decky plugin can do: start a stream through Steam so gamescope focuses it, and stand in front of the trust decision that gates it.
The CLI gains two things (they ship independently of the plugin)
punktfunk discover [--json] [--timeout SECS]— built on a newdiscovery::discover_for, a bounded collector beside the streamingbrowse()the UI uses. It annotates each hit against the saved-hosts store rather than handing back two lists to join:saved/pairedare answered by fingerprint first, address second, which is what stops a host that moved DHCP lease reading as new and a different box that inherited the old address reading as paired.punktfunk launch --request-access— sets the 185 s budget (the host'sPENDING_APPROVAL_WAIT) and records the host as paired when the session reports ready. Refused under--execwith exit 5 rather than silently downgraded: under--execthe CLI becomes the session, so nothing survives to observe the approval.Plus a live bug the plan flagged as R3:
hosts add --fpwas silently discarding the fingerprint when the address was already saved, exiting 0 having done nothing — so the host stayed pinless and every later connect refused with no line anywhere saying why.The plugin
One QAM panel: update banner, hosts, the console-home door, about. Pinned host+profile cards render nested under their host as
▸ <Profile name>— a card is a (host, profile) pair, and a row floating free of its host is exactly the "a pinned tile reads as a duplicate host" problem the desktop shells still have. The plugin renders cards; it creates none.A host with nothing pinned opens a trust sheet: Request access (the host's operator approves this Deck — no PIN) or Use a PIN instead. No advertised fingerprint means the PIN path only, with the reason stated — that pin is the only thing standing between a 185 s wait and an impostor answering for the host.
The launch path becomes
punktfunk launch <ref> [--profile <id>] --exec --fullscreen, and request-access launches run supervised (no--exec) so something survives to record the approval. Wake-on-LAN comes out entirely: the plugin used to fire its own packet and stretch the connect budget to 75 s, a workaround for the CLI-less era;punktfunk launchruns the real wake-and-wait loop and only dials once the host answers.The settings screen is not lost, it moved: console home → Settings, same rows over the same store, gamepad-navigable, one tap from the same panel. Per-game pins have no shared equivalent yet —
decky-pinned.jsonis deliberately left on disk untouched so a later migration can read it. Both are stated in the release-note copy rather than glossed.A regression found by review, and fixed
An adversarial review of this branch caught something I had introduced and would not have found by testing on a Deck either.
The panel names a host by its record's stable id — which the design recommends because an id "survives renames and DHCP moves". It does. What does not is the address on the record, and
ConnectPlan::for_hostdials exactly that, while the panel renders the advert's address. After the cut nothing on a Deck writes a moved address back (discoverandhosts listare both reads; only the desktop shells' hosts pages update one). So after any DHCP move the row read "online" at the new address and every press dialled the old one — a 15 s dead connect, or a black Steam "game" for the full 90 s wake budget if a MAC had ever been learned. The old plugin was immune because it dialled the advert directly.Fixed by making
hosts add <new-addr> --fp <known-fp>move the matching record instead of filing a second one (the fingerprint is the identity — the same rule that makes the verb idempotent), and having the panel re-point a host it can see has moved before launching.Three smaller ones in the same commit:
client-unavailablewas rendered as "No hosts yet", so a Deck with no client installed was told its network was empty;browse()'s worker never exited on a LAN with no Punktfunk host (it parks inrecv(), and the ignored-event arms never touch the sender — so the doc claiming "dropping the receiver stops it" was false); and apair=optionalhost was recordedpaired: truewhen nobody had approved anything, which would have made the same box read "paired" here and "trusted" in the desktop client.Docs
clients/decky/README.mdanddocs-site/content/docs/steam-deck.mdrewritten, with a new Request access section and a plain statement of where the settings went.client-settings.mdclaimed ~18 settings were "offered by … and Decky"; none are.Verifying that file against
crates/pf-console-ui/src/screens/settings.rsalso turned up three claims that were already wrong, independent of this work: render scale is in the console home's row list; the console home does have an auto-wake setting; and its Library button is not gated onlibrary_enabled(that field appears nowhere inpf-console-uioutside its own toggle row). All three fixed here.What was verified, and how
On .21 (CachyOS), against the live LAN:
discover/discover --jsonlist a live host withsaved/pairedcorrect;--timeout 0.5returns in 0.503 s. The fingerprint-first rule proved itself unprompted — the advert at192.168.1.21matched a record saved under127.0.0.1, because that box is its own host.hosts add --fpbranches with their real exit codes, store byte-identical on the refusal.launch --request-access --execrefused with exit 5.--request-accessreachesspawn_session, everything else reachesexec_session.--connect 10.0.0.5:9777for a host answering at.99; after, one record, moved, and--connect 10.0.0.99:9777.discoverleaves a pre-mint store byte-identical whilehosts liststill mints. Ten back-to-back browses settle back to the baseline thread count.cargo fmt --checkclean, clippy clean at-D warnings --all-targets, 100 Rust tests, andpf-console-ui/punktfunk-client-session/punktfunk-client-linuxall still compile.pnpm typecheck+pnpm buildgreen; 31 backend checks pass — and pass on a re-run, which the first version of that suite did not.Closed statically because the Deck was unreachable: the flatpak installs the CLI at
/app/bin/punktfunkso--command=punktfunkresolves, and the deb installs it besidepunktfunk-clientso the wrapper's sibling assumption holds. That is the packaging half of the plan's R1.What is still owed
--exec-less launch still get gamescope focus? — is answered only by running it. If it does not, the recorded fallback is to keep--execeverywhere and have the plugin flip the record after a successful exit.deckuser's config dir. It rides the unchanged_flatpak_env()the old--pairpath already used, but it is unproven.#[cfg]is#[cfg(test)]), but unrun is unrun.Deviations from the plan
main.pyis 1,028 lines against the plan's "under ~500", and the plugin totals ~2,830 rather than the design's ~1,660. Every deleted surface is gone and an AST pass confirms nothing dead remains; the rest is kept code (the SSL-root repair, the update-registry path, the Steam configset editor) plus this codebase's comment density. Cutting further would mean deleting comments each paid for by a failure._classify_library_errorcould not simply be deleted as the plan lists —_native_update_state, which the plan keeps, needs it to spot a client too old for--check-update. Narrowed to_looks_outdated(); the CLI path uses the deterministic exit-5 +unknown commandsignature instead.Release-note copy is drafted in the plan's ledger rather than committed here, since notes are authored at version-bump time and this train bumps nothing.
`punktfunk hosts add <addr> --fp <hex>` against an address already in the store printed "is already saved" and exited 0 — having done nothing at all. The --fp was silently discarded, so a host saved by address stayed pinless and every later connect refused for want of a fingerprint, with no line anywhere saying why. Three outcomes now, and the difference between them is a trust decision: • no fingerprint on the record, one offered → fill it in, print `updated <addr>:<port>` • the same fingerprint offered again → no-op, exit 0 (a panel may retry a step whose state is already correct without having to invent an error to show) • a DIFFERENT fingerprint → refuse, exit 3 The refusal is the important one. A changed identity is a decision for a person at a surface that can show them both — the rule `upsert_trusted` exists to enforce — and quietly overwriting a pin here would be a back door through the pinning the rest of the client is built on. A record still named after its own address takes an offered --name; a label the user chose is theirs and an advert's name must not overwrite it.The plugin's settings tab, fullscreen page, host editor and games picker are gone, and the docs described all four in detail. Sweeps clients/decky/README.md and the docs site. steam-deck.md gains a **Request access** section — the no-PIN path where the host's operator approves the Deck, which is the one genuinely new thing a user gets — and says plainly where the settings went: **Open Punktfunk → Settings**, the same rows over the same store, one tap from the same panel. A removal that reads as a regression is worth a sentence, not a silence. The troubleshooting table drops the rows for surfaces that no longer exist and gains the two questions the new path will actually raise ("request access isn't offered", "the stream just sits there"). client-settings.md claimed ~18 settings were "offered by … and Decky". None are; the console home offers them. Its intro now names the console home's real sections (Stream, Video, Presentation, Audio, Controller, Touchscreen, Interface, Profiles) instead of describing the deleted sidebar. Three claims in that file turned out to be wrong ALREADY, independent of this rework, and are fixed here because verifying against crates/pf-console-ui/src/screens/settings.rs is what found them: • "Render scale — offered everywhere except the console home's list". RowId::RenderScale has been in the console's ROWS since 2026-07-31. • wake-on-lan.md: "Punktfunk Console has no auto-wake setting of its own". It does — RowId::AutoWake, "Wake hosts automatically". Its Wake & Connect BUTTON is independent of the setting, which is the true half that sentence was built on. • The console home's Library button was documented as gated on the "Show game library" toggle. It isn't — `library_enabled` appears nowhere in pf-console-ui outside the toggle row itself; home.rs offers Library on any paired, saved host. Also updated: support-matrix (Decky's Profiles and Game library go ✅/❌ → ⚠️ — the panel shows pinned profile cards but creates none, and the library lives in the console home), wake-on-lan (the plugin no longer fires its own packet or stretches the connect budget — the CLI runs the real wake-and-wait), pairing, game-library, profiles-and-links, input, clipboard and install-client.ok6267dcdcd3`{"ok": True, **data}` let a future payload carrying its own `ok` report failure through the field the shell layer owns. Spread first, set `ok` last.`KnownHosts::load()` mints a stable id for any record that lacks one and SAVES it — which makes it a write, and `discover` was calling it purely to annotate what the browse found with saved/paired. It never hands those ids back to anyone. That matters because the Decky panel issues `discover` and `hosts list` together, in parallel. Against a store written before ids existed, both processes read it, both mint DIFFERENT ids for the same record, and both save. Whichever loses the race has already handed its ids to its caller — so the panel could draw a row whose host reference no longer resolves, and pressing it would exit 5 ("no saved host matches") until the next refresh settled things. `KnownHosts::read()` is `load` without the mint: the store exactly as it is on disk. `discover` uses it; every caller that dials a host by id still uses `load`, so ids are still minted the first time anything needs one. Verified on a fixture store with no ids: `punktfunk discover` leaves it byte-identical, and a following `punktfunk hosts list` mints as before.