Module splash_linux 

Session-aware Linux startup splash.

The launcher is up in milliseconds; agentmux-cef is the multi-second cold start (CEF init + GPU channel + page load). This paints a pulsing brain logo over a dark backdrop in that gap — the Linux analogue of splash.rs (Win32) and splash_mac.rs (Cocoa).

The backend is chosen for centering fidelity, not to mirror the host’s ozone choice: the X11 backend draws an override_redirect window it positions itself (centered on the primary monitor) and XWayland honors that, so it centers under both X11 and native-Wayland sessions. A native-Wayland xdg_toplevel, by contrast, cannot self-position — Mutter drops small toplevels at the top-left, not centered. XWayland is present in nearly every Wayland session, so we prefer the X11 backend whenever an X server is reachable and fall back to the Wayland backend only when there is no X display at all.

Dismiss protocol is the macOS one: spawn() sets AGENTMUX_SPLASH_READY_FILE (the host inherits it and writes the file on first paint); the splash thread polls for that file and tears down, with a safety timeout for a host that crashes before painting.

Spec: docs/specs/SPEC_LINUX_SPLASH_SESSION_AWARE_2026_06_20.md

Modules

wayland 🔒

Wayland splash backend — a software-drawn (wl_shm) xdg_toplevel showing the pulsing brain. This is the fallback path, used only when no X server is reachable (super::detect prefers the self-centering X11/XWayland backend whenever XWayland is up — see that module’s doc for why).

x11 🔒

X11 splash backend — a software-drawn, override-redirect window showing the pulsing brain over a dark backdrop, dismissed (with a fade-out) when the host writes the ready-file or after the safety timeout. For X11 / XWayland sessions.

Structs

StageList 🔒

Accumulates startup events and emits rendered text lines for the stage band.

Enums

Session 🔒

Constants

BG_B 🔒

BG_G 🔒

BG_R 🔒

Opaque dark backdrop RGB(26, 26, 31) = #1A1A1F.

BORDER_B 🔒

BORDER_G 🔒

BORDER_R 🔒

BORDER_WIDTH_PX 🔒

BRAIN_H

BRAIN_W

CARD_H 🔒

CARD_W 🔒

Full card dimensions: brain + padding, stage band, footer band.

CORNER_RADIUS_PX 🔒

Rounded-corner radius for the backdrop (px). Matches splash_mac.rs.

DISMISS_TIMEOUT 🔒

Self-dismiss if the host never signals first paint (crash before frame).

FADE_IN_S 🔒

FADE_OUT 🔒

Opacity fade-out duration on dismiss. Matches splash_mac.rs.

FOOTER_COLOR 🔒

Muted footer text color (#8A8A93) on the #1A1A1F backdrop.

FOOTER_H 🔒

Bottom band height: top pad + 2 glyph rows + inter-line gap + bottom pad.

FOOTER_LINE_GAP 🔒

FOOTER_PAD_BOTTOM 🔒

FOOTER_PAD_TOP 🔒

FRAME_MS 🔒

~60 fps animation tick.

PADDING 🔒

Backdrop padding around the brain, in px.

PULSE_HZ 🔒

PULSE_MAX 🔒

PULSE_MIN 🔒

STAGE_COLOR 🔒

Muted stage text color — slightly brighter than the footer for readability.

STAGE_H 🔒

Height of the stage band.

STAGE_LINE_GAP 🔒

Vertical gap between stage lines.

STAGE_MAX_LINES 🔒

Maximum number of stage lines shown simultaneously.

STAGE_PAD_TOP 🔒

Vertical padding above the first stage line.

STAGE_X 🔒

Left margin for stage lines (px from card edge).

Statics

BRAIN_RGBA 🔒

Brain logo as straight (non-pre-multiplied) RGBA8, emitted by build.rs.

Functions

corner_coverage 🔒

Rounded-rect coverage (0..=1) at pixel (x, y) for a w×h rect with corner radius (0 = square), anti-aliased over a 1-px band on the corner arcs.

detect 🔒

Pick the splash backend by centering ability. The X11 backend self-centers (override-redirect, positioned on the RANDR primary) and XWayland honors that, so prefer it whenever an X server is actually reachable — including under a native-Wayland session, where the Wayland backend can’t self-center and Mutter drops the splash top-left. Only with no usable X display do we fall back to the best-effort Wayland backend.

fade_alpha 🔒

Global fade-out opacity in 0..=1. Returns 1.0 until fade_start is set, then ramps linearly to 0.0 over FADE_OUT. Shared by both backends.

min_hold 🔒

Minimum on-screen time before the splash is allowed to dismiss, so a fast cold start can’t produce a sub-perceptible flash (worse than no splash). Overridable via AGENTMUX_SPLASH_HOLD_MS — also handy for eyeballing the splash during testing (e.g. AGENTMUX_SPLASH_HOLD_MS=3000).

pulse_alpha 🔒

Pulse alpha in 0..=1 for elapsed seconds since the splash appeared: a linear ramp 0→1 over FADE_IN_S, then a PULSE_HZ sine between PULSE_MIN..PULSE_MAX (the backdrop stays opaque; only the brain’s alpha breathes). Shared by both backends.

render_frame 🔒

Composite one frame, pre-multiplied, into a 4-byte-per-pixel buffer: the dark backdrop with the centered brain blended at brain_alpha, the stage list band, and the footer identity strip — all masked to a radius-rounded rect and scaled by the global window_alpha (fade-out). Pre-multiplied output is what both X Render compositors and wl_shm ARGB8888 expect. bgr selects byte order: true → B,G,R,A (X11 ARGB / Wayland ARGB8888 on LE), false → R,G,B,A. Shared by both backends.

spawn

Spawn the startup splash. Sets AGENTMUX_SPLASH_READY_FILE (inherited by the host, which writes it on first paint) and runs the matching backend on a dedicated thread, so the launcher’s main thread continues to start srv + host. The thread self-terminates on first-paint or the safety timeout. Best-effort: any failure (no display, protocol error) just means no splash — the launcher is unaffected.