targets.genericLinux.gpu would ask for a root setup (a tmpfiles.d link
under /etc) for drivers that Nix-built GUI apps need and steam-frame-nix
doesn't; news.display = "silent" drops the unread news notice on each
switch (home-manager news still lists them).
It is built from source, which makes the first switch long. The template
lists it as a commented option; status shows clipboard-sync only while it
runs or its autostart link exists.
create_config locks the template as a path (not the git repository) and
commits everything once, with the user's git identity or, without one,
a fallback passed with -c for that commit only. The template switch no
longer warns that the tree is dirty; the marker and the one-commit rule
are unchanged.
Without ~/.config/home-manager and --flake, a flake in ~/nix-config
(e.g. left by uninstall) is used as it is, like --flake ~/nix-config,
and linked to ~/.config/home-manager. A directory there without
flake.nix still stops the install.
The closing message no longer lists generic "left in place" items
(*.hm-backup-<time> files that usually don't exist, app data, Flatpak
apps). It says where the configuration stays and how install uses it
again, lists the *.hm-backup-* files Home Manager actually made (if
any), and asks to log out or reboot.
- The nix.mount drop-in is also removed when the uninstall fails or is
interrupted (exit trap), and when daemon-reload failed after writing it.
- --dir with a trailing slash no longer puts the temporary clone inside
the directory it replaces.
- The template's repository uses Nix's git when SteamOS has none, so the
template marker exists there too (--clone needs it).
- A failed Nix uninstall during the reinstall of a broken Nix says so.
- clone_config: one branch per case; shorter comments, help and docs.
- Tests: an interrupted uninstall, --dir with a trailing slash; a
redundant "used as it is" case dropped.
README: what --clone does for a private repository (the template's
gh/store helpers, the gh auth login offer, keep those lines in your
config, what gets cloned into and that re-running continues), the
git/gh lines in the usage example, and that uninstall no longer waits
for programs from the Nix store. docs/cleanup.md: the clone steps, the
untouched-template marker, and the LazyUnmount= drop-in.
- uninstall: nix-installer's copy outside /nix is made and run as root
(a user-writable copy run by sudo could be swapped); README uninstall
paragraph shortened to one account of what happens when Nix stays.
- session.nix: the restart-check activation after steamFrameUserServices,
so the latter's comment is above it again.
- install.sh: a duplicate `local` in port_listening; comments.
- docs/cleanup.md: the installer internals of --clone (how an existing
clone is recognised, which git) and restart-check (what it compares,
test overrides); README keeps the usage.
- README install paragraph: shorter list of the dashboard patches.
Examples showed specific apps as if the repository installed or
configured them.
- Docs, README, template and option examples: the Signal Flatpak
(org.signal.Signal, sgnl:// and signalcaptcha://) and a made-up
org.example.App instead of the previous chat and remote-desktop apps;
no install lines (the app is installed by the user, as noted).
- Portal fix: the file-dialog symptom phrased generically.
- Launcher check: made-up Flatpak entries org.example.Chat (Electron,
--file-forwarding @@u %U @@, an action, an SSO scheme) and
org.example.Remote (Qt, -qwindowtitle %c @@u %u @@, localized keys)
replace the copied ones; Firefox, gedit and Jellyfin stay.
nix-installer uninstall failed at `systemctl stop nix.mount` ("Job
failed") while programs started from the Nix store still ran: a terminal
session's tools, or apps that mapped Home Manager's mime.cache.
- Before nix-installer runs, after Home Manager is gone, uninstall scans
/proc for the user's processes whose exe, cwd, root, an fd or a mapped
file is in /nix, and lists them by name and PID (the shells it was
started from included; itself, its subshells and its curl | bash
pipeline skipped). Close them and press Enter to re-check, or abort;
with --yes or without a terminal it stops: "close these or reboot, then
run uninstall again". Nothing is killed (replaces the old kill prompt).
- nix-installer runs from a copy outside /nix.
- cleanup check H: a fake /proc (STEAM_FRAME_NIX_PROC) with programs from
the store stops before Nix; without them Nix is removed.
Clones your own config repository (git@host:owner/repo, https://...,
github:owner/repo) into ~/nix-config or --dir and installs it like
--flake <dir>. An existing clone of the same repository (any URL form) is
reused and, after asking, pulled with --ff-only; another repository, a
non-clone or a different branch is refused. A failed clone hints at SSH
URLs and gh auth login. Uses SteamOS' git, else Nix's.
Checked against local bare repositories through a logging git.
A fresh install into a running session left the keyboard layout and the
SteamVR dashboard patches (VR pet, the VR keyboard's suggestion strip, ...)
silently off until a reboot: gamescope reads XKB_DEFAULT_* only at its
start, and SteamVR opens its DevTools port (VRWebHelper.DebuggerEnabled)
only at its start. Neither can be applied at runtime.
- install.sh restart-check (run on every switch by session.nix, and by
install at its end): compares the keyboard-layout drop-in with the
running gamescope session's environment and checks whether SteamVR runs
without port 8087; install ends with "Restart once" listing them.
- uninstall: a failing nix-installer uninstall (e.g. /nix busy) no longer
aborts the script before the ~/.config/home-manager link and Home
Manager state are removed; it says to reboot and run uninstall again.
- cleanup check: restart-check on fake cgroup/proc dirs.
The module list gains vr-keyboard-controllers and vr-keyboard-touch; the
removed-options table gains the list form of launcherMenu.iconFallbacks,
windowCurvature.snap and barDragRoom; the intro counts the icon fallbacks
among the defaults; the swipe feature line names two-handed swipe and
functionKeys; the VR keyboard rows give the ranges the types enforce.
The Toon Cat (sources/toon-cat/), the Tuxedo Cat glTF (sources/tuxedo-cat/)
and the Quaternius Shiba Inu and Fox (models/{shiba,fox}/model.glb), each
byte-identical to the previously fetched file and with a LICENSE.md
(author, original URL, licence, changes). The build no longer downloads
them; three.js (preview only) still comes from npm. The baked frames,
model dirs and icons are unchanged.
docs/pet.md (usage, configuration, how it works), docs/pet-models.md
(the model spec), the README's feature line, options, changes outside
Nix and Credits (Toon Cat FREE and Tuxedo Cat, CC-BY 4.0; Quaternius
Shiba Inu and Fox, CC0), the cleanup artifact, the layout and runtime
names, and the template.
- gesture-input.js: drop the unused mode getter and release().
- relay.mjs: both sides have a binding; no condition.
- hub.js: the frame cadence is documented once (bridge-patch.js); errors
listed.
- docs: the bridge's idle cost and "one word at a time" stated once;
twoHanded's README row points to the docs; rewrapped lines.
keyboard.vr.functionKeys.enable (default off): while AltGr (Fn on layouts
without AltGr) is one-shot, locked or held, the strip shows F1-F12 instead
of the suggestions. A tap types the extra key VKX_F<n>, which the extra
keys' patch presses with xdotool together with the active Ctrl/Alt/Shift
(Alt+F4, Ctrl+F5) and releases the toggles; the text model resets, like
for Esc. The suggestions are kept as they are meanwhile, so when AltGr goes
off the strip shows the same items and selection again.
- vr-keyboard/function-keys.js: what the strip shows, the F-key keys.
- patch.js (VERSION 27): the strip's view, F-key picks, AltGr changes via
a componentDidUpdate on the keyboard instance (and the poll).
- Allowlist: F1-F12 with any modifiers; Enter still refused.
- relay.mjs: up to 12 strip items.
- Assertions: needs keyboard.vr.enable, extraKeys.enable and a strip
position "above"/"below" ("inside" would hide the AltGr number row).
- Tests: function-keys.test.mjs (switching and restoring, keys against
the allowlist, text model), allowlist F-key cases.
With both lasers on the keyboard SteamVR forwards per poll only one laser's
movement, so the pressing one may get no touchmoves and its swipe became a
tap. keyboard.vr.swipe.twoHanded (default on; turns on the controller
bridge): a press is attributed to the hand whose laser hit is nearest to it
(within 30 px, the trigger as a tiebreak; without recent frames the first
frame after the press decides, within 60 px). The path comes from runs of
one source: the touch's own moves while they flow, that hand's laser hit
per bridge frame once they pause for 60 ms, touchmoves again if frames
pause. A touchend disagreeing with the laser during a bridge run ends at
the laser. Touchmoves on the other hand's laser move the attribution.
Without fresh frames: touch events only, as before. A second press during
a swipe stays Steam's tap (one text field, one word at a time).
The bridge sends full rate only on demand now: hub.js demand(ms) goes
back through the relay (CDP binding __sfuiCtlIn) to systemui's
__sfuiCtl.demand; the swipe patch asks from the press to the release.
Tests: gesture-input with the two-controller recording and synthetic bridge
frames (a pressing hand without touchmoves, attribution with both lasers on
the keyboard, a stale bridge, frames stopping mid-swipe, re-attribution,
interleaved hover and presses); hub demand.
keyboard.vr.touchTyping (off by default): a key is pressed when a
controller's tip, where SteamVR's laser starts (/pose/tip: the device pose
times the render model's "tip" component), passes through it from the
front; released when pulled back 1 cm, re-armed 5 mm in front. Both hands,
also at once. Keys go through the keyboard's own HandleTouchStart /
HandleTouchEnd, like a laser press (Backspace repeats while held). Options
depth (cm) and haptics.
The geometry lives in a reusable controller bridge (vr-keyboard-controllers,
internal option): a systemui patch reads the keyboard's pose with SteamVR's
SGQueryService (an empty transform of ours in the keyboard's mount) and both
controllers' poses, and streams per hand the tip, the laser's hit on the
keyboard and the trigger (~90 Hz while relevant) through the
vr-keyboard-controllers-relay service to __sfuiControllers in Steam's
SharedJSContext. Tests: flake checks vr-keyboard-controllers and
vr-keyboard-touch.
Steam keeps VR screenshots (Steam button + trigger) in
~/.local/share/Steam/userdata/<account ID>/760/remote/250820/screenshots,
where Dolphin, Gwenview and the file pickers don't look.
screenshots (module screenshots, opt-in) links ~/Pictures/<name> (default
"SteamVR Screenshots") there. The account ID comes from steamUserId, or,
unset, at runtime: the Home Manager link points to
<runtimeDir>/steam-frame-nix/screenshots (tmpfs), which the oneshot user
service steam-frame-nix-screenshots points to the account last logged in
(loginusers.vdf MostRecent, else latest timestamp, else the only userdata
folder), on switch, at login and when loginusers.vdf or userdata changes.
install.sh cleanup knows the tmpfs link (--keep screenshots while used).
Flake checks: account detection on fake Steam dirs; cleanup of the link.
Steam sends Tab as the text "\t" and drops Shift. With Shift, Tab now
goes to the xdotool helper (shift+Tab, ISO_Left_Tab on any keymap); the
suggestions text model resets on it like on Shift+arrows. The helper's
allowlist moves to allowlist.mjs with a test (flake check
vr-keyboard-extra-keys).
Neither Valve backend (gamescope, holo) implements FileChooser, so sandboxed
apps fell back to an in-sandbox dialog without the home dir (e.g. Element's
Attachments). session.portalFix.fileChooser (on) links kde.portal into the
Steam session's portal dir and selects kde for FileChooser;
xdg-desktop-portal-kde is D-Bus activated with DISPLAY=:0. Flake check
for the portal config.
SteamOS only ships /etc/xdg/menus/plasma-applications.menu; the nested
desktop sets XDG_MENU_PREFIX=plasma-, the Steam session doesn't, so KDE
apps started there (Dolphin from the "+" menu) built an empty app
database: "no installed application can open" every file.
session.applicationsMenu (module applications-menu, on by default) links
~/.config/menus/applications.menu to Plasma's menu. Flake check: the link
is generated by default and absent when disabled.
steamFrame.launchers.<desktop ID> takes the app's own entry (a Flatpak's
export, a Nix package's or a host file) and rewrites only its command lines
(hostEnv, env, flatpakArgs, args, wrappers) and the keys asked for
(mimeTypes, defaultFor, settings), so name, icon, translations and actions
stay the app's and follow its updates.
- Package entries are rewritten at build time; Flatpak/host file entries at
runtime by steam-frame-nix-launchers into
<session.runtimeDir>/steam-frame-nix/applications (tmpfs), on switch, at
login and when Flatpak installs/updates apps (path unit); the Home Manager
links point there.
- keyring.{enable,electron} replaces steamFrame.keyring.{flatpaks,programs}
(clean break: the old options fail with the new form).
- Firefox's launcher is the Flatpak's entry with the profile wrapper in
front (no --profile for the profile manager); Jellyfin's hardware
decoding sets flatpakArgs and env.
- cleanup --all removes the tmpfs entries.
- Check on copies of the real Element, KRDC, Firefox, gedit, Jellyfin and
Claude entries, quoting and generator behaviour.
- firefox: the prefs.js patterns built once; the extension link condition
without the redundant desktopFix (it implies a pref).
- install.sh steamvr-debugger-arm: no second copy of the old-marker
migration (cleanup, run on every switch before the arm unit exists,
already does it).
- steam-ui-patches: shorter state option description; lib's description
mentions extraArgs.
- README: uiPatches.patches fields in the options table (moved from
docs/ui-patches.md); docs/ui-patches.md: the finder helpers;
docs/steamvr-debugger.md: repeated sentences removed.
- keyring.flatpaks / keyring.programs: desktop entries shadowing an app's
own that run it on the outer bus (one kwalletd6 for both sessions), with
the wallet's D-Bus names as `flatpak run --talk-name` options (no Flatpak
overrides), --password-store=kwallet6 for Electron, and login callback
schemes as default + recommended handlers.
- firefox.defaultBrowser: the launcher as default for http, https and
text/html.
- docker: rootless dockerd as a user service, socket in the outer runtime
dir, CLI with DOCKER_HOST for both sessions.
README keeps intro, feature list linking docs/, install, two sessions,
usage, the complete options table, changes outside Nix, rollback,
uninstall. Each feature's details (problem, what you get, configuration,
limitations, how it works) move to its own page in docs/; docs/dashboard.md
is split per feature and docs/changes-outside-nix.md becomes
docs/cleanup.md.
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).
- 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.
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().
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 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.
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.
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.
Pierre Kisters