85 lines
4.5 KiB
Markdown
85 lines
4.5 KiB
Markdown
# DeckShift — maintainer notes
|
|
|
|
Working notes for future development sessions. User-facing docs live in README.md.
|
|
|
|
## Current state (2026-07-27)
|
|
|
|
- **v0.1.15 released** — commit `8ba6e72`, tagged, pushed to both remotes
|
|
(Forgejo `nosignal/deckshift` + GitHub `28allday/deckshift`; the `forgejo`
|
|
remote pushes to both).
|
|
- v0.1.14 was **skipped**: that label was used by a keybind-change commit
|
|
(`0844f02`, Super+Shift+S → Super+Shift+G) that was reverted before release.
|
|
- Dev/reference machine: Omarchy 4 desktop (AMD RX 9060 XT), install verified
|
|
with `./deckshift.sh --verify` — all checks passed, including the two checks
|
|
added in v0.1.15.
|
|
|
|
## Omarchy 4 facts that shape this codebase
|
|
|
|
Discovered during the 2026-07-27 compatibility audit; verify against a live
|
|
system before assuming they still hold.
|
|
|
|
1. **Hyprland runs on Omarchy's Lua config provider** — `hyprctl systeminfo`
|
|
reports `configProvider: lua`. Every `~/.config/hypr/*.conf` file
|
|
(bindings.conf, autostart.conf, windows.conf, ...) is **completely ignored**,
|
|
even though `hyprland.conf` still contains `source =` lines for them.
|
|
Proof method: a bind present only in bindings.conf does not appear in
|
|
`hyprctl binds -j`.
|
|
2. **User override files are Lua**: `~/.config/hypr/bindings.lua`,
|
|
`autostart.lua`, etc., loaded after Omarchy's defaults. API (defined in
|
|
`~/.local/share/omarchy/default/hypr/helpers.lua`):
|
|
- `o.bind("SUPER + SHIFT + S", "Description", "command")`
|
|
- `hl.unbind("SUPER + SHIFT + S")` — required before rebinding a combo the
|
|
Omarchy defaults claim; duplicate Hyprland binds BOTH fire.
|
|
- `o.launch_on_start("command")` — exec-once equivalent (wraps the command
|
|
with `o.launch()`, i.e. uwsm-app).
|
|
3. **Walker/elephant are gone**: `omarchy-restart-walker` and `elephant` no
|
|
longer exist (`walker` binary may linger as an orphan). The Quickshell-based
|
|
omarchy-shell owns the app menu, notifications, and clipboard. The clipboard
|
|
holder starts fresh with each Hyprland session, so the pre-4 stale-socket
|
|
clipboard bug (v0.1.5/v0.1.6 fix) cannot recur — that code was removed.
|
|
`omarchy-restart-shell` exists if a shell bounce is ever needed.
|
|
4. **Still present and safe to depend on**: `omarchy-pkg-add`,
|
|
`omarchy-hw-nvidia-gsp` / `-without-gsp`, `omarchy-install-gaming-steam`,
|
|
`uwsm-app`, the `TUI.float` floating-window rule
|
|
(`default/hypr/apps/system.lua`), `xdg-terminal-exec`.
|
|
|
|
## Conventions
|
|
|
|
- **Omarchy-only, not distro-portable** — depend on `omarchy-*` helpers freely;
|
|
no non-Omarchy fallbacks. (Pre/post-Omarchy-4 *version* branching is fine and
|
|
used for the bindings/autostart writers.)
|
|
- Lua-first, `.conf` fallback: every Hyprland config write site checks for the
|
|
`.lua` override file first, falls back to the legacy `.conf`, warns if
|
|
neither exists. Keep new write sites consistent with this.
|
|
- All config writes are idempotent (grep-before-append). Re-running
|
|
`./deckshift.sh` on an existing install migrates `.conf` wiring to `.lua`
|
|
automatically (the stale `.conf` lines are left in place — they're dead
|
|
files under Omarchy 4).
|
|
- Release flow: bump `DECKSHIFT_VERSION`, README header + changelog entry,
|
|
commit `vX.Y.Z — summary`, annotated tag, `git push forgejo master &&
|
|
git push forgejo vX.Y.Z` (covers both remotes).
|
|
|
|
## Testing checklist for future changes
|
|
|
|
- `bash -n deckshift.sh bin/deckshift-settings` + `shellcheck -S warning` on
|
|
both (pre-existing SC2155/SC1090 warnings are known noise).
|
|
- `./deckshift.sh --verify` on the dev box.
|
|
- After touching keybind/autostart wiring: `hyprctl reload` +
|
|
`hyprctl configerrors` must come back clean, and confirm via
|
|
`hyprctl binds -j` that the bind is actually live (don't trust file contents
|
|
— that's exactly how the v0.1.15 bug hid).
|
|
- Full round-trip (enter + return + screen-share + clipboard) when touching
|
|
anything in switch-to-gaming / gaming-session-switch / portal recovery.
|
|
|
|
## Open items / ideas
|
|
|
|
- Real hardware round-trip test of v0.1.15 portal recovery (enter Gaming Mode,
|
|
return, confirm "Share desktop" works in Chromium) — wiring is verified, the
|
|
end-to-end path hasn't been re-run since the change.
|
|
- SDDM `Relogin=true` has no backoff: a crash-looping gamescope session
|
|
respawns several times per second until gamescope-session-plus's 5-strike
|
|
short-session tracker recovers. Escape hatch from a tty:
|
|
`sudo /usr/local/bin/gaming-session-switch desktop && sudo systemctl restart sddm`.
|
|
Worth a proper fix someday.
|
|
- The `--noninteractive` mode sketched for NoSignal OS integration was never
|
|
committed here; re-implement from scratch if needed.
|