mesh-catalog/modules/picom/README.md

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.