Visual Companion

Pick ONE input mode per step

A step is either browser-answered or terminal-answered. Do not do both in the same step. Mixing them produces the common failure: agent renders clickable cards, user clicks them, agent is actually blocked on AskUserQuestion -- clicks land in events.jsonl that the agent never reads, and the user sees their clicks "do nothing."

Mode A -- Browser-answered (the cards ARE the question):

Use when the whole point is "pick one of these visual options."

Pre-write checklist (mandatory before every Mode A HTML write):

• Every selectable visual element MUST have a data-choice="<value>" attribute. The client JS ignores elements without it -- styled cards that look clickable but lack data-choice are a silent bug (clicks vanish, user sees nothing happen).
• Do NOT use AskUserQuestion in Mode A. The browser click IS the answer.

1. Clear stale selections first so old clicks do not leak into the new question:

   python3 -c "import urllib.request; req=urllib.request.Request('http://localhost:{port}/events', method='DELETE'); urllib.request.urlopen(req)"

2. Write HTML with [data-choice] elements. The client JS highlights the clicked element and POSTs to /event, which appends a line to .vc-meta/events.jsonl.
3. Tell the user explicitly: > Click one of the cards in the browser to select your choice.
4. Poll events.jsonl until a new line arrives (up to ~60s):

   for i in $(seq 1 300); do
     line=$(tail -n 1 <temp-dir>/.vc-meta/events.jsonl 2>/dev/null)
     [ -n "$line" ] && echo "$line" && break
     sleep 0.2
   done

5. Parse the JSON line and use the choice field as the answer.
6. If the poll times out with no click, fall back to AskUserQuestion and treat the step as Mode B from this point on.

Mode B -- Terminal-answered (browser is visual aid only):

Use when the browser shows a diagram, mockup, or reference and the real answer is a conceptual choice or free text.

1. Write the HTML WITHOUT [data-choice] attributes. Clickable styling with no listener on the agent side is the bug that bit us before -- if you are not going to poll events.jsonl, do not ship clickable targets.
2. Ask the question with AskUserQuestion. The browser is decoration; the button click is the answer.

Terminal-only steps (no browser): No HTML update needed. Optionally push a placeholder page:

<div style="display:flex;align-items:center;justify-content:center;height:100vh;font-family:system-ui;color:#666">
  <p>Continuing in terminal...</p>
</div>

4. HTML Content Guide

Write body content only. The server wraps fragments with DOCTYPE, CSS, and client JS automatically.

A file is treated as a fragment if its first 256 bytes (stripped, case-insensitive) do not start with <!DOCTYPE or <html>. Full HTML documents are served as-is, with client JS injected before </body>.

Layout Patterns

• Options grid: Use .options + .option for comparing 2-3 approaches visually. Mark the recommended option with .recommended.
• Cards: Use .cards + .card for component galleries or feature inventories.
• Mockup: Use .mockup with .mock-nav, .mock-sidebar, .mock-content for wireframes.
• Split view: Use .split for before/after or A/B comparisons.
• Pros/cons: Use .pros-cons for tradeoff visualization.
• Mock UI: .mock-button, .mock-input for wireframe form elements.

Clickable Options with data-choice

Add data-choice attributes to elements that users can click to make selections:

<div class="options">
  <div class="option" data-choice="grid">
    <h3>Grid Layout</h3>
    <p>Content arranged in a responsive grid</p>
  </div>
  <div class="option" data-choice="list">
    <h3>List Layout</h3>
    <p>Content in a vertical list</p>
  </div>
</div>

When a user clicks a [data-choice] element:

• The .selected class is added (blue border + light blue background)
• Previous selections within the same parent are deselected
• A JSON event is appended to .vc-meta/events.jsonl:

  {"type":"choice","choice":"grid","text":"Grid Layout Content arranged in a responsive grid","timestamp":"2026-04-09T14:30:00.000Z"}

events.jsonl Format

Each line is a JSON object appended by the server. The agent reads this file to see what the user clicked:

{"type":"choice","choice":"option-a","text":"Option A","timestamp":"..."}
{"type":"choice","choice":"option-b","text":"Option B","timestamp":"..."}

5. Cleaning Up

The server self-terminates in two cases:

• Idle timeout: No real HTTP activity (page loads, click events, agent updates) for 30 minutes. SSE keepalives and auto-reconnects do NOT reset this timer -- if they did, an open browser tab would keep the server alive forever through any network blip.
• Max lifetime: 8 hours since startup, regardless of activity. Override with --max-lifetime <seconds>; set to 0 to disable.

Note: --owner-pid exists in server.py but is NOT used in the startup template above. In the Bash tool context, $$ resolves to an ephemeral shell PID that dies immediately, making the owner-PID mechanism unreliable. The idle timeout and max lifetime are sufficient.

To stop manually:

kill $(cat <temp-dir>/.vc-meta/server-info.json | python3 -c "import sys,json; print(json.load(sys.stdin)['pid'])") 2>/dev/null

HTML files remain in the temp directory for reference. Optionally copy key mockups to docs/brainstorms/ alongside the spec:

cp <temp-dir>/final-layout.html docs/brainstorms/YYYY-MM-DD-<name>-mockups/