From 896dfe7336284e9e3e6ef6c9a64467e66c00aeb4 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 12 Jul 2026 10:17:28 -0500
Subject: docs(specs): add the widget component-generation spec (DRAFT)

The collection phase closed at 84 verified cards, so porting needs a decision procedure before consumer work starts. The spec carries the agreed five phases (demand inventory, web library extraction, Emacs ports, waybar audio pilot, Level-2 generator go/no-go) and records the baked architecture decisions. I left the web library's packaging shape as the one open decision, tracked as a VERIFY in todo.org. The gallery is the prototype evidence, with the R-series history as the iteration record.
---
 todo.org | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

(limited to 'todo.org')

diff --git a/todo.org b/todo.org
index 2066cf2..51a0da6 100644
--- a/todo.org
+++ b/todo.org
@@ -24,7 +24,11 @@ The vocabulary is open — topic tags are coined as needed — so these are conv
 ** 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).
 
-Next: write the component-generation spec (spec-create, fresh session). Outline agreed with Craig 2026-07-12: Phase 1 demand inventory (widget-to-target matrix from real consumers — waybar panels, emacs games, React UI; port to demand, not all 84). Phase 2 web library extraction (lift card builders into parameterized widgets.js; gallery becomes the demo of the library; CDP behavioral tests carry over). Phase 3 emacs ports (extend gallery-widget.el pattern + gallery-tokens.el; per-widget ERT + rsvg-convert side-by-side visual harness; keymap/click-region interaction per widget). Phase 4 waybar pilot (one real panel — audio — onto tokens-waybar.css + banked composition idioms; lives in ~/.dotfiles, archsetup owns end-to-end; manual-testing checklist). Phase 5 generator decision point (revisit Level-2 codegen after ~5 hand ports, per the recorded architecture decision). Baked decisions: SVG-first substrate, single token source, per-target interaction layers, demand-driven porting, gallery-as-spec. Banked variant/composition ledger lives in the 2026-07-11/12 session archive.
+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.
+*** 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.
+*** VERIFY Web library packaging — classic-script widgets.js + GW namespace?
+The spec's one open decision (owner Craig, by spec-review): =widgets.js= as a classic script exposing one namespace object (working name =GW=), loaded by the gallery via a relative =<script src>= so =file://= keeps working with zero build tooling; shared helpers (svgEl/polar/vuDb, scale tables) move inside it; framework wrappers stay vNext, demand-gated. Approve the shape or name an alternative.
 ** 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=.
@@ -78,6 +82,9 @@ Deferred from the [[file:docs/specs/2026-07-11-net-doctor-expansion-spec.org][ne
 ** TODO [#D] Bt doctor vNext :feature:dotfiles:bluetooth:
 Deferred from the [[file:docs/specs/2026-07-11-bt-doctor-expansion-spec.org][bt doctor expansion spec]] (IMPLEMENTED, v1 shipped): the stale-bond re-pair-offer signature (v1 keeps re-pair strictly user-initiated; the signature must be designed and validated before the doctor ever offers it); a connection-parameter/coexistence hint tail for a "keeps dropping" verdict; the bt-audio-profile expansion beyond the current a2dp repair (codec fallback, default-sink, absolute-volume) — wants coordination with the audio doctor so the two panels don't claim the same A2DP/HFP diagnosis with divergent verdicts.
 
+** TODO [#D] Widget catalogue vNext :feature:design:
+Deferred from the [[file:docs/specs/2026-07-12-component-generation-spec.org][component-generation spec]] (DRAFT): framework wrappers for the web library (React or otherwise — demand-gated, none until a real framework consumer exists); Level-2/3 widget codegen if the spec's Phase 5 decision point says go (a go spawns its own spec); ports beyond the demand matrix as new consumers appear.
+
 ** TODO [#D] Maintenance console vNext :feature:
 Deferred from the [[file:docs/specs/2026-07-07-maintenance-console-spec.org][spec]] (v1 ships determinate remedies only): AI/workflow assistance on read-only metrics (the vLater tier — failed-unit diagnosis, journal-error fix suggestions, OOM investigation); SIGKILL escalation for TERM-survivors on the KILL lever; live streaming meters on evidence rows where a count could be a level.
 
-- 
cgit v1.2.3