Adom Bridge

@@ -0,0 +1,87 @@+# Adom Bridge on Linux++Adom Bridge for Linux is the same app as on Windows, built from the same code and shipped in the same release. It signs in to the same Adom account, joins the same mesh, runs the same bridges, and answers the same verbs from the relay, the mesh and the local API (`127.0.0.1:24680`). It is packaged as one AppImage that runs on any recent x86_64 distribution (tested on Ubuntu 24.04, Fedora 44 and Debian 13; GNOME, Cinnamon; Wayland and X11).++Linux builds are on the **insiders** tier for now: the AppImage is an asset of each Adom Bridge release on this page, and the insiders manifest's `linux` entry is what Linux machines update from.++## Install++Download `adom-bridge_<version>_linux_x86_64.AppImage` from this page's release, then:++```bash+chmod +x adom-bridge_*_linux_x86_64.AppImage+./adom-bridge_*_linux_x86_64.AppImage --install+```++`--install` needs no sudo and writes only under your home folder:++| Path | What it is |+|---|---|+| `~/.local/share/adom-bridge-app/adom-bridge_<version>_linux_x86_64.AppImage` | the app |+| `~/.local/share/adom-bridge-app/adom-bridge-app.AppImage` | a stable link to it; self-update repoints it |+| `~/.local/share/adom-bridge-app/run.sh` | the launcher: starts one copy and exits quietly if one is running |+| `~/.local/share/applications/inc.adom.bridge.desktop` | the app menu entry |+| `~/.config/autostart/inc.adom.bridge.desktop` | start at login (Settings > Launch on boot turns it off and on) |++It then starts Adom Bridge. Running `--install` again from a newer AppImage upgrades in place. `--install --no-launch` installs without starting it. FUSE is not needed.++**Always start it through `run.sh`** (the menu entry and autostart do). Two copies of Adom Bridge on one machine share one identity and keep knocking each other off the relay; `run.sh` takes a lock and checks for a running copy first.++To remove it: quit Adom Bridge, then delete the paths above plus `~/.local/share/icons/hicolor/256x256/apps/adom-bridge.png`. Your settings and sign-in live in `~/.adom/`.++## With Hydrogen++On a machine that runs Hydrogen, Adom Bridge runs embedded, as on Windows:++- **One sign-in.** If Adom Bridge is signed out, it uses Hydrogen's Adom session; you are not asked to sign in twice. If you sign out of Adom Bridge yourself, it stays signed out until you sign in again.+- **It joins your mesh.** If nobody has chosen a mesh mode on this machine, Adom Bridge switches the mesh on in relay mode (nothing listens on your network). Your other machines then show a card asking you to let the new machine in. A mode you chose, including off, is never changed.+- **Approvals show in Hydrogen** as well as in Adom Bridge and in the desktop notification.++## Bridges and runtimes++Bridges with a Linux build (python, node, or a native `spawn.entrypoints.linux`) install and run as on Windows.++- **Node:** Adom Bridge uses your Node if it is version 18 or newer and has npm (it looks on PATH and in the usual places: nvm, volta, fnm, `/usr/local`, snap). Otherwise it downloads the official Node build for your CPU from nodejs.org into `~/.adom/adom-runtimes/` and checks its SHA-256 against the value built into the app before using it. No sudo, nothing installed system-wide.+- **Python:** your distribution's `python3`. If it is missing, the error says how to install it.++`adom-bridge runtimes` shows what each bridge will run with.++## Screenshots and windows++| | X11 | Wayland |+|---|---|---|+| `desktop_screenshot_screen` | read from the X server, no tools needed | through the desktop's screenshot service (xdg-desktop-portal) |+| `desktop_screenshot_window` | the window's area of the screen | the window's area of the screen, for windows running under XWayland |+| `desktop_list_windows` | every window | windows running under XWayland only (on a stock GNOME desktop most apps are native Wayland, so the list is often empty and the reply says why) |++**Allowing screenshots on Wayland.** The first screenshot on a Wayland desktop asks the person at the screen once: *Allow Adom Bridge to Take Screenshots?* Choose **Allow** and later screenshots are silent. GNOME shows this question only while Adom Bridge's window is the focused window; if it is not, the screenshot fails with a message asking the person to click Adom Bridge's window and try again. To allow it ahead of time, or after choosing Deny:++```bash+flatpak permission-set screenshot screenshot inc.adom.bridge yes+```++(The `flatpak` command manages the desktop's permission store; Adom Bridge itself is not a Flatpak.) The screenshot service saves each capture to a file, which Adom Bridge reads and deletes at once.++## Notifications and approvals++Permission prompts appear as desktop notifications with their buttons (**Approve 1 hr**, **Deny**, and so on). Choosing one in the notification decides the request, exactly like the same button in Adom Bridge's window or in Hydrogen. A decision made anywhere else closes the notification. If the desktop's notification service cannot show buttons, the notification says so and the decision is made in Adom Bridge's window.++## Updates++Adom Bridge updates itself from the insiders manifest's `linux` entry: it downloads the new AppImage, checks its SHA-256, puts it beside the old one, repoints `adom-bridge-app.AppImage`, keeps the previous version for a rollback, and starts one new copy through `run.sh` after the old one has exited. `update_mode` works as on Windows (`prompt` by default; `auto` for an unattended machine).++## What does not work on Linux yet++| Feature | Status |+|---|---|+| Input verbs (`desktop_click`, `desktop_type`, ...) | not yet; planned: X11 first, then Wayland through the desktop's remote-control service |+| UI Automation (`desktop_ui_*`) | Windows only |+| Screen and window recording (`desktop_record_*`) | Windows only |+| Windows-only bridges (an `.exe` with no Linux entry, such as Fusion 360) | listed, never started; their verbs answer `unsupported_on_this_os` |++## Troubleshooting++- **It does not start / no window:** run `~/.local/share/adom-bridge-app/run.sh` and read `~/.local/share/adom-bridge-app/app.log`.+- **"Could not create default EGL display":** the AppImage carries its own Mesa EGL and uses it when the machine has none. `ADOM_BRIDGE_EGL=bundled` or `=system` forces one or the other.+- **A node bridge does not start:** `adom-bridge runtimes` shows whether Node was found or downloaded, and why a system Node was skipped.+- **Screenshots fail on Wayland:** the error says whether the screenshot service is missing, waiting for the person to answer, or was refused, and what to do.

