@codeyam/codeyam-cli 0.1.0-staging.f777668 → 0.1.0-staging.fff1b4e

package/codeyam-cli/src/webserver/editorProxy.js

@@ -4,10 +4,185 @@ import fs from 'fs';
 import path from 'path';
 import { getProjectRoot } from "../state.js";
 import { createMockStateManager, } from "../utils/editorMockState.js";
+import { computeEditorPorts } from "../utils/editorDevServer.js";
+import { mockStateEventEmitter } from "./mockStateEvents.js";
+/**
+ * Normalize a target URL by stripping trailing slashes for consistency.
+ *
+ * Previously this also replaced `localhost` with `127.0.0.1`, but that broke
+ * forwarding to dev servers that bind to IPv6 only (e.g. Vite 6 on macOS
+ * binds to `[::1]`). The hostname is now left as-is — `resolveLoopbackAddress`
+ * probes the actual target at startup to pick the right address.
+ */
+export function normalizeTargetUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.toString().replace(/\/$/, '');
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Probe a localhost port to determine the correct loopback address.
+ * Dev servers may bind to IPv4 (127.0.0.1), IPv6 (::1), or both.
+ * Returns the first address that accepts a TCP connection.
+ */
+export async function resolveLoopbackAddress(port) {
+    const candidates = ['127.0.0.1', '::1'];
+    for (const host of candidates) {
+        try {
+            const connected = await new Promise((resolve) => {
+                const socket = new net.Socket();
+                socket.setTimeout(1000);
+                socket.once('connect', () => {
+                    socket.destroy();
+                    resolve(true);
+                });
+                socket.once('error', () => {
+                    socket.destroy();
+                    resolve(false);
+                });
+                socket.once('timeout', () => {
+                    socket.destroy();
+                    resolve(false);
+                });
+                socket.connect(port, host);
+            });
+            if (connected) {
+                return host;
+            }
+        }
+        catch {
+            // Try next candidate
+        }
+    }
+    return null;
+}
 // Global key so the proxy survives HMR
 const GLOBAL_KEY = '__codeyam_editor_proxy__';
+// ─── Live Preview Health ─────────────────────────────────────────────
+const PREVIEW_HEALTH_KEY = '__codeyam_preview_health__';
+function getPreviewHealth() {
+    return globalThis[PREVIEW_HEALTH_KEY] ?? null;
+}
+function setPreviewHealth(report) {
+    globalThis[PREVIEW_HEALTH_KEY] = report;
+}
+/**
+ * Get the current live preview health report (read by API endpoint).
+ */
+export function getPreviewHealthReport() {
+    return getPreviewHealth();
+}
+/**
+ * Reset preview health state (called when a new HTML page is served).
+ */
+export function resetPreviewHealth() {
+    setPreviewHealth(null);
+}
+/**
+ * Error-catching script injected into HTML responses.
+ * Uses vanilla JS for maximum compatibility.
+ */
+export const PREVIEW_HEALTH_SCRIPT = `<script data-codeyam-health>
+(function() {
+  var errors = [];
+  var reported = false;
+  function report(type, msg, stack) {
+    errors.push({ type: type, message: msg, stack: stack, timestamp: Date.now() });
+    if (!reported) {
+      reported = true;
+      setTimeout(function() { flush(); }, 500);
+    }
+  }
+  function flush() {
+    fetch('/__codeyam__/preview-health', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ errors: errors, url: location.href })
+    }).catch(function(){});
+    reported = false;
+    errors = [];
+  }
+  window.addEventListener('error', function(e) {
+    report('error', e.message, e.error && e.error.stack);
+  });
+  window.addEventListener('unhandledrejection', function(e) {
+    report('unhandledrejection', String(e.reason), e.reason && e.reason.stack);
+  });
+  var origError = console.error;
+  console.error = function() {
+    report('console.error', Array.prototype.join.call(arguments, ' '));
+    origError.apply(console, arguments);
+  };
+  window.addEventListener('load', function() {
+    setTimeout(function() {
+      var hasContent = document.body && document.body.innerText.trim().length > 0;
+      fetch('/__codeyam__/preview-health', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          loaded: true,
+          hasContent: hasContent,
+          url: location.href,
+          errorCount: errors.length
+        })
+      }).catch(function(){});
+    }, 1000);
+  });
+
+  // Network-idle detection: notify the parent editor when all initial
+  // fetch requests have completed, so it can show the preview after
+  // client-side data (API calls) has arrived — not just when the DOM loads.
+  var inflight = 0;
+  var settled = false;
+  var settleTimer = null;
+  var origFetch = window.fetch;
+  window.fetch = function() {
+    if (!settled) inflight++;
+    return origFetch.apply(this, arguments).then(function(resp) {
+      if (!settled) { inflight--; checkSettle(); }
+      return resp;
+    }, function(err) {
+      if (!settled) { inflight--; checkSettle(); }
+      throw err;
+    });
+  };
+  function checkSettle() {
+    if (inflight <= 0 && !settled) {
+      clearTimeout(settleTimer);
+      // Small delay to allow React to re-render with the fetched data
+      settleTimer = setTimeout(function() {
+        if (inflight <= 0) {
+          settled = true;
+          try {
+            window.parent.postMessage({ type: 'codeyam-preview-ready' }, '*');
+          } catch(e) {}
+        }
+      }, 100);
+    }
+  }
+  // Fallback: if no fetches happen (static page), settle after load
+  window.addEventListener('load', function() {
+    setTimeout(function() { checkSettle(); }, 200);
+  });
+})();
+</script>`;
 const CACHE_TTL_MS = 500;
 let scenarioCache = { data: null, timestamp: 0 };
