picom: the compositor as a module, claiming node-compositor (hq ADR 0208)

Owns its configuration, moved to picom's window rules; started once from the
session's xinitrc slot; Go tools restart, rules, window-opacity and toggle, which
find the operator's X session from the window manager's environment.

modules/picom/README.md

@@ -0,0 +1,62 @@
+# picom
+
+The X compositor as a module (novox/hq ADR 0208, research 026).
+
+- Installs `picom`, and `xorg-xprop` for setting a window's own opacity.
+- Claims the mesh's `node-compositor` seat (no verbs yet, ADR 0208 §2) and requires `x11-display`.
+  That requirement has the machine's reach: the display server must be held on this module's own
+  machine, or assignment is refused, naming the seat's holders.
+- Owns `~/.config/picom/` and `~/.config/picom/picom.conf`, which it writes whole at every push.
+- **Adds no start of its own.** picom's package ships an XDG autostart entry
+  (`/etc/xdg/autostart/picom.desktop`), which the session runs: the `i3` module's `dex --autostart`.
+  That is the tool's own grain (ADR 0208 §4) and its one start. The desktop modules follow one rule:
+  a process has one starter. Its package's autostart entry is that starter where there is one, and
+  the `xinitrc` slot where there is none.
+
+## Tools
+
+Served by the node's runtime as the operator account (ADR 0175). The tools find the operator's X
+session from the window manager's own environment, and say so plainly when nobody is logged in.
+
+| tool | does |
+|---|---|
+| `picom_restart` | a running picom re-reads its file (`SIGUSR1`); `hard`, or none running, starts a fresh one |
+| `picom_rules` | the global options and the window rules in force, in picom's order, and whether it runs |
+| `picom_window_opacity` | read or set one window's own opacity, the focused window by default |
+| `picom_toggle` | compositing off or on, for a game or a test; the next login starts it again |
+
+A picom a tool starts runs under the account's own service manager (`systemd-run --user`, unit
+`picom`). As a child of the runtime it would die whenever the runtime restarts.
+
+## What it improves on what was found
+
+- **Window rules** replace `opacity-rule`, `inactive-opacity` and `inactive-dim`, which picom 12 and
+  later supersede. The behaviour is the same: only terminals are translucent (95 % focused, 75 %
+  unfocused). The browser and video "pin to 100 %" rule went, because nothing else is made
+  translucent any more.
+- **Full-screen windows are opaque,** a terminal included.
+- **One start.** Today both the window manager's configuration and the autostart entry start picom,
+  and the second one exits.
+- On the desktop, picom was not running at all on the day it was measured, although both starts were
+  in place. It probably fails to start on that machine's GPU. `picom_restart` with `hard` after
+  assignment answers with what happened. The next step is the `picom` user unit's journal.
+
+## What it leaves as found
+
+The window manager's own `exec --no-startup-id picom` line belongs to the `i3` module's configuration,
+which no longer carries it. Nothing else of picom's lies outside the directory this module owns.
+
+## Migration (ADR 0182)
+
+- The first push keeps the found `picom.conf` once, then writes the module's.
+- Until the `i3` module replaces the hand-kept `~/.config/i3/config`, its `exec picom` line starts a
+  second picom. The second one exits at once, because a compositor is already running. Nothing to
+  do, unless the line is still there after `i3` is assigned.
+
+## Blockers
+
+- The seat `node-compositor` and the provision `x11-display` are ADR 0208's.
+  Until the controller knows them, `mctl` reads the claim and the requirement as unknown, and refuses
+  the module.
+- `xorg-xprop` is declared here because the `xorg` module does not install it. If `xorg` comes to
+  declare it, it leaves this module, since a package is declared once per node.