@@ -2,21 +2,31 @@ name: adom-bridge-linux
 description: >-
   For Adom Bridge running on a Linux machine (the AppImage), not the adom-bridge CLI in a
-  container: install one copy, self-update, what is still Windows-only, Grok Bot computers
-  (wake with grok_wake). Use when installing, updating or debugging ab on Linux, or a Linux
-  mesh peer is unreachable.
+  container: --install, one copy, self-update, Wayland screenshots, what is still Windows-only,
+  Grok Bot computers. Use when installing, updating or debugging ab on Linux, or a Linux mesh
+  peer is unreachable.
 ---
 
 # Adom Bridge on Linux
 
-The Linux build is the same app as on Windows, packaged as an AppImage
-(`adom-bridge_<version>_linux_x86_64.AppImage`). It signs in to the same Adom
-account, joins the same mesh, and answers the same verbs from the relay, the mesh
-and the local API (`127.0.0.1:24680`). It is a **private preview**: the AppImage
-lives on the insiders tier, not the public page.
+The Linux build is the same app as on Windows, built from the same code and shipped
+in the same release, packaged as an AppImage
+(`adom-bridge_<version>_linux_x86_64.AppImage`, an asset of the release on
+adom/adom-bridge). It signs in to the same Adom account, joins the same mesh, and
+answers the same verbs from the relay, the mesh and the local API
+(`127.0.0.1:24680`). Linux is on the **insiders** tier: only the insiders
+manifest has a `linux` entry until a human promotes it.
 
 ## Install and launch: one copy, always
 
