path: root/docs/specs/2026-07-02-desktop-settings-panel-spec.org

#+TITLE: Desktop-Settings Dropdown Panel
#+AUTHOR: Craig Jennings
#+DATE: 2026-07-02
#+TODO: TODO | DONE
#+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED

* IMPLEMENTED Desktop-Settings Dropdown Panel
:PROPERTIES:
:ID:       d6bb1e73-ec90-4327-85ee-bfa762da5bce
:END:
- 2026-07-04 Sat @ 12:36:56 -0500 — retrofitted by spec-sort; status set to DRAFT (evidence-based, human-confirmed)

* IMPLEMENTED Status
:PROPERTIES:
:ID:       fb7eec22-a214-4568-82c4-903612f4832f
:END:
- [2026-07-22 Wed] IMPLEMENTED — all four phases shipped in dotfiles: 7a15237 (phase 1, backings engine), 74f723e (bar slice, landed early), 5172289 (phase 2, presenters), 33d82eb (phase 3, GTK port of prototype 37), 680b50d (phase 4, projected faces / night watch / location / tick), 9038eee (the 17-point end-to-end pass re-derived from prototype 37's suite). Full dotfiles suite green (85 suites), AT-SPI smoke 13/13, e2e 17/17 on the live compositor. The Cairo drag gestures and the locked-path night-watch swap are on todo.org's "Manual testing and validation" checklist — human-eye checks, not blockers. Build adaptations from the phase logs: five-stage idle dial (WATCH ran as its own stage), held-to-unpause DND, no-backlight drums dim out, kiosk profile wiped per start, reveal gating pid-matched.
- [2026-07-22 Wed] DOING — spec-response: the four rewritten implementation phases decomposed into build tasks in todo.org under a :SPEC_ID:-stamped parent, with the test surface and the final flip-to-IMPLEMENTED task emitted. The build proceeds in dotfiles settings/ per the location decision; archsetup drives.
- [2026-07-22 Wed] READY — spec-review passed (rubric: Ready with caveats; see Review findings — two findings fixed in-run, two non-blocking build-time picks recorded). The prototyping gate closed at prototype 37, sealed by Craig's "Build it. Anything more would be bit fiddling." The FOCUS headphones glyph stands confirmed by the same words. Normative reference: prototype 37.
- [2026-07-22 Wed] DRAFT — UI PROTOTYPING COMPLETE. Thirty-five prototypes ended at [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-35.html][Prototype 35, the final candidate]] (linked as the normative reference under Design sketch), sealed by Craig's "I think that's it" after his annotation batch applied clean. The design evolved far past the original controls table — programmable-presets matrix, instrument bench, wallpaper channels — with every turn recorded under Prototype iterations. The gate before READY is satisfied: research cited, ~5 directions grew to 35 with the winner iterated to final, every UI decision made against working prototypes. Next: spec-review (reconcile the Design sketch's aging architecture prose against what the prototypes actually settled), then spec-response into build phases.
- [2026-07-21 Tue] DRAFT — casting sitting complete: Craig cast every control role live against working candidates (see "Casting" under Prototype iterations). Scenes = tuner dial + presets; brightness = new detent fader with speedbump physics; keyboard = single-drum roller; power = chicken-head; toggles = rocker bank; airplane = guarded lever (throw fixed); caffeine = wind-up timer dial; chrome = warm-gold receiver plate. Three kit-candidate components accrued in dupre-kit-additions.js with a merge task filed. Next: compose prototype 12 and iterate to final.
- [2026-07-21 Tue] DRAFT — scope change (Craig): lock/suspend withdrawn from the panel (they live on the wlogout screen, Super+Shift+Q); a new open decision "Idle pipeline" proposes staged idle timeouts (dim/lock/screen-off/power action) and caffeine as a timed inhibit, replacing the bare on/off. DND semantics finding recorded in the controls table (pause dams and floods; dead-drop needs an explicit queue clear).
- [2026-07-21 Tue] DRAFT — three Dupre Kit directions (9 engine room, 10 spacecraft DSKY, 11 mixing desk) composed from the real widgets.js builders after Craig pointed the phase at the panel-widget-gallery catalogue; his two favorite level controls (drum roller, thumb-slide attenuator) each carry the levels in one direction for a working comparison. Eleven directions total; pick still pending.
- [2026-07-21 Tue] DRAFT — three more direction prototypes (6 hi-fi receiver, 7 chronograph, 8 gauge cluster) built to Craig's aesthetic brief: retro hi-fi stereo / chronograph / automobile dashboard. Craig loved the scenes-as-station-presets idea, so the tuner dial is direction 6's hero. Also retired the status lamps across all directions (the glowing dot pulled the eye) and fixed a slider-fill CSS hack that bled a huge gold disc over directions 1/2/3/5. Direction pick still pending.
- [2026-07-21 Tue] DRAFT — UI-prototyping phase: recorded the quick-settings prior-art survey (see Prior art under Design sketch) and brought the five 2026-07-19 direction prototypes up to the current controls table (weather-geo toggle added to the shared engine and every direction; caffeine restored to directions 2 and 5, which had dropped it). All five verified rendering error-free headless. Awaiting Craig's direction pick before the iterate-to-final pass.
- [2026-07-21 Tue] DRAFT — added a weather-geolocation toggle to the controls table (use_geo in the weather config: whereami WiFi fix vs pinned home coords). Both machines run use_geo=true for testing as of today; ratio may flip back by hand until the panel ships the switch.
- [2026-07-19 Sun] DRAFT — folded Craig's control-set decisions (home->archsetup handoff): added night-light, DND, lock/suspend, power profile, and scenes to the controls table; recorded volume and theme as out-of-scope with reasons; pulled the format pickers into a separate display-format sibling spec (stub filed). The "few other things" scoping decision and the scenes decision are now closed. The wallpaper-shape decision closed the same day (row-that-opens-a-sub-view — see Decisions), leaving no open decisions. UI prototyping (ui-prototyping rule: research -> 5 directions -> iterate) is not done yet and is the gate before READY.
- [2026-07-04 Sat] DRAFT — all four decisions resolved by Craig (dim + airplane collapse into the panel, touchpad + caffeine stay on the bar; Super+Shift+G keybind; code in dotfiles settings/ beside net/; 5% brightness floor). The four collapse/keybind/location/floor decisions are closed; one open scoping question remains ("few other things" — see Decisions) before a spec-review can flip it READY.
- [2026-07-03 Fri] DRAFT update — from the waybar/panel-family design
  discussion: adopt the instrument-console faceplate aesthetic net + bt
  shipped (lamps, engraved sections, console keys, machined plate), not just
  the raw palette; add the audio panel as a sibling in the panel family;
  cross-reference the shared faceplate CSS. Toggle-consolidation scope (the
  "few other things") still open — see the Decisions section.
- [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.

** Prototype iterations

Five direction prototypes (2026-07-19), all full working layouts over one
shared mock engine ([[file:../prototypes/desktop-settings-shared.js][desktop-settings-shared.js]] +
[[file:../prototypes/desktop-settings-shared.css][desktop-settings-shared.css]]) so the directions are genuinely comparable:
same state model, same verify-everything simulation (apply, mock readback,
green verify flash + toast), same wallpaper sub-view.

- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-1.html][Direction 1 — tile grid]]: the Android/GNOME quick-settings idiom; scenes
  strip, 2-column toggle tiles, sliders and power below.
- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-2.html][Direction 2 — sectioned rack]]: full-width console keys under engraved
  section labels; closest to the net/bt panel idiom.
- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-3.html][Direction 3 — scenes-first]]: scenes as the hero controls, everything else
  beneath.
- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-4.html][Direction 4 — instrument cluster]]: ring gauges for the levels, a rotary
  power-profile selector, lamp rows; leans hardest into the faceplate
  aesthetic.
- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-5.html][Direction 5 — compact expandable rows]]: one slim row per control,
  progressive disclosure for power/scenes/wallpaper.

