omarchy-battery-tooltip/install-battery-tooltip.NOTES.md

install-battery-tooltip.sh — design notes

Notes to travel with the script when copying it to another machine for the omarchy PR.

What it does

Enriches Omarchy's stock waybar battery tooltip from a minimal 5W↓ 69% into a full readout:

󰁿 Battery 69% · 03h:49m left · ↓10.3W/57Wh

Wrapped in an accent-colored border that matches the active theme.

Two files are patched:

File	What changes
~/.config/waybar/config.jsonc	5 keys in the "battery" block
~/.config/waybar/style.css	@import of walker.css + tooltip rules (markered)

Design decisions

1. Laptop detection (layered, skip cleanly on desktops):

   • hostnamectl chassis (primary — systemd's DMI + heuristics)
   • /sys/class/dmi/id/chassis_type (SMBIOS fallback)
   • Battery presence (last resort)
   • --force to override

2. Idempotent by construction:

   • config.jsonc: Python regex + brace-depth parser finds the "battery" block, replaces known keys in-place, inserts missing ones. Safe on stock omarchy AND on already-patched systems.
   • style.css: /* >>> battery-tooltip */ marker block — any re-run replaces between markers instead of accumulating. The walker.css @import is only added if not already present.

3. Capacity modes:

   • Default design — rated spec from energy_full_design (or charge_full_design × voltage_min_design if only mAh files exist). Never changes, never needs refreshing.
   • --current — uses energy_full / charge_full, reflects battery degradation. Drifts over time; user re-runs when they want a refreshed number.

4. Theme following:

   • Border color uses @selected-text from the theme's walker.css. omarchy-theme-set swaps the ~/.config/omarchy/current/theme symlink → border updates automatically on next waybar reload.
   • Font follows because omarchy-font-set rewrites both waybar's style.css font-family AND fontconfig's monospace alias, which our <span face='monospace'> wrapper picks up.

5. Zero-padded time (03h:49m not 3h 49m):

   • format-time: "{H:02}h:{M:02}m" keeps the tooltip a constant width with no leading-space that would compound with template spacing.

6. Monospace wrapper forces stable width:

   • <span face='monospace'>...</span> around the dynamic fields so digit-count transitions (5W → 10W, etc.) don't rewidth the tooltip. <tt> was unreliable in GTK tooltips; face='monospace' is honored consistently.

Output matrix

Scenario	Result	Exit
Laptop	Installs	0
Desktop / VM / server	Skips with info message	0
Desktop with --force	Installs anyway	0
--current	Uses degraded capacity	0
--help	Prints header comment	0
Missing waybar / no python3	Errors with hint	1
Laptop but unreadable sysfs	Errors with path	1
Laptop but no "battery" block	Errors with hint	1

Dependencies

• bash, awk, find, python3 — all in omarchy's base install.
• omarchy-restart-waybar — optional; if present, waybar is restarted automatically. If absent, the installer just reports completion.

Tested on

• Acer laptop, BAT1 (charge-based sysfs, Li-ion, ~57Wh design, 18 cycles).
• Fresh stock omarchy configs (both config.jsonc and style.css).
• Re-runs (3× identical checksums → idempotent).
• Simulated desktop via hostnamectl override.
• Unknown-flag and missing-battery paths.

PR suggestions for the omarchy distro

• If adding to the install flow, call the installer non-interactively. It handles "not a laptop" internally as a zero-exit skip, so no guards needed at the caller.
• If omarchy adds a global install-time hook mechanism, this could live there. Otherwise place it in the laptop-specific install path.
• Backup files (*.bak.<timestamp>) accumulate on each re-run. Consider adding the installer to a path where backups are either swept, or add a --no-backup flag if the install flow doesn't want them.

Caveats / known edge cases

• Capacity padding {capacity:>3} means Battery 5% at single-digit %, Battery100% at 100%. Width stays constant; visible gap varies. Zero-padding (005%) was rejected as uglier.
• Similarly ↓{power:>4.1f} shows ↓ 5.2W vs ↓10.3W.
• Full/plugged tooltips don't have {time} available so they use a simpler format without the monospace span.
• {icon} is NOT supported in tooltip-format-* for the battery module (waybar errors "argument not found"). We use static state glyphs instead — still theme-consistent since all omarchy-managed fonts are Nerd Fonts.

File layout after install

~/.config/waybar/
├── config.jsonc              # battery block patched
├── config.jsonc.bak.<ts>     # timestamped backup per run
├── style.css                 # walker.css import + marker block
└── style.css.bak.<ts>        # timestamped backup per run