refactor: server-side frame wrapping and helper.js consolidation

Move toggleSelect/send/selectedChoice from frame-template.html inline
script to helper.js so they're auto-injected. Server now detects bare
HTML fragments (no DOCTYPE/html tag) and wraps them in the frame
template automatically. Full documents pass through as before.

Fix dark mode in sendToClaude confirmation (was using hardcoded colors).
Fix test env var bug (BRAINSTORM_SCREEN -> BRAINSTORM_DIR).
Add tests for fragment wrapping, full doc passthrough, and helper.js.

lib/brainstorm-server/frame-template.html

@@ -232,28 +232,5 @@
     </div>
   </div>
 
-  <script>
-    let selectedChoice = null;
-
-    function toggleSelect(el) {
-      const container = el.closest('.options') || el.closest('.cards');
-      if (container) {
-        container.querySelectorAll('.option, .card').forEach(o => o.classList.remove('selected'));
-      }
-      el.classList.add('selected');
-      selectedChoice = el.dataset.choice;
-    }
-
-    function send() {
-      const feedbackEl = document.getElementById('feedback');
-      const feedback = feedbackEl.value.trim();
-      const payload = {};
-      if (selectedChoice) payload.choice = selectedChoice;
-      if (feedback) payload.feedback = feedback;
-      if (Object.keys(payload).length === 0) return;
-      brainstorm.sendToClaude(payload);
-      feedbackEl.value = '';
-    }
-  </script>
 </body>
 </html>

lib/brainstorm-server/helper.js

@@ -7,7 +7,6 @@
     ws = new WebSocket(WS_URL);
 
     ws.onopen = () => {
-      // Send any queued events
       eventQueue.forEach(e => ws.send(JSON.stringify(e)));
       eventQueue = [];
     };
@@ -20,12 +19,11 @@
     };
 
     ws.onclose = () => {
-      // Reconnect after 1 second
       setTimeout(connect, 1000);
     };
   }
 