+// Session config extracted from the active scenario — drives cookie injection
+let sessionConfig = undefined;
+/** Session cookies from the seed adapter (e.g. Supabase auth tokens). */
+let seedSessionCookies = undefined;
+// localStorage config extracted from the active scenario — drives HTML injection
+let localStorageConfig = null;
+// Active scenario ID — used to gate localStorage seeding (only re-seed on switch)
+let activeScenarioId = null;
+// Prototype ID — used to gate a one-time localStorage.clear() when a new project is scaffolded
+let currentPrototypeId = null;
+// Current scenario type — 'application'/'user' for seed-based, 'component' for mock-based
+let currentScenarioType = null;
 // Max body size to buffer for mock matching (10MB)
 const MAX_BODY_SIZE = 10 * 1024 * 1024;
 function getProxyState() {
@@ -61,6 +236,8 @@ function readScenarioData() {
         const active = JSON.parse(fs.readFileSync(activeScenarioPath, 'utf-8'));
         const scenarioId = active.scenarioId;
         if (!scenarioId) {
+            // No active scenario — but may have a prototypeId for localStorage clearing
+            currentPrototypeId = active.prototypeId || null;
             scenarioCache = { data: null, timestamp: now };
             return null;
         }
@@ -71,8 +248,16 @@ function readScenarioData() {
             return null;
         }
         const rawData = JSON.parse(fs.readFileSync(dataFilePath, 'utf-8'));
+        // Extract session config for cookie injection
+        sessionConfig = rawData.session || null;
+        // Extract seed adapter session cookies (e.g. Supabase auth)
+        seedSessionCookies = rawData.sessionCookies || undefined;
+        // Extract localStorage config for HTML injection
+        localStorageConfig = rawData.localStorage || null;
+        activeScenarioId = scenarioId;
         // Type-aware: for seed-based scenarios, only serve externalApis via proxy
         const scenarioType = active.type || rawData.type || null;
+        currentScenarioType = scenarioType;
         let mockData;
         if ((scenarioType === 'application' || scenarioType === 'user') &&
             rawData.seed) {
@@ -128,33 +313,108 @@ function bufferRequestBody(req) {
         });
     });
 }
