Refactor visual brainstorming: browser displays, terminal commands (#509)

* Refactor visual brainstorming: browser displays, terminal commands

Replaces the blocking TaskOutput/wait-for-feedback.sh pattern with a
non-blocking model where the browser is an interactive display and the
terminal stays available for conversation.

Server changes:
- Write user click events to .events JSONL file (per-screen, cleared on
  new screen push) so Claude reads them on its next turn
- Replace regex-based wrapInFrame with <!-- CONTENT --> placeholder
- Add --foreground flag to start-server.sh for sandbox environments
- Harden startup with nohup/disown and liveness check

UI changes:
- Remove feedback footer (textarea + Send button)
- Add selection indicator bar ("Option X selected — return to terminal")
- Narrow click handler to [data-choice] elements only

Skill changes:
- Rewrite visual-companion.md for non-blocking loop
- Fix visual companion being skipped on Codex (no browser tools needed)
- Make visual companion offer a standalone question (one question rule)

Deletes wait-for-feedback.sh entirely.

* Add visual companion offer to brainstorming checklist for UX topics

The visual companion was a disconnected section at the bottom of SKILL.md
that agents never reached because it wasn't in the mandatory checklist.
Now step 2 evaluates whether the topic involves visual/UX decisions and
offers the companion if so. Non-visual topics (APIs, data models, etc.)
skip the step entirely.

* Add multi-select support to visual companion

Containers with data-multiselect allow toggling multiple selections.
Without it, behavior is unchanged (single-select). Indicator bar shows
count when multiple items are selected.

lib/brainstorm-server/frame-template.html

@@ -8,12 +8,11 @@
      *
      * This template provides a consistent frame with:
      * - OS-aware light/dark theming
-     * - Fixed header and feedback footer
+     * - Fixed header and selection indicator bar
      * - Scrollable main content area
      * - CSS helpers for common UI patterns
      *
-     * CLAUDE: Replace the contents of #claude-content with your content.
-     * Keep the header, main wrapper, and feedback-footer intact.
+     * Content is injected via placeholder comment in #claude-content.
      */
 
     * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -79,37 +78,21 @@
     .main { flex: 1; overflow-y: auto; }
     #claude-content { padding: 2rem; min-height: 100%; }
 
-    .feedback-footer {
+    .indicator-bar {
       background: var(--bg-secondary);
       border-top: 1px solid var(--border);
-      padding: 0.75rem 1.5rem;
+      padding: 0.5rem 1.5rem;
       flex-shrink: 0;
+      text-align: center;
     }
-    .feedback-footer label { display: block; font-size: 0.65rem; color: var(--text-secondary); margin-bottom: 0.4rem; text-transform: uppercase; letter-spacing: 0.05em; }
-    .feedback-row { display: flex; gap: 0.5rem; }
-    .feedback-footer textarea {
-      flex: 1;
-      background: var(--bg-primary);
-      border: 1px solid var(--border);
-      border-radius: 6px;
-      padding: 0.5rem 0.75rem;
-      color: var(--text-primary);
-      font-family: inherit;
-      font-size: 0.85rem;
-      resize: none;
-      height: 36px;
+    .indicator-bar span {
+      font-size: 0.75rem;
+      color: var(--text-secondary);
     }
-    .feedback-footer textarea:focus { outline: none; border-color: var(--accent); }
-    .feedback-footer button {
-      background: var(--accent);
-      color: white;
-      border: none;
-      padding: 0 1rem;
-      border-radius: 6px;
-      font-size: 0.8rem;
-      cursor: pointer;
+    .indicator-bar .selected-text {
+      color: var(--accent);
+      font-weight: 500;
     }
-    .feedback-footer button:hover { background: var(--accent-hover); }
 
     /* ===== TYPOGRAPHY ===== */
     h2 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.5rem; }
@@ -218,18 +201,12 @@
 
   <div class="main">
     <div id="claude-content">
-      <!-- CLAUDE: Replace this content -->
-      <h2>Visual Brainstorming</h2>
-      <p class="subtitle">Claude will show mockups and options here.</p>
+      <!-- CONTENT -->
     </div>
   </div>
 
-  <div class="feedback-footer">
-    <label>Feedback for Claude</label>
-    <div class="feedback-row">
-      <textarea id="feedback" placeholder="Add notes (optional)..." onkeydown="if(event.key==='Enter'&&!event.shiftKey){event.preventDefault();send()}"></textarea>
-      <button onclick="send()">Send</button>
-    </div>
+  <div class="indicator-bar">
+    <span id="indicator-text">Click an option above, then return to the terminal</span>
   </div>
 
 </body>

lib/brainstorm-server/helper.js

@@ -32,107 +32,56 @@
     }
   }
 
-  // Auto-capture clicks on interactive elements
+  // Capture clicks on choice elements
   document.addEventListener('click', (e) => {
-    const target = e.target.closest('button, a, [data-choice], [role="button"], input[type="submit"]');
+    const target = e.target.closest('[data-choice]');
     if (!target) return;
 
-    // Don't capture regular link navigation
-    if (target.tagName === 'A' && !target.dataset.choice) return;
-
-    // Don't capture the Send feedback button (handled by send())
-    if (target.id === 'send-feedback') return;
-
-    e.preventDefault();
-
     sendEvent({
       type: 'click',
       text: target.textContent.trim(),
-      choice: target.dataset.choice || null,
-      id: target.id || null,
-      className: target.className || null
+      choice: target.dataset.choice,
+      id: target.id || null
     });
+
+    // Update indicator bar (defer so toggleSelect runs first)
+    setTimeout(() => {
+      const indicator = document.getElementById('indicator-text');
+      if (!indicator) return;
+      const container = target.closest('.options') || target.closest('.cards');
+      const selected = container ? container.querySelectorAll('.selected') : [];
+      if (selected.length === 0) {
+        indicator.textContent = 'Click an option above, then return to the terminal';
+      } else if (selected.length === 1) {
+        const label = selected[0].querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || selected[0].dataset.choice;
+        indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
+      } else {
+        indicator.innerHTML = '<span class="selected-text">' + selected.length + ' selected</span> — return to terminal to continue';
+      }
+    }, 0);
   });
 
-  // Auto-capture form submissions
-  document.addEventListener('submit', (e) => {
-    e.preventDefault();
-    const form = e.target;
-    const formData = new FormData(form);
-    const data = {};
-    formData.forEach((value, key) => { data[key] = value; });
-
-    sendEvent({
-      type: 'submit',
-      formId: form.id || null,
-      formName: form.name || null,
-      data: data
-    });
-  });
-
-  // Auto-capture input changes (debounced)
-  let inputTimeout = null;
-  document.addEventListener('input', (e) => {
-    const target = e.target;
-    if (!target.matches('input, textarea, select')) return;
-
-    clearTimeout(inputTimeout);
-    inputTimeout = setTimeout(() => {
-      sendEvent({
-        type: 'input',
-        name: target.name || null,
-        id: target.id || null,
-        value: target.value,
-        inputType: target.type || target.tagName.toLowerCase()
-      });
-    }, 500);
-  });
-
-  // Send to Claude - triggers feedback delivery
-  function sendToClaude(feedback) {
-    sendEvent({
-      type: 'send-to-claude',
-      feedback: feedback || null
-    });
-    // Show themed confirmation page
-    document.body.innerHTML = `
-      <div style="display: flex; align-items: center; justify-content: center; height: 100vh; font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif; background: var(--bg-primary, #f5f5f7);">
-        <div style="text-align: center; color: var(--text-secondary, #86868b);">
-          <h2 style="color: var(--text-primary, #1d1d1f); margin-bottom: 0.5rem;">Sent to Claude</h2>
-          <p>Return to the terminal to see Claude's response.</p>
-        </div>
-      </div>
-    `;
-  }
-
-  // Frame UI: selection tracking and feedback send
+  // Frame UI: selection tracking
   window.selectedChoice = null;
 
   window.toggleSelect = function(el) {
     const container = el.closest('.options') || el.closest('.cards');
-    if (container) {
+    const multi = container && container.dataset.multiselect !== undefined;
+    if (container && !multi) {
       container.querySelectorAll('.option, .card').forEach(o => o.classList.remove('selected'));
     }
-    el.classList.add('selected');
+    if (multi) {
+      el.classList.toggle('selected');
+    } else {
+      el.classList.add('selected');
+    }
     window.selectedChoice = el.dataset.choice;
   };
 
-  window.send = function() {
-    const feedbackEl = document.getElementById('feedback');
-    const feedback = feedbackEl ? feedbackEl.value.trim() : '';
-    const payload = {};
-    if (window.selectedChoice) payload.choice = window.selectedChoice;
-    if (feedback) payload.feedback = feedback;
-    if (Object.keys(payload).length === 0) return;
-    sendToClaude(payload);
-    if (feedbackEl) feedbackEl.value = '';
-  };
-
   // Expose API for explicit use
   window.brainstorm = {
     send: sendEvent,
-    choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata }),
-    sendToClaude: sendToClaude
+    choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
   };
 
   connect();

