@codeyam/codeyam-cli 0.1.0-staging.d3e886e → 0.1.0-staging.dbc742d

package/codeyam-cli/src/utils/__tests__/editorScenarios.test.js

@@ -0,0 +1,841 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import Database from 'better-sqlite3';
+import { Kysely, SqliteDialect } from 'kysely';
+import { deduplicateByName, generateScenarioSlug, convertIsoToSqliteTimestamp, determineCaptureUrl, resolvePreviewNavPath, clearEditorState, clearEditorUserPrompt, readDefaultScreenSize, readScreenSizes, resolveScenarioViewport, resolveViewportWithProjectDefault, upsertEditorScenario, cleanupScenarioFiles, readPreservedConfigProperties, validateStepTransition, } from "../editorScenarios.js";
+describe('editorScenarios', () => {
+    describe('deduplicateByName', () => {
+        it('should keep only the last item for each key', () => {
+            const items = [
+                { name: 'Default', id: '1', value: 'old' },
+                { name: 'Dark Mode', id: '2', value: 'old' },
+                { name: 'Default', id: '3', value: 'new' },
+            ];
+            const result = deduplicateByName(items, (item) => item.name);
+            expect(result).toHaveLength(2);
+            expect(result.find((r) => r.name === 'Default')?.id).toBe('3');
+            expect(result.find((r) => r.name === 'Dark Mode')?.id).toBe('2');
+        });
+        it('should return empty array for empty input', () => {
+            expect(deduplicateByName([], (x) => x.name)).toEqual([]);
+        });
+        it('should not lose screenshots when re-registered scenario has null screenshot (filter before dedup)', () => {
+            // Simulates the journal screenshot lookup flow:
+            // Scenarios ordered by created_at ASC from DB, some re-registered with null screenshot
+            const scenarios = [
+                {
+                    name: 'Full Catalog',
+                    screenshot_path: 'screenshots/aaa.png',
+                    id: 'aaa',
+                },
+                {
+                    name: 'API Error',
+                    screenshot_path: 'screenshots/bbb.png',
+                    id: 'bbb',
+                },
+                { name: 'API Error', screenshot_path: null, id: 'ccc' }, // re-registered, capture in progress
+            ];
+            // BUG: dedup-then-filter loses "API Error" entirely because dedup picks
+            // the latest row (null screenshot), then filter removes it.
+            const buggyDeduped = deduplicateByName(scenarios, (s) => s.name);
+            const buggyResult = buggyDeduped.filter((s) => s.screenshot_path);
+            // This would only contain "Full Catalog" — "API Error" is gone!
+            expect(buggyResult).toHaveLength(1); // demonstrates the bug
+            // FIX: filter-then-dedup preserves the latest row that HAS a screenshot.
+            const filtered = scenarios.filter((s) => s.screenshot_path);
+            const fixedResult = deduplicateByName(filtered, (s) => s.name);
+            expect(fixedResult).toHaveLength(2);
+            expect(fixedResult.find((s) => s.name === 'API Error')?.id).toBe('bbb');
+            expect(fixedResult.find((s) => s.name === 'Full Catalog')?.id).toBe('aaa');
+        });
+        it('should preserve order of first appearance', () => {
+            const items = [
+                { name: 'A', v: 1 },
+                { name: 'B', v: 2 },
+                { name: 'A', v: 3 },
+            ];
+            const result = deduplicateByName(items, (i) => i.name);
+            // Map preserves insertion order — A first, then B
+            expect(result.map((r) => r.name)).toEqual(['A', 'B']);
+        });
+    });
+    describe('generateScenarioSlug', () => {
+        it('should replace non-alphanumeric chars with underscores', () => {
+            expect(generateScenarioSlug('Dark Mode')).toBe('Dark_Mode');
+        });
+        it('should collapse consecutive special characters', () => {
+            expect(generateScenarioSlug('Hello -- World!!')).toBe('Hello_World_');
+        });
+        it('should preserve underscores and alphanumeric characters', () => {
+            expect(generateScenarioSlug('Already_Valid123')).toBe('Already_Valid123');
+        });
+        it('should handle empty string', () => {
+            expect(generateScenarioSlug('')).toBe('');
+        });
+    });
+    describe('convertIsoToSqliteTimestamp', () => {
+        it('should convert ISO 8601 to SQLite format', () => {
+            expect(convertIsoToSqliteTimestamp('2026-02-28T19:00:00.000Z')).toBe('2026-02-28 19:00:00');
+        });
+        it('should handle timestamps without milliseconds', () => {
+            expect(convertIsoToSqliteTimestamp('2026-02-28T19:00:00Z')).toBe('2026-02-28 19:00:00Z');
+        });
+        it('should replace T with space', () => {
+            expect(convertIsoToSqliteTimestamp('2026-01-15T08:30:45.123Z')).toBe('2026-01-15 08:30:45');
+        });
+    });
+    describe('determineCaptureUrl', () => {
+        it('should combine path with proxy URL when path-based and proxy available', () => {
+            expect(determineCaptureUrl('/isolated-components/DrinkCard?s=Default', 'http://localhost:3112', 'http://localhost:3000')).toBe('http://localhost:3112/isolated-components/DrinkCard?s=Default');
+        });
+        it('should work with path field normalized to url (path alias)', () => {
+            // When Claude writes "path": "/drinks/1" instead of "url": "/drinks/1",
+            // the register endpoint normalizes path → url before calling determineCaptureUrl.
+            // This test verifies that determineCaptureUrl handles the resulting value correctly.
+            const normalizedUrl = '/drinks/1'; // after normalization: body.url = body.path
+            expect(determineCaptureUrl(normalizedUrl, 'http://localhost:3112', 'http://localhost:3000')).toBe('http://localhost:3112/drinks/1');
+        });
+        it('should use full URL directly when not path-based', () => {
+            expect(determineCaptureUrl('http://external.com/page', 'http://localhost:3112', 'http://localhost:3000')).toBe('http://external.com/page');
+        });
+        it('should fall back to proxy root when no URL provided', () => {
+            expect(determineCaptureUrl(null, 'http://localhost:3112', 'http://localhost:3000')).toBe('http://localhost:3112');
+        });
+        it('should fall back to dev server when no URL and no proxy', () => {
+            expect(determineCaptureUrl(null, null, 'http://localhost:3000')).toBe('http://localhost:3000');
+        });
+        it('should return null when nothing available', () => {
+            expect(determineCaptureUrl(null, null, null)).toBeNull();
+        });
+        it('should fall back to dev server for path when proxy unavailable', () => {
+            // Path-based but proxy is null — can't route through proxy
+            expect(determineCaptureUrl('/some-path', null, 'http://localhost:3000')).toBe('http://localhost:3000');
+        });
+    });
+    describe('clearEditorState', () => {
+        let tmpDir;
+        let codeyamDir;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'editor-state-'));
+            codeyamDir = path.join(tmpDir, '.codeyam');
+            fs.mkdirSync(codeyamDir, { recursive: true });
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should delete the editor-step.json state file', () => {
+            fs.writeFileSync(path.join(codeyamDir, 'editor-step.json'), JSON.stringify({ step: 5, label: 'Extract' }));
+            clearEditorState(tmpDir);
+            expect(fs.existsSync(path.join(codeyamDir, 'editor-step.json'))).toBe(false);
+        });
+        it('should preserve editor-user-prompt.txt (captured by hook before step 1)', () => {
+            // The hook captures the user's feature request BEFORE step 1 calls clearEditorState.
+            // If clearEditorState deletes the prompt file, the next unrelated user message
+            // (e.g. "ok" approving a database reset) gets captured as the feature prompt.
+            fs.writeFileSync(path.join(codeyamDir, 'editor-step.json'), JSON.stringify({ step: 13, label: 'Present' }));
+            fs.writeFileSync(path.join(codeyamDir, 'editor-user-prompt.txt'), 'Could we add a page for each individual drink?');
+            clearEditorState(tmpDir);
+            expect(fs.readFileSync(path.join(codeyamDir, 'editor-user-prompt.txt'), 'utf8')).toBe('Could we add a page for each individual drink?');
+        });
+        it('should not throw if state file does not exist', () => {
+            expect(() => clearEditorState(tmpDir)).not.toThrow();
+        });
+    });
+    describe('clearEditorUserPrompt', () => {
+        let tmpDir;
+        let codeyamDir;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'editor-prompt-'));
+            codeyamDir = path.join(tmpDir, '.codeyam');
+            fs.mkdirSync(codeyamDir, { recursive: true });
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should delete the prompt file', () => {
+            fs.writeFileSync(path.join(codeyamDir, 'editor-user-prompt.txt'), 'old feature prompt');
+            clearEditorUserPrompt(tmpDir);
+            expect(fs.existsSync(path.join(codeyamDir, 'editor-user-prompt.txt'))).toBe(false);
+        });
+        it('should not throw if file does not exist', () => {
+            expect(() => clearEditorUserPrompt(tmpDir)).not.toThrow();
+        });
+    });
+    describe('resolvePreviewNavPath', () => {
+        it('should use explicit path when provided', () => {
+            expect(resolvePreviewNavPath('/explicit', '/scenario-url')).toBe('/explicit');
+        });
+        it('should fall back to scenario URL when no explicit path', () => {
+            expect(resolvePreviewNavPath(null, '/drinks/1')).toBe('/drinks/1');
+        });
+        it('should return undefined when neither path nor URL provided', () => {
+            expect(resolvePreviewNavPath(null, null)).toBeUndefined();
+        });
+        it('should return undefined for empty strings', () => {
+            expect(resolvePreviewNavPath('', '')).toBeUndefined();
+        });
+        it('should prefer explicit path over scenario URL', () => {
+            expect(resolvePreviewNavPath('/', '/drinks/1')).toBe('/');
+        });
+    });
+    describe('register endpoint path→url normalization (logic verification)', () => {
+        // These tests verify the normalization logic used in api.editor-register-scenario.ts:
+        //   body.url = body.url || body.path || undefined;
+        // The route can't be unit-tested directly (ESM import.meta), so we verify
+        // the normalization + downstream logic here.
+        function normalizeUrl(body) {
+            // Mirror the exact line from api.editor-register-scenario.ts line 152
+            return body.url || body.path || undefined;
+        }
+        it('should use url when provided', () => {
+            expect(normalizeUrl({ url: '/drinks/1' })).toBe('/drinks/1');
+        });
+        it('should fall back to path when url not provided', () => {
+            expect(normalizeUrl({ path: '/drinks/1' })).toBe('/drinks/1');
+        });
+        it('should prefer url over path', () => {
+            expect(normalizeUrl({ url: '/explicit', path: '/fallback' })).toBe('/explicit');
+        });
+        it('should return undefined when neither provided', () => {
+            expect(normalizeUrl({})).toBeUndefined();
+        });
+        it('should work end-to-end: path → normalize → determineCaptureUrl', () => {
+            // Full pipeline: Claude writes "path": "/drinks/1"
+            // → register normalizes to url: "/drinks/1"
+            // → determineCaptureUrl combines with proxy
+            const body = { path: '/drinks/1' };
+            const normalizedUrl = normalizeUrl(body);
+            const captureUrl = determineCaptureUrl(normalizedUrl || null, 'http://localhost:4100', 'http://localhost:3000');
+            expect(captureUrl).toBe('http://localhost:4100/drinks/1');
+        });
+        it('should work end-to-end: no url → normalize → proxy root', () => {
+            // Claude omits both url and path
+            // → normalize returns undefined
+            // → determineCaptureUrl falls back to proxy root
+            const body = {};
+            const normalizedUrl = normalizeUrl(body);
+            const captureUrl = determineCaptureUrl(normalizedUrl || null, 'http://localhost:4100', 'http://localhost:3000');
+            expect(captureUrl).toBe('http://localhost:4100');
+        });
+    });
+    describe('readDefaultScreenSize', () => {
+        let tmpDir;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'screen-size-test-'));
+            fs.mkdirSync(path.join(tmpDir, '.codeyam'), { recursive: true });
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should return width and height from config', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                defaultScreenSize: { name: 'Mobile', width: 375, height: 667 },
+            }));
+            const result = readDefaultScreenSize(tmpDir);
+            expect(result).toEqual({ width: 375, height: 667 });
+        });
+        it('should return null when no defaultScreenSize in config', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({ projectTitle: 'Test' }));
+            const result = readDefaultScreenSize(tmpDir);
+            expect(result).toBeNull();
+        });
+        it('should return null when config file does not exist', () => {
+            const result = readDefaultScreenSize(tmpDir);
+            expect(result).toBeNull();
+        });
+    });
+    describe('resolveScenarioViewport', () => {
+        it('should use explicit viewport when provided', () => {
+            const result = resolveScenarioViewport({
+                bodyWidth: 800,
+                bodyHeight: 600,
+                projectDefault: { width: 375, height: 667 },
+            });
+            expect(result).toEqual({ width: 800, height: 600 });
+        });
+        it('should use project default when no explicit viewport', () => {
+            const result = resolveScenarioViewport({
+                projectDefault: { width: 375, height: 667 },
+            });
+            expect(result).toEqual({ width: 375, height: 667 });
+        });
+        it('should fall back to 1280x720 when neither is provided', () => {
+            const result = resolveScenarioViewport({});
+            expect(result).toEqual({ width: 1280, height: 720 });
+        });
+        it('should use project default for missing dimensions', () => {
+            const result = resolveScenarioViewport({
+                bodyWidth: 800,
+                projectDefault: { width: 375, height: 667 },
+            });
+            // bodyWidth provided, bodyHeight not — should use project default height
+            expect(result).toEqual({ width: 800, height: 667 });
+        });
+    });
+    describe('resolveViewportWithProjectDefault', () => {
+        let tmpDir;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'viewport-project-default-'));
+            fs.mkdirSync(path.join(tmpDir, '.codeyam'), { recursive: true });
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should use custom default from config.json when no explicit viewport provided', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                defaultScreenSize: { name: 'iPhone 15', width: 393, height: 852 },
+            }));
+            const result = resolveViewportWithProjectDefault({
+                codeyamRoot: tmpDir,
+            });
+            expect(result).toEqual({ width: 393, height: 852 });
+        });
+        it('should prefer explicit viewport over project default', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                defaultScreenSize: { name: 'iPhone 15', width: 393, height: 852 },
+            }));
+            const result = resolveViewportWithProjectDefault({
+                bodyWidth: 1024,
+                bodyHeight: 768,
+                codeyamRoot: tmpDir,
+            });
+            expect(result).toEqual({ width: 1024, height: 768 });
+        });
+        it('should fall back to 1280x720 when no config and no explicit viewport', () => {
+            const result = resolveViewportWithProjectDefault({
+                codeyamRoot: tmpDir,
+            });
+            expect(result).toEqual({ width: 1280, height: 720 });
+        });
+        it('should fall back to 1280x720 when config has no defaultScreenSize', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({ projectTitle: 'Test' }));
+            const result = resolveViewportWithProjectDefault({
+                codeyamRoot: tmpDir,
+            });
+            expect(result).toEqual({ width: 1280, height: 720 });
+        });
+        it('should resolve dimension name to screenSizes entry', () => {
+            // Claude registers "Home - Mobile" with dimension: "Mobile"
+            // → resolveViewportWithProjectDefault looks up "Mobile" in screenSizes
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                screenSizes: {
+                    Desktop: { width: 1440, height: 900 },
+                    Mobile: { width: 375, height: 667 },
+                },
+            }));
+            const result = resolveViewportWithProjectDefault({
+                dimension: 'Mobile',
+                codeyamRoot: tmpDir,
+            });
+            expect(result).toEqual({ width: 375, height: 667 });
+        });
+        it('should prefer explicit viewport over dimension name', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                screenSizes: {
+                    Mobile: { width: 375, height: 667 },
+                },
+            }));
+            const result = resolveViewportWithProjectDefault({
+                bodyWidth: 800,
+                bodyHeight: 600,
+                dimension: 'Mobile',
+                codeyamRoot: tmpDir,
+            });
+            expect(result).toEqual({ width: 800, height: 600 });
+        });
+        it('should prefer dimension name over project defaultScreenSize', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                defaultScreenSize: { name: 'Desktop', width: 1440, height: 900 },
+                screenSizes: {
+                    Tablet: { width: 768, height: 1024 },
+                },
+            }));
+            const result = resolveViewportWithProjectDefault({
+                dimension: 'Tablet',
+                codeyamRoot: tmpDir,
+            });
+            expect(result).toEqual({ width: 768, height: 1024 });
+        });
+        it('should fall back to defaultScreenSize when dimension name not found in screenSizes', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                defaultScreenSize: { name: 'Desktop', width: 1440, height: 900 },
+                screenSizes: {
+                    Mobile: { width: 375, height: 667 },
+                },
+            }));
+            const result = resolveViewportWithProjectDefault({
+                dimension: 'NonExistent',
+                codeyamRoot: tmpDir,
+            });
+            expect(result).toEqual({ width: 1440, height: 900 });
+        });
+        it('should use inherited viewport from existing scenario instead of chrome-extension project default', () => {
+            // BUG: When re-registering a scenario after a code change, the register
+            // endpoint creates a new DB record. If Claude doesn't pass viewport info,
+            // the resolution falls to defaultScreenSize (chrome-extension size for
+            // extension projects). But the original scenario had desktop viewport.
+            //
+            // FIX: The register endpoint looks up the existing scenario by name and
+            // passes its viewport_width/viewport_height as bodyWidth/bodyHeight,
+            // so the inherited desktop size takes precedence over the project default.
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                defaultScreenSize: { name: 'Popup', width: 400, height: 600 },
+            }));
+            // Without inherited values → falls to chrome-extension default
+            const withoutInherited = resolveViewportWithProjectDefault({
+                codeyamRoot: tmpDir,
+            });
+            expect(withoutInherited).toEqual({ width: 400, height: 600 });
+            // With inherited values from existing scenario → uses desktop size
+            const withInherited = resolveViewportWithProjectDefault({
+                bodyWidth: 1280,
+                bodyHeight: 720,
+                codeyamRoot: tmpDir,
+            });
+            expect(withInherited).toEqual({ width: 1280, height: 720 });
+        });
+        it('should use inherited dimension from existing scenario instead of project default', () => {
+            // Same bug but for dimension-based scenarios: the existing scenario had
+            // dimension "Desktop" stored, and the re-registration should inherit it.
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                defaultScreenSize: { name: 'Popup', width: 400, height: 600 },
+                screenSizes: {
+                    Desktop: { width: 1440, height: 900 },
+                    Popup: { width: 400, height: 600 },
+                },
+            }));
+            // Without inherited dimension → falls to project default (Popup)
+            const withoutInherited = resolveViewportWithProjectDefault({
+                codeyamRoot: tmpDir,
+            });
+            expect(withoutInherited).toEqual({ width: 400, height: 600 });
+            // With inherited dimension from existing scenario → resolves to Desktop
+            const withInherited = resolveViewportWithProjectDefault({
+                dimension: 'Desktop',
+                codeyamRoot: tmpDir,
+            });
+            expect(withInherited).toEqual({ width: 1440, height: 900 });
+        });
+    });
+    describe('readScreenSizes', () => {
+        let tmpDir;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'screen-sizes-test-'));
+            fs.mkdirSync(path.join(tmpDir, '.codeyam'), { recursive: true });
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should return screenSizes map from config', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({
+                screenSizes: {
+                    Desktop: { width: 1440, height: 900 },
+                    Mobile: { width: 375, height: 667 },
+                    Tablet: { width: 768, height: 1024 },
+                },
+            }));
+            const result = readScreenSizes(tmpDir);
+            expect(result).toEqual({
+                Desktop: { width: 1440, height: 900 },
+                Mobile: { width: 375, height: 667 },
+                Tablet: { width: 768, height: 1024 },
+            });
+        });
+        it('should return empty object when no screenSizes in config', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({ projectTitle: 'Test' }));
+            const result = readScreenSizes(tmpDir);
+            expect(result).toEqual({});
+        });
+        it('should return empty object when config file does not exist', () => {
+            const result = readScreenSizes(tmpDir);
+            expect(result).toEqual({});
+        });
+        it('should return empty object when screenSizes is not an object', () => {
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'config.json'), JSON.stringify({ screenSizes: 'invalid' }));
+            const result = readScreenSizes(tmpDir);
+            expect(result).toEqual({});
+        });
+    });
+    describe('upsertEditorScenario', () => {
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            // Create the editor_scenarios table matching the real schema
+            await db.schema
+                .createTable('editor_scenarios')
+                .addColumn('id', 'varchar', (col) => col.primaryKey())
+                .addColumn('project_id', 'varchar', (col) => col.notNull())
+                .addColumn('name', 'varchar', (col) => col.notNull())
+                .addColumn('description', 'text')
+                .addColumn('component_name', 'varchar')
+                .addColumn('component_path', 'varchar')
+                .addColumn('url', 'varchar')
+                .addColumn('type', 'varchar')
+                .addColumn('screenshot_path', 'varchar')
+                .addColumn('viewport_width', 'integer')
+                .addColumn('viewport_height', 'integer')
+                .addColumn('dimension', 'varchar')
+                .addColumn('created_at', 'datetime', (col) => col.defaultTo(new Date().toISOString()))
+                .addColumn('updated_at', 'datetime', (col) => col.defaultTo(new Date().toISOString()))
+                .execute();
+        });
+        afterEach(async () => {
+            await db.destroy();
+        });
+        it('should insert a new scenario when none exists with same name', async () => {
+            const result = await upsertEditorScenario(db, {
+                projectId,
+                name: 'ArticleRow - Default',
+                description: null,
+                componentName: 'ArticleRow',
+                componentPath: 'src/components/ArticleRow.tsx',
+                url: '/isolated-components/ArticleRow?s=Default',
+                type: null,
+                viewportWidth: 1280,
+                viewportHeight: 720,
+                dimension: null,
+            });
+            expect(result.isNew).toBe(true);
+            expect(result.cleanedUpIds).toEqual([]);
+            // Verify exactly 1 row in DB
+            const rows = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .execute();
+            expect(rows).toHaveLength(1);
+            expect(rows[0].id).toBe(result.scenarioId);
+            expect(rows[0].name).toBe('ArticleRow - Default');
+        });
+        it('should update existing scenario instead of creating a duplicate', async () => {
+            // First registration
+            const first = await upsertEditorScenario(db, {
+                projectId,
+                name: 'ArticleRow - Default',
+                description: null,
+                componentName: 'ArticleRow',
+                componentPath: 'src/components/ArticleRow.tsx',
+                url: '/isolated-components/ArticleRow?s=Default',
+                type: null,
+                viewportWidth: 1280,
+                viewportHeight: 720,
+                dimension: null,
+            });
+            // Second registration with same name
+            const second = await upsertEditorScenario(db, {
+                projectId,
+                name: 'ArticleRow - Default',
+                description: 'updated description',
+                componentName: 'ArticleRow',
+                componentPath: 'src/components/ArticleRow.tsx',
+                url: '/isolated-components/ArticleRow?s=Default',
+                type: null,
+                viewportWidth: 800,
+                viewportHeight: 600,
+                dimension: null,
+            });
+            // Should reuse the same ID
+            expect(second.scenarioId).toBe(first.scenarioId);
+            expect(second.isNew).toBe(false);
+            // Should have exactly 1 row, not 2
+            const rows = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .execute();
+            expect(rows).toHaveLength(1);
+            expect(rows[0].description).toBe('updated description');
+            expect(rows[0].viewport_width).toBe(800);
+        });
+        it('should clean up duplicate rows from past always-insert behavior', async () => {
+            // Simulate old behavior: 3 rows with the same name (accumulated duplicates)
+            for (let i = 0; i < 3; i++) {
+                await db
+                    .insertInto('editor_scenarios')
+                    .values({
+                    id: `old-id-${i}`,
+                    project_id: projectId,
+                    name: 'ArticleRow - Default',
+                    url: '/isolated-components/ArticleRow?s=Default',
+                    viewport_width: 1280,
+                    viewport_height: 720,
+                    created_at: new Date(Date.now() + i * 1000).toISOString(),
+                })
+                    .execute();
+            }
+            // Now upsert — should consolidate to 1 row
+            const result = await upsertEditorScenario(db, {
+                projectId,
+                name: 'ArticleRow - Default',
+                description: null,
+                componentName: 'ArticleRow',
+                componentPath: 'src/components/ArticleRow.tsx',
+                url: '/isolated-components/ArticleRow?s=Default',
+                type: null,
+                viewportWidth: 1280,
+                viewportHeight: 720,
+                dimension: null,
+            });
+            expect(result.isNew).toBe(false);
+            // Should return the IDs of cleaned-up duplicates
+            expect(result.cleanedUpIds).toHaveLength(2);
+            // Should have exactly 1 row remaining
+            const rows = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .execute();
+            expect(rows).toHaveLength(1);
+            expect(rows[0].id).toBe(result.scenarioId);
+        });
+        it('should not conflict with scenarios of different names', async () => {
+            await upsertEditorScenario(db, {
+                projectId,
+                name: 'ArticleRow - Default',
+                description: null,
+                componentName: 'ArticleRow',
+                componentPath: 'src/components/ArticleRow.tsx',
+                url: '/isolated-components/ArticleRow?s=Default',
+                type: null,
+                viewportWidth: 1280,
+                viewportHeight: 720,
+                dimension: null,
+            });
+            await upsertEditorScenario(db, {
+                projectId,
+                name: 'ArticleCard - Default',
+                description: null,
+                componentName: 'ArticleCard',
+                componentPath: 'src/components/ArticleCard.tsx',
+                url: '/isolated-components/ArticleCard?s=Default',
+                type: null,
+                viewportWidth: 1280,
+                viewportHeight: 720,
+                dimension: null,
+            });
+            const rows = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .execute();
+            expect(rows).toHaveLength(2);
+        });
+        it('should scope upsert to the same project — different projects can have same scenario name', async () => {
+            const result1 = await upsertEditorScenario(db, {
+                projectId: 'project-a',
+                name: 'Home - Default',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 1280,
+                viewportHeight: 720,
+                dimension: null,
+            });
+            const result2 = await upsertEditorScenario(db, {
+                projectId: 'project-b',
+                name: 'Home - Default',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 1280,
+                viewportHeight: 720,
+                dimension: null,
+            });
+            expect(result1.scenarioId).not.toBe(result2.scenarioId);
+            expect(result1.isNew).toBe(true);
+            expect(result2.isNew).toBe(true);
+            const rows = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .execute();
+            expect(rows).toHaveLength(2);
+        });
+    });
+    describe('cleanupScenarioFiles', () => {
+        let tmpDir;
+        let scenariosDir;
+        let screenshotsDir;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scenario-cleanup-'));
+            scenariosDir = path.join(tmpDir, '.codeyam', 'editor-scenarios');
+            screenshotsDir = path.join(scenariosDir, 'screenshots');
+            fs.mkdirSync(screenshotsDir, { recursive: true });
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should delete .json, .seed.json, and screenshot files for given IDs', () => {
+            // Create files for two scenario IDs
+            fs.writeFileSync(path.join(scenariosDir, 'old-id-1.json'), '{"mock":"data"}');
+            fs.writeFileSync(path.join(scenariosDir, 'old-id-1.seed.json'), '{"seed":"data"}');
+            fs.writeFileSync(path.join(screenshotsDir, 'old-id-1.png'), 'fake-png-data');
+            fs.writeFileSync(path.join(scenariosDir, 'old-id-2.json'), '{"mock":"data2"}');
+            cleanupScenarioFiles(tmpDir, ['old-id-1', 'old-id-2']);
+            expect(fs.existsSync(path.join(scenariosDir, 'old-id-1.json'))).toBe(false);
+            expect(fs.existsSync(path.join(scenariosDir, 'old-id-1.seed.json'))).toBe(false);
+            expect(fs.existsSync(path.join(screenshotsDir, 'old-id-1.png'))).toBe(false);
+            expect(fs.existsSync(path.join(scenariosDir, 'old-id-2.json'))).toBe(false);
+        });
+        it('should not throw when files do not exist', () => {
+            expect(() => cleanupScenarioFiles(tmpDir, ['nonexistent-id'])).not.toThrow();
+        });
+        it('should not delete files for unrelated scenario IDs', () => {
+            fs.writeFileSync(path.join(scenariosDir, 'keep-me.json'), '{"keep":"this"}');
+            cleanupScenarioFiles(tmpDir, ['delete-me']);
+            expect(fs.existsSync(path.join(scenariosDir, 'keep-me.json'))).toBe(true);
+        });
+    });
+    describe('readPreservedConfigProperties', () => {
+        let tmpDir;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'config-preserve-'));
+            fs.mkdirSync(path.join(tmpDir, '.codeyam'), { recursive: true });
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should preserve defaultScreenSize from existing config', () => {
+            const configPath = path.join(tmpDir, '.codeyam', 'config.json');
+            fs.writeFileSync(configPath, JSON.stringify({
+                projectSlug: 'my-project',
+                defaultScreenSize: { name: 'Popup', width: 400, height: 600 },
+                webapps: [],
+            }));
+            const preserved = readPreservedConfigProperties(configPath);
+            expect(preserved.defaultScreenSize).toEqual({
+                name: 'Popup',
+                width: 400,
+                height: 600,
+            });
+        });
+        it('should preserve screenSizes from existing config', () => {
+            const configPath = path.join(tmpDir, '.codeyam', 'config.json');
+            fs.writeFileSync(configPath, JSON.stringify({
+                projectSlug: 'my-project',
+                screenSizes: {
+                    Desktop: { width: 1440, height: 900 },
+                    Mobile: { width: 375, height: 667 },
+                },
+            }));
+            const preserved = readPreservedConfigProperties(configPath);
+            expect(preserved.screenSizes).toEqual({
+                Desktop: { width: 1440, height: 900 },
+                Mobile: { width: 375, height: 667 },
+            });
+        });
+        it('should preserve projectTitle and projectDescription', () => {
+            const configPath = path.join(tmpDir, '.codeyam', 'config.json');
+            fs.writeFileSync(configPath, JSON.stringify({
+                projectSlug: 'my-project',
+                projectTitle: 'My Chrome Extension',
+                projectDescription: 'A cool extension',
+            }));
+            const preserved = readPreservedConfigProperties(configPath);
+            expect(preserved.projectTitle).toBe('My Chrome Extension');
+            expect(preserved.projectDescription).toBe('A cool extension');
+        });
+        it('should preserve all user-configured properties at once', () => {
+            const configPath = path.join(tmpDir, '.codeyam', 'config.json');
+            fs.writeFileSync(configPath, JSON.stringify({
+                projectSlug: 'my-project',
+                packageManager: 'npm',
+                webapps: [],
+                defaultScreenSize: { name: 'Popup', width: 400, height: 600 },
+                screenSizes: { Desktop: { width: 1440, height: 900 } },
+                projectTitle: 'My Chrome Extension',
+                projectDescription: 'A cool extension',
+            }));
+            const preserved = readPreservedConfigProperties(configPath);
+            expect(preserved).toEqual({
+                defaultScreenSize: { name: 'Popup', width: 400, height: 600 },
+                screenSizes: { Desktop: { width: 1440, height: 900 } },
+                projectTitle: 'My Chrome Extension',
+                projectDescription: 'A cool extension',
+            });
+        });
+        it('should NOT preserve auto-detected properties like projectSlug and webapps', () => {
+            const configPath = path.join(tmpDir, '.codeyam', 'config.json');
+            fs.writeFileSync(configPath, JSON.stringify({
+                projectSlug: 'my-project',
+                packageManager: 'npm',
+                webapps: [{ path: '.', framework: 'next' }],
+                createdAt: '2026-01-01',
+                defaultScreenSize: { name: 'Popup', width: 400, height: 600 },
+            }));
+            const preserved = readPreservedConfigProperties(configPath);
+            // Only user-configured properties should survive
+            expect(preserved).toEqual({
+                defaultScreenSize: { name: 'Popup', width: 400, height: 600 },
+            });
+            expect(preserved).not.toHaveProperty('projectSlug');
+            expect(preserved).not.toHaveProperty('packageManager');
+            expect(preserved).not.toHaveProperty('webapps');
+            expect(preserved).not.toHaveProperty('createdAt');
+        });
+        it('should return empty object when config does not exist', () => {
+            const configPath = path.join(tmpDir, '.codeyam', 'nonexistent.json');
+            const preserved = readPreservedConfigProperties(configPath);
+            expect(preserved).toEqual({});
+        });
+        it('should return empty object when config has no preservable properties', () => {
+            const configPath = path.join(tmpDir, '.codeyam', 'config.json');
+            fs.writeFileSync(configPath, JSON.stringify({
+                projectSlug: 'my-project',
+                webapps: [],
+            }));
+            const preserved = readPreservedConfigProperties(configPath);
+            expect(preserved).toEqual({});
+        });
+        it('should return empty object when config is invalid JSON', () => {
+            const configPath = path.join(tmpDir, '.codeyam', 'config.json');
+            fs.writeFileSync(configPath, 'not valid json');
+            const preserved = readPreservedConfigProperties(configPath);
+            expect(preserved).toEqual({});
+        });
+    });
+    describe('validateStepTransition', () => {
+        it('should allow step 1 with no current state', () => {
+            expect(validateStepTransition(1, null)).toBeNull();
+        });
+        it('should allow step 1 even when on a later step (restart)', () => {
+            expect(validateStepTransition(1, 5)).toBeNull();
+        });
+        it('should allow advancing to the next step', () => {
+            expect(validateStepTransition(2, 1)).toBeNull();
+            expect(validateStepTransition(3, 2)).toBeNull();
+            expect(validateStepTransition(13, 12)).toBeNull();
+        });
+        it('should allow re-running the current step', () => {
+            expect(validateStepTransition(3, 3)).toBeNull();
+            expect(validateStepTransition(7, 7)).toBeNull();
+        });
+        it('should allow going back to a previous step', () => {
+            expect(validateStepTransition(3, 5)).toBeNull();
+        });
+        it('should reject skipping steps forward', () => {
+            const err = validateStepTransition(5, 2);
+            expect(err).not.toBeNull();
+            expect(err).toContain('step 2');
+            expect(err).toContain('step 5');
+        });
+        it('should reject jumping to step 13 from step 3', () => {
+            const err = validateStepTransition(13, 3);
+            expect(err).not.toBeNull();
+            expect(err).toContain('step 4');
+        });
+        it('should reject step 2 with no current state', () => {
+            const err = validateStepTransition(2, null);
+            expect(err).not.toBeNull();
+            expect(err).toContain('step 1');
+        });
+        it('should reject step 13 with no current state', () => {
+            const err = validateStepTransition(13, null);
+            expect(err).not.toBeNull();
+        });
+    });
+});
+//# sourceMappingURL=editorScenarios.test.js.map