1# Visual Companion Guide
2 
3Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
4 
5## When to Use
6 
7Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
8 
9**Use the browser** when the content itself is visual:
10 
11- **UI mockups** — wireframes, layouts, navigation structures, component designs
12- **Architecture diagrams** — system components, data flow, relationship maps
13- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
14- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
15- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
16 
17**Use the terminal** when the content is text or tabular:
18 
19- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
20- **Conceptual A/B/C choices** — picking between approaches described in words
21- **Tradeoff lists** — pros/cons, comparison tables
22- **Technical decisions** — API design, data modeling, architectural approach selection
23- **Clarifying questions** — anything where the answer is words, not a visual preference
24 
25A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
26 
27## How It Works
28 
29The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
30 
31**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, connection status, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
32 
33## Starting a Session
34 
35```bash
36# Start AFTER the user approves the companion. --open auto-opens their browser on
37# the first screen; --project-dir persists mockups and enables same-port restart.
38scripts/start-server.sh --project-dir /path/to/project --open
39 
40# Returns: {"type":"server-started","port":52341,
41#           "url":"http://localhost:52341/?key=ab12…",
42#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
43#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
44```
45 
46Save `screen_dir` and `state_dir` from the response. With `--open`, the browser opens itself when you push the first screen — you don't need to ask the user to open it, but still share the URL as a fallback (headless/remote setups won't auto-open).
47 
48**The URL contains a session key (`?key=…`).** The server rejects any request
49without it, so always give the user the **complete** URL from the `url` field —
50never strip the query string, and never hand out a bare `http://host:port`. The
51key gates HTTP and WebSocket access so a stray browser tab or another machine on
52the network can't read the screens or inject events. After the first load the
53browser remembers the key via a cookie, so reloads and `/files/*` assets work
54without repeating it.
55 
56**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
57 
58**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
59 
60**Launching the server by platform:**
61 
62**Claude Code:**
63```bash
64# Default mode works — the script backgrounds the server itself.
65scripts/start-server.sh --project-dir /path/to/project --open
66```
67 
68On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
69 
70**Codex:**
71```bash
72# Codex reaps background processes. The script auto-detects CODEX_CI and
73# switches to foreground mode. Run it normally — no extra flags needed.
74scripts/start-server.sh --project-dir /path/to/project --open
75```
76 
77**Copilot CLI:**
78```bash
79# Use --foreground and start the server via the bash tool with mode: "async"
80# so the process survives across turns. Capture the returned shellId for
81# read_bash / stop_bash if you need to interact with it later.
82scripts/start-server.sh --project-dir /path/to/project --open --foreground
83```
84 
85**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
86 
87If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
88 
89```bash
90scripts/start-server.sh \
91  --project-dir /path/to/project \
92  --host 0.0.0.0 \
93  --url-host localhost
94```
95 
96Use `--url-host` to control what hostname is printed in the returned URL JSON.
97 
98## The Loop
99 
1001. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
101   - **Required: confirm the server is alive before referring to the URL or pushing a screen.** Check that `$STATE_DIR/server-info` exists and `$STATE_DIR/server-stopped` does not. If it has shut down, restart it with `start-server.sh` using the **same `--project-dir`** — it reuses the same port, so the user's open tab reconnects on its own (it shows a "paused" overlay while the server is down) and you don't need to send a new URL. The server auto-exits after 4 hours idle (configurable with `--idle-timeout-minutes`).
102   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
103   - **Never reuse filenames** — each screen gets a fresh file
104   - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)
105   - Server automatically serves the newest file
106 
1072. **Tell user what to expect and end your turn:**
108   - Remind them of the URL (every step, not just first)
109   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
110   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
111 
1123. **On your next turn** — after the user responds in the terminal:
113   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
114   - Merge with the user's terminal text to get the full picture
115   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
116 
1174. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
118 
1195. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
120 
121   ```html
122   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
123   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
124     <p class="subtitle">Continuing in terminal...</p>
125   </div>
126   ```
127 
128   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
129 
1306. Repeat until done.
131 
132## Writing Content Fragments
133 
134Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, connection status, and all interactive infrastructure).
135 
136**Minimal example:**
137 
138```html
139<h2>Which layout works better?</h2>
140<p class="subtitle">Consider readability and visual hierarchy</p>
141 
142<div class="options">
143  <div class="option" data-choice="a" onclick="toggleSelect(this)">
144    <div class="letter">A</div>
145    <div class="content">
146      <h3>Single Column</h3>
147      <p>Clean, focused reading experience</p>
148    </div>
149  </div>
150  <div class="option" data-choice="b" onclick="toggleSelect(this)">
151    <div class="letter">B</div>
152    <div class="content">
153      <h3>Two Column</h3>
154      <p>Sidebar navigation with main content</p>
155    </div>
156  </div>
157</div>
158```
159 
160That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
161 
162## CSS Classes Available
163 
164The frame template provides these CSS classes for your content:
165 
166### Options (A/B/C choices)
167 
168```html
169<div class="options">
170  <div class="option" data-choice="a" onclick="toggleSelect(this)">
171    <div class="letter">A</div>
172    <div class="content">
173      <h3>Title</h3>
174      <p>Description</p>
175    </div>
176  </div>
177</div>
178```
179 
180**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item's selected styling.
181 
182```html
183<div class="options" data-multiselect>
184  <!-- same option markup — users can select/deselect multiple -->
185</div>
186```
187 
188### Cards (visual designs)
189 
190```html
191<div class="cards">
192  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
193    <div class="card-image"><!-- mockup content --></div>
194    <div class="card-body">
195      <h3>Name</h3>
196      <p>Description</p>
197    </div>
198  </div>
199</div>
200```
201 
202### Mockup container
203 
204```html
205<div class="mockup">
206  <div class="mockup-header">Preview: Dashboard Layout</div>
207  <div class="mockup-body"><!-- your mockup HTML --></div>
208</div>
209```
210 
211### Split view (side-by-side)
212 
213```html
214<div class="split">
215  <div class="mockup"><!-- left --></div>
216  <div class="mockup"><!-- right --></div>
217</div>
218```
219 
220### Pros/Cons
221 
222```html
223<div class="pros-cons">
224  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
225  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
226</div>
227```
228 
229### Mock elements (wireframe building blocks)
230 
231```html
232<div class="mock-nav">Logo | Home | About | Contact</div>
233<div style="display: flex;">
234  <div class="mock-sidebar">Navigation</div>
235  <div class="mock-content">Main content area</div>
236</div>
237<button class="mock-button">Action Button</button>
238<input class="mock-input" placeholder="Input field">
239<div class="placeholder">Placeholder area</div>
240```
241 
242### Typography and sections
243 
244- `h2` — page title
245- `h3` — section heading
246- `.subtitle` — secondary text below title
247- `.section` — content block with bottom margin
248- `.label` — small uppercase label text
249 
250## Browser Events Format
251 
252When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
253 
254```jsonl
255{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
256{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
257{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
258```
259 
260The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
261 
262If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
263 
264## Design Tips
265 
266- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
267- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
268- **Iterate before advancing** — if feedback changes current screen, write a new version
269- **2-4 options max** per screen
270- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
271- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
272 
273## File Naming
274 
275- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
276- Never reuse filenames — each screen must be a new file
277- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
278- Server serves newest file by modification time
279 
280## Cleaning Up
281 
282```bash
283scripts/stop-server.sh $SESSION_DIR
284```
285 
286If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
287 
288## Reference
289 
290- Frame template (CSS reference): `scripts/frame-template.html`
291- Helper script (client-side): `scripts/helper.js`
292