lib/brainstorm-server/index.js

@@ -6,6 +6,8 @@ const fs = require('fs');
 const path = require('path');
 
 const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
+const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
+const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
 const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
 
 if (!fs.existsSync(SCREEN_DIR)) {
@@ -25,10 +27,7 @@ function isFullDocument(html) {
 
 // Wrap a content fragment in the frame template
 function wrapInFrame(content) {
-  return frameTemplate.replace(
-    /(<div id="claude-content">)[\s\S]*?(<\/div>\s*<\/div>\s*<div class="feedback-footer">)/,
-    `$1\n      ${content}\n    $2`
-  );
+  return frameTemplate.replace('<!-- CONTENT -->', content);
 }
 
 // Find the newest .html file in the directory by mtime
@@ -74,6 +73,11 @@ wss.on('connection', (ws) => {
   ws.on('message', (data) => {
     const event = JSON.parse(data.toString());
     console.log(JSON.stringify({ source: 'user-event', ...event }));
+    // Write user events to .events file for Claude to read
+    if (event.choice) {
+      const eventsFile = path.join(SCREEN_DIR, '.events');
+      fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
+    }
   });
 });
 
@@ -103,6 +107,9 @@ app.get('/', (req, res) => {
 chokidar.watch(SCREEN_DIR, { ignoreInitial: true })
   .on('add', (filePath) => {
     if (filePath.endsWith('.html')) {
+      // Clear events from previous screen
+      const eventsFile = path.join(SCREEN_DIR, '.events');
+      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
       console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
       clients.forEach(ws => {
         if (ws.readyState === WebSocket.OPEN) {
@@ -122,11 +129,13 @@ chokidar.watch(SCREEN_DIR, { ignoreInitial: true })
     }
   });
 
-server.listen(PORT, '127.0.0.1', () => {
+server.listen(PORT, HOST, () => {
   console.log(JSON.stringify({
     type: 'server-started',
     port: PORT,
-    url: `http://localhost:${PORT}`,
+    host: HOST,
+    url_host: URL_HOST,
+    url: `http://${URL_HOST}:${PORT}`,
     screen_dir: SCREEN_DIR
   }));
 });

lib/brainstorm-server/start-server.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Start the brainstorm server and output connection info
-# Usage: start-server.sh [--project-dir <path>]
+# Usage: start-server.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
 #
 # Starts server on a random high port, outputs JSON with URL.
 # Each session gets its own directory to avoid conflicts.
@@ -8,17 +8,42 @@
 # Options:
 #   --project-dir <path>  Store session files under <path>/.superpowers/brainstorm/
 #                         instead of /tmp. Files persist after server stops.
+#   --host <bind-host>    Host/interface to bind (default: 127.0.0.1).
+#                         Use 0.0.0.0 in remote/containerized environments.
+#   --url-host <host>     Hostname shown in returned URL JSON.
+#   --foreground          Run server in the current terminal (no backgrounding).
+#   --background          Force background mode (overrides Codex auto-foreground).
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 # Parse arguments
 PROJECT_DIR=""
+FOREGROUND="false"
+FORCE_BACKGROUND="false"
+BIND_HOST="127.0.0.1"
+URL_HOST=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --project-dir)
       PROJECT_DIR="$2"
       shift 2
       ;;
+    --host)
+      BIND_HOST="$2"
+      shift 2
+      ;;
+    --url-host)
+      URL_HOST="$2"
+      shift 2
+      ;;
+    --foreground|--no-daemon)
+      FOREGROUND="true"
+      shift
+      ;;
+    --background|--daemon)
+      FORCE_BACKGROUND="true"
+      shift
+      ;;
     *)
       echo "{\"error\": \"Unknown argument: $1\"}"
       exit 1
@@ -26,6 +51,19 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+if [[ -z "$URL_HOST" ]]; then
+  if [[ "$BIND_HOST" == "127.0.0.1" || "$BIND_HOST" == "localhost" ]]; then
+    URL_HOST="localhost"
+  else
+    URL_HOST="$BIND_HOST"
+  fi
+fi
+
+# Codex environments may reap detached/background processes. Prefer foreground by default.
+if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
+  FOREGROUND="true"
+fi
+
 # Generate unique session directory
 SESSION_ID="$$-$(date +%s)"
 
@@ -48,15 +86,38 @@ if [[ -f "$PID_FILE" ]]; then
   rm -f "$PID_FILE"
 fi
 
-# Start server, capturing output to log file
 cd "$SCRIPT_DIR"
-BRAINSTORM_DIR="$SCREEN_DIR" node index.js > "$LOG_FILE" 2>&1 &
+
+# Foreground mode for environments that reap detached/background processes.
+if [[ "$FOREGROUND" == "true" ]]; then
+  echo "$$" > "$PID_FILE"
+  env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node index.js
+  exit $?
+fi
+
+# Start server, capturing output to log file
+# Use nohup to survive shell exit; disown to remove from job table
+nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node index.js > "$LOG_FILE" 2>&1 &
 SERVER_PID=$!
+disown "$SERVER_PID" 2>/dev/null
 echo "$SERVER_PID" > "$PID_FILE"
 
 # Wait for server-started message (check log file)
 for i in {1..50}; do
   if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then
+    # Verify server is still alive after a short window (catches process reapers)
+    alive="true"
+    for _ in {1..20}; do
+      if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+        alive="false"
+        break
+      fi
+      sleep 0.1
+    done
+    if [[ "$alive" != "true" ]]; then
+      echo "{\"error\": \"Server started but was killed. Retry in a persistent terminal with: $SCRIPT_DIR/start-server.sh${PROJECT_DIR:+ --project-dir $PROJECT_DIR} --host $BIND_HOST --url-host $URL_HOST --foreground\"}"
+      exit 1
+    fi
     grep "server-started" "$LOG_FILE" | head -1
     exit 0
   fi

lib/brainstorm-server/wait-for-feedback.sh

@@ -1,27 +0,0 @@
-#!/bin/bash
-# Wait for user feedback from the brainstorm browser
-# Usage: wait-for-feedback.sh <screen_dir>
-#
-# Blocks until user sends feedback, then outputs the JSON.
-# Write HTML to screen_file BEFORE calling this.
-
-SCREEN_DIR="${1:?Usage: wait-for-feedback.sh <screen_dir>}"
-LOG_FILE="${SCREEN_DIR}/.server.log"
-
-if [[ ! -d "$SCREEN_DIR" ]]; then
-  echo '{"error": "Screen directory not found"}' >&2
-  exit 1
-fi
-
-# Record current position in log file
-LOG_POS=$(wc -l < "$LOG_FILE" 2>/dev/null || echo 0)
-
-# Poll for new lines containing the event
-while true; do
-  RESULT=$(tail -n +$((LOG_POS + 1)) "$LOG_FILE" 2>/dev/null | grep -m 1 "send-to-claude")
-  if [[ -n "$RESULT" ]]; then
-    echo "$RESULT"
-    exit 0
-  fi
-  sleep 0.2
-done