docs(gallery): document widgets.js consumer API; close extraction phase

README gains a widget-library section covering the GW builder contract, GW_CSS styling, the tick contract for live meters, named style options, and the CDP probes. The stray waybar-redesign bullet moves back to the prototypes list. todo.org Phase 1 closes as a dated entry.

1 files changed, 56 insertions, 3 deletions

diff --git a/docs/prototypes/README.org b/docs/prototypes/README.org
index 674a45d..651636a 100644
--- a/docs/prototypes/README.org
+++ b/docs/prototypes/README.org
@@ -18,7 +18,62 @@ point at.
 - [[file:panel-widget-gallery.html][panel-widget-gallery.html]] — the shared instrument-console
   widget kit (lamps, engraved sections, console keys, needle gauges). The
   living catalogue: every widget here is the visual + behavioral spec for
-  its reusable-component ports.
+  its reusable-component ports. All widgets build from [[file:widgets.js][widgets.js]] (below);
+  the gallery page is the reference consumer.
+- [[file:2026-07-03-waybar-redesign-prototype.html][2026-07-03-waybar-redesign-prototype.html]] — three directions for sprucing up
+  waybar in the dupre instrument-console aesthetic (future work).
+
+* Widget library ([[file:widgets.js][widgets.js]])
+
+The whole kit lives in =widgets.js= — a classic script (no modules, no build
+step) exposing the =GW= namespace with one builder per gallery card. Load it
+with =<script src="widgets.js"></script>= and call builders directly.
+
+** Builder contract
+
+=GW.name(host, opts)= → handle ={el, get, set, ...}=. =host= is an empty
+element the widget renders into. =opts.onChange(value, text)= fires on every
+state change, including the initial paint; =text= is the widget's canonical
+readout string. (Exception: live meters whose original init was silent — they
+paint on the first =set=/=push=.)
+
+** Styling
+
+Widget-internal CSS ships inside =widgets.js= (the =GW_CSS= block, injected
+once as =<style id="gw-css">= at load), so widgets are fully styled on any
+page. The design tokens (=--gold=, =--glow-hi=, the amber family, =--mono=,
+=--pulse-rate=, …) must be defined on =:root= by the consumer — the gallery's
+generated =:root= block is the reference; =tokens.json= is the source.
+
+** Tick contract (live meters)
+
+The page owns the clock and the signal source; builders own rendering state.
+Live meters expose value-driven handles that repaint synchronously and fire
+=onChange=:
+
+- =set(level)= for level meters (peak-hold logic lives in the builder)
+- =push(v)= / =set(samples, current)= for history meters (the builder owns
+  the ring buffer)
+- =set(samples, amp)= for sampled traces (samples normalized)
+
+Widget-owned animation (the R17 scope trace, R31 radar sweep, R44 servo
+chase, R52 pseudo-PC, R53 day clock, R10 TIME page) runs inside the builder,
+gated on =prefers-reduced-motion=.
+
+** Style options
+
+Widgets with named style axes take them as constructor opts backed by a
+=STYLES= table on the builder — e.g. =GW.slideToggle(host, {onStyle:'green',
+thumb:'brass'})= with the axes enumerated in =GW.slideToggle.STYLES=, and
+=handle.setStyle(axis, name)= to restyle a live instance. The gallery's
+option chips are demo rigs driving =setStyle=.
+
+** Verification
+
+=tests/gallery-probes/= drives the full kit headlessly over CDP:
+=probe.mjs= (every card renders + responds, size toggle, drags at zoom) and
+=probe-fams.mjs= (screen-family retinting). Run with =node= against the
+gallery file URL; both must pass before a gallery or widgets.js change lands.
 
 * Design tokens (single source, three targets)
 
@@ -35,5 +90,3 @@ gallery card 10) — it reads gallery-tokens.el and emits the widget as SVG via
 svg.el, so the same look renders inside Emacs. Tests:
 =tests/gallery-tokens/= (generator, unittest) and =tests/gallery-widgets/=
 (renderer, ERT), both in =make test-unit=.
-- [[file:2026-07-03-waybar-redesign-prototype.html][2026-07-03-waybar-redesign-prototype.html]] — three directions for sprucing up
-  waybar in the dupre instrument-console aesthetic (future work).