The host has published every lifecycle transition on GET /api/v1/events since the
API existed — client connect/disconnect, session and stream start/end, pairing
decisions, display create/release, library, store and plugin changes — and
nothing consumed a byte of it. The console instead polled ten endpoints on 1-5 s
timers, so a change was up to 5 s stale and two pages could disagree while you
looked at them. The Library page polled not at all: install a game in Steam and
it never appeared until a full reload.
The console now subscribes once and invalidates exactly the queries an event
affects. Events never carry data into the cache — they only say "this is stale" —
so an unknown future kind costs nothing and a missed event degrades to the
polling that is still there underneath, now at a slow safety-net interval. The
fast ticks that remain are the ones events cannot express: the live stream
numbers while streaming, and a lingering display's teardown countdown.
Four things had to be true for this to work, and none of them were. Each was
found by measuring, not by reading:
- Nitro's `localFetch` accumulates the response and only builds it when the
handler returns, so nothing streams through the deployed Bun server. Three
frames sent a second apart arrived together, three seconds late, when the
upstream closed — and an SSE stream never closes, so nothing would ever have
arrived. /api/v1/events gets its own route that hands back a web Response
wrapping the upstream stream, which passes straight through.
- Hydration mounts the app shell and discards it ~15 ms later. A subscription
owned by that effect opened, closed, and never came back. It is a refcounted
module singleton now, with a grace period so a remount re-attaches instead of
reconnecting.
- `getRouter()` runs more than once in the browser, and each call built its own
QueryClient. The subscription held the first, the live pages read the second,
and every invalidation went to a cache nobody was reading. One client per
browser session; the server still gets a fresh one per request, which it must.
- `invalidateQueries` only refetches queries that currently have an observer.
An event means the HOST changed, so every cached copy is wrong whether or not
something is watching it.
Two features fall out of the same work:
- **Automation** — a page for GET/PUT /api/v1/hooks. The host has run these
hooks all along and the console never showed them, so the only way to see what
your machine does when a stream starts was to open the config file. Writing one
means writing a shell command the host will execute, so saving re-asks for the
console password, like an update or an unreviewed install.
- The Host page warns when another Moonlight-compatible server (Sunshine,
Apollo) is running on the same machine. The host has detected this at startup
for ages and reported it in /local/summary; nothing surfaced it. It is the most
common reason a host looks installed and working but no client can reach it.
Verified in a real browser against a mock host: three events drive three
refetches of a query with no polling timer, the conflicts card names the
intruder, the hook list and its dialog render, and the console reports no errors.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Browser UI for the host's management REST API (mgmt.rs / docs/api/openapi.json).
Stack, exactly as specified:
- TanStack Start (Vite, SPA mode) — file-based routes, SSR shell + client hydration.
- React Query via orval codegen from the checked-in OpenAPI spec: a custom fetch mutator
(src/api/fetcher.ts) centralizes the base URL, the bearer token (Settings → localStorage),
JSON, and a throwing ApiError; the query client skips retries on 4xx. orval returns the
response body directly (includeHttpResponseReturnType:false) so a query's `.data` is the
typed payload; GET→useQuery, POST/DELETE→useMutation by method.
- shadcn/ui on Tailwind v4 (CSS-first tokens, dark-first) — button/card/badge/input/label/
table/skeleton primitives hand-authored from the canonical source.
- Paraglide i18n (en + de) with a reactive useLocale() hook and a language switcher.
Pages: dashboard (live status — video/audio/session/stream, stop-session + request-IDR,
2s polling), host (identity/codecs/ports), clients (paired list + unpair), pairing (PIN
submit, polls pin_pending), settings (API token + language).
Dev server proxies /api → 127.0.0.1:47990 (same-origin, no CORS; PUNKTFUNK_MGMT_URL to
override). Generated code (orval client, paraglide runtime, routeTree) is gitignored and
reproduced by `pnpm codegen` (prepare/pre* scripts). Validated live against `serve`: API
shapes match, dev proxy works, SSR shell renders the localized nav, build + tsc green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
enricobuehlerandClaude Opus 5