2026-07-21: all five updated to the current controls table (weather-geo
added; caffeine restored to directions 2 and 5) and verified rendering
error-free.

Three more directions added 2026-07-21 to Craig's aesthetic brief — retro
hi-fi stereo, chronograph, automobile dashboard — treating the panel as a
physical object rather than a software surface. Same shared engine, same
control roster:

- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-6.html][Direction 6 — hi-fi receiver]]: scenes as station presets on a backlit
  tuner dial (sliding needle) + preset keys; rotary knobs with VU meters
  for the levels; a backlit switch bank; an input-selector knob for power.
- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-7.html][Direction 7 — chronograph]]: the panel is a watch. Brightness is the main
  dial (drag the bezel; gold hand + digital window), chrono subdials carry
  keyboard/power/scene, crowns are the momentary actions, bracelet links
  are the toggles.
- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-8.html][Direction 8 — gauge cluster]]: a dashboard binnacle with twin needle
  gauges (drag to set), a rocker-switch bank with backlit legends,
  push-button drive modes for scenes, an ignition rotary for power, dash
  pull-knobs for actions.

Three further directions added 2026-07-21, composed from the real Dupre Kit
builders (widgets.js) rather than hand-rolled lookalikes — so each doubles
as a component-selection exercise for the eventual GTK port. Craig's two
favorite level controls get the same job in two different directions so
they can be compared in working form: the drum roller in direction 9, the
thumb-slide attenuator in direction 10.

- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-9.html][Direction 9 — engine room]]: drum-roller levels, split-flap scene board
  read from a rotary selector, breaker-panel toggles, guarded airplane
  lever, engine-order telegraph for power, arm-to-fire actions.
- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-10.html][Direction 10 — spacecraft DSKY]]: thumb-slide levels, slide-switch bank
  under a live caution board, scenes commanded by DSKY verb entry
  (V01-V04, V00 off), keyed mode switch for power.
- [[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-11.html][Direction 11 — mixing desk]]: slot faders in dB with a VU bridge,
  radio-preset scene bank, chip toggles with DND on a stomp pedal, rotary
  power selector.

Kit-integration notes for the port, learned building these: the kit's
CSS-built selector spans (.dupre-rotsel, .dupre-keylock) size themselves
with width/height on inline display, so consumers outside the gallery need
display:inline-block on them; breakerPanel has no set() and hardcodes its
initial states, so reflecting external state means synthesizing clicks on
its hit rects (a set() upstream would fix it); and the shared mock engine
now carries weathergeo in its state object (it was metadata-only, and
kit toggles default-on when opts.on is undefined).

*** Casting (2026-07-21) — instrument per role, picked live

Rather than one direction wholesale, Craig cast each control role from the
bench in a live sitting (candidates driven in working form; the scenes and
levels casting pages below were built for the head-to-heads):

- Scenes (panel hero, top): kit slideRule tuner dial — stops
  OFF/FOCUS/PRES/BATT/NIGHT, lit stop label, sliding needle — over
  PRESET 1-4 keys. Beat rotary + split-flap head-to-head
  ([[file:../prototypes/2026-07-02-desktop-settings-panel-scenes-compare.html][scenes casting page]]).
- Screen brightness: detentFader (NEW kit-candidate component) — full-width
  horizontal fader, detents at 25/50/75 with speedbump physics (magnet +
  escape hysteresis; the thumb parks until the pointer pushes through).
  Craig's revision of the plain faderH pick.
- Keyboard backlight: drumRoller, single drum 0-10 (kit builder generalized
  to 1..N channels + min/max — stock was hardcoded to two drums).
  ([[file:../prototypes/2026-07-02-desktop-settings-panel-levels-compare.html][levels casting page]] carries both level controls.)
- Power profile: chicken-head knob, three detents.
- Toggle bank: kit rocker bank — lit engraved legends carry state (no lamp
  dots; the status-lamp retirement holds).
- Airplane: guardedToggle, laptop-only, patched to a rotateX throw (the
  stock 180° planar spin swept the lever sideways mid-transition).
- Caffeine / idle inhibit: kit timerDial as a wind-up timed inhibit (real
  minutes at build; demo clock is min/sec).
- Chrome: direction 6's receiver faceplate in warm Dupre gold — family-kin
  with net/bt/audio. (Marantz-blue slideRule skin seen and passed on.)

