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.

Settings

Two preferences, each a machine's own (the per-node layer of settings), because the right values follow the machine's graphics driver (novox/hq research 037):

setting	default	what it changes
backend	glx	how picom draws: glx on the graphics card, xrender on the CPU
use-damage	true	true repaints only what changed (picom's own default); false repaints the whole screen each frame

The defaults are what every machine ran before, so the file filled with them changes nothing. They exist for hq issue 345: a window that is mapped but shows nothing (a calendar reminder) or stays stale after a workspace switch (a chat window) is a known failure of glx with damage tracking on some drivers, and xrender or use-damage false is how a machine is set to test that. The file stays trusted, so both are set at the controller's terminal alone (issue 339): a value is pasted into picom.conf as it is, and a backend of xrender"; write-pid-path = "… would add an option of the caller's (hq issue 346). A changed file is read at the next picom_restart or login: the module has no unit to reload.

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 lies outside its directory

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.

Files it does not know

Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).

• ~/.config/picom: holds only what this module declares; anything else is moved out by the node-engine to ~/.local/state/mesh-moved/picom/ with a list, never deleted (ADR 0422 §4).