@codeyam/codeyam-cli 0.1.0-staging.dd216e0 → 0.1.0-staging.df25827

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

@@ -0,0 +1,1000 @@
+import http from 'http';
+import zlib from 'zlib';
+import { injectHealthScript, PREVIEW_HEALTH_SCRIPT, getPreviewHealthReport, resetPreviewHealth, buildErrorPage, escapeHtml, } from "../editorProxy.js";
+describe('editorProxy', () => {
+    describe('normalizeTargetUrl', () => {
+        it('should leave localhost as-is (no longer normalizes to 127.0.0.1)', () => {
+            const { normalizeTargetUrl } = require('../editorProxy');
+            expect(normalizeTargetUrl('http://localhost:3112')).toBe('http://localhost:3112');
+        });
+        it('should leave 127.0.0.1 unchanged', () => {
+            const { normalizeTargetUrl } = require('../editorProxy');
+            expect(normalizeTargetUrl('http://127.0.0.1:3112')).toBe('http://127.0.0.1:3112');
+        });
+        it('should leave other hostnames unchanged', () => {
+            const { normalizeTargetUrl } = require('../editorProxy');
+            expect(normalizeTargetUrl('http://myhost:3112')).toBe('http://myhost:3112');
+        });
+        it('should strip trailing slash', () => {
+            const { normalizeTargetUrl } = require('../editorProxy');
+            expect(normalizeTargetUrl('http://localhost:3112/')).toBe('http://localhost:3112');
+        });
+    });
+    describe('resolveLoopbackAddress', () => {
+        let server;
+        afterEach((done) => {
+            if (server?.listening) {
+                server.close(done);
+            }
+            else {
+                done();
+            }
+        });
+        it('should resolve to 127.0.0.1 when server binds to IPv4', async () => {
+            const { resolveLoopbackAddress } = require('../editorProxy');
+            server = http.createServer((_req, res) => res.end('ok'));
+            await new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+            const port = server.address().port;
+            const host = await resolveLoopbackAddress(port);
+            expect(host).toBe('127.0.0.1');
+        });
+        it('should resolve to ::1 when server binds to IPv6 only', async () => {
+            const { resolveLoopbackAddress } = require('../editorProxy');
+            server = http.createServer((_req, res) => res.end('ok'));
+            await new Promise((resolve) => server.listen(0, '::1', () => resolve()));
+            const port = server.address().port;
+            const host = await resolveLoopbackAddress(port);
+            expect(host).toBe('::1');
+        });
+        it('should return null when no server is listening', async () => {
+            const { resolveLoopbackAddress } = require('../editorProxy');
+            const host = await resolveLoopbackAddress(19876);
+            expect(host).toBeNull();
+        });
+    });
+    describe('proxy forwarding uses 127.0.0.1', () => {
+        let targetServer;
+        let targetPort;
+        afterEach((done) => {
+            if (targetServer?.listening) {
+                targetServer.close(done);
+            }
+            else {
+                done();
+            }
+        });
+        it('should forward requests to target and return correct response', async () => {
+            const { startEditorProxy, stopEditorProxy } = require('../editorProxy');
+            // Start a target server that returns 200
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('OK from target');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            // Start proxy pointing to the target using localhost URL
+            const result = await startEditorProxy({
+                port: 0, // let OS pick
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            // Make a request through the proxy
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(200);
+            const body = await response.text();
+            expect(body).toBe('OK from target');
+            await stopEditorProxy();
+        });
+        it('should log when target returns non-2xx status', async () => {
+            const { startEditorProxy, stopEditorProxy } = require('../editorProxy');
+            // Start a target that returns 404
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not Found');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const warnSpy = jest.spyOn(console, 'warn').mockImplementation();
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            const response = await fetch(`http://127.0.0.1:${result.port}/test-path`);
+            expect(response.status).toBe(404);
+            // Verify a warning was logged about the non-2xx response
+            expect(warnSpy.mock.calls.some((call) => String(call[0]).includes('[editorProxy]') &&
+                String(call[0]).includes('404') &&
+                String(call[0]).includes('/test-path'))).toBe(true);
+            warnSpy.mockRestore();
+            await stopEditorProxy();
+        });
+        it('should verify forwarding works after start via self-test', async () => {
+            const { startEditorProxy, stopEditorProxy, verifyProxyForwarding, } = require('../editorProxy');
+            // Start a target that returns 200
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('healthy');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            const verified = await verifyProxyForwarding();
+            expect(verified).toBe(true);
+            await stopEditorProxy();
+        });
+        it('should report verification failure when target is down', async () => {
+            const { startEditorProxy, stopEditorProxy, verifyProxyForwarding, } = require('../editorProxy');
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: 'http://127.0.0.1:19876',
+            });
+            const verified = await verifyProxyForwarding();
+            expect(verified).toBe(false);
+            await stopEditorProxy();
+        });
+        it('should return false for verification when proxy is not running', async () => {
+            const { verifyProxyForwarding, stopEditorProxy, } = require('../editorProxy');
+            await stopEditorProxy();
+            const verified = await verifyProxyForwarding();
+            expect(verified).toBe(false);
+        });
+        it('should return 502 when target is unreachable', async () => {
+            const { startEditorProxy, stopEditorProxy } = require('../editorProxy');
+            // Start proxy pointing to a port with nothing listening
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: 'http://localhost:19876',
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(502);
+            await stopEditorProxy();
+        });
+        it('should forward requests to an IPv6-only target server', async () => {
+            const { startEditorProxy, stopEditorProxy } = require('../editorProxy');
+            // Start a target server bound to IPv6 only (::1) — this is what Vite 6 does on macOS
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('OK from IPv6 target');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '::1', () => resolve()));
+            targetPort = targetServer.address().port;
+            // Start proxy with a localhost URL (simulating Vite's "Local: http://localhost:PORT")
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            // The proxy should successfully forward to the IPv6-only target
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(200);
+            const body = await response.text();
+            expect(body).toBe('OK from IPv6 target');
+            await stopEditorProxy();
+        });
+    });
+    describe('injectHealthScript', () => {
+        it('should inject before </head> when present', () => {
+            const html = '<html><head><title>Test</title></head><body>Hello</body></html>';
+            const result = injectHealthScript(html);
+            expect(result).toContain(PREVIEW_HEALTH_SCRIPT + '</head>');
+            expect(result).toContain('<title>Test</title>');
+        });
+        it('should inject before </body> when no </head>', () => {
+            const html = '<html><body>Hello</body></html>';
+            const result = injectHealthScript(html);
+            expect(result).toContain(PREVIEW_HEALTH_SCRIPT + '</body>');
+        });
+        it('should append when no </head> or </body>', () => {
+            const html = '<div>Hello</div>';
+            const result = injectHealthScript(html);
+            expect(result).toBe('<div>Hello</div>' + PREVIEW_HEALTH_SCRIPT);
+        });
+        it('should include the data-codeyam-health attribute', () => {
+            const html = '<html><head></head><body></body></html>';
+            const result = injectHealthScript(html);
+            expect(result).toContain('data-codeyam-health');
+        });
+        it('should use 100ms settle delay for network-idle detection', () => {
+            // The settle delay determines how long after all fetch() calls complete
+            // before the preview is shown. 100ms is enough for React to re-render.
+            expect(PREVIEW_HEALTH_SCRIPT).toContain('}, 100)');
+        });
+        it('should use 200ms fallback for static pages with no fetches', () => {
+            expect(PREVIEW_HEALTH_SCRIPT).toContain('}, 200)');
+        });
+    });
+    describe('preview health endpoint', () => {
+        let targetServer;
+        let targetPort;
+        afterEach(async () => {
+            const { stopEditorProxy } = require('../editorProxy');
+            await stopEditorProxy();
+            if (targetServer?.listening) {
+                await new Promise((resolve) => targetServer.close(() => resolve()));
+            }
+            resetPreviewHealth();
+        });
+        it('should intercept POST /__codeyam__/preview-health and store errors', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            // Start a target that returns 200
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('ok');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            // Post error data to the health endpoint
+            const response = await fetch(`http://127.0.0.1:${result.port}/__codeyam__/preview-health`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    errors: [
+                        {
+                            type: 'error',
+                            message: 'Cannot read properties of undefined',
+                            timestamp: 1710000000,
+                        },
+                    ],
+                    url: 'http://localhost:3112/',
+                }),
+            });
+            expect(response.status).toBe(204);
+            // Check the stored health data
+            const health = getPreviewHealthReport();
+            expect(health).not.toBeNull();
+            expect(health.errors).toHaveLength(1);
+            expect(health.errors[0].message).toBe('Cannot read properties of undefined');
+            expect(health.url).toBe('http://localhost:3112/');
+        });
+        it('should store loaded/hasContent from load report', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('ok');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            // Post load report
+            await fetch(`http://127.0.0.1:${result.port}/__codeyam__/preview-health`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    loaded: true,
+                    hasContent: true,
+                    url: 'http://localhost:3112/',
+                    errorCount: 0,
+                }),
+            });
+            const health = getPreviewHealthReport();
+            expect(health).not.toBeNull();
+            expect(health.loaded).toBe(true);
+            expect(health.hasContent).toBe(true);
+        });
+        it('should inject health script into HTML responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            // Target that returns HTML
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<html><head><title>App</title></head><body><div>Hello</div></body></html>');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            const body = await response.text();
+            expect(body).toContain('data-codeyam-health');
+            expect(body).toContain('/__codeyam__/preview-health');
+            expect(body).toContain('<title>App</title>');
+            expect(body).toContain('<div>Hello</div>');
+        });
+        it('should NOT inject health script into non-HTML responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end('{"data": "test"}');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            const response = await fetch(`http://127.0.0.1:${result.port}/api/data`);
+            const body = await response.text();
+            expect(body).toBe('{"data": "test"}');
+            expect(body).not.toContain('data-codeyam-health');
+        });
+        it('should accumulate errors across multiple health reports', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('ok');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            // First error report
+            await fetch(`http://127.0.0.1:${result.port}/__codeyam__/preview-health`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    errors: [{ type: 'error', message: 'Error 1', timestamp: 1 }],
+                    url: 'http://localhost:3112/',
+                }),
+            });
+            // Second error report
+            await fetch(`http://127.0.0.1:${result.port}/__codeyam__/preview-health`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    errors: [
+                        { type: 'console.error', message: 'Error 2', timestamp: 2 },
+                    ],
+                    url: 'http://localhost:3112/',
+                }),
+            });
+            const health = getPreviewHealthReport();
+            expect(health).not.toBeNull();
+            expect(health.errors).toHaveLength(2);
+            expect(health.errors[0].message).toBe('Error 1');
+            expect(health.errors[1].message).toBe('Error 2');
+        });
+    });
+    describe('buildLocalStorageScript', () => {
+        it('should clean up previous keys when no localStorage config but scenarioId is present', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            // When switching to a scenario WITHOUT localStorage from one that HAD it,
+            // the script must clean up the previous scenario's keys so stale filters
+            // don't persist and hide data.
+            const script = buildLocalStorageScript(null, 'scenario-123');
+            expect(script).toContain('__codeyam_ls_keys__');
+            expect(script).toContain('removeItem');
+            expect(script).toContain('clear:scenario-123');
+        });
+        it('should return empty string when no localStorage config and no scenarioId', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            expect(buildLocalStorageScript(null, '')).toBe('');
+            expect(buildLocalStorageScript(undefined, '')).toBe('');
+        });
+        it('should emit cleanup script when localStorage config is empty object', () => {
+            // BUG FIX: When switching from a scenario with localStorage data to one
+            // with empty localStorage (e.g. "First Launch - Welcome"), we must still
+            // clean up the previous scenario's keys. Otherwise the app reads stale data.
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const script = buildLocalStorageScript({}, 'scenario-123');
+            expect(script).not.toBe('');
+            // Should clean up previous keys
+            expect(script).toContain('localStorage.removeItem');
+            expect(script).toContain('__codeyam_ls_keys__');
+            expect(script).toContain('__codeyam_ls_sid__');
+            // Should NOT set any new keys (empty config)
+            expect(script).not.toContain('localStorage.setItem(\"margo');
+        });
+        it('should generate a script that sets localStorage entries', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const config = {
+                margo_articles: [{ id: 'a1', title: 'Test Article' }],
+                margo_collections: [{ id: 'c1', name: 'Test Collection' }],
+            };
+            const script = buildLocalStorageScript(config, 'scenario-abc');
+            // Should be wrapped in a script tag
+            expect(script).toMatch(/^<script data-codeyam-ls>/);
+            expect(script).toMatch(/<\/script>$/);
+            // Should gate on scenario ID to avoid re-seeding on reload
+            expect(script).toContain('scenario-abc');
+            expect(script).toContain('__codeyam_ls_sid__');
+            // Should set the localStorage entries
+            expect(script).toContain('margo_articles');
+            expect(script).toContain('margo_collections');
+            expect(script).toContain('localStorage.setItem');
+            // Should track which keys were set for cleanup
+            expect(script).toContain('__codeyam_ls_keys__');
+        });
+        it('should emit gated localStorage.clear() when prototypeId is provided and config is null', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const script = buildLocalStorageScript(null, 'scenario-123', 'proto-abc');
+            // Should not be empty — prototypeId triggers a clear script
+            expect(script).not.toBe('');
+            expect(script).toContain('localStorage.clear()');
+            // Should be gated by the __codeyam_proto__ marker
+            expect(script).toContain('__codeyam_proto__');
+            expect(script).toContain('proto-abc');
+        });
+        it('should clean up previous keys when prototypeId is absent but scenarioId is present', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            // No prototypeId but scenarioId — cleanup previous scenario's keys
+            const script1 = buildLocalStorageScript(null, 'scenario-123');
+            expect(script1).toContain('removeItem');
+            const script2 = buildLocalStorageScript(null, 'scenario-123', null);
+            expect(script2).toContain('removeItem');
+        });
+        it('should clean up keys from previous scenario before setting new ones', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const config = { my_key: 'my_value' };
+            const script = buildLocalStorageScript(config, 'scenario-xyz');
+            // Should read previous keys and remove them
+            expect(script).toContain('__codeyam_ls_keys__');
+            expect(script).toContain('localStorage.removeItem');
+        });
+        it('should JSON.stringify non-string values', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const config = {
+                string_key: 'plain string',
+                object_key: { nested: true },
+                array_key: [1, 2, 3],
+            };
+            const script = buildLocalStorageScript(config, 'scenario-1');
+            // Object/array values should be JSON-stringified and embedded as JS string literals.
+            // JSON.stringify is applied twice: once to serialize the value, once to make it a safe JS string.
+            // So {"nested":true} becomes "{\"nested\":true}" in the script source.
+            expect(script).toContain('object_key');
+            expect(script).toContain('nested');
+            expect(script).toContain('array_key');
+            expect(script).toContain('[1,2,3]');
+        });
+        it('should include localStorage mutation watcher that sends postMessage on changes', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const config = { my_key: 'my_value' };
+            const script = buildLocalStorageScript(config, 'scenario-1');
+            // Should hook setItem, removeItem, and clear
+            expect(script).toContain('__codeyam_orig_setItem__');
+            expect(script).toContain('__codeyam_orig_removeItem__');
+            expect(script).toContain('__codeyam_orig_clear__');
+            // Should send postMessage to parent
+            expect(script).toContain('codeyam-localstorage-changed');
+            expect(script).toContain('postMessage');
+            // Should filter out internal codeyam keys
+            expect(script).toContain('__codeyam_');
+        });
+        it('should include localStorage mutation watcher even for empty localStorage config', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const script = buildLocalStorageScript({}, 'scenario-1');
+            // Empty config still needs the watcher since the app may write to localStorage
+            expect(script).toContain('codeyam-localstorage-changed');
+        });
+        it('should include a listener for codeyam-get-localstorage requests', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const config = { my_key: 'my_value' };
+            const script = buildLocalStorageScript(config, 'scenario-1');
+            // Should listen for get-localstorage requests from parent
+            expect(script).toContain('codeyam-get-localstorage');
+            expect(script).toContain('codeyam-localstorage-state');
+        });
+        it('should not include mutation watcher when no localStorage config and no scenarioId', () => {
+            const { buildLocalStorageScript } = require('../editorProxy');
+            // No config AND no scenarioId — returns empty string
+            expect(buildLocalStorageScript(null, '')).toBe('');
+        });
+        it('should re-seed localStorage when scenario data changes even if ID is the same', () => {
+            // BUG: When a scenario is re-registered with updated data (e.g., adding
+            // collections to articles), the scenario ID stays the same. The guard
+            // checked only the ID, so the browser skipped re-seeding and showed stale
+            // data. The screenshot (captured by Playwright with a fresh browser)
+            // showed the new data, but the live preview didn't.
+            const { buildLocalStorageScript } = require('../editorProxy');
+            const originalData = {
+                articles: '[{"id":"a1","title":"Test"}]',
+            };
+            const updatedData = {
+                articles: '[{"id":"a1","title":"Test","collectionIds":["c1"]}]',
+                collections: '[{"id":"c1","name":"Dev"}]',
+            };
+            const script1 = buildLocalStorageScript(originalData, 'scenario-abc');
+            const script2 = buildLocalStorageScript(updatedData, 'scenario-abc');
+            // Both scripts use the same scenario ID
+            expect(script1).toContain('scenario-abc');
+            expect(script2).toContain('scenario-abc');
+            // The guard values must be DIFFERENT so the browser re-seeds
+            // Extract the guard comparison value from each script
+            const guardPattern = /__codeyam_ls_sid__.*?===\s*([^\)]+)\)/;
+            const guard1 = script1.match(guardPattern)?.[1];
+            const guard2 = script2.match(guardPattern)?.[1];
+            expect(guard1).toBeDefined();
+            expect(guard2).toBeDefined();
+            expect(guard1).not.toEqual(guard2);
+        });
+    });
+    describe('localStorage injection in HTML responses', () => {
+        it('should inject localStorage script before health script in HTML', () => {
+            const { buildLocalStorageScript, injectHealthScript, } = require('../editorProxy');
+            const lsScript = buildLocalStorageScript({ items: [1, 2] }, 'scenario-1');
+            // localStorage script should be injected before the health script
+            // (needs to run before app loads)
+            const html = '<html><head><title>Test</title></head><body>Hello</body></html>';
+            const result = injectHealthScript(html, lsScript);
+            expect(result).toContain('data-codeyam-ls');
+            expect(result).toContain('data-codeyam-health');
+            // localStorage script should appear BEFORE health script in the output
+            const lsIdx = result.indexOf('data-codeyam-ls');
+            const healthIdx = result.indexOf('data-codeyam-health');
+            expect(lsIdx).toBeLessThan(healthIdx);
+        });
+        it('should not inject localStorage script when none provided', () => {
+            const html = '<html><head><title>Test</title></head><body>Hello</body></html>';
+            const result = injectHealthScript(html);
+            expect(result).toContain('data-codeyam-health');
+            expect(result).not.toContain('data-codeyam-ls');
+        });
+    });
+    describe('compressed response handling', () => {
+        let targetServer;
+        let targetPort;
+        afterEach(async () => {
+            const { stopEditorProxy } = require('../editorProxy');
+            await stopEditorProxy();
+            if (targetServer?.listening) {
+                await new Promise((resolve) => targetServer.close(() => resolve()));
+            }
+            resetPreviewHealth();
+        });
+        it('should strip accept-encoding so target returns uncompressed HTML for injection', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            const originalHtml = '<html><head><title>Compressed</title></head><body><div>Gzipped</div></body></html>';
+            // Target server that compresses only when client sends Accept-Encoding
+            // (simulates real dev servers like Next.js/Vite)
+            targetServer = http.createServer((req, res) => {
+                const acceptEncoding = req.headers['accept-encoding'] || '';
+                if (acceptEncoding.includes('gzip')) {
+                    const compressed = zlib.gzipSync(Buffer.from(originalHtml));
+                    res.writeHead(200, {
+                        'Content-Type': 'text/html',
+                        'Content-Encoding': 'gzip',
+                        'Content-Length': compressed.length,
+                    });
+                    res.end(compressed);
+                }
+                else {
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(originalHtml);
+                }
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            // Request through proxy WITH Accept-Encoding (simulating a real browser)
+            const response = await fetch(`http://127.0.0.1:${result.port}/`, {
+                headers: { 'Accept-Encoding': 'gzip, deflate, br' },
+            });
+            // The proxy should return a valid, readable response
+            expect(response.status).toBe(200);
+            const body = await response.text();
+            // Should contain the original HTML content (not corrupted binary)
+            expect(body).toContain('<title>Compressed</title>');
+            expect(body).toContain('<div>Gzipped</div>');
+            // Should have injected the health script
+            expect(body).toContain('data-codeyam-health');
+            // Should NOT have Content-Encoding since the proxy serves uncompressed
+            expect(response.headers.get('content-encoding')).toBeNull();
+        });
+    });
+    describe('session cookie injection into requests', () => {
+        let targetServer;
+        let targetPort;
+        let tempDir;
+        let receivedCookies;
+        let originalProjectRoot;
+        beforeEach(() => {
+            const fs = require('fs');
+            const path = require('path');
+            const os = require('os');
+            const { getProjectRoot } = require('../../state');
+            const { setProjectRoot } = require('../../state');
+            originalProjectRoot = getProjectRoot();
+            tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proxy-req-cookie-'));
+            setProjectRoot(tempDir);
+            receivedCookies = undefined;
+        });
+        afterEach(async () => {
+            const { stopEditorProxy, invalidateScenarioCache, } = require('../editorProxy');
+            const { setProjectRoot } = require('../../state');
+            invalidateScenarioCache();
+            await stopEditorProxy();
+            if (targetServer?.listening) {
+                await new Promise((resolve) => targetServer.close(() => resolve()));
+            }
+            if (originalProjectRoot) {
+                setProjectRoot(originalProjectRoot);
+            }
+            const fs = require('fs');
+            fs.rmSync(tempDir, { recursive: true, force: true });
+            resetPreviewHealth();
+        });
+        it('should forward seed adapter session cookies in the request Cookie header', async () => {
+            const fs = require('fs');
+            const path = require('path');
+            const { startEditorProxy, invalidateScenarioCache, } = require('../editorProxy');
+            // Set up scenario files
+            const scenarioId = 'integration-auth-test';
+            const codeyamDir = path.join(tempDir, '.codeyam');
+            const scenariosDir = path.join(codeyamDir, 'editor-scenarios');
+            fs.mkdirSync(scenariosDir, { recursive: true });
+            fs.writeFileSync(path.join(codeyamDir, 'active-scenario.json'), JSON.stringify({ scenarioId, type: 'application' }));
+            fs.writeFileSync(path.join(scenariosDir, `${scenarioId}.json`), JSON.stringify({
+                type: 'application',
+                seed: { user: [{ id: '1' }] },
+                sessionCookies: [
+                    {
+                        name: 'sb-test-auth-token',
+                        value: '{"access_token":"test-jwt","refresh_token":"test-ref"}',
+                        path: '/',
+                        sameSite: 'Lax',
+                    },
+                ],
+            }));
+            // Target server that captures the request Cookie header
+            targetServer = http.createServer((req, res) => {
+                receivedCookies = req.headers.cookie;
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('OK');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            // Invalidate to force re-read of scenario data
+            invalidateScenarioCache();
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            // Make request WITHOUT any cookies (simulates first iframe load after scenario switch)
+            await fetch(`http://127.0.0.1:${result.port}/library`);
+            // The target server should have received the injected auth cookie
+            expect(receivedCookies).toBeDefined();
+            expect(receivedCookies).toContain('sb-test-auth-token=');
+            expect(receivedCookies).toContain('test-jwt');
+        });
+        it('should merge injected cookies with existing browser cookies', async () => {
+            const fs = require('fs');
+            const path = require('path');
+            const { startEditorProxy, invalidateScenarioCache, } = require('../editorProxy');
+            const scenarioId = 'integration-merge-test';
+            const codeyamDir = path.join(tempDir, '.codeyam');
+            const scenariosDir = path.join(codeyamDir, 'editor-scenarios');
+            fs.mkdirSync(scenariosDir, { recursive: true });
+            fs.writeFileSync(path.join(codeyamDir, 'active-scenario.json'), JSON.stringify({ scenarioId, type: 'application' }));
+            fs.writeFileSync(path.join(scenariosDir, `${scenarioId}.json`), JSON.stringify({
+                type: 'application',
+                seed: {},
+                session: { cookieValue: 'sess_alice' },
+                sessionCookies: [
+                    { name: 'sb-auth', value: 'supabase-jwt', path: '/' },
+                ],
+            }));
+            targetServer = http.createServer((req, res) => {
+                receivedCookies = req.headers.cookie;
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('OK');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            invalidateScenarioCache();
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            // Make request WITH an existing cookie (simulates browser that already has cookies)
+            await fetch(`http://127.0.0.1:${result.port}/library`, {
+                headers: { Cookie: 'other-cookie=existing-value' },
+            });
+            // Should have both the existing cookie and the injected ones
+            expect(receivedCookies).toContain('other-cookie=existing-value');
+            expect(receivedCookies).toContain('session-token=sess_alice');
+            expect(receivedCookies).toContain('sb-auth=supabase-jwt');
+        });
+    });
+    describe('Cache-Control on HTML responses', () => {
+        let targetServer;
+        let targetPort;
+        afterEach(async () => {
+            const { stopEditorProxy } = require('../editorProxy');
+            await stopEditorProxy();
+            if (targetServer?.listening) {
+                await new Promise((resolve) => targetServer.close(() => resolve()));
+            }
+            resetPreviewHealth();
+        });
+        it('should add Cache-Control: no-store to proxied HTML responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            // Target server that serves plain HTML without cache headers
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<html><head><title>Test</title></head><body>Hello</body></html>');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(200);
+            // Proxy must set no-store so the browser doesn't cache pages between
+            // scenario switches (application scenarios share the same proxy URL
+            // but differ in seed data).
+            expect(response.headers.get('cache-control')).toBe('no-store, must-revalidate');
+        });
+        it('should NOT add Cache-Control: no-store to non-HTML responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            // Target server that serves JSON without cache headers
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: true }));
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/api/data`);
+            expect(response.status).toBe(200);
+            // Non-HTML responses pass through the target's original headers;
+            // the proxy only forces no-store on HTML.
+            expect(response.headers.get('cache-control')).toBeNull();
+        });
+    });
+    describe('escapeHtml', () => {
+        it('should escape ampersands, angle brackets, and quotes', () => {
+            expect(escapeHtml('<script>alert("xss")</script>')).toBe('&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;');
+        });
+        it('should escape single quotes', () => {
+            expect(escapeHtml("it's")).toBe('it&#39;s');
+        });
+        it('should return empty string for empty input', () => {
+            expect(escapeHtml('')).toBe('');
+        });
+        it('should leave safe text unchanged', () => {
+            expect(escapeHtml('Hello world 123')).toBe('Hello world 123');
+        });
+    });
+    describe('buildErrorPage', () => {
+        it('should generate a complete HTML document', () => {
+            const page = buildErrorPage(500, 'Internal Server Error', 'something broke');
+            expect(page).toContain('<!DOCTYPE html>');
+            expect(page).toContain('<html');
+            expect(page).toContain('</html>');
+        });
+        it('should include the status code and title', () => {
+            const page = buildErrorPage(502, 'Dev Server Unreachable', 'details here');
+            expect(page).toContain('502');
+            expect(page).toContain('Dev Server Unreachable');
+        });
+        it('should include the error detail text', () => {
+            const page = buildErrorPage(500, 'Error', 'Connection refused on port 3000');
+            expect(page).toContain('Connection refused on port 3000');
+        });
+        it('should escape HTML in the detail to prevent XSS', () => {
+            const page = buildErrorPage(500, 'Error', '<script>alert("xss")</script>');
+            expect(page).not.toContain('<script>alert("xss")</script>');
+            expect(page).toContain('&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;');
+        });
+        it('should include codeyam-server-error postMessage', () => {
+            const page = buildErrorPage(500, 'Error', 'detail');
+            expect(page).toContain('codeyam-server-error');
+            expect(page).toContain('postMessage');
+        });
+        it('should NOT include codeyam-preview-ready postMessage', () => {
+            const page = buildErrorPage(500, 'Error', 'detail');
+            expect(page).not.toContain('codeyam-preview-ready');
+        });
+        it('should include a retry button that sends codeyam-server-error-retry', () => {
+            const page = buildErrorPage(500, 'Error', 'detail');
+            expect(page).toContain('codeyam-server-error-retry');
+            // Should have a button element
+            expect(page).toMatch(/<button[^>]*>/i);
+        });
+        it('should include the status code in the postMessage data', () => {
+            const page = buildErrorPage(502, 'Unreachable', 'detail');
+            // The postMessage should include statusCode: 502
+            expect(page).toContain('502');
+        });
+        it('should escape HTML in the title to prevent XSS', () => {
+            const page = buildErrorPage(500, '<img onerror=alert(1)>', 'detail');
+            expect(page).not.toContain('<img onerror=alert(1)>');
+            expect(page).toContain('&lt;img onerror=alert(1)&gt;');
+        });
+        it('should handle multiline error detail', () => {
+            const detail = 'Error on line 1\nStack trace line 2\nStack trace line 3';
+            const page = buildErrorPage(500, 'Error', detail);
+            expect(page).toContain('Error on line 1');
+            expect(page).toContain('Stack trace line 3');
+        });
+        it('should handle empty detail', () => {
+            const page = buildErrorPage(500, 'Error', '');
+            expect(page).toContain('<!DOCTYPE html>');
+            expect(page).toContain('codeyam-server-error');
+        });
+    });
+    describe('5xx error page serving', () => {
+        let targetServer;
+        let targetPort;
+        afterEach(async () => {
+            const { stopEditorProxy } = require('../editorProxy');
+            await stopEditorProxy();
+            if (targetServer?.listening) {
+                await new Promise((resolve) => targetServer.close(() => resolve()));
+            }
+        });
+        it('should serve an error page instead of raw HTML for 500 responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(500, { 'Content-Type': 'text/html' });
+                res.end('<html><body>Internal Server Error</body></html>');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(500);
+            const body = await response.text();
+            // Should contain the friendly error page, not the raw error
+            expect(body).toContain('codeyam-server-error');
+            expect(body).toContain('Internal Server Error');
+        });
+        it('should NOT replace non-HTML 500 responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'server error' }));
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/api/data`);
+            expect(response.status).toBe(500);
+            const body = await response.text();
+            // JSON responses should pass through unchanged
+            expect(body).toContain('"error":"server error"');
+            expect(body).not.toContain('codeyam-server-error');
+        });
+        it('should serve an error page for 500 responses with no content type', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            // Simulates Next.js returning bare "Internal Server Error" with no Content-Type
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(500);
+                res.end('Internal Server Error');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(500);
+            const body = await response.text();
+            expect(body).toContain('codeyam-server-error');
+            expect(body).toContain('<!DOCTYPE html>');
+            expect(body).toContain('Internal Server Error');
+        });
+        it('should serve an error page for 500 text/plain responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end('Something went wrong');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(500);
+            const body = await response.text();
+            expect(body).toContain('codeyam-server-error');
+            expect(body).toContain('Something went wrong');
+        });
+        it('should serve an error page for 503 responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(503, { 'Content-Type': 'text/html' });
+                res.end('<html><body>Service Unavailable</body></html>');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(503);
+            const body = await response.text();
+            expect(body).toContain('codeyam-server-error');
+        });
+        it('should serve an error page for POST requests returning 500', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(500, { 'Content-Type': 'text/html' });
+                res.end('<html><body>POST Error</body></html>');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/api/action`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ test: true }),
+            });
+            expect(response.status).toBe(500);
+            const body = await response.text();
+            expect(body).toContain('codeyam-server-error');
+            expect(body).toContain('POST Error');
+        });
+        it('should NOT serve an error page for 4xx responses', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            targetServer = http.createServer((_req, res) => {
+                res.writeHead(404, { 'Content-Type': 'text/html' });
+                res.end('<html><body>Not Found</body></html>');
+            });
+            await new Promise((resolve) => targetServer.listen(0, '127.0.0.1', () => resolve()));
+            targetPort = targetServer.address().port;
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: `http://localhost:${targetPort}`,
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/missing`);
+            expect(response.status).toBe(404);
+            const body = await response.text();
+            // 4xx should pass through normally (with health script injected, not error page)
+            expect(body).not.toContain('codeyam-server-error');
+            expect(body).toContain('Not Found');
+        });
+        it('should serve an HTML error page for 502 connection failures', async () => {
+            const { startEditorProxy } = require('../editorProxy');
+            // No target server — connection will fail
+            const result = await startEditorProxy({
+                port: 0,
+                targetUrl: 'http://127.0.0.1:19999',
+            });
+            expect(result).not.toBeNull();
+            const response = await fetch(`http://127.0.0.1:${result.port}/`);
+            expect(response.status).toBe(502);
+            const body = await response.text();
+            expect(body).toContain('codeyam-server-error');
+            expect(body).toContain('<!DOCTYPE html>');
+        });
+    });
+});
+//# sourceMappingURL=editorProxy.test.js.map