The three kit-candidate components (detentFader NEW, drumRoller and
guardedToggle UPGRADEs) live in
[[file:../prototypes/dupre-kit-additions.js][dupre-kit-additions.js]] pending the
kit merge (tracked in todo.org).

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-12.html][Prototype 12 — the casting composite]] (2026-07-21, overnight on Craig's
go): every cast instrument composed on the warm-gold receiver chassis with
the current roster — tuner + presets, detent fader, single drum,
chicken-head, wind-up caffeine timer, rocker bank, guarded airplane,
wallpaper sub-view; lock/suspend absent per the wlogout amendment. All
interactions verified headless (scene tune + preset punch, fader detents,
drum drag, chicken step, timer wind → caffeine, rockers, lever, sub-view
round-trip). Composing it surfaced and fixed a latent shared-engine bug:
wallpaperSubview returned a div carrying the ds-subview class
(display:none outside .open), so the wallpaper sub-view had been opening
empty in every direction prototype. Iteration to final happens against
this file.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-13.html][Prototype 13 — P12 + Craig's first iteration]] (2026-07-22): presets moved
above the dial full-width (Preset 2 contains "Presentation" whole); screen
brightness RECAST from the detent fader to the drum — screen + keyboard now
run as the classic two-drum pair left of an enlarged caffeine timer, which
gains a HOLD/TIMED rocker so caffeine can be held always-on; compact
chicken-head in the upper-right quadrant; switch wall of six with the
guarded airplane lever in the mix; weather-geo DROPPED from the panel
entirely (controls-table row removed — the config stays hand-edited);
wallpaper row unchanged. The detentFader remains a kit-merge candidate on
its own merits. Verified: HOLD drives caffeine, drum drag drives
brightness, preset containment and tuner stop visibility checked
programmatically. Second pass same night: the drums grew to run flush with
the timer column (drum top level with the dial top, bottom with the HOLD
rocker — verified 0px deltas); drumRoller gained a height option for it (a
taller stage opens a longer paper window showing more of the scale), which
joins the kit-merge candidate's contract. Third pass: the caffeine timer
was unwindable live — crossing zero mid-drag toggled caffeine, the
re-render destroyed the dial under the pointer, and every rebuilt
timerDial leaked its countdown interval as a ghost writing stale minutes.
Fix: self-clocked instruments persist across re-renders (reparent, never
rebuild) and state sync is debounced past the drag. This is a
build-architecture rule for the GTK port too: instruments that own a
clock own their widget lifetime.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-14.html][Prototype 14 — timer refinements]] (2026-07-22): the HOLD/TIMED rocker is
replaced by a bat toggle seated at the timer's upper-right where the
winding-direction arrow was (arrow removed) — bat up TIMED, down HOLD
(always-on caffeine); the timer dial is vertically centered against the
drum column instead of top-flush. batToggle joins the kit-merge additions
with the same rotateX throw fix as guardedToggle (stock had the identical
180° planar spin). Verified: bat drives hold-caffeine both ways, center
delta 0, arrow absent.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-15.html][Prototype 15 — power slide]] (2026-07-22): the chicken-head is replaced by
a three-position slide switch under the tuner — a status lamp per
position, labeled PERFORMANCE / BALANCE / POWER SAVE, stretching to
exactly the tuner's length; the tuner itself is restored to full plate
width. Two more kit-candidates for it: slideSelector (NEW — stretchable
n-position slide with per-position lamps, pillSlide's full-size
descendant) and a slideRule width option (the printed scale spreads its
stops proportionally; custom widths take a wider edge margin so end-stop
labels stay inside). Verified: slide clicks and drags land positions and
drive the profile, exactly one lamp lit, scenes move the slide (Focus
sets BALANCE), tuner tunes at full width with end labels contained.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-16.html][Prototype 16 — rebalanced]] (2026-07-22): built from a design critique
Craig requested ("it still feels off") whose diagnosis was inverted
salience — the least-used control (the caffeine timer, largest object,
only big red) shouted loudest while the heroes (scenes, brightness)
whispered. Changes, same instruments throughout: three uniform plates on
one grid (Scenes·Power / Levels·Caffeine / Switches); the drum pair
replaced by the thumb-slide attenuator pair at Craig's call (the cream
paper drums were the panel's bright blob and out of family with the
slide/fader chrome); the timer de-throned — steel stop knob, amber
index/OFF, single engraving, bat docked on its stage; rockers carry their
function name on the lit half with a new `quiet` option killing the
warning-red off state (a fourth kit-candidate UPGRADE — red-off stays
stock default for switches where off is the notable state); the airplane
lever sits on the rocker baseline with trimmed AIR/SAFE labels. Red now
appears exactly twice, both semantically: the tuner needle (vintage
heritage) and the airplane danger disc. Salience rule recorded for the
GTK build: visual loudness follows frequency × importance — scenes and
brightness loudest, switches calm, caffeine polite.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-17.html][Prototype 17 — switches under their presets]] (2026-07-22): plate order
rearranged for causality — the presets program the switches, so the wall
now sits directly beneath the scenes plate ("strange to have the preset
buttons on top controlling switches on the bottom" — Craig), with the
power slide just under the wall in a shared Switches · Power plate;
Levels · Caffeine follows. The power slide's knob goes dark (a knob
option — chrome default / machined-dark — added to the slideSelector
kit candidate). Verified: plate order wall → slide → levels, dark knob
class active, and the adjacency in action — the Night preset lights the
rockers directly beneath it and slides power to POWER SAVE.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-18.html][Prototype 18 — the program chart]] (2026-07-22): Craig asked what analog
component the missing "one selector recalls a configuration" pattern maps
to. Answer: two — the behavioral half is the organ combination action /
flying-fader scene recall (controls physically move on recall, which the
panel already does), and the legible half is the washing-machine faceplate
program chart, which was the missing piece. New kit-candidate
DUPRE.programChart: one row per program, one column per contact — filled
dot closes it, ring opens it, dash leaves it alone, letters carry enums —
active row lit, display-only, derived straight from the scene definitions
(which makes visible that scenes never touch TPAD/MOUSE). Also this pass:
airplane removed from the panel (network panel owns it — table row and
wall slot dropped); the dial's OFF stop relabeled CUSTOM (no scene = a
hand-set configuration, not "off"); a real-proportion pass — thumb slides
up toward hand size, timer down toward kitchen-timer size. Verified:
chart rows follow scene changes, CUSTOM releases the scene while the
switches hold state, airplane absent.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-19.html][Prototype 19 — the chart becomes a punch card]] (2026-07-22): the program
chart turns editable and white — its lights indicate FUTURE state (what
the preset will set on recall), so they sit deliberately outside the
amber live family; clicking a cell reprograms the preset (dots cycle
closes → opens → untouched, the power letter cycles P/B/S/–), with edits
written back to the scene definitions and honored on the next recall
(verified: adding DND to Battery's program, then recalling Battery,
engaged DND for real). Switches engage GREEN (a rocker accent option —
run/engaged semantics) and shrink to true rocker size; slides grow.
Three-register color semantics recorded for the build: amber = scene
family and live selection, green = engaged switches, white = programmed
future state. Craig's observation logged with it: the panel is converging
on a master-preset architecture — the presets program everything below
except the wound timer minutes; the chart is that programming surface.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-20.html][Prototype 20 — the switch matrix]] (2026-07-22): the master-preset
architecture made literal. The panel's axis IS the switches: preset row,
punch chart, and switch wall fuse into one matrix — each row a live
switch (rocker / caffeine lamp / a mini three-detent power slide), the
four preset buttons running across the top as column heads (names only,
no PRESET N), white punch lights under each program column, every cell
editable. The slide-rule tuner is retired (preset buttons + CUSTOM-by-
touching carry scene selection); TPAD and MOUSE — which no scene touches
— drop to their own Pointing strip; SCREEN, KBD, and power go horizontal
via a new kit-candidate, thumbSlideH (the thumb slide turned on its side:
continuous 0-100 or detented positions, stretchable). Build note: the
matrix itself is page-level composition for now — if it survives
iteration it should become a kit switchMatrix component; and component-
scoped CSS bit again (the chart's dot classes are scoped to .dupre-pchart,
so the matrix carries its own copy). Verified: preset buttons recall and
light the rockers, punch edits write back and hold, horizontal slides
drive both levels, the matrix power slide sets the profile, tuner absent.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-21.html][Prototype 21 — the pin routing matrix]] (2026-07-22): P20's accidental
switch-relocation told Craig what the interface actually is — a pin
routing matrix (EMS-Synthi patch idiom, already in the kit). The kit
pinMatrix got the upgrade treatment (kit-candidate #9: configurable
geometry, per-column pin colors, clickable button column-heads with an
active state, row-group dividers, set(); stock 5×6 defaults preserved)
and became the whole interface: switch names label the rows (the physical
rockers are gone — "remove all the switches, which now become labels"),
program buttons head the columns, a green live NOW column carries current
state (click to toggle; the live power pin can't be pulled, only moved),
white pins program the four scene columns, and the power rows are a radio
group per column. Program semantics simplified to complete definitions:
recall makes the column's pin pattern the truth (pin on, absent off).
CAFF is an ordinary switch row; the caffeine timer job is retired and the
dial is repurposed as a SLEEP TIMER (wind minutes until suspend — the
receiver classic; pairs with CAFF as the two directions of the idle
fight), bat toggle retired with it. The drums return for SCREEN/KBD at
Craig's call ("I love the drum"). Verified end to end: NOW pins toggle
live state, program pins write back, power radio enforces one pin per
column, column-head recall applies the full pattern (including a
just-seated CAFF pin), sleep timer winds/runs down/fires the mock
suspend, button heads contained after a geometry margin fix.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-22.html][Prototype 22 — the programmable matrix]] (2026-07-22): Craig named the
component the design was building toward, and it exists now —
DUPRE.programMatrix (kit-candidate #10): programs as caps column-head key
plates (FOCUS · PRESENT · BATTERY · NIGHT — "Presentation" shortened),
settings as spelled-out engraved rows (AUTO-DIM, NIGHT LIGHT, DO NOT
DISTURB, CAFFEINE; engraved-and-infilled relief after the pure kit
engrave idiom proved illegible at 6px), radio row groups, and the core
semantic: NO live column — pressing a head activates the program and its
column's pins turn white → green, because active-is-live: the recalled
pattern IS the machine's state. Editing the green column edits the
present (live state and stored program move together, and the column
STAYS active); editing a white column edits a future. Build finding for
the GTK port: the mock engine cleared the active scene on any member
write, which silently dropped active-is-live — the real PanelModel must
let program-membership writes survive without deactivating the program.
Verified: activation floods the column green and applies the pattern,
active-column DND pull changed live + program while staying in NIGHT,
radio PERF move followed suit, inactive-column CAFFEINE seat edited the
program without touching live state.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-23.html][Prototype 23 — the pushwheel CPU row]] (2026-07-22): CPU power collapses
from three radio rows to ONE letter row. Craig asked for the analog
referent — triangle up/down steppers beside a lettered tape-counter
window — which is the industrial push-button thumbwheel (BCD pushwheel)
switch; no kit component existed (chromeMinMax checked: it's a dome
gauge), so programMatrix grew letter rows: program cells carry one of
the row's values (P/B/S here, click cycles; ↑/~/↓ noted as an alternate
glyph set), and stepper: true appends the pushwheel at the row's right —
window showing the LIVE letter, triangles stepping it (up toward P,
clamped). Active-is-live holds: stepping while a program is active
writes the program's letter too and stays active. Row labels now
right-align to the column buttons' left edge (Craig). Verified: stepper
walks B→S and back up to P, inactive letter cycles edit programs only,
NIGHT activation floods letters green, active stepping moves live +
program together; a margin fix cleared the fourth column's letter from
the pushwheel window.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-24.html][Prototype 24 — tape wheel + jewel verdicts]] (2026-07-22): the triangle
steppers retire after one prototype — the tape-counter wheel IS the
button now (click cycles the live CPU letter, wrapping), rendered as a
proper wheel cell: cream paper, cylinder shading, 13px printed letter,
after the kit tapeCounter's look. And the active column gains verdict
lamps per Craig's read that they're jewel pilot lamps "just not so large
and flashy": every switch row in the live column shows a definite state —
a domed green jewel for seated, a smaller red jewel for a socket the
program holds off; inactive seated pins wear a frost-white jewel dome.
Verified: wheel cycles B→S→P→B, NIGHT activation shows three green
verdicts + one red (CAFFEINE held off) + the green S letter, program
edits and active-is-live unchanged.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-25.html][Prototype 25 — wheels in every column]] (2026-07-22): Craig caught the
side wheel as another NOW-column vestige — under active-is-live the
active column's value IS the live value, so the tape wheel belongs in
every program column, not off to the side. Each CPU POWER cell is now
its own bezeled tape wheel (click cycles that program's letter); the
active column's wheel wears a green bezel and is the machine's live CPU
state. Jewel pilot lamps sized up (5.6 / 4.8) with taller rows (dy 21)
to match. Verified: inactive wheels edit programs only, the active wheel
cycles live + program together and stays active, activation applies the
program's letter.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-26.html][Prototype 26 — physical keys, arrow wheels]] (2026-07-22): the program
heads become real keys — raised bevel over a static shadow at rest,
visibly DEPRESSED onto it when active, with green lighting only the
engraved legend (a backlit key, not a bordered chip); the active wheel's
green bezel is dropped (paper doesn't glow — the depressed key and the
jewel verdicts carry live indication); row labels engraved larger and
brighter-infilled for faceplate presence; the CPU wheels print ↑ – ↓
(performance / balanced / saver) instead of letters; and the whole panel
widens to 434px (matrix 382) to give it all room. Verified: NIGHT's key
depresses with a green legend while the others sit proud, wheels carry
the arrow glyphs, the active wheel still cycles live + program together
without dropping the program.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-27.html][Prototype 27 — console keys, six slots, one bench]] (2026-07-22): the
head keys become the kit's own console-key primitive (.dupre-key,
lighting full green when active — the component now composes DOM keys
over the SVG pin field); TWO blank program slots grow the matrix
rightward (programs are {id, label} so blank labels keep unique pin
keys; the slots recall as honest all-off programs — verified: Slot5
lights four red verdicts and a dash); the panel window widens to 560.
The lower level becomes one bench: drums · machined groove · TPAD over
MOUSE · groove · sleep dial, and the separate Pointing plate dissolves.
Maintenance note: a string-surgery patch had earlier fused pinMatrix and
programMatrix (shared anchor text matched the wrong builder — the
assignment silently vanished); both were rebuilt clean, which the kit
merge should treat as the canonical text. Keys blur after click so only
meaningful light remains. Next design conversation, per Craig: how the
sleep dial associates with the action it fires at zero.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-28.html][Prototype 28 — the idle tripper rail]] (2026-07-22): the dial-association
conversation resolved the dial out of existence. Craig's question — "in X
minutes from now, or when idle for X minutes?" — was answered B, with the
principle stated: THIS PANEL PROGRAMS FUTURES, not immediate actions. A
wound countdown lies for intent B (an idle threshold re-arms on input),
so the sleep dial retired and the idle pipeline surfaced as its honest
analog: the tripper rail (kit-candidate #12, DUPRE.tripRail — the
mechanical time-switch tripper translated from clock time to idle time).
A sqrt-spaced idle-minutes scale with clamp tabs — DIM 5 · LOCK 7 ·
WATCH 8 · SCREEN OFF 10 · SUSPEND 30 — dragged to retune (stages clamp
between neighbors, keeping pipeline order), a dashed OFF siding parks a
stage disabled, flags re-alternate among active tabs so labels never
collide, and engaged CAFFEINE renders the whole rail dimmed with a
BYPASSED · CAFFEINE stamp — the pin's meaning made visible. This
supersedes the idle-pipeline decision's "delays live in hypridle.conf"
placement: the rail IS the panel-native programming surface for those
same values (the build writes hypridle.conf and reloads). Verified:
dragging SUSPEND 30→45 commits, LOCK clamps below its neighbor, WATCH
parks to off, the bypass dims and stamps.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-29.html][Prototype 29 — the idle tripper dial]] (2026-07-22): the rail was my
translation; Craig's actual mental image was the ROUND form — the
Intermatic segment-timer dial with four COLORED tripper tabs clamped on
the rim (kit-candidate #13, DUPRE.tripDial; the rail stays a candidate in
its own right). A 300° sqrt-spaced idle scale with a bottom OFF notch:
drag a tab around the rim to retune its stage, drop it through the notch
to disable; a side legend maps color → stage → minutes (DIM amber ·
LOCK slate · SCREEN OFF steel · SUSPEND terracotta). Two design
resolutions rode in with it: WATCH IS THE LOCK SCREEN — the night watch
becomes the face the lock stage shows, not a pipeline stage of its own
(the idle-decision's separate eye-candy stage folds into LOCK; the
night-watch build gains "runs as/over hyprlock" as its integration
target); and the dial returns to the bench, restoring drums · groove ·
pointing · groove · dial. Verified: rim drag commits (SUSPEND 30→45),
order clamping holds (LOCK stopped at DIM+0.5), the notch parks a stage,
CAFFEINE dims the face under the BYPASSED stamp.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-30.html][Prototype 30 — family chrome]] (2026-07-22): Craig flagged the panel as
noticeably off-family from maint/net/bt; diagnosis: the prototypes had
been wearing the widget gallery's amber (#e2a038) since P9, while the
family runs THEME gold (#dab53d / #ffd75f) — plus flat brushed plates
where the family uses raised gradient faceplates. Aligned: theme-gold
token family, maint-style body glow and panel background, the maint
header (raised face, cream wide-tracked title), raised-gradient plates
with inset highlights, and a darker matrix field inset into a lighter
plate (the requested contrast — empty sockets now read as visible
punch-card rings). Also this pass: slots labeled 1 · 2 as SLIM keys
(programMatrix gains weighted column widths; window compacts to 540);
factory presets programmed (FOCUS 1011↑ · PRESENT 0011– · BATTERY 1000↓
· NIGHT 1101↓, slots all-off, all programs persist edits); the section
renamed PROGRAMMABLE PRESETS; the caffeine/CPU divider removed; drums
and dial enlarged with lighter cream dial numerals. Open question
parked: where TPAD/MOUSE live (Craig floated right-of-the-presets;
recommendation recorded in session notes to keep them off the
programming faceplate).

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-31.html][Prototype 31 — encircled groups]] (2026-07-22): the TPAD/MOUSE question
resolved — Craig accepted keeping them off the programming faceplate but
wanted them smaller: the rockers retire and the pair become console keys
(same primitive as the preset heads, lighting green when engaged),
horizontal, seated above the dial. The bench reorganizes into three
ENCIRCLED instrument groups — bordered boxes with their labels set into
the border break, the classic faceplate group idiom: BRIGHTNESS (the
drum pair, grown to 204 to match proportion), POINTERS (the two keys),
IDLE (the tripper dial, size unchanged). Grooves retired with the
rockers. Verified: keys toggle live state and light green, groups render
with break labels, no bench overflow. With this pass Craig declared the
settings panel's cosmetics done; next surface: the wallpaper sub-view.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-32.html][Prototype 32 — the wallpaper channels]] (2026-07-22): built from Craig's
mode-table reframe (see "Wallpaper sub-view — the mode table" under
Design sketch): the units of choice are MODES, not framed pictures, so
the sub-view is a CHANNEL BANK — seven mode cards, each wearing its own
face per the table: WATCH (mini radar face), SUN PAIR (diagonal slashed
thumbnail of the selected pair), SINGLE (the chosen thumb), RANDOM (a
fanned deck — the answer to the table's open representation question),
VIDEO (play-badged frame), CLOCK (drawn face), WORLD (mini-clock
matrix). The active channel rings green; the config surface below
switches per channel — library grid for single, the PAIR PRESS for
sun pair (fill the day frame, the night frame auto-arms, MINT PAIR
strikes the slashed chip into a persistent tray of selectable pair
objects, exactly the mint semantics Craig specified), the interval wheel
(tape-wheel idiom, 5/10/15/30/60) for random, a video picker, and
honest no-options plates for the generators. The wallpaper row's state
text reads the tuned channel. Verified: channel switching, single
selection, the full mint flow (day pick auto-arms night, minted pair
joins tray selected), interval cycling. Mechanisms like the carousel
remain available for the eventual real-image library picker, demoted to
the one layer where units are uniform.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-33.html][Prototype 33 — sources + pair scrap]] (2026-07-22): two missing
capabilities land. SOURCES: a directory list at the sub-view's foot (all
channels draw from it) — folder rows with remove (guarded: the last
source can't be removed) and an ADD DIRECTORY key (mock candidates; the
real build opens a directory picker). PAIR SCRAP: hovering a minted chip
reveals ✕; the first strike arms it red ("strike again to scrap"), the
second deletes — arm-to-fire friction for a destructive act, consistent
with the panel's danger idiom; selection index self-heals including the
empty-tray case. Verified: add/remove sources with the last-source
guard, scrap flow arms then deletes, empty tray renders honestly.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-34.html][Prototype 34 — annotation batch one]] (2026-07-22): Craig's new iteration
method in action — he annotated via org-capture into the roam inbox
(ten archsetup notes), I claimed and applied the batch. Settings side:
SETTINGS header amber-caps (verified against the net/bt prototype, whose
header word is gold — the P30 family pass had wrongly copied maint's
cream); preset keys become GLYPHS (crescent moon for NIGHT, half battery
F007E for BATTERY, projector screen for PRESENT, and — answering Craig's
"focus = ? help with this" — the crosshairs reticle F0210, aim-and-
attend, over eyeglasses which read as "reading"); the narrower keys buy
FOUR numbered slots; CPU balanced glyph – → =; TOUCHPAD spelled out; the
drums' redundant LEVELS ×10 title removed (per Craig's screenshot) and
the drums grown into the space; the toast's idle "waiting…" hidden.
Wallpaper side (his sun-pair architecture + the extend-everywhere
directive): every mode gets a DESCRIPTION panel (helpful operating text,
never "no options"); galleries are side-scrolling strips (7-10 thumbs);
the section order for sun pair runs modes → minted pairs → pair press →
pictures → sources; the minted-pair gallery sorts alpha/recency via two
small keys, shows labels under chips (nothing when unlabeled), and each
chip carries ~ (edit: reopens day/night/label in the press and leaves
the gallery, re-mint to return) and − (delete; recreate to recover);
the press gains its label field; the picture gallery feeds the armed
frame and notes the extension filtering; PREVIEW sections show watch
(Craig's real night-watch screenshot, trimmed to
prototypes/2026-07-22-watch-preview.png), clock, world, single, and
video; SOURCES appears only for the directory-drawing modes (single,
pair, random, video) and hides for the generators. All flows verified
headless including the edit-remint round trip and sort toggles.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-36.html][Prototype 36 — annotation batch two]] (2026-07-22): eight more roam
captures applied. Settings: all matrix keys uniform (43px — glyph keys
slimmed to the numbered keys' size, glyphs bumped to 15px for
recognizability); the bench rearranged — POINTERS above BRIGHTNESS on
the left, the IDLE dial alone on the right, enlarged to 184 with its
legend moved BENEATH the dial (a legendPos option on the tripDial
kit-candidate); drums centered in their frame. Wallpaper: a NEW SOLID
COLOR channel (eighth card) in the sun-pair format — minted labeled
colors above, color picker + label + MINT below, no sources; RANDOM
gains minted SETS — labeled, count-badged chips (first picture + count),
sortable, with ~/− edit/delete, built in a set press by clicking
pictures in and out, minimum two, interval wheel retained; sort keys now
stack vertically LEFT of every sortable gallery; all side-scroll
galleries wear custom themed scrollbars inside evenly-padded wells;
SOURCES scrolls vertically past four entries; and the pair tray is
seeded with a dozen pairs so the scroller's position shows. Verified:
uniform key row, bench order and dial legend, pair tray overflow, solid
mint, set press round trip (mint "blues" of three), card count badge.
P35 remains the linked final for the matrix/bench; the wallpaper
sub-view's normative reference advances to this file.

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-37.html][Prototype 37 — annotation batch three]] (2026-07-22): nine more captures.
Channel faces go ICONIC — the sun-pair card is a fixed yellow/navy
diagonal with a dark sun glyph on the gold and a cream crescent on the
navy (per Craig's spec), SOLID wears dupre blue, and the world card's
mini clocks are redrawn as honest clocks (cream faces, hour + minute
hands at six different times; the world preview matches). Numbered slots
register as scenes named 1-4 so activation announces "▶ 1" instead of a
slot codename. The idle dial's center reads the EXACT minutes (halves
included) live while a tab drags, reverting to a now-visible IDLE (9px
cream) on release; the legend shows exact values too. The video
channel's preview shrinks to 55% so sources fit; the sub-view title
capitalizes to WALLPAPER. FOCUS tries the headphones glyph (F02CB) as
the deep-work icon — awaiting Craig's confirmation, crosshairs retired.
All seventeen applied annotations (batches two + three) swept from the
roam inbox after application; seven foreign items remain for their
projects.

