One managed block in omarchy-menu.jsonc: the punktfunk submenu (merging
with the host tool's block by reused ids), Open Punktfunk, the couch
console, and a connect row per saved host -- typing a host's name into
Super+Space and pressing enter starts the stream. Wake rows where a
MAC is known.
The menu cannot generate rows at runtime -- its provider field resolves
only against a map baked into the shell (verified in Menu.qml, Omarchy
4.0.1) -- so the rows are static and kept true instead:
KnownHosts::save calls the sync, and save is the one door every store
mutation walks through, in the GTK app, the couch console and the CLI
alike. omarchy-menu refresh repaints an open shell.
Opt-in (a preferences switch, or --omarchy-menu on); off removes
exactly our block -- on the testbox the file came back byte-identical.
The GTK shell already recoloured; this moves the reader into
pf-client-core and spends it twice more, so the console wears the theme
too and a client-only box needs no setup at all:
- The reader falls back to the theme's own colors.toml when our
rendered template is absent. Only host boxes render the template, and
a box that is only a screen was themed nowhere.
- The console gets a follow-system palette: a quiet field mixed from
the theme's own ground, ink and accent derived with the same 3:1 lift
the shell uses. The session binary polls the file every 2 s and
publishes on change; the shell's existing palette-rebuild seam does
the rest, so an omarchy-theme-set lands mid-session with no restart.
- One switch rules both surfaces: follow_os_theme, default on, its row
shown only where a theme is actually published -- and the console
hides its Background picker while the system theme rules it.
menu_is_valid stripped `//` to end-of-line with no idea of strings, so
the console row's own action -- it carries a https://localhost:47992
fallback -- was cut mid-string and the whole file refused as
unparsable. Found on the testbox: the script could no longer edit the
very file it had written.
The replacement scans character-wise, stripping comments and forgiving
trailing commas only OUTSIDE strings. The client mirrors the algorithm
in Rust (omarchy_menu::jsonc_parse); change one, change both.
`--ignored` alone starts all three display tests in one process, and GTK
initialises once per process from one thread -- libtest gives each test
its own thread, `--test-threads=1` included. So whichever starts first
wins and the rest panic with "Attempted to initialize GTK from two
different threads". Each passes alone; the note said otherwise.
Every colour in the shell's own stylesheet already resolved through
libadwaita's named palette, so wearing the desktop's theme is a matter
of redefining those names -- not of touching a widget. Omarchy has been
rendering the four values on every theme switch since the host
integration landed, and until now only the web console read them.
Hex only. The surfaces are mixed out of the background/foreground pair,
so the numbers are needed anyway; GTK's CSS parser knows nothing of
oklch; and an unrendered template still holds its literal `{{ accent }}`,
which the same check is what refuses.
The accent is split, because libadwaita spends one name on accented text
and another on a fill. The fill keeps the theme's exact colour, and only
the text form is lifted toward the foreground until it reads at 3:1 --
several Omarchy light themes pick an accent that is handsome as a fill
and illegible as a label.
success, warning and destructive keep libadwaita's values: a theme with
a red accent must not make "Unpair" and "Connect" the same colour.
Colours only. The widget vocabulary stays Adwaita.
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.
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.
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.
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.
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.
2026-08-22 23:41:05 +02:00
625 changed files with 62683 additions and 5521 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
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.
@@ -481,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":[
@@ -4331,6 +4439,67 @@
},
"components":{
"schemas":{
"ActionInfo":{
"type":"object",
"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.",
@@ -5535,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"
@@ -6141,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":[
@@ -9142,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.",
if(dragHeld)NativeBridge.nativeSendPointerButton(handle,1,false)// end the drag
}
}
}
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
