1# ADR: Live Variant Mode
2
3**Status:** Implemented (v3.1, feature branch `feature/single-skill-consolidation`)
4**Date:** 2026-04-12
5**Author:** Paul Bakaus + Claude
6
7## Context
8
9Impeccable is a design skill for AI coding agents. It teaches AI harnesses (Claude Code, Cursor, Gemini CLI, Codex, etc.) how to produce better frontend design. The skill has 22 commands (bolder, quieter, polish, typeset, etc.) that the agent runs on source code.
10
11The missing piece: there was no way to visually iterate on a live page. The user could ask the agent to "make this bolder," but they had to read the code diff, reload the page, and decide if they liked it. If not, they'd ask again, wait, reload, repeat. Slow and disconnected.
12
13**Goal:** Let the user select an element directly in the browser, pick a design action, and see N real HTML+CSS variants hot-swapped in. Cycle through them visually, accept or discard, repeat. The agent generates the variants; the browser shows them.
14
15## Decision
16
17Build a self-contained live variant mode that ships as part of the impeccable skill (no separate npm install required). The system bridges three parties: the **browser** (where the user picks elements and cycles variants), the **server** (a localhost HTTP server that relays messages), and the **agent** (the AI that generates variants by modifying source files).
18
19### Key architectural decisions
20
21**1. Source modification, not DOM patching.**
22Variants are written to the actual source file, not injected into the browser DOM. This means:
23- Framework state (React, Vue, etc.) is preserved because the framework's own rendering pipeline handles the update via HMR.
24- "Accept" is trivial: the winning variant is already in the source. Just remove the other variants.
25- Variants are real code that the user can inspect in their editor, diff, and commit.
26
27**2. SSE + fetch, not WebSocket.**
28Server-Sent Events (server to browser) + fetch POST (browser to server) instead of WebSocket. This eliminates the `ws` npm dependency entirely. The server is zero-dependency pure Node.js (http, crypto, fs, net, os). This matters because the scripts ship inside the skill directory and run in the user's project without any package installation.
29
30**3. Self-contained skill scripts.**
31All live mode code lives in `skill/scripts/`:
32- `live-server.mjs` — HTTP server (SSE, poll, source file reader)
33- `live-poll.mjs` — CLI client for the agent poll/reply loop
34- `live-wrap.mjs` — CLI helper that finds elements in source and creates variant wrappers
35- `live-browser.js` — Browser script (element picker, action panel, variant cycler, global bar)
36
37When a user installs the skill via `npx skills add pbakaus/impeccable`, they get the live mode without any additional setup. The agent runs the scripts via `node {{scripts_path}}/live-server.mjs`.
38
39**4. HTTP long-poll for the agent, not WebSocket or stdin.**
40The agent communicates with the server via HTTP long-poll (`GET /poll` blocks until a browser event arrives). This works across all AI harnesses because every harness can run a shell command and read its stdout. No harness-specific integration needed.
41
42**5. `display: contents` variant wrapper.**
43Variants are wrapped in a container with `display: contents`, which makes the wrapper invisible to CSS layout. The selected element's relationship with its parent (flex child, grid child, etc.) is preserved. The wrapper carries `data-impeccable-variants` and `data-impeccable-variant-count` attributes that the browser script uses to detect and cycle variants.
44
45**6. No-HMR fallback.**
46For dev servers that don't support HMR (like Bun's static HTML import), the browser fetches the raw source file directly from the live server's `/source` endpoint and injects the variants into the DOM. This works universally, at the cost of losing framework state on that injection.
47
48## Architecture
49
50```
51 ┌─────────────────────────────────────────────────────────────────┐
52 │ BROWSER │
53 │ │
54 │ live-browser.js (injected via <script> tag in source HTML) │
55 │ ├── Element picker (mousemove highlight, click select, │
56 │ │ keyboard nav: arrows=siblings, shift+arrows=parent/child) │
57 │ ├── Action bar (floating pill: action picker, freeform input, │
58 │ │ variant count, go button; morphs to generating/cycling) │
59 │ ├── Global bar (bottom pill: Detect toggle, Pick toggle, Exit) │
60 │ ├── Variant cycler (MutationObserver watches for new │
61 │ │ [data-impeccable-variant] children in DOM) │
62 │ ├── SSE connection (EventSource → /events for server push) │
63 │ ├── fetch POST (→ /events for browser-to-server messages) │
64 │ └── localStorage (session state survives reloads) │
65 │ │
66 └────────────┬──────────────────────────────────┬─────────────────┘
67 │ SSE (server → browser) │ POST (browser → server)
68 │ EventSource /events │ fetch /events
69 ▼ ▼
70 ┌─────────────────────────────────────────────────────────────────┐
71 │ LIVE SERVER │
72 │ │
73 │ live-server.mjs (node, localhost:8400+, zero dependencies) │
74 │ ├── GET /live.js — browser script (token injected) │
75 │ ├── GET /detect.js — anti-pattern overlay (backwards compat)│
76 │ ├── GET /events — SSE stream to browser (server push) │
77 │ ├── POST /events — browser events (generate, accept, etc.)│
78 │ ├── GET /poll — agent long-poll (blocks until event) │
79 │ ├── POST /poll — agent reply (forwarded to browser SSE) │
80 │ ├── GET /source — raw file reader (no-HMR fallback) │
81 │ ├── GET /health — status, port, connected clients │
82 │ └── GET /stop — graceful shutdown │
83 │ │
84 │ State: session token, SSE client set, event queue, poll queue │
85 │ Server file: .impeccable/live/server.json (project root) │
86 │ │
87 └────────────┬──────────────────────────────────┬─────────────────┘
88 │ GET /poll (long-poll) │ POST /poll (reply)
89 │ blocks until browser event │ forwarded to SSE
90 ▼ ▲
91 ┌─────────────────────────────────────────────────────────────────┐
92 │ AGENT │
93 │ │
94 │ Follows skill/reference/live.md │
95 │ 1. Start server: node scripts_path/live-server.mjs & │
96 │ 2. Inject <script> into source HTML (comment-marked) │
97 │ 3. Poll loop: │
98 │ ├── generate → wrap + write variants + reply done │
99 │ ├── accept → present variant code + cleanup + reply done │
100 │ ├── discard → restore original + reply done │
101 │ ├── exit → cleanup script tag + stop server │
102 │ └── timeout → re-poll │
103 │ │
104 │ Tools used per generation: │
105 │ 1. node live-wrap.mjs (find element, create wrapper) │
106 │ 2. Edit (write all variants in single edit) │
107 │ 3. node live-poll.mjs --reply <id> done --file <path> │
108 │ │
109 └─────────────────────────────────────────────────────────────────┘
110```
111
112## Message flow
113
114### Generate variants
115
116```
117User clicks element → picks "Bolder" → clicks Go
118 ↓
119Browser POST /events: {type:"generate", id:"abc", action:"bolder", count:3, element:{...}}
120 ↓
121Server enqueues event
122 ↓
123Agent GET /poll returns: {type:"generate", id:"abc", action:"bolder", count:3, element:{...}}
124 ↓
125Agent runs: node live-wrap.mjs --id abc --count 3 --classes "hero-left"
126 → Finds element in source, wraps with data-impeccable-variants container
127 → Original stays visible (no flash of empty content)
128 ↓
129Agent writes all 3 variants in a single Edit tool call
130 → Each variant is a <div data-impeccable-variant="N"> with full HTML replacement
131 → First variant visible, others display:none
132 ↓
133Agent POST /poll: {id:"abc", type:"done", file:"public/index.html"}
134 ↓
135Server forwards via SSE to browser: {type:"done", file:"public/index.html"}
136 ↓
137Browser checks: variants in DOM? (HMR)
138 YES → MutationObserver detected them → show cycling bar
139 NO → fetch /source?path=public/index.html → parse → inject → show cycling bar
140```
141
142### Accept variant
143
144```
145User clicks Accept on variant 2
146 ↓
147Browser POST /events: {type:"accept", id:"abc", variantId:"2"}
148Browser shows "Applying variant..." spinner
149 ↓
150Agent GET /poll returns: {type:"accept", id:"abc", variantId:"2"}
151Agent reads variant 2 HTML from source, presents to user
152Agent removes variant wrapper, restores clean source
153Agent POST /poll: {id:"abc", type:"done"}
154 ↓
155Browser receives done via SSE → green "Variant applied" confirmation → auto-dismiss
156```
157
158### Discard
159
160```
161User clicks Discard (or presses Escape)
162 ↓
163Browser POST /events: {type:"discard", id:"abc"}
164Browser immediately: restores original element in DOM, hides bar, resets to PICKING
165 ↓
166Agent GET /poll returns: {type:"discard", id:"abc"}
167Agent removes variant wrapper from source, restores original
168Agent POST /poll: {id:"abc", type:"done"}
169```
170
171## Variant wrapper format
172
173In the source file (HTML example):
174
175```html
176<!-- impeccable-variants-start abc12345 -->
177<div data-impeccable-variants="abc12345" data-impeccable-variant-count="3" style="display: contents">
178 <div data-impeccable-variant="original">
179 <!-- original element (visible until first variant arrives) -->
180 </div>
181 <div data-impeccable-variant="1">
182 <!-- variant 1 (visible) -->
183 </div>
184 <div data-impeccable-variant="2" style="display: none">
185 <!-- variant 2 -->
186 </div>
187 <div data-impeccable-variant="3" style="display: none">
188 <!-- variant 3 -->
189 </div>
190</div>
191<!-- impeccable-variants-end abc12345 -->
192```
193
194Comment markers enable deterministic cleanup. `display: contents` on the wrapper preserves flex/grid layout. The `data-impeccable-variant-count` attribute tells the browser how many to expect.
195
196## Browser UI
197
198### Global bar (always visible during live mode)
199
200Compact floating pill at bottom center. Light, translucent, matching the brand aesthetic.
201
202- **Impeccable** brand mark (magenta)
203- **Detect** toggle (eye icon): loads anti-pattern scanner in extension mode, shows overlay count badge
204- **Pick** toggle (crosshair icon): enables/disables element picker (default: on)
205- **Exit** button (x): sends exit event, tears down all UI
206
207When both Detect and Pick are active, detect overlays get `pointer-events: none` so the picker sees through them. The picker's z-index (100001) is above detect overlays (99999).
208
209### Action bar (floating, contextual)
210
211Appears below the selected element. Morphs between states:
212
213- **Configure**: `[Action pill ▾] [freeform input] [×3] [Go →]`
214- **Generating**: `[Action label] [● ● ○] Generating 2 of 3...`
215- **Cycling**: `[←] [● ● ●] 2/3 [→] [✓ Accept] [✕]`
216- **Saving**: `[spinner] Applying variant...`
217- **Confirmed**: `[✓ Variant applied]` (green, auto-dismisses after 1.8s)
218
219## Session persistence
220
221`localStorage` stores:
222- Session state (id, action, count, arrived variants, visible variant)
223- Handled sessions (accepted/discarded session IDs)
224
225This survives page reloads, browser close/reopen, HMR, and accidental refreshes. On page load, `resumeSession()` checks for an active variant wrapper in the DOM + the localStorage state and resumes the correct cycling position.
226
227## Security
228
229- **Session token**: `crypto.randomUUID()`, checked on all mutating endpoints and SSE connections.
230- **Localhost only**: server binds to `127.0.0.1`, not `0.0.0.0`.
231- **Token in server file**: `.impeccable/live/server.json` in project root. Only the user's processes can read it.
232- **Token injected into `/live.js`**: the server prepends `window.__IMPECCABLE_TOKEN__` at serve time.
233- **Path traversal guard**: `/source` endpoint validates the requested path is within `process.cwd()`.
234- **No eval/innerHTML**: all browser UI built with `createElement` and `textContent`.
235
236## Server resilience
237
238- **Debounced exit**: when all SSE clients disconnect, the server waits 8 seconds before signaling exit to the agent. This avoids false exits from HMR reloads and brief network blips.
239- **Stale PID detection**: on startup, the server checks if an existing PID file's process is still running. Dead processes are cleaned up automatically.
240- **Browser server-lost handling**: after 5 failed SSE reconnection attempts, the browser cleans up all UI and shows a "Live server disconnected" toast.
241
242## Performance optimizations
243
244The generation loop was optimized from ~40s to ~15-20s:
245
2461. **`wrap` CLI helper**: one command replaces 3-4 agent tool calls (grep + read + edit). Finds the element by ID/class/tag priority, creates the variant wrapper, returns the file path and insert line.
2472. **Batch variant writes**: all variants in a single file edit instead of one per variant. Saves N-1 tool call round-trips.
2483. **Page URL hint**: browser includes `location.pathname` in the generate event so the agent can map URL to source file directly.
249
250Net effect: 4 tool calls (wrap + edit + read + reply) instead of 8+.
251
252## Test coverage
253
254- **26 wrap tests** (`tests/live-wrap.test.mjs`): unit tests for `buildSearchQueries`, `findElement`, `findClosingLine`, `detectCommentSyntax` + integration tests for full `wrapCli` on HTML and JSX fixtures.
255- **15 server tests** (`tests/live-server.test.mjs`): integration tests that start a real server, test all endpoints, verify browser→agent event flow and agent→browser SSE delivery.
256
257## Known limitations
258
259- **Bun's static HTML import**: Bun's `import from "index.html"` caches at module load time. Source changes require a server restart to appear in the served HTML. The no-HMR fallback (fetch from `/source`) handles this, but it's less seamless than Vite/Next.js where HMR works natively.
260- **Single generation at a time**: only one generate/cycle session can be active. This is by design (the source file can only have one variant wrapper at a time).
261- **Inspection-only accept (v1)**: accepting a variant presents the code to the user and cleans up the scaffolding. Write-back (keeping the variant in place) is planned for v2.
262- **No cancel during generation**: once the agent starts generating, it finishes all variants before the user can interact again.
263
264## Future work
265
266- **Write-back on accept**: instead of restoring the original after accept, keep the accepted variant as the new source.
267- **Detect-to-fix flow**: clicking a detected anti-pattern pre-selects that element and pre-fills the action (e.g., "overused font" pre-fills "typeset").
268- **Background poll for Claude Code**: use `run_in_background: true` to keep the main conversation free during the poll loop.
269- **Streaming variants**: progressive reveal as the agent writes each variant (currently batched for speed).