docs: README updates for v0.1.4–v0.1.6

- Bump banner version 0.1.3 → 0.1.6. - Drop the "moving toward distro-portability" / "cross-distro is the next direction" notes — DeckShift is Omarchy-only. - Add What's New entries for v0.1.4 (portal-recovery race fix), v0.1.5 (clipboard via Walker restart), v0.1.6 (Omarchy-only cleanup). - Combine the screen-sharing and clipboard symptoms into a single troubleshooting block (same root cause) and replace the old racy manual-restart command with `touch /tmp/.deckshift-just-returned && /usr/local/bin/deckshift-portal-recovery`, with a note explaining why the marker is required. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
chore: drop non-Omarchy fallback in portal-recovery Walker restart
2026-05-12 21:02:51 +01:00 · 2026-05-12 20:59:00 +01:00 · 2026-05-12 20:56:36 +01:00
2 changed files with 33 additions and 12 deletions
--- a/README.md
+++ b/README.md
@ -1,15 +1,31 @@
 # DeckShift

-**Version 0.1.3** — Steam Deck-style gaming mode for Linux + Hyprland. Press `Super+Shift+S` to enter Gaming Mode (Steam Big Picture in Gamescope), `Super+Shift+R` to return to your desktop.
+**Version 0.1.6** — Steam Deck-style gaming mode for [Omarchy](https://omarchy.com). Press `Super+Shift+S` to enter Gaming Mode (Steam Big Picture in Gamescope), `Super+Shift+R` to return to your desktop.

-Lineage: forked from [Super-Shift-S-Omarchy-Deck-Mode](https://git.no-signal.uk/nosignal/Super-Shift-S-Omarchy-Deck-Mode), briefly renamed Omarchy Deck, then renamed DeckShift as the project moves toward distro-portability.
+Lineage: forked from [Super-Shift-S-Omarchy-Deck-Mode](https://git.no-signal.uk/nosignal/Super-Shift-S-Omarchy-Deck-Mode), briefly renamed Omarchy Deck, then renamed DeckShift.

-> **Current status**: targets [Omarchy](https://omarchy.com) (Arch + Hyprland + SDDM + iwd). Works on other Arch + Hyprland setups with minor manual tweaks. Cross-distro support (Fedora / openSUSE / Cachy) is the next direction.
+> **Target:** [Omarchy](https://omarchy.com) — Arch + Hyprland + SDDM + Walker. DeckShift depends on Omarchy-specific helpers (`omarchy-pkg-add`, `omarchy-restart-walker`, etc.) and is not intended to be cross-distro.

 [![DeckShift demo](https://img.youtube.com/vi/nj4pLh3spCs/maxresdefault.jpg)](https://youtu.be/nj4pLh3spCs)

 ## What's New

+### v0.1.6 — Omarchy-only, simpler portal recovery
+
+- Dropped the non-Omarchy fallback in `deckshift-portal-recovery` — DeckShift targets Omarchy only, so the helper now just calls `omarchy-restart-walker` directly.
+- Header / docs cleaned up to drop the "cross-distro is the next direction" note.
+
+### v0.1.5 — clipboard recovery after Gaming Mode
+
+- After returning from Gaming Mode, Walker's clipboard listener (`elephant.service`) was still bound to the killed Hyprland's Wayland socket, so paste did nothing and clipboard history was empty.
+- `deckshift-portal-recovery` now calls `omarchy-restart-walker` at the end, which restarts `elephant.service` + `app-walker@autostart.service` and reattaches the clipboard to the live compositor.
+
+### v0.1.4 — portal recovery race fix
+
+- The initial `deckshift-portal-recovery` helper restarted all five services (xdg-desktop-portal-hyprland, xdg-desktop-portal, pipewire, pipewire-pulse, wireplumber) simultaneously. That raced — the portals could come up before wireplumber had rebuilt the node graph, leaving the screencast portal bound to nothing.
+- Rewritten as a serialised sequence: push live `WAYLAND_DISPLAY`/`XDG_*` env into systemd-user + D-Bus activation env → stop portals → SIGTERM/SIGKILL stragglers → restart pipewire stack → wait → start portals.
+- Thanks to the user on the issue tracker who diagnosed the race and supplied the env-update + serialised-restart sequence.
+
 ### v0.1.3 — power-state save/restore + reliable exit

 - **Saves your real pre-Gaming-Mode state** (CPU governor + power profile) on entry to `~/.cache/deckshift/saved-state` and restores those exact values on exit. No more guessing `powersave`/`balanced`.
@ -431,17 +447,17 @@ See [Recovery from a Black Screen](#recovery-from-a-black-screen) for how to get
 - Check PipeWire config exists: `cat /etc/pipewire/pipewire.conf.d/10-gaming-latency.conf`
 - Try lower quantum: edit the config and set `default.clock.min-quantum = 128`

-**Screen sharing in Chromium / Firefox is broken after returning from Gaming Mode (only "Share a tab" works)**
+**Screen sharing in Chromium / Firefox is broken after returning from Gaming Mode (only "Share a tab" works) — and/or clipboard is dead**

-`xdg-desktop-portal-hyprland` is bound to the killed Hyprland instance — tab capture works because it bypasses the portal, but desktop/window capture goes through it and fails silently.
+Both symptoms have the same root cause: `xdg-desktop-portal-hyprland` and Walker's `elephant.service` (the clipboard listener) are still bound to the killed Hyprland instance after the SDDM restart. Tab capture in Chromium works because it bypasses the portal entirely. Clipboard listening, screen capture, and window capture all go through services that need to be reattached to the live compositor.

-DeckShift handles this automatically via `/usr/local/bin/deckshift-portal-recovery` (autostarted from `~/.config/hypr/autostart.conf`). If you installed before this fix or the autostart hook didn't get added, run:
+DeckShift handles this automatically via `/usr/local/bin/deckshift-portal-recovery` (autostarted from `~/.config/hypr/autostart.conf`). If you installed before this fix, re-run `./deckshift.sh` to install the helper, or run the recovery manually:

 ```bash
-systemctl --user restart xdg-desktop-portal-hyprland xdg-desktop-portal pipewire pipewire-pulse wireplumber
+touch /tmp/.deckshift-just-returned && /usr/local/bin/deckshift-portal-recovery
 ```

-then re-open the browser tab.
+then re-open the browser tab. (The `touch` is needed because the helper is a no-op without the marker file — that's deliberate, so it doesn't bounce portals on every normal login.)

 **Suspend fails with "Access denied" after returning from Gaming Mode**

--- a/deckshift.sh
+++ b/deckshift.sh
@ -3,8 +3,8 @@
 # DeckShift - Steam Deck Mode for Linux + Hyprland
 #
 # Forked from Super-Shift-S-Omarchy-Deck-Mode (v12.27) → renamed Omarchy Deck →
-# renamed DeckShift. Currently targets Omarchy/Arch but distro-portability is
-# the next direction. Extended with:
+# renamed DeckShift. Targets Omarchy (Arch + Hyprland + SDDM + Walker). Extended
+# with:
 #   - NVIDIA GSP-aware driver branch selection (legacy 580xx for Pascal/Maxwell)
 #   - omarchy-pkg-add idempotent package installs
 #   - Optional Xbox Bluetooth controller support (xpadneo-dkms)
@ -34,7 +34,7 @@ set -Euo pipefail
 # -u: Treat unset variables as errors (catches typos in variable names)
 # -o pipefail: A pipeline fails if ANY command in it fails, not just the last one

-DECKSHIFT_VERSION="0.1.4"
+DECKSHIFT_VERSION="0.1.6"

 # Resolve the directory this script lives in so we can find sibling files like
 # bin/deckshift-settings and applications/deckshift-settings.desktop when
@ -2431,7 +2431,8 @@ KEYBIND_MONITOR
  # screencast portal would bind to nothing. We now (a) push live session
  # env into D-Bus + systemd --user so portals activate against the new
  # Wayland socket, (b) stop portals first, (c) restart pipewire and wait
-  # for the graph, (d) start portals last.
+  # for the graph, (d) start portals last, (e) restart Walker/elephant so
+  # the clipboard listener reattaches to the live Wayland socket too.
  info "Creating portal recovery helper..."
  local portal_recovery="/usr/local/bin/deckshift-portal-recovery"

@ -2466,6 +2467,10 @@ sleep 2

 # Now bring portals up cleanly.
 systemctl --user start xdg-desktop-portal-hyprland.service xdg-desktop-portal.service 2>/dev/null || true
+
+# Walker (elephant) holds the clipboard listener, which is also bound to the
+# dead Hyprland's Wayland socket and stays broken until restarted.
+omarchy-restart-walker >/dev/null 2>&1 || true
 PORTAL_RECOVERY

  sudo chmod +x "$portal_recovery"