jschoubben
a7953b969d
A calendar reminder showed as a transparent, empty window on shanks and no tool could say which window it was or which preferences Betterbird ran with. The module owns one file, the user.js its setting prefs fills, which its tools place whole into the profile Betterbird uses and never over an operator's own; it reads named preferences without credentials or accounts, restarts Betterbird under the user manager so its output reaches the journal, checks what it promises, and shows a reminder on demand from a throw-away profile so a fix can be proved without the operator's calendar. No package: betterbird-bin is the AUR's.
betterbird
Betterbird, the mail and calendar client of g14 and shanks (a Thunderbird fork, with the operator's
Exchange calendar through the Owl add-on), as a module (novox/hq issue 345, ADR 0208). It requires
x11-display, so it is assigned only where a display server is held on the same machine.
It exists because a symptom had no tools: on a workstation, a calendar reminder appeared as a transparent window with nothing in it (2026-10-09). Nothing in the mesh could say which window that was, how the compositor treats it, or which preferences Betterbird ran with. The diagnosis is in hq issue 345.
Owns
| what | where |
|---|---|
| the module's directory | ~/.config/betterbird/ |
the module's user.js, filled from the setting prefs |
~/.config/betterbird/user.js |
Nothing else. It holds no seat and adds no start.
- No package. g14 and shanks both run
betterbird-bin153.1.0esr-1, installed explicitly from the AUR:pacmancounts it as foreign. The node-engine installs packages from the official repositories only, so the module does not declare it, and installing and upgrading Betterbird stay the operator's (an AUR helper).betterbird_statussays the version and that it is from the AUR;betterbird_checksays when it is missing. - No start. Betterbird is started by the operator from the launcher (on the workstation measured,
it runs in the login session's scope, started by hand, with no autostart entry and no line in i3's
configuration).
betterbird_restartstarts it as the transient user unitmesh-betterbird, so its output then goes to the journal. - The profile is Betterbird's (ADR 0182):
~/.thunderbird/holds the mail, the address books, the calendars' caches, the logins and the keys. The module declares none of it.
The user.js: how a preference is declared
Betterbird reads user.js in its profile when it starts, and a preference set there wins over the
one it saved in prefs.js. The profile's directory has a random name per machine
(<random>.default-default), which a manifest cannot name. So:
- the node-engine writes
~/.config/betterbird/user.jsfrom the module's settingprefs, one line ofuser_pref("name", value);statements (default: a comment, no preference); - the module's tools copy that file whole into the profile:
betterbird_user_jswithapply, orbetterbird_restart, which places it before it starts Betterbird again; - Betterbird reads it at that start.
The profile is found as the one the running Betterbird holds open; with none running, as the
installation's default in profiles.ini ([Install…] Default), else the profile marked Default=1.
On the workstation measured these differ: Profile1 is marked Default=1, and the installation's
default, the one in use, is the other.
A user.js the module did not write is never overwritten. The module's begins with the line
// Betterbird's user.js (module betterbird; any other is the operator's, and apply refuses with
what to do. The tools refuse a declared file that holds anything but comments and user_pref
statements, or that sets a preference whose name can hold a credential.
The file is trusted (it carries no "trusted": false): a preference can weaken how the mail client
checks a server, so the setting is changed only at the controller's terminal, never through a verb
(novox/hq issue 339).
Tools
They are served by the node's runtime as the operator account (ADR 0175). No answer carries mail, a calendar entry, an account, an address or a credential.
| tool | does |
|---|---|
betterbird_status (r) |
whether it runs (pid, since, scope, children), the package and version and that it is from the AUR, where its output goes, the profile and how it was found, the user.js (declared, placed, in effect), the add-ons the operator installed (ids), and the preferences that decide how its windows and notifications look |
betterbird_prefs (r) |
named preferences or prefixes (ending in . or *, at most 200): value and source (user.js, prefs.js or the default). A name that can hold a credential (password, token, oauth, signon, …) or that names an account, server, calendar or person (mail.server., mail.identity., calendar.registry., extensions.owl., …) is answered without its value |
betterbird_user_js (r; a with apply) |
the declared user.js against the profile's; apply places it |
betterbird_log (r) |
the last lines of the journal of mesh-betterbird (or of the reminder test), addresses and credentials masked. A Betterbird the module did not start prints elsewhere, and the answer says where |
betterbird_restart (a) |
ends Betterbird (asked to quit, forced after 20 s), places the user.js where allowed, starts it as mesh-betterbird. An unsent message in a composer is lost: ask the operator first |
betterbird_check (r) |
installed; one running; profile found; the user.js on the machine, valid, placed, in effect; its output read |
betterbird_reminder_test (a) |
a reminder on demand without the operator's calendar (below) |
A reminder on demand
betterbird_reminder_test starts a second Betterbird with --no-remote in a throw-away profile
under /run/user/<uid>/mesh-betterbird-reminder-test/, as the user unit
mesh-betterbird-reminder-test (ended after 10 minutes at most). The profile holds the module's
user.js and one calendar: a local .ics file with one event, "Mesh reminder test", whose reminder is
due after seconds from the call (default 40). carry copies named preferences of the operator's
profile into it (a theme, a colour switch), under the same limits as betterbird_prefs. Then:
xorg_windowswith classCalendaranswers the reminder window: roleAlarmWindow, typeDialog, its depth (32: a visual with alpha, which the compositor blends), its map state;xorg_screenshotwith that window shows it as the screen shows it.
stop ends it and removes the profile. The running Betterbird, its profile and its calendars are not
touched: --no-remote keeps the two apart.
The reminder window, as measured (2026-10-09, workstation, i3 and picom with glx)
| X class / instance | eu.betterbird.Betterbird / Calendar |
| role, type | AlarmWindow, _NET_WM_WINDOW_TYPE_DIALOG (i3 floats it) |
| depth | 32 (ARGB visual), like every Betterbird window there |
| size | 600×300, kept in the profile's xulstore.json |
A window of depth 32 that its program has not drawn is transparent under a compositor, not black: that is why the symptom looks the way it does. Why Betterbird did not draw it is hq issue 345's question.
What changes when it is assigned
| g14 | shanks | |
|---|---|---|
| files | ~/.config/betterbird/ and its user.js (no preference) |
the same |
| the profile | untouched until betterbird_user_js with apply or betterbird_restart |
the same; the profile has no user.js today, so apply may place one |
| Betterbird | keeps running as started | keeps running as started (since 2026-10-04, its output on the session's pipe nobody reads: betterbird_check names it until betterbird_restart) |
Relies on
- A display server on the same machine (
x11-display, ADR 0208 §3). xorgforxorg_windowsandxorg_screenshot, which look at Betterbird's windows. This module carries no window code of its own.systemd-runandjournalctlof the account's user manager.