+**The AppImage installs itself:** `./adom-bridge_<ver>_linux_x86_64.AppImage --install`
+(no sudo, no FUSE). It copies itself to `~/.local/share/adom-bridge-app/`, points
+`adom-bridge-app.AppImage` at it, writes the locked `run.sh` below, a menu entry
+(`~/.local/share/applications/inc.adom.bridge.desktop`) and, while Launch on boot is on,
+`~/.config/autostart/inc.adom.bridge.desktop` (both run `run.sh`), then starts it.
+`--no-launch` skips the start. Running it again from a newer AppImage upgrades in place.
+What it sets up, and why:
+
 - Keep the AppImage in a folder of its own, for example
   `~/.local/share/adom-bridge-app/`, with a stable symlink
   `adom-bridge-app.AppImage -> adom-bridge_<version>_linux_x86_64.AppImage`.
@@ -32,7 +42,8 @@ lives on the insiders tier, not the public page. - Set `DISPLAY` to the X display it should use.
 - `adom-bridge-app --version` prints the version and exits; it never starts a copy.
 
-A minimal `run.sh`:
+The `run.sh` that `--install` writes is equivalent to this minimal one (it also
+matches a FUSE-mounted `/tmp/.mount_*` copy and passes its arguments through):
 
 ```bash
 #!/bin/bash
@@ -85,9 +96,35 @@ overrides). No `libs/` folder or extra packages are needed. | Works | Not yet (Windows only) |
 |---|---|
 | shell_execute, run_script, files (send_files, pull_file, read/write) | input verbs (desktop_click, desktop_type, ...) |
-| desktop_screenshot_screen, desktop_screenshot_window, desktop_list_windows (X11, 2.1.181+, no tools needed) | UI Automation (desktop_ui_*) |
-| bridges with a Linux build (python, node, or `spawn.entrypoints.linux`) | Windows-only bridges (a `.exe` with no Linux entry): listed, never started, verbs answer `unsupported_on_this_os` |
-| self-update, mesh, relay, notifications (notify-send) | recording |
+| desktop_screenshot_screen, desktop_screenshot_window, desktop_list_windows on X11 (no tools needed) and Wayland (see below) | UI Automation (desktop_ui_*) |
+| bridges with a Linux build (python, node, or `spawn.entrypoints.linux`); Node is the system one if 18+ with npm, else a verified nodejs.org download | Windows-only bridges (a `.exe` with no Linux entry): listed, never started, verbs answer `unsupported_on_this_os` |
+| self-update, mesh, relay, notifications with buttons (approve from the notification) | recording |
+
+## Wayland
+
+ab usually runs under XWayland on a Wayland desktop (Ubuntu and Fedora GNOME), so X11
+answers but cannot read the screen.
+
+- `desktop_screenshot_screen` uses the xdg-desktop-portal Screenshot service. The first
+  capture on a machine shows the person a one-time *Allow Adom Bridge to Take Screenshots?*
+  prompt (GNOME shows it only while Adom Bridge's window is focused; otherwise the verb fails
+  at once and says to ask the person to click Adom Bridge's window, then retry); the verb waits up to 45 s, then fails with an error saying it is waiting for that
+  answer. After Allow, captures are silent. If it was refused:
+  `flatpak permission-set screenshot screenshot inc.adom.bridge yes` (the permission store, not a Flatpak
+  install). Check the stored answer with
+  `flatpak permission-show screenshot` or `gdbus call --session --dest org.freedesktop.impl.portal.PermissionStore --object-path /org/freedesktop/impl/portal/PermissionStore --method org.freedesktop.impl.portal.PermissionStore.Lookup screenshot screenshot`.
+- `desktop_screenshot_window` works for XWayland windows (the portal capture, cropped).
+  A native Wayland window (most GNOME apps, Firefox, Hydrogen) has no readable position:
+  capture the screen.
+- `desktop_list_windows` lists XWayland windows only (stock GNOME refuses its full list to apps),
+  so it is often empty there; the reply's `_hint` says so.
+
+## With Hydrogen
+
+- Signed out + embedded: ab takes Hydrogen's session (`GET /auth-token` on Hydrogen's
+  loopback API); no second sign-in. A Sign out in ab's window is remembered.
+- Embedded, mesh off, and nobody ever chose a mode (no `~/.adom/mesh/mode-choice.json`):
+  ab switches the mesh to `relay` and records that; the other boxes show the join card.
 
 Commands a bridge or script runs get the machine's own environment, not the
 AppImage's private library paths, so `python3` and `curl` work normally.