# 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.