@codeyam/codeyam-cli 0.1.0-staging.ad88eeb → 0.1.0-staging.afbbaae

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

@@ -5,6 +5,7 @@ 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.
  *
@@ -60,10 +61,128 @@ export async function resolveLoopbackAddress(port) {
 }
 // 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() {
@@ -117,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;
         }
@@ -129,8 +250,14 @@ function readScenarioData() {
         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) {
@@ -204,6 +331,13 @@ 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);
@@ -217,19 +351,70 @@ function forwardBufferedRequest(req, res, targetUrl, bodyBuffer) {
     };
     const proxyReq = http.request(options, (proxyRes) => {
         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) {
@@ -240,33 +425,97 @@ 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,
         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) => {
         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 });
@@ -278,25 +527,94 @@ function forwardRequest(req, res, targetUrl) {
  * When sessionConfig is undefined (no scenario loaded yet), does nothing.
  */
 function injectSessionCookie(headers) {
-    if (sessionConfig === undefined)
-        return;
-    let cookie;
-    if (sessionConfig?.cookieValue) {
-        cookie = `session-token=${sessionConfig.cookieValue}; Path=/; SameSite=Lax`;
+    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`);
+        }
     }
-    else {
-        // No session config — clear any existing session cookie
-        cookie = `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]),
-            cookie,
+            ...cookies,
         ];
     }
     else {
-        headers['set-cookie'] = [cookie];
+        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('; ');
     }
 }
 /**
@@ -305,6 +623,324 @@ function injectSessionCookie(headers) {
 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.
  */
@@ -375,7 +1011,13 @@ 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();
     let targetUrl = normalizeTargetUrl(options.targetUrl);
     let port = options.port;
@@ -415,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
@@ -446,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;
             }
@@ -462,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;
@@ -533,6 +1187,10 @@ 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.