hyprpanel

name: hyprpanel description: Context and rules for any task involving hyprpanel — patched launcher, custom SCSS, theme switcher, and color interpolation engine argument-hint: [task description] allowed-tools: Bash, Read, Glob, Grep, Edit, Write

HyprPanel Custom Setup

Load this before any task that touches hyprpanel config, SCSS, JS patches, theming, or the launch chain.

Critical: Always Use the Patched Launcher

Never start hyprpanel with hyprpanel, hyprpanel -q, or /usr/share/hyprpanel/hyprpanel-app directly. A PreToolUse hook (~/.claude/hooks/hyprpanel-guard.py) hard-blocks these and direct gjs -m … dmFyIF-ags.js launches.

The stock binary skips all JS patches (modules stretch to bar height, menus misposition, notification images mis-align).

hyprpanel-launch is the single source of truth for the start sequence and is theme-switcher aware. In order it: two-stage kills any running instance (SIGTERM → SIGKILL, since a frozen main loop ignores the graceful SIGTERM), removes a stale Astal D-Bus socket, persists the last theme colors (colors-new.json) into config.json, rotates diagnostic logs, then starts hyprpanel-patched with stderr captured to /tmp/hyprpanel-stderr.log. Add new start-time logic here only — never in a parallel path.

Launch Chain

hyprland.conf exec-once
  └─ ~/.config/hyprpanel/bin/hyprpanel-watchdog   (owns lifecycle; sole parent)
       └─ ~/.config/hyprpanel/bin/hyprpanel-launch  (called on start + every restart)
            └─ ~/.config/hyprpanel/bin/hyprpanel-patched
                 1. Runs stock hyprpanel-app with gjs launch line stripped (sed '/gjs /d')
                    → decodes JS bundle to $XDG_RUNTIME_DIR/dmFyIF-ags.js without executing it
                 2. Applies sed/python patches to decoded JS (incl. diagnostic instrumentation)
                 3. Runs: gjs -m $XDG_RUNTIME_DIR/dmFyIF-ags.js

The watchdog is the exec-once target (not hyprpanel-launch directly). It monitors /tmp/hyprpanel-heartbeat and restarts on freeze/death — always by calling hyprpanel-launch, so the theme-switcher-aware start path is never bypassed. See Freeze Watchdog & Diagnostics below.

Update risk: If a HyprPanel package update changes the gjs invocation line in the stock script, the sed filter /gjs /d may stop matching. Symptom: modules stretch to bar height (valign patch not applied). Check the stock script at /usr/share/hyprpanel/hyprpanel-app if this happens.

Freeze Watchdog & Diagnostics

The GJS main loop occasionally freezes (bar renders but clock stops, clicks/hover dead). hyprpanel-watchdog detects and recovers from this, and the hyprpanel-patched bundle is instrumented to diagnose the cause.

Instrumentation (injected by hyprpanel-patched at the end of the bundle):

• Heartbeat: a GLib.timeout_add writes /tmp/hyprpanel-heartbeat every 2 s and logs HEARTBEAT to /tmp/hyprpanel-diag.log. When it stalls, the main loop is blocked.
• Command trace: the Astal vfunc_request handler logs CMD_START/CMD_END <ms> per CLI call. A CMD_START with no CMD_END = the hung command.
• themeManager wrappers: applyCss, applyColorOverrides, _compileSass, _applyCss log _START/_END <ms>/_THROW/_REJECT, so a freeze during theming shows the exact stage. (Boot's first applyCss runs during module eval, before wrappers install, so it isn't traced — expected.)

Watchdog (hyprpanel-watchdog):

• Polls the heartbeat; on >8 s stale (freeze) or no gjs process (death) it captures a freeze set to ~/.local/state/hyprpanel-freezes/ — freeze-<ts>.log (per-thread wchan/syscall, gdb backtraces if Yama allows, log tails), freeze-<ts>.events.log (all non-HEARTBEAT diag lines: CMD_*/theme stages/errors), and freeze-<ts>.stderr.log. This dir is persistent (survives reboot) unlike the /tmp live logs; pruned to the newest 100 sets. It then sends SIGABRT to trigger a systemd-coredump for postmortem (coredumpctl gdb <pid>, also reboot-safe), and restarts via hyprpanel-launch.
• Circuit breaker: ≥3 restarts within 180 s pauses restarts for 15 min and sends a critical notify-send, preventing a restart spin-loop.
• Diagnostic logs auto-rotate at 5 MB (.1 segment) inside hyprpanel-launch.

If gdb attach in the report says "Operation not permitted": that's ptrace_scope=1 (Yama). Use the coredump instead — coredumpctl gdb then thread apply all bt.

