From 3ae44b636f5f55e9fe50e15fdfe7fe6ddfb6d1a9 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 12 Jul 2026 21:03:02 -0500
Subject: docs(spec): component-generation spec reviewed, folded, and
 decomposed

spec-review passed with three findings, all pre-agreed and folded in the same pass: the option-1 approval superseded the demand-gated extraction order (extraction now covers the full catalogue ungated, phases 1-2 swapped, decisions 4 and 8 re-scoped), the card-record refactor is now named in phase 1, and stale counts were refreshed (109 cards, R56). Lifecycle DRAFT -> READY -> DOING; phase tasks live under the Retro widget catalogue parent with the spec UUID stamped as :SPEC_ID:.
---
 todo.org | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

(limited to 'todo.org')

diff --git a/todo.org b/todo.org
index 535fe7c..d08d48c 100644
--- a/todo.org
+++ b/todo.org
@@ -60,17 +60,34 @@ Six period families defined (green = P1 phosphor built on =phos=, amber = P3 on
 *** 2026-07-12 Sun @ 13:15:19 -0500 Added spec sheets to all 84 cards
 Every card now carries a collapsible "spec sheet" (a details element under the note) with up to 8 fields: input (always present, names the model — click ports everywhere including Emacs click-regions, drag needs a click/key idiom there, display widgets take no real input), solves, use (common vs specialty + where it shines), limits, origin, difficulty, prefer-when, and period (present on 41 of 84 — only where the component is clearly not timeless, e.g. nixie 1955-75 sits with keypads/telegraphs and clashes with VFD and LED seven-seg). Content lives in one INFO object keyed by card number; card() renders it. CDP-verified: 84/84 sheets present (missing-key check), fields render, zero exceptions.
 *** TODO Widget validation pass
-Craig validates every control before any componentization build (his call — the lamps are his worklist, not agent-checkable). Each card carries a status lamp at the upper-right: click cycles off → amber → green, state persists per card in localStorage (key =gv-<no>=). When the pass completes, bake the final statuses into the gallery source and use the green set as the build order for the widgets.js extraction.
+Craig validates every control via the card lamps (his worklist, not agent-checkable): click cycles off → amber → green, state persists per card in localStorage (key =gv-<no>=). Gate change with the option-1 approval (2026-07-12): the lamps no longer gate the widgets.js extraction (lossless, proceeds now) — they gate per-widget Emacs ports and the final catalogue blessing. When the pass completes, bake the final statuses into the gallery source.
 *** TODO Component classification taxonomy
 Brainstorm WITH Craig (after the squash merge, not solo): break the components down by use — freeform output, binary selection, multi-selection, fine-tuning, etc. The taxonomy identifies use-cases with no appropriate component, which fills out the gallery with some confidence of completeness.
 ** DOING [#B] Retro widget catalogue :feature:design:
-The panel widget gallery ([[file:docs/prototypes/panel-widget-gallery.html][docs/prototypes/panel-widget-gallery.html]]) grows into a retro-instrument component catalogue: reference photos of period hardware → gallery cards (the visual + behavioral spec) → reusable components for three targets (emacs svg.el, web/React, waybar). Tokens single-sourced in [[file:docs/prototypes/tokens.json][tokens.json]] (gen_tokens.py emits web/waybar/elisp); svg.el proof widget shipped (gallery-widget.el, needle gauge). Reference photos live in [[file:working/retro-stereo-widgets/][working/retro-stereo-widgets/]]. R-series cards (R01-R31) are the reference-derived widgets — collection phase COMPLETE 2026-07-12 (84 cards, all behaviorally verified).
+:PROPERTIES:
+:SPEC_ID: 3ac0d42c-db1a-4d21-bce4-e63785fef0ba
+:END:
+The panel widget gallery ([[file:docs/prototypes/panel-widget-gallery.html][docs/prototypes/panel-widget-gallery.html]]) grows into a retro-instrument component catalogue: reference photos of period hardware → gallery cards (the visual + behavioral spec) → reusable components for three targets (emacs svg.el, web/React, waybar). Tokens single-sourced in [[file:docs/prototypes/tokens.json][tokens.json]] (gen_tokens.py emits web/waybar/elisp); svg.el proof widget shipped (gallery-widget.el, needle gauge). Reference photos live in [[file:working/retro-stereo-widgets/][working/retro-stereo-widgets/]]. Collection converged at R56 (109 cards, all behaviorally verified; probes in [[file:tests/gallery-probes/][tests/gallery-probes/]]).
 
-Next: spec-review of the [[file:docs/specs/2026-07-12-component-generation-spec.org][component-generation spec]] (DRAFT), then decompose via spec-response. The spec carries the agreed 5-phase plan (demand inventory → web library extraction → emacs ports → waybar audio pilot → Level-2 generator go/no-go) and the baked decisions (SVG-first, single token source, per-target interaction, demand-driven porting, gallery-as-spec). Banked variant/composition ledger lives in the 2026-07-11/12 session archive.
+Build runs per the [[file:docs/specs/2026-07-12-component-generation-spec.org][component-generation spec]] (DOING; reviewed + decomposed 2026-07-12): web extraction first (ungated, lossless), then demand-gated Emacs/waybar ports. Banked variant/composition ledger lives in the 2026-07-11/12 session archive.
 *** 2026-07-12 Sun @ 10:14:10 -0500 Wrote the component-generation spec (DRAFT)
 [[file:docs/specs/2026-07-12-component-generation-spec.org][2026-07-12-component-generation-spec.org]] via spec-create: full spine (summary, problem, goals, two-altitude design, alternatives, 8 decisions with 1 open, 5 phases, acceptance criteria, readiness dimensions, risks). Gallery cited as the prototype evidence per the ui-prototyping rule (filed references + R01-R31 iteration history + final at 52a43ec). vNext items logged as the "Widget catalogue vNext" task.
 *** 2026-07-12 Sun @ 20:24:37 -0500 Web library packaging approved — classic-script widgets.js + GW namespace
-Craig approved with the componentization go-ahead (option 1): =widgets.js= as a classic script exposing one =GW= namespace, relative =<script src>= so =file://= keeps working, shared helpers inside, framework wrappers vNext. Decision flipped DONE in the spec (cookie 8/8); spec is review-ready. Build gated on Craig's per-card validation pass (the status lamps).
+Craig approved with the componentization go-ahead (option 1): =widgets.js= as a classic script exposing one =GW= namespace, relative =<script src>= so =file://= keeps working, shared helpers inside, framework wrappers vNext. Decision flipped DONE in the spec (cookie 8/8). Gate per the same approval: extraction proceeds ungated (lossless transform); the validation lamps gate only per-widget Emacs ports and the final blessing.
+*** 2026-07-12 Sun @ 20:57:50 -0500 Spec reviewed and decomposed (DRAFT → READY → DOING)
+spec-review passed (Ready): 3 findings, all accepted and folded same pass — option-1 supersession of the demand-gated extraction order (Phases 1-2 swapped: extraction first, ungated), the card-record refactor named in Phase 1, stale counts refreshed (109 cards / R56). Probe baseline repaired first (753380e — two stale assertions from the evening sprint). Phase tasks below; =:SPEC_ID:= stamped on this parent.
+*** TODO Phase 1 — web library extraction :refactor:solo:
+Lift all 109 card builders into =docs/prototypes/widgets.js= (classic script, =GW= namespace, shared engine inside: svgEl/polar/vuDb/dragX/dragY/dragDelta/seg7/SCREEN_FAMS/gradients); restructure each card as a declarative record (no/title/stage/options/readout/note/spec-sheet incl ref/lamp) rendered by one =card()= path. Batches of ~10-15; per-batch gate = green =tests/gallery-probes/probe.mjs= + =probe-fams.mjs=; commit+push per batch. Gallery stays working from =file://= throughout. Close with the slide toggle (card 01) as the first fully-realized component: its four option groups become constructor args (on/off/offText/thumb).
+*** TODO Phase 2 — demand inventory (Emacs/waybar) :design:
+Widget-to-target matrix for the scripted-port targets: walk the live waybar panels (net/bt/audio/maint) and the Emacs surfaces Craig names; record which cards each actually wants. Lands in the spec's appendix; Craig approves. Tree untouched. Not =:solo:= — the matrix is his call.
+*** TODO Phase 3 — Emacs ports of demanded widgets :feature:
+Extend the =gallery-widget.el= pattern per demanded widget: ERT (tokens, geometry normal/boundary/error, SVG structure, state-tracks-value) + rsvg-convert side-by-side against the card; keymap/click-region interaction per widget; wired into =make test-elisp=. Gated on the Phase 2 matrix and Craig's green lamp per widget.
+*** TODO Phase 4 — waybar pilot: audio panel :feature:dotfiles:
+Restyle the audio panel's GTK CSS onto =tokens-waybar.css= + the banked composition idioms. Lives in =~/.dotfiles=; archsetup drives edit/test/commit/push end to end + inbox note. Visual result gets a manual-testing checklist entry (daily-driver panel).
+*** TODO Phase 5 — Level-2 generator go/no-go :design:
+After ~5 hand ports, weigh widget-level codegen with evidence (mechanical duplication vs judgment per port). Recorded as a dated decision in the spec; go spawns its own spec.
+*** TODO Flip the spec to IMPLEMENTED
+When the phases above close: status heading keyword → =IMPLEMENTED=, dated history line with the reason, Metadata =Status= mirror. Three lines, one file.
 ** DONE [#C] Net panel: Enterprise error never dismisses :bug:dotfiles:network:
 CLOSED: [2026-07-12 Sun]
 Fixed in dotfiles =a157bed=. Root cause: error toasts are sticky by design (so background refreshes can't wipe an unread error), but the enterprise join hint's flow posts no follow-up status and row clicks post none either, so nothing ever replaced it. Fix: a window-wide capture-phase click gesture dismisses a sticky toast on the user's next interaction; policy in =viewmodel.toast_action_plan= (unit-tested), timed toasts and background clears unchanged. Panel smoke run confirms launch/doctor/close with the gesture installed. Pointer-level dismiss is a manual-testing child (AT-SPI can't drive pointer gestures). Repro screenshot: =~/pictures/screenshots/2026-07-10_195911.png=.
-- 
cgit v1.2.3