enricobuehler
102f550bba
Pass --custom-refresh-rates (patch level 3+) and --pipewire-composite-external-overlay (level 4+) on both spawn paths, with the same probe-then-pass shape the HDR and cursor flags already use. A stock gamescope has neither flag and gets neither, which is exactly today's behaviour. New knob PUNKTFUNK_GAMESCOPE_REFRESH_RATES=60,90,120 widens the set a session offers in Steam's in-session display settings. The rate the session actually runs at is always included, so it can only add options; junk entries are skipped rather than failing the host, because the worst a typo can cost is the extra option the operator wanted. And the part that would have turned a week of field triage into one log line: warn_if_mode_lost(). --nested-refresh is the ONLY refresh a headless gamescope has, and it reaches a gamescope-session-plus solely through the GAMESCOPE_BIN wrapper, which the session script is free to lose — a sessions.d file sourced with `set -a` can reassign GAMESCOPE_BIN, and one that sets GAMESCOPECMD outright skips the whole builder. When that happens the stream still runs, still looks right, and the client's own fps counter still reads the negotiated rate (the encode loop repeats the held frame), while the game underneath is capped to 60. Nothing anywhere said so. It warns rather than refusing, deliberately: verify_managed_spawn_flags refuses because its retry resolves a different plan, but a relaunch here would hand the session the same environment and lose the mode the same way, so refusing would only loop. Fails open on the same rule as the flag check — nothing to compare against says nothing. Also corrects the comment above the launch env, which claimed CUSTOM_REFRESH_RATES "generates the mode the session ADVERTISES … what makes games see the real refresh". It never did: no upstream gamescope has --custom-refresh-rates, so gamescope_has_option gated it off and the variable was inert. That belief is why the real lever went unexamined. configuration.md gains the new knob and a warning on PUNKTFUNK_MAX_FPS, which also lowers the refresh the session REPORTS on gamescope — the docs said it does not cap the stream, which is true of the wire and not of what games are told. Linux-verified on Ubuntu: cargo check --all-targets, clippy -D warnings, 133 tests (2 new), cargo fmt --check.
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