pbakaus_impeccable/notes/adr-live-variant-mode.md

# ADR: Live Variant Mode

**Status:** Implemented (v3.1, feature branch `feature/single-skill-consolidation`)
**Date:** 2026-04-12
**Author:** Paul Bakaus + Claude

## Context

Impeccable 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.

The 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.

**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.

## Decision

Build 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).

### Key architectural decisions

**1. Source modification, not DOM patching.**
Variants are written to the actual source file, not injected into the browser DOM. This means:
- Framework state (React, Vue, etc.) is preserved because the framework's own rendering pipeline handles the update via HMR.
- "Accept" is trivial: the winning variant is already in the source. Just remove the other variants.
- Variants are real code that the user can inspect in their editor, diff, and commit.

**2. SSE + fetch, not WebSocket.**
Server-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.

**3. Self-contained skill scripts.**
All live mode code lives in `skill/scripts/`:
- `live-server.mjs` — HTTP server (SSE, poll, source file reader)
- `live-poll.mjs` — CLI client for the agent poll/reply loop
- `live-wrap.mjs` — CLI helper that finds elements in source and creates variant wrappers
- `live-browser.js` — Browser script (element picker, action panel, variant cycler, global bar)

When 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`.

**4. HTTP long-poll for the agent, not WebSocket or stdin.**
The 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.

**5. `display: contents` variant wrapper.**
Variants 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.

**6. No-HMR fallback.**
For 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.

## Architecture

```
 ┌─────────────────────────────────────────────────────────────────┐
 │                         BROWSER                                 │
 │                                                                 │
 │  live-browser.js (injected via <script> tag in source HTML)     │
 │  ├── Element picker (mousemove highlight, click select,         │
 │  │   keyboard nav: arrows=siblings, shift+arrows=parent/child)  │
 │  ├── Action bar (floating pill: action picker, freeform input,  │
 │  │   variant count, go button; morphs to generating/cycling)    │
 │  ├── Global bar (bottom pill: Detect toggle, Pick toggle, Exit) │
 │  ├── Variant cycler (MutationObserver watches for new           │
 │  │   [data-impeccable-variant] children in DOM)                 │
 │  ├── SSE connection (EventSource → /events for server push)     │
 │  ├── fetch POST (→ /events for browser-to-server messages)      │
 │  └── localStorage (session state survives reloads)              │
 │                                                                 │
 └────────────┬──────────────────────────────────┬─────────────────┘
              │ SSE (server → browser)           │ POST (browser → server)
              │ EventSource /events              │ fetch /events
              ▼                                  ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │                      LIVE SERVER                                │
 │                                                                 │
 │  live-server.mjs (node, localhost:8400+, zero dependencies)     │
 │  ├── GET  /live.js     — browser script (token injected)        │
 │  ├── GET  /detect.js   — anti-pattern overlay (backwards compat)│
 │  ├── GET  /events      — SSE stream to browser (server push)    │
 │  ├── POST /events      — browser events (generate, accept, etc.)│
 │  ├── GET  /poll        — agent long-poll (blocks until event)   │
 │  ├── POST /poll        — agent reply (forwarded to browser SSE) │
 │  ├── GET  /source      — raw file reader (no-HMR fallback)     │
 │  ├── GET  /health      — status, port, connected clients        │
 │  └── GET  /stop        — graceful shutdown                      │
 │                                                                 │
 │  State: session token, SSE client set, event queue, poll queue  │
 │  Server file: .impeccable/live/server.json (project root)        │
 │                                                                 │
 └────────────┬──────────────────────────────────┬─────────────────┘
              │ GET /poll (long-poll)             │ POST /poll (reply)
              │ blocks until browser event        │ forwarded to SSE
              ▼                                  ▲
 ┌─────────────────────────────────────────────────────────────────┐
 │                         AGENT                                   │
 │                                                                 │
 │  Follows skill/reference/live.md             │
 │  1. Start server: node scripts_path/live-server.mjs &           │
 │  2. Inject <script> into source HTML (comment-marked)           │
 │  3. Poll loop:                                                  │
 │     ├── generate → wrap + write variants + reply done           │
 │     ├── accept  → present variant code + cleanup + reply done   │
 │     ├── discard → restore original + reply done                 │
 │     ├── exit    → cleanup script tag + stop server              │
 │     └── timeout → re-poll                                       │
 │                                                                 │
 │  Tools used per generation:                                     │
 │  1. node live-wrap.mjs (find element, create wrapper)           │
 │  2. Edit (write all variants in single edit)                    │
 │  3. node live-poll.mjs --reply <id> done --file <path>          │
 │                                                                 │
 └─────────────────────────────────────────────────────────────────┘
```

## Message flow

### Generate variants

```
User clicks element → picks "Bolder" → clicks Go
  ↓
Browser POST /events: {type:"generate", id:"abc", action:"bolder", count:3, element:{...}}
  ↓
Server enqueues event
  ↓
Agent GET /poll returns: {type:"generate", id:"abc", action:"bolder", count:3, element:{...}}
  ↓
