forked from unom/punktfunk
enricobuehlerandClaude Opus 5
6de78213ee
The stats overlay was the visible half of a general problem: nine of the client's settings had a row here and twenty didn't, so a Deck that never sees a desktop could not reach its own decoder, chroma, HDR, audio layout, echo cancellation, touch or mouse model, scroll direction, auto-wake, or either audio endpoint. Everything the store holds is here now — except the two things a plugin backend genuinely cannot answer, named in `backend.ts` so the next reader doesn't go looking: which physical pad is player 1 (SDL's live device list lives in the client process, and no CLI enumerates it) and the session's remembered window size, which is not a preference. Thirty rows is too many to scroll past on a thumbstick, so they are split across a `SidebarNavigation` — the left-rail-of-categories layout SteamOS's own Settings uses, and the one Deck users already know. Every page fits on screen without scrolling, which is the point: the rail is the index, so nothing is more than one hop away. The categories, their order and the wording of the rows are the console settings screen's — it is the other settings editor reachable without leaving Gaming Mode, and two different orders for one store is how people stop trusting either. It shows them as one steppable list because it has no pointer and no room for a rail; here they become the rail's pages. The six pages take one shared settings object rather than each holding state, so a change on one is visible on the others the moment you switch. Three more rules: - A dependent setting is INDENTED under what it depends on and DISABLED, never hidden: mic device and echo cancellation under the microphone, controller type under forwarding. The console dims those rows for the same reason, and a row that vanishes as you toggle the one above it is a moving target for a thumbstick. The device row at the foot of Audio is rendered even while it reads, for that reason. - A picker with nothing to pick doesn't appear: the GPU row shows up only where the enumeration found more than one adapter, so it is absent on a Deck and present on a Bazzite desktop with a dGPU. - A setting that behaves differently HERE says so in its own description rather than being dropped. Capture system shortcuts holds nothing back under gamescope; fullscreen-on-stream can't lose to a launch that always passes `--fullscreen`; the client's library toggle isn't this plugin's browser. Each says which. The device pickers are real, not stubs: `list_devices` reads `--list-adapters` and `--list-audio` off the SESSION binary, the same two enumerations the GTK shell shells out for because it links no Vulkan itself. It is cached for the life of the backend (that call inits Vulkan and PipeWire) with an explicit Refresh for the headset you just plugged in, and a failure — a client too old to ship the session binary — leaves the pickers on Automatic and says so instead of claiming you have no devices. `_parse_audio_endpoints` is split out and unit-tested with the malformed lines that must never reach a picker. Two smaller honesty fixes fall out of building it. A Dropdown can only display a value that is one of its options, and this store has four other writers — so a stored value the table doesn't list is carried as its own entry rather than rendering blank or, worse, showing a different value than the stream will use. And a stored audio endpoint that isn't currently connected keeps a "(not connected)" entry, the way the Linux picker keeps "(not detected)", instead of silently re-pointing the next stream at the default. The Settings tab's wrapper deliberately stops being a scroll area: a SidebarNavigation given an indefinite height to fill collapses its rail, so the pane hands it the full height and keeps its hands off the overflow, and the footer inset moves inside the pages. The docs claimed nine things about this plugin that are no longer true, and three about the console home that stopped being true when its own row set grew on 2026-07-31 (4:4:4, echo cancellation, auto-wake and the library toggle are all there in `screens/settings.rs`). Both corrected. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
punktfunk-docs
The Punktfunk documentation site: Fumadocs on TanStack Start (Vite + Nitro/bun preset).
Content lives in content/docs/ as .md/.mdx. This site is the source of truth
for the user-facing guides; design rationale lives in the internal punktfunk-planning repo.
API reference
/api renders the host's management REST API as an interactive
Scalar reference (linked from the top nav, the docs
sidebar, and the landing page). It reads public/openapi.json — a
snapshot of the repo's generated spec. Refresh it after a management-API change:
# from the repo root — regenerate the spec, then copy the snapshot in:
cargo run -p punktfunk-host -- openapi > api/openapi.json
cp api/openapi.json docs-site/public/openapi.json
Nothing in CI diffs the two, so the snapshot goes stale silently — that manual cp is the only
thing keeping them in sync. Before publishing docs, check that they match:
diff <(jq -S . api/openapi.json) <(jq -S . docs-site/public/openapi.json)
That should print nothing. Right now it doesn't: the committed snapshot predates the
/api/v1/update/check, /api/v1/update/apply and /api/v1/update/status endpoints, so the
published /api reference is missing the host self-update surface — re-copy it.
Develop
bun install
bun run dev # http://localhost:3001 (docs at /docs)
CI gates every change on bun run build followed by bun run lint (the TypeScript typecheck), in
that order — the build emits the .source typegen the typecheck imports. Run both before you push.
Build & serve
bun run build
bun run start # serves .output/ via Bun
Layout
source.config.ts Fumadocs MDX collection (content/docs)
content/docs/ the docs content (.md/.mdx) + meta.json nav
src/
routes/
__root.tsx RootProvider + html shell
index.tsx landing page
docs/$.tsx catch-all docs renderer (Fumadocs DocsLayout)
api/index.tsx Scalar API reference (reads public/openapi.json)
api/search.ts Orama search endpoint
lib/source.ts Fumadocs loader over the generated collection
lib/layout.shared.tsx shared nav chrome
components/mdx.tsx MDX component map
styles/app.css Tailwind 4 + Fumadocs preset