JS Bundle Patches

1. Bar module vertical alignment

valign: FILL on the bar's three box containers (box-left, box-center, box-right) stretches all modules to full bar height. The patch injects valign: Gtk4.Align.CENTER on each so modules stay at their natural height and are vertically centered within the taller bar set in modules.scss.

2. Notification image centering

Adds valign: Gtk4.Align.CENTER to notification-card-image-container.

3. Dropdown menu positioning

On an ultrawide with large theme.bar.margin_sides, hyprpanel toggleWindow positions menus at the wrong X offset. A Python patch intercepts the toggleWindow handler, reads theme.bar.margin_sides and theme.bar.outer_spacing from live config, and sets correct left/right margins on the dropdown event box before toggling.

Custom SCSS (~/.config/hyprpanel/modules.scss)

HyprPanel's SCSS pipeline (in /usr/share/hyprpanel/src/style/index.ts):

1. Writes theme variables to /tmp/hyprpanel/variables.scss
2. Loads /usr/share/hyprpanel/src/style/main.scss
3. Prepends the variables @import
4. Appends modules.scss content verbatim at the end
5. Compiles with: sass --load-path=/usr/share/hyprpanel/src/style /tmp/hyprpanel/entry.scss /tmp/hyprpanel/main.css

Because modules.scss is concatenated (not imported), standard SCSS variables like $notification-label from HyprPanel's own SCSS are available. @import with an absolute path also works.

Current rules

Do not add @import statements at the top of modules.scss — they get appended after the full compiled stylesheet and can interfere with sass's import ordering. If SCSS variables from an external file are needed, either use absolute paths and test compilation manually first, or pre-compute the values in the matugen template and output them as plain CSS.

Theme Switcher (~/.config/hyprkit/theme-switch/)

theme-switch (orchestrator)

theme-switch [<wallpaper>|--random]   # apply wallpaper + regenerate all colors
theme-switch                          # open rofi wallpaper picker

On invocation:

