tool-ring (Super+G) not working on ported machine: implementation guide, failure modes, verification

[nethum529]

Companion to #9/#12. Ground truth verified live on the source laptop 2026-08-09.

How tool-ring REALLY works here

• What it is: a GTK4 layer-shell radial launcher, pure Python, from
  https://github.com/nethum529/tool-ring (cloned by install.sh to
  ~/Projects/tool-ring, symlinked to ~/.local/bin/tool-ring).
• The bind: Super+G comes from Ambxst (binds.json → generated conf):
  bind = SUPER, G, exec, /home/nethum/.local/bin/tool-ring — an ABSOLUTE
  path. So it needs (a) Ambxst binds working (issue Workspaces + Super+# + Super+Tab not working on ported machine: implementation guide, failure modes, verification #9) and (b) that exact
  path existing.
• The LD_PRELOAD trick (critical): gtk4-layer-shell must be loaded before
  libwayland-client or the overlay silently fails to become a layer surface.
  bin/tool-ring wraps the launch with
  LD_PRELOAD=/usr/lib/libgtk4-layer-shell.so. Running python3 tool_ring.py
  directly is NOT supported — you get a normal window or nothing, with no error.
• Runtime deps: gtk4, gtk4-layer-shell, python-gobject. These were
  missing from packages.txt until PR tool-ring runtime deps in packages.txt #13 — a ported machine almost certainly
  lacks gtk4-layer-shell, which alone explains 'struggling'.
• Public vs private (important for 1:1): the laptop's actual
  ~/.local/bin/tool-ring is NOT the repo symlink — it is a local wrapper
  running a PRIVATE copy at ~/.local/share/tool-ring/tool_ring.py that
  carries personal launch commands, deliberately kept out of every public repo.
  The public repo ships a sanitized default ring. A ported machine gets the
  sanitized ring; that is expected, not a bug.

Implementation

cd ~/linux-setup && git pull                     # must include PR #13
sudo pacman -S --needed gtk4 gtk4-layer-shell python-gobject
./install.sh --no-pkgs                           # clones repo + makes the symlink (idempotent)
ls -l ~/.local/bin/tool-ring                     # -> ~/Projects/tool-ring/bin/tool-ring
tool-ring                                        # test from a terminal first

Optional 1:1 private ring (manual, NEVER commit it): from the laptop over
tailscale: scp -r nethum-cachyos:~/.local/share/tool-ring ~/.local/share/
then replace the symlink with a wrapper that preloads gtk4-layer-shell and
runs ~/.local/share/tool-ring/tool_ring.py (copy the laptop's
~/.local/bin/tool-ring file itself).

Failure modes, most likely first

1. gtk4-layer-shell not installed (pre-tool-ring runtime deps in packages.txt #13 checkout). Symptom: ring opens
   as a floating tiled window, or nothing. pacman -Q gtk4-layer-shell.
2. python-gobject missing: ModuleNotFoundError: No module named 'gi'
   when running tool-ring in a terminal.
3. Super+G dead but terminal launch works → the bind layer, not tool-ring:
   Ambxst not running (Workspaces + Super+# + Super+Tab not working on ported machine: implementation guide, failure modes, verification #9), or the absolute path broken —
   ~/.local/bin/tool-ring missing (install.sh symlink step skipped) or a
   non-nethum username (binds.json carries /home/nethum; the parity seed
   rewrites it, but Ambxst regenerates from binds.json later — edit
   binds.json's tool-ring entry for other usernames).
4. Agent bypasses the wrapper (python3 tool_ring.py): silent layer-shell
   failure by design; always launch via bin/tool-ring.
5. LD_PRELOAD path wrong on non-Arch layouts: wrapper hardcodes
   /usr/lib/libgtk4-layer-shell.so; verify the file exists.
6. X11/XWayland session: layer-shell is a Wayland protocol; must be a
   Hyprland (Wayland) session.

Verify correctness

pacman -Q gtk4 gtk4-layer-shell python-gobject   # all present
test -e /usr/lib/libgtk4-layer-shell.so && echo preload-ok
ls -l ~/.local/bin/tool-ring                     # symlink (or private wrapper)
tool-ring &                                      # ring renders at cursor as an overlay
hyprctl binds | grep 'SUPER, G'                  # exec → .../tool-ring

Functional: press Super+G — the ring appears centered on the cursor as an
overlay above tiled windows (not a managed tile), mouse selection launches the
tool, Escape/click-away dismisses it.