1#!/usr/bin/env node
2/**
3 * Live variant mode server (self-contained, zero dependencies).
4 *
5 * Serves the browser script (/live.js), the detection overlay (/detect.js),
6 * uses Server-Sent Events (SSE) for server→browser push, and HTTP POST for
7 * browser→server events. Agent communicates via HTTP long-poll (/poll).
8 *
9 * Usage:
10 *   node <scripts_path>/live-server.mjs              # start
11 *   node <scripts_path>/live-server.mjs stop         # stop + remove injected live.js tag
12 *   node <scripts_path>/live-server.mjs stop --keep-inject   # stop only
13 *   node <scripts_path>/live-server.mjs --help
14 */
15 
16import http from 'node:http';
17import { randomUUID } from 'node:crypto';
18import { spawn, execFileSync } from 'node:child_process';
19import fs from 'node:fs';
20import path from 'node:path';
21import net from 'node:net';
22import { fileURLToPath } from 'node:url';
23import { parseDesignMd } from './lib/design-parser.mjs';
24import { loadContext } from './context.mjs';
25import {
26  assembleLiveBrowserScript,
27  assertLiveBrowserScriptParts,
28  readLiveBrowserScriptParts,
29  resolveLiveBrowserScriptParts,
30} from './live/browser-script-parts.mjs';
31import { createLiveSessionStore } from './live/session-store.mjs';
32import { validateEvent } from './live/event-validation.mjs';
33import { createManualEditRoutes } from './live/manual-edit-routes.mjs';
34import { LIVE_COMMANDS } from './live/vocabulary.mjs';
35import {
36  getDesignSidecarPath,
37  getLiveDir,
38  getLiveAnnotationsDir,
39  readLiveServerInfo,
40  removeLiveServerInfo,
41  resolveDesignSidecarPath,
42  writeLiveServerInfo,
43} from './lib/impeccable-paths.mjs';
44import { countByPage as countPendingByPage } from './live/manual-edits-buffer.mjs';
45import {
46  createManualApplyController,
47  summarizeManualApplyFailures,
48} from './live/manual-apply.mjs';
49import {
50  applyDeferredSvelteComponentAccepts,
51  removeAllSvelteComponentSessions,
52} from './live/svelte-component.mjs';
53 
54const __dirname = path.dirname(fileURLToPath(import.meta.url));
55// PRODUCT.md / DESIGN.md live wherever context.mjs resolves. The generated
56// DESIGN sidecar is project-local at .impeccable/design.json, with legacy
57// DESIGN.json fallback for existing projects.
58const PROJECT_CONTEXT = loadContext(process.cwd());
59const CONTEXT_DIR = PROJECT_CONTEXT.contextDir;
60const DESIGN_MD_PATH = PROJECT_CONTEXT.designPath
61  ? path.resolve(process.cwd(), PROJECT_CONTEXT.designPath)
62  : null;
63const DEFAULT_POLL_TIMEOUT = 600_000;   // 10 min — agent re-polls on timeout anyway
64const SSE_HEARTBEAT_INTERVAL = 30_000;  // keepalive ping every 30s
65 
66// ---------------------------------------------------------------------------
67// Port detection
68// ---------------------------------------------------------------------------
69 
70async function findOpenPort(start = 8400) {
71  return new Promise((resolve) => {
72    const srv = net.createServer();
73    srv.listen(start, '127.0.0.1', () => {
74      const port = srv.address().port;
75      srv.close(() => resolve(port));
76    });
77    srv.on('error', () => resolve(findOpenPort(start + 1)));
78  });
79}
80 
81// ---------------------------------------------------------------------------
82// Session state
83// ---------------------------------------------------------------------------
84 
85const state = {
86  token: null,
87  port: null,
88  sseClients: new Set(),   // SSE response objects (server→browser push)
89  pendingEvents: [],        // browser events waiting for agent ack ({ event, leaseUntil })
90  pendingPolls: [],         // agent poll callbacks waiting for browser events
91  nextEventSeq: 1,
92  lastAgentPollingBroadcast: null,
93  exitTimer: null,
94  sessionDir: null,         // per-session tmp dir for annotation screenshots
95  sessionStore: null,
96  leaseTimer: null,
97  manualEditActivity: null,
98  nextManualEditSeq: 1,
99  // Deferreds for in-flight chat-routed Apply events. Keyed by event id; each
100  // entry is resolved when the chat agent POSTs an ack carrying the batch
101  // result, or rejected when the hard timeout fires.
102  pendingApplyDeferreds: new Map(),
103  // Updated whenever a /poll long-poll request arrives or is resolved with an
104  // event. Used to detect "a chat agent is likely attached" without requiring
105  // a poll to be parked at the exact moment we dispatch.
106  lastPollAt: 0,
107  timedOutApplyIds: new Map(),
108};
109 
110const CHAT_POLL_FRESHNESS_MS = 60_000;
111const POLL_LEASE_EXPIRY_TIMER_GRACE_MS = 2;
112const DEBUG_MANUAL_EDIT_EVENTS = /^(1|true|yes)$/i.test(process.env.IMPECCABLE_LIVE_DEBUG_EVENTS || '');
113 
114const manualApply = createManualApplyController({
115  pendingEvents: state.pendingEvents,
116  pendingApplyDeferreds: state.pendingApplyDeferreds,
117  timedOutApplyIds: state.timedOutApplyIds,
118  enqueueEvent,
119  acknowledgePendingEvent,
120  flushPendingPolls,
121  recordManualEditActivity,
122  cwd: () => process.cwd(),
123});
124 
125const manualEditRoutes = createManualEditRoutes({
126  getToken: () => state.token,
127  manualApply,
128  recordManualEditActivity,
129  getManualEditStatus,
130  chatAgentLikelyActive,
131  cwd: () => process.cwd(),
132  env: () => process.env,
133});
134 
135function chatAgentLikelyActive() {
136  if (state.pendingPolls.length > 0) return true;
137  if (!state.lastPollAt) return false;
138  return Date.now() - state.lastPollAt < CHAT_POLL_FRESHNESS_MS;
139}
140 
141// Cap per-annotation upload size. A full 1920×1080 PNG is typically <1 MB;
142// cap at 10 MB to guard against runaway writes from a misbehaving client.
143const MAX_ANNOTATION_BYTES = 10 * 1024 * 1024;
144 
145function enqueueEvent(event) {
146  if (!event || (event.id && state.pendingEvents.some((entry) => entry.event?.id === event.id && entry.event?.type === event.type))) return;
147  state.pendingEvents.push({ event, leaseUntil: 0, seq: state.nextEventSeq++ });
148  flushPendingPolls();
149}
150 
151function restorePendingEventsFromStore() {
152  if (!state.sessionStore) return;
153  for (const snapshot of state.sessionStore.listActiveSessions()) {
154    if (snapshot.pendingEvent) enqueueEvent(snapshot.pendingEvent);
155  }
156}
157 
158function findAvailablePendingEvent(now = Date.now()) {
159  for (const entry of state.pendingEvents) {
160    if (entry.leaseUntil && entry.leaseUntil > now) continue;
161    return entry;
162  }
163  return null;
164}
165 
166function leaseEvent(entry, leaseMs) {
167  if (!entry.event?.id) {
168    const idx = state.pendingEvents.indexOf(entry);
169    if (idx !== -1) state.pendingEvents.splice(idx, 1);
170    return entry.event;
171  }
172  entry.leaseUntil = Date.now() + leaseMs;
173  scheduleLeaseFlush();
174  broadcastAgentPollingIfChanged();
175  return entry.event;
176}
177 
178function acknowledgePendingEvent(id) {
179  if (!id) return false;
180  const idx = state.pendingEvents.findIndex((entry) => entry.event?.id === id);
181  if (idx === -1) return false;
182  const acknowledged = state.pendingEvents[idx].event;
183  state.pendingEvents.splice(idx, 1);
184  scheduleLeaseFlush();
185  broadcastAgentPollingIfChanged();
186  return acknowledged;
187}
188 
189function findPendingEventById(id) {
190  if (!id) return null;
191  const entry = state.pendingEvents.find((item) => item.event?.id === id);
192  return entry?.event || null;
193}
194 
195function summarizePendingEventForStatus(entry) {
196  const event = entry.event || {};
197  const summary = {
198    id: event.id,
199    type: event.type,
200    leased: !!(entry.leaseUntil && entry.leaseUntil > Date.now()),
201    leaseUntil: entry.leaseUntil || null,
202  };
203  if (event.type === 'manual_edit_apply') {
204    summary.pageUrl = event.pageUrl || null;
205    summary.chunk = event.chunk || null;
206    summary.repair = event.repair || null;
207    summary.evidencePath = event.evidencePath || null;
208    summary.agentAction = event.agentAction || manualApply.buildAgentAction(event);
209    summary.manualApplySummary = manualApply.summarizeEvent(event, manualApply.getDeferred(event.id)?.batch || event.batch);
210  }
211  return summary;
212}
213 
214function summarizeActiveSessionForClient(snapshot = {}) {
215  return {
216    id: snapshot.id,
217    phase: snapshot.phase,
218    pageUrl: snapshot.pageUrl ?? null,
219    sourceFile: snapshot.sourceFile ?? null,
220    previewFile: snapshot.previewFile ?? null,
221    previewMode: snapshot.previewMode ?? null,
222    expectedVariants: snapshot.expectedVariants ?? 0,
223    arrivedVariants: snapshot.arrivedVariants ?? 0,
224    visibleVariant: snapshot.visibleVariant ?? null,
225    checkpointRevision: snapshot.checkpointRevision ?? 0,
226    paramValues: snapshot.paramValues || {},
227  };
228}
229 
230function activeSessionSummaries() {
231  if (!state.sessionStore) return [];
232  return state.sessionStore.listActiveSessions().map((snapshot) => summarizeActiveSessionForClient(snapshot));
233}
234 
235function cancelQueuedAnonymousExitEvents() {
236  let removed = 0;
237  for (let i = state.pendingEvents.length - 1; i >= 0; i -= 1) {
238    const event = state.pendingEvents[i]?.event;
239    if (event?.type !== 'exit' || event.id) continue;
240    state.pendingEvents.splice(i, 1);
241    removed += 1;
242  }
243  if (removed > 0) {
244    scheduleLeaseFlush();
245    broadcastAgentPollingIfChanged();
246  }
247  return removed;
248}
249 
250function scheduleLeaseFlush() {
251  if (state.leaseTimer) {
252    clearTimeout(state.leaseTimer);
253    state.leaseTimer = null;
254  }
255  const now = Date.now();
256  const nextLeaseUntil = state.pendingEvents
257    .map((entry) => entry.leaseUntil || 0)
258    .filter((leaseUntil) => leaseUntil > now)
259    .sort((a, b) => a - b)[0];
260  if (!nextLeaseUntil) return;
261  state.leaseTimer = setTimeout(() => {
262    state.leaseTimer = null;
263    flushPendingPolls();
264    broadcastAgentPollingIfChanged();
265  }, Math.max(0, nextLeaseUntil - now + POLL_LEASE_EXPIRY_TIMER_GRACE_MS));
266}
267 
268function flushPendingPolls() {
269  let changed = false;
270  while (state.pendingPolls.length > 0) {
271    const entry = findAvailablePendingEvent();
272    if (!entry) {
273      scheduleLeaseFlush();
274      broadcastAgentPollingIfChanged();
275      return;
276    }
277    const poll = state.pendingPolls.shift();
278    poll.resolve(leaseEvent(entry, poll.leaseMs));
279    changed = true;
280  }
281  scheduleLeaseFlush();
282  if (changed) broadcastAgentPollingIfChanged();
283}
284 
285function agentPollingConnected() {
286  const now = Date.now();
287  return state.pendingPolls.length > 0
288    || state.pendingEvents.some((entry) => entry.leaseUntil && entry.leaseUntil > now);
289}
290 
291function broadcastAgentPollingIfChanged() {
292  const connected = agentPollingConnected();
293  if (state.lastAgentPollingBroadcast === connected) return;
294  state.lastAgentPollingBroadcast = connected;
295  broadcast({ type: 'agent_polling', connected });
296}
297 
298/** Push a message to all connected SSE clients. */
299function broadcast(msg) {
300  const data = 'data: ' + JSON.stringify(msg) + '\n\n';
301  for (const res of state.sseClients) {
302    try { res.write(data); } catch { /* client gone */ }
303  }
304}
305 
306function recordManualEditActivity(type, details = {}) {
307  const entry = {
308    seq: state.nextManualEditSeq++,
309    type,
310    ts: new Date().toISOString(),
311    ...details,
312  };
313  state.manualEditActivity = entry;
314  if (DEBUG_MANUAL_EDIT_EVENTS) {
315    try {
316      const filePath = path.join(getLiveDir(process.cwd()), 'manual-edit-events.jsonl');
317      fs.mkdirSync(path.dirname(filePath), { recursive: true });
318      fs.appendFileSync(filePath, JSON.stringify(entry) + '\n');
319    } catch {
320      /* diagnostics are best-effort; never block live mode on observability */
321    }
322  }
323  broadcast(entry);
324  return entry;
325}
326 
327function getManualEditStatus() {
328  try {
329    const { totalCount, perPage } = countPendingByPage(process.cwd());
330    return { totalCount, perPage, lastActivity: state.manualEditActivity };
331  } catch (err) {
332    return {
333      totalCount: null,
334      perPage: {},
335      lastActivity: state.manualEditActivity,
336      error: err.message,
337    };
338  }
339}
340 
341// ---------------------------------------------------------------------------
342// Load scripts
343// ---------------------------------------------------------------------------
344 
345function loadBrowserScripts() {
346  // Detection script: prefer the skill-bundled detector, then fall back to
347  // source/npm package locations for local development and older installs.
348  // This one IS cached — detect.js rarely changes during a session.
349  const detectPaths = [
350    path.join(__dirname, 'detector', 'detect-antipatterns-browser.js'),
351    path.join(__dirname, '..', '..', 'cli', 'engine', 'detect-antipatterns-browser.js'),
352    path.join(__dirname, '..', '..', '..', '..', 'cli', 'engine', 'detect-antipatterns-browser.js'),
353    path.join(process.cwd(), 'node_modules', 'impeccable', 'cli', 'engine', 'detect-antipatterns-browser.js'),
354  ];
355  let detectScript = '';
356  for (const p of detectPaths) {
357    try { detectScript = fs.readFileSync(p, 'utf-8'); break; } catch { /* try next */ }
358  }
359 
360  // Browser script parts: DO NOT cache. Return paths so the /live.js handler
361  // can re-read every part on each request. Editing browser code during
362  // iteration should land on the next tab reload, not require a server restart.
363  const liveScriptParts = resolveLiveBrowserScriptParts(__dirname);
364  try {
365    assertLiveBrowserScriptParts(liveScriptParts);
366  } catch (err) {
367    process.stderr.write('Error: ' + err.message + '\n');
368    process.exit(1);
369  }
370 
371  return { detectScript, liveScriptParts };
372}
373 
374function hasProjectContext() {
375  // PRODUCT.md carries brand voice / anti-references — that's what determines
376  // whether variants are brand-aware. DESIGN.md (visual tokens) is a separate
377  // concern, surfaced by the design panel's own empty state.
378  return !!PROJECT_CONTEXT.hasProduct;
379}
380 
381function statOrNull(filePath) {
382  try { return fs.statSync(filePath); } catch { return null; }
383}
384 
385// HTTP request handler
386// ---------------------------------------------------------------------------
387 
388function createRequestHandler({ detectScript, liveScriptParts }) {
389  return (req, res) => {
390    const url = new URL(req.url, `http://localhost:${state.port}`);
391    res.setHeader('Access-Control-Allow-Origin', '*');
392    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
393    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
394    if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
395 
396    const p = url.pathname;
397 
398    // --- Scripts ---
399    if (p === '/live.js') {
400      // Re-read from disk each request so edits to live-browser.js land on
401      // the next tab reload. No-store headers prevent browser caching across
402      // sessions — during iteration, a cached old script silently breaks
403      // every subsequent session.
404      let parts;
405      try {
406        parts = readLiveBrowserScriptParts(liveScriptParts);
407      } catch (err) {
408        res.writeHead(500, { 'Content-Type': 'text/plain' });
409        res.end('Error reading live browser scripts: ' + err.message);
410        return;
411      }
412      const body = assembleLiveBrowserScript({
413        token: state.token,
414        port: state.port,
415        vocabulary: LIVE_COMMANDS,
416        parts,
417      });
418      res.writeHead(200, {
419        'Content-Type': 'application/javascript',
420        'Cache-Control': 'no-store, no-cache, must-revalidate, max-age=0',
421        'Pragma': 'no-cache',
422      });
423      res.end(body);
424      return;
425    }
426    if (p === '/detect.js' || p === '/') {
427      if (!detectScript) { res.writeHead(404); res.end('Not available'); return; }
428      res.writeHead(200, { 'Content-Type': 'application/javascript' });
429      res.end(detectScript);
430      return;
431    }
432 
433    // --- Vendored modern-screenshot (UMD build) ---
434    // Lazy-loaded by live.js when the user clicks Go; exposes
435    // window.modernScreenshot.domToBlob(...) for capture.
436    if (p === '/modern-screenshot.js') {
437      const vendorPath = path.join(__dirname, 'modern-screenshot.umd.js');
438      try {
439        res.writeHead(200, {
440          'Content-Type': 'application/javascript',
441          'Cache-Control': 'public, max-age=31536000, immutable',
442        });
443        res.end(fs.readFileSync(vendorPath));
444      } catch {
445        res.writeHead(404); res.end('Vendor script not found');
446      }
447      return;
448    }
449 
450    // --- Annotation upload (browser → server, raw PNG body) ---
451    // Client generates the eventId, POSTs the PNG, then POSTs the generate
452    // event with screenshotPath already set. Keeps bytes out of the SSE/poll
453    // bridge and preserves the "one shot from the user's POV" UX.
454    if (p === '/annotation' && req.method === 'POST') {
455      const token = url.searchParams.get('token');
456      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
457      const eventId = url.searchParams.get('eventId');
458      if (!eventId || !/^[A-Za-z0-9_-]{1,64}$/.test(eventId)) {
459        res.writeHead(400, { 'Content-Type': 'application/json' });
460        res.end(JSON.stringify({ error: 'Invalid eventId' }));
461        return;
462      }
463      if ((req.headers['content-type'] || '').toLowerCase() !== 'image/png') {
464        res.writeHead(415, { 'Content-Type': 'application/json' });
465        res.end(JSON.stringify({ error: 'Content-Type must be image/png' }));
466        return;
467      }
468      if (!state.sessionDir) {
469        res.writeHead(500, { 'Content-Type': 'application/json' });
470        res.end(JSON.stringify({ error: 'Session dir unavailable' }));
471        return;
472      }
473      const chunks = [];
474      let total = 0;
475      let aborted = false;
476      req.on('data', (c) => {
477        if (aborted) return;
478        total += c.length;
479        if (total > MAX_ANNOTATION_BYTES) {
480          aborted = true;
481          res.writeHead(413, { 'Content-Type': 'application/json' });
482          res.end(JSON.stringify({ error: 'Payload too large' }));
483          req.destroy();
484          return;
485        }
486        chunks.push(c);
487      });
488      req.on('end', () => {
489        if (aborted) return;
490        const absPath = path.join(state.sessionDir, eventId + '.png');
491        try {
492          fs.writeFileSync(absPath, Buffer.concat(chunks));
493        } catch (err) {
494          res.writeHead(500, { 'Content-Type': 'application/json' });
495          res.end(JSON.stringify({ error: 'Write failed: ' + err.message }));
496          return;
497        }
498        res.writeHead(200, { 'Content-Type': 'application/json' });
499        res.end(JSON.stringify({ ok: true, path: absPath }));
500      });
501      req.on('error', () => {
502        if (!aborted) {
503          res.writeHead(500, { 'Content-Type': 'application/json' });
504          res.end(JSON.stringify({ error: 'Upload failed' }));
505        }
506      });
507      return;
508    }
509 
510    // --- Health ---
511    if (p === '/status') {
512      const token = url.searchParams.get('token');
513      if (token !== state.token) { res.writeHead(401, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'Unauthorized' })); return; }
514      const sessions = activeSessionSummaries();
515      res.writeHead(200, { 'Content-Type': 'application/json' });
516      res.end(JSON.stringify({
517        status: 'ok',
518        port: state.port,
519        connectedClients: state.sseClients.size,
520        pendingEvents: state.pendingEvents.map((entry) => summarizePendingEventForStatus(entry)),
521        agentPolling: agentPollingConnected(),
522        activeSessions: sessions,
523        manualEdits: getManualEditStatus(),
524      }));
525      return;
526    }
527 
528    if (p === '/health') {
529      res.writeHead(200, { 'Content-Type': 'application/json' });
530      res.end(JSON.stringify({
531        status: 'ok', port: state.port, mode: 'variant',
532        hasProjectContext: hasProjectContext(),
533        connectedClients: state.sseClients.size,
534      }));
535      return;
536    }
537 
538    // --- Design system (unified v2 response) + raw ---
539    //   /design-system.json    returns both parsed DESIGN.md and .impeccable/design.json
540    //                          sidecar when present. Panel merges them:
541    //                            { present, parsed, sidecar, hasMd, hasSidecar,
542    //                              mdNewerThanJson, parseError?, sidecarError? }
543    //                          - parsed: output of parseDesignMd (frontmatter
544    //                            + six canonical sections) when DESIGN.md exists.
545    //                          - sidecar: .impeccable/design.json contents when present.
546    //                            Expected shape: schemaVersion 2, carrying
547    //                            extensions + components + narrative.
548    //   /design-system/raw     returns DESIGN.md markdown verbatim
549    if (p === '/design-system.json' || p === '/design-system/raw') {
550      const token = url.searchParams.get('token');
551      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
552 
553      const mdPath = DESIGN_MD_PATH;
554      const jsonPath = resolveDesignSidecarPath(process.cwd(), PROJECT_CONTEXT.designContextDir || CONTEXT_DIR) || getDesignSidecarPath(process.cwd());
555      const mdStat = statOrNull(mdPath);
556      const jsonStat = statOrNull(jsonPath);
557 
558      if (p === '/design-system/raw') {
559        if (!mdStat) { res.writeHead(404); res.end('Not found'); return; }
560        res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' });
561        res.end(fs.readFileSync(mdPath, 'utf-8'));
562        return;
563      }
564 
565      if (!mdStat && !jsonStat) {
566        res.writeHead(404, { 'Content-Type': 'application/json' });
567        res.end(JSON.stringify({ present: false }));
568        return;
569      }
570 
571      const response = {
572        present: true,
573        hasMd: !!mdStat,
574        hasSidecar: !!jsonStat,
575        mdNewerThanJson: !!(mdStat && jsonStat && mdStat.mtimeMs > jsonStat.mtimeMs + 1000),
576      };
577 
578      if (mdStat) {
579        try {
580          response.parsed = parseDesignMd(fs.readFileSync(mdPath, 'utf-8'));
581        } catch (err) {
582          response.parseError = err.message;
583        }
584      }
585 
586      if (jsonStat) {
587        try {
588          response.sidecar = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
589        } catch (err) {
590          response.sidecarError = 'Failed to parse .impeccable/design.json: ' + err.message;
591        }
592      }
593 
594      res.writeHead(200, { 'Content-Type': 'application/json' });
595      res.end(JSON.stringify(response));
596      return;
597    }
598 
599    // --- Source file (no-HMR fallback) ---
600    if (p === '/source') {
601      const token = url.searchParams.get('token');
602      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
603      const filePath = url.searchParams.get('path');
604      if (!filePath || filePath.includes('..')) { res.writeHead(400); res.end('Bad path'); return; }
605      const absPath = path.resolve(process.cwd(), filePath);
606      if (!absPath.startsWith(process.cwd())) { res.writeHead(403); res.end('Forbidden'); return; }
607      let content;
608      try { content = fs.readFileSync(absPath, 'utf-8'); }
609      catch { res.writeHead(404); res.end('File not found'); return; }
610      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
611      res.end(content);
612      return;
613    }
614 
615    // --- SSE: server→browser push (replaces WebSocket) ---
616    if (p === '/events' && req.method === 'GET') {
617      const token = url.searchParams.get('token');
618      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
619      clearTimeout(state.exitTimer);
620      state.exitTimer = null;
621      cancelQueuedAnonymousExitEvents();
622      res.writeHead(200, {
623        'Content-Type': 'text/event-stream',
624        'Cache-Control': 'no-cache',
625        'Connection': 'keep-alive',
626      });
627      res.write('data: ' + JSON.stringify({
628        type: 'connected',
629        hasProjectContext: hasProjectContext(),
630        agentPolling: agentPollingConnected(),
631        activeSessions: activeSessionSummaries(),
632      }) + '\n\n');
633 
634      state.sseClients.add(res);
635 
636      // Keepalive: SSE comment every 30s prevents silent connection drops.
637      const heartbeat = setInterval(() => {
638        try { res.write(': keepalive\n\n'); } catch { clearInterval(heartbeat); }
639      }, SSE_HEARTBEAT_INTERVAL);
640 
641      req.on('close', () => {
642        clearInterval(heartbeat);
643        state.sseClients.delete(res);
644        if (state.sseClients.size === 0) {
645          clearTimeout(state.exitTimer);
646          state.exitTimer = setTimeout(() => {
647            if (state.sseClients.size === 0) enqueueEvent({ type: 'exit' });
648          }, 8000);
649        }
650      });
651      return;
652    }
653 
654    if (manualEditRoutes(req, res, url)) return;
655 
656    // --- Browser→server events (replaces WebSocket messages) ---
657    if (p === '/events' && req.method === 'POST') {
658      let body = '';
659      req.on('data', (c) => { body += c; });
660      req.on('end', () => {
661        let msg;
662        try { msg = JSON.parse(body); } catch {
663          res.writeHead(400, { 'Content-Type': 'application/json' });
664          res.end(JSON.stringify({ error: 'Invalid JSON' }));
665          return;
666        }
667        if (msg.token !== state.token) {
668          res.writeHead(401, { 'Content-Type': 'application/json' });
669          res.end(JSON.stringify({ error: 'Unauthorized' }));
670          return;
671        }
672        // Defense in depth: manual copy edits must use the staged stash/apply
673        // endpoints. The direct Save event path is disabled in the browser.
674        if (msg.type === 'manual_edits') {
675          res.writeHead(400, { 'Content-Type': 'application/json' });
676          res.end(JSON.stringify({ error: 'manual_edits must POST to /manual-edit-stash, not /events' }));
677          return;
678        }
679        if (msg.type === 'manual_edit_apply') {
680          res.writeHead(400, { 'Content-Type': 'application/json' });
681          res.end(JSON.stringify({ error: 'manual_edit_apply is disabled; use /manual-edit-stash then /manual-edit-commit' }));
682          return;
683        }
684        const error = validateEvent(msg);
685        if (error) {
686          res.writeHead(400, { 'Content-Type': 'application/json' });
687          res.end(JSON.stringify({ error }));
688          return;
689        }
690        if (state.sessionStore && msg.id) {
691          try {
692            state.sessionStore.appendEvent(msg);
693          } catch (err) {
694            res.writeHead(500, { 'Content-Type': 'application/json' });
695            res.end(JSON.stringify({ error: 'session_store_append_failed', message: err.message }));
696            return;
697          }
698        }
699        if (msg.type === 'exit') {
700          cleanupSvelteComponentSessionsBeforeExit();
701        }
702        if (msg.type !== 'checkpoint') {
703          enqueueEvent(msg);
704        }
705        res.writeHead(200, { 'Content-Type': 'application/json' });
706        res.end(JSON.stringify({ ok: true }));
707      });
708      return;
709    }
710 
711    // --- Stop ---
712    if (p === '/stop') {
713      const token = url.searchParams.get('token');
714      if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
715      res.writeHead(200, { 'Content-Type': 'text/plain' });
716      res.end('stopping');
717      shutdown();
718      return;
719    }
720 
721    // --- Agent poll ---
722    if (p === '/poll' && req.method === 'GET') {
723      handlePollGet(req, res, url);
724      return;
725    }
726    if (p === '/poll' && req.method === 'POST') {
727      handlePollPost(req, res);
728      return;
729    }
730 
731    res.writeHead(404); res.end('Not found');
732  };
733}
734 
735// ---------------------------------------------------------------------------
736// Agent poll endpoints (unchanged from WS version)
737// ---------------------------------------------------------------------------
738 
739function handlePollGet(req, res, url) {
740  const token = url.searchParams.get('token');
741  if (token !== state.token) {
742    res.writeHead(401, { 'Content-Type': 'application/json' });
743    res.end(JSON.stringify({ error: 'Unauthorized' }));
744    return;
745  }
746  state.lastPollAt = Date.now();
747  const timeout = parseInt(url.searchParams.get('timeout') || DEFAULT_POLL_TIMEOUT, 10);
748  const leaseMs = parseInt(url.searchParams.get('leaseMs') || '30000', 10);
749  const available = findAvailablePendingEvent();
750  if (available) {
751    res.writeHead(200, { 'Content-Type': 'application/json' });
752    res.end(JSON.stringify(leaseEvent(available, leaseMs)));
753    return;
754  }
755  const poll = { resolve, leaseMs };
756  const timer = setTimeout(() => {
757    const idx = state.pendingPolls.indexOf(poll);
758    if (idx !== -1) state.pendingPolls.splice(idx, 1);
759    broadcastAgentPollingIfChanged();
760    res.writeHead(200, { 'Content-Type': 'application/json' });
761    res.end(JSON.stringify({ type: 'timeout' }));
762  }, timeout);
763  function resolve(event) {
764    clearTimeout(timer);
765    state.lastPollAt = Date.now();
766    res.writeHead(200, { 'Content-Type': 'application/json' });
767    res.end(JSON.stringify(event));
768  }
769  state.pendingPolls.push(poll);
770  broadcastAgentPollingIfChanged();
771  scheduleLeaseFlush();
772  req.on('close', () => {
773    clearTimeout(timer);
774    const idx = state.pendingPolls.indexOf(poll);
775    if (idx !== -1) state.pendingPolls.splice(idx, 1);
776    broadcastAgentPollingIfChanged();
777  });
778}
779 
780function sessionFileMetadataFromPollReply(file) {
781  if (!file || typeof file !== 'string') return { file };
782  const normalized = file.split(path.sep).join('/');
783  const base = { file: normalized };
784  if (!normalized.endsWith('/manifest.json') && normalized !== 'manifest.json') return base;
785  if (!normalized.includes('node_modules/.impeccable-live/') && !normalized.includes('src/lib/impeccable/')) return base;
786 
787  let full;
788  try {
789    full = path.resolve(process.cwd(), normalized);
790    const rel = path.relative(process.cwd(), full);
791    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return base;
792  } catch {
793    return base;
794  }
795 
796  try {
797    const manifest = JSON.parse(fs.readFileSync(full, 'utf-8'));
798    if (manifest?.previewMode !== 'svelte-component' || !manifest.sourceFile) return base;
799    return {
800      file: String(manifest.sourceFile).split(path.sep).join('/'),
801      sourceFile: String(manifest.sourceFile).split(path.sep).join('/'),
802      previewFile: normalized,
803      previewMode: 'svelte-component',
804    };
805  } catch {
806    return base;
807  }
808}
809 
810function handlePollPost(req, res) {
811  let body = '';
812  req.on('data', (c) => { body += c; });
813  req.on('end', () => {
814    let msg;
815    try { msg = JSON.parse(body); } catch {
816      res.writeHead(400, { 'Content-Type': 'application/json' });
817      res.end(JSON.stringify({ error: 'Invalid JSON' }));
818      return;
819    }
820    if (msg.token !== state.token) {
821      res.writeHead(401, { 'Content-Type': 'application/json' });
822      res.end(JSON.stringify({ error: 'Unauthorized' }));
823      return;
824    }
825    const pendingApplyDeferred = manualApply.getDeferred(msg.id);
826    if (pendingApplyDeferred) {
827      const validation = manualApply.validateResultMessage(msg, pendingApplyDeferred);
828      if (!validation.ok) {
829        recordManualEditActivity('manual_edit_apply_reply_invalid', {
830          id: msg.id,
831          pageUrl: pendingApplyDeferred.pageUrl,
832          chunk: pendingApplyDeferred.event?.chunk || null,
833          repair: pendingApplyDeferred.event?.repair || null,
834          reason: validation.body?.reason || validation.body?.error || 'invalid_manual_apply_result',
835          status: msg.data?.status || null,
836        });
837        res.writeHead(400, { 'Content-Type': 'application/json' });
838        res.end(JSON.stringify(validation.body));
839        return;
840      }
841      recordManualEditActivity('manual_edit_apply_reply_received', {
842        id: msg.id,
843        pageUrl: pendingApplyDeferred.pageUrl,
844        chunk: pendingApplyDeferred.event?.chunk || null,
845        repair: pendingApplyDeferred.event?.repair || null,
846        status: validation.result.status,
847        appliedCount: validation.result.appliedEntryIds.length,
848        failed: summarizeManualApplyFailures(validation.result.failed),
849        fileCount: validation.result.files.length,
850        noteCount: validation.result.notes.length,
851      });
852      manualApply.resolveDeferred(msg.id, validation.result);
853      acknowledgePendingEvent(msg.id);
854      flushPendingPolls();
855      res.writeHead(200, { 'Content-Type': 'application/json' });
856      res.end(JSON.stringify({ ok: true }));
857      return;
858    }
859    if (manualApply.hasTimedOutId(msg.id)) {
860      const rollback = manualApply.rollbackTimedOutReply(msg);
861      recordManualEditActivity('manual_edit_apply_stale_reply_rejected', {
862        id: msg.id,
863        rolledBackFileCount: rollback.rolledBackFiles?.length || 0,
864        rollbackFailureCount: rollback.rollbackFailures?.length || 0,
865      });
866      res.writeHead(409, { 'Content-Type': 'application/json' });
867      res.end(JSON.stringify({ error: 'stale_manual_edit_apply_reply', ...rollback }));
868      return;
869    }
870    const pendingEventBeforeAck = findPendingEventById(msg.id);
871    if (pendingEventBeforeAck?.type === 'steer' && msg.type === 'steer_done'
872        && !msg.file && !(typeof msg.message === 'string' && msg.message.trim())) {
873      res.writeHead(400, { 'Content-Type': 'application/json' });
874      res.end(JSON.stringify({
875        error: 'steer_done_requires_file_or_message',
876        hint: 'Reply with --file after writing source, or include a message explaining an intentional no-op.',
877      }));
878      return;
879    }
880    const acknowledgedEvent = acknowledgePendingEvent(msg.id);
881    let skipJournalReply = false;
882    let existingSession = null;
883    if (!acknowledgedEvent && state.sessionStore && msg.id) {
884      try {
885        existingSession = state.sessionStore.getSnapshot(msg.id, { includeCompleted: true });
886        if (!existingSession?.updatedAt) existingSession = null;
887        skipJournalReply = existingSession?.phase === 'completed' || existingSession?.phase === 'discarded';
888      } catch { /* fall through and record the reply normally */ }
889    }
890    if (!acknowledgedEvent && !existingSession) {
891      recordManualEditActivity('manual_edit_poll_reply_unknown', {
892        id: msg.id || null,
893        type: msg.type || null,
894      });
895      res.writeHead(msg.id ? 404 : 400, { 'Content-Type': 'application/json' });
896      res.end(JSON.stringify({
897        error: msg.id ? 'unknown_poll_reply_id' : 'missing_poll_reply_id',
898        id: msg.id,
899      }));
900      return;
901    }
902    const replyFileMeta = sessionFileMetadataFromPollReply(msg.file);
903    if (state.sessionStore && msg.id && !skipJournalReply) {
904      try {
905        const eventType = msg.type === 'steer_done'
906          ? 'steer_done'
907          : msg.type === 'discard' || msg.type === 'discarded'
908            ? 'discarded'
909            : msg.type === 'complete'
910              ? 'complete'
911              : msg.type === 'error'
912                ? 'agent_error'
913                : 'agent_done';
914        state.sessionStore.appendEvent({
915          type: eventType,
916          id: msg.id,
917          file: replyFileMeta.file,
918          sourceFile: replyFileMeta.sourceFile,
919          previewFile: replyFileMeta.previewFile,
920          previewMode: replyFileMeta.previewMode,
921          message: msg.message,
922          sourceEventType: acknowledgedEvent?.type,
923          carbonize: msg.data?.carbonize === true,
924        });
925      } catch { /* keep reply path best-effort; browser still needs SSE */ }
926    }
927    flushPendingPolls();
928    // Forward the reply to the browser via SSE
929    broadcast({
930      type: msg.type || 'done',
931      id: msg.id,
932      message: msg.message,
933      file: msg.file,
934      sourceFile: replyFileMeta.sourceFile,
935      previewFile: replyFileMeta.previewFile,
936      previewMode: replyFileMeta.previewMode,
937      data: msg.data,
938    });
939    res.writeHead(200, { 'Content-Type': 'application/json' });
940    res.end(JSON.stringify({ ok: true }));
941  });
942}
943 
944// ---------------------------------------------------------------------------
945// Lifecycle
946// ---------------------------------------------------------------------------
947 
948let httpServer = null;
949 
950function shutdown() {
951  cleanupSvelteComponentSessionsBeforeExit();
952  removeLiveServerInfo(process.cwd());
953  if (state.leaseTimer) clearTimeout(state.leaseTimer);
954  state.leaseTimer = null;
955  if (state.sessionDir) {
956    try { fs.rmSync(state.sessionDir, { recursive: true, force: true }); } catch {}
957  }
958  for (const res of state.sseClients) { try { res.end(); } catch {} }
959  state.sseClients.clear();
960  for (const poll of state.pendingPolls) poll.resolve({ type: 'exit' });
961  state.pendingPolls.length = 0;
962  if (httpServer) httpServer.close();
963  process.exit(0);
964}
965 
966function cleanupSvelteComponentSessionsBeforeExit() {
967  try {
968    removeAllSvelteComponentSessions(process.cwd());
969  } catch (err) {
970    console.warn('[impeccable] Svelte component session cleanup failed:', err.message);
971  }
972}
973 
974function applyLegacyDeferredAcceptsOnStartup() {
975  try {
976    const result = applyDeferredSvelteComponentAccepts(process.cwd());
977    if (result.applied > 0 || result.failed > 0) {
978      console.log('[impeccable] applied legacy deferred Svelte component accepts:', JSON.stringify(result));
979    }
980  } catch (err) {
981    console.warn('[impeccable] legacy deferred Svelte component accept apply failed:', err.message);
982  }
983}
984 
985// ---------------------------------------------------------------------------
986// Main
987// ---------------------------------------------------------------------------
988 
989const args = process.argv.slice(2);
990 
991if (args.includes('--help') || args.includes('-h')) {
992  console.log(`Usage: node live-server.mjs [options]
993 
994Start the live variant mode server (zero dependencies).
995 
996Commands:
997  (default)     Start the server (foreground)
998  stop          Stop the server and remove the injected live.js script tag
999  stop --keep-inject   Stop the server only (leave the script tag in the HTML entry)
1000 
1001Options:
1002  --background  Start detached, print connection JSON to stdout, then exit
1003  --port=PORT   Use a specific port (default: auto-detect starting at 8400)
1004  --keep-inject Only with stop: skip live-inject.mjs --remove
1005  --help        Show this help
1006 
1007Endpoints:
1008  /live.js             Browser script (element picker + variant cycling)
1009  /detect.js           Detection overlay (backwards compatible)
1010  /modern-screenshot.js Vendored modern-screenshot UMD build (lazy-loaded by live.js)
1011  /annotation          POST raw image/png to stage a variant screenshot
1012  /events              SSE stream (server→browser) + POST (browser→server)
1013  /poll                Long-poll for agent CLI
1014  /manual-edit-stash   Stage browser copy edits
1015  /manual-edit-commit  Apply staged browser copy edits
1016  /manual-edit-discard Discard staged browser copy edits
1017  /source              Raw source file reader (no-HMR fallback)
1018  /status              Durable recovery status (token-protected)
1019  /health              Health check`);
1020  process.exit(0);
1021}
1022 
1023if (args.includes('stop')) {
1024  const keepInject = args.includes('--keep-inject');
1025  try {
1026    const { info } = readLiveServerInfo(process.cwd()) || {};
1027    const res = await fetch(`http://localhost:${info.port}/stop?token=${info.token}`);
1028    if (res.ok) console.log(`Stopped live server on port ${info.port}.`);
1029  } catch {
1030    console.log('No running live server found.');
1031  }
1032  if (!keepInject) {
1033    const injectPath = path.join(__dirname, 'live-inject.mjs');
1034    try {
1035      const out = execFileSync(process.execPath, [injectPath, '--remove'], {
1036        encoding: 'utf-8',
1037        cwd: process.cwd(),
1038      });
1039      const line = out.trim().split('\n').filter(Boolean).pop();
1040      if (line) {
1041        try {
1042          const j = JSON.parse(line);
1043          if (j.removed === true) {
1044            console.log(`Removed live script tag from ${j.file}.`);
1045          }
1046        } catch {
1047          /* ignore non-JSON lines */
1048        }
1049      }
1050    } catch (err) {
1051      const detail = err.stderr?.toString?.().trim?.()
1052        || err.stdout?.toString?.().trim?.()
1053        || err.message
1054        || String(err);
1055      console.warn(`Note: could not remove live script tag (${detail.split('\n')[0]})`);
1056    }
1057  }
1058  process.exit(0);
1059}
1060 
1061// --background: spawn a detached child server, wait for it to be ready,
1062// print the connection JSON, then exit.  This keeps the startup command
1063// simple (no shell backgrounding or chained commands).
1064if (args.includes('--background')) {
1065  const childArgs = args.filter(a => a !== '--background');
1066  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...childArgs], {
1067    detached: true,
1068    stdio: 'ignore',
1069    cwd: process.cwd(),
1070  });
1071  child.unref();
1072 
1073  // Poll for the PID file (the child writes it once the HTTP server is listening).
1074  const deadline = Date.now() + 10_000;
1075  while (Date.now() < deadline) {
1076    try {
1077      const { info } = readLiveServerInfo(process.cwd()) || {};
1078      if (info.pid !== process.pid) {
1079        // Output JSON so the agent can read port + token from stdout.
1080        console.log(JSON.stringify(info));
1081        process.exit(0);
1082      }
1083    } catch { /* not ready yet */ }
1084    await new Promise(r => setTimeout(r, 200));
1085  }
1086  console.error('Timed out waiting for live server to start.');
1087  process.exit(1);
1088}
1089 
1090// Check for existing session
1091const existingRecord = readLiveServerInfo(process.cwd());
1092if (existingRecord?.info) {
1093  const existing = existingRecord.info;
1094  try {
1095    process.kill(existing.pid, 0);
1096    console.error(`Live server already running on port ${existing.port} (pid ${existing.pid}).`);
1097    console.error('Stop it first with: node ' + path.basename(fileURLToPath(import.meta.url)) + ' stop');
1098    process.exit(1);
1099  } catch {
1100    try { fs.unlinkSync(existingRecord.path); } catch {}
1101  }
1102}
1103 
1104state.token = randomUUID();
1105state.sessionStore = createLiveSessionStore({ cwd: process.cwd() });
1106manualApply.rollbackTransaction({
1107  reason: 'manual_edit_server_start_recovered_abandoned_transaction',
1108});
1109applyLegacyDeferredAcceptsOnStartup();
1110restorePendingEventsFromStore();
1111manualApply.pruneStaleEvidence();
1112const portArg = args.find(a => a.startsWith('--port='));
1113state.port = portArg ? parseInt(portArg.split('=')[1], 10) : await findOpenPort();
1114// Annotation screenshots live in the project root so the agent's Read tool
1115// doesn't trip a per-file permission prompt. Sessioned by token so concurrent
1116// projects (or quick restarts) don't collide.
1117const annotRoot = getLiveAnnotationsDir(process.cwd());
1118fs.mkdirSync(annotRoot, { recursive: true });
1119state.sessionDir = fs.mkdtempSync(path.join(annotRoot, 'session-'));
1120 
1121const { detectScript, liveScriptParts } = loadBrowserScripts();
1122httpServer = http.createServer(createRequestHandler({ detectScript, liveScriptParts }));
1123 
1124httpServer.listen(state.port, '127.0.0.1', () => {
1125  writeLiveServerInfo(process.cwd(), { pid: process.pid, port: state.port, token: state.token });
1126  const url = `http://localhost:${state.port}`;
1127  console.log(`\nImpeccable live server running on ${url}`);
1128  console.log(`Token: ${state.token}\n`);
1129  console.log(`Script: ${url}/live.js`);
1130  console.log('Inject: managed by live-inject.mjs; Astro source tags use is:inline automatically.');
1131  console.log(`Stop:   node ${path.basename(fileURLToPath(import.meta.url))} stop`);
1132});
1133 
1134process.on('SIGINT', shutdown);
1135process.on('SIGTERM', shutdown);
1136