1. Gets cursor position from hyprctl cursorpos for circle reveal origin
2. Saves current colors to /tmp/*-old.* (kitty, hyprland, gtk3, gtk4, spicetify)
3. Runs hyprpanel-colors <wallpaper> in background (computes old/new hyprpanel JSON)
4. Runs matugen image <wallpaper> (writes all registered templates)
5. Maps primary color to nearest GNOME accent + Papirus folder color
6. Changes Papirus folder icon color via papirus-color (~0.3s, symlinks only, no cache rebuild)
7. Starts swww wallpaper transition (circle grow from cursor, 1.5s, 60fps)
8. Reloads swaync CSS (swaync-client --reload-css)
9. Starts color-fade kitty hyprland hyprpanel gtk3 nautilus spotify in background
10. CDP hot-reloads Notion (port 9223) if running
11. Restarts xdg-desktop-portal-gtk after 2s delay (GTK file chooser color pickup)

color-fade (interpolation engine)

A Python engine that drives all color targets through one synchronized animation loop.

• Duration: 0.4s default, ease-in-out cubic easing
• Global frame rate: 60fps base, per-target max_fps caps (30fps for heavier targets)

Targets

All targets share one frame loop and use the same easing curve so colors transition in lockstep.

Performance optimizations

• Pre-flattened RGB arrays: Old/new colors separated into parallel old_r[], old_g[], old_b[], new_r[], new_g[], new_b[] lists. Per-frame interpolation uses direct index access, no tuple allocation.
• Hex lookup table: _HEX = [f"{i:02x}" for i in range(256)] eliminates per-channel f-string formatting.
• Persistent socket connections: Kitty, hyprland, and spotify open connections once in *_init() and reuse across all frames. Eliminates connect/close overhead per frame.
• Hyprland batch IPC: Direct Unix socket with [[BATCH]] prefix instead of spawning hyprctl processes (was 120 process spawns/sec).
• CSS splice maps: GTK3/nautilus targets build byte-offset maps at init (_css_build_splice_map), then per-frame use string slicing instead of regex.
• HyprPanel CSS splice: Reads compiled CSS once at init, does string .replace() of old hex values with interpolated values per frame, writes to /tmp/hyprpanel/main.css, triggers reloadCss which reloads a persistent CssProvider (~17ms total vs 200ms for full applyTheme). Uses a bridge function to map theme keys to unique old hex values for CSS replacement.

HyprPanel target deep dive

The key insight: applyTheme triggers _compileSass() which runs the system sass compiler (200ms per call, far too slow for 30fps). The reloadCss command (added via JS patch) uses a persistent CssProvider that is created once and reloaded each frame via load_from_path(), avoiding both SCSS recompilation and CSS provider accumulation (17ms per frame including file write + socket round-trip).

Key mapping (bridge function): The old/new JSON files use theme keys (theme.bar.background) as keys and #hex as values. Since the old and new themes have entirely different hex values, you can't find "common" entries by hex. The hyprpanel_bridge function finds common theme keys between old and new, then re-keys both to unique old hex values (preserving original case for CSS string matching). This produces ~30 interpolation keys instead of 380+ theme keys, and the output {old_hex: interpolated_hex} can be used directly for CSS replacement.

Flow per frame:

1. Interpolate ~30 unique hex values using ease-in-out cubic easing
2. Read the CSS template (captured at init from /tmp/hyprpanel/main.css)
3. String-replace each old #hex with its interpolated #hex
4. Write the result back to /tmp/hyprpanel/main.css via low-level os.open/os.write
5. Send reloadCss to the Astal socket — reloads the persistent CssProvider in-place

After the fade completes, hyprpanel_finalize() sends applyTheme /tmp/hyprpanel-colors-new.json to sync config.json state with the final colors, then sends clearFadeCss to remove the persistent fade provider (so it doesn't override future theme updates).

If it breaks: The most likely failure is reloadCss not being recognized (HyprPanel update overwrites JS bundle). Restart with hyprpanel-launch to re-apply all patches including the reloadCss command injection. Check hyprpanel rc manually to verify.

hyprpanel-colors (color mapper)

Python script that:

1. Reads current /tmp/hyprpanel/variables.scss hex values → saves as /tmp/hyprpanel-colors-old.json
2. Runs matugen image <wallpaper> --dry-run --json hex to get new Material Design palette
3. Maps each Catppuccin default hex → catppuccin name → matugen variation token → new hex
4. Writes /tmp/hyprpanel-colors-new.json

Both JSON files use {theme_key: "#hex"} format. color-fade finds common theme keys, then uses hyprpanel_bridge to re-key to unique old hex values for CSS replacement.

Nautilus live-reload extension

A Nautilus extension at ~/.local/share/nautilus-python/extensions/matugen-css-reload.py handles two things:

1. CSS live-reload (color fade)

• Registers a Gtk.CssProvider at priority 10000 (overrides libadwaita defaults)
• Polls ~/.config/gtk-4.0/gtk.css mtime every 100ms via GLib.timeout_add
• When mtime changes, reloads the CSS via _provider.load_from_path()
• color-fade's nautilus target writes interpolated CSS to that path every frame

GFileMonitor was tried but events don't reliably dispatch inside nautilus-python. Mtime polling at 100ms is reliable and low overhead.

2. Papirus folder icon refresh

• Polls /tmp/papirus-icons-changed mtime every 100ms
• When the signal file is touched (by theme-switch after papirus-color runs), cycles Gtk.Settings gtk-icon-theme-name from "Papirus-Dark" → "hicolor" → "Papirus-Dark"
• Both property changes happen synchronously in one callback, so no frame renders the intermediate "hicolor" state (no flash)
• This triggers Nautilus's internal notify::gtk-icon-theme-name handler which invalidates icon caches and re-renders folder icons

Papirus folder icon colors

papirus-color at ~/.local/bin/papirus-color is a fast replacement for papirus-folders that only changes symlinks (0.3s) without rebuilding icon caches (3s). The stock papirus-folders rebuilds caches for all 3 Papirus variants via gtk-update-icon-cache, which is unnecessary since the Nautilus extension forces icon refresh via GtkSettings toggle.

• Sudoers NOPASSWD entry at /etc/sudoers.d/papirus-color for sudo /home/archie/.local/bin/papirus-color
• Called with full path in theme-switch: sudo /home/archie/.local/bin/papirus-color <color>
• After symlinks change, theme-switch touches /tmp/papirus-icons-changed to signal the Nautilus extension

Matugen Integration

Registered templates (in ~/.config/matugen/config.toml)

Cache vs live paths: Templates that feed into color-fade targets write to cache paths. The color-fade engine reads new colors from cache, interpolates to the live path each frame, then *_finalize() copies the final cache file to the live path. This prevents matugen from writing final colors to the live path before the fade starts.

matugen-colors.scss

Generated to ~/.config/hyprpanel/matugen-colors.scss on every theme switch. Contains Material Design 3 color variables ($matugen-primary, $matugen-surface-container, etc.). Never edit this file directly — it is overwritten by matugen. Edit the template at ~/.config/matugen/templates/hyprpanel-colors instead.

Key File Paths

IPC sockets used by color-fade