* Metadata

| Field  | Value                                        |
|--------+----------------------------------------------|
| Status | implemented                                  |
|--------+----------------------------------------------|
| Owner  | Craig Jennings                               |
|--------+----------------------------------------------|
| Repo   | dotfiles                                     |
|--------+----------------------------------------------|
| Kin    | net panel (architecture donor), theme studio |
|        | audio panel (sibling), bt panel (aesthetic)  |
|--------+----------------------------------------------|

* 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, night-light, Do Not Disturb, power profile, lock/suspend
   actions, scenes, and a wallpaper manager (see the controls table).
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

** Prior art — how the major desktops solve the quick-settings UX

Surveyed 2026-07-21 for the prototyping phase (ui-prototyping rule: research
before picking a direction).

- *GNOME Shell 43+ Quick Settings* — replaced the decade-old system menu
  with a grid of pill-shaped toggle tiles. Each pill is dual-function: click
  the body to toggle, click a small arrow to expand a submenu that draws
  over the grid rather than opening a new surface. Sliders span two grid
  columns; on/off state is carried by the pill's fill colour. Component
  anatomy: QuickToggle, QuickMenuToggle (toggle + popup submenu),
  QuickSlider, in a column-based grid.
  Sources: [[https://www.debugpoint.com/gnome-43-quick-settings/][debugpoint on the GNOME 43 redesign]],
  [[https://gjs.guide/extensions/topics/quick-settings.html][gjs.guide Quick Settings anatomy]].
- *macOS Control Center* — a menu-bar hub of modules. Controls are
  dual-function here too: clicking a module's icon toggles it, clicking its
  name or arrow opens a deeper sub-view expanded in place (Wi-Fi, Bluetooth,
  Display, Sound). Modules can be dragged out to the menu bar for permanent
  glanceable placement — the same two-layer bar/panel split this spec
  commits to (touchpad + caffeine stay on the bar; the rest collapses in).
  Sources: [[https://support.apple.com/guide/mac-help/quickly-change-settings-mchl50f94f8f/mac][Apple Support — Use Control Center on Mac]],
  [[https://macmost.com/customizing-and-using-control-center-on-your-mac.html][macmost Control Center walkthrough]].
- *Windows 11 Quick Settings* — a taskbar flyout: customizable button grid
  with sliders below it. The trend line is consolidation: 26H2 adds a
  light/dark toggle to the flyout so the Settings app isn't needed, and the
  hardware volume/brightness flyouts are being restyled and made
  repositionable.
  Sources: [[https://pureinfotech.com/windows-11-26h2-quick-settings-dark-mode-toggle/][pureinfotech on the 26H2 flyout]],
  [[https://pureinfotech.com/change-quick-settings-buttons-windows-11/][pureinfotech on button customization]].
- *KDE Plasma 6* — the counter-example: no single consolidated panel;
  per-applet popups hang off individual system-tray icons (6.4 raised
  control contrast and added tray-entry hiding). This is the
  scattered-toggles status quo the spec exists to fix.
  Source: [[https://www.omgubuntu.co.uk/2025/06/kde-plasma-6-4-review-new-features-linux-desktop][OMG! Ubuntu Plasma 6.4 review]].
- *iOS / macOS Focus modes* — the prior art for scenes: named modes that
  flip several settings in one action, surfaced as first-class controls in
  Control Center. The shared prototype engine's SCENES model mirrors this.

Convergent conventions the directions are judged against: a two-layer model
(glanceable bar + consolidated panel); dual-function controls (toggle on the
control itself, expand for depth); compact toggle grid with full-width
sliders; sub-views drawn inside the panel rather than as new windows
(matches the wallpaper-sub-view decision); scenes as first-class controls.

** Final prototype (normative reference)

[[file:../prototypes/2026-07-02-desktop-settings-panel-prototype-37.html][Prototype 37 — the sealed final]] (2026-07-22, Craig's "Build it"),
superseding P35 as the single normative reference after annotation
batches two and three:
the consolidated machine every build phase points at. Structure: the
PROGRAMMABLE PRESETS matrix (glyph program keys + four numbered slots,
white punch pins with jewel verdicts, arrow/equals CPU tape wheels,
active-is-live semantics); the instrument bench of three encircled
groups (BRIGHTNESS drum pair, POINTERS console keys, IDLE tripper dial
with color-tabbed stages and caffeine bypass); and the WALLPAPER
channel sub-view (seven mode cards, per-mode descriptions, side-scroll
galleries, previews, the labeled pair press with mint/edit/delete, and
per-mode sources). Verified by a 17-point end-to-end suite, all
passing. The full design history lives under Prototype iterations in
the Status section; the kit-candidate components accumulated along the
way live in prototypes/dupre-kit-additions.js pending the kit merge.

** 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.
- Instrument-console faceplate aesthetic, consistent with net + bt + audio:
  the machined gradient plate, glowing status lamps, engraved section labels,
  physical console keys for the toggles, and (where a level applies) needle
  gauges. Load the shared instrument-console palette/faceplate CSS asset all
  the family panels use — factor it once, don't duplicate (feeds the
  theme-studio task later).

** Controls and their backings

| Control            | Kind     | Backing                                      |
|--------------------+----------+----------------------------------------------|
| Auto-dim toggle    | toggle   | hyprctl decoration:dim_inactive (dim-toggle) |
|--------------------+----------+----------------------------------------------|
| Idle / caffeine    | toggle   | hypridle start/stop (caffeine-toggle).       |
|                    |          | Back to a plain toggle as of P21 — the timed |
|                    |          | wind-up moved to the sleep timer below.      |
|--------------------+----------+----------------------------------------------|
| Idle program rail  | tripper  | the hypridle pipeline as a time-switch       |
|                    | rail     | tripper rail: drag DIM / LOCK / WATCH /      |
|                    |          | SCREEN OFF / SUSPEND tabs along an           |
|                    |          | idle-minutes scale (writes hypridle.conf +   |
|                    |          | reload); a tab in the OFF siding disables    |
|                    |          | its stage; engaged caffeine renders the      |
|                    |          | whole rail bypassed. Replaced the P21 sleep  |
|                    |          | timer at P28 — Craig ratified intent B       |
|                    |          | ("when idle for X", not "in X from now"):    |
|                    |          | this panel programs futures.                 |
|--------------------+----------+----------------------------------------------|
| Touchpad toggle    | toggle   | toggle-touchpad + touchpad-state file        |
|--------------------+----------+----------------------------------------------|
| Mouse toggle       | toggle   | same mechanism, mouse-state file             |
|--------------------+----------+----------------------------------------------|
| Screen brightness  | slider   | brightnessctl (backlight class), slider + %  |
|--------------------+----------+----------------------------------------------|
| Keyboard backlight | slider   | brightnessctl (kbd_backlight class), slider  |
|--------------------+----------+----------------------------------------------|
| Night light /      | toggle   | color-temperature shift (candidate:          |
| color temperature  |          | hyprsunset; confirm the tool at build)       |
|--------------------+----------+----------------------------------------------|
| Do Not Disturb     | toggle   | dunstctl set-paused (pause notifications).   |
|                    |          | Verified 2026-07-21: pause queues, then      |
|                    |          | floods everything on unpause — never drops.  |
|                    |          | DECIDED (Craig, 2026-07-21): class-split.    |
|                    |          | Ordinary notifications DROP at unpause;      |
|                    |          | alarms (urgency critical + rules promoting   |
|                    |          | known alarm sources) SURVIVE DND and show.   |
|                    |          | Build detail: dunst pause levels with        |
|                    |          | override_pause_level lets alarms punch       |
|                    |          | through live vs held-to-unpause — pick at    |
|                    |          | build. History keeps everything either way.  |
|--------------------+----------+----------------------------------------------|
| Power profile      | selector | powerprofilesctl (performance / balanced /   |
|                    |          | power-saver, three-way)                      |
|--------------------+----------+----------------------------------------------|
| Scenes / profiles  | composite| one control that flips several toggles at    |
|                    |          | once: Focus, Presentation, Battery-saver,    |
|                    |          | Night (see the Scenes decision below)        |
|--------------------+----------+----------------------------------------------|
| Wallpaper manager  | sub-view | still-open shape (row-that-opens-a-sub-view  |
|                    |          | vs its own sub-spec) — resolve at spec-review|
|--------------------+----------+----------------------------------------------|

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. A scene reads back each toggle it
sets and reports the composite as applied only when every member verified.

** Wallpaper sub-view — the mode table (Craig, 2026-07-22)

Craig's reframe, thinking out loud: every mechanism proposal (carousel,
light table, film strip) assumed uniform framed objects, but the real
units of choice are MODES — heterogeneous programs for what the screen
shows. His inventory:

| Mode              | Representation                 | Options                  |
|-------------------+--------------------------------+--------------------------|
| Night watch       | to be designed                 | none                     |
|-------------------+--------------------------------+--------------------------|
| Sunup/sundown     | slashed thumbnail — the thumb  | choose + save pic PAIRS  |
|                   | split vertically or diagonally |                          |
|                   | (top-right to bottom-left),    |                          |
|                   | day pic one side, night the    |                          |
|                   | other                          |                          |
|-------------------+--------------------------------+--------------------------|
| Single            | thumbnail                      | none                     |
|-------------------+--------------------------------+--------------------------|
| Randomize         | open (deck/fan candidate)      | interval spinner (mins   |
|                   |                                | before next random item) |
|-------------------+--------------------------------+--------------------------|
| Video (Apple-TV   | video thumbnail                | none                     |
| aerial style)     |                                |                          |
|-------------------+--------------------------------+--------------------------|
| Custom clock      | picture of the clock           | none                     |
|-------------------+--------------------------------+--------------------------|
| World clock       | matrix of mini-clocks          | none                     |
|-------------------+--------------------------------+--------------------------|

Clock-channel backings (Craig, 2026-07-22): neither clock is a new
design. CUSTOM CLOCK renders the clock that already appears when the
waybar time module is clicked; WORLD CLOCK renders a matrix of miniature
clocks with their timezones and cities — the same data the time module's
hover tooltip shows. One owner per clock design; the wallpaper channels
are projections of those existing surfaces onto the desktop.

Pair semantics (Craig): pairs are SAVED OBJECTS — build one by choosing a
day pic and a night pic, alter either, confirm; the pair is minted and
remains selectable as a unit thereafter. The pair library persists.

** 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: Super+Shift+G (decision B).

* Decisions (Craig)

** DONE Which standalone bar indicators collapse into the panel?
CLOSED: [2026-07-04 Sat]
Resolved (Craig, 2026-07-04): touchpad and caffeine stay on the bar (glanceable state); auto-dim and airplane move into the panel (panel-only, freeing bar width). The airplane Super+Shift+A toggle keybind stays as the quick lane — only its bar indicator collapses in.

Amended 2026-07-22 (Craig, during the first live drive of the panel): caffeine's bar indicator collapses into the panel too. The bar keeps only the touchpad indicator; dim and caffeine are panel-owned (their Super+Shift+D / Super+I keybinds stay as quick lanes). Applied live same day — modules and their state CSS removed from the waybar config.

** DONE Keybind for the panel?
CLOSED: [2026-07-04 Sat]
Resolved (Craig, 2026-07-04): Super+Shift+G (gear), for parity with the other panels' fast path.

** DONE Where does the code live?
CLOSED: [2026-07-04 Sat]
Resolved (Craig, 2026-07-04): dotfiles =settings/= sibling to =net/= (same src-layout, tests in tests/settings/), sharing the palette css. The net panel is the architecture donor; the old in-tree pocketbook-style note is out.

** DONE Slider granularity and floor
CLOSED: [2026-07-04 Sat]
Resolved (Craig, 2026-07-04): 5% floor on the brightness slider, so a dark-room drag can't black the screen out and lock you out. brightnessctl's 0-100% range clamps to a 5% minimum.

** DONE What are the "few other things" beyond the toggles?
CLOSED: [2026-07-19 Sun]
Resolved (Craig, 2026-07-19, via the home->archsetup handoff). Beyond the seven
base toggles/sliders, the panel adds: night-light / color temperature; Do Not
Disturb (dunst); lock / suspend quick actions; power profile
(performance/balanced/saver); and scenes/profiles (see the Scenes decision).
Plus the wallpaper manager already confirmed 2026-07-04 (its shape stays open,
see the Wallpaper decision). The controls table above now carries all of them.

OUT of this panel, with reasons: volume / master-mute stays with the audio
panel (this panel does not mirror it — one owner per control); theme light/dark
goes to the separate theme-studio task, not here.

Amended 2026-07-22 (Craig): airplane mode is withdrawn from the panel too —
it's about the network, and the network panel carries it as its main
on/off. Same one-owner-per-control reasoning; keeping a copy here
overcomplicated the switch wall. (The Super+Shift+A keybind and the
network panel's master switch are the two lanes.)

Amended 2026-07-21 (Craig): lock and suspend are withdrawn from the panel.
Session-exit actions live on the wlogout screen (Super+Shift+Q:
lock/reboot/shutdown/logout/suspend/hibernate) — same one-owner-per-control
reasoning as volume. The direction prototypes still show lock/suspend
buttons; the iterate-to-final pass drops them.

Format pickers (time/date/weather display format) are pulled out entirely into
their own future sibling spec. The real problem there is a single source of
truth — many programs store their own format, so the design question is where
the canonical time/date/weather format lives and how every consumer (clock
module, weather chip) reads it without drift. Tracked as a stub:
[[file:2026-07-19-display-format-single-source-of-truth-spec.org][display-format single-source-of-truth]].

*** 2026-07-04 Sat — Craig's input (roam capture): the set includes a wallpaper manager
Confirmed the panel gathers the mouse/trackpad toggle, a no-sleep (idle-inhibit) toggle, and the auto-dim toggle, and adds a *wallpaper manager* (this is where the displaced waypaper functionality lands — see the media/keybind change that freed Super+Shift+P). The wallpaper manager needs its own depth:
- take a number of directories to look in;
- switch the wallpaper with the change persisting across sessions;
- switch between two pictures at sunup / sundown (a day/night pair).
That last one implies a sun-time source (a lat/long or a sunrise/sunset lookup).

** DONE Idle pipeline — staged timeouts and an idle power action
CLOSED: [2026-07-21 Tue]
Resolved (Craig, 2026-07-21), the lean package with one revision: dim
5 min/10% and lock 7 min stay; add screen-off (DPMS) at 10 min; idle
suspend-then-hibernate at 30 min — default ON for velox, and PRESENT on
ratio too (not hidden by battery detection) but default OFF with an
armed-trigger confirmation before enabling, since an idle-suspended desktop
drops tailscale sessions and hourly backups. Hyprlock grace 5 s. The panel
surfaces only the situational control (the caffeine timer dial); stage
delays live in hypridle.conf. Original analysis below.

Amended same evening (Craig, 2026-07-21): the eye-candy stage is IN after
all — as the Dupre Instrument Night Watch, a fullscreen board of the kit's
own instruments on watch (split-flap + movement + seven-seg carrying real
time, radar sweeping, scope tracing, drift chart, spectrum, VU programme,
blinkenlights core, elapsed tape counter, systems lamps, voice loops, VFD
wire, engine-order telegraph that rings a new order every couple of
minutes). Prototype:
[[file:../prototypes/2026-07-21-night-watch-screensaver-prototype-1.html][night-watch prototype 1]].
It runs between lock and screen-off as a hypridle stage (fullscreen
browser/webview launched on-timeout, killed on-resume); the power cost is
accepted for the stage's duration since DPMS still follows at its delay.
Kit note for the merge task: span-built instruments (scope, stripChart,
vfdMarquee, analogClock, rotsel, keylock) need a blockifying host outside
the gallery's card grid — the night-watch page carries the one-rule fix.
Opened 2026-07-21 from Craig's question: "shutdown/reboot/suspend/hibernate
when idle for X minutes?" Yes — hypridle listeners run arbitrary on-timeout
commands, so any systemctl action can be a stage. Today's pipeline is only
dim-to-10% at 5 min → lock at 7 min; there is no screen-off (DPMS) stage and
no power action, so an idle machine glows at 10% forever.

Proposed idle group for the panel, replacing the bare caffeine on/off:
- Dim delay + dim level (currently hardcoded 300 s / 10%).
- Lock delay (currently 420 s).
- Screen-off (DPMS) stage after N minutes — new.
- Idle power action after X minutes — one of none / suspend / hibernate /
  suspend-then-hibernate / shutdown. Ordering guarantee: lock always fires
  before the power action so the machine wakes locked.
- Caffeine becomes a timed inhibit (wind-up timer, e.g. the kit timerDial:
  30/60/120 min or until-off) instead of killing the whole daemon.

Added 2026-07-21 (Craig approved recording these alongside the stages):
- Hyprlock grace period (currently grace = 0): N seconds after lock where
  any input wakes without a password — softens an aggressive lock delay.
- Optional eye-candy stage: an animated "screensaver" (mpvpaper loop,
  terminal art, shader) launched by a hypridle stage and killed on resume.
  Sits before the DPMS stage if offered at all; it holds GPU + display
  awake, so it trades power for style.
- Lock-face notes for the build: path = screenshot shows a blurred image
  of the work session (privacy consideration; wallpaper/solid is the
  alternative), and hyprlock labels can run shell commands on an interval
  (cmd[update:N]) — the lock face can carry weather/now-playing/battery.

Build notes: Wayland's idle-inhibit protocol already keeps the pipeline at
bay during media playback (video players and browsers inhibit idle, and
hypridle honors it), so caffeine's real audience is passive non-media use —
long reads, watching a build, screen-share without input. systemd
suspend-then-hibernate is the likely default for velox
(suspends now, hibernates when the battery drains); shutdown-on-idle is the
risky option (kills the session and anything unsaved) and wants a long delay
if offered at all; AC-vs-battery differentiation is possible by making the
on-timeout a script that checks the power source. Decisions needed from
Craig: which stages to expose, the default delays, and whether the power
action appears on both machines or only the laptop.

** DONE Scenes / profiles — one control that flips several toggles at once
CLOSED: [2026-07-19 Sun]
Resolved (Craig, 2026-07-19): the panel offers named scenes that set several
controls in one action — Focus, Presentation, Battery-saver, Night. Scenes are
the payoff of consolidating every desktop control in one panel. The exact
toggle set each scene applies is a build-time detail (design it against the
control table); the spec commitment is that scenes exist and each verifies
every member it sets (see Controls note above).

** DONE Wallpaper manager — a panel row that opens a sub-view, or its own sub-spec?
CLOSED: [2026-07-19 Sun]
Resolved (Craig, 2026-07-19): a row in the panel that opens a sub-view, kept
inside the one panel (the "consolidate everything" thesis). The wallpaper
manager's depth (directories to scan, persistent selection, a day/night
sunup/sundown pair needing a sun-time source) lives in that sub-view, not a
separate surface. Sun-time source (lat/long or sunrise/sunset lookup) is a
build detail for the sub-view.

* Implementation phases

All phases live in dotfiles =settings/= (archsetup drives the lifecycle).
The normative reference for every UI decision is prototype 37; the design
history is the Prototype iterations subsection.

1. *Backings engine* — pure Python, TDD with fake binaries. Brightness +
   keyboard backlight (brightnessctl, 5% floor, ×10 drum mapping); toggle
   backings (hyprctl dim_inactive, touchpad/mouse state scripts, hypridle
   caffeine inhibit); DND via dunst pause levels implementing the
   class-split semantic (ordinary notifications drop, alarms survive —
   punch-through vs held decided here); powerprofilesctl three-way; the
   hypridle.conf writer + reload for the idle pipeline (four stages, per-
   stage enable/disable, hyprlock grace); the wallpaper engine — persisted
   mode store (channel, single, minted pairs/sets/colors with labels,
   video, interval, sources), setter adapters (images via the chosen
   setter, solid colors, video via mpvpaper, clock/world/watch as
   projected surfaces), sunrise/sundown calculation from lat/long, the
   random-draw timer, and extension filtering for the galleries.
2. *Presenters* — GTK-free models, unit-tested to 100% like the net
   PanelModel. The program-matrix model (programs as complete
   definitions; active-is-live with program-membership writes surviving
   activation; pin, letter, and radio row kinds; slots 1-4 as first-class
   programs); the bench model (drum mapping, pointers, idle stages with
   order clamping, parking, and caffeine bypass); the wallpaper channels
   model (mint/edit/delete and alpha/recency sort for pairs, sets, and
   colors; per-mode sources visibility; previews).
3. *GTK4/Blueprint UI* — port the instruments prototype 37 actually uses
   to GTK widgets in the Dupre family chrome: console keys, the
   programmable matrix (glyph + numbered heads, jewel verdicts, tape
   wheels), drum roller, tripper dial (bottom legend, exact-minutes drag
   counter, bypass stamp), encircled bench groups, iconic channel cards,
   side-scroll gallery wells with themed scrollbars, the pair/set/color
   presses. Architecture rule from the prototypes: instruments that own a
   clock own their widget lifetime (never rebuilt on state refresh).
   Layer-shell chassis under the bar, wallpaper sub-view navigation,
   AT-SPI smoke per the family pattern.
4. *Integration and bar* — gear module + Super+Shift+G; bar consolidation
   per decision A as amended (dim and caffeine modules dropped 2026-07-22;
   airplane's bar indicator is gone with the control — the network panel
   owns it; only touchpad keeps a bar indicator; wire refresh signals
   both ways); the
   watch/clock/world renderers as projected surfaces (the night watch as
   the hyprlock face per the WATCH-is-the-lock-screen resolution); live
   hypridle rewrite-and-reload; dunst pause-level configuration; end-to-
   end verify-everything against the real machine.

Test surface: fake-binary suites for every backing; presenter suites
covering program recall/edit semantics (including the active-scene-
survives-member-writes invariant), idle-stage clamping/parking/bypass,
and mint/edit/delete/sort round trips for all three minted stores; one
AT-SPI smoke; a scripted end-to-end pass mirroring prototype 37's
17-point suite.

* Review findings [7/7]

Reviewed 2026-07-22 (in-session, both roles — the annotation-batch method
kept author and reviewer in one loop; Craig's "Build it" sealed the
design). Rubric: *Ready with caveats* — the caveats are build-time picks,
not design gaps.

** DONE Implementation phases reflected the pre-casting roster
CLOSED: [2026-07-22 Wed]
The four phases still described the original controls table (lock/
suspend, per-toggle rows). Rewritten this pass to the settled design —
matrix, bench, wallpaper channels, projected surfaces — with the test
surface enumerated.
** DONE Stale architecture prose vs settled design
CLOSED: [2026-07-22 Wed]
The Design sketch accumulated its corrections through the iteration
entries (controls table amended in place; wallpaper mode table and
clock-channel backings recorded; Final prototype section added). The
iterations subsection is the authoritative design log.
** DONE Wallpaper setter tool selection :build:
CLOSED: [2026-07-22 Wed]
DECIDED (phase 1, 2026-07-22): awww 0.12.1 — the swww fork already
running as the wallpaper daemon (=swww= on PATH is a symlink to it;
=set-wallpaper= already drives it). Images and slashed pairs go through
awww =img=; solid colors through awww =clear <color>=; video via
mpvpaper (not yet installed — install lands in phase 4 integration);
clock/world/watch are projected layer-shell surfaces, not setter jobs.
The engine's setter adapter takes the binary from env so the fake-binary
suite and a future setter swap both stay one seam.
** DONE Speedrun pre-flight picks (Craig, 2026-07-22) :build:
CLOSED: [2026-07-22 Wed]
Batched before the phases 2-4 autonomous run:
- Alarm sources for DND: wtimer only — its notifications get the
  CRITICAL promotion in the phase-4 dunstrc rules; everything else
  drops at unpause.
- Night-watch host: google-chrome-stable in kiosk mode, launched by the
  hypridle watch stage, killed on resume.
- Sun-pair location: live whereami lookup at each transition (the
  machine's own location is the right datum for its screen), with the
  last good reading cached in state.json as the offline fallback.
- Factory scenes (Focus / Presentation / Battery-saver / Night): drafted
  against the controls table during phase 2, corrected by Craig in the
  panel afterward.
** DONE DND unpause variant — held, not punch-through :build:
CLOSED: [2026-07-22 Wed]
DECIDED (Craig, 2026-07-22, first live drive): the held-to-unpause
variant. While DND is on nothing shows, alarms included (pause level
100 holds everything). At release, ordinary notifications are dropped
(history keeps them) and the alarms that arrived during DND surface:
close-all → read history → unpause → history-pop each CRITICAL entry
newer than the engage stamp, oldest first. The engine records the
engage instant as CLOCK_MONOTONIC microseconds (dunst's history
timestamp base) in $XDG_RUNTIME_DIR. The controls-table note offering
punch-through-live is superseded by this finding.
** DONE Night-light tool selection :build:
CLOSED: [2026-07-22 Wed]
DECIDED (phase 1, 2026-07-22): gammastep (installed; hyprsunset is not).
On Wayland the gamma ramp only holds while a client owns the
wlr-gamma-control protocol, so gammastep stays resident while night
light is on and the backing mirrors caffeine's daemon model: engage =
spawn detached (=gammastep -O <temp>=, default 4500K), release = pkill,
pgrep as the one source of truth. Swapping to hyprsunset later is one
adapter change behind the same seam.
** DONE Persisted store location and format :build:
CLOSED: [2026-07-22 Wed]
DECIDED (phase 1, 2026-07-22): one JSON document at
=~/.config/desktop-settings/state.json= (root overridable via
=DESKTOP_SETTINGS_CONFIG_DIR= for tests) carrying programs (slots 1-4),
idle stages, and the wallpaper store (channel, pairs, sets, colors,
sources, interval). Factory presets ship as defaults in code; the store
writes atomically (temp file + rename) and tolerates a missing or
corrupt file by falling back to defaults.