Agent runs: node live-wrap.mjs --id abc --count 3 --classes "hero-left"
  → Finds element in source, wraps with data-impeccable-variants container
  → Original stays visible (no flash of empty content)
  ↓
Agent writes all 3 variants in a single Edit tool call
  → Each variant is a <div data-impeccable-variant="N"> with full HTML replacement
  → First variant visible, others display:none
  ↓
Agent POST /poll: {id:"abc", type:"done", file:"public/index.html"}
  ↓
Server forwards via SSE to browser: {type:"done", file:"public/index.html"}
  ↓
Browser checks: variants in DOM? (HMR)
  YES → MutationObserver detected them → show cycling bar
  NO  → fetch /source?path=public/index.html → parse → inject → show cycling bar
```

### Accept variant

```
User clicks Accept on variant 2
  ↓
Browser POST /events: {type:"accept", id:"abc", variantId:"2"}
Browser shows "Applying variant..." spinner
  ↓
Agent GET /poll returns: {type:"accept", id:"abc", variantId:"2"}
Agent reads variant 2 HTML from source, presents to user
Agent removes variant wrapper, restores clean source
Agent POST /poll: {id:"abc", type:"done"}
  ↓
Browser receives done via SSE → green "Variant applied" confirmation → auto-dismiss
```

### Discard

```
User clicks Discard (or presses Escape)
  ↓
Browser POST /events: {type:"discard", id:"abc"}
Browser immediately: restores original element in DOM, hides bar, resets to PICKING
  ↓
Agent GET /poll returns: {type:"discard", id:"abc"}
Agent removes variant wrapper from source, restores original
Agent POST /poll: {id:"abc", type:"done"}
```

## Variant wrapper format

In the source file (HTML example):

```html
<!-- impeccable-variants-start abc12345 -->
<div data-impeccable-variants="abc12345" data-impeccable-variant-count="3" style="display: contents">
  <div data-impeccable-variant="original">
    <!-- original element (visible until first variant arrives) -->
  </div>
  <div data-impeccable-variant="1">
    <!-- variant 1 (visible) -->
  </div>
  <div data-impeccable-variant="2" style="display: none">
    <!-- variant 2 -->
  </div>
  <div data-impeccable-variant="3" style="display: none">
    <!-- variant 3 -->
  </div>
</div>
<!-- impeccable-variants-end abc12345 -->
```

Comment 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.

## Browser UI

### Global bar (always visible during live mode)

Compact floating pill at bottom center. Light, translucent, matching the brand aesthetic.

- **Impeccable** brand mark (magenta)
- **Detect** toggle (eye icon): loads anti-pattern scanner in extension mode, shows overlay count badge
- **Pick** toggle (crosshair icon): enables/disables element picker (default: on)
- **Exit** button (x): sends exit event, tears down all UI

When 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).

### Action bar (floating, contextual)

Appears below the selected element. Morphs between states:

- **Configure**: `[Action pill ▾] [freeform input] [×3] [Go →]`
- **Generating**: `[Action label] [● ● ○] Generating 2 of 3...`
- **Cycling**: `[←] [● ● ●] 2/3 [→] [✓ Accept] [✕]`
- **Saving**: `[spinner] Applying variant...`
- **Confirmed**: `[✓ Variant applied]` (green, auto-dismisses after 1.8s)

## Session persistence

`localStorage` stores:
- Session state (id, action, count, arrived variants, visible variant)
- Handled sessions (accepted/discarded session IDs)

This 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.

## Security

- **Session token**: `crypto.randomUUID()`, checked on all mutating endpoints and SSE connections.
- **Localhost only**: server binds to `127.0.0.1`, not `0.0.0.0`.
- **Token in server file**: `.impeccable/live/server.json` in project root. Only the user's processes can read it.
- **Token injected into `/live.js`**: the server prepends `window.__IMPECCABLE_TOKEN__` at serve time.
- **Path traversal guard**: `/source` endpoint validates the requested path is within `process.cwd()`.
- **No eval/innerHTML**: all browser UI built with `createElement` and `textContent`.

## Server resilience

- **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.
- **Stale PID detection**: on startup, the server checks if an existing PID file's process is still running. Dead processes are cleaned up automatically.
- **Browser server-lost handling**: after 5 failed SSE reconnection attempts, the browser cleans up all UI and shows a "Live server disconnected" toast.

## Performance optimizations

The generation loop was optimized from ~40s to ~15-20s:

1. **`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.
2. **Batch variant writes**: all variants in a single file edit instead of one per variant. Saves N-1 tool call round-trips.
3. **Page URL hint**: browser includes `location.pathname` in the generate event so the agent can map URL to source file directly.

Net effect: 4 tool calls (wrap + edit + read + reply) instead of 8+.

## Test coverage

- **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.
- **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.

## Known limitations

- **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.
- **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).
- **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.
- **No cancel during generation**: once the agent starts generating, it finishes all variants before the user can interact again.

## Future work

- **Write-back on accept**: instead of restoring the original after accept, keep the accepted variant as the new source.
- **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").
- **Background poll for Claude Code**: use `run_in_background: true` to keep the main conversation free during the poll loop.
- **Streaming variants**: progressive reveal as the agent writes each variant (currently batched for speed).