The README is the complete user documentation again: features, install,
two sessions, usage, the full options table (and renamed options), every
feature with problem, usage, limitations, security and "remove when",
UI patches at user level (DevTools on the LAN, after a Steam update),
changes outside Nix, rollback and uninstall.
docs/ keeps only the technical side (how the patches work, writing
patches, signatures and the update procedure, the SteamVR debugger
mechanics, cleanup and installer internals), linked from each feature.
docs/options.md, two-sessions.md and desktop-integration.md are gone
(their content is in the README).
One page per feature group (sessions, keyboard, launcher menu, dashboard, SteamVR debugger, Firefox, Jellyfin, UI patches, changes outside Nix) and the full options table in docs/options.md.
- Intro: no longer claims that everything reverts by activating an older
generation; points to the exceptions and steam-frame-nix-cleanup.
- "Changes outside Nix (exceptions)": path, feature, lifetime, removed by
(the SteamVR debugger key while SteamVR runs, its .armed file, the
runtime drop-in and restore script, the dashboard patches' saved state,
hicolor's mtime); what steam-frame-nix-cleanup does and what of older
versions it removes; what exists only while running (UI patches,
clipboard-sync, the Firefox desktop user.js, Jellyfin's flatpak run
options); what install.sh sets up; app data that stays yours.
- Rollback: `cleanup --all` (curl or nix run) after rolling back to a
generation without steam-frame-nix or older than the cleanup.
- Uninstall: what install.sh uninstall does; dropping steam-frame-nix from
a kept configuration (cleanup --all first, or `uninstall = true;`).
- Per-module notes and options: icon fallbacks, SteamVR debugger, Firefox,
Jellyfin; template comment for iconFallbacks.
The policy for the `state = true` files
(~/.local/state/steam-frame-nix/ui-patches/<name>.json), now stated in the
option, the injector and the README: they are user data, kept when a patch
is disabled or removed (the choices come back when it is enabled again),
and removed only by `steam-frame-nix-cleanup --all` / `install.sh
uninstall`; `--orphans` removes stale *.json.tmp only.
frame-controls v6 drops v5's one-time read of version 4's localStorage copy:
steamvr.service deletes ~/.cache/SteamVR (and with it that localStorage) on
every SteamVR start, so there is nothing left to migrate.
The shim's permissions (devices=all, its store path, LD_PRELOAD,
SFN_MPV_HWDEC) were a Flatpak override: through nix-flatpak's
services.flatpak.overrides, whose override file outlives the
configuration (it left an empty file behind), or a Home Manager link that
`flatpak override --user` would replace (hence `force`). Now a desktop
entry shadowing the Flatpak's (same ID, same fields and actions; also what
the "+" menu sees) passes them as `flatpak run` options
(--device=all --filesystem=<shim>:ro --env=...), so nothing is written to
Flatpak's overrides and they disappear with the entry.
jellyfin.hardwareDecoding.command is that command line for a terminal.
The entries earlier versions put into the override file are removed by
steam-frame-nix-cleanup. Checked with `flatpak run ... --command=sh`: the
shim's store path is visible read-only, the environment is set and
/dev/video* is there.
The desktop profile's user.js link (undoing the fullscreen fix there) was
kept in place on every switch and before every launch. Now the launcher
(nested desktop only) makes it right before Firefox starts, waits for
Firefox instead of exec'ing it, and once it has exited and the profile is
no longer in use removes the link and the value Firefox stored from it in
prefs.js. A second launch that hands its URL to the running Firefox returns
at once and leaves both alone; a user.js of the user's own is never
touched. The desktop profile itself is a normal Firefox profile (browser
data) and is never removed.
No activation step touches profiles anymore: leftovers of a crash and what
older versions wrote (user.js copies and links, their prefs.js values) are
steam-frame-nix-cleanup's (orphans on switch), which leaves the desktop
link alone while the profile is in use; the firefox-desktop-userjs --keep
is gone. The launcher lives in firefox/launcher.nix; checks.firefox runs it
against a fake flatpak (link only while running, forwarded second launch,
prefs.js cleaned only once unlocked, own user.js untouched, Steam session).
The icon fallbacks were links an activation script made (and tracked in
~/.local/state/steam-frame-nix/icon-fallbacks) after scanning the desktop
entries. They are Home Manager links now:
~/.local/share/icons/hicolor/scalable/apps/<name>.svg -> the largest Breeze
app SVG, for utilities-terminal and preferences-system (SteamOS' Konsole and
KDE System Settings) plus iconFallbacks.extra; a name Breeze doesn't have
fails the build. enable = false: none.
- The scan is read-only now (steam-frame-icon-fallbacks --suggest): each
switch prints icons Steam can't find that Breeze has (for extra) and
fallbacks hicolor has anyway.
- hicolor's mtime is bumped when the set of links changed between
generations, so a running Steam rescans (GTK checks theme dir mtimes).
- The script's old links at those paths are removed before
checkLinkTargets (they would be collisions); any others and the manifest
go through steam-frame-nix-cleanup.
The assertion for the old list form stays until ~2026-12.
The key used to be merged into steamvr.vrsettings for good (reset at the
next start after disabling, via a marker). Now it is on only while SteamVR
runs and nothing depends on Nix to undo it:
- before each SteamVR start, the oneshot runs `install.sh
steamvr-debugger-arm`: the key's value goes to
~/.local/state/steam-frame-nix/steamvr-debugger.armed ("absent", "false",
"nofile"), the key is set (jq --indent 3, mode kept), and a runtime
drop-in $XDG_RUNTIME_DIR/systemd/user/steamvr.service.d/
50-steam-frame-nix-debugger.conf runs a /usr/bin-only restore script from
$XDG_RUNTIME_DIR/steam-frame-nix on ExecStopPost= (daemon-reload only when
newly written: once per boot). A key that is already true without .armed
is the user's own and never touched. The old marker migrates to .armed
("absent").
- when SteamVR stops, the key goes back to its previous value (removed if
it was absent, the file too if it only existed for the key) and .armed
is removed. .armed is the only trace a power loss can leave; the next
start or steam-frame-nix-cleanup resolves it.
- disabled: no unit and no drop-in at all; the orphan cleanup restores the
key once SteamVR is stopped (or leaves it to the runtime drop-in while it
runs).
A daemon-reload from a oneshot pulled in by a pending start job was tried
on dummy user units: the job survives and the new ExecStopPost= applies,
also on restart (stop, then the oneshot, then start).
checks.cleanup covers arming, re-arming, restoring and the user's own key.
Every module imports cleanup.nix (also exported as
homeManagerModules.cleanup), which
- puts steam-frame-nix-cleanup (install.sh cleanup) on PATH;
- runs `cleanup --orphans --quiet` after linkGeneration on every switch,
keeping what the configuration still uses (steamFrame.cleanup.keep, set
by the modules: debugger while steamvrDebugger is on, the Firefox desktop
profile's user.js while its fix applies); in a dry run it runs with
--dry-run;
- runs `cleanup --all` instead when Home Manager's `uninstall = true;` is
set (the manual uninstall route);
- removes links of older versions at paths Home Manager is about to own
before checkLinkTargets (steamFrame.cleanup.migrateLinks), which would
count as collisions otherwise.
install.sh cleanup gains --quiet (only actions, deferrals and warnings;
the header only when something is printed). The Jellyfin module's own
removal of the old shim copy goes: cleanup does it.
`install.sh cleanup [--dry-run] (--all | --orphans [--keep <artifact>]...)`
knows every file any version wrote outside the store and Home Manager's
links, removes only what is provably its own, prints every action and
reports everything else as "left alone"; a second run changes nothing.
Only bash, coreutils, findutils, grep, sed, awk and jq (all in /usr/bin on
SteamOS), so it also works piped from curl after a rollback or with Nix gone.
- SteamVR debugger: VRWebHelper.DebuggerEnabled is put back to its value
from before (steamvr-debugger.armed; the old empty marker means "absent"
and is migrated), only while SteamVR is stopped. While it runs, a runtime
drop-in (/run/user/<uid>/systemd/user/steamvr.service.d) runs a /usr/bin-only
restore script from /run/user/<uid>/steam-frame-nix when SteamVR stops.
- icon fallback links into Breeze and their manifest (dirs only if they
held nothing else; hicolor's mtime bumped so Steam rescans).
- Firefox: the desktop profile's user.js link, older user.js links and
marker-headed copies, and the values they left in prefs.js (only with the
profile closed; deferred otherwise).
- Jellyfin: the hwdec shim entries in the Flatpak override (devices=all
only when it came with them), an empty override file, the old shim copy.
- the dashboard patches' saved state: --all only; --orphans removes just
stale *.json.tmp files.
`install.sh uninstall` runs `cleanup --all` before removing Home Manager
(replacing its own ui-patches removal) and names what is deferred;
`install.sh status` shows what `cleanup --all` would do. The flake exports
it as packages.<system>.cleanup / apps.cleanup
(`nix run github:lhns/steam-frame-nix#cleanup -- --all`), and
checks.cleanup runs it against fake home and runtime dirs: every artifact
next to look-alikes that aren't ours, --dry-run, second runs, SteamVR
running (deferral, restore script), the user's own debugger key.
SteamOS's steamvr.service runs `rm -rf ~/.cache/SteamVR` on every SteamVR
start, which deletes vrwebhelper's browser profile and with it the
localStorage frame-controls kept its placements in, so they were lost on
every SteamVR restart and reboot.
steam-ui-patches: per-patch persistent state (`state = true`). The injector
keeps ~/.local/state/steam-frame-nix/ui-patches/<name>.json, seeds
window.__sfuiStore in a fresh page before the patch runs and writes the file
(atomically, on change, name-checked, max 64 KiB) when the page calls the
CDP binding __sfuiStoreSave.
frame-controls v5: placements saved there (v4 localStorage copy migrated
once, then removed). steam-close-button v8: "Steam hidden" saved there; a
restored hidden state hides Steam once if SteamVR already shows it when the
patch attaches (or first shows it before the patch sees Steam's frame).
README: "Changes outside Nix" lists the directory; install.sh uninstall
removes it.
prefs and vrFullscreenFix become default prefs (pref()) in
defaults/pref/steam-frame-nix.js of /app/etc/firefox, the mount point of
the org.mozilla.firefox.systemconfig extension point. home-manager
provides the extension as a user "unmaintained extension" link
($XDG_DATA_HOME/flatpak/extension/<id>/aarch64/stable) to a store dir,
which Flatpak mounts itself: the sandbox doesn't see /nix. Default prefs
are never written to prefs.js, so removing one leaves nothing behind.
The desktop profile undoes the fullscreen fix with a user.js linked to
/app/etc/firefox/steam-frame-nix-desktop-user.js. The sync (on switch,
and before each launch) removes the user.js copies and store links of
older versions and takes their values out of prefs.js, for each profile
not in use (Firefox holds .parentlock open).
Jellyfin Desktop hard-sets mpv's hwdec=auto-copy, whose probe list leaves
out V4L2 M2M, and the Flatpak can't see the Frame's V4L2 decoder. An
LD_PRELOAD shim (preloaded straight from the store, only that path exposed
read-only) rewrites hwdec to v4l2m2m-copy,auto-copy; devices=all makes the
decoder visible. Overrides via nix-flatpak, or a home-manager-owned override
file without it.
When the ring shows, frame-controls no longer takes the press over via
cancelPress(); it raises the press's drag threshold to 3x via the new
window.__sfuiWindowCurvature.scalePressDragThreshold(factor) (measured from
the press start). Laser drift keeps the long press, a deliberate drag starts
the curvature drag and cancels it. Completion still calls cancelPress().
Stock calls Frame.SetControlsItems once per control on every re-render
of a window's controls (~12 identical calls per window and scene-graph
update); each replaces three MobX arrays and re-renders the bar. The
wrapper now skips the stock setter when the (re-partitioned) lists equal
the frame's current ones, and reads each action's icon once per call
(protoForSteam is recomputed on every untracked read).
The Flatpak sandbox doesn't see /nix, so the linked user.js dangled and
Firefox never read it (vrFullscreenFix had no effect). The copy starts with a
marker line, so the module still recognises its own file.
Opt-in with steamFrame.keyboard.vr.enable; swipe, autocorrect and
completion suggestions, Backspace drag and haptics are on under it.
- vr-keyboard/patch.js (Steam UI): swipe decoder, a model of what the
keyboard typed, suggestions that only replace what they typed, Backspace
drag with word detents and retyping; checks its Steam internals by
signature (signatures.json: vr-keyboard) and stays stock otherwise.
- vr-keyboard/panel.js (SteamVR systemui) + relay.mjs (user service
vr-keyboard-relay): the suggestion strip as a dashboard panel below or
above the keyboard (signatures: vr-keyboard-panel).
- Dictionary built from nixpkgs' wordfreq and hunspellDicts; default: the
keyboard.layout language (de, fr, es, it, nl, pt, sv) plus English.
- Tests: keyboard.vr.checks and the flake check vr-keyboard.
US, Dvorak, Colemak, Bulgarian, Chinese, Japanese and Korean have no AltGr
key, so AltGr + Delete and the AltGr arrows were unreachable. They get
Steam's own AltGr toggle key, labelled Fn, right of the space bar like
German AltGr.
The Delete key's hint without AltGr is now a third layout entry (empty
key, label Entf), rendered by Steam exactly like its other AltGr hints
(e.g. } on 0) instead of a stylesheet pseudo-element.
The key that becomes Delete on AltGr shows a small hint (the arrow hints'
7 px) on the baseline of Steam's AltGr hints, while the layout has such a
free key.
Steam draws a [normal, shifted] entry as a bare empty key on AltGr and
drops its key type, so the Half-width ^ grew to a full key. Keep the type
with an empty AltGr entry. The AltGr Delete key gets Backspace's key type
(the dark special-key face), the replaced key's flexible width and a
centred label.
While AltGr is active, the key left of Backspace (German ´/`, empty on
AltGr) becomes Delete, labelled like Steam's Delete key (Entf; Del when
longer), sent by the helper; repeats while held like Backspace.
- dashboard.windowMaxScale / windowDistance -> dashboard.windows.maxScale /
distance
- windowCurvature: default -> initial, snapPixels/snapPoints ->
detentPixels/detentPoints, dragThreshold -> dragThresholdPixels (also the
patch's option keys; window-curvature VERSION 19); removed `snap` now
points to detentPixels
- types.numbers.positive/nonnegative instead of number + range assertions
(step <= max, initial/detentPoints <= max and distance min <= max stay)
- frame-controls patch accepts longPressMs from 300, like the option
(VERSION 2)
- "SteamVR dashboard patch" in descriptions, which fit into 80 columns
Old names keep working with a rename warning.
Closing Steam with X now marks it hidden (state steamHidden). Before,
bar-only ended as soon as any window became active, so closing a docked
window afterwards let stock SteamVR fall back to Steam.
While hidden, the stock fallbacks go to the most recently active other
docked window with a tab, else bar-only:
- autoSwitchOverlayIfNeeded with no active frame;
- the dashboard mailbox's dashboard_overlay_destroyed handler (stock:
switchToHomeOverlay -> Steam);
- show/switch requests for Steam with reason "theater frame destroyed"
(key removed) or "SetDockLocation" (echo of X docking Steam: dropped).
Steam becoming the active frame (tab click, Steam menu pick,
SwitchToDashboardOverlay) ends hidden.
The hidden state replaces the rule that swallowed the first
ShowOverlay(main) from Steam after each dashboard open in bar-only (Steam
doesn't send one there; its only effect was eating a real Steam menu
pick). Version 7; state of versions 5/6 is taken over (bar-only implies
hidden), their fields are left for a rollback. Signatures: mailbox and
dashboard handler anchors, the ShowOverlay ones dropped.
The bar panel is no longer padded during a bar drag (its new size and the
compensated origin reached the compositor at different times, so the bar
flickered). SteamVR keeps sending the pressed bar's coordinates past its
edge, so the drag simply uses them. `barDragRoom` is removed.
- Snap points are detents in drag distance (snapPixels, default 24): the
value holds at the point, then continues, so no value is skipped.
`snap` is removed in favour of `snapPixels`.
- The dashboard's own hover haptics are muted during a drag, so only the
value's ticks and detents are felt.
- Longer drag per step by default: 120 px per 1.0 in the menu, 60 on the
bar button (step stays 0.05).
Document the patch calling convention once in lib/default.nix; patch
headers say what, target, hook, state and contracts. Comments only, no
code changes.
Explain the steamvrDebugger default in plain words, and replace the
"mask the port forwards" advice: SteamOS only enables them with Steam's
Developer Mode, which none of the patches need.
- A short contents list; the intro names all features.
- "UI patches" (with finders/signatures and after-a-Steam-update) is its
own section before "Fixes in detail" instead of sitting between the
keyboard patch and the launcher menu; anchors are unchanged.
- The usage example says how it relates to template/ and uses the
template's stateVersion.
- Developer Mode notes (usage, hidden apps) mention launcherMenu.showAllApps;
the launcher section no longer says the patches use no webpack module;
window curvature points to the window control bar for the bar button.
- pinned-desktop (VERSION 3): drop the stop() of a predecessor global that
never existed in this repo; log errors as "sfui <NAME>:" through one
guard helper, like the grid patch.
- steamCloseButton.enable is a mkEnableOption like the other feature
switches; enable descriptions no longer end in a stray newline.
- launcher-menu.nix header lists show-all and no longer claims the patches
use no webpack module; hiddenApps mentions showAllApps.
- Patch comments: frame-controls ring timing matches the code (half of
longPressMs, at most 1 s), window-curvature names frame-controls as what
moves its control into the bar, steam-close-button no longer refers to an
unpublished version.
steamFrame.dashboard.frameControls: a long press (longPressMs, default
1.5 s; a ring shows the progress from half of it) on a control under a
dashboard window or on a More Options (three-dot) menu row opens a popup
with "Show in bar", which moves that control between the window's bottom
bar and the menu, for all windows. Placement is keyed by the control's
action icon, kept in the page and its localStorage (survives SteamVR
restarts); inBar / inMenu set defaults. floatInTheater gives theater
windows the Float control back.
The popup is a scene-graph panel of its own, attached to the pressed
button's (or the menu's) anchor like SteamVR's tooltips and menu, so the
bar and menu panels don't change; the menu's focus auto-close is held back
while its popup is open. Coordinates with window-curvature through its
sfui-curv-* contract. Lookups by signature ("frame-controls" in
lib/signatures.json, check-only anchors for the rest).
Pierre Kisters