-  function send(event) {
+  function sendEvent(event) {
     event.timestamp = Date.now();
     if (ws && ws.readyState === WebSocket.OPEN) {
       ws.send(JSON.stringify(event));
@@ -42,9 +40,12 @@
     // 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();
 
-    send({
+    sendEvent({
       type: 'click',
       text: target.textContent.trim(),
       choice: target.dataset.choice || null,
@@ -61,7 +62,7 @@
     const data = {};
     formData.forEach((value, key) => { data[key] = value; });
 
-    send({
+    sendEvent({
       type: 'submit',
       formId: form.id || null,
       formName: form.name || null,
@@ -77,37 +78,60 @@
 
     clearTimeout(inputTimeout);
     inputTimeout = setTimeout(() => {
-      send({
+      sendEvent({
         type: 'input',
         name: target.name || null,
         id: target.id || null,
         value: target.value,
         inputType: target.type || target.tagName.toLowerCase()
       });
-    }, 500); // 500ms debounce
+    }, 500);
   });
 
-  // Send to Claude - triggers server to exit and return all events
+  // Send to Claude - triggers feedback delivery
   function sendToClaude(feedback) {
-    send({
+    sendEvent({
       type: 'send-to-claude',
       feedback: feedback || null
     });
-    // Show confirmation to user
+    // Show themed confirmation page
     document.body.innerHTML = `
-      <div style="display: flex; align-items: center; justify-content: center; height: 100vh; font-family: system-ui, sans-serif;">
-        <div style="text-align: center; color: #666;">
-          <h2 style="color: #333;">✓ Sent to Claude</h2>
+      <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>
     `;
   }
 
-  // Expose for explicit use if needed
+  // Frame UI: selection tracking and feedback send
+  window.selectedChoice = null;
+
+  window.toggleSelect = function(el) {
+    const container = el.closest('.options') || el.closest('.cards');
+    if (container) {
+      container.querySelectorAll('.option, .card').forEach(o => o.classList.remove('selected'));
+    }
+    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: send,
-    choice: (value, metadata = {}) => send({ type: 'choice', value, ...metadata }),
+    send: sendEvent,
+    choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata }),
     sendToClaude: sendToClaude
   };
 

lib/brainstorm-server/index.js

@@ -5,15 +5,32 @@ const chokidar = require('chokidar');
 const fs = require('fs');
 const path = require('path');
 
-// Use provided port or pick a random high port (49152-65535)
 const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
 const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
 
-// Ensure screen directory exists
 if (!fs.existsSync(SCREEN_DIR)) {
   fs.mkdirSync(SCREEN_DIR, { recursive: true });
 }
 
+// Load frame template and helper script once at startup
+const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
+const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
+const helperInjection = `<script>\n${helperScript}\n</script>`;
+
+// Detect whether content is a full HTML document or a bare fragment
+function isFullDocument(html) {
+  const trimmed = html.trimStart().toLowerCase();
+  return trimmed.startsWith('<!doctype') || trimmed.startsWith('<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`
+  );
+}
+
 // Find the newest .html file in the directory by mtime
 function getNewestScreen() {
   const files = fs.readdirSync(SCREEN_DIR)
@@ -28,7 +45,6 @@ function getNewestScreen() {
   return files.length > 0 ? files[0].path : null;
 }
 
-// Default waiting page (served when no screens exist yet)
 const WAITING_PAGE = `<!DOCTYPE html>
 <html>
 <head>
@@ -49,7 +65,6 @@ const app = express();
 const server = http.createServer(app);
 const wss = new WebSocket.Server({ server });
 
-// Track connected browsers for reload notifications
 const clients = new Set();
 
 wss.on('connection', (ws) => {
@@ -57,7 +72,6 @@ wss.on('connection', (ws) => {
   ws.on('close', () => clients.delete(ws));
 
   ws.on('message', (data) => {
-    // User interaction event - write to stdout for Claude
     const event = JSON.parse(data.toString());
     console.log(JSON.stringify({ source: 'user-event', ...event }));
   });
@@ -66,27 +80,30 @@ wss.on('connection', (ws) => {
 // Serve newest screen with helper.js injected
 app.get('/', (req, res) => {
   const screenFile = getNewestScreen();
-  let html = screenFile ? fs.readFileSync(screenFile, 'utf-8') : WAITING_PAGE;
+  let html;
 
-  // Inject helper script before </body>
-  const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
-  const injection = `<script>\n${helperScript}\n</script>`;
+  if (!screenFile) {
+    html = WAITING_PAGE;
+  } else {
+    const raw = fs.readFileSync(screenFile, 'utf-8');
+    html = isFullDocument(raw) ? raw : wrapInFrame(raw);
+  }
 
+  // Inject helper script
   if (html.includes('</body>')) {
-    html = html.replace('</body>', `${injection}\n</body>`);
+    html = html.replace('</body>', `${helperInjection}\n</body>`);
   } else {
-    html += injection;
+    html += helperInjection;
   }
 
   res.type('html').send(html);
 });
 
-// Watch for new or changed .html files in the directory
+// Watch for new or changed .html files
 chokidar.watch(SCREEN_DIR, { ignoreInitial: true })
   .on('add', (filePath) => {
     if (filePath.endsWith('.html')) {
       console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
-      // Notify all browsers to reload
       clients.forEach(ws => {
         if (ws.readyState === WebSocket.OPEN) {
           ws.send(JSON.stringify({ type: 'reload' }));

tests/brainstorm-server/server.test.js

@@ -7,12 +7,11 @@ const assert = require('assert');
 
 const SERVER_PATH = path.join(__dirname, '../../lib/brainstorm-server/index.js');
 const TEST_PORT = 3334;
-const TEST_SCREEN = '/tmp/brainstorm-test/screen.html';
+const TEST_DIR = '/tmp/brainstorm-test';
 
-// Clean up test directory
 function cleanup() {
-  if (fs.existsSync(path.dirname(TEST_SCREEN))) {
-    fs.rmSync(path.dirname(TEST_SCREEN), { recursive: true });
+  if (fs.existsSync(TEST_DIR)) {
+    fs.rmSync(TEST_DIR, { recursive: true });
   }
 }
 
@@ -30,19 +29,23 @@ async function fetch(url) {
   });
 }
 
+function startServer() {
+  return spawn('node', [SERVER_PATH], {
+    env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_DIR: TEST_DIR }
+  });
+}
+
 async function runTests() {
   cleanup();
+  fs.mkdirSync(TEST_DIR, { recursive: true });
 
-  // Start server
-  const server = spawn('node', [SERVER_PATH], {
-    env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_SCREEN: TEST_SCREEN }
-  });
+  const server = startServer();
 
   let stdout = '';
   server.stdout.on('data', (data) => { stdout += data.toString(); });
   server.stderr.on('data', (data) => { console.error('Server stderr:', data.toString()); });
 
-  await sleep(1000); // Wait for server to start
+  await sleep(1000);
 
   try {
     // Test 1: Server starts and outputs JSON
@@ -51,17 +54,17 @@ async function runTests() {
     assert(stdout.includes(TEST_PORT.toString()), 'Should include port');
     console.log('  PASS');
 
-    // Test 2: GET / returns HTML with helper injected
-    console.log('Test 2: Serves HTML with helper injected');
+    // Test 2: GET / returns waiting page with helper injected when no screens exist
+    console.log('Test 2: Serves waiting page with helper injected');
     const res = await fetch(`http://localhost:${TEST_PORT}/`);
     assert.strictEqual(res.status, 200);
-    assert(res.body.includes('brainstorm'), 'Should include brainstorm content');
+    assert(res.body.includes('Waiting for Claude'), 'Should show waiting message');
     assert(res.body.includes('WebSocket'), 'Should have helper.js injected');
     console.log('  PASS');
 
     // Test 3: WebSocket connection and event relay
     console.log('Test 3: WebSocket relays events to stdout');
-    stdout = ''; // Reset stdout capture
+    stdout = '';
     const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
     await new Promise(resolve => ws.on('open', resolve));
 
@@ -84,14 +87,61 @@ async function runTests() {
       if (msg.type === 'reload') gotReload = true;
     });
 
-    // Modify the screen file
-    fs.writeFileSync(TEST_SCREEN, '<html><body>Updated</body></html>');
+    fs.writeFileSync(path.join(TEST_DIR, 'test-screen.html'), '<html><body>Full doc</body></html>');
     await sleep(500);
 
     assert(gotReload, 'Should send reload message on file change');
     ws2.close();
     console.log('  PASS');
 
+    // Test 5: Full HTML document served as-is (not wrapped)
+    console.log('Test 5: Full HTML document served without frame wrapping');
+    const fullDoc = '<!DOCTYPE html>\n<html><head><title>Custom</title></head><body><h1>Custom Page</h1></body></html>';
+    fs.writeFileSync(path.join(TEST_DIR, 'full-doc.html'), fullDoc);
+    await sleep(300);
+
+    const fullRes = await fetch(`http://localhost:${TEST_PORT}/`);
+    assert(fullRes.body.includes('<h1>Custom Page</h1>'), 'Should contain original content');
+    assert(fullRes.body.includes('WebSocket'), 'Should still inject helper.js');
+    // Should NOT have the frame template's feedback footer
+    assert(!fullRes.body.includes('feedback-footer') || fullDoc.includes('feedback-footer'),
+      'Should not wrap full documents in frame template');
+    console.log('  PASS');
+
+    // Test 6: Bare HTML fragment gets wrapped in frame template
+    console.log('Test 6: Content fragment wrapped in frame template');
+    const fragment = '<h2>Pick a layout</h2>\n<p class="subtitle">Choose one</p>\n<div class="options"><div class="option" data-choice="a"><div class="letter">A</div><div class="content"><h3>Simple</h3></div></div></div>';
+    fs.writeFileSync(path.join(TEST_DIR, 'fragment.html'), fragment);
+    await sleep(300);
+
+    const fragRes = await fetch(`http://localhost:${TEST_PORT}/`);
+    // Should have the frame template structure
+    assert(fragRes.body.includes('feedback-footer'), 'Fragment should get feedback footer from frame');
+    assert(fragRes.body.includes('Brainstorm Companion'), 'Fragment should get header from frame');
+    assert(fragRes.body.includes('--bg-primary'), 'Fragment should get theme CSS from frame');
+    // Should have the original content inside
+    assert(fragRes.body.includes('Pick a layout'), 'Fragment content should be present');
+    assert(fragRes.body.includes('data-choice="a"'), 'Fragment content should be intact');
+    // Should have helper.js injected
+    assert(fragRes.body.includes('WebSocket'), 'Fragment should have helper.js injected');
+    console.log('  PASS');
+
+    // Test 7: Helper.js includes toggleSelect and send functions
+    console.log('Test 7: Helper.js provides toggleSelect and send');
+    const helperContent = fs.readFileSync(
+      path.join(__dirname, '../../lib/brainstorm-server/helper.js'), 'utf-8'
+    );
+    assert(helperContent.includes('toggleSelect'), 'helper.js should define toggleSelect');
+    assert(helperContent.includes('send'), 'helper.js should define send function');
+    assert(helperContent.includes('selectedChoice'), 'helper.js should track selectedChoice');
+    console.log('  PASS');
+
+    // Test 8: sendToClaude confirmation uses CSS variables (dark mode support)
+    console.log('Test 8: sendToClaude confirmation respects theming');
+    assert(!helperContent.includes('color: #666'), 'Should not use hardcoded light-mode colors');
+    assert(!helperContent.includes('color: #333'), 'Should not use hardcoded light-mode colors');
+    console.log('  PASS');
+
     console.log('\nAll tests passed!');
 
   } finally {