docs(design): specs for net-panel tunnels and settings panel; animation feasibility

Two DRAFT specs — tailscale/VPN/wireguard surfaces in the net panel, and the desktop-settings dropdown panel on the net panel's Blueprint/GTK4 stack — each with open decisions marked for review. The expansion-animation note concludes the collapse-by-reload mechanism can't animate (no widget survives the SIGUSR2 rebuild) and recommends closing that task.

1 files changed, 53 insertions, 0 deletions

diff --git a/docs/design/2026-07-02-waybar-expansion-animation-feasibility.org b/docs/design/2026-07-02-waybar-expansion-animation-feasibility.org
new file mode 100644
index 0000000..cb195c6
--- /dev/null
+++ b/docs/design/2026-07-02-waybar-expansion-animation-feasibility.org
@@ -0,0 +1,53 @@
+#+TITLE: Waybar Expansion Animation — Feasibility Assessment
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-07-02
+
+* Question
+
+The todo.org task "Smooth waybar expansion animation" [#C]: the collapse/expand
+jump is abrupt, and a few systray icons pop in one-by-one afterward. Can the
+expansion animate smoothly?
+
+* How the collapse actually works
+
+=waybar-collapse= rewrites the module arrays in a runtime copy of the config
+(=$XDG_RUNTIME_DIR/waybar/config=) and sends waybar SIGUSR2. Waybar reloads:
+it tears down every module widget and rebuilds the bar from the new config.
+
+* Findings
+
+1. *No widget survives the reload, so nothing can transition.* GTK3 CSS
+   transitions animate property changes on live widgets. The collapse
+   mechanism replaces the whole widget tree; there is no widget on both sides
+   of the change to interpolate. The jump is structural, not stylistic.
+2. *GTK3 doesn't animate widget add/remove anyway.* Smooth insert/remove needs
+   =GtkRevealer= wrapping, which waybar does not use for modules. Making it do
+   so is an upstream waybar patch, not a config or CSS matter.
+3. *The layer surface resize isn't animatable either.* Hyprland layerrules can
+   animate map/unmap (slide/fade), but the bar stays mapped through a collapse
+   — the same surface changes width. No compositor-side hook exists for that.
+4. *A CSS-only fake covers custom modules at best.* Custom modules could emit
+   a "collapsed" class and transition font-size/padding toward zero (GTK3 CSS
+   can animate those). But the collapsed set includes built-ins — tray,
+   pulseaudio, workspaces — which take no script-driven classes. The result
+   would be half the modules gliding and half popping: worse than the clean
+   jump.
+5. *Tray icons popping in one-by-one is separate and unfixable here.* That's
+   asynchronous StatusNotifier re-registration after the reload; each app
+   answers on its own schedule. Only keeping the tray alive across the change
+   (i.e. not reloading) avoids it.
+
+* Conclusion
+
+Not feasible with the current collapse mechanism, and no acceptable partial
+measure exists. A real animation requires waybar itself to support dynamic
+module sets with Revealer-style transitions (an upstream feature), or
+replacing the collapse-by-reload design entirely.
+
+* Recommendation
+
+Close the task as infeasible-for-now (or park at [#D] with a pointer here).
+Revisit only if waybar upstream gains dynamic module visibility (worth a
+check at major waybar releases) or if the bar ever migrates to a custom
+GTK4 shell — the Blueprint pipeline from the net panel would make Revealer
+transitions natural there.