The Windows clippy job has failed on main since a04c8cee: giving the
avatar its OS mark added `os` to `host_tile`, taking it to eight
arguments against clippy's threshold of seven, and `-D warnings` makes
that an error. The job never runs on a Mac or a Linux runner, so the
break reached main green.
Take the allow, as the two neighbours at this limit already do. All
three call sites pass a different mix of the optional tail, so a props
struct would only move the argument list into each of them.
`edit_profile_modal` and `described_overridable` sit at exactly seven
and are untouched.
140 commits since v0.33.0. The release is a control surface for everyone
who streams to a screen they hold: a six-button ring opened by a
two-finger twist, editable by using it rather than by reading a list,
plus an on-screen controller on phones and tablets.
The Steam Controller 2 passthrough leaves Linux. It now captures from
Apple and Android devices and reaches a Windows host, still presented as
itself rather than flattened into a generic pad.
This is not a drop-in for embedders. The C ABI moves 26 to 28, and v27
widens PunktfunkHidOutput from 19 to 85 bytes -- a recompile, not a
relink, with the version equality check as the guard. Every other
version number stands still: wire 2, driver 6, gamepad channel 3.
Windows packagers additionally need the pf_gamepad package rebuilt, for
its eighth hardware id.
api/openapi.json is regenerated rather than re-stamped this time, and
the surface is verified rather than assumed: punktfunk-host compiles on
macOS again, so the staleness test runs here. Every prior release
carried a caveat for exactly that reason.
Also prunes PUNKTFUNK_STANDBY_SINK_KEEP from the undocumented-env
baseline, which the drift gate has warned about since #452 documented
it while still exiting 0.
Gates on the Mac: cargo fmt --all --check, cargo test -p punktfunk-core
--lib --features quic (511 passed, 0 failed), the C ABI harness
(abi_version=28), the openapi staleness test, check-docs-drift.sh,
check-docs-links.sh, cargo audit (2 allowed warnings, no yanked
crates), both openapi copies byte-identical, and Play notes at 493/500
chars and unique.
`windows-client.yml` fails to build this branch on both arm64 and x64,
four errors, all from the commit that gave the host card an OS mark:
hosts.rs:144,145 doc comment on a function parameter
pair.rs:97 avatar(&target.name) — argument #2 missing
stream.rs:37 avatar(&host) — argument #2 missing
`avatar` grew a second parameter and two of its three call sites were
not updated. Neither has an OS chain to pass: `Target` carries name,
address, port, fingerprint, MAC and profile, and no OS field. So both
pass `""`, which is what `avatar` documents as "keeps the monogram" —
and what `stream.rs`'s own header comment already said it wanted.
The parameter comment becomes `//`. Its text was worth keeping; rustc
simply will not take `///` there.
⚠ NOT compiled locally: this crate cannot be built for Windows from a
Mac, and scripts/xcheck.sh does not carry punktfunk-client-windows. CI
is the verifier.
Both this branch and #460 fixed the same abort, independently and within
the hour. #460 merged first, patching four call sites inline; this one
routes all five through one `App::status()`, which is the better shape
and also covers the writer in `run()` that the inline pass left alone.
Conflict resolved to this branch for `win.rs`. Afterwards the file holds
exactly one `lock()` — inside the accessor — so every reader goes
through it. `check-unsafe-hygiene.sh` reports all three gates clean and
rustfmt is clean under the pinned 2021 style edition.
A field reporter installed punktfunk-gamescope under a running host
and kept streaming SDR, with no error to explain it. The host probes
the gamescope binary once per process and caches the answer, because
a session's bit depth must be settled before the display exists - so
a build installed mid-run is never seen.
The install section listed a command for every distro and never
mentioned the restart. Add it, and name the two startup log lines
that tell the two states apart.
A SteamOS-style session (Valve's /usr/lib/steamos/gamescope-session, as
CachyOS ships it) never got --custom-refresh-rates, so Steam's
in-session display menu showed one refresh entry and no resolutions,
and games paced themselves to that single number.
The two gamescope-session-plus paths hand the set to the SCRIPT as
CUSTOM_REFRESH_RATES and let it build the flag. Valve's script has
never read that variable, and the PATH shim forwards only
PF_HDR_ARGS - so the flag reached no SteamOS session at all.
Chain refresh_rate_args into that drop-in's PF_HDR_ARGS, keyed on the
session's own mode like launch_session's `offered`. Split the list
formatting into a pure refresh_rate_list so the no-whitespace
invariant that the unquoted ${PF_HDR_ARGS} depends on has a test.
Four statements had outlived the work they described, and each one
tells a reader that something shipped is missing.
The README, the roadmap and the Windows host page all said the AMD
(AMF) and Intel (QSV) encoders were CI-green only. The support matrix
— which the roadmap itself names as the arbiter — has recorded since
0.31 that AMF was validated on a Ryzen 7000 iGPU and QSV on Arc. A
reader comparing the two pages could only conclude AMD is unsupported
in the shipping build.
The roadmap listed concurrent clients under "Next", with the fact that
they already work buried in a closing parenthesis. Per-client virtual
displays have shipped for many releases; what is actually missing is
identity and per-session isolation, so the entry now leads with that.
The matrix still said no one had run a Hyprland virtual output or the
Omarchy integration on real hardware. 0.33.0 did both, end to end, on
a real Omarchy box. Only the post-theme-switch re-apply stayed
untested, so that is the one entry left standing.
Also replaces the roadmap's "shipped in 0.19 through 0.22.3" list,
eleven releases out of date, with current work and a link that cannot
go stale.
A field report on 2026-08-30: "the GTK client is just launching in
fullscreen". Reproduced on a plain GNOME desktop (.21), launched from
the .desktop entry, with no Deck and no gamescope anywhere on the box.
The shell fullscreens itself when `cli::fullscreen_mode()` is true, and
that read `GAMESCOPE_WAYLAND_DISPLAY` as proof of Gaming Mode. Our own
flatpak sets it unconditionally: `packaging/flatpak/io.unom.Punktfunk.yml`
exports `GAMESCOPE_WAYLAND_DISPLAY=gamescope-0` because the vendored
gamescope WSI layer reads that variable and nothing else to decide
whether to negotiate HDR10 (e1adc5d6, 2026-08-05, shipped in v0.25.0).
So inside the sandbox it is set on every launch, on every desktop —
verified in the sandbox on .21, where the host has neither a gamescope
process nor a socket. The flatpak is the main Linux channel, so this hit
every flatpak user on every desktop since v0.25.0.
Fullscreen was only the visible half. The same reading also meant:
- a stream ignored `fullscreen_on_stream = false` (the env ORed straight
past the flag the client resolves the setting into);
- the settings dialog swapped every dropdown for a subpage, the
workaround meant for gamescope's unmapped popovers;
- the system-button "auto" policy picked Deck rules, handing Steam/QAM
to a local Steam UI that is not there;
- the overlay-focus watcher took the gamescope path.
The variable has to keep being exported, so the fix is in what we accept
as proof. `pf_client_core::gamescope::under_gamescope()` is now the one
answer, and all six readers route through it: `WAYLAND_DISPLAY` settles
it whenever we have one (a desktop session in the sandbox still gets
`--socket=wayland`, so it names the desktop compositor — the same
mismatch the WSI layer bails on), and Gaming Mode, which runs apps as
X11 clients with no `WAYLAND_DISPLAY`, falls back to the named socket
actually existing.
Dropped the `SteamDeck` leg from the Gaming-Mode tests while here: it
says which MACHINE this is, so a Deck in DESKTOP mode was fullscreening
too. `is_steam_deck()` still wants machine identity and keeps it, but
now compares the value — Valve documents `SteamDeck=1`, and desktop
Steam exports `SteamDeck=0` into everything it launches, so the presence
check called every PC with Steam a Deck.
Verified on .21 (CachyOS, GNOME): `cargo fmt --all --check` clean; the
new `only_a_real_gamescope_counts` test passes; `cargo clippy -D
warnings --all-targets` green over pf-client-core, pf-presenter,
punktfunk-client-linux and punktfunk-client-session, with all four
confirmed really built in the log rather than skipped as fresh.
The popover collapsed to a column a character or two wide. The earlier
guess — that a ScrolledWindow asks for its minimum unless told to
propagate the natural one — was only half of it: with the horizontal
policy set to Never, `min_content_width` is IGNORED and the scrolled
window propagates its child's minimum instead. The child is a ListBox
of AdwActionRows whose titles wrap, and a wrapping label's minimum
width is one word, so the whole popover shrank to that.
`set_size_request` is a minimum GTK cannot ignore. The natural width
still grows it to fit the rows, up to the existing ceiling.
Which machine this is answers a more useful question than which letter
its name starts with, and the name is spelled out directly under the
circle anyway. The mark moves out of the status row, where it was the
smallest glyph on the card, and becomes its leading visual.
A host that advertises no OS chain — an older one — keeps the initial,
so nothing regresses to an empty circle.
GTK sets the icon on the Adwaita avatar, which needs show_initials off
first: the widget prefers initials whenever it is allowed to. The
generated background colour stays, and the symbolic mark recolors with
the theme like every other glyph there.
Windows has no theme-aware tint, so the bake changes colour with the
move: mid-grey was chosen to sit on a card face, and it read as smudged
the moment the mark landed on the accent fill. It bakes white now, and
taller, since it is a 22 DIP avatar face rather than a 16 DIP row glyph.
One bake, not two — the row was the grey one's only reader.
Three layout faults in the GTK editor, two of them one mistake.
A gtk::Box is HORIZONTAL by default and packs a single child at the
start, so a child narrower than the box's requested size lands on its
left edge no matter how it aligns itself. That put the centre disc's
mark and the shortcut preview's chord against the left rim. Both fixes
are the same: let the child expand, so its own centre alignment has
space to centre within.
The slot picker opened at its 320 px floor because a ScrolledWindow
asks for its minimum width unless told to propagate the natural one —
which wrapped entries like "Disconnect, keep the game running" into a
narrow column. It now sizes to the list, between a floor and a ceiling.
`ci / rust` has been red on main: gate B of check-unsafe-hygiene.sh flags
`.unwrap()` on the status mutex inside `wndproc`, and it is right to. A
panic crossing an `extern "system"` boundary does not unwind, it ABORTS
the process — so a thread that panicked while holding this lock would
take down the host's only visible surface, on a box where the icon is
also how the operator stops the host.
Poisoning is not a reason to do that here. What the mutex guards is a
display enum; reading it after another thread died is harmless, and
`PoisonError::into_inner` hands it over — the idiom already used
elsewhere in the tree.
Routed through one `App::status()` rather than patched at the line CI
could see. The gate is lexical, so it flagged only the call written
inline in `wndproc`; the other four sit in helpers that `wndproc` calls,
where a panic unwinds into the very same boundary and aborts just the
same. Fixing only the visible one would have left four identical aborts
a function call away and made the gate look satisfied rather than the
bug fixed.
⚠ NOT verified locally: the tray cannot be type-checked for Windows from
a Mac (aws-lc-sys' build script cross-compiles C and dies in cc-rs long
before win.rs), and scripts/xcheck.sh does not carry punktfunk-tray.
windows-host.yml builds AND clippies this crate and triggers on
`crates/punktfunk-tray/**`, so CI is the verifier here.
`check-docs-drift.sh` requires `docs-site/public/openapi.json` to be a
copy of `api/openapi.json`, and the regeneration in the previous commit
updated only the source. The docs site would otherwise publish a
description the API no longer carries.
Caught by the gate, which is what it is for. Its remaining output — the
`PUNKTFUNK_STANDBY_SINK_KEEP` baseline entry that c02c3ec1 documented
and did not prune — is informational and does not fail the job.
Adding the font codepoint to the shared table widened every ALL entry
to three fields; the console's parse-and-fit test still destructured
two. Test-only, so the plain build stayed green and only clippy
--all-targets caught it.
Both desktop editors offered "Swap with <clock>" rows beside the
catalogue. Dragging one disc onto another already swaps them, and any
slot can be set outright from the catalogue above — so the six rows
only made the list longer.
On Windows the card also carried a title naming the slot and a Done
button. The band above the ring names the slot being edited, the open
disc is ringed white, and a pick now closes the card, which is what the
GTK popover always did. Neither had anything left to say.
Clippy caught both, and both are the conversion's own shadow: DIM_INK
lost its last reader when the ring's mark stopped being an opacity on
an Image, and the reset button's armed/unarmed icons collapsed into the
same call once the white bake was gone. The accent fill already says
the button is armed, and the glyph takes the on-accent brush itself.
Baking PNGs was the wrong call and it showed twice over. Reactor's
`.icon()` builds a BitmapIcon with `ShowAsMonochrome(false)` and no
size, so a baked mark is stuck at ONE colour on every theme and renders
at its source pixel count read as DIPs — a colour that never matches
the theme, and a size each control template clamps or does not.
Draw Lucide's own icon font instead. A FontIcon is sized by the control
and tinted from the foreground brush, exactly as the SymbolIcon it
replaced was: white on an accent button, the theme's colour in the
sidebar, and a vector at any DPI. The ring's discs take the same glyph
through a TextBlock, where the size is the ring's geometry and the ink
is white because a disc is dark on both themes.
Three PNG bakes, the two-colour split, the LOCALAPPDATA materializer
and its cache all go. What replaces them is a codepoint per icon in the
shared table and one 664 kB font.
The font reaches the exe by two routes, because ms-appx:/// resolves to
the install folder either way: build.rs stages it for a dev build, and
it is checked in under packaging/assets for a shipped one, which
pack-msix.ps1 copies into the layout the MSIX, the installer and the
portable zip are all packed from. That script now fails loudly if it is
missing — every icon would otherwise ship as a private-use box.
CI gate C counts `env::set_var` mentions per file and this file was at
its baseline of five, so the field leg's sixth copy failed the build.
Raising the baseline is what the gate tells you not to do, and it would
have been the wrong answer anyway: the six copies were the same two-line
safety argument written out six times, which is precisely the shape a
ratchet exists to discourage.
`arm_test_readback` takes the GPU lock guard BY REFERENCE. `env::set_var`
is safe to call and unsound from a live multithreaded process, so "the
caller holds the binary-wide lock" is the entire safety argument — and a
borrow states it in the type system, where it cannot drift out of date,
instead of in prose repeated at each call site.
The file drops from six mentions to two (the call, and the doc comment
that names the API it is arguing about — gate C counts comments too, by
design, and writing around its grep would be gaming it). The baseline
moves 5 -> 2 to match, so the ratchet stays tight rather than merely
satisfied.
Gates: fmt, clippy --all-targets and 197 lib tests clean;
check-unsafe-hygiene.sh gate C now passes. Gate B's punktfunk-tray
finding is untouched by this branch and fails identically on main.
`ci.yml` fails `mgmt::tests::openapi_document_is_complete_and_checked_in`
with its own instructions:
api/openapi.json is stale — regenerate with:
cargo run -p punktfunk-host -- openapi > api/openapi.json
Nobody could see it: the unsafe-hygiene gate sits six steps earlier in
the same job and has been failing since 0329afcb, which skips Test.
The drift is one line and no API surface at all. `7d61c968
feat(vdisplay/windows): standby sinks are neutralised by default`
rewrote the doc comment on `DisplayPolicy::pnp_disable_monitors` — that
comment IS the schema description — and did not regenerate the file.
Structurally the regenerated document is identical: no path, schema or
property is added or removed, and the only textual change is that one
description string. So this carries no platform flavour despite being
generated on macOS.
Refs #451
Every button's icon rendered enormous. Reactor's `.icon()` builds a
WinUI BitmapIcon and drops it into the control with no size set, and a
BitmapIcon measures at its source PIXEL count read as DIPs — where the
SymbolIcon it replaced self-sized to its glyph. The bake was 128 px, so
every button carried a 128 DIP mark.
It looked correct in the settings sidebar, which is what hid it: a
NavigationViewItem's template clamps its icon, an ordinary Button does
not.
Bake the button marks at 16 px instead, Segoe Fluent's optical weight
in a button. The ring keeps a large bake of its own, because it draws
through Image, which takes an explicit width and height — so a big
source there buys resolution rather than size.
The test asserts the ring bake stays much heavier than the button one:
collapsing the two back into a single bake is exactly the mistake, and
it is invisible until someone opens the app.
The extraction matched on `sha256=`, which ffmpeg's framehash muxer
does not emit: its data rows are `0, <dts>, <pts>, <duration>, <size>,
<bare hex>` and the algorithm is named once in a `#hash:` header. So
the reference file came out EMPTY and the script reported "ffmpeg=0
frames" — indistinguishable, to a reader, from ffmpeg having failed to
decode the capture at all. Take the last comma-separated field of every
non-comment row instead.
A capture taken over a lossy link holds AUs whose references never
arrived, and ffmpeg conceals those differently from us — so a divergence
at one of them says nothing about this decoder. Recording the AU indices
(and printing the verdict last) is what separates "our bug" from "the
field lost packets", which is the only reading that makes a field diff
actionable. Split out of a dropped commit whose other half was wrong.
The golden parity legs only decode streams our hosts never emit, and the
field defect they cannot see is exactly the one two Deck reporters now
show: a smear that accumulates through the reference chain while every
integrity counter stays at zero. The full client audit (wire, planner,
params conversion, slots, scope, ring, submission, caps/session) found
no defect by inspection, so the fix needs the first divergent frame off
real silicon.
This leg turns any PUNKTFUNK_DUMP_VIDEO capture into that number:
PF_VKD_FIELD_STREAM points at the .h265 (the .idx sidecar is honoured
when present, complete==0 lines skipped), the join point is found the
way the client found it (plan until an AU succeeds), and every
delivered frame is read back and hashed to <stream>.pfhash in display
order. Per-AU errors are tolerated and counted, off-size frames from a
mid-capture renegotiation are released unshown, and PF_VKD_FIELD_YUV
dumps named frames' planes for eyes-on inspection.
scripts/vkdecode-field-parity.sh is the other half: ffmpeg -f framehash
over the same bytes (nv12/p010le match the readback's packing exactly),
first divergent index, ffprobe facts for the divergent picture.
consume_frame now returns the planes and the hashing moved to its
callers, which is the whole extent of the change to the golden legs.
`ci.yml`'s unsafe-hygiene gate has been failing on main since 0329afcb:
punktfunk-tray/src/win.rs:675: unwrap/expect/panic! reachable in
extern fn `wndproc` (no catch_unwind)
It is right to. A panic crossing an extern boundary aborts the process
since Rust 1.81, so a poisoned status mutex would take the tray icon
away with no way to get it back — the failure the supervisor work in
that commit exists to prevent.
Every read of that mutex now uses the poison-tolerant form this
workspace already uses in 192 other places. Four sites, not the one the
gate named: `wndproc` also calls `update_icon`, `notify_on_connect` and
`show_menu`, and all three read the same lock the same way. The gate
scans only the extern function's own body, so it saw one of four
identical hazards.
The writer in `run()` is left alone. It is the poller thread's callback,
reached by no extern function, so a panic there unwinds normally.
Refs #451
The stage was a diagonal purple-to-teal gradient, baked to a BMP on
disk because reactor's brushes are flat. It read as a different app,
and the console's editor had already dropped its own for that reason.
It is now a flat card face, and the bitmap writer goes with it.
The discs carried short words and no icons at all. They now draw the
slot's Lucide mark from the shared table, the centre draws the ring's
own `more`, and the name of the disc under the pointer reads out in a
band below the ring — the band the other four editors already have,
and where the name went when the words became marks.
Reset stops being a drop-down menu labelled "Reset…" and becomes the
console's armed row: "Reset to default", then "Press again to reset",
with the line about what it removes under it. Same two presses, same
words as every other client.
The rest of the shell's icons move from Segoe Fluent symbols to the
same Lucide set. WinUI cannot tint them: reactor builds every
BitmapIcon with ShowAsMonochrome(false), so each mark ships baked in
two colours — mid-grey for ordinary surfaces, white for accent-filled
buttons and the ring's dark discs.
The editor is meant to BE the ring, but its discs carried short words
where the in-stream ring carries icons, and it sat on a purple-to-teal
gradient the console's editor had already dropped as decoration. Two
different pictures of one control.
Discs now draw the slot's Lucide mark from the shared table, the centre
draws the ring's own `more`, and the stage is a flat card face like
every other card in this shell.
The rest of the shell's icons move to Lucide too, so one page does not
sit in a different icon language from the page before it. GTK strokes
the same path data with gsk and cairo that Skia strokes on the console,
in the widget's own CSS colour — which is why a mark on a ring disc
comes out white without a second asset: `.pf-ring-disc` says so.
Three status-page illustrations keep their Adwaita names: AdwStatusPage
takes an icon name or a paintable, and a paintable cannot read the
widget colour without a GtkSymbolicPaintable subclass — more machinery
than three decorative empty states are worth.
The console already drew Lucide marks, but only the console: its path
table was private to pf-console-ui and its slot-to-icon map lived in
ring.rs, so the two desktop editors that configure the same ring could
not reach either. The GTK editor drew words on its discs and the WinUI
editor drew words too — three shells, three vocabularies for one ring.
Move both tables down into pf-client-core, where every Rust client
already looks for the ring's model, and derive them from masters in
assets/lucide so a mark cannot drift between shells.
The console's icons.rs keeps aliases only for the marks its own chrome
draws. A slot's mark is no longer among them: the shared table hands
out a NAME, which `by_name` resolves — one lookup rather than an alias
per slot, and no second list to fall out of step with the first.
The icon test widens from the 19 marks the console named to all 34 the
workspace ships, because two more shells now stroke the same strings
and neither has a parser of its own to fail loudly.
A device asking to pair showed up only on the Pairing page. Anywhere
else in the console nothing said it had happened, so a request waited
until someone thought to go and look — worst on a phone, where that page
is several taps away.
The host already publishes the knock as a `pairing.pending` event and
the console already subscribes, so this hangs a toast off the frame
that was arriving anyway. It names the device from the event's own
payload and offers one button through to the Pairing page.
The same event now also invalidates the pending list itself, which it
did not: it refreshed the status card and the pairing status, and left
the list an operator actually sits and waits on to its own 10 s timer.
The action navigates rather than routing: this module is not a
component and has no router to reach. It costs a page load, on a button
someone pressed on purpose.
Refs #294
On an Apple TV the wake prompt was a dead end: the host failed to wake,
and neither Cancel nor Try Again could be pressed with a controller.
`ConnectOverlay` and `TrustCardView` each mount a zero-size view that
owns a `GamepadMenuInput` for the overlay's lifetime, and both gated it
to iOS and macOS. That is not tvOS being driven some other way — the
console home underneath runs the same binding there, and it gates itself
inactive while an overlay is up, so with no binding in the overlay
nothing read the pad at all. The trust card had the same hole, between a
pad-only Apple TV and every unknown host.
`GamepadPrompt` keeps its exclusion: it replaces system alerts that the
tvOS focus engine already drives, which its own header says.
Both bindings need an EXTENDED gamepad, the same thing that turns the
console UI on, so this covers the takeover exactly. A Siri Remote is not
one and reaches these buttons through the focus engine or not at all;
whether focus lands in either overlay is unverified and not addressed.
Refs #453
An Nvidia Shield shows "Rumble on this phone" and "Gyro from this phone"
in Controller settings. Both rows are about this device's own body, and
a TV box has none — so on a Shield they are worded for hardware that
isn't there and promise something the box cannot do.
They were gated on the hardware alone, on the assumption that a TV
answers no to a default `Vibrator` and to a SensorManager gyroscope. A
Shield answers yes to both. The likely route is the attached controller
owning the vibrator and the gyroscope the queries find, but the form
factor is the honest gate either way.
Gated at the call site rather than inside `deviceBodyVibrator`: its two
other callers — the console's menu haptics and the in-stream mirror —
want exactly the vibrator it returns today, whatever the form factor.
Fixes#449
The third-platform seam has no gate, which is why it rotted: the
unguarded call sites went from 9 to 11 in the four weeks after they were
first counted, and each one was only found by someone running the check
by hand.
Its own workflow rather than a job in apple.yml, for two reasons. That
file's paths filter is deliberately narrow — punktfunk-core and the
Apple client — because the mac mini is shared and an xcframework build
is heavy, so a host-crate edit would never have fired it. And its
`distribute` job is `needs: swift`, where anything that later grows the
same dependency can block a TestFlight upload over a host compile hole
the client has no part in.
`cargo check`, not clippy, and no `-D warnings`: the graph carries code
that is dead on macOS, and failing on that would only teach people to
ignore the gate. It asks one question.
Refs #299
`cargo check -p punktfunk-host` failed on macOS with 11 errors across
six files. Not one was missing functionality: every one was a call site
or a dependency that assumed Linux-or-Windows without saying so, and the
count had grown from 9 to 11 in four weeks with nobody working on macOS.
`opus` and `libc` were declared only for the platforms with a capture
backend, though the code reaching for them is portable — the mic pump
just decodes, and both `hooks.rs` helpers are already `#[cfg(unix)]`.
`pf-vdisplay` re-exported `try_recover_session` and
`cancel_pending_tv_restore` behind a Linux gate even though both already
carry off-Linux arms. `cursor_blend_for` split on Windows rather than on
Linux, so a third platform fell into the arm holding the VAAPI/CUDA
terms that exist only there. `gamelease` reached past `procscan`'s own
platform-neutral wrappers to `Scanner::system()`, which the module's
documented boundary says it must not.
That last one now goes through a new `procscan::alive`, which builds a
scanner per call exactly as the `names` and `resolve` wrappers beside it
do — two syscalls on Linux, a unit struct on Windows.
Linux and Windows behaviour is unchanged.
Refs #299
Two platform breaks from the branch's first full CI run, invisible to
the local gates.
Android's cargoNdkClippy rejected the ring's in-stream surface as dead
code, and it is right: the Android console holds the ring solely as
the editor, so `input`, `take_command`, `take_cmds`, `damage`,
`animating` and `key` (and the shell's `send_cmd`, and
`MenuList::animating`) are driven only by the desktop overlay. They
wear `cfg_attr(android, allow(dead_code))` rather than a cfg — cfg'ing
them out cascades into their parameter types' imports — and the
`host_actions::{self}` import shrinks to the one name every platform
uses, with the desktop-only call fully qualified.
Windows failed on the two `overlay_focus::gamescope_session()` calls
T17 and the touch-devices log added: `overlay_focus` exists only on
Linux (there is no gamescope to be inside anywhere else). Both go
through a new `in_gamescope()` that answers `false` off Linux.
Verified: the container gate green (64 / 242 / 227); clippy
`-D warnings` for pf-presenter and the Windows client on the Windows
box. The Android lints have no local run (cargo-ndk clippy dies in
audiopus's cmake on a Mac) — the fixes answer exactly the four errors
in the CI log, and CI is the check.
`abi_version_is_pinned` still asserted 27. The v28 bump (the touch
capability, `punktfunk_connection_host_caps2`) arrived in Phase 0
without the pin update the test's own comment demands, and no gate on
this branch ever ran punktfunk-core's tests — the PR's first full CI
run is what caught it. The pin now says 28, with the v28 line beside
it. Container tests: punktfunk-core 512 green, the pin suite included.
A power action ended every session and waited one second before asking
logind, but that teardown is asynchronous: the stream loops have to
notice the quit flag and drop the display lease, and the same wait gets
1500 ms in native/handshake.rs. Nothing verified the display was gone.
Going under on top of a live display is not a transient. The linger
deadline is a std::time::Instant, and CLOCK_MONOTONIC does not advance
while the box is suspended, so the box wakes with the stale display
standing and its window unspent. On a SteamOS managed takeover that is
a headless gamescope session holding the box's own panels DPMS-off.
Pinned displays are exempt. KeepAlive::Forever means until host
shutdown or an explicit release, and on gamescope's bare spawn that
keep-alive covers the nested session and its game, so releasing a pin
here would kill a running game on every sleep.
The docs-drift gate flags PUNKTFUNK_* names in code that the docs never
mention, and this branch carries two: `PUNKTFUNK_HOST_CAP2_TOUCH`, the
v28 ABI capability bit — a quoted literal only because cbindgen.toml
renames the C constant, not an env var anyone sets — and
`PUNKTFUNK_STANDBY_SINK_KEEP`, the vdisplay standby-sink neutraliser's
operator opt-out, which is not this branch's feature to document. Both
take the gate's own escape for deliberately internal knobs: a line in
scripts/ci/docs-undocumented-env-baseline.txt. The check runs green
locally with them.
"All text looks boring and ugly" — the dial's discs carried short words
because the console has no icon font. It still has none: the icons are
Lucide v0.462.0 (ISC), each one carried as its 24×24 SVG path data in
`icons.rs` — every shape of the source SVG folded into one path string
by scripts/gen-lucide-icons.py (a leading relative `m` is absolutised,
since concatenation would re-anchor it) — parsed by Skia's own SVG-path
parser and stroked at Lucide's native width 2 with round caps, scaled
to whatever box the caller gives. A designed, consistent set, rendered
exactly as drawn, for a page of string constants: no font ships, no
dependency lands, and every mark takes the console's paints.
On the dial: End stream, Leave, Touch mode, Keyboard, Stats, Mic (and
its struck twin while muted), Virtual controller, Send text, the three
host powers (moon, cycle, power) and the centre's ellipsis. A shortcut
keeps its stacked keycap chord — its content IS text — and an unknown
host action falls back to its label, so nothing the set cannot name
goes blank. An empty slot in the editor shows a faint plus; in-stream
it stays plain glass.
The hint bar's gamepad glyphs joined the same language, because they
were three dialects: solid floating triangles beside badged letters,
two ink alphas, three container treatments, and a keycap hairline that
never scaled. Now the directional marks are the set's chevrons (a
direction is not a button, so they stay badge-free), the remote's back
arrow is the set's return mark inside its badge, every container wears
the same scaled hairline, and the PlayStation shapes grew to match the
letters' weight, round-joined.
Licensing: LUCIDE-LICENSE sits in the crate and the notices generator
lists it as vendored third-party source; THIRD-PARTY-NOTICES.txt is
regenerated, which also catches the file up with this branch's real
lockfile (nine crates left, chacha20 moved — the committed baseline
was stale).
Tests: every icon parses and stays inside its 24-unit box; every
built-in slot maps to an icon while shortcuts and unknown host actions
stay text.
Two from the Nothing Phone's gamepad UI, both scale bugs the Deck's
scale of 1 could never show.
The "second fill with a different border radius" behind the dial was
the stage's focus halo. `focus_halo` takes its corner in DESIGN units
and scales it itself, like `panel` — every other caller passes it that
way — but the editor handed it an already-scaled corner, so the halo's
rounding grew with the SQUARE of the display scale: identical to the
stage at scale 1, a visibly rounder ghost card at the phone's ~2.
The dial was tiny because the fit reserved 140 design units for the
shortcut rows below the stage. A phone's console scale is
max(min(w,h)/800, density·0.75) — landscape leaves ~380 units of
content height, and the reservation crushed the ring to about half
size. Now, when the fit-below falls under 0.75 and the screen is wide
enough, the shortcut rows move BESIDE the stage and the ring scales to
the height instead — near full size on a landscape phone. The couch
layout is untouched: its fit-below is over 1, so the rows stay under
the stage exactly as the Deck shows them.
Two more from the Deck.
The picker's scrim stopped at the content rect, so the heading above it
stayed bright — a band instead of a modal. The shell only translates
the canvas (insets, transitions), it never clips a screen to its rect,
so the scrim now overshoots every edge by more than any heading, hint
bar or inset can be. The hint bar draws after the screen and stays
legible; it already carries the picker's own controls while it is up.
The dial was cut off at the top — and the cause was the overshoot
clamp of the previous commit, not the stage. The stagger normalisation
divides the per-slot lag out, so `q_raw` sits ABOVE 1 for the early
slots whenever `shown` is near 1; the old code clamped travel at 1, the
new clamp at 1.15 parked slots 0–2 up to 15 % past their seats FOR
GOOD, and the 12 o'clock disc rode out of the stage's clip. Only the
spring's excess past 1 overshoots now (`q + (shown − 1).max(0)`), so at
rest every disc sits exactly on its seat, in the stream and in the
editor alike; the centre's pop follows the same rule.
And for every window the stage cannot fit at full size: the editor
computes a fit from the rect's height (keeping room for the caption and
two shortcut rows) and the stage's width, scales the stage by it and
draws the ring at the same reduced scale — so the ring is never
clipped, whatever the screen; on the Deck the fit is 1 and nothing
changes.
Five things the Deck showed in one session, and one it could not.
The sheet opened empty. The stream overlay redraws only when
`Ring::damage` changes, and that key held only discrete state — the
sheet's `MenuList` fans its rows in on a mount entrance, its focus
eases and springs, none of which the key knew about, so the rows sat at
their first frame (unrisen, invisible) until a cursor move forced one
more redraw. The same gate quietly stalled the ring's own arrival short
of 1 once its steps fell under the key's quantisation. `MenuList` now
reports `animating()` from a settled flag it computes at the end of
every render (no entrance, every ease landed, every spring at rest, the
scroll where it wants to be — the eases are landed explicitly, an
approach never arrives on its own), and `Ring::animating()` folds it
in with its own spring, its highlight eases and its wind-in; while any
of that is true the key hashes a frame counter that `tick` advances, so
the overlay draws every frame until it has all landed and then goes
back to costing nothing.
With the loop fixed the ring could be made to look like something. The
arrival is a spring (`springs::RING`, a whisker of overshoot the six
discs carry into their travel and their size, staggered as before), the
discs sit on a soft shadow with a rim of light on their top edge, the
pad's highlight is a glow and a ring at an eased amount per disc so it
travels between them instead of snapping, the scrim is a pool of shade
around the ring thinning to a veil, the label rides in with the ring,
the sheet rises into its seat under a shadow while its rows fan in, and
a closed ring winds back in and fades instead of vanishing — closed for
input at once (`open`), drawn a moment longer (`visible`). Reduce
motion keeps the crossfade it had. The theme owns the four new paints.
The editor handed focus to the shortcut list when the stick pointed at
6 o'clock: the walk fired on any `Move(Down)` at slot 3, and the stick's
own move rides behind its sector in the same sample. It now walks on a
D-pad Down there, or on the stick pushed down a second time once its
first push put the highlight there; never on the move behind a sector
(`stick_engaged`), and the move that follows a sector-walk is swallowed
so the list is not stepped twice. Coming back up, the ring adopts a
still-held stick so its repeats step nothing until it lets go.
The shortcut editor was its own thing — chips, a hand-drawn grid, a
name box — with a focus halo nothing else on the shell uses, which on a
Deck is invisible. It is now the console's form grammar: a `MenuList`
of rows (Name, Key, Hold with Ctrl/Alt/Shift/Win as stepped On/Off
rows, Add/Save, Remove) under the disc as the ring will draw it; the
name opens the keyboard tray as the add-host screen does, the key opens
a key tray of the same shape — the 66 keys laid out like a keyboard,
drawn the keyboard tray's way: flat keys, the focused one filled with
the accent, the chosen one washed with it. Row focus is the list's own
lift and tint; key focus is a solid accent face.
Touch on the Deck: the user's twist did nothing in Gaming Mode, and the
log shows why it cannot be diagnosed yet — no T17 notice, no finger,
nothing. The presenter now logs SDL's touch devices (id, kind, name) at
connect, the first direct finger of a session, and once, a finger from
a non-direct device it ignores. §5.5 stays unverified; the handoff
carries the evidence and the question.
Tests: the ring's damage key changes per tick while animating and not
once settled; the shortcut rows follow the draft; the key tray walks
like a keyboard. The grid, draft and column tests stay.
The standby-sink opt-out shipped in 7d61c968 with no docs-site page owning
it, so the docs-drift ratchet in check-docs-drift.sh has failed on every
commit since. It is an operator-facing knob, not an internal one, so it
belongs in the Windows host table rather than the undocumented baseline.
The tray died on every upgrade and stayed dead until the next sign-in. The
update-specific remedy only covered console-initiated updates, and only when
the previous binary already recorded the intent — winget, a hand-run setup and
a plain crash all still ended the same way.
Worse, the relaunch it did manage joined the service worker's kill-on-close
job object, because spawn_in_active_session never asked to break away. Every
process that call launches — the tray, the user's game, a hook — was therefore
reaped when the service stopped, contradicting its own documented contract.
The host now supervises the tray for its whole lifetime, gated on the HKLM Run
value the trayicon task writes. That covers every way a tray can die and needs
nothing from the version that ran before, so the intent record's
tray_was_running flag goes.
The icon's lifetime tracks the host's in both directions: the menu's exit
entry stops the host, and says so. Only that entry does — a sign-out and the
uninstaller's --quit still leave a headless host running. The uninstaller now
removes the service before the tray, so the supervisor cannot put one back.
Three things the Deck showed in the gamepad UI's Quick actions editor.
The stick stepped the highlight one slot per flick, like a list. The
design (§2.6, D12) wants the weapon-wheel idiom: the stick's angle is
the slot, neutral is the centre, the D-pad steps. The stick only ever
reached the ring as a four-way `MenuEvent::Move`, quantised inside
`MenuNav::poll`. `menu_nav::ring_sector` now reads the raw sample: past
the deadzone by magnitude (a diagonal counts) the angle falls into one
of six 60° sectors centred on the slots; an engaged sector holds until
the stick drops under `MENU_RELEASE` or the angle leaves it by 5°, so a
stick resting on a boundary never flickers between two slots. The poll
emits `MenuEvent::Sector(Option<u8>)` on change, BEFORE the same
sample's buttons and `Move`, so the ring has engaged the stick by the
time the move that would have stepped it arrives and an A in the same
sample lands on the slot the stick points at; a sector the snapshot
adopted silently releases silently. While engaged the ring ignores `Move`
(the stick's own repeats included) and the D-pad steps again once the
stick lets go. In-stream, neutral highlights the centre; in the editor
the centre is inert, so neutral leaves the slot where it is. Every
list ignores the new variant through its wildcard arm; Android maps
integers INTO `MenuEvent` and is untouched. Android and Apple still
step four-way — their routers quantise the stick before the ring sees
it — and owe the same event.
The stage under the ring was a purple-to-teal gradient. It read as
decoration on the Deck, so it is the flat card face every other card on
the shell uses; `theme::stage_gradient` is gone.
The label under the ring — the highlighted slot's name, or the editor's
"press A" hint — sat at centre + radius + slot diameter, 328 units into
a 330-unit stage clipped to its rounded rect, so only its top edge
showed. The stage now sizes itself from the ring's own geometry (the top
slot, the bottom slot, `ring::LABEL_H` under it, one pad each side) and
the ring sits one pad below the stage's top, so nothing of the ring is
ever clipped. The caption says the stick points.
Tests: `ring_sector` for the six centres, the magnitude deadzone, the
overlap hysteresis and the release threshold; the poll's ordering and
change-only emission; the ring's stick/D-pad handover in-stream and in
the editor.
Design §3.3 in the Windows client, a Quick actions section of the
settings page drawn with the reactor's own elements. Six discs sit on
the ring's geometry over a gradient stage in a `Canvas`; the stage's
pointer handlers own the carry (a pointer that leaves a disc stops
reporting to it, so the discs cannot), a click on a disc opens its
picker, a disc carried onto another swaps the two. A row of six
buttons under the ring gives a keyboard and a screen reader every
slot the pointer reaches. The picker is a card: the catalogue by
group, the current pick accented, an entry this shell cannot serve
disabled with its note, and "Swap with…" as a menu.
The shortcuts follow: a row each with its keycap, Add, and Reset
behind a menu (the second press). The editor: the disc as the ring
will draw it, the name, the four modifiers as toggles, the key on a
keyboard-shaped grid of toggles — or "Press the chord…", which arms an
accelerator per key and Ctrl/Alt/Shift mix and fills the chord from
the one that fires (the Windows key stays a toggle: the shell never
sees a chord Windows owns). Save, Remove, Cancel.
Every edit commits at once through the page's `commit`, so the
profile scope's absorb records the whole ring (D10) and the page's
override marker shows it. WinUI's brushes here are flat, so the stage
gradient is a 24-bit BMP written once beside the art cache and loaded
as a file URI, with a flat tint if it cannot be written.
Gates: clippy `-D warnings` and the section's unit tests on the .133
Windows box. Not yet on glass.
Design §3.3 in the GTK shell, on the toolkit's own widgets so its
focus, drag-and-drop and screen reader carry the editor. A Quick
actions row on the Input page opens a subpage: six round buttons on
the ring's own geometry over a gradient stage, the inert centre, and
the name of the button under the pointer or the focus. A click picks
what the button holds from a popover — the catalogue by group, each
entry's availability note, the current pick marked, and "Swap with…"
for a keyboard; a button dragged onto another swaps the two (GTK4
`DragSource`/`DropTarget`, the slot as a `u32`). Under the ring the
shortcuts as rows with their keycap, Add shortcut, and Reset to
default behind an alert.
The shortcut editor is its own subpage: the disc as the ring will
draw it with its legend, the name as an `EntryRow`, the four modifiers
as toggles, the key on a keyboard-shaped grid of toggles — or "Press
the chord…", which takes the next real key press and fills the
modifiers and the key from it (`gdk::Key` → the chord's names). Save,
and Remove for an existing one.
The blob lives in the dialog's state and is written with the other
rows when the dialog closes, so it obeys the dialog's scope model: in
a profile the row carries the override marker on the first edit,
`commit_profile` writes the whole ring (D10), and the reset puts the
inherited blob back. The row's subtitle is the ring in order.
Gates: container fmt, clippy `-D warnings` and build for
`punktfunk-client-linux`; its tests under Xvfb, with two new ones for
the key names and the summary. Not yet on glass.
Three desktop editors of the ring are about to exist — the Skia
console's, the GTK shell's and the Windows client's — and design
tenet 3 says share the model, not the renderer. So `pf-client-core`
now owns what every editor was restating:
- `overlay_actions::catalogue(cfg, platform)`: the groups, entries and
availability notes an editor lists, in one order, with the desktop's
notes (no virtual controller, no typed text) where the phones have
none.
- `ring::{RING_RADIUS, SLOT_DIAMETER, CENTRE_DIAMETER, slot_angle_deg,
slot_offset}`: the ring's geometry at 100 %, so three drawings of it
cannot drift apart (tenet 8).
- `OverlayConfig::{upsert_shortcut, remove_shortcut}`: a new shortcut
takes the next id and the first empty slot; an existing one changes
in place; a removed one empties its slot — the same on every client.
The console's editors read these instead of their own copies; the
tests moved with the code.
The access chip stood for the whole of any limited session, at every
stats tier including off. A pill that never goes away reads as
distraction rather than information, and the fact it carries — what
this session may do — is one you check occasionally, not one you watch.
Gate it on the stats overlay in the three clients that draw it: the
presenter (and so the Linux and Windows clients, which spawn it),
Apple and Android. tvOS already stated it as a line inside the stats
HUD and needed no change. The expiry toasts stay at every tier — they
announce a change rather than describe a state.
On Apple the stats tier joins the badge stack's animation list, or the
chip pops on the toggle the way the motion hint used to.
Design §3.3 on the Skia console, done the way the phones have it. The
six "Ring, N o'clock" rows stepped with ◀ ▶ and the form that stepped
a key name through sixty entries are gone; one Quick actions row opens
`RingEditorScreen`: the in-stream `Ring` — the same type, in a new
editing mode — full size over a gradient stage. With a pad, the stick
or D-pad walks the slots, A opens the catalogue by group (Session,
Input, View, Audio, Host, Shortcuts, Empty, each with its availability
note and the current pick marked), Y lifts a disc and A drops it on
another to swap, B puts it down or goes back. With a pointer, a click
on a disc picks, a carry onto another disc swaps — `PointerKind::
Release` finally has its gesture. Under the ring the shortcuts sit as
rows with New shortcut and Reset to default (two presses); Down past
6 o'clock walks into them, Up from the top walks back.
`Ring` gains `edit_at` and an `Editing` state: no scrim, no idle
close, the centre dimmed and inert, the three power slots previewed
as a host that offers them would show them (a dimmed "does not offer
it" lied about the slot), a lifted disc raised, a carried disc under
the pointer, and `EditEvent::{Pick, Swap}` out through `take_edit`.
Nothing fires. The one desktop-only thing it read, the host-action
cache, is behind a cfg now, so the ring — and with it the editor —
compiles for the Android console too, which is the pad editor there.
Shortcut discs draw as stacked keycaps (the modifiers small on top,
the key large under them) in-stream and in the editors alike.
`ShortcutEditorScreen` replaces `RingShortcutsScreen`: the disc as
the ring will draw it with its legend, the name on the on-screen
keyboard (Steam's on a Deck), the four modifiers as chips, and the
key on a keyboard-shaped grid — every name `key_vk` knows, six rows
laid out as a keyboard lays them, walked with the stick (Up and Down
keep the column) or clicked — then Save, and Remove for an existing
one. A new shortcut still takes the first empty slot.
Left as it was: the console edits the global blob only (D9's scope
picker is still owed), and a swap on the console has no spring — the
discs change in place.
Gates: container fmt, clippy `-D warnings`, `pf-console-ui` 221 tests
(the ring's two editor tests, the catalogue, the draft round trip,
the grid's coverage and column rule; `every_row_has_exactly_one_tab`
55 → 48); the Android kit build through cargo-ndk, which compiles
this crate for the Android console. Not yet on glass.
Design §5.5: on a Deck in Gaming Mode, Steam Input owns the
touchscreen and replays it as a mouse whose "relative" deltas are
absolute positions — a field capture read 0 finger events against 341
mouse motions of 300 to 450 px. Under the stream's relative-mouse lock
every one of those walked the host cursor further into a corner, and
since SDL saw no fingers, all three touch models were dead together.
`SDL_TOUCH_MOUSE_EVENTS=0` never reached them: they are Steam's, not
SDL's.
`SteamTouchMouse` (touch.rs) recognises that shape — a gamescope
session (`overlay_focus::gamescope_session`, now pub), no direct-touch
finger yet this session, a delta of 150 px or more that no finger drag
produces — and the presenter drops those motions instead of summing
them. The first one raises the session notice once: "Steam Input is
sending the touchscreen as a mouse — pick the Punktfunk controller
layout for touch". A real mouse on a docked Deck keeps working (its
deltas are small), and the first real finger to reach SDL switches
the guard off for the session.
The lever the notice names is the one the Deck docs already teach:
the Steam Input layout the Decky plugin installs, whose whole job is
real touch. §5.5 still marks it unverified on glass — the docs gain a
line on what happens without it, and the notice is the reminder. T18
(reading the touchscreen from evdev) stays deferred.
`build-flatpak.sh` gains `BRANCH=` so a Deck tracking the hosted
`canary` can take a test build in place of it; a second branch beside
it would win the plain `flatpak run` the plugin issues.
Gates: `cargo test -p pf-presenter --lib touch` on the Mac (19, the
new `gaming_mode_drops_leaked_touch_positions_until_a_finger_is_seen`
among them); container build + clippy `-D warnings` for `pf-presenter`
and `pf-client-core` and their tests; fmt. Not yet on a Deck.
Design §4 on Apple, matching Android: the ring's Virtual controller
slot toggles a controller over the stream. While it is up the session
model holds one `VirtualPadWire` — the lowest free wire index from
`GamepadManager`'s one allocator (the way `Sc2Capture` claims one),
declared an Xbox 360 pad, its Arrival before any input, held state
flushed and its Remove on close — so the host sees one controller
arrive and one leave beside any real pad (§9). The ring's mask reaches
it through `setRingOpen`: everything held is released on the host
when the ring opens, nothing is sent until it closes, nothing is
replayed after. Toggled from the ring, it starts masked.
The layer is UIKit: SwiftUI has no multi-touch, and UIKit keeps a
touch with the view it began in, which is exactly the ownership a
stick needs. Each control is one `PadControlUIView` placed by SwiftUI
at its preset position; the layer draws nothing between them, so a
finger there never reaches it and falls through to `StreamLayerUIView`
— tap-to-click keeps working beside the pad. The geometry and the
three input rules (`padControls`, `dpadBits`, `stickWire`,
`triggerWire`) live in the kit with the same numbers as the Android
`VirtualPad.kt`, so the two pads feel the same: four face discs in one
view (a thumb rolls from A to B), an eight-way D-pad by angle, a stick
that follows its first finger from wherever it landed, a trigger read
off the finger's position down its pill. A light impact per press.
tvOS keeps the slot dimmed — "Apple TV has no touch screen" — the way
the Touch mode slot is; the layer file is `#if os(iOS)`.
Editor: a Virtual controller section under the ring — Layout picker,
Opacity and Scale sliders that write on release — through the same
`blob` binding the ring uses. The picker's note no longer promises a
later release.
Gates: `pf-touch-apple-check.sh ios|tvos PunktfunkClient` both
`swift exit: 0`; `VirtualPadTests` (the Swift twin of the Android
test) written in step but not run — the bundle holds the 5-slice
iOS/tvOS core and the macOS test host needs it rebuilt. The Release
xcodebuild for the iPhone succeeded, installed and launched on the
device — not yet seen on glass.
Neither had a page. `input.md` gains "The quick-action ring" — the
twist, the per-shell openers, `Select+A` — and under it "Virtual
controller": where it is shown from, that the host sees a real
arrival and removal on the next free pad index, the fall-through
rule, how the sticks, D-pad and triggers read a finger, and where the
three settings live. `client-settings.md` gains the Quick actions and
Virtual controller rows with their availability (the controller is
Android and iPhone/iPad only; Apple TV, a Deck and the desktops say
why not), and stops counting the Input section's rows — it said five
and listed ten.
Design §4 on Android: the ring's Virtual controller slot is a toggle
that draws a controller over the stream and hides it again. While it
is up it holds one wire pad on the router — `openExternal(XBOX360)`,
the slot model the capture links already use — so the host sees one
controller arrive and one leave, on the lowest free index beside any
real pad (§9). Its buttons ride `slotButton`, so the chords (`Select+A`
opens the ring, the exit hold, the mic and stats chords) and the ring's
mask work on it exactly as on a real pad.
Every control is its own pointer-input node above the gesture layer
and below the ring: a finger on a control is taken, a finger between
them never reaches the layer and falls through to the touch mode
beneath, so tap-to-click keeps working beside the pad. The face
buttons are one node of four discs (a thumb rolling from A to B
presses B); the D-pad reads eight ways by angle; a stick is owned by
its first finger and follows it from wherever it landed, with a fixed
dead zone; a trigger reads the finger's position down its pill, so a
slow press is a slow press. A tick per press. Three presets with fixed
positions; a narrow layer (a phone upright) stacks the clusters
instead of spreading them. Select, Guide and Start are on every
preset — a pad that cannot pause is a bug.
Router: `ExternalPad.axis` is dropped while the ring owns the pad,
like a button. `setRingOpen` had zeroed the axes on the wire, and a
stick still held under the ring wrote over that; a capture-link stick
had the same leak.
Editor: a Virtual controller group under the ring — Layout (Full,
Sticks and shoulders, D-pad and face buttons), Opacity and Scale
sliders that write on release — through the same `onChange` the ring
uses; `SettingDropdown` goes internal for it. The picker's note no
longer promises a later release.
Left out on purpose: stick clicks (no control for them), a
drag-to-position editor, per-game layouts, gyro and touchpad
emulation (§4.3). The pad is per session and starts hidden.
Gates: `:kit` + `:app` compile through cargo-ndk; `VirtualPadTest`
5/5 (every preset fits and never overlaps at three sizes, the D-pad
sectors, the stick travel, the trigger pull) and `OverlayActionsTest`
6/6; the debug APK is installed on the Nothing Phone, which was locked
— not yet seen on glass.
The first open used a centre computed at composition, one step behind the size state, so the ring opened at (0, 0) and the clamp pinned it to the margin — up and left of the card by a slot radius. Both effects that open the ring read the live size now. Verified by screenshot on the Nothing Phone.
The swap's reset fired at 450 ms, inside the spring's settle, so the
two discs jumped their last few points as the contents swapped — a
flash. The spring is stiffer (response 0.35 / damping 0.82 on iOS,
StiffnessMedium / 0.82 in Compose) and the reset waits 650 ms, past
the settle, on both.
Android: the ring is in a card again like every other field — an
`OutlinedCard` without the group's 16 dp inset, so the stage keeps the
width the ring needs and stays centred; the caption sits under it.
Gates: Android debug APK on the Nothing Phone; Release xcodebuild on
the iPhone.
Dropping a disc on another slot swapped the two contents in place. Now
the two discs travel to each other's slots on a spring (the dragged one
from wherever it was released); once they land the blob is written and
the drawing order snaps back to identity with the contents swapped, so
that write draws nothing. iOS keeps a per-disc `order` animated with
`.animation(value:)` and resets it in a transaction with animations
off; Compose animates each disc's position with a spring only while a
swap plays and a snap otherwise, so the twist and a drag still follow
the finger.
Two looks on the editor's stage, both platforms: the ring's scrim (18 %
black while open) is off in the editor — it read as a fill — and a
stage narrower than two ring margins centres the ring instead of
pinning it to one side (the clamp assumed a screen). Android's stage
stands outside the settings card, with its caption under it: the
card's inset left it narrower than the ring, and a card around a
control that draws its own discs read as a fill too.
Gates: Android debug APK on the Nothing Phone; Release xcodebuild on
the iPhone.
On glass, five things about the quick-actions editor:
- Android: dragging a disc onto another slot did nothing. The twist
surface sat on the PARENT of the ring, and the stream's touch
handler consumes every change it sees, so the discs' drag detectors
only ever saw consumed moves and cancelled; a tap survived because
it has no moves. The surface is a sibling under the ring now, the
way the stream's gesture layer is under the in-stream ring.
- The centre disc was live in the editor on both platforms, opening a
preview sheet of something that is not editable there. It is drawn
dimmed and inert while editing.
- The "Tap a button to change it…" line sat on top of the discs. It
is the field's caption under it now on both platforms, like every
other field's.
- Android: the stage had a fill of its own inside the card; it is
transparent like the other fields.
- Android: the key chips in the shortcut editor laid their label out
from the start of a fixed-width chip; the label is centred.
Gates: Android debug APK on the Nothing Phone; Release xcodebuild on
the iPhone.
The console could point a ring slot at a chord the blob already
carried but could not make one. Design §3.3's pad form, on the
existing widgets: a "Quick-action shortcuts" action row in the Input
tab opens `RingShortcutsScreen` — the blob's chords as a list (name
and legend), and an editor for one: a Name field on the on-screen
keyboard tray (Steam's on a Deck), Ctrl / Alt / Shift / Win as On/Off
rows, the Key stepped with ◀ ▶ through everything `key_vk` knows
(wrapping on A), Save, and Remove for an existing one. A new shortcut
takes the first empty slot, as on the phones. B peels back: keyboard,
editor, screen.
Writes rebase on the store's file and save, like the settings screen —
this is one more whole-file writer. The blob logic (`apply_draft`,
`remove_shortcut`) is pure, and the test drives it directly: the store
is one real file shared by every test in the process, and a round trip
through it races the settings tests (the same race behind the known
`reduce_motion_freezes…` flake).
`every_row_has_exactly_one_tab` learns the row (54 → 55).
Gates: container `pf-console-ui` tests (216), fmt, clippy; the Android
kit build through cargo-ndk, which compiles this crate too.
Design §2.3: with reduce_motion on, the Skia ring crossfades in place — the commit snaps to open instead of springing, and the discs sit at their slots from the first frame and only fade; the twist still opens it. The Android and iOS rings already did this (iOS via accessibilityReduceMotion).
Gate: container pf-console-ui tests (215), fmt, clippy.
Design §3.3 on Android, matching the iPhone: the settings editor shows
the in-stream `RingOverlay` — the same composable — full size over a
backdrop that runs the real two-finger twist (`streamTouchInput` with
a `0` handle: `send_event` drops every wire call, the dial still arms,
commits and cancels). Tap a slot to pick its action from the catalogue
by group with availability notes; drag a disc onto another to swap;
tap the centre to see depth two with inert actions. Whatever closes the
ring it springs back open, so the editor is never left with nothing to
tap. The backdrop is the theme's `surfaceVariant`, one more field.
`RingEditing` on the Compose `RingOverlay`: a slot tap picks instead of
firing, an empty slot is a pick target, the scrim takes nothing, the
8 s idle close is off, and `detectDragGestures` on each disc resolves
the drop to a sector — it consumes past touch slop, which is what keeps
the tap from also firing. `ChordKeycap` and `KeycapDisc` are shared
with the editor's previews.
Shortcuts match the iPhone's editor: a row per shortcut with its disc,
name and legend; tapping it (or Add) opens a screen with the disc and
legend previewed live, a name field, the four modifiers as chips, and
the key on a grouped keyboard of chips (word keys on wider chips).
Remove lives there; a new shortcut takes the first empty slot.
Gate: `:app:compileDebugKotlin`; the debug APK for the Nothing Phone.
Design §2.5: the Apple TV's entry to the quick-action ring is a short
press of the remote's Back; a long hold still ends the session. The
ring is the same `RingOverlay` the iPhone draws, driven by the pad path
that already existed (`RingState.handleNav`, `Select+A`, the capture's
`ringOpen` gate) — there is no twist, tap or drag on a TV, so those
three paths are `#if os(iOS)` inside the file and the rest compiles
for both.
What carries it:
- `SiriRemotePointer.onShortBack`, fired on a Back released under the
1 s disconnect hold; the model routes it into `onRingChord`, the
hook the pad chord already used, so the view wires one closure for
both. On tvOS that closure toggles: open at the screen centre,
close if it is up.
- `ContentView` mounts the overlay on tvOS as iOS does (only while
open), pre-fetches host actions at session start, and shares
`ringActions`; the twist sink stays iOS-only.
- `TouchInputMode` moves out of `TouchMouse.swift`'s iOS-only block:
the enum is plain data every platform can name, the gesture machine
under it stays iOS. On tvOS the Touch mode slot is dimmed with
"Apple TV has no touch screen".
Not on an Apple TV yet — no device here. Gates: SwiftPM tvOS, iOS and
macOS client targets; a Release xcodebuild of Punktfunk-tvOS for a
generic device (no signing), which is the build that has no DEBUG.
In the editor the disc's Button fired on release after a drag-to-swap, so the picker sheet opened on top of the swap. One high-priority DragGesture(minimumDistance: 0) owns the disc while editing: a touch that stays within 8 pt is the pick, one carried onto another slot is the swap. In-stream the gesture mask is .subviews, which leaves the Button exactly as it was.
Gate: Release xcodebuild on the iPhone, installed and launched.
The word keys (Backspace, PrtSc, PgDn) wrapped inside the 44 pt grid
cells, so those caps grew taller than their neighbours. Every cap now
keeps one line at a fixed 30 pt and shrinks its text to fit, and the
groups that hold word keys (editing, navigation, other) lay out on
80 pt columns; letters, numbers and function keys keep the tight 44.
Gate: Release xcodebuild on the iPhone.
Four things the quick-actions ring and its editor got wrong on glass:
- Legends. `chord_chip` printed "❖" for Win/Super, "⇧" for Shift, "↵"
for Enter — symbols that read as nothing to most people. It now
prints the word a keyboard prints (Ctrl, Alt, Shift, Win, Esc, Enter,
Backspace, Del, Ins, PgUp, PgDn, PrtSc, Caps), arrows stay arrows,
and `key_legend` exposes the per-key word. Rust, Kotlin and Swift in
lockstep, with the contract tests moved to the new text.
- A shortcut on a disc drew that legend as one line, which ran to the
disc's edge and past it. It is a stacked keycap now: modifiers small
on top (on Apple the compact glyphs its keyboards print, ⌃ ⌥ ⇧ ⌘),
the key large under them, shrinking to fit — `ChordKeycap` on iOS,
the same shape in Compose.
- The three host power actions shared one "power" glyph and were
indistinguishable on the ring. Sleep is a moon, restart a circular
arrow, shut down the power symbol, on iOS and Android.
- The iOS shortcut editor was a bare add sheet. Each shortcut is a row
with its disc, name and legend; tapping it (or Add) opens an editor
with the disc and legend previewed live, a name field, the four
modifiers as chips, and the key on a grouped keyboard you tap
(function, letters, numbers, editing, navigation). Remove lives on
the same sheet; a new shortcut still takes the first empty slot.
Also `every_row_has_exactly_one_tab` learns the seven ring rows the
T19 commit added (47 → 54): that test had not run since — the
container script tests only `pf-presenter` unless `TEST_EXTRA` names
more crates.
Gates: Release xcodebuild on the iPhone; container `pf-client-core`
(237) and `pf-console-ui` (215) tests, fmt, clippy; Android compile +
`OverlayActionsTest` 6/6; Swift `OverlayActionsTests` updated in step
but not run (needs the macOS core rebuilt).
Leaving the editor on the iPhone dropped the user on the category list
and no category could be entered again. The settings detail column is
deliberately not a NavigationStack (an inner one doubles the title bar
on iPad), so a NavigationLink pushed from it rode the collapsed
NavigationSplitView's own stack and, on pop, took the `List(selection:)`
binding with it. AboutView's Shortcuts and Acknowledgements rows had
met the same thing and are sheets for it; Quick actions follows them:
a plain row that presents the editor in its own NavigationStack with a
Done button.
The backdrop is the Form's cell colour (`secondarySystemGroupedBackground`,
resolved dark under the editor's scheme), so it reads as one more field
rather than a bright stage — the grey was too bright.
Trap: the new `@State` first landed inside `#if DEBUG && !os(tvOS)`, so
the SwiftPM (debug) gate passed while the Release xcodebuild failed.
It sits with the unconditional properties now.
Gates: `pf-touch-apple-check.sh ios|tvos PunktfunkClient` exit 0; the
Release xcodebuild for the iPhone succeeded and is on the device.
On the iPhone, after one or two picks the editor went dead: nothing on
the ring answered a tap. UIKit hands a tap on a disc to the backdrop's
`DialCatcherView` as well as to the SwiftUI button above it, so its
tap recognizer ran `ring.close()` on every pick. The ring wound in
behind the picker sheet, and a closed ring's discs are not hit-testable.
The backdrop tap now only dismisses the preview sheet, and whatever
closes the editor's ring — a twist wound back past the commit angle, a
preview row that ends the stream — the ring springs back open once the
wind-in has played (`onChange(of: ring.closing)`), so the editor is
never left with nothing to tap. The caption no longer promises a
twist-to-open state that cannot last.
The backdrop is a plain grey now, as asked, instead of the gradient.
Gate: `pf-touch-apple-check.sh ios PunktfunkClient` exit 0.
Design §3.3, "the editor is the ring": the settings editor now shows the
in-stream `RingOverlay` — the same type, not a copy — full size over a
gradient backdrop, and it answers the real two-finger twist with the
real thresholds. Tap a slot to pick its action from the catalogue by
group (Session, Input, View, Audio, Host, Shortcuts, Empty, each with
its availability note); drag a disc onto another slot to swap the two;
tap the centre to see depth two with inert actions. The shortcuts list
and Reset to default stay under the ring. In a profile that owns its
ring, a line under it says so.
What carries it:
- `DialCatcher` (PunktfunkKit): a UIKit surface running the stream's
`TouchMouse` with its wire unplugged, so only the dial's arm, commit
and cancel come out; a one-finger tap reports separately and closes
the ring (or the sheet) in the editor.
- `RingEditing` on `RingOverlay`: a slot tap picks instead of firing,
an empty slot becomes a pick target, the scrim passes touches through
to the backdrop, the 8 s idle close is off, and a `DragGesture` on
each disc resolves the drop to a sector (released near the centre or
on its own slot it springs home).
- `HostAction` gains a public init so the editor previews the three
power slots as offered.
The six-Picker list form from the previous commit is gone; the ring on
appear plays the same spring it does in-stream.
Gates: `pf-touch-apple-check.sh ios|tvos PunktfunkClient` both exit 0.
On the iPhone for feel; drag-to-swap and the twist over the backdrop
are the two things to try.
The `overlay_actions` blob (design/touch-client-overlay.md §3.2) had
parsers and profile plumbing on every shell but no way to change it.
This is the list form of §3.3: pick what each of the six slots holds,
add or remove custom shortcut chords, and reset to the platform ring.
The ring-as-editor with drag-to-swap and the twist tutorial is still
owed; this is the smallest editor that makes the blob reachable.
iOS: a "Quick actions" row under Touch & pointer, bound through
`scoped(SettingsFields.overlayActions)` like every other profileable
row, with the row's override marker and Reset. The editor
(`QuickActionsEditor.swift`) is six Pickers, a shortcuts list with
swipe-to-delete, an add sheet (label, modifier toggles, key picker,
chord preview) and a Reset to default that drops the override in
profile scope or clears the global. A new shortcut takes the first
empty slot (§3.3).
Android: the same shape as a deep sub-screen (`QuickActionsScreen.kt`,
opened from a Quick actions row in Input with its override badge),
writing through the screen's `update` so the profile diff records the
whole blob. `SettingsGroup` goes internal for it to reuse.
Desktop and the Android console (Skia): six `RingSlot` rows and a
`RingReset` action row in the Input tab. ◀ ▶ step a slot through the
catalogue — empty, the built-ins, the three host power actions, then
the blob's own shortcuts — and write the whole blob back. Shortcut
CREATION is not on the console yet (it needs the on-screen keyboard
flow); a slot can point at a chord the blob already carries. The
console edits the global blob only: it never edits profiles, and D9's
per-row scope picker is new machinery left for later. One test drives
the stepping, the clamp at Empty and the shortcut option.
The slot catalogue is the same list in the same order on all three
shells; host actions are the three advertised power ids.
Gates: `pf-touch-apple-check.sh ios PunktfunkClient` exit 0; Android
`:kit`+`:app` compile through cargo-ndk, JNI floor clean; `cargo fmt`;
`pf-console-ui` tests in the container. Not yet on glass.
The Resolution and Refresh rows showed the mode the sheet last asked
for, on the belief that Android had no live read-back of the
negotiated mode. It has one: `nativeVideoSize` reads
`NativeClient::mode()`, which the control task overwrites with the
host's `Reconfigured` ack (`pump/control_task.rs`). So a rejected
request left the row lying for the rest of the session.
The request still writes the asked-for mode at once (the ack lands off
the composition), then re-reads `nativeVideoSize` 500 ms later so a
rejection shows through. The Kotlin doc on `nativeVideoSize` no longer
calls the value fixed for the session. No new JNI: the
`nativeCurrentMode` the plan proposed would have duplicated it.
Gate: `:kit:compileDebugKotlin :app:compileDebugKotlin` through
cargo-ndk, JNI floor check clean.
On iOS the six slot discs and the centre now each ride their own
spring from the centre to their ring position when the ring opens:
the centre first, each slot 25 ms behind the last, on a bouncier
settle (response 0.4, damping 0.62) than the whole-ring spring had.
Scale and opacity ride the same spring.
Before, one scalar placed every disc and the discs were inserted with
`if q > 0`, so a disc that first appeared at commit had nothing to
animate from: the twist path sprang, the corner disc and `Select+A`
popped in place. The discs now stay in the tree at 0 while the overlay
is mounted, and a `phase` (twist / open / closing) picks each disc's
target and animation through `.animation(_:value:)`. During the twist
they still follow the finger frame by frame with no animation; the
spring takes over at commit from wherever they are.
Closing: `RingState.close()` on an open ring raises `closing` for
140 ms, so the overlay stays mounted while the discs ease back in
(ease-in 120 ms) and then leaves the view hierarchy as before
(tenet 1). A cancel short of commit still leaves at once. Reduce Motion
keeps the plain 120 ms fade with no spring and no stagger.
tvOS is untouched (the file is `#if os(iOS)`); Android and the Skia
ring are unchanged. Gates: `pf-touch-apple-check.sh ios|tvos
PunktfunkClient` both exit 0. Not yet on glass.
On the Nothing Phone the two-finger twist never opened the ring. Real
fingers never pivot about a fixed point: the centroid drifts a few px
per sample while the pair turns, and the Android scroll path fires a
notch per 4 px of centroid travel. The first notch is final
(scrollEmitted), so the gesture was a scroll before it could turn 10°.
The Rust engine shares the 4 px notch; Swift's is 10 pt against a
16 pt slop, so the iPhone mostly got away with it.
While the pair is undecided — under DIAL_SLOP of travel and under
DIAL_ARM_DEG of turn — no notch goes out, and the scroll anchor follows
the centroid so a real scroll starts smoothly once it crosses the slop.
This is what the design's slop rule meant (§2.1: travel past the slop
before arming means scroll); the engines just ran the notch first.
A new Rust test drives a twist whose centroid drifts ~14 px over five
samples: no Scroll act, the dial arms, and 35° commits. The pan test
that mixed a scroll with a rotation now pans 30 px, past the slop.
A pad user had no way into the ring: every existing in-stream chord
forwards its buttons (a game sees the X in Select+X), and nothing
in-stream consumed pad input on any client
(design/touch-client-overlay.md §2.6).
`Select+A`, Select first, is the first swallowed chord. All three
routers already hold a lone Select back for the guide hold; an A
inside that window opens the ring and neither press nor release
reaches the host. While the ring is up the pad belongs to it: the
desktop masks the pads and polls the first into menu events, Android
and Apple release held state on the host and adopt the hardware state
silently; on close nothing is replayed. The D-pad and left stick step
the highlight (Right clockwise, Up to 12 o'clock, Down to 6, Y to the
centre), A fires it, B closes, and the sheet becomes a cursor list on
every shell so the same pad reaches the resolution row.
pf-console-ui also builds for the Android GL host, where the ring's
host-action cache is configured out; the Android JNI crate then failed
to link the console. The Compose ring serves Android.
main took C ABI 27 for the Steam Controller 2 hidout widening, so
punktfunk_connection_host_caps2 and PUNKTFUNK_HOST_CAP2_TOUCH move to
ABI 28; the header is regenerated. The SC2 passthrough badge and the
touch-fallback badge now stack in the same bottom-centre slot.
The desktop session had no in-stream menu: the ⌃⌥⇧ chords were the
only way to end a stream, cycle stats or mute, and a Deck touch user
had none of them (design/touch-client-overlay.md §0.1).
The ring opens under the fingers from the two-finger twist, frame by
frame, or at the window centre from ⌃⌥⇧O; End stream is a slot behind
a two-press arm. Six translucent discs carry short text labels (the
console has no icon font); the centre opens the sheet — a MenuList
with the full catalogue, where Left/Right on the Resolution and
Refresh rows cycle the presets over request_mode. While the ring is
up it owns the glass: pointer and key events go to it, touch fingers
stop feeding the gesture engine, and it takes the damage key so a
settled ring redraws nothing.
The presenter side is one portable contract in pf-client-core::ring
(RingInput / RingCommand / RingFacts), three default methods on the
Overlay trait, per-frame facts on FrameCtx, and SessionOpts carrying
the profile's overlay_actions. Host-action slots are pre-fetched at
connect and ride the console's own command bus. Touch mode becomes
switchable mid-stream (Capture::set_touch_mode) and a shortcut chord
goes out as VKs down then up.
A touch user had one ✕ disc that ended the session and nothing else:
no resolution switch, no host actions, no shortcuts, no way to change
the touch model mid-stream (design/touch-client-overlay.md §0.1).
The ring opens under the fingers from the two-finger twist, frame by
frame, or from the corner disc, which now opens it instead of ending
the session; End stream is a slot behind a two-press arm. Six glass
slots come from the resolved profile's overlay_actions; the centre
opens the sheet with the full catalogue and the resolution presets
over requestMode. It leaves the hierarchy entirely when closed
(tenet 1). The dial reaches SwiftUI through a public DialEvent and a
StreamView.onDial hop; the Keyboard slot summons the soft keyboard by
notification; Touch mode gets a session-scoped override. Haptics:
a tick when the twist arms, a thump at commit, a tap per press, a firm
"no" on a dimmed button, a warning when a destructive slot arms.
One thump at commit was the only feedback. The ring now ticks when the
twist arms, taps on every press, thuds firmly on a dimmed button, and
warns when a destructive slot arms — through the console's
ConsoleHaptics, so it follows the system haptics setting.
A touch user had no in-stream menu: no way to end the stream except an
unconfirmed back gesture, no resolution switch, no host actions, no
shortcuts (design/touch-client-overlay.md §0.1).
The ring opens under the fingers from the two-finger twist, frame by
frame, or at the screen centre from Back — which no longer ends the
session; End stream is a slot behind a two-press arm. Six slots come
from the resolved profile's overlay_actions; the centre opens the
sheet with the full catalogue and the resolution presets over
nativeRequestMode. Toggles leave the ring open, commands close it, a
tap outside or 8 s idle closes it, and it leaves the composition
entirely when closed. Host actions are pre-fetched on the session
tick, never when the ring opens. Touch mode becomes live per session.
A ring shortcut stores key NAMES so one profile fires on every client;
the wire speaks Windows VKs. key_vk (Rust, Kotlin) is the shared
table: modifiers, navigation keys, f1–f24, letters and digits; an
unknown name means the chord does not fire and the editor says so.
No gesture engine tracked the angle between two fingers; two-finger
handling was a centroid, and the ring needed an opener no game, host
or OS claims (design/touch-client-overlay.md §2.1).
Each engine now keeps the finger-to-finger vector from the second
finger's landing and compares it on every move: 10° arms the dial and
suppresses scroll, 30° commits (the ring stays open after the lift),
a lift short of commit cancels and sends nothing, a scroll notch
already sent means the gesture is a scroll for its lifetime, a pinch
is nothing. Progress and direction reach the shell as Dial events; the
ring views consume them next.
SDL reports the two fingers of one frame as separate events, so the
desktop judges the twist only when the other finger's position is from
the same frame or older than a pivot's stillness — halfway through a
plain scroll step the vector reads as a 60° turn.
The in-stream ring (design/touch-client-overlay.md §3) is configured
by ONE JSON blob, never by a dozen booleans: every cross-client setting
costs about six hand edits per client, and a missed edit ships a
feature on some clients only.
`overlay_actions` is a tier-P field on Settings and SettingsOverlay
(the whole blob overrides, D10), mirrored in Swift and Kotlin with the
existing profile plumbing. The parser is lenient by contract: six
slots, unknown ids and dangling shortcuts become empty slots, a broken
blob is the platform default. The Rust tests are the contract; the
Swift and Kotlin ports carry the same five tests.
Selecting the Touch (passthrough) model against a Hyprland, sway or
Omarchy host did nothing: the wlroots injector drops every contact, and
no capability bit let a client know. Windows below build 1809 fails the
same way. The client offered the mode, the host dropped the events, and
no layer said so.
The host now sets HOST_CAP2_TOUCH in the Welcome's second capability
byte when its live injector carries touch (libei, gamescope EIS, KWin;
the PT_TOUCH probe on Windows). The byte never reached a client before:
NativeClient::host_caps2, punktfunk_connection_host_caps2 and
PUNKTFUNK_HOST_CAP2_TOUCH expose it (C ABI 27, additive). Each client
runs the trackpad model for the session when the bit is absent and shows
a one-line notice at stream start.
The core and the C ABI can renegotiate a session's resolution and
refresh without reconnecting, and the Apple and desktop clients use it.
Android had no binding, so the in-stream Resolution row the touch
overlay design adds could not work there.
One JNI on the nativeDisconnectQuit template, one external fun.
On a phone held against a 16:9 stream, a trackpad swipe that started on
a black bar did nothing: the gesture layer sat on the aspect-fitted
picture box, so most of the screen was inert and read as unresponsive.
The gesture layer now spans the whole container. Every absolute
mapping — direct pointer, passthrough, the pen lane — measures against
the picture rect (`videoFitRect`, the same centre-aligned fit the
surface is laid out with) and clamps into it, so a contact on a bar
lands on the nearest picture edge. Trackpad deltas need no rect.
Press-and-hold — the touch idiom for "pick this up" — produced a click
and then a cursor move on all three clients, in trackpad and pointer
mode alike. The engines armed a held left button only from a tap
followed by a second touch within 250 ms. Dragging a window, selecting
text and dragging a file were unreachable from a touchscreen.
One finger held still for 500 ms now presses the left button and drags
until it lifts; the tap-then-drag path stays. A still finger raises no
event, so each engine gets its clock: a run-loop tick on the desktop,
withTimeoutOrNull on Android, a main-queue work item on Apple. The
Android gesture releases a held button on teardown, which it never did.
Turning on "Invert scroll" changed nothing for two-finger scrolling on
an iPad or a Deck. The desktop applied the sign only in the wheel path
(Capture::on_wheel); the touch engine's notches went out raw. On Apple,
InputCapture.sendScroll applies it and its comment called itself the
one scroll sink, but TouchMouse sends straight to the connection.
Both engines now apply the sign where the notch is made, as Android
already did. The Swift comment names the second sink.
A three-finger drag scrolled on a Deck and summoned the keyboard on an
iPad. The published vocabulary is two-finger scroll; the desktop engine
scrolled on two OR MORE fingers.
Three or more fingers now anchor their own centroid, disqualify the tap
when they travel, and never scroll or move the cursor — the rule the
Android and Apple engines already apply.
Act::wire() moves to input.rs, the only place that needs InputKind, so
touch.rs has no platform-gated dependency and builds everywhere. Before
this, `cargo test -p pf-presenter` ran zero tests on macOS and passed.
smoke (arch) got past the sudo fix and died one step later, on the
linger step this branch moved out of --no-start:
==> Starting at boot with nobody logged in
+ sudo loginctl enable-linger "$USER"
System has not been booted with systemd as init system (PID 1).
The smoke containers have no logind, so the call cannot work and linger
would mean nothing there. Reverting the move would put back the summary
that promises start-at-boot and silently drops it under --no-start, so
guard the call instead: run it when systemd is PID 1, warn and carry on
when it is not. An install that otherwise succeeded should not fail on
its last step for a setting the box cannot hold.
--dry-run still prints the command — it reports what a real box would do,
and the defaults matrix asserts on it.
The container path itself is checked by installer-smoke, which is where
it surfaced; no dry-run case can reach it.
installer-smoke went red on the root-container leg:
/tmp/tmp.9gBiJE8x4x/sudo: 2: exec: -n: not found
That shim is install.sh's own — the one it writes when running as root
with no sudo, so the verbatim `sudo …` lines from platforms.json still
work — and it is `exec "$@"`. Rewriting `sudo install -d …` to
`sudo -n install -d …` makes it `exec -n install -d …`, which is not a
command. The smoke job covers that path on purpose.
Not introduced by the previous commit: driving the run() from edf4effb
with no TTY and --yes against the same shim fails identically. Narrowing
the condition moved which sessions hit it, not whether they do.
So the rewrite goes. It buys nothing it claimed: with no terminal, sudo
already exits at once with "no tty present and no askpass program
specified" rather than hanging, and where an askpass helper IS set up,
-n breaks the one unattended path that works. Deleting it also drops a
global sed over an arbitrary command string.
The gate grows the case that would have caught this. Its stub sudo is
now that shim byte for byte, and it asserts the command actually runs.
First attempt at that check was vacuous — run() echoes each command
before running it, so a marker word matched the echo and passed on known
-bad code. The probe is `sudo expr 40 + 2` and the assertion is on 42,
which appears nowhere in the command text.
The correctness sweep found no IddCx 1.10 divergence that could starve
frame generation, so the driver now testifies instead: every acquire
that ends >=1 s of silence (or lands >=250 ms after its display time)
logs the OS's PresentationFrameNumber step and PresentDisplayQPCTime
lag, splitting a FRAME-GENERATION hole into dropped / delayed /
never-composed from inside the swap-chain. The commit-modes callbacks
log each path's ACTIVE/CHANGED flags so an OS-side head deactivation
is visible next to a hole.
On .173 the witness immediately showed the loopback rig's cursor
wiggle generates no damage (ssh runs in session 0; only the console
session is composed): an idle-desktop hole reads pfn +1/fresh, and
with real session-1 damage the head composes hole-free.
Review of the intent-based defaults. Five fixes, three of them defects
the new matrix could not see, so each one gains a case that fails on the
code as it stood.
run(): the `sudo -n` rewrite keyed off --yes, but no terminal already
implies --yes and never the reverse, so `sh install.sh --yes` typed at a
prompt sent `sudo -n` and died on the first step without a cached ticket.
sudo reads /dev/tty, not stdin, so a terminal under --yes prompts fine.
Gated on `[ -z "$TTY" ]` instead, which is the case that actually has
nobody to type a password.
linger: the summary promised "start at boot" unconditionally, but the
`loginctl enable-linger` sat inside `if [ "$START" = 1 ]`, so
`--no-start` printed the promise and dropped it. Every case in the matrix
passes --no-start, so the gate was certifying exactly that. Linger is
configuration, not starting — moved out of the START branch, still ahead
of the `systemctl --user` probe it has to precede.
couch_box(): keying off FAMILY=sysext and a `ujust` on PATH covered
Silverblue, Kinoite, Bluefin and Aurora — desktop workstations that ship
rpm-ostree and ujust and got the group plus linger under --yes without
being asked. Narrowed to `like bazzite || like nobara`, which is what
install.mdx already claimed; gamescope.md corrected to match.
The group prompts name the grant again (usbip attach, only on a machine
you trust, with the docs link). Asking about intent is right, but under
--yes the summary is the only place it is stated, so that line names the
group too.
sunshine_active(): any non-zero exit from `detect-conflicts` read as
"Sunshine is running", so a crashed or too-old host binary would flip
GameStream on and open the plain-HTTP pairing port unasked. Only exit 1
is an answer now; anything else falls through to the unit probe.
check-install-defaults.sh also lifts run() out of the script and drives
it against a stub sudo — --dry-run returns before run() executes
anything, so no dry-run case can reach it.
Gating the sweep left the unknown-firmware case silent: the only log line
lived inside it, so a firmware that does not put report `id` at
100F6C<id+0x35> would drop every write for that actuator with nothing in the
bundle to say why.
Warn once per id instead, naming the id and the UUID that was missing.
Together with the connect-time GATT census that is enough to add the pad's
ids to `Sc2Device.outputCharUUID` from one user's logs — which is the only
reliable fix, since ten output characteristics share one property mask and
nothing on the device distinguishes rumble from a trackpad pulse.
The per-report characteristic fallback rotated Steam's output payloads
across every writable characteristic of the Valve service, including
100F6C34 — which parses what it receives as a settings command (0x87 writes
a firmware register). A swept output frame could therefore persist an
arbitrary setting on the user's own controller. Known-purpose
characteristics are now excluded from the rotation.
It also never converged: nothing observes whether a write produced haptics,
so there is no success signal to latch on. With N candidates the correct one
is live one second in every N, for the life of the session — so on an
unknown firmware it delivered broken haptics AND continuous misdirected
writes, rather than degrading. Gated behind `verbose`, which is what it is:
the bench tool that mapped the firmware in the first place.
The caption ran 23 words across two clauses of what the setting does and
none of what it costs; the house rule is one of each, ~12 words for a
toggle. Its opening clause is now Android's word-for-word, with the
Apple-only cost — the Bluetooth prompt — as the rider, and the row label
matches Android's too.
The storage comment said the default mirrored Android's. Android defaults
ON. Record the prompt as the reason they differ, so the next reader does not
"fix" the mismatch.
"Steam's controller list stays empty" offered a Linux udev rule as the only
answer. Windows has no udev and no permission gate — the pad is a UMDF
device — so the same symptom there means a missing or stale driver package,
and the page sent readers to a fix that cannot apply.
`sc2_capture` was also undocumented, including why it defaults on for
Android and off for Apple.
The embedder guide still described the HID-output pull as DualSense-only and
had no entry for `punktfunk_connection_send_hid_report`, so an out-of-tree
embedder reading it would not learn that `PunktfunkHidOutput` grew 19 to 85
bytes — the one change that can corrupt its memory if it skips the startup
version check.
The guide is the living document; CHANGELOG.md stays a per-release file and
picks the ABI row up at the next cut.
`Sc2Device.strippedOutputLen` said its parity with the host's
`triton::out_report_len` meant "a drift on either side fails CI". It does
not: the Swift test transcribes the host numbers into a literal, so it
catches an edit made in Swift and is blind to one made in Rust — which would
leave the client trimming its GATT writes to a stale length.
Say what the guard actually covers, on both sides, so whoever edits either
table knows it owes the other.
Two statements landed indented 8 spaces inside a 4-space block, so
`cargo fmt --all --check` failed. The fmt gate is repo-wide: one dirty file
blocks every commit, not only this one.
`sc2Capture` was declared inside the `#if os(iOS)` block, but the settings
row that binds `$sc2Capture` is gated `#if os(iOS) || os(macOS)`. The macOS
build therefore failed with "cannot find '$sc2Capture' in scope", taking the
whole PunktfunkClient target — and `swift test` with it — down.
Moved past the `#endif`, next to the other cross-platform storage. The
comment claimed the storage was already unconditional; its iOS-only
neighbours are why that read as true.
A connected-but-inactive external sink - the standby TV that is part of
no topology - keeps probing its link, and the OS then drops composed
frames for the virtual head while other processes present normally. The
sweep that disables its devnode for the session already existed, but sat
behind the experimental pnp_disable_monitors flag nobody enables.
Measured on the .173 lab box (standby LG TV on HDMI, IDD-push loopback
under continuous cursor damage), 16 alternating pairs of 150 s legs,
each leg asserting the treatment actually applied via the sweep's own
"PnP-disable: monitor devnode disabled" line: the baseline produced a
hole-free leg 0 times in 16, the sweep produced one 8 times in 16
(Fisher p~0.002); median hole 6.3 s -> 0.7 s.
It is an improvement, not a cure, and the doc says so: 6 of the 16
treated legs still took FRAME-GENERATION holes tens of seconds long, and
the hole-time rank-sum is only borderline (p~0.055). The residual holes
are the same class, so the root mechanism stays open.
The operator's own displays are NOT in scope: only this selector is
limited to external physicals in no topology at all, so an internal
laptop panel can never be picked. Disabling displays the operator was
actually using stays opt-in under pnp_disable_monitors.
The drain loop now calls IddCxSwapChainReportFrameStatistics after every
FinishedProcessingFrame: COMPLETED status, the metadata's present number,
acquire/publish QPC brackets, and the surface's pixel/byte magnitudes.
The MS sample leaves this call as a TODO and this driver never made it;
the statistics feed the OS's per-output scheduling, and case #4's shape
is DWM starving exactly this head while composing a lit sibling at full
rate. Best-effort (first rc logged once, never breaks the drain), with
setx /M PFVD_FRAME_STATS 0 as the A/B escape hatch.
Both sticks on a virtual Switch Pro sat in the top-right corner under
Steam, reaching centre only at full down-left. Buttons and motion were
fine, and the kernel's own evdev node read correctly throughout.
The SPI-flash handler matched an exact (address, length) pair, and those
pairs came from hid-nintendo. Steam does not use the kernel driver here;
it uses SDL's HIDAPI Switch driver, which reads the same calibration as
18 bytes at 0x603D and 22 at 0x8010. Neither matched, so both fell to
the zero-fill path — which echoes the requested address, so SDL accepted
the reply and parsed a zeroed calibration. A zero centre is never
subtracted, leaving every raw axis value positive.
Serve reads by range from a modelled flash image, so every consumer gets
the same bytes whatever shape it asks for. What hid-nintendo receives is
byte-identical, and the IMU block already used SDL's length, so motion is
untouched. The caller loses its zero-fill fallback.
A `recreate_swapchain` failure in the resize handler propagated out of
`run_session`, ending the stream; the shell then reported a live
session as "Couldn't connect".
A driver that refuses the fullscreen-sized swapchain now costs the
fullscreen only: warn, drop back to windowed, and rebuild against the
geometry that was already working. A windowed failure still
propagates, since there is no smaller state to fall back to.
Toggling fullscreen mid-stream on Windows 11 quit the session with
`vkCreateSwapchainKHR: VK_ERROR_UNKNOWN`.
`recreate_swapchain` drained the present-wait waiter AFTER calling
`vkCreateSwapchainKHR(oldSwapchain = old)`, so the pf-present-wait
thread could sit inside `vkWaitForPresentKHR(old)` while the driver
retired that same swapchain. `vkCreateSwapchainKHR` externally-
synchronises `oldSwapchain`, so the overlap is a spec violation.
The drain (and the unclaimed-present drop) now run before the create.
`present_timing.rs` stated only the destroy half of the rule, which is
how the drain came to sit on the wrong side; it now states both.
The failure text also carries extent, format, colour space, present
mode and image count -- the first questions a field report raises.
Field 2026-08-28, iPad Pro on iOS 27: the picture froze twice in one
session while audio and input kept running, and only reconnecting
cleared it. pf-present logged decode at full rate against ok=0,
noDrawable=120 and no vendLeadMs samples at all, so the
CAMetalDisplayLink had stopped calling back.
Stage-4 has no drawable source of its own: every drawable arrives as
update.drawable. A link that goes quiet is therefore a stream that
never presents again, and nothing noticed. Stage-3's
PresentGate.staleAfter insurance does not reach this path, and the
link is only invalidated at session teardown.
The render thread now tracks how long it has gone without a vend and,
past 250 ms with frames still decoding, retires the link generation
and starts a fresh one. Invalidating the old link also returns the
drawables it holds, so this covers an exhausted pool as well as a
dead link. The relink is logged to the send-logs ring.
Also holds the link delegate for the link thread's lifetime. It is
stored weakly and was kept alive only by a local whose last use is
that store, which ARC is free to release on the spot.
v0.33.0 adopted Keep a Changelog headings but kept PR-body
prose. Replace that section with two-sentence bullets and
add the missing bullet-shape rule to docs/writing.md.
The guided installer defaulted every option to no, so Bazzite and
Nobara users who held Enter got a degraded pad and no linger —
the opposite of those distro pages. Prompts now name the intent,
defaults follow the box, and a summary prints before the first sudo.
Fixes#431
45 commits since v0.32.0 (29 non-merge). Nothing versioned moves: wire
stays 2, C ABI 26, driver 6, gamepad channel 3, plugin index 1, host
event schema 1, gamescope pfhdr8. The management API grows two routes
for host actions, so openapi steps 0.32.0 -> 0.33.0 with a real diff
rather than a stamp.
Minor because of what the tree gained, not what it renumbered: host
power actions on every client, punktfunk-host ctl, Omarchy as a
supported host, and a widened GRANT_ALL. That last one is the embedder
trap of this cut -- 0x3F -> 0x7F is a value change to an existing macro,
so equality comparisons against it now read a pre-power record as
Custom. GRANT_ALL_PRE_POWER exists for that.
First CHANGELOG section written to docs/writing.md section 2: Keep a
Changelog categories, 224 lines against v0.32.0's 454.
Also drops chacha20 0.10.1, which upstream yanked after v0.32.0 shipped.
It is transitive via chacha20poly1305 and 0.10.2 is a lock-only bump, so
cargo audit is back to its two allowed unmaintained warnings.
Gates on the Mac: cargo fmt --check, cargo test -p punktfunk-core --lib
--features quic (508 passed, 0 failed), the C ABI harness (abi_version=26),
check-docs-drift.sh, check-docs-links.sh, cargo audit, both openapi copies
byte-identical, Play notes 424/500 chars and unique, and the ISO 24495
auditor clean on both notes files.
The docs-drift ratchet matches PUNKTFUNK_* by token spelling, not by env
read, so the cbindgen #defines this branch adds — GRANT_POWER,
GRANT_ALL_PRE_POWER and HOST_POWER_CLOSE_CODE — read as new undocumented
knobs. They are ABI constants, not knobs: every sibling grant bit and
close code is already in this file for the same reason.
Three writing surfaces were being asked to hold design reviews. Commit
subjects on main averaged 101 characters, CHANGELOG.md ran to 6,090
lines for eight versions, and module rustdoc carried milestone codes and
soak durations that git blame already keeps honest.
The rules now live in docs/writing.md: Conventional Commits with a
72-character cap, Keep a Changelog categories for new sections, and
comments that state an invariant rather than recap a diff. CONTRIBUTING,
AGENTS.md and the Gitea PR template point at it, and the CHANGELOG
header says which form new sections take.
Nothing existing is rewritten. The changelog archive, the release notes
and every current rustdoc header stay as they are; the style applies to
what gets written next.
Source: github.com/luxus/punktfunk-house-style
Two findings from an Omarchy field session, one root cause each.
## The output resolution reset on every theme change
`omarchy-theme-set` ends in `omarchy-restart-hyprctl`, which is `hyprctl reload`
— and a reload drops EVERY runtime `hyprctl keyword`, our monitor rule for the
streamed head included. This crate already documented that fact (it is what
`restore_heads` relies on to re-light an `exclusive` session's monitors); nothing
put the rule back. So the head silently fell to its default mode mid-stream.
Resizing the client window appeared to fix it only because a resize on Linux
re-creates the output, which runs `set_monitor_rule` again.
The Hyprland backend now subscribes to the compositor's event socket and
re-applies the rule on `configreloaded`. Any reload gets it — the operator's own
`hyprctl reload`, `omarchy-refresh-config`, a theme switch — not just the one
that was reported. The watcher is a socket read, not a poll: an idle session
costs nothing, and its guard shuts the socket down on teardown so the thread
cannot outlive the output (sessions are minted on every mid-stream resize).
The mode only. A reload also undoes `topology: exclusive`'s head disables, but
re-disabling them from this watcher risks a permanently dark desk — teardown's
own `restore_heads` runs a reload to re-light them, and nothing orders the two
today. Noted in the code where the fix belongs.
## The console did not follow the theme, and only half wore it
Two separate causes:
* `useUiConfig` was `staleTime: Infinity`. The ports on that payload genuinely
cannot change without a restart, but the theme can, so the console sat in the
old palette until someone reloaded it. Now polled at 2 s (and refetched on
focus). Polled and not pushed because the console's SSE stream is a proxy of
the HOST's, and the host reads nothing about themes.
* Only `accent` and `mode` were carried. The template has rendered `background`
and `foreground` all along and they were dropped on the floor, which is why a
themed button sat on the console's own violet chrome.
All three colours now reach the page, and a `[data-omarchy]` block in styles.css
expands them into every surface with `color-mix(in oklab, …)` — cards, hovers,
borders, the accent surface — plus the three tints of the lens mark, whose fills
were hard-coded violet and now follow the brand tokens. One block covers light
and dark: `:root[data-omarchy]` outranks both `:root` and `.dark`, and the mixes
take their direction from the theme's own background/foreground pair.
`--success` / `--warning` / `--destructive` deliberately do not follow: they
encode meaning, and a theme whose accent is red must not leave "delete" and
"save" the same colour.
Every ratio was measured, not chosen: `web/tools/check-omarchy-palette.mjs`
reads them back out of the stylesheet, redoes the mixes and asserts WCAG
contrast across six shipped themes (Tokyo Night, Gruvbox, Nord, Catppuccin
Latte, Rose Pine Dawn, Everforest Light). It runs in `postbuild` beside
check-i18n, because nothing else in the repo can catch an unreadable palette —
the mixes resolve in the browser, so the typecheck, the tests and the build all
pass on one. Everforest Light is in that table on purpose: its own foreground is
5.2:1 against its own background, which is what caps a derived muted colour at
3.8:1 there. That ceiling is recorded in the stylesheet.
## Verification
* pf-vdisplay: 273 tests pass on linux-gnu (docker), `xcheck.sh linux clippy`
clean. The new `is_config_reload` test proved non-vacuous by relaxing the
matcher to a `contains` and watching it fail.
* web: build + `tsc --noEmit` + 37 tests + biome all clean. The theme-file
validator test proved non-vacuous by dropping the background check; the
palette gate proved non-vacuous by re-tuning a ratio.
* On glass: the trigger chain confirmed on the Omarchy box (`omarchy-theme-set`
→ `omarchy-restart-hyprctl` → `hyprctl reload`), `configreloaded` present in
the Hyprland 0.56.2 binary, and the event socket found and connectable at
exactly the path the new code computes. The built console served the box's
live theme end to end over `/_auth/ui-config`.
* NOT yet verified on glass: the re-apply itself. A stream was live on the box
and a `hyprctl reload` would have disrupted it.
design/host-actions.md P2. The host has offered sleep/restart/shutdown since
the previous commit; this is where a person can reach them. Every client's host
menu grows the rows right where Wake host appears when the machine is asleep —
finish on the TV, sleep the host from the same menu that woke it.
One shared core: pf_client_core::host_actions holds the discovery read, the
id-only invoke, and a process-wide TTL cache the console, the GTK page and the
Windows tile all read, so three shells cannot end up disagreeing about what a
host offers. Every shell warms it on a refresh tick it already had.
Discovery is PRE-fetched, never fetched when a menu opens: the console screen
holds a cloned row, and rows that appear under a cursor already moving are a
hazard when two of them shut a machine down. For the same reason the console's
armed state became WHICH row is armed rather than a bare flag — a flag let an
arming press on Forget fire Shut down host. Restart and shut down confirm;
sleep is reversible from the same menu, so it goes on one press. An action the
host says it cannot run right now stays listed, disabled, and says why.
Surfaces: console-UI rows + ConsoleCmd::HostAction with session and Android
dispatch; GTK card menu (plus a card-level Toast) with an AlertDialog confirm;
Windows tile menu, its label built and matched through one function so a menu
whose rows outlived their handlers cannot run a different verb; Android touch
home and Skia console; Apple host card and gamepad options. Unknown ids render
from the host's own title on all of them — a later host action needs no client
release to appear.
Typed close: the Swift hostPower case and the Kotlin host-power token. Without
them, sleeping your own host from the couch reads as a crash on those two
clients.
PR #428 taught scripts/install.sh about Omarchy: detection, the `-Sy` then `-S` split that gets past
the libalpm guard, and the hand-off to `punktfunk-omarchy setup`. It wired the INSTALL path only.
`--uninstall` removed the packages but left everything `punktfunk-omarchy setup` had put OUTSIDE
them: tagged ufw rules, the user-unit drop-in, the app-menu entry, hooks.json, and the
`custom_picker_binary` takeover in xdph.conf — the last of which keeps pointing a live compositor at
a picker shim that is no longer installed. `punktfunk-omarchy remove` is the reverse and is
idempotent, but it ships IN the host package, so it has to run before pacman takes it away. Its
guard carries the `|| [ "$DRY" = 1 ]` that step 1b already uses, so the dry-run matrix can see it on
a machine that has never had the package.
Gate 7's matrix had no Omarchy row at all, which is why this went unnoticed; its own comment says a
fix to the installer adds its case there. Three added — the split install, the setup hand-off, and
the uninstall — each proved non-vacuous by reverting the code it covers and watching the gate go red.
The first of those three now covers a fix that reached main separately: `run()`'s non-interactive
rewrite matched only `^sudo pacman -Syu `, so `--yes` and every terminal-less `curl | sh` asked
"Proceed with installation?" with stdin on /dev/null and died. The `-S ` rule that fixes it landed in
the --channel switch work while this branch was open. The row keeps it from regressing.
The guided installer covers apt, dnf, pacman and sysext boxes, but only the
install hub mentioned it — a reader who lands on /docs/ubuntu from a search
never learns the whole page has a one-liner. Put the same block above step 1
on every page the script actually detects, and leave NixOS, SteamOS and
Windows alone: the script refuses those and points at their pages.
Also list Omarchy on the hub cards and in the quickstart table. It was added
to the sidebar with #428 but never to the two pages that route people there.
On a fresh install the web console's FIRST start always failed at the systemd
level:
punktfunk-web.service: Failed to load environment files: No such file or directory
punktfunk-web.service: Failed to spawn 'start' task: No such file or directory
Failed with result 'resources'.
`punktfunk-web.service` declares `After=punktfunk-host.service`, but that was
never a readiness gate: the host is `Type=simple`, so systemd considers it
started the instant it is SPAWNED — seconds before it writes anything. The
console's mandatory `EnvironmentFile=%h/.config/punktfunk/mgmt-token` then read
a file that did not exist yet. `StartLimitIntervalSec=0` meant the restart two
seconds later succeeded, so the console did come up — but the first enable
printed a hard failure on a perfectly good install, and every caller that
watches the exit status believed it.
Field report 2026-08-28 (Omarchy): `punktfunk-omarchy setup` enables the host
and the console back to back, so it lost that race every single time and
reported "Failed to start punktfunk management web console" on an install where
pacman, the repo and all three packages were fine.
The gate now lives in punktfunk-web-init.service, which the console already
orders after (`After=` + `Wants=`) and which is `Type=oneshot` — so blocking
there is the readiness gate the ordering already claimed to be. No new unit, no
new directive, no change to the host's startup path.
It waits for the console's OWN precondition rather than a proxy for it, which
matters because the two files it needs are written far apart: `mgmt-token` goes
out early in `serve` (main.rs, before the listeners) while the identity cert
comes LAST, inside `mgmt::run` -> `identity::load_or_adopt`. Waiting on the
token alone would only have moved the failure to the cert. The check mirrors
web/nitro-entry/tls-paths.mjs exactly: a token, plus a non-empty cert/key pair
from one directory — native, or legacy for a host that never took the identity
split.
Also drops `ConditionPathExists=!%h/.config/punktfunk/web-password` from
web-init. That skipped the unit from the second boot onward, which is precisely
when the wait must still run, and it tied a host-readiness gate to the presence
of an unrelated password file. web-init.sh is idempotent instead, and in steady
state (every start after the host's first run) it returns without sleeping.
Timing out is not fatal — it exits 0 so the console still starts and the
existing Restart backstop takes over, but says WHY, where the bare systemd error
it replaces named a missing file and never the host that owed it.
Mirrored into the NixOS module, and module-check.nix now asserts the absence of
the path condition it used to assert the presence of. All four Linux packages
(deb, RPM, Arch, and Bazzite via the RPM) ship the same two files, so the fix
reaches every one of them from here.
check-docs-drift.sh gate 8 runs the real script against a faked config dir:
it waits when nothing is there, still waits when only the token is there (the
leg a token-only fix would have missed), returns instantly for both the native
and the legacy identity, and stops waiting as soon as the files land. Each case
proved non-vacuous by reverting the fix and watching it go red.
`--channel canary` already worked, but only on a box with nothing installed:
the guided installer skips its whole install block once the three binaries are
on PATH, so re-running it with `--channel` on an existing host printed
"already installed" and changed nothing at all. Switching was a docs page of
`sed` one-liners you ran by hand.
Now `--channel` means the same thing on a fresh box and an installed one, and
it means it in both directions. A switch is a repo rewrite plus a re-resolve
that is allowed to go DOWN — canary is always a minor ahead of stable by
construction, so canary→stable is a downgrade and every package manager
refuses one unless told: apt gets explicit version pins from `madison`,
pacman `-Sy` then `-S` (never `-Syu`, which looks at the lower stable version
and does nothing), dnf a `distro-sync` behind the `install`, and the sysext
script already moved both ways on its own per-feed rollback floor.
Three things that were quietly wrong fall out of doing this properly:
- pacman appended `[punktfunk-canary]` while leaving `[punktfunk]` in place,
so a canary install left both repos enabled and let repo order decide which
build you got. The switch drops whichever section is there first, reusing
--uninstall's own delete.
- `--channel` defaults to stable, so lifting the early-exit would have let a
bare re-run — to fix a group, to open a firewall port — silently drag a
canary box back a channel. With no explicit `--channel` the script now
follows whatever the box is on. The gate below is built around this case.
- A switch moves every punktfunk package on the box, not the three the script
installs, or a hand-installed punktfunk-gamescope is stranded on the channel
the machine just left. That set comes from --uninstall's existing query.
Verification, since a downgrade path touches packages people already have:
check-docs-drift gains gate 8, six --dry-run cases over the four families with
the repo config and the installed binaries faked (`PUNKTFUNK_INSTALL_ETC`
joins `PUNKTFUNK_INSTALL_OS_RELEASE` as a testing override). The case that
matters is a canary box missing a package and re-run bare — mutating the
follow-the-box rule turns it red, which is how it was checked. installer-smoke
adds the round trip against the real registries, where the version has to move
and then come back; the textual gate proves the commands are emitted, only
that one proves the downgrade happens.
design/host-actions.md P0 (host core) + P1 (web console). A reusable action
registry — GET /api/v1/actions (per-caller permission + honest availability) and
an id-only POST /api/v1/actions/{id} on the mgmt cert lane — with three power
built-ins, so the Wake-on-LAN round trip finally closes from the couch.
Core: GRANT_POWER (1<<6) joins the mask; GRANT_ALL 0x3F -> 0x7F; the legacy-full
read rule (an explicitly stored pre-power 0x3F reads as the current GRANT_ALL,
so old Full records neither render Custom nor silently lack Power); typed close
RejectReason::HostPower (0x6B) so ended sessions say why.
Host: power executors (logind via zbus behind the already-shipped polkit rule,
deliberately without -ignore-inhibit; Windows SeShutdownPrivilege +
InitiateSystemShutdownExW / SetSuspendState; macOS answers 501); ordering
reply-202 -> typed close -> 1 s grace -> act; single-flight; another device's
live session blocks a cert-lane invoke (409); action.invoked on the event bus;
denials logged once per (fingerprint, action) per boot. The plugin token gets
neither route.
Console: Host-power card (password-confirmed, the update-apply recipe) + a BFF
route that keeps the invoke off the ungated catch-all; Host power toggle in the
Access sheet. Mirrors: web/Kotlin/Swift consts + legacy rule, pf-client-core
preset_label now masks (an old client no longer renders a new host's Full as
Custom). Tray's service-restart row renamed Restart Punktfunk before the
clients ship a machine-level Restart host. Docs: host-power page, access-levels
row, WoL cross-link. openapi/header/SDK regenerated.
`topology: exclusive` on Hyprland left the operator's heads disabled after a
failed session, recoverable only by a hand-run `hyprctl reload`. The cause is
neither a failing reload nor the registry: it is one line in `apply_topology`.
The host opens the vdisplay backend ONCE and lends it to
`build_pipeline_with_retry` for up to eight attempts, so `create` — and with it
`apply_topology` — runs repeatedly against one instance's `pending_restore`
slot. Attempt 1 disables the heads and prepares the restore; attempts 2..n then
correctly find nothing left to disable (attempt 1 already darkened everything)
and prepare `None`. The slot was assigned unconditionally, so attempt 2 dropped
attempt 1's closure on the floor. When the build finally failed and the backend
dropped, its `Drop` had nothing to run — which is exactly why the field journal
shows `disabled=[...]`, ten `nothing to disable`, and no `restore_heads` line of
either polarity.
`stash_topology_restore` makes the slot first-wins. First is also the RIGHT
list, not merely the surviving one: attempt 1 looked at the desk while it was
still lit, so its set is every head that was on; a later attempt can only see a
subset.
Two corrections to what the code claimed about itself, since they are what made
this read as a registry bug. The Hyprland and sway `pending_restore` docs said
the registry picks the restore up and `Drop` is a mere backstop. It does not:
both backends carry a portal fd, so `registry::acquire` returns them as
pass-through at the `remote_fd.is_some()` check, several statements ABOVE its
`take_topology_restore()` call. Nothing ever lifts these into a display group,
and `Drop` is the only thing that runs them. The per-group hand-off machinery
is real, tested and correct — it just serves KWin, not these two.
That leaves a genuine per-session restore on the wlr-family backends (two
concurrent exclusive sessions: the first to end re-enables the heads under the
second), which is now written down at the field rather than contradicted there.
Closing it needs group bookkeeping the pass-through path does not have, so it
stays #284's call, not a drive-by restructure.
KWin gets the same guard although its slot is drained by the registry after
every create, so it cannot strand today — one of three identical sites left
unguarded is how this comes back.
Four tests in `backend.rs` cover the failure shape, the one that matters being
eight attempts with only the first having heads to disable. Verified by backing
the guard out: it fails with "the retry loop stranded the restore — the desk
stays dark".
`tsc --noEmit` under `noUncheckedIndexedAccess`: destructuring `ticket.split(".")` yields
`string | undefined` per element, and `parts.length !== 3` does not narrow a plain array — so five
type errors on the regex tests and the compare. An explicit `!ts || !nonce || !mac` guard proves it
to the compiler AND rejects the empty segments a `"1..2"` ticket would otherwise reach the regexes
with, which is what the removed `parts.some(p => p.length === 0)` was doing less directly.
Caught by CI's `web` job, not by me: I ran `bun test` and biome and stopped there. The typecheck
needs `node_modules`, which a fresh worktree has none of, and I took the two h3 import failures as
"pre-existing" without noticing that the same missing install was hiding the type check entirely.
With the deps in place the full web suite is 36/36 and `tsc --noEmit` exits 0.
A field client streamed over the host's ZeroTier address while both
machines shared a LAN. Neither end chose that: the host registers
exactly one address (its routed primary), but the OS's own mDNS
responder also answers A queries for <host>.local. per interface with
that interface's address, so the resolved set a client folds is a union
polluted by every overlay network whose multicast reaches it - and both
clients picked with HashSet::iter().next(): arbitrary, and re-rolled on
every re-announce.
punktfunk_core::discovery now makes the pick deterministic, shared by
the desktop and Android clients. Ranking, best wins: longest common
prefix with any of this machine's unicast addresses (on-link beats
routed, which settles LAN-vs-overlay in BOTH directions - a client that
can only reach the host through the overlay has no interface for the
host's LAN address to match), then the address the host itself declared,
then prefix against our default-route source, then the numerically
lowest. The host declares which address its advert is FOR in a new
advisory TXT key (addr); it never overrides reachability, only settles
a multi-NIC host's tie, and old hosts without it still resolve
deterministically.
WP7 shipped a template and no consumer. `punktfunk.json.tpl` rendered fine — Omarchy globs
`~/.config/omarchy/themed/*.tpl` and writes the result to
`~/.local/state/omarchy/current/theme/` on every `omarchy-theme-set`, and the keys the template
asks for (`mode`, `accent`, `background`, `foreground`) all exist in a theme's `colors.toml`,
verified against tokyo-night on the box. Nothing read it, so nothing changed, which is exactly what
"the theme is not applied" looks like from the outside.
Now: the server reads the rendered file and `ui-config` carries it; the root applies `mode` as the
`.dark` class the whole stylesheet already keys off, and `accent` as the brand variable
`--primary`, `--accent` and `--ring` all derive from. One value re-tints the buttons, the active
nav and the focus rings together.
BOTH brand variables, not just `--pf-brand`. The light palette derives `--primary` from it, but
`.dark` derives `--primary` from `--pf-brand-light`, and the console ships pinned dark — so setting
only the first would have re-tinted light mode and done nothing whatsoever in the mode people
actually see.
The accent reaches a style attribute, so the reader validates it as a colour rather than trusting
the file: hex and the functional notations Omarchy themes use, nothing else. That is not
theoretical tidiness — an UNRENDERED template contains the literal `{{ accent }}`, and a theme
switch can be caught mid-write. Both are "no theme" here, and no theme means the console's own
violet, which is also what SSR paints and what shows for the moment before the fetch resolves.
Every failure is the fallback; none is an error page.
Read per request rather than cached, because `omarchy-theme-set` rewrites the file whenever the
user switches and a console that only looked at startup would be wrong until it restarted.
Verified on the box: the template renders (`"mode":"dark","accent":"#7aa2f7"`), and the reader
parses that exact file. 14 tests, biome clean.
⚠ Like the handoff, the console half needs a `punktfunk-web` build to reach a box — it ships as a
prebuilt Nitro `.output` and the Omarchy testbox has no bun — so this is unit-tested and
file-verified but has not painted a pixel on glass.
Three things an Omarchy user meets in the first minute, all of which were wrong.
The login (the handoff)
-----------------------
Asking for a password to open your own console from your own app menu buys nothing — but the
obvious fix, dropping the login, is not available: the console binds **0.0.0.0:47992** so it can be
reached from a phone, and its admin surface is pairing, unpair and session control. Trusting the
network would hand that to the LAN.
So trust what actually distinguishes the operator: the **management token**, a 0600 file inside the
0700 config dir. `punktfunk-host ctl console-url` mints a ticket signed with it; the console
verifies with the copy it already holds and seals the ordinary session cookie. Whoever can read
that file can already drive the whole admin API — it is the credential the console's own proxy
presents — so skipping a password they could simply read widens nothing, and a visitor without a
ticket still meets the login page.
`<unix-seconds>.<nonce>.<HMAC-SHA256>` over `pf-console-handoff:v1:ts:nonce`. 60 s TTL, single use,
symmetric window (a ticket from the future is as wrong as an old one), one 401 for every rejection
so probing learns nothing. No new host route and no shared state: both sides already hold the key.
The decision lives in `util/handoff` rather than the route so it is testable without an h3 event —
and the test suite includes a vector minted by the real Rust host and cross-checked against
python's `hmac`, so a drift in the message format fails here instead of six weeks later in the
field.
The launcher entry
------------------
`Icon=` was empty, so the entry drew nothing. Two causes: the host package never shipped an app
icon (only the CLIENT package installed `io.unom.Punktfunk.svg`), and `omarchy-webapp-install`
derives an icon name with `${ref%.*}` + slugify, which turns a dotted theme name into `io-unom` —
resolving to nothing. The host package now ships the scalable mark, and setup writes `Icon=` and
`Exec=` itself after letting their tool create the entry.
The Omarchy menu
----------------
Super+Space had only the webapp. There is now a Punktfunk submenu — open console, pair a device,
devices waiting, paired devices, stop the session, status, restart — with `when` guards so a row
the box cannot honour does not show.
D7 avoided writing the user's `omarchy-menu.jsonc` because it is a single document where one parse
error silently drops EVERY row they own. That risk is real, so the merge earns its place: work on a
copy, insert between markers so a re-run replaces rather than stacks, validate the result as JSONC
AND confirm our rows actually landed, and only then move it into place. A file that does not parse
to begin with is left completely alone — it is not ours to repair. `remove` takes the block back
out and restores their file byte for byte.
Two bugs the self-check caught before the box did: `awk -v` refuses a newline inside a `-v`
assignment, so the rows silently never landed while the function reported success (hence the merge
now verifies its own output, not just that the file still parses); and `MENU_FILE` was a `readonly`
computed at LOAD time, so it ignored an `XDG_CONFIG_HOME` set afterwards and edited the real config
of the machine running the test. Paths resolve at call time now, like `write_hooks` already did.
Gates: fmt, clippy -D warnings, 13 ctl tests, 7 handoff tests, 13 shell self-checks, docs-drift,
shellcheck. On the box: the ticket verifies against an independent HMAC, two tickets in the same
second differ, and the launcher entry carries the right Exec and Icon.
⚠ The console half needs a `punktfunk-web` build to reach a box — it ships as a prebuilt Nitro
`.output`, and there is no bun on the Omarchy testbox — so the route itself is unit-tested but has
not served a request on glass.
Restoring `custom_picker_binary` at the end of every cast meant the NEXT session found the config
changed, rewrote it, and restarted xdg-desktop-portal-hyprland — and a ScreenCast bound across an
xdph restart never delivers a buffer. The portal runtime caches its D-Bus connection
process-globally (`portal_thread`'s own note), so the restart orphans the cached connection and the
handshake then succeeds against a session nothing is alive to serve. That is the failure our own
error text already names: "a stream bound during a compositor (re)start that will never deliver".
So the restore moves to the host's shutdown path, through the `restore_takeover_now` hook the host
already calls on SIGTERM — no cast is live there, so the xdph restart it triggers costs nothing.
Leaving the shim installed between sessions is safe precisely because it DELEGATES: with no
selection pending it execs the picker that was configured before us, so an ordinary browser share
behaves exactly as it did. That is what D6 actually asks for — the user's screen sharing keeps
working — and it is what lets the takeover be idempotent instead of churning the file. A host that
is SIGKILLed still leaves the shim, and `punktfunk-omarchy remove` puts the original back from the
marker.
Found while chasing a black screen on Omarchy that turned out to have a different root cause (the
VM had two GPUs and the portal allocated on the wrong one), so this fixes a real defect that was
not the one being hunted — every session after the first would have restarted xdph underneath
itself regardless of the GPU topology.
#283's focus fix has never reached a Lua-configured Hyprland. The old note here said why and then
stopped: `hyprctl dispatch focusmonitor <name>` is parsed as `hl.dispatch(focusmonitor <name>)`
and dies with `')' expected near '<name>'`, and `hl.dsp.focusmonitor` does not exist. Both true.
The name was simply wrong.
Measured on Omarchy 4.0.1 / Hyprland 0.56.2, the spelling is
hl.dsp.focus({ monitor = "<name>" })
and the compositor volunteers it — ask with any other key and it answers "hl.focus: unrecognized
arguments. Expected one of: direction, monitor, window, urgent_or_last, last". Same two-era shape
as `dpms_one`: try classic, then Lua, report both if neither lands. Each spelling is rejected by
the other's parser, which is what makes running them blind safe.
This is not the cosmetic window-placement issue it was filed as. A headless output nothing has
focused stays empty; an empty output produces no damage; no damage means no PipeWire frames — and
capture then misses its first-frame deadline:
pipeline build failed — retrying attempt=4 max=8
error=first frame: no PipeWire frame within 10s (node 85): format negotiated but no buffers
arrived — the compositor produced no frames
i.e. a black screen on the client, on every Omarchy box.
It is only HALF the black screen seen on glass, and the other half is NOT fixed here. The same
session had already run `topology: exclusive`, which logged
`topology: exclusive` — the streamed output is now the desk disabled=["Virtual-1","HDMI-A-1"]
twice, and then never restored them: `restore_heads` logs on success AND on failure, and neither
line appears anywhere in the journal, so it was never called on the pipeline-build failure path.
The ten retries that followed all reported "had nothing to disable" — correctly, the heads were
already off — so once the first attempt fails the desk stays dark and every later attempt fails
for the same reason. `hyprctl reload` is the recovery. That belongs to #284's in-flight work
rather than here, so it is recorded with its evidence instead of half-fixed in a file another
effort is editing.
WP0 + S2 run against a real Omarchy 4.0.1 box (Hyprland 0.56.2, Quickshell 0.3.1, RTX 5070 Ti).
Everything below is a measurement, not a re-reading of the docs.
Fixed, each one a first-run defect
----------------------------------
1. **The install line could not work.** Omarchy ships a libalpm PreTransaction hook
(00-omarchy-update-guard) that aborts any transaction whose pacman invocation carries BOTH
-S and -u, to funnel upgrades through `omarchy update`. So the Arch line this branch shipped
for Omarchy — `pacman -Syu <pkgs>` — dies with "Woah partner..." and installs NOTHING. Seen
in /var/log/pacman.log, then confirmed the other way: `pacman -Sy` + `pacman -S <pkgs>`
installs all three cleanly. platforms.json, the docs page and install.sh now split the two,
and plain Arch keeps its full -Syu (a partial upgrade against a ROLLING repo is what breaks
those boxes; Omarchy's frozen snapshot mirror is exactly why it does not break here).
2. **The idle guard never restored anything.** `omarchy-toggle-idle status` prints JSON, not a
keyword — and the payload is a trap: its tooltip names the action the button WOULD take, so
the string "Stay Awake" appears precisely when stay-awake is OFF. The old case-glob matched
neither that nor the words it was looking for, so every arm fell through to "do nothing" and
the box stayed awake after every session. Now reads `"enabled":true`. Verified both ways on
the real tool: a user's own stay-awake survives a stream, one we set is undone.
3. **`status` lied twice.** It reported "no punktfunk rules" seconds after adding six of them
(a failed `sudo -n` read was being treated as proof of absence), and reported xdph missing on
a box that was capturing through it — `pgrep -x` can never match `xdg-desktop-portal-hyprland`
because Linux truncates comm to 15 characters, and pgrep says so on a stderr the check threw
away. Now: never claim absence from a failed read, and ask systemd about the portal.
4. **D3's premise is only half true.** Omarchy ships TWO session entries. On `hyprland-uwsm`
graphical-session.target starts; on plain `hyprland` it never does — measured, and Omarchy's
OWN units that want it (omarchy-crash-watch, omarchy-sleep-lock) sit enabled-and-dead there
too. The drop-in is additive so autostart still works either way, but "restarts with your
session" was a promise we could not keep. setup and status now detect and say which it is,
and the docs explain when switching sessions is worth it (rarely: the host re-derives the
live compositor per connect).
5. **`ctl watch` leaked a stream per dead consumer.** A watcher only ever READS, so when the
widget died its end of our stdout pipe closed unnoticed: six orphans accumulated across three
shell restarts on a host with no events at all. The SSE keep-alive now surfaces as a
`ctl.heartbeat` line, which gives us a write to fail on, and a failed write ends the process.
Verified with its control: dies ~13s after its reader goes, survives 50s while the reader lives.
Confirmed as designed
---------------------
* **D6 end to end.** The box's xdph.conf is exactly the shape the fix targets. A real capture
(xdph → PipeWire 1920x1080 → cuda-import → nvenc) installed the shim, the shim picked up
`hyprland-preview-share-picker` as its fallback automatically, the restore fired on teardown,
and the file came back byte-identical with no marker left. The landmine is defused.
* **The pin correction.** The mgmt port serves 306d95… = native-cert.pem; cert.pem is 34a4cb…,
a different certificate entirely. Pinning cert.pem as the plan said would have exited 4 on
every healthy host. All four exit codes exercised on glass — 4 by pointing ctl at the host's
own legacy cert, which is a valid certificate that simply is not the one mgmt serves.
* **R1 and R3 closed.** Our soname depends (libavcodec.so=63-64 …) match the frozen snapshot
mirror's ffmpeg 9.0.1 exactly, and /etc/pacman.conf is owned by pacman, not omarchy-settings,
so our repo stanza is not clobbered. R4 closed by (1); R7 closed — enforce_permissions is off
as shipped.
* The tree builds on Omarchy in 8m16s against the snapshot's toolchain (rustc 1.98).
Gates: fmt, clippy -D warnings, 13 ctl tests, docs-drift, shellcheck, 8 shell self-checks.
Diagnostics catalog rows for the console's troubleshooting page (design §3.M, WP1).
`hyprland_permissions` — Hyprland 0.49+ can enforce per-application permissions, and when
it does, screencopy and virtual input are denied SILENTLY: black frames and dead input,
with no error from the host and none from the compositor. Every other failure on that path
announces itself; this one is the reason the row exists. Warning rather than Critical on
purpose — enforcement being ON does not mean we are denied, a granted host streams fine,
and no probe outside the compositor can tell the two apart. Not Omarchy-specific: it
applies to every Hyprland box, and Omarchy is merely the distro most likely to turn it on.
`omarchy_updates` — on Omarchy the console's apply button is deliberately absent (D5).
Without a row saying where updates come from instead, "my update button is missing" is an
unanswerable support question, asked in the one place we could have answered it.
Both ids are registered in the documented-ids test, so a rename is caught in review rather
than in a bug report about a check that suddenly renders in English.
Host suite: 678 pass. The one red — gamestream::stream::tests::sender_delivers_batches —
is the documented EINTR flake in this qemu container: it fails identically with these
changes stashed, it lives in a file this branch never touches, and the panic is literally
"Interrupted system call".
Implements the Omarchy integration plan (punktfunk-planning design/omarchy-integration.md
+ omarchy-integration-implementation-plan.md): the ctl surface M-C1..C4, design WP1-WP7,
and the D6 xdph landmine. WP0 (the measurement battery) and WP11 (upstreaming) are not
here — the first needs an Omarchy box, the second needs an explicit go.
`punktfunk-host ctl` (WP8 / M-C1..C4)
------------------------------------
A subcommand, not a second binary. The entry-point analysis is in the plan's §3; the
short version is that a new binary touches every Linux artifact we ship to buy nothing,
while `main.rs` already dispatches a dozen verbs and in-crate means no second declaration
of the mgmt types to drift.
15 verbs over the existing admin lane — pairing arm/pending/approve/deny, the Moonlight
PIN, both planes' device lists with rename/unpair/access presets, session stop/end-game,
and `watch`, which bridges the SSE stream to line-JSON on stdout with `Last-Event-ID`
resume and a synthetic `ctl.resync` line after a `dropped` frame. `--json` on every verb
returns a versioned envelope; the human tables are not parsed by anything we ship.
The security model is the plan's §§1-2, and the load-bearing part is **pin before token**:
the agent pins the host's own leaf (via punktfunk-core's canonical `PinVerify`) and rustls
rejects a mismatch *during the handshake*, so ureq never gets as far as serialising an
`Authorization` header. That closes the local port-squat vector with zero server-side
change — `mgmt/auth.rs` is untouched by this whole surface. There is deliberately no
`--token` flag and no token env read: a credential in either is readable cross-uid through
/proc, which is what the 0700 config dir exists to prevent. ctl consumes the token the
host persists and never mints one (the `web-password` silent-adoption lesson, inverted).
Two corrections to the plan, both from reading the code rather than the doc:
* the mgmt listener serves the NATIVE identity, so the pin is `native-cert.pem` then
`cert.pem` — pinning `cert.pem` alone would exit 4 on a perfectly healthy host;
* the pin is a SHA-256 fingerprint compare through the existing audited verifier, not a
new bytes-compare. Same property, one less thing to review.
The test that matters is the negative: a squatter presenting a valid, well-formed,
wrong self-signed certificate gets exit 4 and receives ZERO application bytes.
The xdph collision (D6)
-----------------------
Omarchy ships its own `~/.config/hypr/xdph.conf` naming `hyprland-preview-share-picker` —
the picker every browser share on the box goes through — and our Hyprland backend takes
`custom_picker_binary` over on first connect. The merge half was already right (one key,
in place, with a backup); the way back did not exist, so a box that had ever streamed kept
our shim forever, including after a crash and after a reboot.
Two changes, and the first is the one that does not depend on getting teardown right: the
shim now DELEGATES — with no selection pending it execs whatever was configured before us,
so ordinary browser shares behave exactly as they did, during a session, after it, after a
kill and after a reboot that emptied $XDG_RUNTIME_DIR. Second, the edit records what it
replaced (a marker comment written in the same atomic write, so it survives everything a
sidecar state file would not), and the picker is handed back when the last cast ends.
`punktfunk-omarchy remove` restores it too, from the same marker.
The rest
--------
* WP1 — `osinfo::is_omarchy()`; the console update tier is notify-only on Omarchy and
names `omarchy update`. Enforced at the apply route, not merely reported: a direct POST
on a box with the helper, the group and the sysupgrade opt-in would otherwise run
`pacman -Syu` into their guard, or past it, skipping the snapper snapshot their rollback
depends on.
* WP2/WP3 — `punktfunk-omarchy setup|remove|status`, installed but never run by the
package (packages do not open firewalls or edit user config behind an operator's back).
LAN-scoped comment-tagged ufw rules over our existing app profiles, the session drop-in
that Omarchy's uwsm actually starts, the console as a webapp rather than an edit to the
user's single menu JSONC, and a Sunshine-coexistence check that says plainly which plane
collides. PKGBUILD gains the hyprland/xdph optdepends that were owed before Omarchy.
* WP4 — docs/omarchy.mdx, the ctl reference in host-cli.md, platforms.json (+ snapshot),
the Hyprland/Omarchy rows in requirements.md, an honest "not verified on glass" row in
the support matrix, and an install.sh branch that hands over to `punktfunk-omarchy setup`.
* WP5/WP6/WP7 — sample hooks wired through hooks.json (never host.env: hooks are a list,
and an operator's existing file is printed to rather than overwritten), an idle guard
that snapshots and RESTORES the user's own stay-awake setting rather than assuming, and
the theme template.
Gates: fmt, clippy -D warnings on punktfunk-host and pf-vdisplay's Linux half, 45 host
tests, 267 pf-vdisplay tests, check-docs-drift, shellcheck, and 8 shell self-checks
covering the awk picker restore and the hooks.json generator against the same fixtures
the Rust round-trip tests use.
Not verified on an Omarchy box — nothing activates without `punktfunk-omarchy setup`, so
a plain Arch box is unaffected either way.
Two field sessions on 0.32.0 (Windows client over ZeroTier, Android over
Wi-Fi) plus a local repro showed every Automatic session ratcheting
20 -> 2.3 Mbps on the first loss episode and never climbing back.
Phase 4 made the bitrate a wire budget: the encoder is handed
enc_kbps(budget) and the read-back maps through budget_kbps(). That
roundtrip deflates 1-2 kbps by design (the inverse never inflates), and
the applied < requested compare then recorded a phantom
encoder_ceiling_kbps on EVERY successful apply. The control task clamps
each later SetBitrate to it, so every climb was acked short at the
current rate, the client controller learned it as a host cap
(reprobe backoff 16 -> 32 windows), and each descent lowered the
"ceiling" further: a one-way ratchet to the floor. 0.31.4 was immune -
its read-back stayed in encoder units, so an in-range apply compared
equal. EncDerive::applied_budget_kbps now reads back in the request's
own truncated terms: only an apply short of what the request itself
derives to - a genuine driver clamp - records a ceiling. Regression
test proven against the backed-out fix.
The startup link-capacity probe fired on a flat 2 s timer, but host
bring-up can take 6-8 s (IDD display acquisition), so the 940/464 Mbps
burst landed exactly on the first IDR - black video for 5-11 s, the
decoder refusing AUs ("PPS 0 not seen"), 2101 audio underruns - and the
result missed the 6 s timeout anyway (bring-up plus the burst's own
queue drain and QUIC loss-recovery backoff: 8.6 s measured), so the
ceiling stayed negotiated: all disturbance, no measurement. The probe
now arms only once a frame has completed, and the timeout is 15 s so a
slow answer still teaches the ceiling.
VIDEO_CAP_HDR invites a PQ stream, and on a Windows box with no HDR10
swapchain the D3D11VA hand-off shows it through the video processor's
PQ->sRGB tonemap — a driver capability nothing ever validated. The Blt
accepts the colorspaces either way and renders garbage where the
conversion is missing (host-side sibling: NVIDIA RGB->P010 'renders
green'). Field 2026-08-26: an Arc A370M client went green on every HDR
session while AV1 8-bit SDR at the same 2880x1620@120 streamed clean.
video_d3d11 gains pq_tonemap_supported() — one throwaway device +
enumerator asked CheckVideoProcessorFormatConversion for the exact pair
the SDR ring sets (P010 G2084 studio in, BGRA8 sRGB out). Only the
driver's definitive 'no' answers false; API failure keeps today's
behaviour. video::hdr_presentable() wraps it behind the short-circuits
that make it free everywhere it doesn't matter (!d3d11_import,
d3d11_hdr10 pass-through, non-Windows shader tonemap), and the session
binary ANDs the HDR setting with it exactly like the 4:4:4 promise —
loud warn when the switch is on and not honored. ten_bit_sdr stays
unprobed on purpose: 10-bit SDR is no tonemap.
Also: log_layout_once keys on decoder x layout instead of decoder alone,
so a mid-stream Reconfigure or SDR<->PQ flip re-logs the frame-vs-pool
dims — the fact a green-bar/smear report hinges on — for the shape that
failed, not just the one the session started at.
Verified: cargo fmt + dockerized Linux clippy -D warnings green for
pf-client-core + punktfunk-client-session; the cfg(windows) half needs
the Windows CI leg (not compilable from this box).
Ports the IMU liveness gate to the Android client so both clients apply the
same policy: zero the IMU block while its timestamp is frozen, pass it through
once it advances. Pure JVM tests pin the truth table.
Captures an OS-paired Steam Controller 2 over its custom Valve GATT service
and forwards raw reports to the host's virtual pad, with a settings toggle and
an on-stream passthrough badge.
The custom service coexists with the OS's own HID-over-GATT binding, so no
unpairing is needed. Two framing rules matter: a characteristic value carries
no HID report-id byte, so 0x45 is re-prepended on the way up; and output
reports are routed per id to their own characteristic at 100F6C<id+0x35>, with
the id stripped from the payload.
The IMU block streams frozen at a stale non-zero resting sample until Steam
enables the gyro, which reads as constant rotation and flies the desktop
cursor — so the block passes through only while its timestamp is advancing.
All framing and table logic is CoreBluetooth-free and unit tested; only the
transport shim touches the radio.
Adds send_hid_report and the HidRaw host-to-client return path to the client
C ABI (ABI_VERSION 26 -> 27, a breaking bump), and stops the Windows host
folding a captured Steam Controller 2 down to an Xbox 360 pad — the SC2 kind
now reaches the Triton backend as-is.
Also adds a --triton bench pad to the host devtest harness, for driving the
claim path without physical hardware.
Gives the pf-gamepad UMDF minidriver an eighth identity, pf_triton, with the
Triton USB/HID descriptors and an in-driver answer to Steam's feature query
dance, and adds the pf-inject backend that drives it over the existing
shared-memory ring.
Output frames are trimmed to their declared per-id length before forwarding,
so a 0x80 rumble goes out as 10 bytes rather than a 64-byte padded write.
Feature SETs are tagged in the ring's length word so the drain can tell them
from interrupt output.
Triton delivery is EVENT-DRIVEN: a read completes only when the input
latch actually changes, where every other identity keeps the 2 ms
every-tick cadence. The pad carries the physical controller BLE reports
and iOS floors the connection interval at ~15 ms, so re-serving the latch
every tick handed Steam ~7 identical reports followed by one holding a
full 15 ms of trackpad travel — read as a flick ~7x faster than the finger
made it (runaway trackball momentum, bench 2026-08-23). Real hardware NAKs
the interrupt IN when it has nothing new; leaving the read pended is this
stack equivalent.
Adds the Triton (2026 Steam Controller, Valve 28DE:1302) device type to the
shared no_std driver protocol crate: the captured 372-byte HID report
descriptor, the per-id output-report length table, and the feature-report
query dance Steam's GetControllerInfo runs (0x83 attributes, 0xAE string,
0xF2 firmware info).
The reply must echo the last SET's command byte or Steam treats the pad as
broken and never adopts it. Identity values served to Steam are synthetic by
construction: the unit id is "TRI\0" | index, the serial is FVPF-prefixed so
the host's physical-controller conflict gate excludes it, and the firmware
build time is pinned to a recent date so Steam does not offer to "update" a
virtual pad.
Descriptor and per-id map were established against physical hardware on the
bench (2026-06-08/09).
biome is not in ci.yml's web gate, so formatting and import order had drifted; `biome check
--write` accounts for most of this diff. `biome migrate` moved the deprecated
linter.rules.recommended to rules.preset. public/ and storybook-static/ are excluded — biome
was linting the favicon as if it were inline JSX and asking it for a <title>.
Three findings were real:
- Library lifted the whole entry list into state so the providers card could count owners.
That consumer is gone: `entries` was written on every grid load and read by nothing. The
state, the `onEntries` prop threading it up, and the effect firing it are all removed —
including from LibraryGrid, where the callback had no callers left.
- `flatten` in SourceSettings spread the accumulator per `allOf` branch, rebuilding the object
each time. Object.assign onto an accumulator that already starts as a fresh copy of the node
is the same result without the O(n²).
- LogsCard's `newestVisible` dep already carried a comment begging the next person not to
"fix" it — it is a trigger, not a read, and removing it silently breaks follow-mode. That
warning is now a biome-ignore, so the tool enforces it instead of prose hoping to.
Build, tsc, 22 tests and biome all clean.
@unom/ui has exported `reloadOnStaleChunk` for exactly this the whole time and nothing had
ever imported it — the copy added a few commits ago was a fourth implementation of a solved
problem. Both routers now call the library.
0.10.0 grew the two things using it turned up: an optional `resolveTarget`, so the recovery
lands on the page the user was navigating to rather than reloading in place, and a try/catch
around the sessionStorage guard, because blocked storage throws on `getItem` and that throw
escaping the listener leaves the tab on exactly the dead page the helper exists to prevent.
The helper installs once, so the callback reads a module-level ref rather than closing over a
router: hydration builds a second router and discards the first, which is the same reason the
console keeps its QueryClient in one.
Deps: @unom/ui 0.10.0 and motion 13.1 (0.10.0 widened the peer, which is what had pinned us to
12), plus @unom/app-ui 0.3.0 for the docs site.
docs-site: build + tsc clean, and the deploy simulation still recovers onto /docs with the
library helper in place. web: build + tsc + 22 tests clean, bun.nix regenerated.
Everything in range moves to current — TanStack router/start/query, fumadocs, radix,
recharts, orval, storybook, biome, paraglide, playwright — and the majors that were
holding both apps a generation back go with them: Vite 7 to 8, @vitejs/plugin-react 5 to
6, vite-tsconfig-paths 5 to 6, @types/node 22 to 26, TypeScript 5.9 to 7. The marketing
site already ran the Vite 8 line against TanStack Start, so this closes a split the
monorepo was carrying for no reason.
Two of the console's majors were fixing a mismatch rather than chasing a number:
@unom/ui@0.9.2 asks for lucide-react ^1.17 and depends on tailwind-merge ^3.6, while the
console was pinned to lucide-react 0.469 and tailwind-merge 2.6.
motion is deliberately left on 12.43. 13.1 is available, but @unom/ui declares motion
^12.40 as a peer and inlines framer-motion 12.38, so moving the app alone would put two
motion runtimes in one tree — and a split motion context is exactly the failure that
neither a typecheck nor a build can see. It moves when @unom/ui does.
docs-site: build + tsc clean. web: build + tsc + 22 tests clean, bun.nix regenerated.
Routes are code-split, so every build names its chunks by content hash and a deploy
replaces the whole `.output`. A tab opened before the deploy still holds the previous
build's HTML, so the first navigation asks for `/assets/*-<oldhash>.js` — which the new
server has never heard of. The dynamic import rejects, nothing catches it, and the page
goes blank. `defaultPreload: "intent"` widens the window: a hover is enough to trip it.
Vite raises `vite:preloadError` for exactly this, and its preload helper wraps both the
dependency preloads and the module import itself, so the event fires before the router
ever sees the rejection. A full page load is the entire fix — the fresh HTML names the
new chunks. Navigating to `latestLocation` rather than reloading in place means a click
that tripped this still lands on the page the user asked for.
Deliberately not `preventDefault()`: that suppresses Vite's rethrow and resolves the
import with `undefined`, handing the router a broken module on the way out. A
sessionStorage stamp keeps a genuinely broken deploy from spinning in a reload loop, and
its read is wrapped because storage can be blocked outright.
Verified on the built docs site under Playwright, serving 404s for the chunks an open tab
asks for: without the handler the page collapses to 32 characters and no <main>, with it
the tab reloads onto /docs and renders in full. Re-verified after the Vite 8 bump.
`check-docs-drift.sh` matches on the `PUNKTFUNK_*` shape, which cannot tell an
environment variable from a cbindgen-exported ABI constant — so exporting
`PUNKTFUNK_CLIENT_CAP_KEEP_HOST_AUDIO` read as a new undocumented knob and
turned the job red. Every sibling is already listed for exactly this reason:
the four other `CLIENT_CAP_*`, all eight `HOST_CAP_*`, all eight
`VIDEO_CAP_*`. This one goes beside them, in sort order.
It is not documentation debt being waved through. The bit's user-facing half
is the "Keep host audio playing" row, already written up in client-settings.md
and pointed at from the `PUNKTFUNK_AUDIO_OUTPUT_MODE` table; the embedder's
half is the doc comment cbindgen carries into the header. There is no
configuration surface here to document, because there is no variable.
`keep_host_audio` shipped in 0.32.0 wired end to end — the setting, the
`CLIENT_CAP_KEEP_HOST_AUDIO` ask, the host's capture policy — but only three
surfaces ever offered it: the Linux GTK client, the Windows client, and the
desktop console. Apple and Android carried no reference to it at all, so the
one place a phone or an Apple TV would look for "why did my PC go quiet" had
nothing to find. There is no shared settings schema; each client hand-mirrors
`trust::Settings`, and this row simply never got mirrored.
Apple gains the full tier-P treatment: a `keepHostAudio` defaults key, the
`EffectiveSettings` field, the `StreamProfile` overlay (so a per-host profile
can keep the study PC's headphones live while the TV profile mutes them), the
Audio-section row, and the bit itself OR'd into the connect's `clientCaps`
beside the presenter caps. Android gains the same across `Settings`,
`Profiles` — including the `KNOWN` key set, without which the key reads as
unknown carry-through — the settings row, the console JSON both ways, and a
new `keepHostAudio` argument threaded through `nativeConnect` into the JNI
caps expression.
`pf-console-ui` had parked `RowId::KeepHostAudio` in `desktop_only` with a
comment saying "until the Android session advertises the bit". It does now, so
the gate comes off and the order-sensitive split test loses its entry.
The C ABI never exported the constant: `client_caps` is a passthrough byte, so
nothing needed a version bump, but cbindgen had no rename entry and emitted a
bare `CLIENT_CAP_KEEP_HOST_AUDIO` into every embedder's namespace — the exact
pollution R21 exists to prevent. It now carries the `PUNKTFUNK_` prefix its
`AUDIO_HIRES` sibling has, plus the compile-time drift assert.
Captions are the Linux client's wording verbatim, and the row sits between
audio quality and the microphone on all four clients, because a setting that
reads differently per platform is the same bug in a smaller font. The docs
line claiming "Linux, Windows and the desktop console" now says everywhere.
Verified: swift build + 384 Apple tests; `:app:compileDebugKotlin`;
`:kit:cargoNdkClippy` over pf-console-ui and the Android native crate; and all
205 pf-console-ui tests on Linux in a container, the split test among them.
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.
Two overstatements in the v0.32.0 notes, both flagged on reading the published
release.
**"anyone who could open your web console page"** was simply wrong, and it is the
sentence the Discord embed leads with. Reaching the pairing routes required an
ALREADY-AUTHENTICATED console session — it was privilege escalation inside the
console (those routes alone among the trust-root actions never re-asked for the
console password), not something an unauthenticated peer on the network could
touch. The notes now say so plainly, and say why it still mattered: pairing is
what grants launch, so a console sign-in became the ability to start a process on
the host.
**"58 security issues"** invites the reading that there were 58 exploitable
defects. There were 58 findings, and the long tail is minor hardening and
build-infrastructure tightening. Both documents now lead with that proportion
instead of the raw count.
Same correction applied to CHANGELOG.md in three places: the section intro, the
`Breaking changes` entry, and the security-review heading.
Nothing about the fix itself changed — only the description of its severity. The
tag does not need re-pointing: `announce.yml` checks out the ref it is dispatched
on rather than the tag, and `apply_release_notes` re-syncs the body from
`docs/releases/<tag>.md` there, so this lands in the announcement. The live
release body is PATCHed to match in the same pass.
Gates: the ISO 24495 auditor is back to its 2 standing findings (NVIDIA and AMD,
company names deliberately left unexpanded); check-docs-links.sh and
check-docs-drift.sh both exit 0.
`ci.yml`'s `cargo test --workspace --locked` has been failing at the very last
step for weeks, on a crate the diff never touched:
Doc-tests pf_capture
error[E0463]: can't find crate for `pf_frame`
--> crates/pf-capture/src/lib.rs:11:5
`pf-frame` is an unconditional dependency of `pf-capture`, the rustdoc command
line carries `--extern pf_frame=<path>`, and Format, both Clippy legs and Build
had all compiled `pf-capture` seconds earlier. The path simply no longer existed
by the time rustdoc opened it.
`tests/c_abi.rs::ensure_staticlib` is what removed it. It shells out to a NESTED
`cargo build -p punktfunk-core --features quic` while the OUTER `cargo test` is
mid-run. That resolves features for one package instead of the workspace union
the outer run resolved, so cargo rebuilds punktfunk-core's subgraph under
different metadata into the SHARED target directory — and the outer run's
pending units, which name `target/<profile>/deps/*.rlib` by explicit `--extern`
path, are left pointing at artifacts that have been replaced. Doctests run last,
so they are what falls over.
The old comment asserted the opposite, and that is the bug in one line:
// The outer cargo's build lock is released during test execution, so this is safe.
The released lock is why the nested build RUNS. It was never why it is safe.
Fix: build into `target/c-abi-harness/` and read the staticlib from there. The
nested build can no longer perturb the outer one, and the harness keeps doing
exactly what it did. Unconditional `--features quic` stays — that is `9c164aa6`'s
fix for a featureless `.a` being silently reused, and it is orthogonal.
Reproduced and verified on Ubuntu 26.04 (the CI base — 24.04's PipeWire is too
old to compile pf-capture's lib test), one variable at a time:
cargo test -p punktfunk-core -p pf-capture --locked --no-fail-fast
before -> exit 101, E0463 on pf_frame
before, --skip c_abi_harness_round_trips -> exit 0 (isolates the cause)
after -> exit 0, harness still PASSes
(abi_version=26, 4 frames round-tripped)
Each from a wiped target dir. `cargo test -p punktfunk-core --test c_abi` also
passes on macOS, where the staticlib path moved.
Why it looked intermittent: whether the doctest step is reached at all depends on
what else in the workspace fails first, and `9c164aa6` made the nested build
unconditional — before that it ran only when the `.a` was missing.
`super::super::stall::classify` in `idd_push.rs`'s test module resolves to
`windows::stall`, which does not exist — `mod stall;` is declared at
`idd_push.rs:332`, so `stall` is a child of `idd_push`, and the test module is
its sibling. A nested `fn` does not add a module level for path resolution,
which is what the extra `super::` was reaching for. The `use
super::stall::{ProbeWindow, StallClass, StallVerdict}` two lines above, in the
same test fn, already had the depth right.
Windows-only and test-only, so it reached main behind a green Build: the error
appears solely under `--all-targets`, when the lib TEST target is compiled.
`package`'s "Clippy (host + tray, Windows)" step has failed on every push since
`11217341` landed it (#413), which is the same shape as #408 — a Windows break
the Mac and Linux dev loops cannot see. The commit that introduced it verified
the logic by extracting `stall.rs` into a native scratch crate, so this test was
never compiled for Windows before it merged.
Reproduced and fixed with `scripts/xcheck.sh`, which covers exactly this and
takes seconds on the Mac:
scripts/xcheck.sh windows clippy # broken: exit 101, error[E0433] at :2528
scripts/xcheck.sh windows clippy # fixed: exit 0
scripts/xcheck.sh linux clippy # exit 0
Rides in the 0.32.0 release branch because it blocks the Windows installer: the
`package` job fails before "Pack + sign installer", so a tag cut over this main
would publish a release with no Windows host attached.
90 commits since v0.31.4 (63 non-merge), cut at db0f4f1e.
**The C ABI steps 25 -> 26.** `punktfunk_connect_opts` closes the
`punktfunk_connect_ex*` ladder: eleven generations each added a field by minting
a new exported symbol plus a 20-something-parameter forwarding shim, and the
replacement takes every option in ONE size-prefixed `PunktfunkConnectOpts`.
Every `ex` keeps its symbol and behaviour, so this is an added surface, not a
changed one. Layout is locked padding-free on both pointer widths (96/68 B) by
const asserts AND by the C harness compiling the same sizes.
The minor bump was already right before the ABI moved: ABR Phase 4 redefines
every control-plane bitrate as the TOTAL WIRE BUDGET rather than the encoder
rate, deliberately without a capability handshake. `include/punktfunk_core.h`
documents the 10-bit SDR ask as "0.32" and says "every pre-0.32 client sets the
two bits together", so the tree had pre-decided the number.
Version table, re-derived at HEAD rather than read off the diff:
* wire 2 -- unchanged. Three additive, ignorable additions: USER_FLAG_REPEAT,
CLIENT_CAP_KEEP_HOST_AUDIO, and Welcome::host_caps2 (trailing, absent -> 0)
carrying HOST_CAP2_REPEAT_MARK
* C ABI 25 -> 26 (above)
* crate dirs 27, 39 members, edition 2024, MSRV 1.85 -- unchanged
* driver proto 6, gamepad channel 3, plugin index 1, host event schema 1,
gamescope +pfhdr8, SDK 0.1.6 -- all unchanged; pf-driver-proto and
punktfunk-host/src/events.rs show no diff at all
* api/openapi.json 0.31.4 -> 0.32.0, content-identical (info.version is the
whole diff); both copies re-stamped and byte-identical to each other
* @punktfunk/plugin-kit stays 0.4.4 ON PURPOSE: plugin-kit/src/wire.ts changes
exactly one line and it is a doc comment in the launch.kind table.
`launcher_ui` is a bare string validated host-side, so nothing to republish.
The CHANGELOG's `heroic-console` entry was filed under v0.31.4, but ae13b29a
landed AFTER that tag -- so that frozen section described a change v0.31.4 does
not contain. Moved into the v0.32.0 section verbatim.
Seven behavioural breaking changes, none of them a version step, all listed in
CHANGELOG.md: the wire-budget redefinition; FLOOR_KBPS 5000 -> 2000; DSCP
defaults to AUTO (local peers only); GameStream video AND control encryption
default on (both graduated after their own on-glass pass on .173, and
`PUNKTFUNK_GS_ENCRYPT=video` is the new middle rung); PyroWave forces Automatic
bitrate; the console pairing routes move behind the console password (the
security review's critical finding -- a console session cookie alone reached
code execution); deep links auto-dial by stable record id only.
Release notes rewritten to the ISO 24495-1/-5 plain-language rules: sentences
under 30 words, paragraphs under 6 sentences, bold bullet lead-ins, an explicit
overview, a table of contents, and acronyms defined on first use. The plugin's
own text auditor reports 0 findings on the Play notes and 2 on the release
notes, both of which are the words NVIDIA and AMD -- company names, not
acronyms, deliberately left unexpanded.
`cargo audit` stays GREEN: h2 0.4.18 -> 0.4.19 closed RUSTSEC-2026-0258, left
open deliberately at the v0.31.1 cut. Only two allowed `unmaintained` warnings
remain (audiopus_sys, paste).
The Play whatsnew leads with the Android black screen, which is the one fault a
phone or TV user in this cycle could not work around.
Gates on the cut (the Mac): cargo fmt --all --check; cargo metadata --offline;
lock diff versions-only 36/36; cargo test -p punktfunk-core --lib --features
quic 503 passed / 0 failed; the C ABI harness PASSED (abi_version=26); the
regenerated header is not stale; check-docs-drift.sh; check-docs-links.sh; the
Play notes gate 412/500 chars and unique against 15 files; both openapi copies
cmp identical; repo voice scan clean; cargo audit green.
Why `configure()` passes and `start()` dies with an AImageReader output on the Mi
TV Stick class of device: configure only records the window — start is where ACodec
dequeues (and thereby gralloc-allocates) every codec output buffer from it, with a
usage that is the OR of our reader's consumer bits and the vendor decoder's private
producer bits. Our reader asked for GPU_SAMPLED_IMAGE | COMPOSER_OVERLAY; the
Amlogic OMX component adds its contiguous-vdec-memory flags. On phones (Codec2,
64-bit, gralloc4) that triple is routine. On a 32-bit OMX-era BSP, an app-side
consumer demanding overlay-scanout + GPU-sampled + vdec-writable in a single
allocation is the exotic ask, and a refusal surfaces exactly as
`start failed: ErrorUnknown` after a clean configure.
So the ladder gets a middle rung that keeps ASC instead of abandoning it: retry
with a reader asking for GPU_SAMPLED_IMAGE alone — the SurfaceTexture shape every
TextureView/WebView video path exercises, the most universally allocatable there
is. SurfaceFlinger then GPU-composites the layer (one 1080p quad — noise), and
everything that makes ASC worth having survives: real latch times, real release
fences, the learned panel period. setBuffer has no overlay requirement, so the
only cost is losing the HWC direct-scanout optimization on devices that were never
going to grant it anyway.
Usage is the only reader axis worth a rung: READER_MAX_IMAGES is not a start-time
factor (consumer-side images allocate lazily during streaming), so a start failure
that survives the gpu-only rung genuinely needs the SurfaceView rungs behind it.
The ladder is now: ASC overlay → ASC gpu-only → SurfaceView (aggressive keys) →
SurfaceView (plain keys), deduped as before so a device that works pays nothing
and each log line names the exact configuration that won or was refused. The
"asc: backend up" line now carries the reader profile too.
`configure()` succeeding says nothing about `start()` — start is where the codec
negotiates buffers with its output consumer and allocates them, so a decoder that
accepted the format can still refuse the surface it has to render into.
On a Xiaomi Mi TV Stick (Android 11, armeabi-v7a, OMX.amlogic.hevc.decoder.awesome2)
every session logged `start failed: ErrorUnknown` and the decode thread returned, so
not one access unit was ever fed while the pump kept receiving video. The frame queue
filled, the pump jumped to live once per FLUSH_COOLDOWN, and the host read that
perfect 2 s keyframe cadence as a client too slow to sustain the stream. Audio, input
and the library all kept working, so it presented as a permanent black screen with
sound — nine sessions of it in one log, and nothing on the host able to see why.
Give the async loop a bring-up ladder instead of one attempt. A codec that failed
start is in an error state and cannot be reconfigured, so each rung builds a fresh
one and sheds what a start can choke on, most-suspect first: the AImageReader the ASC
presenter renders into (READER_MAX_IMAGES full-resolution PRIVATE COMPOSER_OVERLAY
buffers, which the SurfaceView path does not allocate at all), then the aggressive
low-latency key set. Every downstream branch already keys off `asc.is_some()`, so a
fallen-back session simply runs the SurfaceView presenter that has always been the
API < 29 / ASC-init-failure fallback. Rung 0 is always exactly what the session asked
for, so a device that works pays nothing; the winning rung is logged, so the next
device that needs one names its own culprit instead of leaving us to guess.
The sync loop gets no ladder: it only runs with low-latency mode off, which is
already the conservative key set, and it renders straight into the SurfaceView — both
axes are already shed, and there is no simpler configuration to fall back to. It gets
the diagnosis in its error line instead, since the session stays up around the
failure there too.
Also lifts the HDR static-info fetch above the ladder so a retry never pays its
250 ms wait again, and extracts the async-notify callback registration, which each
rung's fresh codec now needs.
Field reports of "201" when sending logs to the host: the upload was working
the whole time, and the client was calling it an error.
`POST /api/v1/client-logs` answers **201 Created** — it is a route that STORES
a bundle, and it has said so since the feature landed (`mgmt/client_logs.rs`,
where CREATED is both the returned status and the documented one). The Android
uploader tested `resp.code == 200` and treated everything else as a failure, so
the user got "Couldn't send logs — host answered HTTP 201" while their bundle
was already sitting on the host's web console Logs page. Worse than a cosmetic
lie: it invites a retry, and the store keeps only 5 bundles per device, so a
few retries evict the reporter's own earlier logs.
The check now uses OkHttp's `isSuccessful` (200..299) rather than a
hand-written code, so there is no second list of numbers to fall out of sync
with the host.
One line covers both Android shells: since the send-logs work spread the action
to every UI, the Skia console and the touch home both route through
`SendLogs.toHost`, which is the only place the status is judged.
The other legs were already correct and are untouched: Apple matches
`case 200, 201` (`LibraryClient.swift`), and the desktop ureq path treats any
2xx as `Ok` — only 4xx/5xx become `Error::StatusCode`. A sweep of the remaining
strict-200 comparisons in the clients found only GET art/status fetches, where
200 really is the sole success.
Verified with `./gradlew :app:compileDebugKotlin` (task executed, not cached).
Every OS-level name a virtual pad needs is derived from a pad index and nothing
else: the `Global\pfxusb-boot-<i>` / `Global\pfds-boot-<i>` bootstrap mailboxes, the
`SwDeviceCreate` instance ids (`pf_xusb_<i>`, `pf_pad_<i>`, `pf_ds4_<i>`,
`pf_xbox_<i>`), and on Linux the DualSense pairing MAC, the Deck serial and the
Switch MAC — the last three documented as needing to be unique per pad, because
hid-playstation adopts the MAC as the HID `uniq` and SDL/Steam dedup by that serial.
The host serves up to DEFAULT_MAX_CONCURRENT sessions of the same desktop, each with
its own input thread and its own router, and every client numbers its first
controller wire pad 0. So two paired clients each holding a controller collide on all
of them. On Windows the second session's `Shm::create_named` sees ERROR_ALREADY_EXISTS
on all five retries and never gets a pad for the whole session — and the create-failure
hint tells the operator to restart the service, which would kill both sessions, when no
other process is involved at all. On Linux nothing errors: both mint the same DualSense
MAC and SDL merges the two pads into one controller.
The wire index is a session's own numbering and cannot be an OS identity. New
`pf_inject::pad_pool` makes the OS slot host-wide — claimed on a pad's first present
frame, released when it goes away, freed wholesale when the session drops — and `Pads`
translates once on the way in. Because only the NUMBER changes and not the name format,
the drivers (which read the index back out of `pszDeviceLocation`) need no change.
Slots are claimed lazily rather than as fixed per-session windows, so a single session
still reaches all MAX_PADS pads; two sessions share the range. An exhausted host now
declines with an honest line instead of retrying against a name it can never win.
Feedback reverses the same map: a backend tags rumble and rich HID output with the OS
slot it created the device under, so `Pads::pump` maps it back to the client's wire
index — otherwise the fix would have delivered one client's rumble to another's pad.
`HidOutput::pad`/`with_pad` keep that translation in one place, so a seventh variant
cannot silently forget it.
Verified: pf-inject 40 tests (8 new, covering the collision, single-session reach,
release, drop, exhaustion, mask and reverse-map), punktfunk-core 502 with `--features
quic`, and `cargo check -p punktfunk-host` clean on linux/amd64 in punktfunk-rust-ci —
punktfunk-host does not build on macOS, so that check is the only compile signal for
this file and it was not skipped.
PUNKTFUNK_RENDER_NODE had three independent readers disagreeing on trim
and empty-string handling (pf-gpu: no trim; pyrowave: trim+filter; the
remote worker handshake: raw .ok(), so an empty or padded value crossed
the process boundary verbatim). pf_gpu::render_node_env() is now the one
parse; linux_render_node layers the console's manual GPU preference on
top, and the PyroWave sites keep reading the env-only form deliberately —
their device-selection oracle rules forbid the preference layer.
The two sites had drifted — the class of defect virtual_stream's size
invites. Bring-up keyed gamescope_composite on the compositor alone; the
capture-loss retarget read plan.gamescope_cursor, which also folds in the
gamescope_composites_cursor() capability (a gamescope that paints the
pointer into its own node). On such a node, bring-up planned a host
composite the XFixes reader never feeds. composite_plan() is now THE
derivation for both, settle_portal_cursor's discipline applied to the
pair session_plan.rs already documents as must-agree.
Five mpsc senders and six receivers in a row, two of them both carrying
bare u32s (retarget_rx / gap_rx) — one silent transposition at the spawn
site away from a runtime puzzle. control::run now takes control::Task,
destructured at the top into the same-named locals, so the 500-line body
is byte-for-byte unchanged and the spawn site reads as named fields.
Drops one of the workspace's 127 too_many_arguments allows.
`MaxLumaPixelsHEVC` was the constant `1869449984` in every document, including
the ones whose `ServerCodecModeSupport` had just dropped HEVC — a GPU-less host
encodes H.264 and nothing else, and said so in the mask while still quoting a
4K60 HEVC ceiling two lines above it. The code's own comment flagged the
contradiction and left it, on the grounds that Moonlight gates on the mask.
That reasoning is right, which is exactly why this is worth closing rather than
keeping: the field is harmless only for as long as every client keeps ignoring
it, and nothing on our side guarantees that. It now follows the mask, with `0` —
the field's own way of saying no HEVC capacity — when HEVC is not offered.
Gate: Linux fmt + clippy + 14/14 pacing + 96/96 gamestream; Windows `.133`
clippy on the full matrix + 14/14 + 95/95.
None of these change behaviour. All four were carrying comments that read as
unfinished work, and the work turned out to be establishing what is true.
**TLS accepts any client certificate — and should.** The verifier's comment
called pinning "a hardening follow-up". It is not one. A TLS handshake completes
before the request line is parsed, so "pin the post-pair routes, accept-any on
the pairing routes" cannot be expressed there at all — it would take a second
listener on a second port, and the protocol fixes the ports. Some HTTPS traffic
must come from unpaired peers anyway: `/serverinfo` answers `PairStatus=0`
precisely so a client can discover it needs to pair, and the management API goes
further and admits certless browsers. And deferring costs nothing: the
`CertificateVerify` signature IS checked, so a peer reaching a handler has proved
possession of its certificate's private key, and `peer_is_paired` pins the
SHA-256 of that same certificate before any state-changing work. Every route but
`/serverinfo` goes through it. Rejecting with an HTTP error rather than a TLS
alert is a difference in *when*, not in what is proven. The comment now says
that, including the thing that WOULD be a hole — accepting the certificate
without checking the signature, which is why the legacy-Moonlight fallback
re-verifies rather than waving old certificates through.
**The PIN's 4-digit space is not the exposure.** 10⁴ invites the brute-force
question, and the answer is that nothing can brute-force it: submission is the
bearer-authenticated management API and nowhere else, so a network peer has no
oracle to hammer, and a per-attempt cap would bound the operator's typos rather
than an attacker. A wrong PIN costs a fresh client handshake *and* a fresh
operator submission — not a loop anyone automates from the network. The real
residual is **capture**, not guessing: the PIN slot is bound to no particular
handshake, so a peer parked at the right moment can take the PIN typed for
someone else. That is already narrowed twice (an ambiguous submit is refused, an
unconsumed PIN expires) and its full fix is to key the gate by `uniqueid` —
which also needs the management API to name *which* device is asking, so the
operator answers a named prompt. Written down so the next reader audits the race
rather than re-deriving the brute-force answer.
**Audio's unauthenticated CBC cannot be negotiated away.** The instinct is to
reach for `SS_ENC_AUDIO` (0x04) as the authenticated answer. Per the sanctioned
wire reference, `SS_ENC_AUDIO` *selects exactly the mode we already implement*:
"if SS_ENC_AUDIO: AES-128-CBC encrypt the PKCS7-padded Opus frame", noted there
as "CBC, not GCM. No auth tag appended (unlike video/control GCM)", negotiated
through `x-nv-general.featureFlags` bit 0x20 rather than the `encryptionSupported`
mask. So GameStream has no authenticated audio mode to advertise: offering the
flag would change nothing on the wire, and adding a tag would be a private
extension no client can decode. The malleability is real and it is
protocol-inherent, in the same family as pairing over plain HTTP. A session that
needs authenticated audio needs the native plane, whose audio is AES-GCM. This
moves the item from "blocked on a layout we could not find" to "answered" — the
layout was not missing, the premise was.
**`encoderCscMode` was warning about something it could not act on.** The note
claimed Moonlight renders from the requested value rather than the bitstream VUI,
so any mismatch shifts colours. The wire reference does not say that — it lists
the key among those a host parses, and nothing more — and we emit an explicit,
correct VUI that a VUI-driven renderer would follow. Worse, the common case is
unactionable by construction: this session's own on-glass run shows a stock
client sending `csc=3` (Rec709 **full**) while negotiating HDR, and HDR10 *is*
BT.2020 PQ, so the request and the mode contradict each other and the mode wins.
The old code warned on every HDR session about that. It now says so at debug, and
keeps a warning only for SDR, where the request could in principle be met —
honestly labelled unverified.
Also recorded: honouring it is not "just plumbing". `videoFullRangeFlag` is
hardcoded to 0 in every encoder backend with the capture-side CSC fixed to match,
so an SDR client asking for full range needs a per-session colour request
threaded from RTSP through the capture CSC into each backend's VUI — code the
native plane shares and currently gets right. That is a real piece of work with a
real regression surface, and it should be scoped as one rather than as a logging
follow-up.
Gate: Linux fmt + clippy + 14/14 pacing + 96/96 gamestream; Windows `.133`
clippy on the full matrix + 14/14 + 95/95.
Eleven generations of punktfunk_connect_ex* each added a field by minting a
new exported symbol plus a 20-something-parameter forwarding shim (ex11 over
ex10: two fields). punktfunk_connect_opts takes every option in ONE
size-prefixed PunktfunkConnectOpts — PunktfunkConfig's struct_size guard,
with the growth direction added: an older, shorter caller gets its tail
defaulted to unspecified/auto instead of misread. Layout is locked
padding-free on both pointer widths (96/68 B) by const asserts AND by the C
harness compiling the same sizes, so an appended field can never land in
bytes an older sizeof already covered. Every ex keeps its symbol and
behaviour; the chain is closed in the embedding guide (whose ladder table
had stalled at ex7 — the maintenance tax on display).
Also: the cargo-test C harness now actually links on an Apple Silicon dev
box (-L/opt/homebrew/lib was missing) and always builds the staticlib WITH
quic — a featureless .a left by an earlier plain build was silently reused.
QSV's copies had already diverged twice in ways the file itself confesses
(the dropped trim() that left LTR enabled on Intel, the IR period knob that
silently did nothing) — and PUNKTFUNK_LTR_FORCE_AT=0 still behaved
differently per vendor. enc/policy.rs now parses each knob once, rfi.rs's
sibling; tuned per-vendor defaults (QSV 1/4 s vs AMF 1/2 s LTR cadence) and
API-bound clamps deliberately stay with their backend.
`obu_size` is a leb128 read straight out of the stream — bounded only by `u32::MAX`,
and tied to nothing about how many bytes are actually present. `read_obu` then built
the OBU with an unchecked `&data[start_offset..start_offset + obu_size]`, so any
access unit whose last OBU declared more payload than remained panicked with
`range end index .. out of range for slice of length ..`. That is a bounds check
rather than arithmetic, so it panics in release too, and it aborts whichever thread
is decoding.
It reaches every native AV1 rung: pf-vkdecode, pf-dxvadec and pf-vaadec are all
re-exports of `pf_bitstream::av1::Av1Planner`, whose `plan_au` hands raw access-unit
bytes straight to this function. `PUNKTFUNK_AU_FAULT=truncate` produces the shape,
and so does any AU delivered short over the wire.
This was a hole in an otherwise consistent posture, not a missing idea: `plan_au`
degrades every other malformation to `TruncatedAu`/`Parse`, and pf-vkdecode already
re-validates `obu.end > au.len()` a layer up. Bound it once, where all three rungs
route through. The checked end is reused for `bytes_used`, so the slice and the
advance can no longer disagree.
Both tests fail without the guard — the parser one reproduces the original panic
verbatim (`range end index 10600 out of range for slice of length 5293`).
Recorded as PROVENANCE.md deviation 14. Not filed upstream.
The previous commit shipped `SS_ENC_CONTROL_V2` dark, on the grounds that the
wire had not yet met a real client here. It has now, twice, on `.173` (Win11,
RTX 4090) against Moonlight on macOS at 2560x1440@240 HEVC Main10 HDR.
| Leg | Result |
|---|---|
| `control` (SUPPORTED, not requested) | **the client turns it on by itself** — video and audio flow, hardware decode |
| `require` (both bits REQUESTED) | negotiated and streamed the same way; the lever is not broken |
The line that settles it is the host's own scheme detector, which reports what
it actually locked onto rather than what was negotiated:
```
control: GCM scheme locked in
scheme=Scheme { key_rev: false, nonce: V2 { seq_be: false, marker: [67, 67] },
tag_first: true, aad: None }
```
`[67, 67]` is `b"CC"` — the client→host V2 marker — after which the host sealed
its HDR-mode cue under the flipped `b"HC"` and the client acted on it. Both
directions on distinct nonces, on hardware. That is the defect from the previous
commit's note, observed closed rather than argued closed.
So `Supported` — the default — now carries both bits, exactly as WP7's video
encryption graduated after its own glass pass. What used to be the `control`
opt-in becomes `PUNKTFUNK_GS_ENCRYPT=video`, the way *out*: it keeps video
encryption and drops only the control offer. That granularity is worth its three
lines rather than being YAGNI — this plane serves a spread of client builds and
exactly one has been tested against the V2 offer, so the alternative rollback
(`=0`) would throw away video encryption to fix a control-channel problem.
**The deferral that turned out not to exist.** The worry was that control-v2
would drag encrypted RTSP in with it, forcing a `corever` threshold nobody has
the value for. Both legs kept RTSP plaintext — the client asked for
`rtsp://192.168.1.173:48010` and stayed there — which confirms the framing is
chosen by the launch URL scheme, not by the DESCRIBE flag. The sealed-RTSP
reader is in and unit-tested, but it has not been exercised on the wire; it will
be the day a client opens a connection with the type bit set, and it is written
to answer in kind when that happens.
**The other thing glass settled** is the previous commit's open question about
the ping payload's encoding. Both media planes logged `client endpoint learned
(ping payload verified)` on the first datagram, in both legs — so the payload
crosses in a form `ping_matches` accepts, the two-second fallback never fired,
and that check can be tightened from "prefer" to "require" whenever we want it.
Docs follow: `moonlight.md` no longer says the control channel "uses the older
GameStream scheme", which stopped being true for a stock client with this
commit, and `configuration.md` documents the new `video` value.
Gate: Linux fmt + clippy + 14/14 pacing + 96/96 gamestream; Windows `.133`
clippy on the full matrix + 14/14 + 95/95. One `send_pacing` failure on the
first Linux run was a timing flake under load (0.36 s vs the usual 0.06 s) and
passed 14/14 on re-run — the suite is known for it. `.173` was restored
afterwards: original binary back byte-for-byte by size and timestamp, no test
lines in `host.env`, service running, listeners up, and the build tree this
session created removed.
The legacy GameStream control scheme builds its AES-GCM nonce out of the
sender's own sequence number and nothing else. There is no direction byte, so
the host's messages — rumble, the HDR-mode cue — and the client's input share a
single (key, nonce) space and collide the moment their two independent counters
cross. That is the one catastrophic GCM failure, and `control.rs` has carried a
note saying so, ending "the real fix is V2 control-encryption negotiation".
This is that fix, and most of it turned out to be already written. The scheme
detector has understood `NonceKind::V2` — `seq` in `[0..4]`, `b"CC"` at
`[10..12]` — since it was built, and `encrypt_control` already flips the marker
to `b"HC"` for host-originated messages. What was missing was the one thing that
makes a client choose that scheme: the advertisement. So the control plane needs
no code change at all here; it needs `SS_ENC_CONTROL_V2` in
`encryptionSupported`, and it detects the rest from the first packet that
authenticates.
Enabling V2 also lets the client seal RTSP itself, which is the part that was
deferred, and the reason it was deferred dissolves on inspection. The worry was
needing to know `corever` — the field that decides whether a session speaks
sealed RTSP — whose threshold the sanctioned reference names but does not value,
and guessing it would break every session it guessed wrong about. But the two
framings are **self-distinguishing**: a sealed message opens with
`typeAndLength`, whose MSB is `ENCRYPTED_MESSAGE_TYPE_BIT`, and a plaintext one
opens with an ASCII method name, always below 0x80. So there is nothing to
negotiate and no threshold to guess — the connection is read in whichever
framing it arrived in and answered in the same one, the same "detect it from the
wire" posture the control stream already takes. `corever` never has to be
consulted, which also means it never has to be guessed.
Two details worth their own lines:
**The host's RTSP sequence counter is process-global and never resets.**
GameStream RTSP is one message per TCP connection, so a per-connection counter
would restart at zero for every one of a session's seven messages and reuse
(key, nonce) six times over — reintroducing, in the fix, exactly the defect
being fixed. Same rule WP7 established for the video counter, and same reasoning.
**The frame's length field is bounded before it is believed.** It is
attacker-controlled and arrives before a single byte has authenticated, so it is
checked against the same budget the plaintext path uses rather than trusted
enough to reserve against.
Shipped dark, deliberately: `PUNKTFUNK_GS_ENCRYPT=control` opts in, the default
advertisement is unchanged, and `require` (the on-glass lever) now covers both
bits. This is the posture WP7 shipped video encryption in — dark until glass
confirmed a real client negotiated it — and control-v2 has not yet met a real
client here. Flipping the default is a one-line change once it has.
The two comments claiming we "advertise no encryption" are corrected while I am
here; they have been wrong since WP7 advertised `SS_ENC_VIDEO`, right in their
conclusion and wrong in their reason.
Gate: Linux container fmt + clippy `--all-targets -D warnings` + 14/14 pacing +
96/96 gamestream (93 before); Windows `.133` clippy on the full
`nvenc,amf-qsv,qsv` matrix + 14/14 + 95/95 (92 before). The three new tests cover
the receive path as well as the send path, and were confirmed non-vacuous by
mutating the nonce's direction byte to a constant — both directional assertions
fail, which is the security property doing its job.
Both media planes learned where to send by taking the first UDP datagram that
arrived from the launch owner's address and never looking inside it. The ping
payload the protocol exists to carry — handed to the client in the SETUP
response, echoed back as its first datagram — was the fixed constant
`0011223344556677` for every session on every host, and nothing ever compared
it against what arrived. Source-IP binding was the whole guard, so anything
that could send from (or spoof) that address won the endpoint simply by being
first, and was handed the stream.
So the payload becomes a per-session secret: eight random bytes minted at
`/launch`, re-minted at `/resume`, advertised hex-encoded in SETUP, and checked
before an endpoint is adopted. Both planes now go through one
`learn_client_endpoint`, because they had drifted into two byte-identical loops
and a rule about who owns a stream should exist once.
Minting alone would have proved nothing, though, and this is the part worth
pausing on: SETUP was **unauthenticated** while its siblings ANNOUNCE and PLAY
were not. Any peer that could reach 48010 could simply ask for the payload the
media planes were about to verify, and walk the check. So SETUP is gated on
`authorized_launch` like the other two — a secret handed to whoever asks is not
a secret, and that hole, not the constant, was the reason the old check would
have been theatre.
The check **prefers** a matching datagram rather than **requiring** one, and
that is deliberate rather than timid. The sanctioned wire reference says the
client echoes the payload and that modern clients wrap it in an `SS_PING`
carrying a sequence number, but it gives neither that structure's layout nor
whether the payload crosses as the header's ASCII or as its decoded bytes.
`ping_matches` accepts every shape those unknowns allow — either encoding, with
trailing bytes — yet a hard gate resting on a layout nobody has confirmed would
black-screen every session it guessed wrong about, and compatibility is this
plane's entire reason to exist. An unverified datagram is therefore held as a
fallback, adopted only if two seconds pass with nothing better, and logged with
the bytes that did arrive. One real session settles the encoding; then the
fallback can go and this becomes the hard gate it wants to be.
What this closes: an off-path attacker who cannot read the plaintext RTSP
exchange can no longer guess its way onto a media port. What it does not close:
an on-path observer, who can still read the payload out of SETUP — that one
needs `SS_ENC_CONTROL_V2`, and the two changes are worth more together than
either is alone.
Constant-time comparison throughout (`crypto::ct_eq`), so the expected value
can't be probed a byte at a time.
Gate: Linux container fmt + clippy `--all-targets -D warnings` + 14/14 pacing +
93/93 gamestream (90 before). The three new tests were confirmed non-vacuous by
mutating `ping_matches` to return `true` and watching the negative case fail.
Review of 47d9a7d2 plus the on-glass pass it was waiting for, run 2026-08-27 against
.173 (Win11, RTX 4090) from Moonlight on macOS. Four legs, all pass:
1. encryption off -> streams, encrypt_video: false (no regression)
2. =1 (supported) -> the CLIENT OPTS IN BY ITSELF, decodes, 0 errors
3. =require -> negotiated, decoded in hardware, 0 errors
4. =require + 5% loss -> 27 s, 8 keyframes decoded, ZERO IDR re-requests
Leg 2 is why the default moves: I had argued a client might only enable video
encryption on WAN/relay links — which is why the `require` lever exists at all — and
it opted in on a LAN unprompted. Default-on therefore delivers encryption in
practice rather than being a no-op offer.
Leg 4 is the one that mattered most: at 5 % injected wire loss the client never asked
for a single keyframe, so FEC recovered every dropped SEALED shard. That is the
FEC-then-encrypt ordering proven on hardware, not just in the unit test.
Two independent confirmations of the wire format fell out of the run:
* the client negotiated packet_size 1360 where the plaintext leg used 1392 — it
subtracted sizeof(ENC_VIDEO_HEADER) exactly as the reference says, so the on-wire
datagram is 1408 either way and still fits the MTU it sized for;
* FFmpeg parsed nal_unit_type 19 (IDR_W_RADL) and reported 'Decoded frame with POC
0/0' on a Main 10 VideoToolbox path — a real decoder reading real HEVC out of the
decrypted, FEC-reassembled payload.
Default is now Supported; PUNKTFUNK_GS_ENCRYPT=0 is the escape hatch back to the
plaintext wire, `require` stays as the test lever that forces the negotiation.
Review fixes in the same change (found reading 47d9a7d2 back, before the test):
- A failed seal pushed the CLEARED buffer, putting a 0-byte datagram on the wire.
Unreachable in practice (GCM only refuses absurd lengths) but the wrong failure
mode: the shard is now dropped, which is what FEC is there for. seal_shard returns
bool and — per clippy, correctly — takes &mut [u8] now that it never clears.
- `off` and `key` derive separately from self.enc_key; they cannot desync today, but
if they ever did, sealing would encrypt from offset 32 INTO the shard body and
corrupt every packet with no error anywhere. A debug_assert states the invariant.
- Stale rtsp module header (it still said plaintext-only, P1.5).
Docs follow the behaviour: moonlight.md/clients.md now say video is encrypted, and
the 'legacy control encryption is weaker' caveat is corrected — it was overstating
things now that video and audio are both sealed; what remains true is that pairing is
plain HTTP and the control channel uses the older GameStream scheme.
Gates: Linux container fmt + clippy --all-targets -D warnings (non-vacuous) +
send_pacing 14/14 + gamestream 90/90; Windows .133 clippy nvenc,amf-qsv,qsv clean +
14/14 + 89/89; check-docs-drift.sh + check-docs-links.sh clean. .173 restored to its
original binary and host.env, build tree removed.
GS competitive program WP7 — the largest remaining wire divergence from a Sunshine-class
host, and the last item the docs' "weaker than the native protocol" caveat rested on.
- RTSP DESCRIBE advertises SS_ENC_VIDEO (0x02) as encryptionSupported and NEVER as
encryptionRequested: requiring encryption would refuse every client that doesn't do
it. ANNOUNCE's x-ss-general.encryptionEnabled echo decides the session, and is
honored only for a bit the host actually offered.
- Each finished datagram is AES-128-GCM-sealed under the /launch rikey and shipped as
[iv 12][frameNumber u32 LE][tag 16] || ciphertext(blocksize) — the ENC_VIDEO_HEADER
layout, whose 32 bytes sit OUTSIDE the FEC blocksize (the client already subtracted
them from the packetSize it negotiated, so the datagram still fits its MTU).
- The order is FEC first, THEN encrypt per shard. That is the load-bearing property,
and it has its own test: the client decrypts what it received and runs RS recovery
over those plaintexts, so parity computed over ciphertext would recover nothing.
Sealing is in-place into a buffer that reserved the prefix, so the pooled
no-allocation path (WP1.3) survives; parity, which encode_into sizes exactly, costs
one memcpy on the ~20 % of packets that are parity.
- The GCM nonce counter is PROCESS-global and monotonic, never reset. (key, nonce)
reuse is the one catastrophic GCM failure, and a session-scoped counter would repeat
the moment a KEYLESS /resume — which WP3 defines as keeping the current keys —
started a fresh packetizer on the same rikey.
DEFAULT OFF, opt in with PUNKTFUNK_GS_ENCRYPT=1. This is the compat plane's video hot
path and a wire mistake there is a black screen for any client that opts in; I cannot
run a stock Moonlight client in this environment, so it ships dark and the WP0.3
on-glass pass flips the default. SS_ENC_CONTROL_V2 and SS_ENC_AUDIO stay unoffered:
control-v2 also re-frames RTSP itself, and the audio-GCM layout is not in the
sanctioned wire reference.
Also WP8's docs pass, now that the claims are false in the user's favour:
moonlight.md said the GameStream path "doesn't use the native protocol's
FEC/encryption extensions" — Moonlight-compatible FEC has shipped for months and the
host now adapts it to reported loss. Rewrote that (and the clients.md twin) to say
what Moonlight actually does and doesn't get, documented the bitrate as the wire
budget it became in WP2.1, and documented the three new knobs (PUNKTFUNK_FRAME_DRIVEN,
PUNKTFUNK_GS_ADAPT, PUNKTFUNK_GS_ENCRYPT) — check-docs-drift.sh gates that.
⚠ The drift gate also demanded PUNKTFUNK_IDD_ADAPTIVE be pruned from the undocumented
baseline: it is documented in configuration.md but was never pruned, so that ratchet is
red on main independently of this branch. Pruned here since the gate refuses to pass
otherwise.
Gates: Linux container fmt + clippy --all-targets -D warnings (non-vacuous) +
send_pacing 14/14 + gamestream 89/89 (new: encrypted round-trip incl. tamper + wrong
key + IV uniqueness, and RS recovery THROUGH encryption); Windows .133 clippy
nvenc,amf-qsv,qsv clean + 14/14 + 88/88; check-docs-drift.sh and check-docs-links.sh
both clean.
GS competitive program WP5 (the media items implementable without new wire research —
4:4:4 and encoderCscMode stay follow-ups: the 4:4:4 SCM extension bit values are not in
the sanctioned wire reference, and CscMode honor is an encoder-wide colorspace plumb).
- WP5.1 the capture format comes from the shared SessionPlan (gs_session_plan: 4:2:0,
depth 10 only with HDR, no cursor-forward — this plane has no client cursor channel)
instead of the hand-hardcoded OutputFormat::resolve(hdr, gpu). One resolver for both
planes, and the visible win: a gamescope GameStream session (cursor blend off there)
now resolves nv12_native, so the producer's NV12 feeds Vulkan Video directly and the
per-frame RGB→NV12 CSC the native plane already skips is skipped here too. Also the
structural prerequisite for 4:4:4 when its advertisement bits are researched.
- WP5.4 the encoder gets the source's REAL HDR grade every frame (set_hdr_meta from the
capturer, exactly the native loop's shape): an HDR backend embeds it as in-band
mastering/CLL SEI on keyframes — the channel a stock Moonlight decoder tone-maps
from. This plane never called it, so an HDR GameStream session shipped no grade at
all; the 0x010e control cue only flips the display mode and carries generic fallback
metadata.
- WP5.5 RS(4,2) audio FEC on every layout — stereo included. The parity math is
layout-agnostic (shards are opaque encrypted packets) and a stock client runs the
same fixed RS(4,2) recovery regardless of channel count; the old channels>2 gate was
bring-up caution that left the MOST COMMON configuration with zero audio loss
protection.
Gates: Linux container fmt + clippy --all-targets -D warnings + send_pacing 14/14 +
gamestream 87/87; Windows .133 clippy nvenc,amf-qsv,qsv clean + 14/14 + 86/86.
On-glass owed with the WP0.3 pass: gamescope NV12 path on .41, HDR SEI in a client
bitstream dump, stereo FEC under netem loss.
GS competitive program WP6.1. serverinfo's <mac> was a fake constant
(01:02:03:04:05:06) over HTTPS — and Moonlight PERSISTS that field as the target for
its Wake-on-LAN, so every client-side wake against this host was a silent no-op. It
now carries the real routed-NIC MAC via the same crate::wol::wake_macs the native
plane's mDNS advert uses (routed NIC first, lowercase colon-hex — the wire reference's
documented shape: real MAC on HTTPS, zeros on plain HTTP).
Cached on first SUCCESS only: /serverinfo is polled, so per-poll NIC enumeration is
waste — but a cold-booted host may not have a routable address yet (the #366 boot-race
lesson), so a failed read retries on the next poll instead of latching zeros forever.
Plain HTTP keeps hiding the MAC.
Gates: Linux container fmt + clippy -D warnings + send_pacing 14/14 + gamestream
87/87 (new pin: never the fake MAC, hidden over HTTP); Windows .133 clippy
nvenc,amf-qsv,qsv clean + 14/14 + 86/86.
GS competitive program WP3 (design/gamestream-competitive-program.md). Three fixes
that together make Moonlight's Resume/Quit UX exist against this host for the first
time — serverinfo hard-coded state=FREE/currentgame=0, so no stock client ever showed
Resume or Quit, and /resume read no query params at all, so even a reached resume ran
on stale crypto keys.
- serverinfo now reports the live session's appid + SUNSHINE_SERVER_BUSY — to the
session OWNER's pinned cert ONLY. Owner-scoped on purpose (owner_current_game, pure
+ tested): a non-owner shown the truth would route same-app taps into the owner-only
/resume and /cancel and lose the reject/join/steal admission it gets via /launch
today; and a busy signal over plain HTTP would leak what's running to the LAN.
Advertisement fails CLOSED on unknown fingerprints (unlike the control gate, which
deliberately fails open).
- /resume parses rikey/rikeyid and RE-KEYS the live session (a resuming Moonlight
mints fresh keys; the control GCM and audio CBC derive from them — the old keys made
every post-resume control packet undecryptable). Malformed rikey refuses the resume;
keyless keeps the current keys. The media/RTSP source-IP binds re-anchor to the
address the client resumes from, so a device that moved networks can come back.
- /resume RESTARTS the media planes for the new connection. A PLAY that found
'streaming' still true took its already-running branch: the old threads kept
streaming at the vanished endpoint and the resumed client got no media. The handler
clears the run flags and WAITS (bounded, 2 s) for the old threads' FULL exit — each
media thread now bumps AppState::media_exited as its last act, after its teardown
(capturer re-pool, lease guard, events) has run — so the successor threads never
race the predecessor over the pooled capturer and the old exit path cannot stomp
the new session's flags. The launch surviving that wait is re-keyed; one cleared by
the old threads' client-unreachable teardown falls back to a clean /launch. The
ENet control plane already handles the fast-reconnect half (a new Connect replaces
the tracked peer; the old peer's late timeout is gated off it).
Gates: Linux container fmt + clippy --all-targets -D warnings (non-vacuous) +
send_pacing 14/14 + gamestream 86/86 (new: owner-scoped currentgame matrix, resume
re-key round-trip incl. malformed/keyless arms, busy-state XML pin); Windows .133
clippy nvenc,amf-qsv,qsv clean + 14/14 + 85/85. On-glass resume with a stock
Moonlight client owed (WP0.3 pass).
GS competitive program WP2.2-2.4 (design/gamestream-competitive-program.md). The
Moonlight plane's only in-stream quality signal — the periodic 0x0201 loss-stats
report — used to fall through the control decoder and be silently dropped; the host
was blind to client-observed loss and its only recovery was serving IDR round-trips.
No Sunshine-class host does more than log this signal. Now:
- WP2.2 the control stream decodes 0x0201 (LE i32s: loss count, window ms,
last-good frame — the verified IDX_LOSS_STATS reading, apollo-comparison #94) into
cumulative per-session counters on AppState (GsLossStats), read as window deltas.
- WP2.3 adaptive FEC: the parity percent climbs fast under loss (+max(5, pct/2) per
lossy window, cap 50) and decays slowly on clean windows (-5 per 8, floored at the
configured base). Applied live through the packetizer between frames — safe because
block geometry is derived per frame and the client reads each block's parity count
from the per-packet fecInfo wire percent.
- WP2.4 bitrate de-rating: SUSTAINED loss (2+ consecutive lossy windows) de-rates the
wire budget x0.85 per window, floored at max(1/4 of the negotiated rate, 5 Mbps);
clean windows climb it back at 1/20 of the negotiated rate per 4 — division of
labour as on the native plane: parity answers random/burst loss, fewer bits answer
congestion. The client's negotiated number stays the hard ceiling.
- The WP2.1 invariant is kept live: every step re-derives the ENCODER rate under
(budget, percent) and retargets it in place (Encoder::reconfigure_bitrate); the send
pacer's rate follows through an atomic. An encoder that refuses the in-place
retarget (software paths) turns adaptation OFF for the session — raising parity
over a frozen encoder rate would push the wire back over budget. The stats sample
reports the LIVE budget, so the console shows what the host actually targets.
PUNKTFUNK_GS_ADAPT=0 pins both levers at their configured values (the A/B lever).
Constants are deliberately conservative first values — the WP0.3 netem matrix tunes
them. Also: the stale module/status doc headers the completeness inventory flagged.
Gates: Linux container fmt + clippy --all-targets -D warnings (non-vacuous) +
send_pacing 14/14 + gamestream 83/83 (incl. the two new adaptation state-machine
tests); Windows .133 clippy with nvenc,amf-qsv,qsv clean + send_pacing 14/14 +
gamestream 82/82 (amf-qsv,qsv — the box has no NVENC import lib for test linking).
On-glass netem verification (WP0.3) owed.
GS competitive program WP0/WP1/WP2.1 (design/gamestream-competitive-program.md in the
planning repo). Four latency/overshoot gaps between the Moonlight-compat plane and the
native plane, all closed by wiring GS into machinery the native plane already had:
- WP1.1 arrival-driven capture: the GS encode loop slept out its whole tick and then
SAMPLED, holding a frame that arrived just after the previous sample for up to a full
interval (~half on average, ~8 ms at 60 fps). It now sleeps to a 0.9-interval floor and
wakes on the capture's actual arrival, exactly the native T1.1 shape — with the same
credit bucket pinning the long-run average at the negotiated rate, so a mirrored panel
running faster than the session cannot overdrive the wire. The bucket
(CaptureCredit, ex the native loop's private PaceBudget) and the PUNKTFUNK_FRAME_DRIVEN
gate move to send_pacing, shared by both planes.
- WP1.2 microburst pacing: the GS sender passed burst_bytes: None into the shared pacer,
so EVERY frame — a 3-packet P-frame included — spread across 0.75 of the frame interval
(an ~11 ms tail at 60 fps), and small frames still slept out the full budget. It now
runs the native parameterization: an auto-sized burst leaves immediately (a normal
frame goes out whole, unpaced) and only an oversized frame's overflow spreads, across
the time it needs at ~3x the stream rate, bounded to ~2 intervals. The chunking stays
BOUNDED (<=12 steps) — on that non-RT thread the per-step sleep overshoot must stay
independent of bitrate.
- WP1.3 pooled packetization: the packetizer copied the whole AU into a staging Vec and
allocated one Vec per shard (~3300 for a 4 MB IDR) plus unpooled parity, every frame.
Datagram buffers now cycle sender -> packetizer -> wire through a recycle channel,
parity goes through the pooled encode_into, and each payload byte is copied exactly
once, straight from the encoder's buffer into its datagram. A poisoned-pool equivalence
test pins the pooled path byte-identical to a fresh packetizer.
- WP1.5 wake-on-packet control: the ENet service loop was a 2 ms spin-sleep, so every
client input/IDR-request datagram waited out the rest of the tick. The control socket
now blocks with a 2 ms read timeout (same idle cadence and CPU); an arriving datagram
wakes it immediately. rusty_enet's receive loop returns on the first produced event
(verified in its transpiled enet_protocol_receive_incoming_commands), so the block only
ever sits where the sleep used to.
- WP2.1 budget honesty: the encoder was handed the full negotiated bitrate and then 20%
FEC parity plus per-shard framing went ON TOP — every session carried ~1.23x what the
client configured, and on the constrained links where the setting matters the overshoot
was the failure. The encoder rate is now derived UNDER the client's number
(gs_encoder_bps, the compat twin of the native encoder_kbps_for_budget from ABR
overhaul Phase 4), so the wire fits the budget the Moonlight user actually set.
- WP0 measurement: the wire's frame_processing_latency field (1/10 ms, the Sunshine
extension Moonlight's overlay shows as 'Host processing latency') is now stamped per
frame instead of hardcoded 0; the 1 Hz stats sample grows a send_spread stage measured
on the sender thread; and the video tests gain a GS-wire loopback harness — a
client-shaped reassembler running Cauchy RS recovery over lossy datagram subsets —
locking layout + recovery against every later packetizer change.
Also: the mirror source's capture-format 'gpu' predicate now matches the virtual source's
(resolved_backend_is_gpu, not the zerocopy env knob).
Gates: Linux container (punktfunk-rust-ci) fmt --all --check clean, clippy --all-targets
-D warnings clean and non-vacuous, send_pacing 14/14, gamestream 81/81 (incl. the new
harness + equivalence + schedule pins). Windows .133 clippy/tests with nvenc,amf-qsv,qsv
run in parallel with this commit; macOS spot-check shows only the known cfg(linux) stub
errors. On-glass A/B (WP0.3 baseline matrix) still owed.
window_loss_ppm's frames_dropped bump fired even when lost == 0 && late > 0:
every presumed-lost shard eventually ARRIVED, the frames died of lateness —
a delivery hole (host compose stall's resume edge, client-radio pause), which
neither lever this number drives can touch: FEC repairs loss, not delay, and
a bitrate backoff cannot shorten a hole. In the 2026-08-27 field log that was
loss_ppm=50000 exactly, x0.7 three times to 6.86 Mbps in 4 s, on a wire with
zero measured loss — the false ratchet is why a 160 ms hole reads as a
quality crater on our stream while the same pause is a cursor hiccup on the
competition.
The bump survives everywhere it is right: silent total loss (shards that
never arrived count in neither recovered nor late) reads late == 0 and still
bumps, and any window with real net loss bumps as before. Client-side mint,
so old clients keep the old behavior until updated.
The 2026-08-27 NVIDIA-laptop field case (36 stalls/27 s, blamed on the dark
laptop panel) reattributes to damage starvation: the desktop's only damage
source is the DWM-composited cursor, the cursor moves only while the client's
input arrives, and DwmFlush stayed 8-33 ms through every hole — DWM was
composing all along and correctly presenting nothing, because nothing was
dirty. The detector could not see that, so it fitted a 1.87 s 'display
metronome' to the reporter's input cadence and the WARN put the panel on
trial (connected_inactive lists it on every laptop under the exclusive
isolate — a standing correlation trap).
- try_consume samples GetCursorPos (rate-limited, user32 only) and
accumulates motion per gap; the stall-ending frame's own move is held back
one call so it never counts into the gap it ended. Some(0) = nothing was
dirty anywhere; Some(n>0) through a present-free hole = damage existed and
the display stack composed none of it — the positive conviction
CONTENT-SILENCE could never make.
- window_report attributes the pre-hole flow: flow_dwm_only = every lookback
present came from dwm.exe — a game's holes are never demoted.
- classify: ComposeSilence + working witness + flow_dwm_only + cursor still
=> new class DAMAGE-IDLE. Excluded from the metronome (fed post-
classification via StallWatch::cycle now), both repeated-stall WARNs, and
the connected_inactive blame; per-stall lines carry
cursor_moved_px_during_gap + flow_dwm_only either way.
- The below-OS METRONOMIC warn stops prescribing panel A/Bs for holes the
witness can already explain, and says every pre-0.28 field metronome ran
with the REALTIME lever default-on.
Logic verified by extracting stall.rs verbatim (+ the etw pure slice) into a
native scratch crate: 16/16 tests green, incl. the new damage_idle_split and
damage-idle-does-not-feed-the-metronome cases. Windows-only glue (GetCursorPos
sampler, field inits) is compile-gated on the Windows legs.
Five field requests from one returning user, traced and fixed together
(report: the "Daily-Driver Five" triage).
**10-bit SDR, independent of HDR.** VIDEO_CAP_10BIT and VIDEO_CAP_HDR were
always separate wire bits, but everything above the wire welded them: the
client advertised both from one "HDR" switch, the handshake required an HDR
capture source for any 10-bit depth, SessionPlan derived hdr from bit_depth,
and the encoder stamped BT.2020 PQ on every 10-bit format. Now a client
setting ("10-bit SDR", default off, tier-P) advertises the depth bit alone;
the handshake resolves bit_depth=10 without the HDR gates where the SDR-10
chain exists (Windows IDD-push + direct NVENC + HEVC — everywhere else the
session stays 8-bit, said honestly in the Welcome); the Welcome's colour
label, the virtual display's HDR bring-up and the capturer's want-HDR flag
all follow the new session-hdr verdict instead of the depth. The capture
side grows PixelFormat::Rgb10a2Sdr — the BGRA slot expanded 8→10 by a
trivial full-res pass (HdrRgb10Converter::new_sdr_expand) — which NVENC
ingests as ABGR10 and encodes Main10 under the ordinary BT.709 SDR VUI,
both 4:2:0 and 4:4:4. The win is the ENCODER's precision (compression
stops adding banding to gradients); the desktop stays 8-bit and neither
display's colour state is touched. The client already decodes by the VUI,
so no decode-side change was needed.
**"Capture system shortcuts" now works in Desktop mouse mode.** The setting
was wired end to end and then discarded by one `!desktop` term in the
presenter's grab condition — documented as "a remote desktop is something
you Alt-Tab away from", which made the toggle inert for exactly the
remote-desktop use it matters most for. The keyboard grab now follows the
setting in BOTH mouse models; desktop mode keeps an escape capture mode
never had (the unlocked pointer clicks any other window, focus drops, the
chords come back). Docs updated; the Mac's ⌘-chord behaviour is unchanged.
**Keep host audio playing (Moonlight's "Mute host PC speakers", unchecked,
per session).** New client setting + CLIENT_CAP_KEEP_HOST_AUDIO (0x20,
request-only, no HOST_CAP echo — an older host just re-routes as always).
A session holding the bit gets the host's audio devices left alone for its
lifetime (RAII guard): Windows skips the IPolicyConfig default parking and
loopbacks the operator's own default device; Linux taps the default sink's
monitor instead of claiming the default. Host-global best-effort across
concurrent sessions, as the cap documents. Rows in the GTK, Windows and
console-UI settings (desktop-only until Android advertises the bit).
**Prep commands carry the negotiated mode.** A per-app do/undo step's whole
environment was PF_APP_ID; the width/height/refresh/HDR it needs for a
per-mode frame cap were resolved 80 lines above and written only to the
unix-only marker file. Both serving planes now pass PF_STREAM_WIDTH /
_HEIGHT / _REFRESH / _HDR (the marker file's vocabulary, via one shared
hooks::prep_mode_env) — so an RTSS cap is one step instead of one
hard-coded entry per device, on Windows hosts too.
**The forwarded cursor matches the client's DPI.** The desktop-mode pointer
was resampled by the video fit factor alone, and SDL shows a custom cursor
surface at ~1:1 physical pixels on every backend — so on a 200% client our
pointer was half the size of every native one (and X11 the same; Wayland
escapes via buffer scale). The resample factor now folds in
SDL_GetWindowDisplayScale, the same model the Apple client gets for free
from point-sized NSCursors.
Verified: workspace clippy --locked -D warnings + targeted tests (hooks,
profiles, caps, console-ui rows, capture-policy) green on Linux
(pf-gtkflow); pf-capture/pf-frame windows-msvc green via xcheck; rustfmt
clean. NOT verified: the Windows-only halves of pf-encode/punktfunk-host
(no reachable Windows toolchain — .133 down; windows-host.yml is
dispatch-only, see the preceding commit), and everything on-glass: the
SDR-10 stream end to end, the desktop-mode grab, keep-host-audio wiring,
prep env on a live launch, and the cursor size at 200%.
bbc01cdd (ABR overhaul Phase 4, merged today as #408) threaded the new EncDerive
through prepare_display, but the call site in native/handshake.rs passes enc_of
BEFORE bit_depth while the signature takes bit_depth first — a type error in a
cfg(target_os = "windows") block. Nothing caught it: the ci.yml clippy job runs
on Linux and never compiles this block, and windows-host.yml only runs on
dispatch/release, so main's Windows host is currently unbuildable and no check
is red.
Reorder the arguments to match the signature. (--no-verify: this commit is cut
as a minimal cherry-pickable hotfix from a branch whose full fmt-clean state
lands in the following commits.)
`punktfunk-session` keeps the CONSOLE subsystem on purpose — its stdout is the
shell/session contract. Both couch entry points are GUI processes with no console
to lend it, so a spawn without CREATE_NO_WINDOW makes Windows mint one: a black
terminal that then sits behind the couch UI for the whole session. The shell's
own stream spawns (spawn.rs) have carried the flag since the port; the two
`--browse` hand-offs never did — the "Punktfunk Console" MSIX tile and
`punktfunk-client --console` (Steam shortcut, HTPC startup item) hit it every launch.
The two hand-offs were copy-paste twins, which is how they drifted apart on one
flag, so they become one file (couch.rs) that both roots include — the standalone
`punktfunk-console.exe` bin by `#[path]`, the shell as a module. `session_binary()`
folds in there too, so there is one resolver rather than two.
Second, quieter bug in the same spawn: stdout was inherited. With a console that
was merely invisible output; with CREATE_NO_WINDOW the inherited handle is invalid,
and `match_window` reports the settled window size on stdout REGARDLESS of
`--json-status` — a `println!` onto a dead handle panics the child mid-stream. So
stdout is an explicit `Stdio::null()`, not an inheritance.
Verified: couch.rs type-checks and clippies clean against x86_64-pc-windows-msvc in
an isolated harness (the crate itself cannot be cross-checked from macOS — SDL3 and
aws-lc-rs do not cross-build). On-glass verification on Windows is owed.
The ring layer moves out of the session binary into pf_client_core::logring
(desktop-gated beside the ring it feeds) — it started as punktfunk-session's
private module, and the moment both desktop shells wanted the row, a copy per
bin was exactly the drift the crate exists to prevent. The session keeps the
same layer under its new name; tracing-log and log fall out of its manifest.
Both shells install it beside their visible layer with its own DEBUG filter —
the env filter keeps scoping only what's printed, because the ring exists for
the diagnostics nobody enabled before the bug happened.
The row itself lands on each shell's saved-host menu on the console's own gate
(paired + online), wired to logring::send_to_host on a worker thread, outcome
as a toast (GTK) / the status line (WinUI), in the console's wording verbatim.
And the bundle is worth sending: orchestrate now pipes the session child's
stderr through logring::forward_child_stderr — every line still lands on our
stderr exactly as inherit interleaved it, and lands in the ring too. Without
that, the one surface a GUI-only user can export held everything EXCEPT the
stream it was exported about — the same hole the WinUI logfile module was
built to close for the file; its child forwarder now feeds the ring on the
same pass.
Reported from the field: the guided installer (scripts/install.sh) left a Fedora box with a host
and no web console — and then printed the console's URL anyway. Reproduced with the real script
against a faked Fedora 44 os-release: with `punktfunk-host` on PATH the installer prints "already
installed — skipping the install" and never runs its dnf line, so `punktfunk-web` is never added.
The console is where you pair, approve a device and change every setting, so that box can stream
nothing and offers no way to fix it.
The registry was never the problem: `punktfunk-web` is present in the fedora-44 and bazzite RPM
groups, the debian repo and the arch repo (checked all four). The install step was gated on ONE
binary while installing THREE packages.
* scripts/install.sh asks per package (host / punktfunk-web-server / punktfunk-scripting) instead
of skipping everything the moment the host binary exists. A box that got the host by hand, from
an older docs line, or from a package manager set to drop weak deps now gets its console on a
re-run. Installing a package that is already there is a no-op, so re-running stays safe.
* The install lines NAME the console on every family. apt relied on `Recommends: punktfunk-web`
and pacman on an optdepend, both of which vanish under `APT::Install-Recommends "0"` /
`install_weak_deps=False` / plain pacman. dnf already named it. The packages keep their weak
deps — a hard Requires would break the COPR build, which has no bun and ships no console — but
no documented path leans on them any more.
* The installer stops lying when the console is absent: step 6 warns instead of silently dropping
punktfunk-web from the units it enables, and the closing banner offers the install line rather
than a URL nothing serves.
Verified unchanged on the channels that were already right: the Bazzite sysext bakes in web +
scripting, the NixOS module defaults `web.enable` to `host.enable`, the SteamOS script defaults
`WITH_WEB=1`, and the Windows installer bundles the console unconditionally behind a payload guard
added after 0.22.1/0.22.2 shipped without one. COPR is the documented exception (no bun in mock).
The gates that let this ship:
* check-docs-drift.sh gate 7 asserted the install line only as far as the host package name, so
a line that dropped the console still passed. It now names all three per family.
* installer-smoke.yml asserted `punktfunk-host --version` and nothing about the console. It now
asserts the binary and the user unit per family, and carries the reported failure as a test:
remove punktfunk-web, re-run the installer, require it back.
data/platforms.json is the source for both the docs and the installer, so the per-distro pages,
the install landing page and the web-console page were updated with it — including a "no console on
a box that has the host?" recovery block for anyone already in this state.
Two halves of the same field report: a 0.31.4 user whose gamepad UI never
activates — on Always, with a pad attached — and who then has no way to send
anyone the log that would say why.
"Send logs to host" existed only in the Skia console's host menu. That put the
log-escape hatch behind the very shell that was failing: a phone whose console
does not come up has no route to its own logs at all. The upload moves out of
SkiaConsole into `SendLogs`, one implementation both shells call, and the touch
home's card menu grows the row on the console's own gate (paired + online, host
card only). The wording stays the desktop console's verbatim, so a quoted
message means the same thing on every client.
The activation half is a gap in what the app admits. `App` folds
`SkiaConsole.wanted() && healthy` into the gamepad-UI decision on top of the
user's setting, and those two terms are the ONLY ones that can veto "Always" —
the mode, the pad, the TV check and the dev flag are ORed, so a device whose
console never builds ignores every one of them. Until now that produced a switch
the app silently disobeyed, indistinguishable from the switch being broken.
`SkiaConsole.unavailable()` names the reason and the Interface settings group
prints it as its footer: null on every device where the console works, so it
costs nothing there.
The reason string itself was already in the ring the new row uploads —
`console: render thread ended: …` and `console: window surface: …` go through
`log::error!`, which `RingTee` tees into `pf_client_core::logring`. So the two
halves close the loop: the user stuck in the touch UI can now send the log that
names why they are stuck in it.
Verified: 98 app unit tests green, `:app:assembleDebug` clean, native builds for
all three ABIs.
'20 Mbps' used to mean 22-30+ Mbps on the wire: FEC parity (1-50 %),
packet framing (~4.5 %) and the audio plane all rode on top of the
number the user set — and on the constrained links where the setting
matters most, that overshoot WAS the failure. Per the signed-off RFC
§5.1 (amended 2026-08-27: no capability handshake — the semantics just
change; new-client→old-host is byte-for-byte today's behavior, and
old-client→new-host shifts conservative by the overhead share):
Host: every number on the control plane — Hello resolve, SetBitrate,
acks, live_bitrate, the console — is the TOTAL WIRE BUDGET. Encoder
opens/reconfigures convert through EncDerive (budget − audio, over
framing + FEC) snapshotted at the live FEC percent, and read-backs
convert back so a short apply reports budget truth. A FEC step
re-derives the encoder rate in place, so parity reallocates WITHIN the
budget instead of inflating the wire. The audio reservation comes from
the resolved plane (exact PCM cost, or the shared Opus budget ladder).
PyroWave is the identity (its pin is an encoder operating point);
GameStream keeps its historical semantics untouched.
Client: the controller's actual becomes the WIRE measure — received
bytes with headers, seals and parity (they spend the budget), minus
probe filler, plus the mirrored audio reservation — so utilization and
the proven mark compare like with like against budget targets.
The derivation is pure and unit-tested: roundtrips never inflate the
budget, reallocation is monotone in FEC, and a budget too small for
its own audio floors honestly. punktfunk-core --features quic: all 500
lib tests green natively; punktfunk-host clippy -D warnings green on
the CI image. Docs: the bitrate sections say what the number now means.
Static content used to poison the client's ABR against the first moment
of motion (the 2026-08-26 field chain, step 5), and a frame-driven
source could never climb at all (the documented dead band). Four
changes, per the signed-off RFC §4.1–4.3 + §7 Q4:
- The host marks idle-keepalive re-encodes on the wire
(USER_FLAG_REPEAT; whole-frame and streamed paths) and says so in a
new trailing Welcome byte (host_caps2 / HOST_CAP2_REPEAT_MARK — the
second capability byte the 0x80 wall predicted, same append
discipline, placeholder chain extended one link). Old clients ignore
both; against an old host the client keeps every legacy rule.
- Idle windows (every AU a repeat) are NEUTRAL: they train no OWD/
decode/encode baselines, accrue no climb credit or re-probe
authority, and never authorize a climb — loss/flush/drop keep their
full power. The pinned climb-gate test is extended, not deleted.
- Utilization is measured per frame at the source's own rate: a 35 fps
menu on a 90 Hz config climbs when its frames run full. The
proven-headroom cap prorates with it — it bounds the next target's
projected WIRE rate at ×1.5 over what was delivered — or the two
gates would deadlock exactly where the fix is needed.
- Recovery is bounded and multiplicative: the proven mark is a
two-bucket windowed max (~30–60 s) instead of all-session, and the
first active window after ≥3 s of stillness re-arms slow start with
the cooldown cleared — the ~103 s additive crawl from the floor
becomes seconds, never past ×1.5 over recently-proven delivery.
- FLOOR_KBPS drops 5000 → 2000 (RFC §7 Q4), with a one-shot log
warning on the first descent below the old fence; the client-settings
doc says so.
punktfunk-core --features quic: all 500 lib tests green natively,
including six new field-shaped scenarios (frame-driven climb, idle
neutrality head-to-head vs a legacy host, bounded onset re-arm,
windowed proven decay, floor + warning, idle-never-climbs).
Phases 1+2 of the ABR overhaul implemented review §2.1/§2.2/§2.3/§2.4 while this
branch was doing the same, so every ABR conflict resolves to main's side and my
duplicates are deleted:
- abr.rs: main folds the mode-switch rebind into set_stream_cap itself (a
`mode_switch` flag) instead of a second method — my rebind_stream_cap and its
test are removed; main's a_mode_switch_reteaches_the_stream_cap_both_ways
covers strictly more (up-switch, re-authorize, down-switch, disabled).
- pump.rs / control_task.rs / data.rs: main's ack queue and stream-cap recompute
are the same shape; taken wholesale.
- stream.rs: main's §2.2/§2.3 arms taken (its gap cast saturates, mine did not).
What this branch still carries is what main does not: the capture-stall telemetry
(posture line, repeated-stall WARN, CONTENT-SILENCE prose), the AMF work
(applied_bitrate_bps readback, accepted-props logging, AV1 B-picture pin,
no-reordering assertion), the adl-emul probe fixes, and the wire-MTU-re-key
attribution arm.
H.264 already pins BPicturesPattern=0 ('RDNA3+ defaults > 0'). AV1's three
B-picture properties are VCN5 features (AMF header, verified 2026-08-26) whose
defaults are 0/false today — but a default that flips on newer silicon is
exactly how H.264 grew them, and AV1 is the one AMD codec with no LTR and no
intra-refresh, so a reordering surprise lands on the codec that can least afford
it. Optional sets: pre-VCN5 drivers decline the names, which is the right no-op.
HEVC needs no twin — AMF defines no B-frame property for it at all, and a VCN3
capture measured 3 I + 52 P + 0 B.
The live smoke test now asserts AUs leave in submit order, so a driver that
silently declines a pin fails the test instead of shipping reordered output.
08-22 ABR review §2.4: a full resolve ack plus a corrective short retarget in
the same 750 ms report window collapsed to whichever arrived last — host-cap
learning needs two consecutive short acks, so a lost correction delayed or
prevented the cap and could reintroduce the overdrive sawtooth. Bounded queue
(8), drained fully per window.
08-22 ABR review §2.1: the stream-shape cap was computed once from the Welcome
mode and never again, so a 4K→720p switch kept authorizing 4K-sized climbs for
the whole session (only the reactive loss/decode signals reined them in). The
mode-gen site now recomputes the cap from the accepted mode (depth/chroma are
session-negotiated and ride along) and rebind_stream_cap clamps an already-
learned ceiling down to it. Up-switches lift only the cap — with no untrimmed
measurement stored, a higher ceiling would be evidence-free (§3.3 re-probe owns
that half). Pinned by a_mode_switch_rebind_clamps_the_learned_ceiling_but_never_raises_it.
A tag is a pointer, not a version. `actions/checkout@v4` re-resolves on
every run, so whoever controls that tag controls the first step of nearly
every job in this repo — including the jobs holding signing keys. 52
checkout sites and 31 cache sites now name a commit; announce.yml's lone
existing SHA pin moves up with them so the tree is uniformly pinned rather
than half-pinned, which is the state where a reader cannot tell a
deliberate omission from a miss.
checkout v4 -> v7.0.1, cache v4 -> v6.1.0, both by commit.
The reason this needed proving rather than just doing: v5+ of both declare
`runs.using: node24`, and Gitea's runner only accepts node24 from a certain
version on. Checkout is step 0 of almost everything here, so getting it
wrong fails the whole fleet at once — including the runs that would tell
you it broke.
What was established first:
- every runner serving this repo is Gitea Runner v1.0.8, whose vendored
act accepts node24;
- `runs.using` is only a validation gate — act execs a BARE `node` from
PATH, so the image's node is the real interpreter, and the oldest one
here is 18.19.1 (ubuntu:24.04's nodejs, in rust-ci-noble);
- so checkout v7's node24-targeted ESM bundle was run under that exact
node, in that exact image: it parsed inputs, drove `git` through
@actions/exec, created .git, set up and tore down credential config, and
ran its post step. It reached a genuine git error against the synthetic
file:// remote used for the test — not a module-load or missing-API
failure. It works.
- actions clone straight from github.com here (no Gitea mirror), so these
SHAs are meaningful; both tags are lightweight, pointing directly at the
commits pinned.
No breaking change in v5..v7 applies: this repo passes zero checkout
inputs, and uses neither `pull_request_target` nor `workflow_run` (v7's
fork-PR restriction). cache v5/v6 pick the same legacy service path as v4
because the runner never sets ACTIONS_CACHE_SERVICE_V2.
upload-artifact@v3 is deliberately NOT swept — it is pinned low on purpose,
because Gitea's artifact backend identifies as GHES and v4 refuses it.
The 2026-08-26 lab sessions over an overlay hop (udp_mtu 1336) produced the
'host/display disturbance' warn at period 1.7 s — just outside both client
cooldown bands — while the real cause was the path black-holing full-size video
until the re-key. Period alone cannot make this call; the session's transport
context can. New first-priority arm: wire_rekeys > 0 names the constrained path
and points at PUNKTFUNK_WIRE_MTU.
Last floating tool in the builder images. Unpinned, two rebuilds months
apart bake different cargo-ndk versions with nothing recording it, and this
is the tool that drives the .so files in the published APK/AAB. crates.io
is append-only with a checksummed index, so the version string is the whole
pin — no checksum needed, unlike the bun/sccache/FFmpeg cases.
4.1.2 is current, so this is a zero-change pin like the others.
rust-ci-noble builds FFmpeg and nv-codec-headers from `git clone --branch
<tag>`, and the .so files land in the host .deb every Ubuntu user
installs. Tags are mutable: upstream can repoint one and, unlike a branch,
nothing would look different. The comment above it claimed "immutable-tag
clone, so no separate checksum needed", which is the same
comment-asserts-what-the-code-doesn't shape this whole branch has been
unpicking.
Both are now asserted against the commit the tag points at TODAY, so the
built tree is byte-identical and only the mutability is closed. A moved tag
now fails the build loudly, matching the sha256sum -c pins next door.
Both tags are ANNOTATED, so the bare ref is a tag object, not a commit —
the pin is the peeled `refs/tags/X^{}`, which is what `rev-parse HEAD`
returns after a --depth 1 tag clone. Pinning the tag object would have
failed every build.
rustup's installer and `cargo install cargo-ndk` are left: both float, but
crates.io is append-only with a checksummed index and rustup verifies its
own downloads — neither is a fixed name whose bytes can move.
Two things that cost real time setting DEPLOY_KNOWN_HOSTS for the first
time. ssh looks a host key up by the exact string it dialled, so a plain
entry stops matching the moment DEPLOY_PORT is not 22 — and it fails
looking like a host-key error, not a formatting one. The comma form covers
both. And DEPLOY_HOST is unom-1's public Hetzner IP since the 2026-07-12
cutover, so a stale private address in an SSH config is the wrong thing to
scan.
Also say ed25519 only: pinning every type ssh-keyscan prints means the
weakest pinned key decides, since a host offering just RSA would satisfy
the check on the RSA line.
The marking was opt-in because some consumer ISPs/routers bleach or
reject DSCP-tagged packets — but that risk lives on WAN paths, and the
win (APs map DSCP to WMM airtime priority — real for exactly the Wi-Fi
downlink field case) lives on local ones. The default becomes AUTO:
mark toward RFC1918 / ULA / link-local / loopback peers, stay off
toward anything routable.
PUNKTFUNK_DSCP=1 still forces it on everywhere, =0 stays the kill
switch, and the embedder hook (the Android low-latency tie-in) still
forces on regardless of the peer — for paths like VPNs the address
math can't recognize as local. Decision + classifier are pure and
unit-tested; the connected-loopback test covers the AUTO path end to
end. Windows qWAVE mechanics unchanged.
The four correctness seams from the 08-22 auto-bitrate review §2, chosen
options per the RFC (planning design/abr-stack-overhaul.md §3):
- §2.3: a failed bitrate-change encoder rebuild now snaps the client back
(retarget_tx) — the control task acks BEFORE the apply, so the client's
climb base, utilization and proven math tracked a rate the encoder
never ran until some later event happened to correct them.
- §2.2: the ABR rebuild announces PipelineGap on success, like the
mode-switch and topology rebuilds already do — a ~0.6 s host-local
stall read as congestion killed slow start for the session (the 401 ms
field case: minutes at ~15 Mbps on a clean link).
- §2.1: an accepted mode switch re-teaches the stream-shape cap —
computed once from the Welcome mode, 1080p→4K kept a 1080p-sized climb
ceiling and 4K→720p left an oversized one standing. A re-set
set_stream_cap also rebinds the already-learned ceiling downward
(set_ceiling deliberately never lowers); the FIRST set keeps the
founding semantics, pinned by the existing stream-bound test.
- §2.4: the bitrate_ack slot becomes a queue drained in arrival order —
latest-wins collapsed a full resolve ack + corrective short retarget
landing in the same 750 ms window, and host-cap learning needs two
CONSECUTIVE short acks.
punktfunk-core --features quic: 490 tests green natively, including the
new a_mode_switch_reteaches_the_stream_cap_both_ways.
Heroic 2.21 added a fullscreen gamepad UI — the Big Picture of that launcher,
and the tile you actually want on a stream. Nothing could publish it: a plugin
names a launcher UI and the host builds the line, and the only Heroic value the
host knew was `heroic`, which opens the ordinary window.
`launcher_ui` now also takes `heroic-console` on Linux, resolving to the same
prefix `heroic` does — native binary if on PATH, else the Flatpak — plus
`--console --fullscreen`. Both flags, because Heroic reads them separately:
`--console` only routes the UI to that front end (`isCLIConsoleMode`) and
`--fullscreen` is what fills the screen (`isCLIFullscreen`). No URI can do it —
`heroic://` speaks `ping` and `launch` and nothing else — which is the same
reason Playnite's fullscreen tile spawns its exe directly rather than going
through the registered protocol handler. An older Heroic ignores the unknown
`--console` and still honours `--fullscreen`, so the tile degrades to a
fullscreen desktop UI rather than to nothing.
That makes the value a launcher UI rather than a launcher. It already was one on
Windows, where `playnite` has always meant `Playnite.FullscreenApp.exe`; the doc
comment claiming otherwise is corrected. A `heroic_ui` kind mirroring `steam_ui`
would have been tidier and was rejected on the compatibility asymmetry: an
unknown KIND degrades to an unlaunchable tile, but an unknown VALUE is a hard
400 that refuses the whole reconcile, so either shape has to be gated on
`minHost` in the plugin index and the value is much the smaller change. A plugin
publishing `heroic-console` must set `minHost` to the release carrying this.
Second fix, from the same reading: `resolvable_launcher_ui` special-cased only
Playnite-on-Windows and answered `true` for everything else, so a Heroic tile
survived `sanitize_launcher_entries` even when `heroic_launch_prefix()` resolves
to nothing. Keeping `~/.config/heroic` after uninstalling Heroic is enough to
reach that — the plugin's `detect` only looks for the directory — and the
operator got a launcher tile that does nothing. Both Heroic values now probe the
prefix, exactly as Playnite probes for its exe.
Static content used to strip every defense before motion: the unpaced
microburst allowance was an absolute max(128 KiB, wire/4) — sized for
gigabit LAN, so at Wi-Fi bitrates every frame went out back-to-back —
and adaptive FEC decayed to 1 %, so the first big motion frame died
unprotected (the 2026-08-26 field case; RFC design/abr-stack-overhaul.md
in punktfunk-planning, §2.1–2.4).
- The allowance is now TIME at the pace rate: 10 ms, clamped to
[16 KiB, 256 KiB] (send_pacing::auto_burst_bytes). One constant lines
up both proven ends — ~19 KiB at the field case's 15 Mbps pace (its
discriminator was PACE_BURST_KB=16) and ~112 KiB at 90 Mbps LAN pace,
so LAN latency does not regress. PACE_FACTOR=0 keeps the legacy rule.
- A streamed AU consumes ONE allowance across its block flushes instead
of a fresh one per block (the latent per-block multiplication).
- One frame's paced spread is bounded to ~2 frame intervals so an IDR
can't back the encode|send sync_channel(3) up into cadence_degraded,
which refuses every climb; MAX_PACE_SPREAD stays the absolute bound.
- Adaptive FEC gains a burned floor: any window with real shard loss
raises the decay floor to 5 %; ~2 clean minutes re-earn 1 %, an early
re-burn doubles the requirement (bounded), a durable step-down resets
it — no session-permanent latch, per the encode stand-down's house
rule. PUNKTFUNK_FEC_PCT pin semantics and the GameStream plane are
untouched.
Pure logic (FecFloor, auto_burst_bytes, native_budget) is unit-tested;
the burned-floor band is noted in the FEC_PCT docs.
The chunked poll ships slice bytes the moment the doNotWait lock publishes
them, trusting that they are a byte-exact prefix of the AU the finishing
blocking lock returns. The check for that trust — the ChunkState shadow
comparison — was compiled out of release builds, so a driver branch whose
sub-frame accounting runs ahead of the flushed bytes shipped not-yet-written
buffer content straight to the wire: self-consistent tiling, wrong bytes,
no client counter moving. That is the black-band field report (Windows
client, 4090 host, identical across all three decoders, Android immune —
it never negotiates the slice wire), and most likely the Linux/AMD grey
smears too.
Make the shadow prefix check unconditional (one AU-sized copy + compare
per frame — noise next to the encode), and on divergence latch
subframe_broken before bailing into the existing encode-stall recovery:
the in-place rebuild now resolves sub-frame OFF for every later session
open on this encoder, so the driver that lied is disarmed after exactly
one rebuild instead of looping into MAX_ENCODER_RESETS. The client sees
the abandoned-AU path it already handles (ages the frame out, IDR
re-anchors) — a one-second hiccup, once, instead of endless corruption.
Both direct-NVENC backends (Windows D3D11, Linux CUDA) get the identical
change; the bail path also stops leaking the popped frame's input mapping.
The workflow-level pins closed the bootstrap path only. On the normal path
the bun that gets vendored into the published .deb/.rpm comes from the
builder image, and every image still installed it with the upstream
installer piped into bash — so the script still chose bytes that ship to
users. rust-ci and fedora-rpm now take the same pinned, SHA-256-checked
bun-v1.3.14 asset the workflows do; arch-ci takes bun from pacman, which
verifies package signatures.
Same class, found while sweeping and worse than the cited sites: five
images fetched sccache over a version-pinned URL with no integrity check at
all. sccache is RUSTC_WRAPPER for every binary we ship — it can serve
poisoned object files straight into a signed package, which is the position
the review called the highest-leverage in a build. Download, verify against
upstream's published sum, then extract.
packaging/flatpak/build-flatpak.sh took flatpak-cargo-generator.py from a
mutable master, the same fetch flatpak.yml just pinned; both now name the
same commit and sum, so the local build and CI agree.
Arch note: bun rides the existing -Syu transaction rather than a later
layer. A separate layer resolves against the DB baked into the CACHED -Syu
layer, and Arch mirrors carry only current versions, so a cache-hit rebuild
months on would fail to fetch a package the stale snapshot names.
None of this takes effect until the images are rebuilt: docker.yml's
`builders` job keys on the git tree hash of ci/, so this re-keys the whole
family. Until then the workflow bun pins sit behind `command -v bun ||` and
short-circuit against the image's baked bun.
rustup's own installer is left piped, as apple.yml already does — pinning
rustup-init is a separate decision, and the same argument reaches every
image at once.
First .173 run: 15 logical adapters enumerated, zero connectors walked, exit 0,
no explanation — a probe whose deliverable is an rc must never end silent. One
record per distinct (bus, vendor, present) shape before the filter.
An explicit client rate under PyroWave was ill-defined (all-intra bpp
semantics — the operating point is bits per pixel, not kbps) and bypassed
the PUNKTFUNK_PYROWAVE_MAX_MBPS operator ceiling entirely.
Host: resolve_bitrate_kbps_for ignores the requested rate under PyroWave
(warn when overriding) so every PyroWave session goes through the per-mode
bpp pin + ceiling, and bitrate_auto treats PyroWave sessions as Automatic
so mode switches re-resolve the pin whatever the Hello carried.
Clients: pf-client-core sends bitrate 0 when the preference is an
ADVERTISED PyroWave (a failed decode probe falls back to H.26x, where the
user's rate must survive); the Apple client mirrors the same gate at its
own Hello site. The console UI and the Apple settings dim the bitrate
control with a one-line explanation instead of offering an inert rate.
The stored setting is preserved everywhere — switching codecs back
restores it.
Follow-ups left open by the security-review pass.
The Windows client had the deep-link fix's enforcement but not its UX: a
name- or address-resolved link was REFUSED with a note pointing at the host
list, marked in-code as degraded, because that shell had no prompt surface
wired up. It has one — `ContentDialog`, already used for "Remove saved
host?" and "Delete profile?" — so the link now asks, naming the host and
anything it wants to launch, and on confirm runs the identical dial the
id-referenced path runs. Same wake, trust and error surfaces; confirming is
one click in front of the same code.
The supply-chain pins only covered the jobs the report cited. deb.yml
(a signing-key job) and arch.yml still piped bun's installer into bash;
flatpak.yml still took the deploy host key on first contact while holding
FLATPAK_GPG_PRIVATE_KEY. deb now takes the same pinned, SHA-256-checked bun
asset as rpm and windows-host; arch takes bun from pacman, which verifies
package signatures; flatpak verifies the host key from DEPLOY_KNOWN_HOSTS
through the fail-open-through-setup preflight it already had.
Found while sweeping, worse than the cited sites: flatpak.yml fetched
flatpak-cargo-generator.py from a mutable `master` and ran it in the job
holding the GPG key — third-party Python deciding which crate sources the
signed build vendors. Pinned to a commit and checksummed.
pf-zerocopy's EGL bindings declared glShaderSource/glGetUniformLocation as
`*const i8`, but `CStr::as_ptr()` yields `*const c_char` — i8 on x86_64,
u8 on aarch64. So the crate did not compile for aarch64 at all, and CI is
x86_64-only and could never see it. Verified both directions: with c_char
`cargo check -p pf-zerocopy --target aarch64-unknown-linux-gnu` passes,
and the old spelling still fails E0308 there.
Docs: the note saying Windows has no prompt is gone, and the first-connect
sentence put Windows in the wrong group — it pre-fills its trust prompt
from the link like Linux and Android; only the Apple apps show a notice.
Corrected an Apple comment claiming it seeds the add sheet with the address
and fingerprint when it only sets a notice string.
- Every capture session stamps a 'GPU-priority posture' INFO line (both REALTIME
opt-ins) at open, so a stalling log carries the levers even when no WARN fires.
- Repeated stalls WITHOUT a stable period now WARN with the full triage payload
(tallies, suspects, levers) — the 2026-08-26 7700 XT log had 6 holes in 8 s and
zero guidance because only the metronomic arms spoke.
- CONTENT-SILENCE prose stops overselling benignity: a frozen presenter
(disturbance-immunity Flavor 3) reads identically, and our probes all run at the
host's elevated GPU priority.
- Native AMF implements applied_bitrate_bps via a GetProperty readback (typed the
existing vtable slot), so encoder_ceiling learning / the ABR overdrive guard stop
being inert on AMD; optional-property rejections log at INFO and the encode-active
line carries ltr/intra_refresh — the VCN capability matrix builds itself from
field logs.
- Doc drift: PUNKTFUNK_GPU_PRIORITY_CLASS default is high (not auto) everywhere it
is described; PUNKTFUNK_IDD_ADAPTIVE documented; troubleshooting names the
REALTIME-lever first step and the new repeating-stall warning.
Design: punktfunk-planning design/windows-amd-host-program.md §3.1–§3.3 wave 2.
Follow-up from the same Chromecast field report: the hint legend only ever
spoke gamepad (or desktop-keyboard keycaps), whatever was actually driving.
A TV remote got Enter/Esc/Tab — keys it does not have — and a Switch pad's
badges read the Xbox letters, so 'A Select' sat over the button engraved B.
The shell now notes WHAT drove last at every input seam — the Android host
loop labels its two menu paths (discrete events are the remote, the pad
sampler is the pad), the desktop overlay's menu channel is pad by
construction, and the keyboard path notes itself. Each frame the legend
resolves from that:
* a pad speaks its own family — PlayStation shapes, Nintendo letters (both
pairs swapped, the way the pad is engraved), ABXY for the rest;
* keys on Android are a TV remote: an OK badge for select, the ↩ return
arrow for back, the section hint pointing at the D-pad path (▲) that
reaches the tab strip, and the Y/X hints hidden outright — a remote has
neither, and advertising a button the device cannot press is worse than
silence;
* keys on the desktop stay keyboard keycaps;
* nothing has driven yet: the connected pad's family, else the platform's
key device — so an untouched console reads right on every device.
The controller chip grows a remote mark and says 'TV remote' when that is
what is driving; a pointer press changes nothing, since a tap says nothing
about the buttons in the user's other hand. The screen dump gains the two
remote frames (Home + Settings) for the eyeball pass.
A slice-streamed sentinel's wire base was bounds-checked (in range, below
the final block) but never validated to TILE the AU: a base that lied
within bounds left a zero gap and an overlap, and the reassembler still
stamped the frame `complete`. The decoder then painted the wrong-offset
bytes as garbage rectangles while no loss counter moved — so the recovery
machinery never fired and the corruption marched on indefinitely (the
field report: black bars 'moving like an equalizer', identical across
Vulkan/DXVA/CPU decoders, Android immune because it never negotiates the
slice wire).
At completion, verify the blocks tile [0..total_data] contiguously; a
frame that doesn't is killed exactly like a lying final header — index
remembered against stragglers, counted into frames_dropped, which is the
signal that arms the freeze gate and requests recovery. The
slice-progressive prefix walk gets the same contiguity guard so a lying
base can't extend a 'contiguous' prefix either.
Gate C in check-unsafe-hygiene.sh matches the qualified `env::set_var`
anywhere in a file, comments included — deliberately, so the contract stays
dumb and stable. The new SESSION_BACKEND doc explained what it replaced by
naming it, which reads as a fresh call site to the gate. Reword rather than
raise the baseline: the baseline is there to catch a real write later, and
this change deleted one.
Security review 2026-08-25, 58 confirmed findings across host, console,
clients and supply chain. Nearly every serious one is a documented boundary
whose code stopped enforcing what its comment promised — so where the two
disagreed, the comment won and the code was made to match, and where it
could not be, the comment was corrected instead.
Critical — a console session cookie alone reached code execution: every
pairing route rode the generic catch-all with the operator's admin bearer
attached. Arming, approving and PIN submission now sit behind the console
password like the other trust-root routes, and the armed PIN is returned
once in that gated response instead of riding a 1 s status poll.
High — the plugin lane no longer reads the unredacted log ring (which
carried the webhook credentials the /hooks carve-out exists to withhold);
hook lines log an origin and a short id, never a URL or a command line; a
plugin-reported pid is held to procscan's start-time floor before the
SYSTEM host will signal it; ClipOffer is gated on the live grant mask, so a
revoked guest loses the host clipboard in both directions; ENet refuses
connects with no live launch instead of letting LAN peers squat all four
slots; Windows secrets are born with their DACL applied rather than
world-readable; the sysext feed binds FEED and a monotonic SERIAL inside
the signed bytes; privileged_field allowlists the host-resolved launch
kinds so a new kind is privileged by default; five parser panics reachable
from one malformed NALU are range-checked; release-signing jobs pin bun,
sccache and actions by checksum/SHA; h2 -> 0.4.19 (RUSTSEC-2026-0258).
Deep links only auto-dial by stable record id now — a display name or an
address gets a confirmation on every client. The Apple identity key moves
to ThisDeviceOnly so it stops riding encrypted backups.
pf-vdisplay stops routing session identity through the process environment:
the injector backend threads through a typed slot, so per-batch getenv no
longer races a per-session setenv. The four remaining writes have no
in-repo readers and are documented as such; the SAFETY proof that claimed
ENV_LOCK made them sound is gone.
Verified: cargo clippy --workspace --all-targets --locked -D warnings and
cargo fmt --all --check clean in the CI image; web builds, tsc --noEmit
clean, 22/22 server tests; Swift debug+release + 26/26, Kotlin :kit 7/7.
Not fixed, deliberately: the plugin token can still mint command execution
(the plugin launch kind exists so a plugin names a command the host runs —
per-plugin identity does not change that, and the runner is one process
hosting fibers, so there is nowhere to hang a credential); the shared
plugin-UI origin; the rollback Authenticode publisher pin (Azure mints a
fresh leaf per request, and the signer subject is not in the tree). Each is
now described accurately where it lives instead of being claimed closed.
A Chromecast field report: with only the TV remote — the pad had dropped off,
as Chromecast pads do — every settings tab but the first was unreachable. The
split of the one 30-row scroll into tabs put section switching on L1/R1, Tab
and PgUp/PgDn, and a remote has none of those; the D-pad's left/right already
mean 'adjust the focused row'.
Up from the list's top row now steps onto the tab strip instead of recoiling:
left/right travel the ring (wrapping, like the shoulders), Down or A drop
back into the rows of the tab that's showing, B still leaves the screen, and
the shoulders keep working from either focus. The strip shows the handoff —
brighter pill, ‹ › chevrons — the rows rest their focus ring while it holds
focus, and the hint bar names the D-pad's meaning up there. A pointer press
on the rows takes the focus back.
The gamepad path is untouched: nothing changes until an Up is pressed on the
top row, which used to be a boundary recoil.
A Bazzite triple-monitor field report: monitors cycling off/on around every
session, sessions ending with some or all monitors dark or at the wrong
resolution, and an exclusive apply logging also_disabled=[] on a desk with
three enabled physicals.
KWin persists output state per MONITOR SET (kwinoutputconfig.json). Creating
our virtual output changes the set, and a set that ever ran exclusive has
'physicals disabled' stored — so KWin disables them ITSELF, in the window
between our output's creation and the topology apply's enumeration. The apply
then finds nothing enabled, captures nothing for restore, and teardown
re-enables nothing: the desk stays dark, and KWin's own recovery improvises
modes. Under Extend/Primary the same stored setup switched screens off that
those topologies promise never to touch.
Three moves, all in the KWin backend:
* create() snapshots the enabled physicals BEFORE the virtual output exists —
the only read KWin's reaction cannot have polluted.
* Exclusive: the snapshot joins the restore list (union_restore) — an output
KWin disabled before we could see it is still re-enabled at teardown.
Extend/Primary: reenable_stranded() puts the stored-config casualties back
on, immediately and once more after a short delay (KWin can apply the
stored setup after our first read). One shot each, never a loop.
* The group-teardown restore gains a delayed verify that re-asserts AFTER our
output is reclaimed — under the without-us set, so KWin persists the heal
into the stored setup instead of re-fighting us next session. It stands
down if a new session's managed output already owns the topology.
A box stranded BEFORE this fix stays stranded once: the snapshot cannot see
outputs that were already dark. Re-enabling them once in System Settings
while no stream is live writes the healthy without-us setup back, and the
loop cannot re-form.
`punktfunk` only *Recommends* punktfunk-web (and punktfunk-scripting), so
`sudo dnf install punktfunk` installs the host with no console on any box where
weak deps are off — install_weak_deps=False, --setopt=install_weak_deps=0, or an
rpm-ostree layering that drops them. The user then follows step 4 and gets
"Unit punktfunk-web.service could not be found", with nothing saying why.
Name both subpackages in the install line at its single source
(data/platforms.json + the docs-site snapshot), which the guided installer and
the Fedora page quote verbatim, and drop the "the console comes with it" claim
from the README. Adds the symptom to Troubleshooting, including the other cause:
COPR has no punktfunk-web at all (no bun in its mock chroot).
21 commits since v0.31.3 (14 non-merge). Cut from origin/main c407f6a6 (#393
merged).
THE NUMBER: a patch, and the cleanest one in a while — NOTHING versioned moves.
WIRE_VERSION 2, C ABI 25 with include/punktfunk_core.h showing NO diff against
the v0.31.3 tag (nor against v0.31.2 or v0.31.1 — third release running), driver
protocol 6 / min 3 with pf-driver-proto unchanged, gamepad channel 3, plugin
index schema 1, host event schema 1 (events.rs no diff), gamescope +pfhdr8 with
no new patch files, SDK 0.1.6 and plugin-kit 0.4.4 both untouched. api/openapi.json
is CONTENT-identical — info.version is the entire diff, the first release since
v0.31.0 where the management API grows nothing. No lockfile moves, in any of the
five. Four feat commits, all additive and all client- or Linux-host-side; v0.31.3
and v0.31.1 each carried two feats as a patch on the same reasoning.
THE SHAPE: Linux-host, and the faults share a premise — a policy written against
ONE desktop that silently did nothing on the others. Topology::Exclusive on a
gamescope session was implemented as org_kde_kwin_dpms and reached only a live
KDE desktop, so a Game Mode box (the deployment whose TV the operator most wants
dark) got nothing: #389 is five commits closing that — a DRM floor for a box with
no desktop at all, sway and Hyprland arms, the managed route's own hold, and the
box-session free that was gated on is_steam_launch. The sleep:idle BLOCK
inhibitor refused every Suspend() for a stream's length including the operator's
own from Steam's power menu, and on a DM-stopping takeover polkit's allow_active
fallback found no session to elect and dropped all three power actions to
auth_admin_keep (#391). The web console served the LEGACY identity because every
launcher names that pair and none of them CAN choose, so browsers rejected it and
the tray's mgmt-pinned probe refused the handshake and labelled a healthy console
dead (#393). Plus the client's encode down-driver (#392), an installTap format
snapshot reaching the ObjC terminate handler (#387), the console's bitrate row
(#388), and a GTK front door for the console UI (#390).
TWO ENTRIES WORTH THE READER'S ATTENTION, both recorded as such:
* The sway arm of #389 is NOT verified on glass — the lab has Bazzite, Nobara
and SteamOS, no sway box. Hyprland, KDE and the DRM floor were all measured
on real machines. The notes say so in "Thanks" rather than burying it.
* #389's Hyprland arm shipped WRONG in its first cut and was corrected on glass
(540e282e): the dpms dispatcher is a TOGGLE that ignores the state word, so
the blind "send off, later send on" would have LIT an already-dark head at
stream start and DARKENED a lit one at teardown — the exact failure the
feature exists to prevent. Read -> act only if different -> verify.
DOCS FRESHNESS, per docs/releases/README.md step 1: #390 and #393 carried their
own docs-site updates (clients.md, and #389's two gamescope.md edits). Two facts
were left owed, both in gamescope.md and both the "stale sentence" class that
docs-drift cannot catch:
* the darkening mechanism list still read "KDE, else DRM" and never learned
about the sway and Hyprland arms from e0a82201;
* the "could not deliver a dark screen" example was a box in Game Mode, which
is now precisely the case that IS served by the DRM floor. The real remaining
gap is GNOME/Mutter, so it says that instead.
Also: the punktfunk group grew a third grant this cycle (the three logind power
actions, via 49-punktfunk-power.rules), and the group's own callout block
enumerated only the usbip nodes — one sentence added there.
No new PUNKTFUNK_* variable this cycle (PUNKTFUNK_UI_TLS_CERT/KEY are
pre-existing and already in the baseline), no new host subcommand, and no install
command, repo URL or port change, so data/platforms.json and the website's
vendored copy need nothing.
VERIFIED HERE: scripts/ci/check-docs-drift.sh clean, and PROVEN LIVE rather than
assumed — a deliberate one-byte break of the openapi copy makes it fail, and it
passes again restored; scripts/ci/check-docs-links.sh clean; the android.yml Play
notes gate run verbatim, 481/500 characters and unique against every other
release's file; both openapi copies cmp identical and stamped 0.31.4; cargo fmt
--all --check clean; git diff v0.31.3..HEAD empty on include/punktfunk_core.h, on
crates/pf-driver-proto, on punktfunk-core/src/lib.rs, on punktfunk-host/src/events.rs
and on api/openapi.json, which is the direct evidence for those five version rows;
git diff v0.31.1..HEAD on the C header also empty, which is the "third release
running" claim; Cargo.lock's 36 workspace version strings moved with Cargo.toml
and zero 0.31.3 strings remain; 27 crate dirs / 39 workspace members, both
unchanged; notes voice scan clean (zero backticked terms above ## For developers,
and zero internal names on a scan for gamescope/polkit/logind/DPMS/CRTC/DRM/
systemd/kwin/mutter/wlroots/rustls/ioctl); CHANGELOG link pinned to
src/tag/v0.31.4.
NOT RUN HERE, and why: any punktfunk-host build, clippy or cargo test — the host
does not compile on macOS at all, and CI covers it; the web/ and docs-site/ bun
builds — nothing under web/ is touched by this commit and the docs-site edits are
prose in an existing .md; the Android unit tests — nothing here touches Kotlin.
LEFT AS A DECISION, not made here: the tag itself. Notes, CHANGELOG and Play text
are authored ahead of it exactly as docs/releases/README.md step 1 requires, so
whichever workflow wins the create race seeds a complete release body — but
pushing v0.31.4 fans out every build workflow, and that is step 2.
The web console never followed the identity split: every launcher names the legacy cert.pem/key.pem, so it served a CN-only, SAN-less RSA cert. Browsers reject that outright, and the tray's liveness probe — pinned to the native identity the mgmt API serves — could never complete the handshake, labelling a healthy console "not responding" beside a tooltip reading "idle".
Resolved at the Nitro entry, the one place every launcher routes through: prefer the native pair when both halves are present, usable and in the same directory; fall back to the legacy pair otherwise. The tray's console probe drops its pin rather than gaining a second one, and `serve` now mints the native identity before the legacy one.
Reviewed adversarially (no blockers; the one real finding — a pair that could be assembled from two different directories — fixed in 1e2b956d). All 8 checks green, including the native-only clippy gate. Verified end to end against a built server: both pairs → P-256 with SANs; legacy only → RSA as before; 0-byte native cert → clean fallback rather than a restart loop.
Review of the parent commit. One real defect, the rest accuracy.
The resolver could hand back a MISMATCHED pair, which is the one invariant its
own header promised it never would: `nativeCert` came from `dirname(cert)` and
`nativeKey` from `dirname(key)`, two independent directories, so
("/a/cert.pem", "/b/key.pem") resolved to /a/native-cert.pem + /b/native-key.pem
— two unrelated files presented as a pair. No shipped launcher splits them, but
the guard is one comparison and it is the whole point of the module.
Rewritten off a suffix test instead of `node:path`, which fixes two more things
in passing. `node:path` resolves per-RUNTIME, so a POSIX CI runner reads
`C:\ProgramData\punktfunk\cert.pem` as one long filename and never swaps — and
Windows, where windows/service.rs hands us exactly that, is the platform the CI
job can never exercise. The suffix test gives the same answer everywhere and is
now covered by a win32 case. It also leaves the prefix VERBATIM, where
`join(dirname(p), …)` normalised /a/b/../cert.pem into a different directory the
moment `b` was a symlink.
Existence is no longer enough: `pf_paths::write_secret_file` is
create+truncate+write rather than temp+rename, so a console starting mid-write
could adopt a 0-byte cert and leave `Bun.serve` throwing on every restart. Not
every launcher retries forever — the Steam Deck unit is `Restart=on-failure`
under the default rate limit, i.e. permanently dead. The check is now a
non-empty stat, mirroring the host's own `!c.trim().is_empty()`. Verified: with
native-cert.pem truncated to 0 bytes the console starts and serves the legacy
pair.
Two comments of mine overclaimed and are corrected rather than left to mislead:
* serve() said "cert.pem existing implies the native pair does too". False on
an upgraded host whose native clients pinned the legacy cert — load_or_adopt
returns it and writes no native files at all. The ordering claim that IS
true is narrower: whenever that call writes a native pair, it does so before
cert.pem appears.
* the tray said the console entry "always opens the same URL regardless of the
probe". True of the menu entry, but win.rs gates the tray-icon single-click
on console_up. Also notes that the Windows probe was never pinned to begin
with (punktfunk_config_dir is None off Linux), so that half is a no-op.
Rest is doc drift the parent commit annotated in two launchers but not the other
four: web.env.example, README, web-run.cmd, and the ci.yml comment that still
said the web test step was "Scoped to server/".
18/18 web tests (was 14), biome and rustfmt clean, and the runtime check re-run
against a fresh build: both pairs -> P-256 with SANs; 0-byte native cert ->
legacy RSA, console still serving.
A Linux operator saw "Open web console (not responding)" in the tray next to a
tooltip reading "idle", and the console would not load in a browser either.
The host has kept two identities since the identity split (crate::identity):
native-cert.pem/native-key.pem (P-256, real SANs — what the native QUIC plane,
the mgmt API and every native client pin) and the legacy cert.pem/key.pem (RSA,
CN=punktfunk, NO SAN, kept byte-stable for Moonlight). The web console never
followed the split. Every launcher — the systemd unit, the NixOS module, the
Windows service supervisor, web-run.cmd, the Steam Deck installer — still names
the LEGACY pair, and none of them CAN choose: `Environment=` has no "this file,
else that one". So the console served a certificate with no SAN at all, which
costs twice over:
* browsers reject a CN-only cert outright (ERR_CERT_COMMON_NAME_INVALID), so
the console the operator was told to open does not load;
* the tray's loopback liveness probe reused the agent PINNED to the mgmt
identity — the native cert — so rustls refused the handshake and a perfectly
healthy console was labelled "not responding". The "idle" tooltip beside it
is the proof: the same agent reached mgmt fine on the very same tick.
The entry is the one place every launcher routes through, so the choice is made
there: prefer the native sibling pair when both files exist, as a PAIR or not at
all (a native cert with the legacy key completes no handshake with anyone). A
host that never took the split has no native pair on disk and falls through
unchanged, as does an operator-supplied cert under any other name. This also
hands the bundled bun the smaller secret: on a default build key.pem is the
Moonlight pairing SIGNING key, native-key.pem is only a TLS key.
The tray's console probe loses its pin rather than gaining a second one. It is a
different server and there is no rule that it presents the mgmt certificate — an
operator fronting the console with their own LAN-CA cert would have hit this just
as squarely. The probe sends no credentials, reads no body, and decides only a
menu label, so there is nothing for a pin to protect.
`serve` now resolves the native identity BEFORE minting the legacy one. That
closes a first-run window where the console (which waits on cert.pem) could start
between the two writes and serve the SAN-less cert for the rest of the boot, and
it fixes a second latent fault: with cert.pem missing but native clients paired,
the old order let load_or_create mint a brand-new cert.pem that load_or_adopt
then adopted while logging that it was preserving their pins.
Verified against the built server: configured exactly as the shipped unit does
(PUNKTFUNK_UI_TLS_CERT=.../cert.pem), it now serves the P-256 cert with
DNS:localhost/IP:127.0.0.1; with the native pair removed it serves the RSA cert
as before. 14/14 web tests pass, biome and rustfmt clean.
Nothing this controller learns from evidence is permanent — both learned caps
re-probe on the CAP_REPROBE_WINDOWS_MIN ladder, and the clock-flush detector was
itself changed from "off for the rest of the session" to re-armable for exactly
this reason. The encode stand-down had no business being the exception.
What it answers is transient by nature: contention on the host's GPU ends when
the game exits to a menu, when the shader storm finishes, when the second app on
the card closes. What it silences is the only signal that can descend when the
encoder is genuinely past its compute knee on a link that shows nothing else. So
a permanent stand-down trades a bounded problem for an unbounded one — one
contended stretch would strip knee protection from every calm minute that
follows, including the ones where a climb can reach a rate the ASIC cannot hold.
A clean run now re-arms it, and the interval doubles each time the silence is
immediately re-earned, so a genuinely standing contention settles into a slow
poll rather than thrashing. The asymmetry is the whole argument: a too-eager
re-arm costs one ×0.7 and stands down again; a too-permanent silence costs the
protection outright.
Verified on the NixOS VM (125, Hyprland 0.55.4) — and the arm I shipped for it in
the previous commit was wrong twice over. This is why it went on glass.
**The argv did not work at all.** `hyprctl dispatch dpms off <name>`, the form
this file's own probe notes use, dies on the Lua config manager: `dispatch` is
shorthand for `hl.dispatch(...)`, so the bare words are parsed as a Lua
expression —
error: [string "return hl.dispatch(dpms off HDMI-A-1)"]:1:
')' expected near 'off'
The Lua spelling is `hl.dsp.dpms("off", "<name>")` (found by enumerating
`hl.dsp` through `hyprctl eval`, which only exists on that manager). A hyprlang
box wants the classic form, there is no stable probe for which manager is
loaded, and `hyprctl_dispatch` already catches the exit-0 rejections both
produce — so try classic, then Lua, and report both failures if neither lands.
**And the dispatcher is a TOGGLE that ignores the state word.** Measured:
On ==[ hl.dsp.dpms("on", "HDMI-A-1") ]==> Off <- asked ON, got OFF
Off ==[ hl.dsp.dpms("on", "HDMI-A-1") ]==> On
Off ==[ hl.dsp.dpms{state="off", ...} ]==> On <- asked OFF, got ON
Both spellings, positional and table. So the blind "send off, later send on" the
previous commit shipped would LIGHT an already-dark head at stream start and
DARKEN a lit one at teardown — the operator's screen left off after the stream,
precisely the failure this policy exists to prevent. (It bit me while probing:
a restore fired at an already-On head turned it off, which for a while looked
like "dpms on cannot restore on Hyprland".)
So `dpms_one` is read → act only if the state differs → verify, via
`hyprctl -j monitors all`'s `dpmsStatus` (measured to track the connector's
sysfs `dpms` exactly, in both states, and a dark monitor stays listed). That
shape is also correct where the call really is a set, so it is not conditional
on detecting the manager. It returns whether it CHANGED anything, and
`dpms_other_heads` records only those — a head already in the wanted state is
left alone, because "fixing" it would break it, and reporting it would have the
re-light toggle a head we never darkened.
The on-glass assertion is relaxed from "every connected head goes dark" to "at
least one did, and all are restored": this VM carries a virtio `Virtual-1`
beside the real `HDMI-A-1` and Hyprland manages only the latter, so the strict
form failed on a difference that is not a defect.
Verified end to end, real Rust through the real dispatcher on a live Hyprland:
before: [("card0-HDMI-A-1", "On"), ("card1-Virtual-1", "On")]
during: [("card0-HDMI-A-1", "Off"), ("card1-Virtual-1", "On")]
after: [("card0-HDMI-A-1", "On"), ("card1-Virtual-1", "On")]
went dark: ["card0-HDMI-A-1"]
test gamescope::tests::live_the_managed_hold_darkens_a_real_panel ... ok
The unmanaged `Virtual-1` is correctly untouched, and the test exercises the
double-acquire (reconnect) path too, so the toggle-safe release is covered.
cargo test -p pf-vdisplay 255 passed / 0 failed; clippy --all-targets clean;
fmt --check and check-docs-drift.sh clean. sway remains the one arm not verified
on glass — there is no sway box in the lab.
A 1440p60 Lutris session ratcheted 57 → 5 Mbps over ten minutes on a link that
never dropped a packet — no keyframe asks, no flushes, a flat decoder, and the
host granting every rate it was asked for. Two things did it, both in the
client's encode down-driver.
The thresholds were absolute durations calibrated at 120 Hz ("~half a frame
budget", "≈1.5 × a frame budget"). At 60 Hz one frame is 16.7 ms, so an ordinary
one-frame encode hiccup cleared the SEVERE tier and took the immediate ×0.7
where the same hiccup at 120 Hz (8.3 ms) never reached it — which is exactly the
asymmetry the field log shows against 1440p120 sessions on the same host and
client. Size them in the session's own frame budget instead, plumbed from the
negotiated refresh and re-read on a mode switch.
And the signal fired for a cause the rate cannot fix. It exists to find the
encoder's compute knee, where cutting the rate cuts the work; when encode time
is held up by a game saturating the GPU that premise is false, the backoff
changes nothing, and `on_ack`'s baseline re-seed erases the evidence that
nothing improved. So remember the level each encode-attributed backoff fires at:
two in a row that fire no lower mean the rate is not the lever, and the signal
disarms for the session. Same shape as NOOP_CLOCK_FLUSHES_TO_DISARM. Loss, OWD,
decode and keyframe signals keep their full power throughout, and the host's own
climb refusal stays the backstop for a genuine knee.
`exclusive` on a gamescope session meant "turn the box's own panels off", and
that only actually happened on two kinds of box: one running KDE (via
`org_kde_kwin_dpms`) and one running no desktop at all (via the DRM floor added
in the previous commit). A gamescope session on a **sway** or **Hyprland**
desktop got nothing — the desktop keeps driving its panels, and the DRM floor
cannot help because that compositor holds DRM master, so `SET_MASTER` is refused.
There is no cross-compositor DPMS protocol, so the module becomes a dispatcher,
each arm self-gating on its own IPC so a box only pays for the one that answers:
| desktop | mechanism |
|----------------|--------------------------------------------------------|
| KDE / KWin | in-process `org_kde_kwin_dpms`, then `kscreen-doctor` |
| sway (wlroots) | `swaymsg output <name> dpms off` |
| Hyprland | `hyprctl dispatch dpms off <name>` |
| none at all | `drm_dpms` — the CRTCs off over DRM |
| GNOME / Mutter | cannot be served (below) |
**`kwin_dpms` is renamed `panel_dpms`.** A module that darkens sway and Hyprland
should not be named after KWin, and this file has already paid for one stale
name: the comment authorising the DPMS skip on the other gamescope routes ("its
takeover already stopped the desktop") outlived the stop it named by three
commits and hid the whole defect. (The rename's sed also caught
`org_kde_kwin_dpms` itself — the vendored protocol's interface names, which are
not ours to rename — and those are restored.)
**DPMS, not the `disable` these backends already have.** Both wlroots and
Hyprland implement their OWN exclusive topology by disabling heads; that is
right when the streamed output lives on that compositor and has to become "the
desk", and wrong here — a gamescope spawn owns no output there, so disabling
would move the operator's workspaces and re-home their windows for a stream that
is not even on their compositor. It matters most on Hyprland, where this
module's own notes record that a disabled head has no clean undo: the only known
restore is re-reading the operator's whole config, which drops every runtime
override they set by hand. DPMS is a separate axis and round-trips cleanly.
Both arms reuse their backend's existing `heads_to_disable` filter with an EMPTY
`ours` — a gamescope session owns nothing to spare, but a concurrent wlroots
session's `HEADLESS-*` still must be spared or darkening blacks out that client's
stream. They address heads by NAME and report which ones actually changed, so the
re-light undoes exactly those.
⚠ **GNOME is a structural gap, not an omission.** Mutter exposes no DPMS to
clients; its own `exclusive` mechanism (`ApplyMonitorsConfig` omitting the
physicals) needs a virtual output of its own to keep enabled, which a gamescope
session does not have; and the DRM floor is refused because Mutter holds master.
The `warn!` now names that instead of saying nothing.
⚠ **The sway and Hyprland arms are NOT verified on glass.** The lab has Bazzite,
Nobara and SteamOS — no sway or Hyprland box. Their argv shapes and the
sibling-sparing filter are unit-tested and everything compiles clean, but the
commands themselves have not been run against a live compositor. Treat them as
unproven until someone streams from one.
Verified: `cargo test -p pf-vdisplay` 254 passed / 0 failed; clippy
--all-targets clean; fmt --check and check-docs-drift.sh clean. Re-ran BOTH
on-glass tests on the Nobara VM after the rename — the managed path falls
through KDE → sway → Hyprland → DRM correctly on a box with none of the first
three, and the panel still goes On → Off → On:
test gamescope::tests::live_the_managed_hold_darkens_a_real_panel ... ok
test drm_dpms::tests::live_the_panels_go_dark_and_come_back ... ok
The previous commit left Managed without a darken hold and wrote down a reason:
its display reports `DisplayOwnership::SessionManaged`, and `registry::acquire`
returns for anything not `Owned` ABOVE its `take_topology_restore()` pickup, so a
hold registered the way the bare spawn does would never be released — and a panel
dark after every stream is worse than one left lit.
That reasoning was right and the conclusion was wrong. Managed is the recommended
route, it gives the best experience, and it is the ONLY way to serve a client its
own virtual output at its own mode — so it is the route where `exclusive` most
needs to mean something. "No release path on the registry" is an argument for
putting the release somewhere else, not for skipping the feature.
Somewhere else is `do_restore_tv_session`: the one teardown every managed path
funnels through, and already the home of the drop-in sweep for exactly this class
of reason ("must not leak past an early return"). The release goes at the very
TOP of it rather than beside that sweep, because the SteamOS branch returns above
it. Safe there: releasing re-lights, and every path below either hands the box
back or deliberately keeps a headless session on a box with no connected display
— nothing lit to darken in that case anyway.
The hold is a bool, not a count, and that is load-bearing. The managed SESSION is
what gets darkened, not each connect: it outlives client disconnects (the point
of `MANAGED_SESSION`) and a same-mode reconnect reuses it warm without a
relaunch. Acquiring per connect would ratchet `kwin_dpms`'s refcount up with no
matching releases and pin the operator's panel dark for the rest of the host's
life. The edges are split into pure `managed_darken_{acquire,release}_edge` — the
same shape as `kwin_dpms::Holds` and for the same reason — so the balance rule is
unit-tested without a live compositor: reconnect takes no second hold, the
unconditional release is idempotent, a full cycle re-arms, and `extend` /
`SharedDesktop` still take no hold at all.
Verified on the Nobara VM (123, Fedora 44) in the takeover state, against a real
connected head, driving the actual managed helpers rather than the pure edges:
before: [("card0-HDMI-A-1", "On")]
during: [("card0-HDMI-A-1", "Off")] <- incl. a second acquire (reconnect)
after: [("card0-HDMI-A-1", "On")]
test gamescope::tests::live_the_managed_hold_darkens_a_real_panel ... ok
The bare-spawn on-glass test still passes alongside it. (`mutter::live_mutter_
create_drop` fails on that box and is unrelated — it needs a GNOME session.)
`gamescope.md`'s per-model table said Managed does not darken a desktop beside
it; it now says what both owning routes actually do, and that neither needs root.
cargo test -p pf-vdisplay 252 passed / 0 failed; clippy --all-targets clean;
fmt --check and check-docs-drift.sh clean.
`kwin_dpms` asks KWin for DPMS-off, which is the right answer whenever there is a
KDE desktop to ask. A box sitting in Game Mode has none — it runs gamescope and
no KWin — and that is *precisely* the deployment whose TV the operator wants
dark. So `exclusive` silently did nothing there, which is the field report.
Measured on the Nobara VM (123, Fedora 44) before writing any of this, because
the obvious cheaper answers all fail on real hardware:
* Getting the box's session out of the way is NOT enough. After the takeover
idles it, `card0-HDMI-A-1` sits at `enabled=enabled dpms=On` indefinitely —
when no client holds DRM master the kernel just keeps the CRTC configured.
That refutes `gamescope.rs:1573` ("left the Deck in a headless session with its
panel dark") as a general claim: that was a Deck's internal panel.
* `setterm --blank force` is unreachable: `/dev/tty1` is `crw------- root:tty`.
* The connector's `dpms` sysfs attribute is read-only even as root.
* `/sys/class/graphics/fb0/blank` DOES work (`dpms=Off`) — but needs root, and
the takeover deliberately stopped needing privilege in 0.31.0. Not worth
re-introducing a group requirement for.
What does work, unprivileged: `/dev/dri/cardN` carries a logind uaccess ACL for
whoever holds the active seat (`crw-rw----+`), and `SET_MASTER` succeeds while
nobody else is master — exactly the state the takeover has just produced. So
walk `GETRESOURCES`, `GETCRTC` each id, and `SETCRTC` with `fb_id=0,
mode_valid=0, count_connectors=0` on the ones actually driving something. The
connector goes `enabled=disabled dpms=Off`, the same end state `kscreen-doctor
--dpms off` reaches through KWin.
Two measured properties shrank the code. The darkness **survives DROP_MASTER**,
so mastership is handed straight back — a host still holding it would starve the
box's own gamescope when the restore relaunches its session, turning a dark panel
into a session that cannot start. And the re-light is **`close(fd)`**: the
kernel's last-close restores the console, so there is no saved mode to replay, no
restore that can half-fail, and crash safety is free (a dead host has its fds
closed by the kernel and the box lights up) — the same property `kwin_dpms` gets
from DPMS being non-persistent. Nothing to journal, nothing to sweep at startup.
`SET_MASTER` failing is also the natural guard for the Attach route: a card
already mastered by a live compositor is not ours, and darkening it would darken
the very picture being streamed.
Four ioctls, three `repr(C)` structs, one `unsafe` block. The ioctl numbers
encode their payload size (`0x40`, `0x68`), so the layouts are pinned by
`const _: () = assert!(...)` at compile time — a struct that drifts would have
the kernel read or write the wrong byte count on someone's TV — plus a test that
restates it greppably and pins the two field offsets the count/data-pass dance
depends on.
The on-glass test earned its place immediately. Everything else was green —
ABI tests, clippy, 251 unit tests, and a Python probe that had proven the ioctl
sequence itself — while the first Rust cut still left the panel lit: `darken_card`
closed its fd before returning and `darken` re-opened a fresh one to hold. That
close is the kernel's LAST close, which restores the console; the new fd held
nothing. It reported `darkened cards: ["card0"]` over a connector at
`enabled=enabled dpms=On`. The fd that does the work is now the fd that is held.
Verified on that VM with this exact binary, against a real connected head:
before: [("card0-HDMI-A-1", "enabled", "On")]
darkened cards: ["card0"]
during: [("card0-HDMI-A-1", "disabled", "Off")]
after: [("card0-HDMI-A-1", "enabled", "On")]
cargo test -p pf-vdisplay 251 passed / 0 failed; clippy --all-targets clean
(incl. the workspace's undocumented_unsafe_blocks deny); fmt --check and
check-docs-drift.sh clean.
The gamepad console has shipped since the arch split, but on Linux the only way
in was `punktfunk-session --browse` (or `punktfunk-client --browse`, which execs
it) on a command line — no way to find a mode. The WinUI shell has had both doors
for a while; this is the GTK half.
Three entry points, one destination:
* A gamepad button in the hosts header (`input-gaming-symbolic`), left of the
hamburger — the same placement WinUI gives it.
* "Console UI" in the main menu, so the mode has a searchable name and not just
a tooltip.
* `io.unom.Punktfunk.Console.desktop` — a second launcher shipped by the deb,
rpm, arch and flatpak packagings. It is what an app-grid search finds and what
gets added to Steam as a non-Steam game. `Exec=punktfunk-client --browse
--fullscreen` deliberately goes through the shell binary: that argv already
execs the session, and it is the command flatpak's Exec rewrite expects.
The in-shell launch is a `gio::Subprocess` — `wait_check_async` lands the child's
exit on the GTK main loop with no thread and no channel, releases `busy`,
refreshes the host list (the console can pair hosts), and banners a non-zero
exit. That last part is also how a session built without its `ui` feature
surfaces: it prints "--browse needs the console UI" and exits non-zero.
Which is why the Nix build does NOT install the new desktop entry — it compiles
the session `--no-default-features`, so that launcher could only ever print an
error. Noted in packaging/nix/README.md next to the existing Skia caveat.
Field report, Nobara, 2026-08-24: launching a game from the library with
`game_session=dedicated` and `topology: exclusive` left the operator's physical
screen on. Two independent causes, neither of which had a line in the log.
The first is ours and recent. `c2f5e91b` replaced the managed takeover's
display-manager STOP with an idle drop-in, deliberately, so the box keeps a DM
able to service the user's own "Switch to Desktop". That stop was also, as a
side effect, the only thing that took the box's own panel down. Nothing replaced
it, and the comment authorising the DPMS skip on this file's other routes — "its
takeover already stopped the desktop" — outlived the stop it named by three
commits, so the gap read as intentional. That comment is now the two reasons that
actually hold, written at the returns they belong to: Managed reports
`SessionManaged` and `registry::acquire` returns above its
`take_topology_restore()` pickup, so a hold taken there would never be released
(a panel left dark after every stream is worse than one left lit — `relight` is
written as "the last line of defence for a dark monitor" for that reason); and
Attach mirrors a gamescope that may be lighting the panel, so darkening it would
darken the picture being streamed.
The second is older and louder, and is what the report actually hit.
`stop_autologin_sessions` was reached only for a Steam launch — `is_steam_launch`
is `cmd.split_whitespace().next() == Some("steam")` — because freeing Steam's
single instance was the only requirement anyone had for it. But on a Game Mode
box that same session is the DRM master of the TV (`gamescope/heads.rs`), so a
NON-Steam library game left it running and the panel showed live Game Mode for
the whole stream. `exclusive` is a second, separate reason to want that session
out of the way, and it is now stated as one: `free_box_session_for_exclusive` is
pure and unit-tested over all four Steam x Exclusive combinations, including that
`extend` / the `SharedDesktop` preset ("never blank the real monitors") must
still leave the box strictly alone. Best-effort, unlike the Steam arm above it —
there it costs a dark screen, not the game, so it warns and continues.
Neither could be diagnosed from a log. `kwin_dpms::darken` is only ever reached
because the operator selected `exclusive`, so every decline is "you asked for
your screens off and they stayed on" — and the definitive not-KDE arm sat at
`debug!`. A box already in Game Mode has no KWin to answer DPMS at all, which is
precisely the box this fires on. It says so at `warn!` now, the same honesty
`relight` has always had for the dark direction.
`gamescope.md` claimed managed "deliberately takes the session over and blanks
the panel". It takes the session over; blanking is Topology's job and differs per
model, so the page now says which model can do what. The polkit/lingering block
above it is NOT stale — it is scoped to the restore path and pre-0.31.0 adoption,
and is left alone.
Verified: `cargo test -p pf-vdisplay` 249 passed / 0 failed, clippy --all-targets
clean, docs-drift gate clean. Not yet exercised against a live Nobara box — the
DPMS half cannot fire there by construction (no KWin in Game Mode), so what wants
measuring on the VM is whether releasing the DRM master leaves the connector dark
or merely blank-but-powered.
The gamepad shell's Bitrate picker has been seven rungs ending at 80 Mbps since the
console shipped, which is the ceiling a user just ran into — the GTK dialog beside it
has always gone to 3000 Mbit/s, so the two surfaces disagreed about what this machine
may ask for, and the console was the smaller of the two.
Three changes, one row:
- The ladder is 30 rungs, 1 Mbps to 2 Gbps. Tight at the bottom (1, 2, 3, 4, 5, 6, 8,
10, 12, 15, 20, 25 …), where one rung decides whether a thin link is watchable, and
coarse at the top, where a rung is noise. Rates at or above a gigabit read as Gbps.
- Y opens a typed rate on that row — digits, four of them, through the tray keyboard
(or SDL text input, and Steam's own keyboard on a Deck) exactly like the add-host and
pair fields. A goes on cycling the ladder everywhere, so the console's grammar is
unchanged; the field is what the ladder cannot be, which is every number in between.
- A rate that is not a rung now steps to its NEIGHBOUR. The generic picker snaps a value
it does not recognise to its first option, which on this row is Automatic: one nudge
threw away a rate typed here or set by the desktop spinner.
The desktop dialog gets the same complaint's other half: its spinner steps 1 Mbit/s
instead of 5, so 3, 4 and 6 are reachable without typing.
`Screen::edit_key` now takes the context, because this is the first field that commits
into the settings store when it closes rather than holding text for a later action row.
`installTap(onBus:bufferSize:format:)` validates a non-nil format against the
bus and raises an Objective-C exception on ANY mismatch. Swift cannot catch
that, so it reached the terminate handler and aborted the process — SIGABRT in
`AVAudioEngineGraph::InstallTapOnNode`, crashing macOS 0.31.0 at session start,
not at launch.
The format handed to the tap is necessarily read a moment earlier
(`input.outputFormat(forBus: 0)`), and on macOS the input can move underneath
it in that window: a device switch, a clock/rate change, or the
`kAudioOutputUnitProperty_CurrentDevice` swap `startCapture` itself performs two
lines before. The existing guard only rejected the 0 Hz / 0-channel case, which
is a different failure — a device that is absent, not one that changed.
Install with `format: nil` instead, which is the documented "use the bus's own
format" and makes the mismatch unrepresentable rather than merely unlikely.
The tap then has to follow the real format, so the rate-dependent pieces (mono
bus, resampler, both scratch buffers) move into a `MicChain` the tap rebuilds
when `buffer.format.sampleRate` differs — a chain pinned to a stale rate would
resample by the wrong ratio and pitch-shift the mic. That rebuild subsumes the
old grow-on-larger-quantum branch; the steady state still allocates nothing.
Tests cover the sizing arithmetic the rebuild rests on — including that
`staging` fits the UPWARD ratio, which silently truncates every packet on any
device below 48 kHz if it is sized for the input rate instead.
Second half of "the power menu does nothing during a stream", and an
independent fault from the sleep veto: on the takeover flavors that STOP
the display manager, the box is left with no active local session, and
that is what logind's power actions are gated on.
logind ships `power-off`/`reboot`/`suspend` as `allow_active: yes`.
polkit decides "active" from the caller's own logind session and, for a
caller that has none — every `systemd --user` unit, which is exactly what
the managed gamescope session is — falls back to the user's elected
DISPLAY session. logind elects that only from `user`/`greeter` class
sessions, never from the user manager's own, so stopping the display
manager removes the last candidate and all three actions drop to
`auth_admin_keep`: an interactive password prompt, put to a
non-interactive caller, on a screen that is switched off.
On SteamOS-like boxes that is the call being refused. Steam does not ask
logind for "Shut Down" at all — it writes $STEAMOS_STEAM_SHUTDOWN_SENTINEL
and exits, and gamescope-session-plus runs a plain `poweroff` once Steam
is gone. During a stream that wrapper is ours, in the session-less
transient unit.
Measured on Bazzite, 2026-08-24: the identical
`pkcheck --action-id org.freedesktop.login1.power-off` from a
`systemd --user` unit answers authorized with sddm up, and
`auth_admin_keep` with sddm stopped — and answers authorized again, in
that same stopped state, with this rule installed.
Scope it to the (shipped-empty) `punktfunk` group, which is the same
group the takeover's own root helper authorizes on: a takeover that stops
a display manager cannot work without that helper, so this grants to
exactly the population the fault reaches. The three actions are the three
entries in Steam's power menu; the `-multiple-sessions` and
`-ignore-inhibit` variants are deliberately left out.
Since b7a00137 the host has held a logind `sleep:idle` inhibitor in BLOCK
mode for the whole length of a stream, so a passive (video-only) viewer
could not have the box suspend out from under them. A block lock on
`sleep` refuses EVERY suspend, though, not just the one an idle timer
asks for: "Sleep" in Steam's Big Picture power menu reaches logind as the
same `Suspend()` call, and logind answers it with
Operation inhibited by "Punktfunk" (PID …), reason is "a client is streaming".
Nothing in that UI surfaces a D-Bus error, so the menu entry simply does
nothing — for as long as anyone is watching the box. Reproduced on a
Bazzite host, 2026-08-24, by taking the same lock by hand.
Hold the veto only while the stream is QUIET. Any client input on either
plane drops it synchronously — releasing is a close(2) on the inhibitor
fd, no round trip, so a Sleep press cannot race it — and it is re-taken
only after 30 s of silence. That is the line the original justification
already drew ("remote INPUT resets the compositor's idle timers, but a
video-only viewer sends none"): a person choosing Sleep is, by
definition, sending input, and a passive viewer never does. The case the
lock was written for is unchanged — 30 s of nothing and the veto is back.
Both planes stamp the clock at their single input entry point: the native
input thread's channel recv (before the grant tests — a denied event
still means a person is there) and the GameStream control plane's three
decode arms, past the keepalive gate, because a keepalive is the one
thing a passive viewer does send.
The v0.31.3 CHANGELOG recorded this cut as a decision left open, on the same
reasoning v0.31.0 used for 0.1.5: a plugin resolves `@punktfunk/host` from the
registry, so types sitting in `sdk/` reach nobody until a version carries them.
#374 added `PATCH /clients/{fingerprint}`, `RenameClient` and
`PairedClient.label` to the management API and regenerated the client for them —
so without this cut the route exists on every 0.31.3 host and no plugin can call
it in a typed way.
ONE FILE is the whole diff since sdk-v0.1.5: `sdk/src/gen/punktfunk.ts`. It is
larger than the feature because regenerating it from the UNCHANGED committed spec
already produced a ~700-line diff — the checked-in copy had drifted from its own
pinned generator, and nothing in CI regenerates or verifies it (unlike
api/openapi.json and include/punktfunk_core.h, which are both gated). #374 landed
the clean regeneration rather than hand-patching generated code, and this cut
publishes it.
`SDK_VERSION` moves with `package.json`. It is a hand-maintained constant — the
build sets `rootDir: "src"` so it cannot import the manifest, and the runner ships
as one bundled `runner-cli.js` with no manifest beside it — and the runner
compares it against the SDK installed in the plugins tree to decide whether to
reinstall. Shipping 0.1.6 with the constant still reading 0.1.5 would publish the
types and then never deliver them. `version.test.ts` gates exactly that, which is
also what sdk-publish.yml's "Tag matches package version" step re-checks against
the tag.
GATES, all four steps sdk-publish.yml runs, in order and locally:
`bun install --frozen-lockfile --ignore-scripts` clean, `bun run typecheck`
clean, `bun test` 83 pass / 0 fail / 191 expect() calls across 12 files (the same
83 the 0.1.5 cut reported), `bun run build` clean. Nothing but the two version
sites and the two release documents is touched — no dist/ or lockfile churn
reached the tree.
`@punktfunk/plugin-kit` is deliberately NOT re-cut: nothing under plugin-kit/ has
moved since 0.4.4, which stays the registry's `latest`.
Tag `sdk-v0.1.6` on the merge commit, alongside `v0.31.3`. The two version
independently by design — sdk-publish.yml triggers on `sdk-v*` and the app's `v*`
tags never republish the SDK — so the shared commit is a convenience, not a
coupling.
41 commits since v0.31.2 (26 non-merge). Cut from origin/main f5931650 (#385
merged, main green).
THE NUMBER: a patch. One versioned surface moves and it moves additively — the
management API gains PATCH /clients/{fingerprint}, the RenameClient schema and
PairedClient.label, none of which existed before, so nothing that consumes the
API today changes shape. Everything else is where v0.31.2 left it: WIRE_VERSION
2, C ABI 25 with include/punktfunk_core.h showing NO diff against the v0.31.2 tag
(second release running), driver protocol 6 / min 3 with pf-driver-proto
unchanged, gamepad channel 3, plugin index schema 1, host event schema 1,
gamescope +pfhdr8 with no new patch files, SDK 0.1.5 and plugin-kit 0.4.4 both
untouched. Two feat commits (#374, #384), both additive; v0.31.1 carried two
feats as a patch on the same reasoning.
THE SHAPE: the faults share a family resemblance — a session degrading or ending
against something ordinary that nothing was checking. Steam's pre-launch trees
latching the game lease and their exit then read as the game's (#372); a
fullscreen game mode-setting the virtual display under both stream loops (#373);
the forced-keyframe coalesce window measured in frames rather than time (#377);
an Android TV negotiating the refresh its own console pin installed rather than
what the panel outputs (#378); a startup capacity probe large enough to
black-hole the link it was measuring (#379); a hand-back that never verified the
panel came back (#375); a half-minted audio devnode nothing afterwards
recognised (#381); and a failed compositor build that unlinked the working one it
never replaced (#382). Plus two Android input/present fixes (#376, #380), the
console's per-frame cost and its new resolution switch (#384, #385), one feature
(#374), and CI (#370, #383).
TWO ENTRIES WORTH THE READER'S ATTENTION, both recorded as such:
* #375 ships WITHOUT a reproduction. Five scenarios across both distro families
on real VMs all recovered cleanly and the first proposed mechanism was
disproved on glass, so it closes the gap that lets any trigger end as a dark
panel rather than guessing at one.
* #380 is re-implemented from #371's diagnosis, and #371 is NOT merged. All
three faults were real and correctly identified; each fix as sent reached
further than the hardware that needed it. The notes credit the diagnosis.
DOCS FRESHNESS, per docs/releases/README.md step 1: #379, #380 and #384 carried
their own docs-site updates (configuration.md, input.md, client-settings.md). The
one fact left owed was naming a Moonlight device, whose canonical home is the
"Managing paired devices" section of docs-site/content/docs/pairing.md — a
paragraph goes there. No new PUNKTFUNK_* variable this cycle
(PUNKTFUNK_RECOVER_SESSION_CMD is pre-existing and already documented in
configuration.md and gamescope.md), no new host subcommand, and no install
command, repo URL or port change, so data/platforms.json and the website's
vendored copy need nothing.
VERIFIED HERE: scripts/ci/check-docs-drift.sh clean; scripts/ci/check-docs-links.sh
clean; the android.yml Play notes gate run verbatim, 444/500 characters and unique
against every other release's file; both openapi copies cmp identical and stamped
0.31.3; cargo fmt --all --check clean; cargo audit clean over all five Rust
lockfiles (h2 fixed in the commit below this one); cargo about --fail clean on the
host workspace; git diff v0.31.2..HEAD on include/punktfunk_core.h and on
crates/pf-driver-proto both empty, which is the direct evidence for those two
version rows; Cargo.lock's 36 workspace version strings moved with Cargo.toml;
notes voice scan clean (zero backticked terms above ## For developers) and the
CHANGELOG link pinned to src/tag/v0.31.3.
NOT RUN HERE, and why: any punktfunk-host build, clippy or cargo test — the host
does not compile on macOS at all, and CI covers it; the web/ and docs-site/ bun
builds — nothing under web/ is touched by this commit and the docs-site edit is
prose in an existing .md; the Android unit tests — nothing here touches Kotlin.
LEFT AS A DECISION, not made here: sdk/src/gen/punktfunk.ts changed in #374 (a
clean regeneration that also absorbed ~700 lines of pre-existing drift) but
@punktfunk/host is not re-cut, so the registry's 0.1.5 has no types for the new
route. Cut sdk-v0.1.6 if anything outside this repo needs them.
`cargo audit` on the root lockfile went red on 2026-08-17, when RUSTSEC-2026-0258
was disclosed against h2 <= 0.4.15 (unbounded empty DATA frames; fixed in
0.4.16). audit.yml's cargo-audit job is BLOCKING and fires on every Cargo.lock
change, so the 0.31.3 version bump in the next commit would have taken it red on
merge regardless of this advisory's own timing.
h2 is transitive — no manifest in the workspace declares it — so this is a
lockfile-only change.
MINIMAL ON PURPOSE. `cargo update -p h2` reports "Locking 1 package" but also
rewrote nine unrelated entries from `windows-sys 0.61.2` to 0.52.0/0.59.0,
gratuitous resolver drift that would have changed what the Windows builds compile
against for no reason. That was discarded; the two h2 lines are applied directly
instead, and `cargo metadata --locked` accepts the result with nothing else
moving — which is the proof the resolver needed none of the rest.
VERIFIED: `cargo audit` over all five Rust lockfiles. The root one is now clean;
the other four already were. The two lines cargo-audit still prints
(`audiopus_sys`, `paste`) are *unmaintained* warnings, already allowed via
.cargo/audit.toml, and do not fail the job.
NOT REGENERATED, deliberately: THIRD-PARTY-NOTICES.txt still records h2 0.4.15.
scripts/gen-third-party-notices.sh walks the dependency closure of the machine it
runs on, and on macOS it DROPS nine crates — the rusqlite / libsqlite3-sys /
fallible-iterator / hashlink cluster, 575 -> 566 — because they are gated to
platforms this Mac is not. Committing that would remove attributions a Linux or
Windows build genuinely links, which the script's own header calls a legal
regression rather than an untidiness. Regenerate on Linux. Nothing in
.gitea/workflows diffs the checked-in copy, and build-deb.sh /
pack-host-installer.ps1 / punktfunk.spec / pack-msix.ps1 each regenerate it on
their own platform, so the shipped packages are accurate and this is cosmetic
drift in the in-repo copy only.
`platform_row_split_hides_only_the_other_platforms_concepts` pins the exact
ordered set of rows the desktop does not show, which is the point of it — a row
that silently changed platform is the regression it exists to catch. The new
switch is Android-only by design, so the expected list grows by one, between the
Controllers action row and the console-UI switch (it sits under Reduce motion,
earlier in the Interface tab than either).
Caught by CI on both the Linux and Windows legs, which run this crate's tests;
the row-COUNT assertion next to it was already updated and passed.
The console draws at whatever resolution the panel hands it, and on a 4K
television or projector that is four times the fragment work of 1080p on a
graphics chip built to decode and composite video rather than to draw a moving
interface. The reporter's two devices — a Fire TV Stick 4K Max and a Valerion
projector — are both premium products and both exactly this shape: the money
is in the light engine and the panel, and the SoC is a TV part. A premium 4K
box is MORE likely to want this than a cheap 1080p stick, which never had the
extra pixels to begin with.
So: an off-by-default switch in the controller-optimized settings, directly
under Reduce motion, because the two are the same kind of bargain — give up
some fidelity, get a smoother console. On, the buffer's long edge is capped at
1920 with `SurfaceHolder.setFixedSize` and the compositor scales it up for
free. Text goes a little softer. Nothing else changes.
Two things this had to get right, neither of which is obvious from the call:
`setFixedSize` shrinks the BUFFER and not the VIEW. Everything that speaks in
surface pixels therefore has to be scaled to match — the safe-area insets, the
design-unit scale, and the pointer coordinates, which a mouse still reports in
view pixels and which would otherwise land the cursor at twice its true
offset. The scale factor is one number applied to both axes, so the aspect
ratio survives exactly and no layout can stretch.
And the buffer is sized from the SurfaceView's own laid-out size, reported
back through `onSizeChanged`, rather than from `displayMetrics`. The two
normally agree, but `displayMetrics` has a long history of disagreeing with a
view's real size by a system bar depending on the version and on who is
hiding what, and a buffer whose aspect ratio does not match the rect it is
scaled into is a stretched interface. "Normally agree" is not something to
hang picture geometry on.
The pointer listeners are installed in `AndroidView`'s `factory`, which runs
once, so the factor reaches them through `rememberUpdatedState` — captured
directly it would freeze at its first-composition value (1, before any layout
has reported a size) and a mouse would be wrong for the rest of the session.
The same reason `platformUp` is already held that way.
⚠ This is the INTERFACE only and shares nothing with the stream. Picture size
is `effectiveMode`, off `Display.mode.physicalWidth` — a physical display
mode, not any surface's buffer — and picture scaling is the separate
`renderScale`. The two `SurfaceView`s are different views and this is the only
`setFixedSize` call in the client. The name keeps "interface" in it, and the
docs entry ends by pointing at Resolution and Bitrate, so that nobody turns
this on expecting a sharper stream.
skia-bindings pulls ~19 MB of prebuilt Skia from inside its build script with a
bare curl and no retry, and swallows a failed download into a from-source Skia
build the CI containers cannot complete — so a dropped transfer surfaced as
"Clippy (Android target) failed" with the real cause 1,800 lines up.
A retrying curl shim first on PATH covers it (skia-bindings already resumes and
caches the part-file, so a retry continues the transfer). The prose rule in
android.yml's env block is now a gate that fails on STARTING A FULL BUILD.
A field report of a sluggish console UI on a Fire TV Stick 4K Max and a
Valerion projector. The Skia shell is faster than the Compose one it replaced
per unit of work; it was doing far more work than anyone had counted, and all
of it on every frame whether or not anything had changed.
Four costs, none of which change a pixel:
`Fonts::paragraph` built a `ParagraphBuilder`, added its text and called
`layout()` on every call — the whole shaper, HarfBuzz and line breaking and
font fallback, for every string on screen, sixty times a second. It is now
built once per distinct (text, shape, weight, size, width, colour) and kept.
Position is deliberately not in the key, so a shelf that scrolls and a screen
that slides both re-use what they already shaped. Cold entries are dropped
once the map passes its ceiling, by the two frames that last drew them, so the
live set is what is on screen and paging a large library cannot grow it
forever. The loose `(TextAlign, Option<usize>)` pair became a `Para` tag on
the way past: those two were never independent, and it is half of a hash key
now.
`LayerEnv::paint` raised an unbounded `save_layer` unconditionally — including
on the settled path, where alpha is 1, the scale is 1 and the slide is 0. That
allocates an offscreen the size of the whole SURFACE and composites it back,
to apply an alpha of one, on every frame the console sat still. Skia does not
elide it: `SkCanvas::saveLayerAlphaf` forwards alpha >= 1 straight to
`saveLayer(bounds, nullptr)`, whose only early-out is an empty clip. On a 4K
panel that is a 33 MB render target per frame, against a Skia budget that is
64 MB on a 2 GB box — so it was evicting real work to do nothing. Dropping it
is pixel-identical rather than close: nothing in this crate draws with a blend
mode other than `SrcOver`, `SrcOver` is associative, and there is no LCD
subpixel text to gain or lose an isolation. `screens::home` had already
learned this one tile-deep; this is the same fix one level up.
The toast's layer was unbounded too, for a 34 dp pill. Everything inside it is
inside the pill, so it takes the pill's rect and some slack for the hairline.
`draw_clipped` measured its ellipsis fit by allocating a `String` per
character, for every over-long title on screen, every frame. It measures out
of a stack buffer now. The controller chip's string stopped being rebuilt
sixty times a second to say the same thing.
On the Android host, the render thread now takes the same priority lift the
decode thread has taken all along (`-8`, a band below the stream's `-10`, so
the two do not compete when the console is up mid-session). At default nice, a
TV box's scheduler is free to park the console's frame loop on a little core
behind background work, which reads as a UI that lags the remote.
And the thing that made this hard to answer in the first place: the console
logged its GLES version and its cache budget and never its render resolution
or its frame cost, so "it feels sluggish" could not be triaged from a log
bundle at all. It now names the surface size when it wraps one, and reports
mean and peak draw time once a minute. The window is timed around the draw and
not the swap — `eglSwapBuffers` blocks on vsync, so wall-clock per iteration
is always the panel period and says nothing.
What is deliberately NOT here is the biggest single lever on a 4K box: capping
the console's render resolution. That is a real quality trade on a panel
someone bought for its resolution, and it is not this commit's to make.
A host that died mid-mint left an orphan devnode and the next start minted a
duplicate; the registry stamp route reached for the Render hive even for capture
endpoints. Both reproduced and verified on the .173 Windows lab box.
The Recording-tab hang that prompted the investigation is NOT fixed — it did not
reproduce on .173, and nine candidate mechanisms were ruled out by direct
measurement. See the PR body for the disproof table.
scripts/ci/retry.sh already wraps every single-shot network call in CI, for the
reason documented there: the runner box runs many jobs in parallel and its
network sheds packets under that load. One of the largest fetches in this
workspace was never wrappable that way - skia-bindings pulls ~19 MB of prebuilt
Skia per target from INSIDE its build script, with a bare 'curl -sS -f -L' and
no retry (build_support/binary_cache/utils.rs).
Measured on main 2026-08-22, android job:
DOWNLOAD AND INSTALL FAILED: curl error code: "18"
curl stderr: "curl: (18) end of response with 17054400 bytes missing"
2 MB of 19,057,024 arrived before git.unom.io closed the connection; the same
asset pulls fine from a dev box. skia-bindings then swallowed it - its
try_prepare_download falls through to STARTING A FULL BUILD, a from-source Skia
build the CI containers carry no deps for - so the job surfaced as
'Clippy (Android target) failed' with a Gradle stack trace and the real cause
1,800 lines above it.
* A retrying curl shim first on PATH is the only lever that reaches inside a
build script, and the cheapest correct one: skia-bindings already passes
'-C -' and caches the part-file under OUT_DIR/.cache, so a retry CONTINUES
the truncated transfer rather than restarting it. --retry-all-errors is
load-bearing: a truncated transfer is not an HTTP status, so plain --retry
would let error 18 through.
* Wired into android.yml and both ci.yml rust jobs - pf-console-ui pulls
skia-safe too, so ci/rust downloads Skia on any target-cache miss.
* The rule android.yml's env block states in prose ('Every ABI's log must show
DOWNLOAD AND INSTALL SUCCEEDED') is now a gate that fails the job on
STARTING A FULL BUILD, so a dropped prebuilt can never masquerade as a lint
failure again.
Caught on the SteamOS lab VM while verifying the previous commit end to end. With
libx11-xcb-dev added the build finally COMPLETED (652/652, banner "3.16.25-21-gb71a56c
+pfhdr8") — and then failed its on-glass check:
punktfunk-gamescope: error while loading shared libraries:
libdisplay-info.so.2: cannot open shared object file
Self-inflicted: the previous commit also took libdisplay-info-dev from the CI image's
list. gamescope vendors libdisplay-info as a submodule, but it is NOT in
force_fallback_for, so meson preferred the system lib the moment the build box had the
-dev package and linked it SHARED. SteamOS ships no libdisplay-info.so.2, so the binary
built, installed and printed its +pfhdr banner inside the distrobox and could not start
on the machine it exists for.
This is verbatim the wlroots trap the same comment block already documents ("starts fine
on the build host and dies with libwlroots-0.19.so ... anywhere else"), so it gets the
same remedy rather than a second one: libdisplay-info joins force_fallback_for. "Just
don't install the -dev package" does not hold — Debian, Fedora and Arch all have it and
anything can pull it in transitively, and the failure is silent right up to the on-glass
check that build-gamescope.sh happens to run.
Also drop libdisplay-info-dev from the Deck list (pointless once the fallback is pinned)
and record why that list must NOT be synced with ci/gamescope-trixie.Dockerfile: the CI
list targets a .deb that runs on Debian, this one cross-builds in trixie for SteamOS
glass. libx11-xcb-dev and libxkbcommon-x11-dev stay — SteamOS ships both sonames.
The on-glass check did its job here: it caught the bad binary, removed it and left the
box SDR rather than letting the host promise HDR it could not deliver.
write_stamps falls back to a raw-registry write when the property store
denies it. That fallback built its path from MMDEV_RENDER_PATH unconditionally,
so stamping the minted microphone's CAPTURE endpoint reached for
...\MMDevices\Audio\Render\{capture-guid}\Properties - a key that cannot
exist. RegOpenKeyExW then failed, write_stamps returned the error, and
stamp_identity degraded to 'keeps the driver's default name'.
Invisible to the pad program, whose endpoints are render-only, and invisible on
any box where the property store route succeeds (both field logs show
registry=[] on every stamp line, so neither reporter ever took this path). It
only bites where the property store is denied - exactly the boxes the ACL
repair exists for.
The hive now follows the direction the endpoint id encodes, with render as the
default for anything unrecognised. Unit-tested.
ROOT CAUSE of "HDR stopped working after updating to 0.31.2" on a Deck source install.
Two defects, one symptom.
1. scripts/steamdeck/build-gamescope.sh has been UNBUILDABLE since 2026-08-13, when
3ac4548c turned `-Denable_gamescope_wsi_layer=true` on. The layer needs x11-xcb, which
Debian splits into its own libx11-xcb-dev; the distrobox apt list — last touched
2026-07-31 — never got it. MEASURED on debian:trixie against that list verbatim,
gamescope at the pinned 5fb8dce4:
Run-time dependency x11-xcb found: NO (tried pkgconfig and cmake)
src/layer/meson.build:3:14: ERROR: Dependency "x11-xcb" not found
`meson setup` exits 1 with the list as it was and 0 with libx11-xcb-dev added, and
build-punktfunk-gamescope.sh treats a missing layer as a hard error, so the whole build
fails. ci/gamescope-trixie.Dockerfile walked into the identical trap one release later
(1b28a7f7, v0.28.1) and asserts x11-xcb at image build; this list never got the same
fix. Debian-family only: Arch's libx11 and Fedora's libX11-devel carry x11-xcb.pc.
xkbcommon-x11 and libdisplay-info measured absent too, and are added with it.
2. The build-failure branch then called `unwire`, deleting PUNKTFUNK_GAMESCOPE_BIN from
host.env. A failed build REPLACED NOTHING — the previously installed binary is still on
disk and still passes `verifies`. So a rebuild that never landed took HDR away from a
box that had been streaming it minutes earlier. The script warns into a log nobody reads
and exits 0, the update reports success, and the host then resolves the distro's stock
/usr/bin/gamescope at patch level 0 and fixes the session at 8-bit SDR in the Welcome —
which the punktfunk/1 handshake cannot take back.
A verifying binary now stays wired (and a box a previous run of this bug unwired gets
re-wired). `unwire` happens only where the binary itself fails its on-glass check, which
is the branch that also removes it.
Also promote the "no +pfhdr marker" line from DEBUG to INFO. The handshake already reports
capture_supports_hdr=false at INFO while the one line saying WHY sat a level below it —
that asymmetry is what made this field report expensive to answer.
Verified: the meson reproduction above (exit 1 -> exit 0); all three added package names
resolve on trixie and satisfy their pkg-config modules; the four states of the changed
branch exercised in isolation (working binary stays wired, stock/missing binary unwired,
previously-unwired box re-wired). Not verified on real SteamOS glass — the lab VM was
unreachable from this machine.
Minting an audio devnode is two PnP steps: SetupDiRegisterDeviceInfo makes it
real and bindable, then the owner marker goes into Device Parameters. A host
that dies between them - the 0.30.0 TLS-destructor abort did exactly this,
five times on one field box - leaves a registered, driver-bound, endpoint-
serving devnode carrying no marker.
Nothing resolved it afterwards. find_role_devnode matches on the marker, so
the next pass minted a SECOND devnode and the orphan stayed: a duplicate
'Punktfunk Speakers'/'Punktfunk Microphone' in the Sound zoo that no uninstall
removed, because devnode_cleanup is marker-matched too. A field box showed
exactly this shape - 'Punktfunk Speakers (3- Punktfunk)' beside an unstamped
'Punktfunk Speakers (4- Steam Streaming Speakers)' - in every wiring plan it
logged. Reproduced on .173 against the shipping 0.31.2 binary by clearing the
marker: ROOT\MEDIA\0005 was minted and 0004 was abandoned, still active and
still serving two live Punktfunk Microphone endpoints.
* minted.rs adopts before it mints. An unmarked ROOT\MEDIA\NNNN devnode
carrying the role's Steam hardware id is re-marked and reused, so the
endpoint GUID survives and no device-change broadcast is paid.
* devnode_cleanup sweeps the same shape, so orphans already on a box go at
uninstall instead of outliving the product.
The instance prefix is what keeps both off Valve's own devices: Steam's
devnodes carry these hardware ids and are ROOT-enumerated too, but live under
ROOT\SteamStreamingSpeakers\* / ROOT\SteamStreamingMicrophone\*. Only
ROOT\MEDIA\* can come from our SetupDiCreateDeviceInfoW(DICD_GENERATE_ID).
is_abandoned_mint carries that rule with unit tests.
Reproduced on both Bazzite 44.20260818 and Nobara f44: a host killed mid-takeover
left the box's Game Mode running `/usr/bin/sleep infinity` with the panel lit and
blank, permanently. Fixed and re-verified on both boxes against canary
0.32.0-0.ci15147.gc63e8cee, with no regression to the ordinary disconnect.
The hand-back also measures its own outcome now instead of trusting a systemd job
status, so any other route to a dark panel is caught and escalated rather than
logged as success.
Three defects reported against a Bluetooth DualSense on a Fire TV Stick 4K Max,
re-implemented from #371's diagnosis. #371 itself should not be merged: all
three problems are real, but each fix lands somewhere that breaks more hardware
than it repairs.
1. Some buttons never reach the stream. Fire OS is reported to tag certain
DualSense buttons SOURCE_KEYBOARD even though the keycodes are standard
BUTTON_*, and MainActivity's `event.isFromSource(SOURCE_GAMEPAD)` gate then
drops them. The event's source class is the platform's per-event guess; the
DEVICE's is the fact. New `MainActivity.fromPad` widens to the device — but
ONLY for `KeyEvent.isGamepadButton` keycodes. That exclusion is the whole
safety of it: DPAD keycodes are a keyboard's arrow keys and BACK is a
remote's way out of the stream, and both share their keycodes with a pad.
`Gamepad.isPad` is untouched (source-class only) and no vendor-id or
device-name matching is added anywhere — the field report records both pads
being IDENTIFIED correctly; only their button positions were wrong.
2. Touchpad click and Mute were dropped. Both have wire bits (BTN_TOUCHPAD,
BTN_MISC1) and no Android keycode, so GENERIC_SONY's `0x13d`/`0x13e` rows now
borrow BUTTON_15/BUTTON_16 to carry them into `buttonBit`. Inside
GENERIC_SONY and nowhere else: `0x13d`/`0x13e` are BTN_THUMBL/BTN_THUMBR —
L3 and R3 — in the standard Linux mapping, and they mean touchpad and mute
only inside the straight-through report order a driverless pad uses. A row in
SONY_MODERN, or an override above `padMap(dev)`, costs every Xbox pad, Switch
Pro, 8BitDo, Steam Deck and hid-playstation DualSense both stick clicks.
`correct()`'s `genericKeyCode` guard stays exactly as it was.
3. Mute toggles the mic — once per press, and only on a pad that has one.
Edge-triggered through the existing `completesChord` as the one-button chord
it is: `onButton` still calls `slotButton(down = true)` on auto-repeat, so an
unguarded check would flap the mic for as long as the button is held. Gated
on a new `Slot.hasMuteButton`, because BTN_MISC1 is the wire's misc/QAM bit
and `Sc2Device` puts a Steam Controller 2's QAM button on it — "any MISC1"
would mute the microphone on every QAM press. Resolved at slot open from what
each path knows: the report order for an InputDevice, the declared kind for a
capture link. Under the "local" system-button policy a real mute button is
exempt from the early return (that policy means the press stays with this
device, which is exactly what the toggle does) and loses only its wire send;
every other system button behaves as before.
Tests: `every other pad keeps L3 and R3 on those scancodes` is the regression
that matters and fails on #371's shape (verified by reproducing it). Plus the
rewritten touchpad/mute assertions, the guard's negative path — untested in
either direction until now, because every existing case fed `correct()` the
keycode `Generic.kl` would have produced — and the mute button's edge rule in
GamepadChordTest. `an Xbox pad at the standard positions keeps X, Y and its
shoulders` is kept.
Not yet verified on hardware: no Fire TV Stick 4K Max or DualSense here, and no
adb device attached. §1's premise (the SOURCE_KEYBOARD tagging) is therefore
unconfirmed — the change is a no-op if it does not hold.
Field reports on 0.31.x, Bazzite and Nobara: after disconnecting, the box's own
physical screen stays black.
I could not reproduce it (PR #375 has the full negative write-up: five scenarios
across both distro families on the real VMs, all recovering cleanly, and the
mechanism I first proposed disproved on glass). So this does not guess at the
trigger. It closes the gap that lets ANY trigger end as a dark panel, and fixes
the one black-screen path I could prove.
## The restore never checked its own work
`do_restore_tv_session` issues a lifecycle verb and logs what systemd said about
the JOB. "The job succeeded" and "the box shows a picture" are different
questions, and nothing in this file has ever asked the second one — the restore
walks away the moment the verb returns, so every way the box can end up dark
looks identical to success in the log.
So measure it. After the hand-back a detached watcher polls
`detect_active_session()`, whose `None` means no compositor of our uid is running
at all — exactly the symptom. If the box is still dark 25 s later it climbs a
ladder of remedies, each measured on both images (Bazzite 44.20260818, Nobara
f44, 2026-08-22):
1. STOP the autologin unit. Its login session's script is parked on
`systemctl --user --wait start <unit>` on both images, so a stop releases that
wait, the session exits, and `Relogin=true` logs back in — starting the unit
inside a session with a seat. `stop`, not `restart`: a restart does NOT
release the parked waiter (measured), which is why it cannot rescue a box the
ordinary restart already failed to bring back.
2. Restart the display manager — what the pre-0.31.0 takeover did on every
disconnect, and proven on the Bazzite VM to return the box to game mode.
3. `PUNKTFUNK_RECOVER_SESSION_CMD`, then an ERROR naming the command a human has
to run.
Detached, and that is load-bearing: the restore holds `RESTORE_FLIGHT`, which a
reconnecting client must take before it can re-take the box, so watching for up
to a minute while holding it would put that wait in front of every reconnect.
The watcher also stands down the instant `takeover_live()` says a new takeover
armed — the box belongs to that stream now, and a remedy fired into it would be
a fresh bug. It runs after `clear_takeover()` so that check means "a client
reconnected" and not "our own takeover has not been filed yet".
Skipped on the shutdown path: `restore_takeover_now` runs inside `native.rs`'s
20 s `SHUTDOWN_RESTORE_GRACE`, and spending that grace watching would cost the
hand-back rather than check it. What covers a shutdown that left the box dark is
the next host start — which this commit also makes true.
## A crashed host left the box's game mode asleep, provably
`restore_takeover_on_startup` sweeps a leftover idle drop-in off the box and logs
that the box's "own Game Mode session would have started and then done nothing".
Removing the FILE does not touch the unit RUNNING under it: its `ExecStart` is
still the sleep, so it sits `active` drawing nothing. Nothing below that sweep
restarts it either — the takeover file may be absent, unparseable, or fail
`takeover_state_is_live`, and all three exits leave the box on a dark panel with
its game mode "running". Any host killed mid-takeover (SIGKILL, OOM, a yanked
update) lands exactly there, and it survives until someone reboots.
`hand_back_idled_units_after_crash` restarts those units, gated on the box
actually being dark so a user already in game mode or on a desktop is never
bounced, and only for ACTIVE instances — under a just-removed idle drop-in,
active means "running the sleep".
## Not changed
The `restart` verb on the ordinary restore path. It works on both distros
(measured), and 0.31.0 chose it deliberately for the idled unit. The `stop` idea
survives only as escalation rung 1, where it runs after the proven path has
already failed.
`listed_autologin_units` is factored out of `stop_autologin_sessions` so both
callers share it, and its column parsing — which decides whether a live gaming
session can be told from a dead leftover — finally has a test against real
`--plain` output from both images.
The startup link-capacity probe burst at a flat 2 Gbps on the reasoning that it
must measure the link and not itself. That reasoning is obsolete: the ABR
already clamps the measured ceiling to `stream_cap_kbps` (what this session's
mode + codec could plausibly use), so every bit measured above `cap / 0.7` is
discarded the moment it lands. The height bought a number nothing reads, and
paid bufferbloat for it — a constrained Wi-Fi link can black-hole under it
(measured on webOS: a 6 s probe timeout delaying first video to 14 s, and a
"successful" probe still reporting send_dropped=20211; the same shape is now
reported on a Fire TV Stick 4K Max).
Derive the target instead: `stream_cap_kbps × 2`, capped at the old 2 Gbps.
×2 is the smallest multiplier that can still prove the cap (the ceiling is
`delivered × 0.7`, so proving it needs `delivered ≥ cap × 1.43`), so this can
never cap anyone — a session whose mode justifies a high ceiling asks for a
high target by itself, and a mode `stream_ceiling_kbps` declines to size still
gets 2 Gbps. Deliberately not a platform `cfg!`: the constraint is the
session's, not Android's, and webOS has the same bug.
Second half of the black screen: if the burst takes the first keyframe down
with it, nothing re-requests one and the client sits on black until an
unrelated recovery path happens to fire. Ask for a keyframe at probe end when
no frame completed across the burst — compared against the count snapshotted
at the burst's leading edge rather than against 0, so it also covers a
mid-session embedder speed test that kills a running stream. One request per
probe, through the control task's coalescer, so it cannot IDR-storm.
`PUNKTFUNK_ABR_PROBE_KBPS` and its `> 0` filter are unchanged.
Field report: on Android TV / Fire Stick, latency explodes whenever the client's
refresh differs from the host's, and setting the refresh by hand is the only
workaround.
The client was manufacturing that mismatch itself, in three steps:
1. `MainActivity.onCreate` pins the panel to its highest-refresh mode for the
console UI (`setConsoleHighRefreshRate(true)`) — unconditionally, TVs
included. That pin exists for phone refresh governors (Nothing OS's LTPO
logic among them) which cap third-party apps at 60 Hz. No TV has one.
2. At connect, `nativeDisplayMode` resolves "Native" refresh from
`display.mode` — which now reports the mode the MENU pinned, not the TV's
real HDMI output. So the session negotiates (say) 120.
3. `StreamScreen` releases the pin again on TV, by design: there the decoder's
own `setFrameRate(CHANGE_FRAME_RATE_ALWAYS)` governs the HDMI mode. The
panel falls back to 60 while the host is already serving 120.
A 120 fps stream on a 60 Hz output, by construction, on exactly the two form
factors in the report. Picking a refresh explicitly is precisely what bypasses
step 2, which is why that is the workaround people found. The mode comparator
sorts refresh before area, so the same pin could also drop a 4K TV to 1080p120
and negotiate the stream at that.
Fixed at the choke point: `resolveHighRefreshMode` returns early on a TV, leaving
`highRefreshModeId` at 0, which `setConsoleHighRefreshRate` already treats as a
no-op — so all three of its callers are covered by the one guard. A TV that
genuinely wants 120 still gets it by choosing it, driven by the native mode
switch, exactly as the TV path documents.
Also in the same chain: `nativeDisplayMode` TRUNCATED the panel rate, so a TV
reporting the fractional NTSC rates over HDMI (59.94, 29.97, 23.976) asked the
host for 59 / 29 / 23 — rates no display mode has, which the host serves by
clamping down to the highest it advertises at or below. Rounded now, which also
makes it agree with `MainActivity.streamPanelFps`; the two describe the same
panel and must not disagree.
The window was `frame_interval * 2`, which is 16.7 ms at 120 fps. A Moonlight
client that has lost decode sync re-asks for an IDR roughly every 30 ms, so the
gate never closed between requests and effectively every request became a full
keyframe.
Field log (AMD RX 7800 XT, Bazzite 44, 1080p120 HEVC over the GameStream plane):
1118 IDR requests in one 91 s session, 1115 honoured, only 3 coalesced — about
one full IDR every tenth frame at a 100 Mbps target. IDRs that size saturate the
send path, which causes the loss that prompts the next request, so the storm
sustains itself. It reads as stutter at a flat latency, because frames are being
lost rather than queued. The same session's H.264 leg (libav VAAPI, same
bitrate) took 2 IDR requests and was clean.
The window is a round-trip bound — how long until the client can receive and
decode the IDR it already asked for — so it needs an absolute floor rather than
a frame count. 100 ms matches the encoder-reset backoff in the same loop.
Simulated against the logged 30 ms request cadence, this cuts honoured IDRs over
a 91 s session from every request to roughly a quarter, while still recovering
promptly from a genuine loss event.
Every pf-decode SIGABRT on the Shield is fdsan catching a double-close of the
acquire fence the ASC presenter passes to ASurfaceTransaction_setBuffer, in
three shapes: inside Fence::Fence(int) under setBuffer when the number had
already been re-owned ("fd N is owned by unique_fd, was expected to be
unowned"), at the end of Transaction::apply when the layer state is torn down,
and in Parcel::freeDataNoInit once the number churns.
The fence is not ours to give. AImageReader::acquireLatestImage drains with a
single int* out-param it overwrites per image, then releases each dropped image
with whatever that out-param currently holds — the successor's fence — and
returns the last value written. So as soon as a burst gives it two images to
collapse, the caller receives an fd the reader has already adopted and closed,
plus one leaked fd per extra drop. This is unfixed as of AOSP main, so the
newest-wins collapse has to happen on our side.
Drain both present intents with acquireNextImageAsync, whose fence is always a
fresh dup we exclusively own, and let latency pick the newest itself — the loop
the smoothing FIFO already ran. Superseded candidates drop as before: image back
to the pool, its own acquire fence closed. Reader drops now show up in `skipped`
instead of vanishing inside the reader lock.
The GameStream twin of the native fix. A fullscreen game can mode-set the
virtual display mid-stream; the IDD-push capturer re-opens its ring at the
new mode, and `try_latest` then hands this loop a frame the encoder cannot
accept. Every submit fails, the submit ladder rebuilds the encoder IN
PLACE at the same configured size — which cannot converge on a size the
source has already left — and after five resets the stream ends, costing
the Moonlight client a full disconnect/reconnect.
Reopen at the delivered size instead, with the same bookkeeping the
capture-loss rebuild in this loop already does (ring depth, RFI caps,
forced IDR, in-flight numbering restart). A failed reopen spends the
shared `encoder_resets` budget at the existing exponential pace rather
than ending the stream on the first try — a mode-set leaves the driver
settling, which is what that backoff exists for.
`gs_bit_depth(frame.format)` is derived per open, so an HDR flip that
recreates the ring at P010 now re-opens at the right depth too.
The client is NOT told: GameStream has no mid-stream mode-change message,
so Moonlight decodes a bitstream that disagrees with the resolution it
configured its decoder from. That is the same bargain the first open in
this function already takes whenever the captured size differs from the
negotiated one (the monitor-mirror case, §7.3) — tolerant decoders re-init
off the SPS and scale; a strict one (Media Foundation on Xbox) may stall
and drop the session. Taking it here too is strictly better than the
alternative, which is ending every stream the moment a game changes mode.
The guard carries that note.
A trailing comment that long makes rustfmt treat the two comment lines
that follow it as a continuation of the same block and reflow them into a
hanging indent past column 60, which fails `cargo fmt --all --check`.
Put it on its own line above the statement instead.
`ci / rust` failed the unsafe-hygiene gate: mgmt/tests.rs went to 6 process-global-API
mentions against a baseline of 3. The new rename test had copy-pasted the existing
`EnvGuard` + CONFIG_DIR_TEST_LOCK + tempdir dance, which is exactly the duplication gate C
exists to catch — its advice is to fix the call site rather than raise the baseline.
So there is now ONE `ConfigDirOverride` both tests use. It also makes the pairing harder to
get wrong than the copies were: the lock is a FIELD rather than a separate `_serial` binding
a test could forget, and since `Drop::drop` runs before any field drops, the environment is
restored while the guard still holds the lock.
Back to 3 mentions, and `sh scripts/ci/check-unsafe-hygiene.sh` reports all three gates clean.
Note the last one is a PROSE mention: the grep counts comments too (deliberately — "keep it
dumb and stable"), so the doc comment had to stop naming the function it warns about.
Not re-run on .173: the box went off-network mid-change. It does not need to be — this is
`mgmt/tests.rs`, which is not Windows-gated, so Linux CI compiles and runs it. The Windows-only
verification (clippy over the `cfg(target_os = "windows")` devtest change) was already done and
that file is untouched here.
The reopen added in the previous commit bailed the session on the FIRST
failed `open_video`. That is worse than what it replaced: the mode-set
that triggers the reopen is exactly the kind of event that leaves the
driver settling, which is the transient the submit path's backoff already
exists for ("NVENC session open failing after a codec switch", 2026-07 —
no 8 ms retry could outlive it).
Spend the shared `encoder_resets` budget on it at the same exponential
pace (100 ms → 1.6 s), re-entering the follow-the-source guard each round.
The old encoder stays installed and mismatched meanwhile, so it simply
keeps failing submit until an open succeeds or the budget runs out — the
same ~3 s ceiling as before, but now every round is a real attempt at the
new mode instead of an in-place re-init that cannot converge.
Also tag the exhausted path accurately: it is an encoder REOPEN failure,
not a submit failure, and the session-end log prints that context.
A fullscreen game can mode-set the virtual display mid-session with no
client Reconfigure. The IDD-push capturer already handles that — it
re-opens its ring at the new mode on a confirmed descriptor change — but
nothing re-opened the ENCODER, which is the one component that cannot
follow a resolution change in place.
Every submit then failed with "captured frame 1920x1080 != encoder
3840x2160", and the submit-error path only rebuilds the encoder IN PLACE
(Terminate + re-Init at the SAME configured size), which cannot fix a
size the source has already left. All five resets burned on it and the
video session ended ~3 s later, with audio still running — the client
sees a frozen picture and has to reconnect.
Field report 2026-08-22 (host 0.31.2, RX 6800 XT, AMF/HEVC 4K60):
IDD push: display descriptor changed — recreating the ring at the new
mode target_id=259 from=3840x2160 hdr=true to=1920x1080 hdr=true
encoder submit failed — encoder rebuilt in place, forcing an IDR
error=captured frame 1920x1080 != encoder 3840x2160 reset=1 max=5
... reset=5 max=5
encoder did not recover after repeated in-place rebuilds — ending the
video session ... resets=6
Track what the encoder was opened against and, when the source delivers
something else, re-open at the delivered size through the same
`open_video` path the client-initiated resize uses — then publish the new
mode to the client exactly as an accepted resize does, so its mode slot,
stats and aspect follow. PyroWave's Automatic rate is re-resolved for the
new mode (it is a per-mode bpp pin); H.26x rates stay with ABR.
Also covers a mid-session frame-format change (an HDR flip re-creates the
ring at a new format), which failed the same way.
The GameStream/Moonlight loop has the identical gap, left alone here: that
protocol has no mid-stream mode-change message, so following the source
there needs its own decision.
A player had to launch Rocket League twice: the first launch streamed the
"Processing Vulkan shaders" dialog and then dropped, ten seconds in. The host
did that to itself.
`reaper SteamLaunch AppId=<appid>` is the *appid's* wrapper, not the game's.
Steam wraps its pre-launch work for a title in one too, so a launch is a chain
of appid-tagged trees and only the last is the game. The lease matched the
first tree two seconds in, and that single sighting latched it out of the start
phase (START_GRACE, five minutes, ending nothing) into the exit watch
(EXIT_CONFIRM, three seconds, ending the session). When the tree exited with
the game still starting, the watch called it the game exiting and closed the
connection with APP_EXITED.
Linux has nothing to catch that: `procscan::running_hint` is Windows-only, and
no provider reports runstate for Steam, so an appid scan with three seconds of
slack is the whole signal. (Steam's registry.vdf is not an option — RunningAppID
is no longer set on modern Steam Linux, and the per-app Running key is
unreliable.)
Two layers, because only one of them can be certain:
* The matcher now rejects a `SteamLaunch AppId=` reaper whose payload is
`fossilize_replay` — Steam's shader replayer, never a game.
* A scan match must be seen continuously for SHIM_WINDOW before it latches.
This is the rule already applied to a spawned child ("a launcher about to
hand off looks exactly like the game for its first few seconds"); the scan
side never had it. It bounds the pre-launch trees nobody has named yet, at
the cost of a few seconds of GameRunning latency. Exit detection is
untouched, and a provider report still latches immediately — that is the
launcher's own statement, not an inference from a lookalike.
The log said `procs=1` and never which process, which is what made this
unclosable from a log alone; `procscan::names` puts that on the line.
Reported from the field: "is there a possibility of renaming the moonlight paired
devices? as they're all named CN=NVidia Gamestream Client". They are, and it is not a
display bug — every moonlight-common-c client self-signs with that same fixed subject,
so the certificate carries no device identity at all. Until now the console listed that
string for every Moonlight row, which means a user with a phone, a TV and a Switch saw
three identical rows and had nothing but a fingerprint prefix to tell them apart — most
sharply when deciding which one to unpair.
The name is an operator-supplied label, stored host-side keyed by fingerprint:
* `client-labels.json`, a SIDECAR to `paired.json` rather than a field inside it.
`paired.json` is a bare `Vec<Vec<u8>>` of DERs, so giving it a shape would be a
migration on the one file that decides who may connect — and a label is not part of
that trust decision, so a corrupt or missing label file must never be able to lock
anyone out. Same atomic temp-file + rename as `save_paired`.
* `PATCH /api/v1/clients/{fingerprint}` sets or clears it; `GET /clients` grows a
`label`. A whitespace-only body clears rather than storing a blank name, and only an
already-paired fingerprint may be named (a label for an unknown one would be
invisible and never cleaned up). Unpairing forgets the label, so the file cannot grow
without bound and a re-pairing of the same certificate starts unnamed.
* Scrubbing reuses `native_pairing::sanitize_device_name` rather than growing a second
one: it already strips C0/C1 controls and Unicode bidi overrides and caps at 64.
That is not cosmetic here — the label is the ONLY thing distinguishing two paired
devices in the console, so an unscrubbed one could dress a stranger's device up as
the operator's TV and be spared an unpair on that basis. For the same reason the new
route takes the plugin/cert lanes of the DELETE beside it (neither may reach it),
not the roster GET's read permission; the lane test now pins that.
* Console: a pencil on Moonlight rows opens the existing `promptText` dialog seeded
with the current label (not the `CN=…` fallback, or every rename would start by
deleting boilerplate). Native rows keep their pairing-supplied name and get no
pencil.
Test: one round trip through the API — name it, see it in the list, watch the bidi
override and the whitespace collapse get scrubbed, clear it two ways, reject a
malformed and an unpaired fingerprint, and assert the unpair forgot it on disk.
VERIFIED on .173 (the Windows box, since punktfunk-host does not build on macOS):
`cargo test -p punktfunk-host mgmt::` → 58 passed, including the new
`client_label_round_trips_scrubs_and_is_forgotten_on_unpair` and both guardrails that
caught this work in progress (`every_route_is_classified_for_the_plugin_and_cert_lanes`
and `openapi_document_is_complete_and_checked_in`). Web `tsc --noEmit` clean.
Two notes on the diff, both PRE-EXISTING and verified as such rather than assumed:
* `sdk/src/gen/punktfunk.ts` is bigger than this feature. Regenerating it from the
UNCHANGED committed spec already produces a ~700-line diff, i.e. the checked-in copy
had drifted from its own pinned generator — nothing in CI regenerates or verifies
it. This lands the clean regeneration rather than hand-patching generated code.
* `api/openapi.json` was regenerated on Windows, not CI's Linux. Checked structurally
before committing: the only differences are `PATCH /clients/{fingerprint}`, the
`RenameClient` schema and `PairedClient.label` — no OS-driven drift.
Unrelated and NOT touched: `mgmt::tests::display_monitors_answers_even_with_no_compositor`
fails on Windows, at HEAD as well. It answers `compositor="windows", monitors=[],
error=null`, and the test's escape hatches only cover gamescope, an absent compositor or
an error. Either the test needs a Windows arm or Windows display enumeration is returning
nothing it should — that is a real question, so it is left for someone to answer rather
than papered over here.
Chasing "gamepad still dead on GameStream clients after dfcffcdd" (Artemis on
Android, Moonlight on a Switch; both report only mouse/touch working). dfcffcdd
moved this plane from the XUSB companion to the UMDF HID Xbox pad and was verified
by `cargo check` + `clippy` only, so nothing about it had ever run.
The suspicion this flag was built to test: `UhidManager` has a `heartbeat` whose
own doc says a UMDF pad "treats a multi-second input silence as an unplugged
controller", the native plane calls it every tick, and `SessionPads::pump_rumble`
does not. That asymmetry looked decisive because the two planes differ in exactly
the way that would expose it: punktfunk's own client re-sends every live pad's
snapshot every 100 ms unconditionally (`input_task.rs` refresh tick), so a native
pad is never silent, while moonlight-common-c sends a controller packet only on
CHANGE — an untouched pad emits nothing at all.
`--idle-after N` stops the state frames while still pumping; `--resume-after M`
starts them again, because enumeration surviving a silence proves nothing on its
own (a pad can stay listed and deliver no input) — what matters is whether a report
written after the silence still lands.
MEASURED on .173 (Win11 26200), and it does NOT reproduce: with `--xboxhid
--idle-after 12 --seconds 75`, the pad sat through 58 s of total input silence with
`SWD\PUNKTFUNK\PF_XBOX_0` at Status=OK and its promoted `HID\PUNKTFUNK&IG_00` child
still present the whole time. So the heartbeat gap is NOT the field bug, and the
one-line "add a heartbeat to the GameStream arm" fix this was going to justify is
not warranted — which is the point of landing the probe rather than the guess.
Also measured with the same binary, and worth recording because it IS real:
* two LIVE processes wanting pad index 0 collide exactly as `PadCreateFault::
IndexOwnedElsewhere` describes (`Global\pfds-boot-0`, ACCESS_DENIED because the
mailbox DACL is SYSTEM+LocalService). dfcffcdd put BOTH input planes on that one
name — before it, GameStream used `Global\pfxusb-boot-0` and the two could never
collide — so the hazard is new, even if it is not what the reporter hit.
* a clean release-then-retake does NOT collide: back-to-back runs at 0 s, 1 s and
3 s gaps all created their pad, so an ordinary client reconnect is not the trigger.
Ruled out on the same box while here: the driver package (`pf_gamepad.inf` 08/18
declares all three Xbox hwids and the `xinputhid` promotion), stale drivers in the
field (the Windows updater is a full Inno Setup run that re-runs `driver install
--gamepad`), and access grants (a Moonlight fingerprint has no grants record, which
`control.rs` reads as GRANT_ALL).
Still open, and it needs a live session: .173 runs `PUNKTFUNK_HOST_CMD=serve`, i.e.
GameStream is switched OFF, so this box has never exercised the plane dfcffcdd
changed. That is how a compile-only fix reached users unexercised, and it is the
first thing to change before the next attempt.
flatpak-deps-present.sh decides whether the job talks to Flathub at all, and
a push-paths filter that ignores it means a change to that decision ships
untested until the next unrelated client commit happens to rebuild. Same
reason .gitea/workflows/flatpak.yml is already listed.
The flatpak job died on every attempt with
Updating runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/25.08
Error: Failed to update org.freedesktop.Sdk.Extension.rust-stable: While
pulling ... .filez: Server returned HTTP 404
dl.flathub.org was serving a 404 for one object of the then-current
rust-stable//25.08 commit. retry.sh burned all 10 attempts (~9 min) on the
same object, and flatpak-builder segfaulted on its own error path (rc=139),
so the wrapper could not tell a dead end from a load blip either.
Root cause is ours, not Flathub's: `--install-deps-only` does not install
what is missing, it UPDATES what is present. builder_manifest_install_dep()
branches on `flatpak info --show-commit <ref>` succeeding and runs
`flatpak update` for every already-installed dep, with no fallback to a
plain install when that update fails. ci/flatpak-ci.Dockerfile bakes the
entire runtime set, so that update was a pure no-op on a healthy run while
making every build depend on Flathub's health at that minute. Nothing wanted
the newer commit — the manifest pins a runtime VERSION, not a commit.
So ask first, and reach for Flathub only on a real miss. The check is
scripts/ci/flatpak-deps-present.sh (runtime + SDK at the manifest's exact
runtime-version, sdk-extensions by presence, since their version comes from
the SDK's metadata and any bump that moves them moves runtime-version too).
It fails OPEN: anything it cannot parse takes the full install path. Its
--self-test stubs `flatpak` and covers baked / cold / each dep missing /
wrong version / unreadable manifest.
Also drop --install-deps-from=flathub from the build step. Its comment
called it "a no-op safety net"; builder-main.c calls
builder_manifest_install_deps() whenever that flag is set, and
--install-deps-only only decides whether it exits afterwards, so the step
billed as offline was re-running the same update — and could only ever fire
if the prefetch step had already failed the job.
packaging/flatpak/build-flatpak.sh keeps --install-deps-from: a dev box
genuinely wants deps installed, and it has no baked image.
10 commits since v0.31.1 (6 non-merge). Cut from origin/main 48eeae75 (#368
merged).
THE NUMBER: a patch, and unlike the last cut the version table does not even
have to argue for it. Nothing versioned moved — WIRE_VERSION 2, C ABI 25 with
include/punktfunk_core.h showing NO diff at all against the v0.31.1 tag (not
even a #define, unlike the last two releases), driver protocol 6 / min 3 with
pf-driver-proto unchanged, gamepad channel 3, plugin index schema 1, host event
schema 1, gamescope +pfhdr8 with no new patch files, SDK 0.1.5 and plugin-kit
0.4.4 both untouched. No `!` commit, no feat, no route added or removed, no
breaking change of any kind. Every non-merge commit is fix/refactor/test.
The cycle has a shape: three of the six non-merge commits are the same class of
fault — the host using the wrong local address — reached from three directions.
The data socket bound 0.0.0.0:0 and let routing pick the video source, which the
client's connected socket then dropped in-kernel (#367). Host::detect() froze the
advertised address at process start, so a cold boot that beat the network pinned
127.0.0.1 for the life of the process and broke both mDNS adverts, the Moonlight
session URL, the WoL mac record and HostInfo together (#366). And the firewall
rules guarding the ports those addresses point at admitted any program on the
machine (#368). The fourth is an Android regression from v0.31.1 (#365); the
remaining two are the refactor and test supporting #366.
api/openapi.json changes in DOCUMENTATION ONLY this time — two description
strings on HostInfo, no route, schema, required field or type — plus the stamp.
Re-stamped here, not regenerated: punktfunk-host does not build on macOS, and
#366 regenerated the document itself on a runner where
openapi_document_is_complete_and_checked_in actually executes. "0.31.1" appears
nowhere in either copy afterwards, and the two copies are byte-identical.
That description change is load-bearing rather than cosmetic, so it is called out
as a behaviour change in the CHANGELOG beside the firewall one: HostInfo.local_ip
was a field snapshotted at detect() and is now a method that re-reads per
request, so a consumer that cached it at startup was caching a value that could
be 127.0.0.1 forever.
The other behaviour change is the externally visible one: Windows service install
now scopes all five fixed-port rules to the listening executable while keeping
their localport=, so 5353 is punktfunk's alone and anything else on the machine
that was reachable on mDNS through our any-program rule needs its own. Fallbacks
are asymmetric on purpose — a fixed-port rule that cannot resolve its exe falls
back to the old wide form (a looser rule still streams), while the data-plane
rule skips (it has no port to fall back to, so a program-less version would not
be looser, it would be open).
Also in this commit, because a cut is when docs freshness bites:
docs-site/content/docs/ports.mdx. Its "Video needs nothing opened" bullet has
been wrong for Windows since v0.31.1 added the data-plane rule — it now says so
and names why (no fixed rule can cover a per-session ephemeral port). And the
Windows line gains a Callout for the 5353 change above, since that is the one
thing on this page a reader may have to act on. Callout shape copied from the
proven usage in plugins.mdx (no `title` prop — node_modules is not installed here
and fumadocs' prop surface could not be verified offline).
Play notes are Android-only per whatsnew/TEMPLATE.txt, which this cycle means the
#365 regression alone. The three host-side fixes are deliberately NOT in there:
updating the app does not fix any of them, so listing them on the store page
would promise something the download does not deliver.
Gates: cargo fmt --all --check clean; cargo metadata --offline ok with the
Cargo.lock diff versions-only (36/36); cargo test -p punktfunk-core --lib 273
passed; the C ABI harness PASSED reporting abi_version=25 (needed `brew install
opus` on this Mac to link — the first run failed on the missing library, not on
the code); cbindgen regenerated include/punktfunk_core.h during that build and it
came out byte-identical to the checked-in file AND to the v0.31.1 tag, which is a
stronger check on the ABI row than diffing it; scripts/ci/check-docs-drift.sh
clean; scripts/ci/check-docs-links.sh clean; the android.yml Play notes gate run
verbatim, 357/500 characters and unique; both openapi copies cmp identical and
stamped 0.31.2; notes voice scan clean (one backticked term in the whole file,
the `punktfunk-host service install` command, and the only technical vocabulary
sits inside `## For developers`).
Not run here, and why: clippy and any punktfunk-host build (does not compile on
macOS — CI covers it), and the Android unit tests (:kit: and :app: were run on
#365 itself; nothing in this commit touches Kotlin).
One judgement call left for the tag: SECURITY.md promises to credit a reporter in
the release notes when the fix is public, and the #368 commit records only "a
user on 2026-08-21" with no name. The notes credit them unnamed. If they want
their name on it, that is a one-line edit to docs/releases/v0.31.2.md before the
tag is pushed.
`service install` added `dir=in action=allow` rules carrying only `localport=`,
which admit ANY process on the machine on those ports — GameStream
(47984/47989/47998-48010/48010), the native plane (9777), mgmt (47990), mDNS
(5353), and the console pair (47992/47993). Binding a high port on Windows
needs no elevation, so an unprivileged program could take any of them and be
reachable from the LAN simply by binding first — silently, because our rule is
precisely what suppresses the "Allow this app to communicate on…" prompt that
would otherwise be the only way in.
Scope every rule to the executable that actually listens on it, keeping the
ports: program AND port is strictly tighter than either alone. The host rules
name the host exe (resolved once and shared with the data-plane rule, which
already worked this way and is the pattern the rest now follow); the console
rules name the bundled `<app>/bun/bun.exe` the supervisor spawns.
The old argument for leaving them unscoped — "an install whose recorded exe
path later moves still has its fixed ports open" — does not hold: `service
install` re-runs this whole remove-then-add on every upgrade, so the path is
refreshed rather than left stale.
Fallbacks are deliberate and asymmetric. A fixed-port rule whose program can't
be resolved falls back to the old any-program form, because a looser rule still
streams and no rule is a black screen. The data-plane rule instead skips: it
has no `localport=` to fall back to, so a program-less version of it would not
be a looser rule but an open host.
One externally visible change, called out in installer output: 5353 is ours
alone now, so anything else on the machine that answered mDNS through
punktfunk's rule needs its own.
Reported by a user on 2026-08-21, after the source-IP fix in #367 resolved
their black screen.
`bind_data_socket` bound `0.0.0.0:0`, so the kernel chose the video source
address from the routing table, independently of the address the client's
control connection actually arrived on. The client's data socket is
`connect`ed to the host IP it dialed, so its kernel drops every datagram from
any other source — before userspace, where nothing counts it.
On a host with two live paths to the client (Ethernet and Wi-Fi both up on the
same LAN; a VPN/overlay adapter claiming the route) that is a permanent black
screen with every gauge green: the hole-punch still arrives so the host logs
`punched=true`, `loss_ppm` stays 0 because there are no packets to see gaps
in, and QUIC — which quinn pins to the right local address — carries control,
audio and input perfectly. `from_socket_punch` already documents the mirror of
this assumption for the *client's* source IP; the host side was never checked.
Bind the data socket to `Connection::local_ip()` instead (unmapping an
IPv4-mapped v6 address so the socket can still `connect` to a v4 peer), and
fall back to the wildcard, loudly, when it is unavailable.
Two diagnostics, because this session's log could not answer the question:
- the `data plane bound` line now carries the socket's post-`connect` `local=`
address — the source the kernel will actually stamp — and WARNs when it
differs from the address the control plane arrived on.
- the black-screen ERROR no longer asserts "This is a PATH problem, not
decode" and no longer names `punched=false` as *the* fingerprint. It fired
with `punched=true` in the field, which contradicts its own advice and sent
an investigation at the firewall. It now branches on what the bring-up line
says, and admits its counter is incremented after decrypt and replay checks,
so a session whose every datagram failed to open reports the same zero.
`Host::detect()` snapshotted the LAN address once, at process start, and every
consumer read that frozen field for the life of the process. On a cold boot the
host outruns the network — the Windows service is `AutoStart` with no
dependencies — so the route probe failed with ENETUNREACH and the loopback
fallback stuck until someone restarted the host by hand.
Four surfaces broke off that one field: both mDNS adverts published 127.0.0.1 as
their A record, `session_url_xml()` handed Moonlight `rtsp://127.0.0.1:48010`,
`wol::wake_macs()` dropped the `mac` TXT record and silently disabled
Wake-on-LAN, and `HostInfo.local_ip` reported loopback to the console.
Fixed at the choke point: `primary_local_ip()` never returns loopback and falls
back to the first non-loopback interface address when no default route exists
yet; `Host::local_ip` re-reads instead of freezing; and a live mDNS advert
re-registers when the routed address changes. Also covers a changed DHCP lease
and a host moved between Wi-Fi and Ethernet.
The route probe needs a default route, which on a cold boot lands after the NIC
has its address; the fallback is what answers in between, and nothing exercised
it. Split it into `first_lan_ipv4` so a test can assert the one thing that
matters: it never hands back the loopback `get_if_addrs` also reports.
std's mpsc doubles as the sleep and the stop signal: the loop times out every
IP_RECHECK to re-check the address, and the Advert dropping its sender wakes the
thread immediately instead of leaving it to notice a flag up to 10s later. Drops
the Arc<AtomicBool> and the Drop impl.
`Host::detect()` snapshotted the LAN address once, at process start, and every
consumer read that frozen field forever. On a cold boot the host wins the race
against the network — the Windows service is registered `AutoStart` with no
dependencies — so `primary_local_ip()`'s route probe to 8.8.8.8 failed with
ENETUNREACH and the loopback fallback stuck for the life of the process.
Restarting the host re-ran `detect()` on a live network, which is the workaround
users found.
Four surfaces broke together, all off that one field:
* both mDNS adverts (`_punktfunk._udp`, `_nvstream._tcp`) published `127.0.0.1`
as their A record — the address a client lists and dials;
* `session_url_xml()` handed Moonlight `rtsp://127.0.0.1:48010` after /launch,
so even a manually-added host could not stream;
* `wol::wake_macs()` found no interface for loopback and dropped the `mac` TXT
record, silently disabling Wake-on-LAN;
* `HostInfo.local_ip` reported loopback to the web console.
Fixed at the choke point rather than per-caller:
* `primary_local_ip()` never returns loopback or the unspecified address. When
the route probe fails it falls back to the first non-loopback interface
address, which exists as soon as the NIC is configured even if the default
route is not installed yet — the common shape of the boot race.
* `Host::local_ip` becomes a method that re-reads instead of a field that
freezes. A `connect(2)` on an unconnected UDP socket sends no packets and
costs nothing beside the HTTP response it is serialized into.
* mDNS records are pushed, not polled, so a live advert re-registers when the
routed address changes (`discovery::advertise_live`, shared by both service
types). It polls the routed address rather than subscribing to the daemon's
IpAdd events because the boot race usually resolves without one: the NIC
often has its address before we register and only the route lands late.
This also covers the sibling cases that were never reported — DHCP handing out a
different lease, and a host moved between Wi-Fi and Ethernet.
Two field reports (2026-08-21), one shape: a GameSir G8+ and an Xbox Elite
Series 2 ("Xbox Wireless Controller" over Bluetooth) with X answering Y, Y
answering LB, and the two shoulders answering menu buttons — everything else
correct. That is not a stray mapping, it is exactly what `GENERIC_XBOX` does to
scancodes `0x133`/`0x134`/`0x136`/`0x137`, so the correction added yesterday was
firing on pads whose buttons were already where `Generic.kl` says they are.
It fired because it asked the wrong question. `hasKeys(BUTTON_C, BUTTON_Z)`
answers for what a device DECLARES, not what it reports: `hid-input` allocates
`BTN_A + n` straight through for every button in the descriptor, so BTN_C
(`0x132`) and BTN_Z (`0x135`) are set on ANY pad declaring six or more —
including a standard-layout pad that never presses either. The signal is
therefore identical on the pad that needs correcting and the pad that does not,
and no amount of tightening it could have separated them. It is the same pad
model in both reports: an Elite Series 2 needed the correction on a Fire TV and
another Elite Series 2 was broken by it here.
What does separate them is the axes. A HID gamepad describes its triggers either
as the Accelerator/Brake usages — which become `ABS_GAS`/`ABS_BRAKE`, names
Android has words for — or as two more generic axes on `ABS_Z`/`ABS_RZ`, which
it does not. A descriptor well-formed enough to name its triggers puts its
buttons at the standard positions too. It is also the firmware line on the pad in
the report: an Xbox Wireless Controller over Bluetooth reports GAS/BRAKE after
its firmware update and Z/Rz before it, and only the older one was ever wrong.
`padButtons` now takes `namedTriggers` and answers NATIVE whenever it is set —
no correction of any kind, on buttons or axes, for a pad Android already reads.
`padMap` computed that fact one line below and only ever spent it on the axes;
it now decides both. `hasKeys` stays for the narrower question it can answer —
WHICH straight-through order, once the axes have established there is one — where
a false positive costs nothing.
Moonlight decides it on the same fact (`ControllerHandler`, `gasRange == null`
beside the `"Xbox Wireless Controller"` name); yesterday's commit cited its
tables and then replaced its discriminator, which is where this came in.
Verified: `:kit:testDebugUnitTest` and `:app:testDebugUnitTest` green (16 cases
in PadButtonsTest, 3 new: the gate holds for every vendor/declaration
combination, the four reported buttons stay themselves, and the report-order
choice past the gate is unchanged), `:app:compileDebugKotlin` clean. The
DualSense report filed alongside these — Triangle dead in the client UI and in
the stream — is NOT explained by this and is not fixed here: a button that
reaches neither is one `buttonBit` maps to nothing, which no branch of the
correction produces for Triangle. The Controllers screen prints the raw scancode
and keycode of every press; that line off the reporter's pad will pin it.
30 commits since v0.31.0 (19 non-merge). #362 merged onto main seconds
after the release merge (#363), so the notes as tagged would have been
wrong in the one way that matters: they lead `## New` with the console's
"Controller-optimized UI" switch, and cbd3d028 is the commit that makes
that switch do anything at all.
trust::Settings::extra is #[serde(flatten)], so the android.* keys are
TOP-LEVEL keys of the settings document. ConsoleJson wrote and read them
nested under an "extra" object, which serde filed under the literal key
"extra" — so no console row ever found android.gamepad_ui_enabled. Every
Android-only row rode the same dead path in 0.31.0: low latency, phone
rumble/gyro, SC2 and DualSense capture, and the console-UI mode picker.
That is a user-facing fix in its own right and is now in `## Fixed`, in
`## TL;DR`, and in the Play notes — it is the most useful 500 characters
an Android user gets from this release.
Also folded in: c9a76287, the focus halo and panel_highlight taking the
card's corner plus their own outset (a rect grown by d only stays
concentric if its radius grows by d too).
NOT folded in — deliberately: cargo audit is red on main with
RUSTSEC-2026-0258 (h2 0.4.15, unbounded empty DATA frames, fixed in
0.4.16, transitive via hyper). It predates this cut — the same job failed
on 669a1bc0 and on the v0.31.0 tag commit — so it is not a regression
here. `cargo update -p h2 --precise 0.4.16` bumps h2 in eleven lock lines
but ALSO rewrites several windows-sys references downward (0.61.2 ->
0.59.0/0.52.0) on the pinned 1.96.0 toolchain. Re-resolving the graph for
the Windows build inside a version bump that cannot be compiled for
Windows on this host is the wrong trade; it wants its own commit and its
own CI. Recorded in the CHANGELOG's verification section.
Cargo.lock is untouched by this commit.
Gates re-run: cargo fmt --all --check clean; scripts/ci/check-docs-drift.sh
clean; cargo test -p punktfunk-core --lib 273 passed; the Play notes gate
run verbatim, 440/500 characters and unique; both openapi copies cmp
identical and stamped 0.31.1; notes voice scan clean.
27 commits since v0.31.0 (17 non-merge). Cut from origin/main 2be444b3
(#361 merged).
THE NUMBER: a patch, on the user's call, and the version table does not
argue with it. Nothing versioned moved — WIRE_VERSION 2, C ABI 25 with
include/punktfunk_core.h differing from the v0.31.0 tag by one `#define`,
driver protocol 6 / min 3 (pf-driver-proto has no diff against the tag),
gamepad channel 3, plugin index schema 1, host event schema 1, gamescope
+pfhdr8 with no new patch files, SDK 0.1.5 untouched. No `!` commit and
no breaking change of any kind.
Two surfaces grow, both by pure addition, and neither forces the minor:
the management API gains PUT /library/provider/{provider}/running (#361,
already regenerated into both openapi copies there — this commit moves
only the stamp), and plugin-kit goes 0.4.3 -> 0.4.4 to export
ProviderClient.reportRunning from the package root. plugin-kit-v0.4.4 is
tagged AND published — it is the registry's `latest`; 0.4.2 is still
skipped there. A plugin that adopts neither is unaffected, and a 404 from
an older host means "this host tracks games by scanning".
The cycle is otherwise fix-shaped: fifteen fixes and two small features
— the console's own switch for turning itself off (which exists because
0.31.0 made the console the only interface Android shows with a pad
attached) and the provider running-report above.
The new control message (DeliveryReport, type byte 0x0B) is a `#define`,
not an ABI step — the same shape PipelineGap (0x0A) had at v0.30.0, and
it takes a free byte in its block rather than lengthening LossReport,
which is length-checked exactly.
Two behaviour changes are called out in the CHANGELOG rather than left
to be discovered: Windows `service install` now provisions a
program-scoped inbound UDP rule for the host exe (the black-picture
fix — no `localport=` rule can ever cover an ephemeral data port), and
the GameStream plane's default virtual-Xbox backend flips from the XUSB
companion to the UMDF HID pad, which is the correction of a default that
was only ever a module-name coincidence. Both revert with
PUNKTFUNK_XBOX_BACKEND=xusb / by removing the rule.
Also in this commit, because a cut is when it bites:
packaging/gamescope/PKGBUILD moves pfhdr7 -> pfhdr8. The banner has said
+pfhdr8 since patch 0010 and the host probes it for >= 8, but pacman
compares pkgver-pkgrel, read 3.16.25.pfhdr7-1 on both v0.30.0 and
v0.31.0, and offered Arch/SteamOS hosts no upgrade at all — so the
keyboard-layout fix never reached them. deb and rpm derive the version
from the binary banner and moved by themselves; Arch is the only channel
that hardcodes it. The v0.31.0 table flagged this as pre-existing.
api/openapi.json is RE-STAMPED here, not regenerated: punktfunk-host
does not build on macOS. #361 regenerated the document itself, with the
new route and its three schemas, on a runner where
openapi_document_is_complete_and_checked_in actually executes. This
commit moves one line (info.version, which utoipa fills from
CARGO_PKG_VERSION), and "0.31.0" appears nowhere else in either copy.
Gates: cargo fmt --all --check clean; cargo metadata --offline ok with
the Cargo.lock diff versions-only (36/36); cargo test -p punktfunk-core
--lib 273 passed; the C ABI harness passed reporting abi_version=25 —
it did NOT run on the v0.31.0 cut, so this is the first cut since ABI 25
where a C compiler has built the generated header;
scripts/ci/check-docs-drift.sh clean; the android.yml Play notes gate
run verbatim, 442/500 characters and unique; both openapi copies cmp
identical and stamped 0.31.1; notes voice scan clean.
The focus halo grows the card's rect by 4 design units on every side but drew
it with the card's own corner radius. A shape grown by `d` keeps its corners
parallel to the original's only if its radius grows by `d` too — otherwise the
two arcs stop sharing a centre. So the halo came out squarer than the card it
sits under: clean along the edges, visibly misaligned at the four corners,
where it read as a badly drawn outline rather than as light spilling out.
Same rule applied to `panel_highlight`, which pulls in half a unit and kept the
full radius. `drop_shadow` only offsets, so its geometry was already right, and
the collections plate uses `RRect::with_outset`, which adjusts the radii itself.
Every card in the console goes through these two helpers — the home tiles, the
library grid, the coverflow, the collections deck.
Turning "Controller-optimized UI" off in the console did nothing: the console
stayed up, because the setting never left the console.
`trust::Settings::extra` is `#[serde(flatten)]`, so the `android.*` keys are
TOP-LEVEL keys of the settings document, beside `width` and `codec`.
`ConsoleJson` wrote and read them nested under an `"extra"` object instead.
Serde put that whole object into the map under the literal key `"extra"`, so
no console row ever found `android.gamepad_ui_enabled` — the row showed its
own default, and the value the console saved came back to Kotlin as the one
Kotlin had just sent. `applySettings` then saw no change, raised no callback,
and `App` never recomputed `gamepadUiActive`.
Every Android-only row rode the same broken path: low latency, phone
rumble/gyro, SC2 and DualSense capture, and the console-UI mode picker.
A store written by the nesting build carries the dead wrapper; it is dropped
on the next write rather than echoed for the life of the install.
The new test pins the shape from both sides. A round-trip alone could not have
caught this — both halves agreed on the same wrong nesting, which is exactly
how it survived review.
Merged with `apple / swift` red: the Mac runner's volume is out of space (594 "No space left on device" lines; the only distinct error is "You can't save the file because the volume 'Macintosh HD' is out of space"). It passed on the parent commit 1280f697 and the only delta since was one line in scripts/ci/docs-undocumented-env-baseline.txt — Swift compilation of the Apple client cannot be affected by a Rust host firewall rule, a core control message, or a CI text baseline. A rerun hit the same wall, so the mac-mini-1 disk needs the owed cleanup.
Every check that can validate this change is green: ci/rust (480 core tests), ci/rust-arm64, android, docs-drift, web, docs-site, bun-nix, and both windows-client legs. The Windows HOST build — which the PR checks never run, and which is the only thing that compiles the cfg(windows) firewall function — was dispatched separately on the branch and passed, including "Clippy (host + tray, Windows)".
`api/openapi.json` (and its docs-site copy) gain exactly the new route and its
three schemas — nothing else moved, which is the check worth doing on a
regenerated spec.
The test fix is one the tests found themselves, on the first run in an
environment that actually executes them: all three shared the provider id
`playnite` and cleared the whole process-global table between cases, so under
parallel scheduling they flipped each other's answers — `omitted_is_not_running`
read `None` for a title another test had just wiped. Each now takes ids only it
uses and forgets only its own row, which also retires the blunt `reset()` that
made the collision possible.
`reportRunning` and its two types were reachable only through the deep
`./reconcile.js` path — `index.ts` re-exports an explicit list, not a star — so
no plugin could import them from the package root the way it imports every
other provider symbol.
Version bumped because it is a published package and the addition is what a
consumer would depend on; the playnite plugin deliberately does NOT, calling the
route through the untyped host seam instead so it is not gated on this publish.
The host derives liveness by scanning, which needs something recognizable on
disk. A Playnite-launched emulated game, a manually added one, or a library
plugin that records no install directory has none — and its launch is a
`playnite://` hand-off, so the host holds no process either. The lease went
`Untracked`: the exit was never noticed, `session_on_game_exit` could not fire,
and `POST /game/end` had nothing to aim at. Playnite knew the whole time.
New `PUT /library/provider/{provider}/running` takes a provider's complete
running set (with the pid where it knows one) — declarative and idempotent like
the reconcile beside it, so a missed event or a plugin restart self-corrects
rather than drifting. `crate::runstate` holds it and expires it after 90s
unless restated, which is what makes it safe for a live provider to hold a
session open for a game the host cannot see: a plugin that dies stops counting
and the host falls back to scanning, exactly as today.
`LeaseKind::Reported` is the lease that follows from it. `open` reaches it when
the spec is empty and a provider speaks for the id, and — the load-bearing part
on Windows, where every launch is a hand-off by construction — the three shim
reclassification paths now fall back to it where they fell to `Untracked`.
Phase 1 takes "running" as the game appearing; phase 2 takes "stopped" as the
exit. Unlike `procscan::running_hint`, which may only ever delay an exit because
Steam's registry flag survives an unclean one, a fresh report is decisive in
both directions. A reported pid joins the termination ladders on the same terms
as a spawned one: re-resolved and start-time-pinned at the moment of use.
The route is the plugin lane's, like the reconcile. No new authority — the host
maps `external_id` through the catalog, so a provider can only speak about
entries it published; an unknown id is counted, not refused, because a report
legitimately races its own reconcile and 400-ing the batch would throw away the
liveness of every other running title.
plugin-kit gains `ProviderClient.reportRunning`; a 404 from an older host means
"this host tracks games by scanning".
`check-docs-drift.sh` scans for `PUNKTFUNK_*` identifiers and asks that
each be documented in docs-site or explicitly baselined. It cannot tell
an env knob from a cbindgen-exported `#define`, so the new
`PUNKTFUNK_MSG_DELIVERY_REPORT` header constant tripped it.
It is a wire message type byte, not a knob an operator can set — same as
every other `PUNKTFUNK_MSG_*`, all of which are already in the baseline.
Added in sorted position beside them.
Two field reports from one Android user, with one shape between them: a
decision taken once, at a moment when the answer was still wrong, and never
revisited.
The console UI could not be dismissed. "With a controller" asks whether a pad
is attached, and the client answered that with `isPad` — does this device's
source class include gamepad or joystick. That is the right question for
ROUTING an event and the wrong one for presence: devices publish inputs that
claim the source class while being no such thing (OEM game-mode overlays, the
gaming-phone shoulder triggers), and one of them is enough to pin the console
UI on forever, because a pad that was never there can never disconnect.
`pads()` now filters on `looksLikeController`: the source claim AND hardware
behind it — a stick, a HAT, or the A/B face buttons — on a device the platform
did not synthesize itself. The claim is cheap; the hardware is not. `isPad`
keeps its looser meaning for the event lane, where it is correct. It is not a
complete defence (an OEM device that declares BTN_GAMEPAD and two axes is
indistinguishable from a pad at this layer), so the master switch stays the
guaranteed way out — and the Controllers screen still lists everything real in
one column or the other, which is where someone looks when the client's idea of
"a pad is attached" disagrees with the room.
The picture sat in the top-left corner. The ASurfaceControl layer composites
into the SurfaceView's on-screen rectangle, read once at `surfaceCreated` — but
the stream screen hides the system bars and switches the window to draw into
the display cutout a frame or two later, and each of those grows the view under
a surface that is never recreated. The layer went on painting at the size it
started with, anchored at the origin. It passed on glass because a device whose
bars were already hidden when the surface arrived never sees the gap.
The size is now live: a packed atomic on the session handle, seeded by
`nativeStartVideo`, re-reported by `nativeVideoSurfaceSize` from every
`surfaceChanged`, and read by the layer before each present. One atomic load per
frame, and rotation and multi-window come along for free.
Verified: `:kit:cargoNdkClippy` (arm64 + armv7, deny warnings), `:kit:` and
`:app:` unit tests, and the native crate's own suite. The new JNI symbol is
exported in the built `.so`.
The managed takeover stopped stopping the display manager and started idling the
box's autologin session instead (c2f5e91b). That commit also deleted the two lines
the old DM stop carried — `record_session_select_baseline()` and
`STOPPED_DM = Some(dm)` — and 38a0f54b then removed every remaining writer of that
static. The in-stream switch gate in `create_managed_session` still reads it, so
`honor_session_select_switch` became unreachable code on every box.
Bazzite never noticed, for two reasons measured on `.41`: its `os-session-select`
is a thin wrapper over `steamosctl` D-Bus calls and writes NO sentinel (verified —
`~/.config/steamos-session-select` does not exist before or after a completed
switch), and `is_steam_htpc_platform()` defaults the mid-stream session watcher ON
for bazzite/steamos, which follows the switch by itself.
Nobara gets neither. `ID=nobara` matches no HTPC default, so no watcher; and its
ChimeraOS-layout `os-session-select` DOES write the sentinel, which was the only
thing the host had to see the switch by. So on Nobara the user's "Switch to
Desktop" went entirely unhandled: the capture loss it causes drives a rebuild, the
rebuild relaunches game mode over the booting desktop, and the stream is thrown
straight back in — the 2026-07-24 field report, reopened by a user 2026-08-20.
Arm the gate on the takeover that actually exists now. `takeover_idled()` reads
IDLE_DROPIN_ARMED, the idle drop-in re-baselines the sentinel when it goes in, and
STOPPED_DM is documented as what it has become: adoption-only state for a takeover
stranded by a pre-0.31.0 host. The hand-back keeps that host's DM restore + switch
replay (now `replay_switch_under_restored_dm`) but runs it only for such an adopted
takeover — a 0.31.0 takeover leaves the DM up precisely so the OS does that work
itself, and on the VM it does: `Updated user selected session to plasma`, then
Plasma.
Both hand-back paths also give the box its own Game Mode back, which neither did.
The takeover replaces that session's ExecStart with a sleep, and a mid-stream
switch is the one exit that leaked it — the disconnect restore sweeps it, but a
switch is not a disconnect. Measured on Bazzite `.41`: after a completed switch to
KDE the unit still carried `ExecStart=/usr/bin/sleep infinity`, so "Return to
Gaming Mode" would have started a unit that does nothing. That is the same barred
way back `release_autologin_mask` already exists to prevent for the mask this
drop-in replaced, so it goes there — covering the watcher-driven distros — and in
`honor_session_select_switch`, covering the sentinel-driven ones.
Verified on the Nobara VM (123 on home-node-3) by driving the real path against
live systemd: takeover -> real `steamos-session-select plasma` -> rebuild. The
rebuild refuses to relaunch game mode, the idle drop-in is gone, and the box
arrives in KDE. Backed out to the 0.31.0 shape on the same box it fails at "the
switch did not advance the sentinel" — the blindness itself. The extended
`the_mask_comes_off_only_when_the_box_takes_itself_back` covers the watcher path
against a live user manager, and fails without the hand-back.
A field host streamed 1919 frames into a black screen while its own log
blamed the client. Four faults, each of which alone makes the failure
invisible.
The Windows firewall rules are `localport=`-scoped (47998-48010, 9777,
5353), but the media data plane binds an EPHEMERAL port per session. No
such rule can ever cover it, so Windows Firewall drops the client's
hole-punch on EVERY session on EVERY Windows host — `punched=false` on
the "data plane bound" line, in all six sessions of two field logs. The
punch then never opens the return path and video is sent blind to an
address the client merely reported. `service install` now also adds a
program-scoped inbound UDP rule for the host executable, which covers
whatever port a session picks. Program-scoped rather than a pinned port:
pinning into 47998-48010 would collide with Sunshine/Apollo.
`LossReport` carried only `loss_ppm`, which is ambiguous at zero — loss
is a ratio over the packets that arrived, so a flawless link and a link
delivering NOTHING both report 0. The host read total silence as perfect
and decayed adaptive FEC to its floor. Clients now also send a
`DeliveryReport` with the session's received-packet count. It is a new
type byte, NOT a field appended to `LossReport`: that message is
length-checked exactly, so lengthening it would make every shipped host
reject the loss reports its FEC runs on. Sent every window while the
count is zero, once when the first packets land, then never — an older
host warns per unknown message and must not be flooded on a good
session.
`NO_VIDEO_RETRY` (client got nothing) and `FLUSH_COOLDOWN` (client
drowning) were both 2000 ms, so the host's cadence classifier could not
tell two opposite faults apart and picked the wrong one out loud. The
no-video cooldown moves to core beside `FLUSH_COOLDOWN` at 2600 ms, and
both sides compare against the shared constant rather than a copy.
The diagnosis now leads with the delivery count: zero is an error naming
the data plane, a confirmed count keeps the old confident wording, and an
old client that cannot answer gets a warning that says so instead of
guessing. A punch that never arrives is also its own warning now, rather
than a debug field on an info line.
Reported from a Fire TV Stick 4K Max: a DualSense and an Xbox Elite Series 2,
both over Bluetooth, both identified correctly but with buttons on the wrong
actions ("L1 being L2"). Both work in Moonlight on the same box.
Android names a pad's buttons through a KEY LAYOUT file matched on VID/PID. A
pad with no matching file falls back to AOSP's `Generic.kl`, which assigns
keycodes by SCANCODE POSITION — 0x130→BUTTON_A, 0x131→BUTTON_B, 0x132→BUTTON_C
and up. That is only right if the pad's buttons sit where the file assumes, and
a HID gamepad with no kernel driver numbers its buttons 1..n straight through in
its OWN report order, so every keycode past the first divergence is somebody
else's button. Neither pad has a layout there: AOSP ships none for the Elite
Series 2 over Bluetooth (045e:0b05) on any version, and the DualSense's
(054c:0ce6) both postdates Fire OS and carries `requires_kernel_config
CONFIG_HID_PLAYSTATION`, which a Fire TV kernel has not. A DualSense reporting
straight through puts L2 on 0x136, which `Generic.kl` calls BUTTON_L1 — the
reported symptom exactly, and Circle and R1 (BUTTON_C / BUTTON_Z) mapped to
nothing at all and were dropped.
This client read `KeyEvent.keyCode` only, so it inherited every one of those
errors — in the stream, in the console shell's navigation, and in the
Controllers screen's own tester, which is why the tester agreed with the bug.
Resolve buttons from the SCANCODE instead, which is the pad's own report
position and immune to the layout file — the same reason `Keymap.toVk` reads
`scanCode` for keyboards. Two things keep it off pads that already work:
1. the correction applies ONLY where the delivered keycode is what
`Generic.kl` would have said, so a device-specific layout always wins;
2. which report order to read is decided from what the DEVICE declares —
a pad numbering straight through claims BUTTON_C and BUTTON_Z, keycodes
no real controller has a button for — never from a model table.
`Gamepad.padKeyCode(event)` is a drop-in for `event.keyCode` and every pad
reader now goes through it: the streaming branch, the Skia console shell's
probe, the older Compose navigation, and the Controllers tester. The console and
the game must not disagree about which button a user pressed.
Axes get the same treatment: a pad declaring none of LTRIGGER/RTRIGGER,
BRAKE/GAS or BRAKE/THROTTLE is one Android never mapped, and its triggers are on
raw axes. A Sony pad reporting straight through lays out X, Y, Z, Rz, Rx, Ry, so
only the triggers (RX/RY) were missed; every other such pad puts the right stick
on Rx/Ry and the triggers on Z/Rz — the shape that makes pulling a trigger swing
the right stick. Whether those idle at −1 is measured off the device's own range
rather than assumed, so a pad reporting an honest 0..1 is not rescaled to a
permanent half-pull.
Also: the Controllers screen now reports each press as its raw scancode and
keycode plus the correction, names the resolved layout on the pad's card, and
reads axes through the same map the stream does — so it can be trusted again,
and so an unmapped pad can be pinned from a field report without the hardware.
The Xbox Bluetooth product ids (One S, Elite Series 2 and its Core) join the
identity table; without them an Elite streamed under the Xbox 360 identity.
Moonlight carries the same two report-order tables (`ControllerHandler`'s
`isNonStandardDualShock4` / `isNonStandardXboxBtController`), which is why both
pads work there on the same box.
Verified: :kit:testDebugUnitTest and :app:testDebugUnitTest both green (13 new
cases in PadButtonsTest covering the scancode tables and the axis resolution),
:app:compileDebugKotlin clean. NOT yet tested on glass — the reporter's Fire TV
is the confirmation this needs. The Xbox pad's Guide button stays unreachable
either way: it arrives as KEY_HOMEPAGE, and Android never delivers KEYCODE_HOME
to an app.
Reported from the field: gamepad input does nothing on GameStream clients, and it
reproduces across every client and device a user tries (Artemis on a Steam Deck and
on an Android phone both). That breadth is the tell — it is not a client at all.
On Windows there are two virtual Xbox backends and they are not interchangeable to a
game. The XUSB companion registers only GUID_DEVINTERFACE_XUSB and exposes no HID
collection (pf_xusb.inx says so in its own header: "a non-HID UMDF2 driver", Class =
System), so Steam's hidapi enumeration, SDL, RawInput, DirectInput, joy.cpl and
WGI/GameInput cannot see it at all — only classic XInputGetState can. The native plane
moved to the real HID pad as its DEFAULT on 2026-08-09 (bd5735b8) for exactly that
reason; its doc comment records the reporter who lost a controller for two weeks to it.
The GameStream plane never got that change. It has bound `crate::inject::gamepad`
since the first gamepad commit, when that name meant uinput and Windows had no second
backend; Windows later gave the same name the XUSB companion, so this plane inherited
it by module-name coincidence rather than by any decision. bd5735b8 did touch
control.rs — but only to widen the rumble closure's arity, and its note reasons about
"the uinput backend", not about the Windows one sitting behind the same import. So
every Moonlight session since has presented a pad most games cannot enumerate, while
native punktfunk sessions on the same host got the good one.
There was also no way out: `windows_xbox_hid` was `pub(super)`, i.e. unreachable from
this module, so PUNKTFUNK_XBOX_BACKEND did nothing here — and the Windows manager
ignores the arrival `kind` byte, so a client could not ask for a DualSense either, the
escape that saved the earlier reporter.
- native.rs / native/gamepad.rs: `mod gamepad` and `windows_xbox_hid` become
pub(crate). The knob keeps ONE definition and one name; widening visibility breaks
no existing caller. Its doc now records that both planes read it, and why being
`pub(super)` was itself the bug.
- gamestream/control.rs: a `SessionPads` enum is the one place this plane picks a
backend — the HID pad when the shared knob says so, the XUSB companion otherwise,
and on every other platform the single backend that exists.
`PUNKTFUNK_XBOX_BACKEND=xusb` now reverts both planes together.
The HID pad's rich-feedback plane is dropped rather than plumbed: an Xbox pad has no
lightbar or adaptive triggers, and GameStream has no vocabulary for one — its rumble
message (0x010B) carries the two handle motors and nothing else, which is why the
trigger levels were already dropped at the call site.
No test: a `cfg(target_os = "windows")` #[test] would compile NOWHERE. ci.yml excludes
it by target, and windows-host.yml lints the host with `cargo clippy -p punktfunk-host`
without `--all-targets`, which does not build `cfg(test)` modules at all — the same
blind spot that workflow's own comments blame for letting the Linux twin's tests rot to
the wrong arity. It would be dead weight, not coverage.
VERIFIED
* ON WINDOWS (.133, the only box where this arm compiles at all):
`cargo check -p punktfunk-host` clean in 57s, then
`cargo clippy -p punktfunk-host -- -D warnings` clean in 42s — both on default
features, which include `gamestream`. This compiles BOTH enum arms: `Xusb` and
`Hid` are Windows types alike.
Non-vacuous by construction: `cargo clean -p punktfunk-host` ran first (a scp'd
tree plus this box's lagging clock and a warm shared target dir otherwise yield a
fresh `Finished` having compiled nothing), and both passes logged
`Compiling punktfunk-host v0.31.0`. The only warning is punktfunk-core's
header-write notice — benign and pre-existing.
* `cargo fmt --all --check` clean.
NOT VERIFIED — owed
* Linux: no box could run it (.25's root filesystem is 100% full; .21/.136/.138 were
down; OrbStack here hangs even on `docker run alpine echo`). Exposure is small —
the Linux arm is three calls on a `GamepadManager` whose Windows XUSB sibling has
the identical method surface and just compiled — and ci.yml DOES run on
pull_request, so opening a PR closes this.
* On glass: no Moonlight session has driven the HID pad through this plane yet. That
is the real acceptance test, and the log line to look for is
"virtual Xbox pad created (Windows UMDF HID)" where it used to say
"virtual Xbox 360 created (Windows XUSB companion)".
* windows-host.yml has NO `pull_request` trigger (push to main, v* tags,
workflow_dispatch only), so CI will not re-check this arm on a PR — the .133 run
above is deliberately standing in for it.
Re-measured every version-table row against the tree rather than
trusting the earlier cut: ABI 25, wire 2, driver 6/min 3, gamepad 3,
index schema 1, event schema 1, edition 2024, MSRV 1.85, 27 crate dirs,
39 workspace members, SDK 0.1.5, plugin-kit 0.4.3, openapi 0.31.0 with
both copies byte-identical, gamescope +pfhdr8 with 10 patch files and
no diff against the tag. All match what the table claims. The C header
diff against v0.30.0 removes exactly two things — the old ABI define and
the ex11 doc paragraph that stated the superseded hi-res rule — so
'addition only' holds.
Three fixes to the text itself:
* The commit count is now taken at the tip being released (170/113 at
d7fa5847) instead of at this branch, where it moved every time I
committed to it.
* The two NixOS items in Before-you-update are one item. They were
separated by three unrelated bullets, so the audience that has to
act on both — builds are failing AND there is now a cache — had to
find them in two places.
* A TL;DR line read 'it repaired itself on no retry', which says the
opposite of what it means.
Checked and left alone: the Gaming Mode 'Switch to Desktop' entry is
presented as a bug users hit, and that is right — v0.30.0's takeover
does stop the display manager on mask-fragile flavors
(gamescope.rs:259 at the tag), so it shipped. Only the mask-vs-stop
detail moved inside this cycle.
Gates: fmt clean, punktfunk-core --lib 273 passed, cargo metadata ok,
Play notes 456/500 and unique, voice scan finds no internal names in the
notes body.
170 -> 173 commits since v0.30.0 (115 non-merge, counted on this branch).
One is user-facing and is in the notes: the web console's Virtual
displays page rendered the Streamed-screen and session-lifetime cards
below the tab shell, so both tabs showed them and the Live tab read as
a duplicate of Configuration. They are policy surfaces and now sit
inside Configuration.
The other three are CHANGELOG-only: the guides trim's second round, the
fifth get-started screenshot (a client's host list), and the workflow
change that made it reachable — linux-client-screenshots now publishes
its PNGs to the generic registry as well, because the v3 artifact store
is browser-only and nothing could pull the shots out of it.
The CI bullet also records this branch's own retry.sh wrapping, since a
reader hitting 'Fail extracting tarball' deserves to find the diagnosis
rather than repeat it.
Gates re-run on this tip: fmt clean, punktfunk-core --lib 273 passed,
Play notes 456/500, both openapi copies identical at 0.31.0.
docs-site died on `error: Fail extracting tarball for
"@rolldown/binding-linux-x64-gnu"` (run 19630, 2026-08-20). The message
points at the package; the package is fine.
MEASURED, because the message invites the wrong fix:
* The tarball's sha512 matches docs-site/bun.lock exactly, and it is
an ordinary 3-entry npm tgz — same gzip framing, same modes, no pax
headers — as the 1.2.0 one that installs fine. Only the payload
differs in size (20.6 MB vs 19.0 MB of .node).
* bun 1.3.13 AND 1.3.14 both extract that exact tarball from disk in
under 80 ms. So it is not the bun bump the floating oven/bun:1 tag
brought in, and not a format bun stopped accepting.
* In the SAME run, the web job installed the same registry over the
same network and passed — it was 25 s ahead of docs-site.
* Run 19632, seven minutes later, installed the identical lockfile
and passed.
So: a transient truncation, not a bad package. bun streams
download-and-extract, so a tarball cut off mid-stream surfaces at the
extract step and names the package it was reading — which is why this
looks like `@rolldown/binding-linux-x64-gnu` is broken and why the
obvious fixes (bump rolldown, pin bun, refresh the lockfile) would all
have "worked" by changing which bytes were in flight, and none of them
would have fixed anything.
scripts/ci/retry.sh already exists for precisely this and its header
already diagnosed it: "the runner box executes many jobs in parallel and
its network drops packets under that load … Wrap every single-shot
network command in CI with this instead." `bun install` is a single-shot
network command and was the one class still unwrapped, so it is wrapped
now at all nine Linux sites — ci.yml (web, docs-site), arch, deb, rpm,
web-screenshots, sdk-publish and plugin-kit-publish (both installs).
3 attempts, not retry.sh's usual 5: a genuinely stale lockfile fails
deterministically under --frozen-lockfile, and 10s+20s of backoff is
enough to outlive a load burst without making that honest failure wait
a minute and a half.
The two windows-host.yml installs are left alone: pwsh, and a Windows
box that is not the contended runner.
Verified: all seven workflows still parse; the helper resolves from
web/, docs-site/ and sdk/ (the three working-directory shapes used);
the wrapper recovers a command that fails once and succeeds on the
retry; and `bash ../scripts/ci/retry.sh 3 bun install --frozen-lockfile
--ignore-scripts` in docs-site installs all 1138 packages, so the
lockfile is sound and the wrapper does not change the command.
Not done, deliberately: docs-site's lockfile still pins rolldown 1.1.2
where web has 1.2.0. That difference is real but it is not this bug,
and refreshing a lockfile to chase a network flake would have buried it.
An Android TV's only input is its remote — a D-pad, OK and Back — and the
console bound both Settings and the game library to face buttons that
remote does not have. X opened Settings, Y opened the shelf, and neither
event could be produced: the Kotlin bridge emits Move/Confirm/Back for a
remote and nothing else, the carousel's only action tiles are Add Host and
Rescan, and the hint chips that also carry those actions need a finger on
a touchscreen. So on a TV the two were simply unreachable. This is the
gap the deleted Compose home used to paper over with its own "no face
buttons" mapping, and the same wall Apple hit on the Siri Remote.
Down on the carousel now opens Settings — the other free direction beside
up, which already opens the host menu. It is a second route on a pad and
the only route on a remote, so the hint bar names the one the device in
hand actually has: ▼ with no pad attached, X with one. That is the whole
extent of the legend change; Y still opens the library and still says so.
The shelf gains a Library row on the host's own options menu, which up
reaches, offered on exactly the terms Y offers it (saved AND paired). It
replaces the menu rather than stacking on it, so Back from the shelf lands
on the carousel and not on a menu about the host just left. This is also
the route `docs/game-library.md` has been describing all along — "open its
options and choose Library" — which until now did not exist.
▼ is a new hint glyph: the ▲ triangle stood on its head rather than a
second drawing routine, and pressable in the hint bar exactly as ▲ is.
ROOT CAUSE of every gamescope symptom chased today. nixpkgs WRAPS this package:
makeWrapper leaves the real compositor ELF at bin/.gamescope-wrapped and
installs a small launcher at bin/gamescope that sets PATH (xwininfo) before
exec'ing it. Our prune kept only `gamescope`:
find $out/bin -mindepth 1 ! -name gamescope -delete
so it deleted the compositor and shipped the launcher pointing at a path that
no longer existed. MEASURED (run 19622): $out/bin held one 16 KB file, and
`strings` on it showed the PATH prologue and '/bin/.gamescope-wrapped'.
That single line explains all of it:
* `--version` printed NOTHING — the launcher exec'd a deleted target. I had
attributed this to the build sandbox, and to upstream's PrintVersion()
landing after 3.16.25. Both were wrong.
* the +pfhdr marker was 'missing from the binary' — a wrapper carries no
version string, so it never could have been there.
Keep the target through the prune, and assert on the WRAPPED ELF rather than
the launcher (which would otherwise pass or fail by accident). The launcher
references its target by absolute path, so renaming the launcher stays safe.
The guards were right on every run; they were reporting a genuinely broken
artifact, not a flaky check.
The Interface section owned two facts this changes: which surfaces carry
"Gamepad-optimized browsing" (the Android console home carries it now, so
that home can be left from inside it) and what an Android TV sees — the
mode row used to be described as present-but-inert there, and both rows are
simply absent now.
The Android console's settings screen had a picker for WHEN it fronts the
app but no switch for WHETHER it does — that lived only in the touch
settings, which a user already inside the console has no way to reach.
The console UI became the only UI on Android, so the way back out was a
setting you could only change from the thing you were trying to get to.
Adds the "Controller-optimized UI" row over the same `gamepadUiEnabled`
the touch switch writes, folded through `extra` under
`android.gamepad_ui_enabled` like the other Android-only rows. Off
returns to the touch home immediately: the console's save bumps the
snapshot generation, the host emits its settings event, and Kotlin's
`applySettings` now folds the flag back into the App state that
`gamepadUiActive` reads.
Shown only where "off" has somewhere to land. `ConsoleOptions.fallback_ui`
(new, threaded to `Ctx` beside `deck`) is true only for the Android touch
shell — false on a TV and for the desktop session, where this console IS
the interface and an off switch would strand the user in nothing.
The mode row follows the same rule and moves under it: it decides nothing
on a TV (the tv term satisfies `gamepadUiActive`'s OR on its own) or while
the switch is off, so it is hidden in both cases rather than offered as a
control that changes nothing. Renamed to the touch screen's own word for
it, "Show it" — "Controller UI" directly under "Controller-optimized UI"
was two rows told apart by their tails.
The marker is not in the installed ELF, and patch 0005 applies cleanly to a
src/meson.build that still carries the exact line it rewrites. Those two facts
cannot both be reasoned from the log as it stands, so stop guessing and
instrument the two stages separately:
* postPatch now asserts +pfhdr is in src/meson.build after our vcs_tag
substitution — the same gate build-punktfunk-gamescope.sh applies. If it
fires, patch 0005 or the substitution lost the marker, and it prints the
version block as patched.
* the installCheck failure branch now prints evidence instead of an
assertion: $out/bin, anything under $out mentioning pfhdr, and the
version-shaped strings actually present in the binary.
Whichever fires, the next run says which stage drops it. Each guess here costs
a full compositor build, and I have now spent three on this one symptom.
The Streamed screen and session-game lifetime cards sat BELOW the tab
shell, so they rendered on both tabs — from the Live displays tab the
page read as the Configuration tab's content duplicated (reported the
other way round, same sight). Both are policy surfaces, so they ride
inside the Configuration tab as siblings of the config card; the Live
tab is now only the live list + arrangement.
`--version` produces EMPTY output under nix's build sandbox — measured on BOTH
nixpkgs' 3.16.25 and the pinned 5fb8dce4 (runs 19551 / 19573 / 19594). It is a
sandbox property, not a defect: gamescope calls PrintVersion() before the getopt
loop (src/main.cpp:721), so `gamescope --version` does print the banner on a
real system, which is what the host's capability probe reads. My earlier claim
that the probe itself was broken was wrong.
packaging/gamescope/build-punktfunk-gamescope.sh already avoids running the
binary, asserting on src/meson.build instead. Grepping the installed ELF is
strictly stronger than either: the version string reaches .rodata via
GamescopeVersion.h's k_szGamescopeVersion, so this proves the marker survived
patching, meson configuration and compilation into the artifact we ship — and it
cannot be defeated by the binary being unable to start.
The src pin from the previous commit stays. It is still right for its own
reason: the patches are authored against 5fb8dce4, nixpkgs' 3.16.24 could not
take patch 0009 at all, and every other channel ships this exact commit.
Saved hosts with their pairing state + an unpaired host found on the network, from
linux-client-screenshots run 19593 via the new generic-package publish (fixed 'ci' version,
anonymous GET), cropped to the cards. Completes the handoff's screenshot list: console login,
Waiting for approval + PIN, the Approve dialog, live status, and a client's host list.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
#320 merged but v0.31.0 was never tagged, and 69 more commits (41
non-merge) landed on top of it. The version stays 0.31.0 and Cargo.toml
does not move; the notes, Play notes and CHANGELOG section are
re-measured on the new tip.
THE NUMBER IS NOW FORCED, where the first cut's was a judgement call.
The C ABI moves 24 -> 25: punktfunk_set_log_callback plus the
PunktfunkLogCb typedef (#338's core half), so an embedder can hear the
core's tracing lines. Addition only — no declaration moved, no repr(C)
struct grew a field, and an embedder that never calls it is byte-
compatible with v24. include/punktfunk_core.h is therefore NO LONGER
byte-identical to the v0.30.0 tag, which the first cut's table and both
"nothing versioned moves" paragraphs claimed.
Table re-measured on d801cb72. Two rows changed since the first cut and
two were already corrected in-tree by their own commits:
* C ABI 24 -> 25 (above).
* api/openapi.json 0.29.0 -> 0.31.0 — the STAMP only. No management
surface moved; the file had been left two versions stale and #337's
regenerate-and-diff caught it. Both copies cmp identical.
* SDK 0.1.5 and plugin-kit 0.4.3 were cut during the cycle (#348,
#334), so the rows the first cut wrote as "owed" are now past tense.
The registry still skips 0.4.2 on purpose.
Everything else holds: wire 2, driver protocol 6 / min 3, gamepad
channel 3, plugin index schema 1, host event schema 1, edition 2024,
MSRV 1.85, 27 crate dirs, gamescope +pfhdr8 with no new patches. The
PKGBUILD pfhdr7 discrepancy is unchanged and still pre-existing.
REWRITTEN RATHER THAN APPENDED TO, because the intervening work never
shipped and a user must not read a within-cycle correction as a second
bug:
* The Gaming Mode takeover section. The first cut described "stops the
login manager first, then steps in" — which #342 replaced before
shipping, after a field report that a stopped display manager leaves
the box unable to service Steam's own Switch to Desktop (it hung
until reboot, and could not even be detected around: every trace of
that switch is written by the component we had stopped). End state:
idle the autologin over the gamescope-session-plus@ template, leave
the DM running. #343 then deleted the whole 142-line stop/linger
chain the old approach needed. Two shipped facts became false with
it — the takeover no longer stops the DM and no longer needs the
punktfunk group (that group still gates the usbip pad nodes) — and
the notes' Before-you-update says so for Deck/Bazzite operators.
* The Android ASC entries. HDR seeded from the codec's echo, untagged
SDR raising blacks to grey, and the console's dispose re-showing the
system bars over the stream are all regressions against THIS cycle's
unreleased presenter, so they are folded into the Android story, not
listed as fixes users hit.
NEW USER-FACING WORK, in rough order of how much it changes:
* Windows client (#349): the default download becomes a signed
per-user Inno Setup installer + portable zip; MSIX stays for the
Store. This is the Steam fix — MSIX puts the exe under WindowsApps,
which Steam's picker cannot browse, and alias activation defeats
overlay injection. Before-you-update carries the one action in the
release: an MSIX user who wants it must Remove-AppxPackage first and
will re-pair once, because pairing identity lives with the package.
* install.sh (#345/#346): one command from nothing to a pairable Linux
host, running platforms.json's lines verbatim, with Sunshine
coexistence, --dry-run, --uninstall and env twins. Shipped PREVIEW
on purpose and the notes say so.
* Send logs to host completes on Apple (#338) and Android (#339) — the
two legs 0.30's notes named as follow-ups.
* KWin 6.6 (#344/#331): it refuses to stream an output it created
disabled, in the session's language, logged nowhere, and persists
the disable against the stable per-client name so it repeats
forever. Enable and retry; and a translated refusal no longer burns
all 8 retries.
* Deck Wake-on-LAN (#347, closes#322), portable Playnite covers
(#330), plugin-kit republish on startup/manual (#334), console touch
gestures and idle gates (#333), cancel-connect (#329), NixOS host
builds failing outright (#328 + #332 + #336).
* Docs overhaul (#337/#340/#343/#346): get-started track, Switching
from Sunshine, screenshots, and data/platforms.json as the single
source for install facts with seven CI drift gates over it.
Gates on this tree: cargo fmt --all --check clean (no drift this time —
the first cut needed a whitespace commit, which is already in main);
cargo metadata --offline ok; cargo test -p punktfunk-core --lib 273
passed; Play notes gate verbatim 456/500 and unique; voice scan clean
outside For developers; both openapi copies cmp identical at 0.31.0.
⚠ The C ABI harness still did not run here — no libopus on this MacBook
— and this time the header DID change, so ABI 25's C compile is owed to
CI. Named in Verification status rather than left to be found.
⚠ Owed outside this repo: platforms.json changed (the Windows download),
so punktfunk-website needs `bun run sync-platforms` committed — the step
#346 added to docs/releases/README.md, and this is its first exercise.
The category sacrificed, per page (RFC 'screenshots over prose' / phase-2 handoff item 3):
- client-settings.md (4368→3144 words): the why-rationale narrative around each setting; every
default, number, availability list, env var and link stays.
- virtual-displays.md (3724→3015): status/history notes (the 'What's live today' tracker
paragraph, 'Windows has always lingered 10 s') and design rationale; compositor-specific
operational facts stay.
- plugins.mdx (2835→2418): narrative duplication — restart instructions stated twice, story
asides the linked plugin repos carry.
- input.md (2499→2403) and wake-on-lan.md (2286→2186): rationale asides and historical notes
('the plugin used to fire a packet itself…'); these two are per-platform fact tables end to
end, so only a light pass was honest.
15712→13166 words over the five biggest Guides (−16%). Zero heading changes (anchors stable),
docs-drift + docs-links green, docs-site build + lint green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
nix was the ONLY channel not pinning the compositor — the RPM spec, the
PKGBUILD, build-punktfunk-gamescope.sh and packaging/gamescope/README.md all
ship 5fb8dce4 (3.16.25-11), while gamescope.nix patched whatever version
nixpkgs happened to carry. That produced two failures in two days, both the
same bug:
* nixpkgs shipped 3.16.24, where patch 0009's context does not exist, so the
build died at patchPhase. host.gamescopeHdr defaults true, so every
`services.punktfunk.host.enable = true` failed the same way.
* bumping the lock to 3.16.25 fixed the patches, and then --version printed
NOTHING. Upstream's `gamescope::PrintVersion()` landed AFTER the 3.16.25
tag; in that tag `--version` is `return 0;` with the comment "We always
print the version to stderr anyway". The host reads that banner to decide a
session's bit depth and cursor compositing BEFORE the virtual display
exists, so a silent banner is a silent fall back to SDR.
The installCheck was right to fail — this was not a check problem.
Also in this commit: the +pfhdr guard now prints the banner it read. That is
how the empty output was identified at all; without it the failure is
indistinguishable from the binary not starting, at ~15 min per guess.
vcs_tag now substitutes the PINNED version (old.version is the pre-override
attr and would still say 3.16.25).
nix-instantiate --parse clean. Hash from nix-prefetch-git --fetch-submodules.
A user report: launching via Big Picture doesn't work and the Steam overlay never appears.
Not because the app is UWP (it's full-trust Win32 under MSIX too) but because of the MSIX
install SHAPE: the exe lives under the ACL'd WindowsApps dir Steam's non-Steam-game picker
can't browse, and alias/shell:AppsFolder activation defeats the overlay's injection — Steam
must spawn the exe itself from a normal path.
- punktfunk-client.iss: per-user (no UAC) install to %LOCALAPPDATA%\Programs\Punktfunk.
Re-creates the manifest's grants in HKCU (punktfunk:// scheme, Start entries, {app} on the
user PATH for the punktfunk CLI) and fetches the Windows App Runtime when missing.
- pack-client-installer.ps1: consumes pack-msix.ps1's layout (one assembly, three artifacts),
signs the four exes individually, emits setup.exe + a portable zip. Same signing backends
and fail-closed-on-tags rule as the sibling scripts; no .cer (an exe runs untrusted).
- windows-client.yml: pack step after the MSIX, publish + release-attach the new artifacts
(canary/latest aliases punktfunk-client-setup_<arch>.exe, ..._<arch>-portable.zip).
- deeplink.rs: write_shortcut targets the app-execution alias only under package identity;
unpackaged installs have no alias but a stable path, so they target current_exe().
has_package_identity() now shared with main.rs's AppUserModelID probe.
- docs: install-client (installer default + a 'Launching through Steam' section + MSIX/portable
as alternates), channels, uninstall, clients, platforms.json (both copies, drift check green).
v0.31.0's changelog recorded this cut as owed and said why: plugins resolve
`@punktfunk/host` from the registry, so a fix sitting in `sdk/` reaches nobody
until a version carries it. Four commits have touched the SDK since sdk-v0.1.4,
the headline one being the mgmt-port fix — a moved `PUNKTFUNK_MGMT_BIND` left
every plugin and the tray dialing 47990.
`SDK_VERSION` moves with it. It is a hand-maintained constant (the bundled
runner has no package.json to read at runtime), and the runner compares it
against the SDK actually installed in the plugins tree to decide whether to
reinstall — so shipping 0.1.5 with the constant still reading 0.1.4 would have
published the fix and then never delivered it. `version.test.ts` exists for
exactly this and caught it.
Gates: 83/83 SDK tests pass.
The memory raise got gamescope building, and it now reaches installCheckPhase
and fails there:
punktfunk-gamescope: the +pfhdr marker is missing — the patches did not take
Patch 0005 applied cleanly to src/meson.build in that same run, so the message
is misleading: the patch DID take. Two very different causes are
indistinguishable from the log as written —
* the binary never ran (shrunk RPATH, missing loader dep), so --version
printed nothing at all; or
* it ran and printed a version without +pfhdrN, meaning upstream no longer
builds the banner from VCS_TAG.
A guard that reports 'missing' without showing what it read cannot be acted on,
and each guess costs a full compositor build. Capture the output and print it on
failure, with a note on how to read the two cases apart.
No behaviour change: same assertion, same exit. Also verified in this run: the
chmod fix works (prune, rename and layer install all completed) and the WSI
layer is installed.
Phase 2 of the docs-and-onboarding overhaul (items 1-partial, 2 and 4 of the handoff):
install.sh: --uninstall reverses step 1 + step 6 per family (user units off first, only the
punktfunk packages actually installed, then the repo; config/groups/firewall stay, as
/docs/uninstall states) — smoke-tested as a new installer-smoke step on all three families.
The end-of-run check now catches the two NVIDIA silent failures on every family: no driver at
all, and a module the kernel refused to load (Secure Boot) via an nvidia-smi probe pointing at
the troubleshooting anchor; the Fedora ffmpeg-libs/NVENC warning folds into the same block.
check-docs-drift.sh gate 7: the manual 16-file os-release matrix PR #345 was verified with,
committed — every family's detection, its install line, its removal line and the four
unsupported pointers run through the real script under --dry-run on every push (docs-drift's
container gains curl, the script's own prerequisite).
Screenshots (RFC: "screenshots over prose"): four console shots captured from the same
storybook-fixture pipeline web-screenshots.yml runs — login and the armed Pairing page into
quickstart.md, the Approve dialog (access level + expiry + guest fast-path) into pairing.md
replacing the prose that described it, live status into web-console.md. Files under
docs-site/public/img/, dark-theme, bundled+preloaded by the docs build (verified served).
Still missing: a client host-list shot — linux-client-screenshots run 19546 built it, but its
artifact isn't API-downloadable; add it when a browser session can fetch the zip.
WP5 rider: the release-flow docs-freshness step now includes the website content look-over.
NOT flipped: installer stays preview — the handoff gates the default flip on real-box mileage
(Bazzite above all), which a Mac can't provide.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
On KWin >= 6.6 `streamVirtualOutput` creates the output on the backend and then
passes `workspace()->findOutput(output)` to the stream, which is null for an
output the workspace does not manage (`wantsToManage` = `isEnabled() &&
!isNonDesktop()`). So an output KWin creates DISABLED is refused with
"Could not find output" — translated into the session's language, and logged
nowhere, because disabling an output is a perfectly valid configuration that
applies successfully. 6.4/6.5 passed the backend output straight through and
streamed it either way.
It repeats forever. The host asks for a STABLE per-client output name precisely
so KWin persists that client's scale and mode against it, so a stored setup
naming it `enabled: false` is reapplied to every future session for that client
— and the user cannot fix it in System Settings, because the output only exists
for the few milliseconds the request is alive.
Repair it instead. On a refusal, enable the head over kde_output_management_v2
and let the retry go again. Two properties of KWin make that possible, both read
off Plasma/6.7 rather than assumed:
* `sendFailed` only sends the event — it does not emit `finished`, and
`removeVirtualOutput` is wired to `finished`. The disabled output therefore
stays alive for as long as we hold the failed stream open, which is the
window the repair runs in (and why it must run inside the worker thread,
before the connection drops).
* `WaylandServer::handleOutputAdded` offers EVERY backend output to the
output-device registry, gating only placeholders and non-desktop ones. Only
`wl_output` is gated on being enabled, so a disabled output is invisible to
`stream_output` but fully addressable over output management.
Enabling it is a user-applied configuration, so KWin persists it against that
output's identity: the retry's fresh request finds a stored setup that enables
it. The repair therefore fixes attempt N+1, never attempt N.
`REPAIRED_HINT` keeps that retry reachable. The opener wraps every worker error
with "KWin virtual output failed", which is the phrase the host's
`is_permanent_build_error` matches to short-circuit the retry loop — so a
repaired refusal carrying it would be classified permanent and the retry that
consumes the repair would never run, making the whole path dead code. A repaired
refusal is reported verbatim without that wrapper; an unrepairable one keeps it
and still fails fast, because nothing about the box changed. The host-side test
pins both halves.
Every wake gate in the codebase reads `!host.mac.is_empty()` against the saved
record — `ConnectPlan::wake`, the console's `can_wake`, `punktfunk wake`. That MAC
only ever reached the store through `trust::learn_mac`, and `learn_mac` had exactly
two callers: the GTK hosts page and the WinUI one.
Neither runs on a Steam Deck. Gaming Mode has only the Decky panel (which drives the
headless CLI) and the console home — and those learned the management port alone,
never the MAC. So a Deck's records stayed MAC-less forever, every wake gate stayed
false, and Wake-on-LAN was skipped silently: no packet, no error, nothing to see.
It worked on desktop purely because those two hosts pages learn on each discovery
tick. (#322)
Rather than add the missing call twice, collapse the three per-field learners
(`learn_mac`, `learn_os`, `learn_mgmt_port` — three `pub fn`s, three load/save
cycles) into one `learn_from_advert`, and call it at every site where an advert
meets a saved record: both desktop hosts pages, the console home, and the CLI's
`discover`. Remembering one call is not a thing a front-end can half-do; remembering
three is what produced this. It takes the three fields rather than a `DiscoveredHost`
because there are two of those — core's and the WinUI shell's verbatim port.
`discover` is where the panel-only flow is fixed: it is the one verb the Decky panel
runs that ever sees an advert. It keeps `KnownHosts::read()`, so it still mints no
ids and cannot join the race that comment warns about, and `learn_from_advert` writes
only when an advert genuinely taught the record something — a steady-state panel
refresh touches no disk.
Two things fall out of the same root cause: the console home now persists the OS
chain too, so a Deck host's icon stops vanishing the moment mDNS goes quiet; and
`punktfunk wake`'s "connect to it once while it's awake" is replaced, since a MAC
comes from an advert and never from a connect — that wording sent this diagnosis
looking in the wrong place.
The magic-packet sender itself was never at fault (`punktfunk-core::wol` passes its
7 tests) and neither was the flatpak sandbox (`--share=network`). Nothing reached
them.
Closes#322
2026-08-19 14:16:14 +02:00
677 changed files with 69578 additions and 6872 deletions
if grep -q "STARTING A FULL BUILD" /tmp/android-clippy.log; then
echo "::error::skia-bindings did not get its prebuilt archive and started building Skia from source — the download was dropped (see DOWNLOAD AND INSTALL FAILED above). This is a fetch failure, not a lint failure."
exit 1
fi
exit $rc
# The kit's JVM unit tests — the pure parsers, migrations and feedback policies. They were
# running nowhere: this workflow only assembled, and android-screenshots.yml runs the :app
# Error: Failed to update org.freedesktop.Sdk.Extension.rust-stable: While pulling …
# .filez: Server returned HTTP 404
# dl.flathub.org served a 404 for one object of the then-current rust-stable//25.08
# commit, deterministically — all 10 retry.sh attempts died on the SAME object over
# ~9 min — and flatpak-builder SEGFAULTED on its own error path (rc=139), so retry.sh
# saw a crash rather than a clean "this will never work" either. The build never wanted
# that newer commit: the manifest pins a runtime VERSION, not a commit, and the baked
# one satisfies it. Updating bought nothing and imported an upstream outage.
#
# So: assert what the image already has, and reach for Flathub only on a real miss —
# the same "guard, don't install on top of a stale image" doctrine as the Tooling step.
# The check lives in scripts/ci/flatpak-deps-present.sh (run its --self-test after
# touching it): a bug in it that reports "satisfied" when it is not would build against
# whatever runtime happened to be lying around, which is worth more than an inline
# if-statement. It deliberately fails OPEN — anything it cannot parse takes the slow
# install path below.
if bash scripts/ci/flatpak-deps-present.sh "$MANIFEST"; then
echo "deps satisfied by the baked image — not touching Flathub"
flatpak list --user --columns=ref
else
echo "::warning::$MANIFEST declares deps punktfunk-flatpak-ci does not have — pulling from Flathub (~1.5 GB). Bump GNOME_VERSION/FREEDESKTOP_VERSION in ci/flatpak-ci.Dockerfile so this stays off the hot path."
if [ -z "${FLATPAK_GPG_PRIVATE_KEY:-}" ] || [ -z "${DEPLOY_HOST:-}" ]; then
echo "::warning::FLATPAK_GPG_PRIVATE_KEY/DEPLOY_* not set — skipping repo deploy (bundle still published)."
if [ -z "${FLATPAK_GPG_PRIVATE_KEY:-}" ] || [ -z "${DEPLOY_HOST:-}" ] || [ -z "${DEPLOY_KNOWN_HOSTS:-}" ]; then
echo "::warning::FLATPAK_GPG_PRIVATE_KEY/DEPLOY_*/DEPLOY_KNOWN_HOSTS not set — skipping repo deploy (bundle still published). See packaging/nix/README.md for the host key."
exit 0
fi
# 1) Import the signing key into a throwaway keyring; sign the repo.
@@ -437,7 +494,13 @@ jobs:
# objects so clients mid-update aren't broken; the fresh signed summary advertises latest.
| **Windows host** (Windows 11 22H2+, x64) | ✅ Beta — shipping as a signed installer: its own all-Rust IddCx **virtual display** (secure-desktop capable) with a **sealed IDD-push** capture path — finished frames pushed straight into its own driver, not screen-scraped (no DDA/WGC) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. NVIDIA live-validated; AMD/Intel CI-green |
| **Windows host** (Windows 11 22H2+, x64) | ✅ Beta — shipping as a signed installer: its own all-Rust IddCx **virtual display** (secure-desktop capable) with a **sealed IDD-push** capture path — finished frames pushed straight into its own driver, not screen-scraped (no DDA/WGC) · GPU encode (NVENC on NVIDIA, AMF/QSV on AMD/Intel, software H.264 without a GPU) · WASAPI audio · bundled virtual-gamepad drivers (no ViGEmBus) · HDR incl. Vulkan-game HDR. All three vendors validated on real hardware; NVENC has the most field time |
| **macOS / iOS / tvOS client** (`clients/apple`) | ✅ Streaming live: VideoToolbox decode (HEVC, and AV1 on hardware that decodes it), controllers incl. DualSense, discovery, pairing, speed test |
| **Linux client** (`clients/linux` + `clients/session`) | ✅ Streaming live: relm4/GTK4 launcher shell that spawns a Vulkan session binary — Vulkan Video / VAAPI / software decode, PipeWire audio, SDL3 controllers, Skia console UI; ships as Flatpak/apt/rpm/Arch |
Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2022 as part of Feather (MIT). All other copyright (c) for Lucide are held by Lucide Contributors 2022.
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
"description":"The actions this host offers, as seen by the caller: platform availability (with the honest\nreason when something can't run) and whether THIS caller is permitted to invoke each one.\nAdmin lane: everything permitted. Paired-cert lane: permission follows the device's live\naccess mask (the Host power grant). Clients render rows generically — unknown ids still\nwork with the server-supplied title.",
"operationId":"listActions",
"responses":{
"200":{
"description":"The actions, per-caller",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ActionList"
}
}
}
},
"401":{
"description":"Missing or invalid credentials",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/actions/{id}":{
"post":{
"tags":[
"actions"
],
"summary":"Invoke a host action",
"description":"Runs one action by id — empty body, no parameters: the id selects a fixed host-side\nbehavior, and nothing in the request reaches the privileged path. On `202` the host first\nends every streaming session cleanly (clients see a typed \"the host is going to sleep /\nshutting down\" close), waits ~1 s so this response flushes, then acts.\n\nPaired-cert callers need the **Host power** grant, and are refused (`409`) while another\ndevice's session is live — a granted guest cannot yank the host out from under the owner\nmid-stream. The admin console is never blocked (it warns instead). One action runs at a\ntime host-wide.",
"operationId":"invokeAction",
"parameters":[
{
"name":"id",
"in":"path",
"description":"Action id (`power.sleep`, `power.reboot`, `power.shutdown`)",
"required":true,
"schema":{
"type":"string"
}
}
],
"responses":{
"202":{
"description":"Accepted — sessions are being ended and the action follows in about a second"
},
"401":{
"description":"Missing or invalid credentials",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
},
"403":{
"description":"This caller's access does not include this action (no Host power grant)",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
},
"404":{
"description":"Unknown action id",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
},
"409":{
"description":"Refused: an action is already in flight, another device's session is live (cert lane), or the platform said no (a foreign sleep inhibitor, a second local user, …)",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
},
"501":{
"description":"This host platform has no executor for it (macOS host)",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/client-logs":{
"get":{
"tags":[
@@ -364,6 +472,77 @@
}
}
}
},
"patch":{
"tags":[
"clients"
],
"summary":"Rename a paired client",
"description":"Sets or clears the operator-visible display name for one paired Moonlight client. This is\npurely cosmetic — it touches no certificate and no trust decision — but it is the only way to\ntell paired devices apart: every moonlight-common-c client self-signs with the identical\nsubject `CN=NVIDIA GameStream Client`, so an unnamed list is a row of clones distinguishable\nonly by fingerprint. The name is stored beside the pairing store and survives host restarts;\nunpairing the device forgets it.",
"operationId":"renameClient",
"parameters":[
{
"name":"fingerprint",
"in":"path",
"description":"Hex SHA-256 fingerprint of the client certificate DER (64 chars, case-insensitive)",
"required":true,
"schema":{
"type":"string"
}
}
],
"requestBody":{
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/RenameClient"
}
}
},
"required":true
},
"responses":{
"200":{
"description":"The client as it now reads",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/PairedClient"
}
}
}
},
"400":{
"description":"Malformed fingerprint",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
},
"401":{
"description":"Missing or invalid bearer token",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
},
"404":{
"description":"No paired client with that fingerprint",
"content":{
"application/json":{
"schema":{
"$ref":"#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/compositors":{
@@ -1860,6 +2039,69 @@
}
}
},
"/api/v1/library/provider/{provider}/running":{
"put":{
"tags":[
"library"
],
"summary":"Report which of a provider's titles are running",
"description":"The **live** counterpart to the `detect` hints in a reconcile payload: that one says *how to\nrecognize* a title's process, this one says *it is running now* (design §9,\n[`crate::runstate`]). For a provider that starts games itself and knows when they stop —\nPlaynite tracks every launch and fires an event on both edges — this is a fact the host would\notherwise have to re-derive by scanning, and for a title with nothing to scan for (an emulated\ngame, a manually added one) could not derive at all.\n\nDeclarative and idempotent, like the reconcile: the body is the provider's **complete** running\nset, so a missed event, a plugin restart or an install mid-game all self-correct on the next\nreport rather than drifting.\n\nThe report **expires** after `ttl_s` (90s) unless restated, which is what makes it safe for a\nlive provider to keep a streaming session open for a game the host cannot see: a plugin that\ndies with a game running stops counting shortly after, and the host falls back to process\nscanning exactly as it does without one. Re-report on every change **and** on a timer well\ninside the window.\n\nTitles the provider does not currently publish are ignored (counted in `unknown`), not an error:\na report may legitimately race its own reconcile.",
"operationId":"reportProviderRunning",
"parameters":[
{
"name":"provider",
"in":"path",
"description":"The provider id ([a-z0-9._-], `manual` reserved)",
"description":"One action as the caller sees it (`GET /actions`).",
"required":[
"id",
"title",
"group",
"danger",
"available",
"permitted"
],
"properties":{
"available":{
"type":"boolean",
"description":"Whether this host can run it right now (platform probe — a VM that can't S3 lists\nsleep as unavailable rather than offering a dead switch)."
},
"danger":{
"type":"boolean",
"description":"Whether a client UI should double-confirm (the action loses state — reboot/shutdown)."
},
"group":{
"type":"string",
"description":"Action group (`power` for the built-ins)."
},
"id":{
"type":"string",
"description":"Stable action id (`power.sleep`, …) — the invoke path parameter.",
"example":"power.sleep"
},
"permitted":{
"type":"boolean",
"description":"Whether THIS caller may invoke it (admin lane: always; cert lane: the `GRANT_POWER`\nbit of the device's live access mask)."
},
"title":{
"type":"string",
"description":"Display title. Clients localize known ids and fall back to this for unknown ones."
},
"unavailable_reason":{
"type":[
"string",
"null"
],
"description":"Why it is unavailable, when it is."
}
}
},
"ActionList":{
"type":"object",
"description":"`GET /actions` response.",
"required":[
"actions"
],
"properties":{
"actions":{
"type":"array",
"items":{
"$ref":"#/components/schemas/ActionInfo"
}
}
}
},
"ActiveGame":{
"type":"object",
"description":"One launched game, for the console's running-game card.",
@@ -5401,7 +5704,7 @@
},
"pnp_disable_monitors":{
"type":"boolean",
"description":"EXPERIMENTAL (Windows): DISABLE physical monitors' PnP device nodes forthe stream's\nduration (persistently, so a standby monitor/TV whose hot-plug events re-arrive stays\ndisabled) and re-enable them at teardown. Two selectors: the monitors an `Exclusive`\nisolatedeactivated, plus — in ANY topology — external monitors that are connected but not\npart of the desktop (the standbyTV that was never active, whose input auto-scan /\ninstant-on HPD cycling re-probes thelink every few seconds). Targets the same\n\"connected-but-dark head\" periodic-stutter class as [`Self::ddc_power_off`], but at the\nWindows-reaction level: a disabled devnode's wake events trigger no PnP arrival, no CCD\nre-evaluation, no DWM invalidation. A crash-recovery journal re-enables leftovers on host\nstartup. Orthogonal to `preset` (like `game_session`); `#[serde(default)]` = off."
"description":"EXPERIMENTAL (Windows): DISABLE the OPERATOR'S OWN physical monitors' PnP device nodes for\nthe stream'sduration (persistently, so a monitor whose hot-plug events re-arrive stays\ndisabled) and re-enable them at teardown — the monitors an `Exclusive`isolate\ndeactivated. Still opt-in, because it takes displays the operator was actually using.\n\nThe *other* selector — external monitors connected but part of NO topology (the standby\nTV that was never active, whose input auto-scan /instant-on HPD cycling re-probes the\nlink every few seconds) — no longer needs this flag: it runs by default, see\n[`standby_sink_neutralise`]. Setting this flag still implies it. Targets the same\n\"connected-but-dark head\" periodic-stutter class as [`Self::ddc_power_off`], but at the\nWindows-reaction level: a disabled devnode's wake events trigger no PnP arrival, no CCD\nre-evaluation, no DWM invalidation. A crash-recovery journal re-enables leftovers on host\nstartup. Orthogonal to `preset` (like `game_session`); `#[serde(default)]` = off."
},
"preset":{
"$ref":"#/components/schemas/Preset"
@@ -6007,6 +6310,42 @@
}
}
},
{
"type":"object",
"description":"A host action was invoked (`design/host-actions.md` §3.3) — v1: the `power.*` verbs.\nEmitted on ACCEPT (`outcome: \"accepted\"`), and again if the executor later fails\n(`outcome: \"failed: …\"`) — a succeeded power action ends this process, so \"accepted with\nno failure after it\" is the success signal a hook can act on (\"the host is going down\").",
"required":[
"id",
"outcome",
"kind"
],
"properties":{
"device":{
"oneOf":[
{
"type":"null"
},
{
"$ref":"#/components/schemas/DeviceRef",
"description":"The invoking paired device, when the cert lane invoked it; absent for the\noperator's console (admin lane)."
}
]
},
"id":{
"type":"string",
"description":"The invoked action id (`power.sleep`, `power.reboot`, `power.shutdown`)."
},
"kind":{
"type":"string",
"enum":[
"action.invoked"
]
},
"outcome":{
"type":"string",
"description":"`accepted`, or `failed: <the executor's error>`."
}
}
},
{
"type":"object",
"required":[
@@ -6625,7 +6964,7 @@
},
"HostInfo":{
"type":"object",
"description":"Host identity and advertised capabilities (static for the life of the process).",
"description":"Host identity and advertised capabilities (static for the life of the process, except\n`local_ip`).",
"required":[
"hostname",
"uniqueid",
@@ -6671,7 +7010,7 @@
},
"local_ip":{
"type":"string",
"description":"Best-effort primary LAN IP."
"description":"Best-effort primary LAN IP, read fresh on every request — a host that started before its\nnetwork did (cold boot) reports `127.0.0.1` only until it actually has an address, and a\nhost that moves networks reports the new one. Poll it rather than caching it."
},
"os":{
"type":"string",
@@ -7312,6 +7651,14 @@
"description":"Lowercase hex SHA-256 of the client certificate DER — the client's stable id here.",
"description":"Operator-assigned display name for this device, if one has been set (`PATCH /clients/{fp}`).\n\nThis is the ONLY thing that can tell two paired Moonlight devices apart in a list, because\ntheir certificates cannot: see [`Self::subject`]. Absent until somebody names the device.",
"example":"Living Room TV"
},
"not_after_unix":{
"type":[
"integer",
@@ -7333,7 +7680,7 @@
"string",
"null"
],
"description":"Certificate subject (e.g. `CN=NVIDIA GameStream Client`), if the DER parses."
"description":"Certificate subject (e.g. `CN=NVIDIA GameStream Client`), if the DER parses.\n\nDo not display this as a device name. Every moonlight-common-c client self-signs with that\nsame fixed subject, so it identifies the *protocol*, not the device — a list of paired\nphones, TVs and handhelds all read identically. [`Self::label`] is the field to show."
}
}
},
@@ -7792,6 +8139,46 @@
}
}
},
"ProviderRunningAccepted":{
"type":"object",
"description":"The result of a liveness report.",
"required":[
"matched",
"unknown",
"ttl_s"
],
"properties":{
"matched":{
"type":"integer",
"description":"How many reported titles matched an entry this provider currently publishes.",
"minimum":0
},
"ttl_s":{
"type":"integer",
"format":"int64",
"description":"Seconds this report stays authoritative without being restated — re-report inside it while\nanything is running.",
"minimum":0
},
"unknown":{
"type":"integer",
"description":"How many were ignored because no such entry exists (a report that raced a reconcile).",
"minimum":0
}
}
},
"ProviderRunningInput":{
"type":"object",
"description":"Request body for `reportProviderRunning`.",
"properties":{
"running":{
"type":"array",
"items":{
"$ref":"#/components/schemas/RunningTitle"
},
"description":"Every title of this provider's that is running **right now**. The full set, not a delta:\nanything absent from it is reported as stopped."
}
}
},
"ReleaseDisplayRequest":{
"type":"object",
"description":"Request body for `releaseDisplay`.",
@@ -7846,6 +8233,42 @@
}
}
},
"RenameClient":{
"type":"object",
"description":"Body of `PATCH /clients/{fingerprint}` — the device's display name.",
"properties":{
"label":{
"type":[
"string",
"null"
],
"description":"The name to show for this device. `null` (or an empty/whitespace-only string) clears it and\nthe device goes back to being listed by fingerprint alone.\n\nScrubbed before storage by the same sanitizer the native plane runs on device names:\ncontrol characters and Unicode bidi overrides are stripped (they could make one paired\ndevice impersonate another in this very list), whitespace collapsed, and the result capped\nat 64 characters.",
"example":"Living Room TV"
}
}
},
"RunningTitle":{
"type":"object",
"description":"One running title in a provider's liveness report.",
"required":[
"external_id"
],
"properties":{
"external_id":{
"type":"string",
"description":"The provider's own stable id for the title — the same key its reconcile payload uses."
},
"pid":{
"type":[
"integer",
"null"
],
"format":"int32",
"description":"The process id the provider started for it, when it knows one. Optional, and never trusted\nas a bare number: the host re-resolves it and pins it to its start time before it is ever\nsignalled, so a stale or recycled pid simply contributes nothing.",
"minimum":0
}
}
},
"RuntimeRequest":{
"type":"object",
"required":[
@@ -8924,6 +9347,10 @@
{
"name":"update",
"description":"Host update check: install kind + channel, the last verified release manifest, and whether a newer host exists (admin lane only)"
},
{
"name":"actions",
"description":"Host actions: discover what this host offers (per-caller availability + permission) and invoke one by id — v1: sleep, restart, shut down the machine, gated per device by the Host power grant"
# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
# Checked by SHA-256, like the bun pin: sccache is RUSTC_WRAPPER, so it sits in front of every
# rustc invocation that produces a SHIPPED binary. Bump SCCACHE_VERSION and SCCACHE_SHA together —
# upstream publishes the sum as <asset>.tar.gz.sha256 next to the release asset.
ARGSCCACHE_VERSION=0.10.0
RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz"\
| tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'\
# bun builds the punktfunk-web console + the punktfunk-scripting runner AND is vendored as
# their runtime (PF_WITH_WEB=1 / PF_WITH_SCRIPTING=1) — so these bytes end up inside the
# package arch.yml signs and publishes. Arch ships bun in [extra], so take the
# pacman-signed package (pacman verifies package signatures by default) instead of piping
# bun.sh's installer into root's shell, which would be upstream code choosing them. Same
# call as arch.yml's bootstrap guard. It rides THIS transaction rather than a later layer
# on purpose: -Syu refreshes the db in the same step that installs, so a cache-hit rebuild
# can never resolve bun against a stale snapshot the mirrors no longer carry.
bun \
&& pacman -Scc --noconfirm \
&& bun --version
# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
# Checked by SHA-256, like the bun pin: sccache is RUSTC_WRAPPER, so it sits in front of every
# rustc invocation that produces a SHIPPED binary. Bump SCCACHE_VERSION and SCCACHE_SHA together —
# upstream publishes the sum as <asset>.tar.gz.sha256 next to the release asset.
ARGSCCACHE_VERSION=0.10.0
RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz"\
| tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'\
# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
# musl build: one static binary serves the Ubuntu and Fedora images alike.
# Checked by SHA-256, like the bun pin: sccache is RUSTC_WRAPPER, so it sits in front of every
# rustc invocation that produces a SHIPPED binary. Bump SCCACHE_VERSION and SCCACHE_SHA together —
# upstream publishes the sum as <asset>.tar.gz.sha256 next to the release asset.
ARGSCCACHE_VERSION=0.10.0
RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz"\
| tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'\
# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
# musl build: one static binary serves the Ubuntu and Fedora images alike.
# Checked by SHA-256, like the bun pin: sccache is RUSTC_WRAPPER, so it sits in front of every
# rustc invocation that produces a SHIPPED binary. Bump SCCACHE_VERSION and SCCACHE_SHA together —
# upstream publishes the sum as <asset>.tar.gz.sha256 next to the release asset.
ARGSCCACHE_VERSION=0.10.0
RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz"\
| tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'\
# Shared compile cache: jobs set RUSTC_WRAPPER=sccache (backend = RustFS S3 on the LAN,
# see .gitea/workflows — the env lives there so dev use of this image stays uncached).
# musl build: one static binary serves the Ubuntu and Fedora images alike.
# Checked by SHA-256, like the bun pin: sccache is RUSTC_WRAPPER, so it sits in front of every
# rustc invocation that produces a SHIPPED binary. Bump SCCACHE_VERSION and SCCACHE_SHA together —
# upstream publishes the sum as <asset>.tar.gz.sha256 next to the release asset.
ARGSCCACHE_VERSION=0.10.0
RUN curl -fsSL "https://github.com/mozilla/sccache/releases/download/v${SCCACHE_VERSION}/sccache-v${SCCACHE_VERSION}-x86_64-unknown-linux-musl.tar.gz"\
| tar -xz --wildcards --strip-components=1 -C /usr/local/bin '*/sccache'\
"Tap a button to change it, drag one onto another to swap."+
if(overridden)" This profile has its own quick actions; the default ring no longer reaches it."else"",
style=MaterialTheme.typography.bodySmall,
color=MaterialTheme.colorScheme.onSurfaceVariant,
modifier=Modifier.padding(start=4.dp),
)
}
// The virtual controller's preset and look (§4.3), written to the blob's `pad` through the
// same path the ring uses.
SettingsGroup(
"Virtual controller",
footer="Shown from the ring's Virtual controller button. A finger on one of its controls drives the game; a finger anywhere else drives the touch mode.",
){
SettingDropdown(
label="Layout",
options=listOf("full"to"Full","sticks"to"Sticks and shoulders","dpad"to"D-pad and face buttons"),
selected=cfg.pad.layout,
caption="Which controls the controller shows; fewer controls leave more of the picture uncovered.",
// AXIS_DISTANCE units are device-arbitrary; 0..1 covers real hardware, and 0 while
// hovering legitimately means "at the hover floor".
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
enricobuehler
luxus
bluelightspecial