+/**
+ * Strip IPv6 bracket notation for use with http.request hostname.
+ * URL.hostname returns `[::1]` for IPv6 but http.request needs `::1`.
+ */
+function stripIPv6Brackets(hostname) {
+    if (hostname.startsWith('[') && hostname.endsWith(']')) {
+        return hostname.slice(1, -1);
+    }
+    return hostname;
+}
 /**
  * Forward a buffered request to the target dev server.
  * Unlike the streaming forwardRequest, this replays a buffered body.
  */
 function forwardBufferedRequest(req, res, targetUrl, bodyBuffer) {
     const target = new URL(targetUrl);
+    const hostname = stripIPv6Brackets(target.hostname);
     const headers = { ...req.headers, host: `${target.hostname}:${target.port}` };
+    // Remove accept-encoding so the dev server returns uncompressed responses.
+    // The proxy injects a health script into HTML — this fails on compressed bodies.
+    delete headers['accept-encoding'];
+    // Inject session cookies into the request so the dev server sees auth
+    // on the first request after a scenario switch (before the browser has
+    // stored them from Set-Cookie responses).
+    injectRequestCookies(headers);
     // Update content-length if we have the body buffer
     if (bodyBuffer) {
         headers['content-length'] = String(bodyBuffer.length);
     }
     const options = {
-        hostname: target.hostname,
+        hostname,
         port: target.port,
         path: req.url,
         method: req.method,
         headers,
     };
     const proxyReq = http.request(options, (proxyRes) => {
-        res.writeHead(proxyRes.statusCode || 200, proxyRes.headers);
+        const status = proxyRes.statusCode || 200;
+        if (status >= 300 && status < 400) {
+            console.log(`[editorProxy] Target redirect ${status} for ${req.method} ${req.url} → ${proxyRes.headers.location}`);
+        }
+        if (status >= 400) {
+            console.warn(`[editorProxy] Target returned ${status} for ${req.method} ${req.url}`);
+        }
+        const headers = { ...proxyRes.headers };
+        injectSessionCookie(headers);
+        // Check if response is HTML — if so, buffer and inject health script
+        const contentType = proxyRes.headers['content-type'] || '';
+        if (contentType.includes('text/html')) {
+            resetPreviewHealth();
+            const chunks = [];
+            proxyRes.on('data', (chunk) => chunks.push(chunk));
+            proxyRes.on('end', () => {
+                const body = Buffer.concat(chunks).toString('utf-8');
+                delete headers['content-length'];
+                delete headers['content-encoding'];
+                headers['cache-control'] = 'no-store, must-revalidate';
+                // Serve a friendly error page for 5xx responses instead of
+                // forwarding the raw error HTML (e.g. Next.js "Internal Server Error")
+                if (status >= 500) {
+                    const errorPage = buildErrorPage(status, 'Internal Server Error', body);
+                    res.writeHead(status, headers);
+                    res.end(errorPage);
+                    return;
+                }
+                const lsScript = buildLocalStorageScript(localStorageConfig, activeScenarioId || '', currentPrototypeId);
+                const injected = injectHealthScript(body, lsScript);
+                res.writeHead(status, headers);
+                res.end(injected);
+            });
+            return;
+        }
+        // For 5xx responses without a content type or with text/plain,
+        // serve a friendly error page. These are typically broken dev servers
+        // (e.g. Next.js returning bare "Internal Server Error" with no headers).
+        // JSON API errors are left alone — they're legitimate responses.
+        if (status >= 500 && !contentType.includes('application/json')) {
+            const chunks = [];
+            proxyRes.on('data', (chunk) => chunks.push(chunk));
+            proxyRes.on('end', () => {
+                const body = Buffer.concat(chunks).toString('utf-8');
+                const errorPage = buildErrorPage(status, 'Internal Server Error', body);
+                res.writeHead(status, {
+                    'Content-Type': 'text/html',
+                    'Cache-Control': 'no-store',
+                });
+                res.end(errorPage);
+            });
+            return;
+        }
+        res.writeHead(status, headers);
         proxyRes.pipe(res, { end: true });
     });
     proxyReq.on('error', (err) => {
         console.warn(`[editorProxy] Forward error for ${req.method} ${req.url}: ${err.message}`);
         if (!res.headersSent) {
-            res.writeHead(502, { 'Content-Type': 'text/plain' });
-            res.end('Bad Gateway — dev server unreachable');
+            const errorPage = buildErrorPage(502, 'Dev Server Unreachable', `The proxy could not connect to the dev server. It may be starting up, restarting, or crashed.\n\n${err.message}`);
+            res.writeHead(502, {
+                'Content-Type': 'text/html',
+                'Cache-Control': 'no-store',
+            });
+            res.end(errorPage);
         }
     });
     if (bodyBuffer && bodyBuffer.length > 0) {
@@ -165,38 +425,531 @@ function forwardBufferedRequest(req, res, targetUrl, bodyBuffer) {
     }
 }
 /**
- * Forward an HTTP request to the target dev server (streaming, no body buffering).
+ * Forward an HTTP request to the target dev server.
+ * For HTML responses: buffers body to inject health-check script.
+ * For non-HTML responses: pipes directly (no buffering).
  */
 function forwardRequest(req, res, targetUrl) {
     const target = new URL(targetUrl);
+    const hostname = stripIPv6Brackets(target.hostname);
+    // Build headers, stripping accept-encoding so the dev server returns uncompressed
+    // responses. The proxy injects a health script into HTML — this fails on compressed bodies.
+    const { 'accept-encoding': _ae, ...forwardHeaders } = req.headers;
+    const reqHeaders = {
+        ...forwardHeaders,
+        host: `${target.hostname}:${target.port}`,
+    };
+    // Inject session cookies into the request so the dev server sees auth
+    // on the first request after a scenario switch.
+    injectRequestCookies(reqHeaders);
     const options = {
-        hostname: target.hostname,
+        hostname,
         port: target.port,
         path: req.url,
         method: req.method,
-        headers: { ...req.headers, host: `${target.hostname}:${target.port}` },
+        headers: reqHeaders,
     };
     const proxyReq = http.request(options, (proxyRes) => {
-        res.writeHead(proxyRes.statusCode || 200, proxyRes.headers);
+        const status = proxyRes.statusCode || 200;
+        if (status >= 300 && status < 400) {
+            console.log(`[editorProxy] Target redirect ${status} for ${req.method} ${req.url} → ${proxyRes.headers.location}`);
+        }
+        if (status >= 400) {
+            console.warn(`[editorProxy] Target returned ${status} for ${req.method} ${req.url}`);
+        }
+        const headers = { ...proxyRes.headers };
+        injectSessionCookie(headers);
+        // Check if response is HTML — if so, buffer and inject health script
+        const contentType = proxyRes.headers['content-type'] || '';
+        if (contentType.includes('text/html')) {
+            // Reset health state for new page loads
+            resetPreviewHealth();
+            const chunks = [];
+            proxyRes.on('data', (chunk) => chunks.push(chunk));
+            proxyRes.on('end', () => {
+                const body = Buffer.concat(chunks).toString('utf-8');
+                delete headers['content-length'];
+                delete headers['content-encoding'];
+                headers['cache-control'] = 'no-store, must-revalidate';
+                // Serve a friendly error page for 5xx responses instead of
+                // forwarding the raw error HTML (e.g. Next.js "Internal Server Error")
+                if (status >= 500) {
+                    const errorPage = buildErrorPage(status, 'Internal Server Error', body);
+                    res.writeHead(status, headers);
+                    res.end(errorPage);
+                    return;
+                }
+                const lsScript = buildLocalStorageScript(localStorageConfig, activeScenarioId || '', currentPrototypeId);
+                const injected = injectHealthScript(body, lsScript);
+                res.writeHead(status, headers);
+                res.end(injected);
+            });
+            return;
+        }
+        // For 5xx responses without a content type or with text/plain,
+        // serve a friendly error page. These are typically broken dev servers
+        // (e.g. Next.js returning bare "Internal Server Error" with no headers).
+        // JSON API errors are left alone — they're legitimate responses.
+        if (status >= 500 && !contentType.includes('application/json')) {
+            const chunks = [];
+            proxyRes.on('data', (chunk) => chunks.push(chunk));
+            proxyRes.on('end', () => {
+                const body = Buffer.concat(chunks).toString('utf-8');
+                const errorPage = buildErrorPage(status, 'Internal Server Error', body);
+                res.writeHead(status, {
+                    'Content-Type': 'text/html',
+                    'Cache-Control': 'no-store',
+                });
+                res.end(errorPage);
+            });
+            return;
+        }
+        res.writeHead(status, headers);
         proxyRes.pipe(res, { end: true });
     });
     proxyReq.on('error', (err) => {
         console.warn(`[editorProxy] Forward error for ${req.method} ${req.url}: ${err.message}`);
         if (!res.headersSent) {
-            res.writeHead(502, { 'Content-Type': 'text/plain' });
-            res.end('Bad Gateway — dev server unreachable');
+            const errorPage = buildErrorPage(502, 'Dev Server Unreachable', `The proxy could not connect to the dev server. It may be starting up, restarting, or crashed.\n\n${err.message}`);
+            res.writeHead(502, {
+                'Content-Type': 'text/html',
+                'Cache-Control': 'no-store',
+            });
+            res.end(errorPage);
         }
     });
     req.pipe(proxyReq, { end: true });
 }
+/**
+ * Inject or clear the session-token cookie on proxied responses.
+ * When a scenario has session.cookieValue, sets the cookie to auto-log the user in.
+ * When a scenario has no session field (null), clears any existing session cookie.
+ * When sessionConfig is undefined (no scenario loaded yet), does nothing.
+ */
+function injectSessionCookie(headers) {
+    const cookies = [];
+    // Dev auth cookie (built-in session-token)
+    if (sessionConfig !== undefined) {
+        if (sessionConfig?.cookieValue) {
+            cookies.push(`session-token=${sessionConfig.cookieValue}; Path=/; SameSite=Lax`);
+        }
+        else {
+            cookies.push(`session-token=; Path=/; Max-Age=0`);
+        }
+    }
+    // Seed adapter session cookies (e.g. Supabase auth tokens)
+    if (seedSessionCookies && seedSessionCookies.length > 0) {
+        for (const sc of seedSessionCookies) {
+            const cookiePath = sc.path || '/';
+            const sameSite = sc.sameSite || 'Lax';
+            cookies.push(`${sc.name}=${sc.value}; Path=${cookiePath}; SameSite=${sameSite}`);
+        }
+    }
+    if (cookies.length === 0)
+        return;
+    const existing = headers['set-cookie'];
+    if (existing) {
+        headers['set-cookie'] = [
+            ...(Array.isArray(existing) ? existing : [existing]),
+            ...cookies,
+        ];
+    }
+    else {
+        headers['set-cookie'] = cookies;
+    }
+}
+/**
+ * Get session cookies that should be injected into requests forwarded to the
+ * dev server. Returns an array of {name, value} pairs, or null if no session
+ * cookies are configured.
+ *
+ * This is the counterpart to `injectSessionCookie()` (which adds Set-Cookie
+ * to responses). Without request-side injection, the first request after a
+ * scenario switch has no cookies — the dev server's auth middleware sees no
+ * session and redirects to the login page before the browser ever receives
+ * the Set-Cookie response.
+ */
+export function getRequestCookieInjection() {
+    const cookies = [];
+    if (sessionConfig?.cookieValue) {
+        cookies.push({ name: 'session-token', value: sessionConfig.cookieValue });
+    }
+    if (seedSessionCookies && seedSessionCookies.length > 0) {
+        for (const sc of seedSessionCookies) {
+            cookies.push({ name: sc.name, value: sc.value });
+        }
+    }
+    return cookies.length > 0 ? cookies : null;
+}
+/**
+ * Inject session cookies into the request's Cookie header before forwarding
+ * to the dev server. This ensures the dev server sees auth cookies on the
+ * very first request after a scenario switch (before the browser has stored
+ * them from Set-Cookie responses).
+ */
+function injectRequestCookies(headers) {
+    const injection = getRequestCookieInjection();
+    if (!injection)
+        return;
+    // Parse existing cookies from the request
+    const existing = typeof headers.cookie === 'string' ? headers.cookie : '';
+    const existingPairs = existing
+        ? existing.split(';').map((s) => s.trim())
+        : [];
+    // Build a map of existing cookies for deduplication
+    const cookieMap = new Map();
+    for (const pair of existingPairs) {
+        const eqIdx = pair.indexOf('=');
+        if (eqIdx !== -1) {
+            cookieMap.set(pair.slice(0, eqIdx), pair.slice(eqIdx + 1));
+        }
+    }
+    // Override with injected cookies
+    for (const { name, value } of injection) {
+        cookieMap.set(name, value);
+    }
+    // Reassemble
+    const parts = [];
+    for (const [k, v] of cookieMap) {
+        parts.push(`${k}=${v}`);
+    }
+    if (parts.length > 0) {
+        headers.cookie = parts.join('; ');
+    }
+}
+/**
+ * Get the current session config (for testing).
+ */
+export function getSessionConfig() {
+    return sessionConfig;
+}
+/**
+ * Get the current localStorage config (for testing and script generation).
+ */
+export function getLocalStorageConfig() {
+    return localStorageConfig;
+}
+/**
+ * Get the active scenario ID (for testing and script generation).
+ */
+export function getActiveScenarioId() {
+    return activeScenarioId;
+}
+/**
+ * Get the current prototype ID (for testing).
+ */
+export function getCurrentPrototypeId() {
+    return currentPrototypeId;
+}
+/**
+ * Simple djb2 hash — fast, deterministic, good enough for cache busting.
+ * Not cryptographic — just detects when localStorage config content changes.
+ */
+function simpleHash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+    }
+    return (hash >>> 0).toString(36);
+}
+/**
+ * Build a script tag that seeds localStorage with scenario data on first load.
+ * Gated by scenario ID — only seeds when the scenario changes, preserving
+ * interactive modifications across page reloads / HMR.
+ *
+ * Returns empty string if no localStorage config is provided.
+ */
+export function buildLocalStorageScript(localStorageConfig, scenarioId, prototypeId) {
+    // null/undefined means no localStorage config at all — clean up keys
+    // that were set by a previous scenario so stale filter/sort state
+    // doesn't bleed through and hide data in the new scenario.
+    if (!localStorageConfig || typeof localStorageConfig !== 'object') {
+        // Always clean up previous scenario's keys, gated by scenarioId
+        // so it only runs once per switch (not on every HMR reload).
+        const guardValue = scenarioId ? `clear:${scenarioId}` : '';
+        if (prototypeId) {
+            return `<script data-codeyam-ls>
+(function() {
+  if (localStorage.getItem('__codeyam_proto__') === ${JSON.stringify(prototypeId)}) return;
+  localStorage.clear();
+  localStorage.setItem('__codeyam_proto__', ${JSON.stringify(prototypeId)});
+})();
+</script>`;
+        }
+        if (scenarioId) {
+            // No prototypeId but we do have a scenarioId — clean up keys
+            // from the previous scenario without doing a full clear.
+            return `<script data-codeyam-ls>
+(function() {
+  if (localStorage.getItem('__codeyam_ls_sid__') === ${JSON.stringify(guardValue)}) return;
+  var prev = JSON.parse(localStorage.getItem('__codeyam_ls_keys__') || '[]');
+  for (var i = 0; i < prev.length; i++) localStorage.removeItem(prev[i]);
+  localStorage.removeItem('__codeyam_ls_keys__');
+  localStorage.setItem('__codeyam_ls_sid__', ${JSON.stringify(guardValue)});
+})();
+</script>`;
+        }
+        return '';
+    }
+    // Even an empty object needs a cleanup script — switching from a scenario
+    // with localStorage data to one without must clear the previous keys.
+    const entries = Object.entries(localStorageConfig);
+    const keys = entries.map(([k]) => k);
+    // Build setItem calls — stringify non-string values
+    const setStatements = entries
+        .map(([key, value]) => {
+        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+        return `localStorage.setItem(${JSON.stringify(key)}, ${JSON.stringify(serialized)});`;
+    })
+        .join('\n');
+    // Guard value includes a content hash so re-registering a scenario with
+    // updated data (same ID, different content) busts the cache. Without this,
+    // the browser skips re-seeding because the scenario ID hasn't changed,
+    // causing stale data in the live preview while screenshots show fresh data.
+    const contentHash = simpleHash(JSON.stringify(localStorageConfig));
+    const guardValue = `${scenarioId}:${contentHash}`;
+    return (`<script data-codeyam-ls>
+(function() {
+  if (localStorage.getItem('__codeyam_ls_sid__') === ${JSON.stringify(guardValue)}) return;
+  var prev = JSON.parse(localStorage.getItem('__codeyam_ls_keys__') || '[]');
+  for (var i = 0; i < prev.length; i++) localStorage.removeItem(prev[i]);
+  ${setStatements}
+  localStorage.setItem('__codeyam_ls_keys__', ${JSON.stringify(JSON.stringify(keys))});
+  localStorage.setItem('__codeyam_ls_sid__', ${JSON.stringify(guardValue)});
+})();
+</script>` + buildLocalStorageWatcherScript());
+}
+/**
+ * Build a script that watches for localStorage mutations and notifies the parent
+ * frame via postMessage. Also responds to `codeyam-get-localstorage` requests so
+ * the editor can read the current localStorage state when saving.
+ */
+function buildLocalStorageWatcherScript() {
+    return `<script data-codeyam-ls-watcher>
+(function() {
+  if (window.__codeyam_ls_watcher_installed__) return;
+  window.__codeyam_ls_watcher_installed__ = true;
+
+  var origSet = localStorage.setItem.bind(localStorage);
+  var origRemove = localStorage.removeItem.bind(localStorage);
+  var origClear = localStorage.clear.bind(localStorage);
+  window.__codeyam_orig_setItem__ = origSet;
+  window.__codeyam_orig_removeItem__ = origRemove;
+  window.__codeyam_orig_clear__ = origClear;
+
+  function isInternal(key) {
+    return typeof key === 'string' && key.indexOf('__codeyam_') === 0;
+  }
+
+  localStorage.setItem = function(key, value) {
+    origSet(key, value);
+    if (!isInternal(key) && window.parent !== window) {
+      window.parent.postMessage({ type: 'codeyam-localstorage-changed', action: 'set', key: key }, '*');
+    }
+  };
+
+  localStorage.removeItem = function(key) {
+    origRemove(key);
+    if (!isInternal(key) && window.parent !== window) {
+      window.parent.postMessage({ type: 'codeyam-localstorage-changed', action: 'remove', key: key }, '*');
+    }
+  };
+
+  localStorage.clear = function() {
+    origClear();
+    if (window.parent !== window) {
+      window.parent.postMessage({ type: 'codeyam-localstorage-changed', action: 'clear' }, '*');
+    }
+  };
+
+  window.addEventListener('message', function(event) {
+    if (event.data && event.data.type === 'codeyam-get-localstorage') {
+      var data = {};
+      for (var i = 0; i < localStorage.length; i++) {
+        var k = localStorage.key(i);
+        if (k && !isInternal(k)) {
+          data[k] = localStorage.getItem(k);
+        }
+      }
+      event.source.postMessage({ type: 'codeyam-localstorage-state', data: data }, '*');
+    }
+  });
+})();
+</script>`;
+}
+/**
+ * Inject the health-check script (and optional localStorage script) into an HTML response body.
+ * Inserts before </head> if present, otherwise before </body>, otherwise appends.
+ * When a localStorageScript is provided, it's injected BEFORE the health script
+ * so localStorage is populated before the app loads.
+ */
+export function injectHealthScript(html, localStorageScript) {
+    const scripts = (localStorageScript || '') + PREVIEW_HEALTH_SCRIPT;
+    if (html.includes('</head>')) {
+        return html.replace('</head>', scripts + '</head>');
+    }
+    if (html.includes('</body>')) {
+        return html.replace('</body>', scripts + '</body>');
+    }
+    return html + scripts;
+}
+/**
+ * Escape HTML special characters to prevent XSS when embedding
+ * dev server error output into the error page.
+ */
+export function escapeHtml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Build a self-contained HTML error page for display in the preview iframe.
+ *
+ * - Sends `codeyam-server-error` postMessage to the parent editor on load
+ *   so the editor can auto-restart the dev server.
+ * - Includes a "Retry" button that sends `codeyam-server-error-retry`.
+ * - Does NOT send `codeyam-preview-ready` (so the editor doesn't
+ *   mistake the error page for a successful load).
+ */
+export function buildErrorPage(statusCode, title, detail) {
+    const escapedDetail = escapeHtml(detail);
+    const escapedTitle = escapeHtml(title);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapedTitle}</title>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body {
+  background: #1e1e1e;
+  color: #e0e0e0;
+  font-family: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, sans-serif;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+  padding: 24px;
+}
+.container {
+  max-width: 560px;
+  width: 100%;
+  text-align: center;
+}
+.status-code {
+  font-size: 48px;
+  font-weight: 600;
+  color: #f87171;
+  line-height: 1;
+  margin-bottom: 8px;
+}
+.title {
+  font-size: 18px;
+  font-weight: 500;
+  color: #f87171;
+  margin-bottom: 16px;
+}
+.detail {
+  background: #2a2a2a;
+  border: 1px solid #3a3a3a;
+  border-radius: 6px;
+  padding: 16px;
+  margin-bottom: 20px;
+  max-height: 240px;
+  overflow: auto;
+  text-align: left;
+}
+.detail pre {
+  font-family: 'IBM Plex Mono', monospace;
+  font-size: 12px;
+  color: #b0b0b0;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.message {
+  font-size: 13px;
+  color: #888;
+  margin-bottom: 16px;
+}
+button {
+  background: #005c75;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  padding: 8px 20px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+button:hover { background: #004d63; }
+</style>
+</head>
+<body>
+<div class="container">
+  <div class="status-code">${statusCode}</div>
+  <div class="title">${escapedTitle}</div>
+  <div class="detail"><pre>${escapedDetail}</pre></div>
+  <p class="message">Attempting to restart the dev server...</p>
+  <button onclick="window.parent.postMessage({type:'codeyam-server-error-retry'},'*')">Retry</button>
+</div>
+<script>
+try { window.parent.postMessage({type:'codeyam-server-error',statusCode:${statusCode}},'*'); } catch(e) {}
+</script>
+</body>
+</html>`;
+}
+/**
+ * Handle POST /__codeyam__/preview-health — store health data in globalThis.
+ */
+function handlePreviewHealthPost(req, res) {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => {
+        try {
+            const body = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+            const current = getPreviewHealth() || {
+                errors: [],
+                loaded: false,
+                hasContent: false,
+                url: '',
+                lastUpdated: 0,
+            };
+            if (body.errors && Array.isArray(body.errors)) {
+                current.errors = current.errors.concat(body.errors);
+            }
+            if (body.loaded !== undefined) {
+                current.loaded = body.loaded;
+            }
+            if (body.hasContent !== undefined) {
+                current.hasContent = body.hasContent;
+            }
+            if (body.url) {
+                current.url = body.url;
+            }
+            current.lastUpdated = Date.now();
+            setPreviewHealth(current);
+        }
+        catch {
+            // Ignore malformed JSON
+        }
+        res.writeHead(204);
+        res.end();
+    });
+}
 /**
  * Handle WebSocket upgrade by piping to the target dev server.
  */
 function handleUpgrade(req, socket, head, targetUrl) {
     const target = new URL(targetUrl);
+    const hostname = stripIPv6Brackets(target.hostname);
     const port = parseInt(target.port, 10) || 80;
-    console.log(`[editorProxy] WebSocket upgrade: ${req.url} → ${target.hostname}:${port}`);
-    const proxySocket = net.connect(port, target.hostname, () => {
+    console.log(`[editorProxy] WebSocket upgrade: ${req.url} → ${hostname}:${port}`);
+    const proxySocket = net.connect(port, hostname, () => {
         // Reconstruct the HTTP upgrade request
         const requestLine = `${req.method} ${req.url} HTTP/${req.httpVersion}\r\n`;
         const headers = Object.entries(req.headers)
@@ -258,10 +1011,34 @@ function removeProxyConfig() {
  * Supports all HTTP methods (GET, POST, PUT, DELETE, PATCH) with body buffering.
  */
 export async function startEditorProxy(options) {
-    // Stop existing proxy first
+    // If proxy is already running, reuse it (prevents second tab from killing first tab's proxy)
+    const existing = getProxyState();
+    if (existing) {
+        console.log(`[editorProxy] Proxy already running on port ${existing.port} → ${existing.targetUrl}`);
+        return { port: existing.port };
+    }
+    // Stop any leftover state (shouldn't happen, but defensive)
     await stopEditorProxy();
-    const { targetUrl } = options;
+    let targetUrl = normalizeTargetUrl(options.targetUrl);
     let port = options.port;
+    // When the target is localhost, probe to find the correct loopback address.
+    // Dev servers may bind to IPv4 (127.0.0.1) or IPv6 (::1) — Vite 6 on macOS
+    // binds to ::1 by default. We need to match the actual binding.
+    try {
+        const parsed = new URL(targetUrl);
+        if (parsed.hostname === 'localhost') {
+            const targetPort = parseInt(parsed.port || '80', 10);
+            const resolvedHost = await resolveLoopbackAddress(targetPort);
+            if (resolvedHost) {
+                parsed.hostname = resolvedHost;
+                targetUrl = parsed.toString().replace(/\/$/, '');
+                console.log(`[editorProxy] Resolved localhost to ${resolvedHost} for port ${targetPort}`);
+            }
+        }
+    }
+    catch {
+        // Keep original targetUrl
+    }
     console.log(`[editorProxy] Starting proxy (requested port ${port}, target ${targetUrl})`);
     const mockState = getMockStateManager();
     const server = http.createServer((req, res) => {
@@ -280,6 +1057,11 @@ export async function startEditorProxy(options) {
                 res.end();
                 return;
             }
+            // Intercept preview health reports from the injected script
+            if (method === 'POST' && pathname === '/__codeyam__/preview-health') {
+                handlePreviewHealthPost(req, res);
+                return;
+            }
             // Load scenario data (also feeds MockStateManager)
             readScenarioData();
             // For methods that may carry a body, buffer it first
@@ -311,11 +1093,17 @@ export async function startEditorProxy(options) {
                         'Content-Type': 'application/json',
                         'Access-Control-Allow-Origin': '*',
                         'X-CodeYam-Proxy': 'scenario-data',
+                        'Cache-Control': 'no-store',
                     });
                     res.end(match.body != null ? JSON.stringify(match.body) : '');
                     return;
                 }
                 // No mock match — forward with buffered body
+                if ((currentScenarioType === 'application' ||
+                    currentScenarioType === 'user') &&
+                    pathname.startsWith('/api/')) {
+                    mockStateEventEmitter.emitDataMutationForwarded(method, pathname);
+                }
                 forwardBufferedRequest(req, res, targetUrl, bodyBuffer);
                 return;
             }
@@ -327,6 +1115,7 @@ export async function startEditorProxy(options) {
                     'Content-Type': 'application/json',
                     'Access-Control-Allow-Origin': '*',
                     'X-CodeYam-Proxy': 'scenario-data',
+                    'Cache-Control': 'no-store',
                 });
                 res.end(match.body != null ? JSON.stringify(match.body) : '');
                 return;
@@ -351,7 +1140,10 @@ export async function startEditorProxy(options) {
                     resolve();
                 });
             });
-            port = currentPort;
+            // When port 0 is requested, the OS assigns an ephemeral port
+            const addr = server.address();
+            port =
+                typeof addr === 'object' && addr !== null ? addr.port : currentPort;
             const state = { server, port, targetUrl };
             setProxyState(state);
             // Write proxy-config.json for the preload module
@@ -394,6 +1186,41 @@ export async function stopEditorProxy() {
  */
 export function invalidateScenarioCache() {
     scenarioCache = { data: null, timestamp: 0 };
+    sessionConfig = undefined;
+    seedSessionCookies = undefined;
+    localStorageConfig = null;
+    activeScenarioId = null;
+    currentPrototypeId = null;
+}
+/**
+ * Verify that the proxy can successfully forward a request to the target dev server.
+ * Makes a HEAD request through the proxy and checks that it gets a response (any status).
+ * Returns false if the proxy isn't running or if the request fails entirely.
+ */
+export async function verifyProxyForwarding() {
+    const state = getProxyState();
+    if (!state) {
+        console.warn('[editorProxy] Cannot verify — proxy is not running');
+        return false;
+    }
+    try {
+        const response = await fetch(`http://127.0.0.1:${state.port}/`, {
+            method: 'HEAD',
+            signal: AbortSignal.timeout(5000),
+        });
+        // Any response from the target (even 404) means forwarding works.
+        // Only 502 (our own Bad Gateway) means the target is unreachable.
+        if (response.status === 502) {
+            console.warn(`[editorProxy] Verification failed — proxy returned 502 (target unreachable)`);
+            return false;
+        }
+        console.log(`[editorProxy] Verification passed — proxy forwarding to ${state.targetUrl} (status ${response.status})`);
+        return true;
+    }
+    catch (err) {
+        console.warn(`[editorProxy] Verification failed — could not reach proxy on port ${state.port}`);
+        return false;
+    }
 }
 /**
  * Ensure the proxy is running. If it's not, start it using the current dev server URL.
@@ -415,9 +1242,10 @@ export async function ensureProxyRunning() {
         return null;
     }
     const codeyamPort = parseInt(process.env.CODEYAM_PORT || '3111', 10);
-    console.log(`[editorProxy] Proxy not running, starting on-demand (port ${codeyamPort + 1}, target ${devServer.url})`);
+    const { proxyPort } = computeEditorPorts(codeyamPort);
+    console.log(`[editorProxy] Proxy not running, starting on-demand (port ${proxyPort}, target ${devServer.url})`);
     const result = await startEditorProxy({
-        port: codeyamPort + 1,
+        port: proxyPort,
         targetUrl: devServer.url,
     });
     if (result) {
@@ -428,4 +1256,8 @@ export async function ensureProxyRunning() {
     console.error('[editorProxy] Failed to start on-demand proxy');
     return null;
 }
+/**
+ * Test-only export: trigger readScenarioData so tests can verify session config extraction.
+ */
+export const _readScenarioDataForTest = readScenarioData;
 //# sourceMappingURL=editorProxy.js.map