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.

3 files changed, 318 insertions, 0 deletions

diff --git a/docs/design/2026-07-02-desktop-settings-panel-spec.org b/docs/design/2026-07-02-desktop-settings-panel-spec.org
new file mode 100644
index 0000000..8becf71
--- /dev/null
+++ b/docs/design/2026-07-02-desktop-settings-panel-spec.org
@@ -0,0 +1,128 @@
+#+TITLE: Desktop-Settings Dropdown Panel
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-07-02
+#+TODO: TODO | DONE
+#+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED
+
+* DRAFT Status
+:PROPERTIES:
+:ID:       fb7eec22-a214-4568-82c4-903612f4832f
+:END:
+- [2026-07-02 Thu] DRAFT — initial spec from the todo.org task "Desktop-settings
+  dropdown panel" (2026-06-24 review), updated for the Blueprint/GTK4 pipeline
+  the net panel stood up 2026-07-01.
+
+* Metadata
+
+| Field  | Value                                        |
+|--------+----------------------------------------------|
+| Status | draft                                        |
+|--------+----------------------------------------------|
+| Owner  | Craig Jennings                               |
+|--------+----------------------------------------------|
+| Repo   | dotfiles                                     |
+|--------+----------------------------------------------|
+| Kin    | net panel (architecture donor), theme studio |
+|--------+----------------------------------------------|
+
+* Problem
+
+Desktop toggles are scattered: dim, caffeine/idle, touchpad/mouse, airplane
+mode each own a bar module and a keybind; brightness and keyboard-backlight
+have keybinds but no visible control or level readout. The bar is running out
+of glanceable width (hence the collapse arrows), and sliders can't live in
+waybar at all. One settings dropdown — a gear glyph opening a small panel —
+gathers them.
+
+* Goals
+
+1. One panel with every desktop toggle + slider: auto-dim, idle/caffeine,
+   touchpad, mouse, airplane (laptop-only), screen brightness, keyboard
+   backlight.
+2. Conditional rows appear only when the hardware/context applies (mouse
+   present, trackpad present, battery present) — reuse the detection the
+   airplane/touchpad indicators already do.
+3. Every control reflects live state and verifies its action took (the net
+   panel's verify-everything contract).
+4. Bar stays the quick layer: which standalone indicators survive is a
+   decision below.
+
+* Design sketch
+
+** Architecture — clone the net panel's proven stack
+
+- GTK4 + gtk4-layer-shell, Blueprint .blp sources compiled to committed .ui
+  (=make ui=; dev-only build dependency, fresh clones run without the
+  compiler).
+- Humble-object split: a GTK-free PanelModel presenter (unit-tested to 100%
+  like the net PanelModel) + thin composite-widget pages. Backing actions in
+  a GTK-free settings.py that shells out to brightnessctl / hyprctl / the
+  existing toggle scripts, TDD'd with fake binaries like every dotfiles
+  suite.
+- One gated AT-SPI smoke (the run-panel-smoke.sh pattern), no bespoke
+  headless widget suite.
+- Dupre WIP palette CSS, shared with the net panel — factor the palette
+  block into a common css asset both panels load rather than duplicating
+  (feeds the theme-studio task later).
+
+** Controls and their backings
+
+| Control            | Backing                                      |
+|--------------------+----------------------------------------------|
+| Auto-dim toggle    | hyprctl decoration:dim_inactive (dim-toggle) |
+|--------------------+----------------------------------------------|
+| Idle / caffeine    | hypridle start/stop (caffeine-toggle)        |
+|--------------------+----------------------------------------------|
+| Touchpad toggle    | toggle-touchpad + touchpad-state file        |
+|--------------------+----------------------------------------------|
+| Mouse toggle       | same mechanism, mouse-state file             |
+|--------------------+----------------------------------------------|
+| Airplane mode      | airplane-mode script (laptop-only row)       |
+|--------------------+----------------------------------------------|
+| Screen brightness  | brightnessctl (backlight class), slider + %  |
+|--------------------+----------------------------------------------|
+| Keyboard backlight | brightnessctl (kbd_backlight class), slider  |
+|--------------------+----------------------------------------------|
+
+Slider changes apply live (throttled) and read back the actual level after
+apply — verify-everything. Toggles re-read their source of truth after
+firing, same as the bar indicators do, and the bar modules get their refresh
+signals so both surfaces agree.
+
+** Open/close behavior
+
+Gear glyph module on the bar right cluster; click toggles the panel
+(layer-shell anchored under the bar, right-aligned). Focus-out auto-hide +
+Close button, matching the net panel. Keybind decision below.
+
+* Decisions (Craig)
+
+** TODO Which standalone bar indicators collapse into the panel?
+Options per module (dim, touchpad, caffeine): keep on bar + mirrored in
+panel; or panel-only (frees bar width). Recommendation: keep touchpad and
+caffeine visible on the bar (state you glance at), move dim into the panel
+(you set it rarely), keep airplane where it is.
+
+** TODO Keybind for the panel?
+Super+Shift+G (gear) is free. Or no keybind — mouse-only surface.
+
+** TODO Where does the code live?
+Recommendation: dotfiles =settings/= sibling to =net/= (same src-layout,
+tests in tests/settings/), sharing the palette css. In-tree pocketbook-style
+was the old note; the net panel is the better donor now.
+
+** TODO Slider granularity and floor
+brightnessctl exposes 0-100%; a 5% floor stops "screen went black in a dark
+room" lockouts. Confirm the floor (or allow 0 with a long-press escape
+hatch).
+
+* Implementation phases
+
+1. settings.py backings (brightness get/set, kbd backlight, toggle
+   state readers) — pure engine, TDD with fake brightnessctl/hyprctl.
+2. PanelModel presenter (rows, conditional visibility, verify-after-apply
+   semantics) — unit-tested, no GTK.
+3. Blueprint UI + gear bar module + open/close wiring; palette css factored
+   to a shared asset; AT-SPI smoke.
+4. Bar-module consolidation per the decision above (drop/keep indicators,
+   refresh-signal wiring, keybind).
diff --git a/docs/design/2026-07-02-net-panel-other-interfaces-spec.org b/docs/design/2026-07-02-net-panel-other-interfaces-spec.org
new file mode 100644
index 0000000..ee01c02
--- /dev/null
+++ b/docs/design/2026-07-02-net-panel-other-interfaces-spec.org
@@ -0,0 +1,137 @@
+#+TITLE: Net Panel — Tailscale, VPN, and WireGuard Interfaces
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-07-02
+#+TODO: TODO | DONE
+#+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED
+
+* DRAFT Status
+:PROPERTIES:
+:ID:       79a1075a-4b56-4f25-a861-b69f120a636a
+:END:
+- [2026-07-02 Thu] DRAFT — initial spec from the roam capture "other network
+  interfaces (tailscale, VPNs, wireguard)" filed in todo.org 2026-07-02.
+
+* Metadata
+
+| Field  | Value                                             |
+|--------+---------------------------------------------------|
+| Status | draft                                             |
+|--------+---------------------------------------------------|
+| Owner  | Craig Jennings                                    |
+|--------+---------------------------------------------------|
+| Repo   | dotfiles (net module); archsetup (packages)       |
+|--------+---------------------------------------------------|
+| Parent | Waybar network module spec (2026-06-29), V2 panel |
+|--------+---------------------------------------------------|
+
+* Problem
+
+The net panel's Connections tab shows what NetworkManager knows: WiFi networks
+and wired links. The machines also run overlay and tunnel interfaces the panel
+is blind to:
+
+- Tailscale (tailscaled, both daily drivers; the tailnet is how the machines
+  reach each other; not an NM device)
+- WireGuard configs (assets/wireguard-config/ carries Proton VPN configs;
+  importable as NM connections of type wireguard or run via wg-quick)
+- Commercial VPN clients (Proton VPN GTK app is installed on velox; owns its
+  own tunnel device)
+
+When one of these is up it changes routing, DNS, and reachability — exactly
+the things the Diagnostics tab reasons about — yet the panel neither shows nor
+controls them, and the doctor can misattribute a VPN-caused failure to the
+underlying link.
+
+* Goals
+
+1. Visibility: the Connections tab shows overlay/tunnel interfaces with live
+   state (up/down, address, and for tailscale the tailnet peers summary).
+2. Control: bring each up or down from the panel row, same interaction shape
+   as Join/Disconnect on WiFi rows (no terminals — V2 contract).
+3. Diagnostics awareness: diagnose/doctor know when a tunnel owns the default
+   route or DNS, name it in evidence rows, and stop misattributing its
+   failures to the physical link.
+
+Non-goals (this iteration): installing or configuring VPN providers, tailnet
+ACL management, exit-node selection UI (a "use exit node" affordance can ride
+a later pass), kill-switch management (tracked separately in the spec's
+failure catalog).
+
+* Design sketch
+
+** Data sources — one probe per backend, engine-side
+
+New GTK-free module net/src/net/overlays.py with one probe per backend,
+each returning the same small dict shape ({kind, name, state, addr, detail,
+can_toggle}):
+
+- tailscale: =tailscale status --json= (rich: self, peers, exit node, health
+  messages). Daemon down → state "stopped". Binary absent → backend absent.
+- wireguard-nm: =nmcli -t connection show= filtered to type wireguard —
+  up/down via the existing nmcli wrapper (activate/deactivate connection).
+- wg-quick configs outside NM (files in /etc/wireguard) — read-only listing
+  at most; toggling them requires root and wg-quick; probably defer.
+- proton-gtk: detect its tunnel device (proton0 / ipv6leakintf) when up;
+  control stays with the Proton app (can_toggle false, detail points at the
+  app) unless Craig prefers driving it via its CLI.
+
+** Panel
+
+A fourth Connections group "Tunnels" (after Saved / Available now / Wired)
+using the existing group-header + row machinery. Row: glyph per kind, name,
+state caption; primary action Up/Down where can_toggle, else Open app.
+Tailscale row detail (subtitle or tooltip): tailnet name, peer count online,
+exit node if any.
+
+** Privileged path
+
+- tailscale up/down: needs root or operator — =tailscale set --operator= at
+  install time (archsetup) makes the user an operator, so no sudo needed at
+  runtime. Fallback: the V2 net-priv helper gains tailscale-up/down verbs.
+- NM wireguard connections: no privilege needed (NM polkit default for the
+  active user).
+
+** Diagnostics awareness
+
+- diag gains an "overlay owns default route/DNS" detection step: when the
+  default route or resolv.conf points at a tunnel interface, evidence names
+  it ("default route via tailscale0") and failure classification runs the
+  physical-link checks against the underlying device instead.
+- doctor: a tunnel-caused egress failure (VPN up but its endpoint dead)
+  classifies fixable with next_action "bring the tunnel down / reconnect",
+  not a WiFi reset.
+
+** Bar indicator
+
+Unchanged by default. Optional later: a small overlay badge on the net glyph
+when a tunnel owns the default route.
+
+* Decisions (Craig)
+
+** TODO Which backends ship in the first pass?
+Recommendation: tailscale + NM-managed wireguard. Proton app detection-only.
+wg-quick configs deferred.
+
+** TODO Tailscale control path: operator flag at install vs net-priv verbs?
+Recommendation: =tailscale set --operator=$USER= in archsetup's tailscale
+step (declarative, no sudo at runtime); net-priv verbs only if operator mode
+proves insufficient (e.g. up with flags).
+
+** TODO Does "Tunnels" belong in Connections or its own tab?
+Recommendation: a Connections group. A fourth top tab dilutes the V2 nav for
+three rows.
+
+** TODO Proton VPN: detect-only or drive its CLI?
+Recommendation: detect-only first; the app owns reconnect/kill-switch logic.
+
+* Implementation phases
+
+1. overlays.py probes (tailscale JSON, nmcli wireguard filter, proton device
+   detection) — pure engine, TDD with fake binaries; =net status= grows an
+   overlays section.
+2. Panel Tunnels group + Up/Down wiring through the worker thread; AT-SPI
+   smoke extension.
+3. Diagnose/doctor overlay awareness (route/DNS ownership step, classifier
+   rows, evidence text) — TDD against the diag harness.
+4. archsetup: tailscale operator flag in the tailscale install step; VM test
+   assertion.
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.