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

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

@@ -1,7 +1,9 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { deduplicateByName, generateScenarioSlug, convertIsoToSqliteTimestamp, determineCaptureUrl, resolvePreviewNavPath, clearEditorState, clearEditorUserPrompt, } from "../editorScenarios.js";
+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, slugifyDimension, isRowInFeatureSession, backfillEntityShaOnScenarios, countScenariosNeedingEntityBackfill, validateEntityLinkageForAppScenario, validateScenarioCategorization, resolveSeedFrom, } from "../editorScenarios.js";
 describe('editorScenarios', () => {
     describe('deduplicateByName', () => {
         it('should keep only the last item for each key', () => {
@@ -217,5 +219,1550 @@ describe('editorScenarios', () => {
             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,
+            });
+            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,
+            });
+            // 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,
+            });
+            // 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,
+            });
+            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,
+            });
+            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,
+            });
+            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,
+            });
+            const result2 = await upsertEditorScenario(db, {
+                projectId: 'project-b',
+                name: 'Home - Default',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 1280,
+                viewportHeight: 720,
+            });
+            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('slugifyDimension', () => {
+        it('should lowercase and replace spaces with hyphens', () => {
+            expect(slugifyDimension('Extension Popup')).toBe('extension-popup');
+        });
+        it('should strip non-alphanumeric characters', () => {
+            expect(slugifyDimension('Desktop (Large)')).toBe('desktop-large');
+        });
+        it('should collapse multiple hyphens', () => {
+            expect(slugifyDimension('My -- Screen')).toBe('my-screen');
+        });
+        it('should handle simple names', () => {
+            expect(slugifyDimension('Desktop')).toBe('desktop');
+            expect(slugifyDimension('Mobile')).toBe('mobile');
+        });
+        it('should handle empty string', () => {
+            expect(slugifyDimension('')).toBe('');
+        });
+        it('should trim leading/trailing hyphens', () => {
+            expect(slugifyDimension(' Mobile ')).toBe('mobile');
+        });
+    });
+    describe('upsertEditorScenario with dimensions', () => {
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            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('dimensions', 'text')
+                .addColumn('screenshot_paths', 'text')
+                .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 store dimensions as JSON array', async () => {
+            const result = await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home Page',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 1440,
+                viewportHeight: 900,
+                dimensions: ['Desktop', 'Mobile'],
+                screenshotPaths: null,
+            });
+            const row = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .where('id', '=', result.scenarioId)
+                .executeTakeFirst();
+            expect(row).toBeDefined();
+            expect(JSON.parse(row.dimensions)).toEqual([
+                'Desktop',
+                'Mobile',
+            ]);
+        });
+        it('should store screenshot_paths as JSON object', async () => {
+            const screenshotPaths = {
+                Desktop: 'screenshots/abc--desktop.png',
+                Mobile: 'screenshots/abc--mobile.png',
+            };
+            const result = await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home Page',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 1440,
+                viewportHeight: 900,
+                dimensions: ['Desktop', 'Mobile'],
+                screenshotPaths,
+            });
+            const row = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .where('id', '=', result.scenarioId)
+                .executeTakeFirst();
+            expect(JSON.parse(row.screenshot_paths)).toEqual(screenshotPaths);
+        });
+        it('should update dimensions and screenshot_paths on re-registration', async () => {
+            const first = await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home Page',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 1440,
+                viewportHeight: 900,
+                dimensions: ['Desktop'],
+                screenshotPaths: { Desktop: 'screenshots/old--desktop.png' },
+            });
+            const second = await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home Page',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 1440,
+                viewportHeight: 900,
+                dimensions: ['Desktop', 'Mobile'],
+                screenshotPaths: {
+                    Desktop: 'screenshots/new--desktop.png',
+                    Mobile: 'screenshots/new--mobile.png',
+                },
+            });
+            expect(second.scenarioId).toBe(first.scenarioId);
+            const row = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .where('id', '=', second.scenarioId)
+                .executeTakeFirst();
+            expect(JSON.parse(row.dimensions)).toEqual([
+                'Desktop',
+                'Mobile',
+            ]);
+            expect(JSON.parse(row.screenshot_paths)).toEqual({
+                Desktop: 'screenshots/new--desktop.png',
+                Mobile: 'screenshots/new--mobile.png',
+            });
+        });
+        it('should handle null dimensions gracefully (backward compat)', async () => {
+            const result = await upsertEditorScenario(db, {
+                projectId,
+                name: 'Legacy Scenario',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: null,
+                viewportWidth: 1280,
+                viewportHeight: 720,
+            });
+            const row = await db
+                .selectFrom('editor_scenarios')
+                .selectAll()
+                .where('id', '=', result.scenarioId)
+                .executeTakeFirst();
+            expect(row.dimensions).toBeNull();
+            expect(row.screenshot_paths).toBeNull();
+        });
+    });
+    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();
+        });
+        it('should allow advancing from step 13 to step 14', () => {
+            expect(validateStepTransition(14, 13)).toBeNull();
+        });
+        it('should allow advancing from step 14 to step 15', () => {
+            expect(validateStepTransition(15, 14)).toBeNull();
+        });
+        it('should allow advancing from step 15 to step 16', () => {
+            expect(validateStepTransition(16, 15)).toBeNull();
+        });
+        it('should reject skipping from step 13 to step 15', () => {
+            const err = validateStepTransition(15, 13);
+            expect(err).not.toBeNull();
+            expect(err).toContain('step 14');
+        });
+        it('should reject rapid-fire advance when step started < 3s ago', () => {
+            const recentStart = new Date(Date.now() - 1000).toISOString(); // 1s ago
+            const err = validateStepTransition(4, 3, recentStart);
+            expect(err).not.toBeNull();
+            expect(err).toContain('only 1s ago');
+            expect(err).toContain('checklist');
+        });
+        it('should allow advance when step started > 3s ago', () => {
+            const oldStart = new Date(Date.now() - 5000).toISOString(); // 5s ago
+            expect(validateStepTransition(4, 3, oldStart)).toBeNull();
+        });
+        it('should not enforce time guard on step 1 → 2 transition', () => {
+            const recentStart = new Date(Date.now() - 2000).toISOString();
+            // currentStep=1, so guard only applies for currentStep >= 2
+            expect(validateStepTransition(2, 1, recentStart)).toBeNull();
+        });
+        it('should not enforce time guard when re-running the same step', () => {
+            const recentStart = new Date(Date.now() - 2000).toISOString();
+            expect(validateStepTransition(5, 5, recentStart)).toBeNull();
+        });
+    });
+    describe('isRowInFeatureSession', () => {
+        const featureStart = '2026-03-12 14:01:31';
+        it('should include row created after feature start', () => {
+            expect(isRowInFeatureSession({ created_at: '2026-03-12 14:30:00' }, featureStart)).toBe(true);
+        });
+        it('should exclude row created before feature start with no updated_at', () => {
+            expect(isRowInFeatureSession({ created_at: '2026-03-12 13:00:00' }, featureStart)).toBe(false);
+        });
+        it('should include re-registered row with old created_at but recent updated_at', () => {
+            // This is the bug: application-level scenarios from a previous feature
+            // are re-registered, which only updates updated_at. The session filter
+            // must check updated_at too, otherwise these scenarios vanish from results.
+            expect(isRowInFeatureSession({
+                created_at: '2026-03-12 13:28:00',
+                updated_at: '2026-03-12 14:32:00',
+            }, featureStart)).toBe(true);
+        });
+        it('should exclude row with both timestamps before feature start', () => {
+            expect(isRowInFeatureSession({
+                created_at: '2026-03-12 13:00:00',
+                updated_at: '2026-03-12 13:30:00',
+            }, featureStart)).toBe(false);
+        });
+        it('should handle null created_at with recent updated_at', () => {
+            expect(isRowInFeatureSession({ created_at: null, updated_at: '2026-03-12 14:32:00' }, featureStart)).toBe(true);
+        });
+        it('should handle null updated_at with recent created_at', () => {
+            expect(isRowInFeatureSession({ created_at: '2026-03-12 14:30:00', updated_at: null }, featureStart)).toBe(true);
+        });
+    });
+    describe('upsertEditorScenario with entitySha and displayName', () => {
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            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('dimensions', 'text')
+                .addColumn('screenshot_paths', 'text')
+                .addColumn('page_file_path', 'varchar')
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('display_name', '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 store entitySha and displayName on insert', async () => {
+            const result = await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home - Default',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 400,
+                viewportHeight: 600,
+                entitySha: 'abc123',
+                displayName: 'Home',
+            });
+            expect(result.isNew).toBe(true);
+            const row = rawDb
+                .prepare('SELECT entity_sha, display_name FROM editor_scenarios WHERE id = ?')
+                .get(result.scenarioId);
+            expect(row.entity_sha).toBe('abc123');
+            expect(row.display_name).toBe('Home');
+        });
+        it('should update entitySha and displayName on upsert', async () => {
+            // Insert first
+            await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home - Default',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 400,
+                viewportHeight: 600,
+                entitySha: 'old-sha',
+                displayName: 'OldName',
+            });
+            // Upsert with new values
+            const result = await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home - Default',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 400,
+                viewportHeight: 600,
+                entitySha: 'new-sha',
+                displayName: 'Home',
+            });
+            expect(result.isNew).toBe(false);
+            const row = rawDb
+                .prepare('SELECT entity_sha, display_name FROM editor_scenarios WHERE id = ?')
+                .get(result.scenarioId);
+            expect(row.entity_sha).toBe('new-sha');
+            expect(row.display_name).toBe('Home');
+        });
+        it('should not overwrite entitySha when not provided', async () => {
+            // Insert with SHA
+            const first = await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home - Default',
+                description: null,
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 400,
+                viewportHeight: 600,
+                entitySha: 'keep-this',
+                displayName: 'Home',
+            });
+            // Upsert without entitySha/displayName
+            await upsertEditorScenario(db, {
+                projectId,
+                name: 'Home - Default',
+                description: 'updated',
+                componentName: null,
+                componentPath: null,
+                url: '/',
+                type: 'application',
+                viewportWidth: 400,
+                viewportHeight: 600,
+            });
+            const row = rawDb
+                .prepare('SELECT entity_sha, display_name FROM editor_scenarios WHERE id = ?')
+                .get(first.scenarioId);
+            expect(row.entity_sha).toBe('keep-this');
+            expect(row.display_name).toBe('Home');
+        });
+    });
+    describe('backfillEntityShaOnScenarios', () => {
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            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('dimensions', 'text')
+                .addColumn('screenshot_paths', 'text')
+                .addColumn('page_file_path', 'varchar')
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('display_name', '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 backfill component scenario by component_path match', async () => {
+            // Insert a scenario with null entity_sha but with component_path
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, component_name, component_path, url, type, viewport_width, viewport_height)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-1', projectId, 'Header - Default', 'Header', 'src/components/Header.tsx', '/isolated-components/Header', 'component', 1280, 720);
+            const result = await backfillEntityShaOnScenarios(db, [
+                {
+                    sha: 'entity-sha-1',
+                    name: 'Header',
+                    filePath: 'src/components/Header.tsx',
+                },
+            ]);
+            expect(result.updated).toBe(1);
+            const row = rawDb
+                .prepare('SELECT entity_sha, display_name FROM editor_scenarios WHERE id = ?')
+                .get('sc-1');
+            expect(row.entity_sha).toBe('entity-sha-1');
+            expect(row.display_name).toBe('Header');
+        });
+        it('should backfill page scenario by page_file_path match and derive display_name from route', async () => {
+            // Insert a scenario with null entity_sha but with page_file_path
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, page_file_path, url, type, viewport_width, viewport_height)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-2', projectId, 'Feedback - Default', 'app/feedback/page.tsx', '/feedback', 'application', 1280, 720);
+            const result = await backfillEntityShaOnScenarios(db, [
+                {
+                    sha: 'entity-sha-2',
+                    name: 'Feedback',
+                    filePath: 'app/feedback/page.tsx',
+                },
+            ]);
+            expect(result.updated).toBe(1);
+            const row = rawDb
+                .prepare('SELECT entity_sha, display_name FROM editor_scenarios WHERE id = ?')
+                .get('sc-2');
+            expect(row.entity_sha).toBe('entity-sha-2');
+            // display_name derived from page_file_path via routeDisplayName(buildRoutePattern())
+            expect(row.display_name).toBe('Feedback');
+        });
+        it('should update scenarios with stale entity_sha to latest', async () => {
+            // Margo bug: entity code changes create new versions with new SHAs,
+            // but scenarios still point to the old SHA. Since journals preserve
+            // screenshots and everything is in git, we always want scenarios
+            // pointing to the latest entity version.
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, component_name, component_path, url, type, viewport_width, viewport_height, entity_sha, display_name)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-3', projectId, 'Header - Dark', 'Header', 'src/components/Header.tsx', '/isolated-components/Header', 'component', 1280, 720, 'old-sha', 'Header');
+            const result = await backfillEntityShaOnScenarios(db, [
+                {
+                    sha: 'latest-sha',
+                    name: 'Header',
+                    filePath: 'src/components/Header.tsx',
+                },
+            ]);
+            expect(result.updated).toBe(1);
+            const row = rawDb
+                .prepare('SELECT entity_sha FROM editor_scenarios WHERE id = ?')
+                .get('sc-3');
+            expect(row.entity_sha).toBe('latest-sha');
+        });
+        it('should not update scenarios already pointing to the latest SHA', async () => {
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, component_name, component_path, url, type, viewport_width, viewport_height, entity_sha, display_name)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-3b', projectId, 'Header - Dark', 'Header', 'src/components/Header.tsx', '/isolated-components/Header', 'component', 1280, 720, 'current-sha', 'Header');
+            const result = await backfillEntityShaOnScenarios(db, [
+                {
+                    sha: 'current-sha',
+                    name: 'Header',
+                    filePath: 'src/components/Header.tsx',
+                },
+            ]);
+            expect(result.updated).toBe(0);
+        });
+        it('should skip scenarios with no matching entity', async () => {
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, component_name, component_path, url, type, viewport_width, viewport_height)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-4', projectId, 'Footer - Default', 'Footer', 'src/components/Footer.tsx', '/isolated-components/Footer', 'component', 1280, 720);
+            // Entities list doesn't include Footer.tsx
+            const result = await backfillEntityShaOnScenarios(db, [
+                {
+                    sha: 'entity-sha-1',
+                    name: 'Header',
+                    filePath: 'src/components/Header.tsx',
+                },
+            ]);
+            expect(result.updated).toBe(0);
+            const row = rawDb
+                .prepare('SELECT entity_sha FROM editor_scenarios WHERE id = ?')
+                .get('sc-4');
+            expect(row.entity_sha).toBeNull();
+        });
+        it('should match component scenarios by name+path, not just path (multi-entity files)', async () => {
+            // A single file can export multiple components (e.g., FullPageLibrary.tsx
+            // exports FullPageLibrary, FullPageEmptyState, FullPageArticleCard).
+            // Each component scenario should get the SHA for its specific entity,
+            // not whichever entity happens to be last in the map.
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, component_name, component_path, url, type, viewport_width, viewport_height, entity_sha)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-fplib', projectId, 'FullPageLibrary - Default', 'FullPageLibrary', 'src/library/FullPageLibrary.tsx', '/isolated-components/FullPageLibrary', 'component', 1280, 720, 'old-fplib-sha');
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, component_name, component_path, url, type, viewport_width, viewport_height, entity_sha)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-fpempty', projectId, 'FullPageEmptyState - Default', 'FullPageEmptyState', 'src/library/FullPageLibrary.tsx', '/isolated-components/FullPageEmptyState', 'component', 1280, 720, 'old-fpempty-sha');
+            const result = await backfillEntityShaOnScenarios(db, [
+                {
+                    sha: 'new-fplib-sha',
+                    name: 'FullPageLibrary',
+                    filePath: 'src/library/FullPageLibrary.tsx',
+                },
+                {
+                    sha: 'new-fpempty-sha',
+                    name: 'FullPageEmptyState',
+                    filePath: 'src/library/FullPageLibrary.tsx',
+                },
+            ]);
+            expect(result.updated).toBe(2);
+            const fplib = rawDb
+                .prepare('SELECT entity_sha FROM editor_scenarios WHERE id = ?')
+                .get('sc-fplib');
+            expect(fplib.entity_sha).toBe('new-fplib-sha');
+            const fpempty = rawDb
+                .prepare('SELECT entity_sha FROM editor_scenarios WHERE id = ?')
+                .get('sc-fpempty');
+            expect(fpempty.entity_sha).toBe('new-fpempty-sha');
+        });
+        it('should prefer default export entity for page scenarios when file has multiple entities', async () => {
+            // Bug: src/popup/App.tsx has multiple entities (App visual, getInitialView library,
+            // View type). Page scenarios should link to the default export (App), not whichever
+            // entity happens to come first in the array.
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, page_file_path, url, type, viewport_width, viewport_height)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-page-1', projectId, 'Save View - First Time User', 'src/popup/App.tsx', '/', 'application', 400, 600);
+            // Pass multiple entities for the same file — default export should win
+            // regardless of order. Here the default export (App) appears first but
+            // gets overwritten by later non-default entities in the naive set() impl.
+            const result = await backfillEntityShaOnScenarios(db, [
+                {
+                    sha: 'app-sha',
+                    name: 'App',
+                    filePath: 'src/popup/App.tsx',
+                    isDefaultExport: true,
+                },
+                {
+                    sha: 'get-initial-view-sha',
+                    name: 'getInitialView',
+                    filePath: 'src/popup/App.tsx',
+                    isDefaultExport: false,
+                },
+                {
+                    sha: 'view-type-sha',
+                    name: 'View',
+                    filePath: 'src/popup/App.tsx',
+                    isDefaultExport: false,
+                },
+            ]);
+            expect(result.updated).toBe(1);
+            const row = rawDb
+                .prepare('SELECT entity_sha FROM editor_scenarios WHERE id = ?')
+                .get('sc-page-1');
+            expect(row.entity_sha).toBe('app-sha');
+        });
+        it('should update page scenario to latest entity version when multiple versions exist', async () => {
+            // Real-world bug: App.tsx entity gets versioned (code changes create new SHAs).
+            // The scenario points to the oldest version's SHA. When sync receives all 3
+            // versions of the same default-export entity, it should update the scenario
+            // to the LATEST version, not keep it stuck on the oldest.
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, page_file_path, url, type, viewport_width, viewport_height, entity_sha, display_name)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-home', projectId, 'Welcome Screen — First Install', 'src/popup/App.tsx', '/', 'application', 400, 600, 'version-1-sha', // stale — points to oldest version
+            'Home');
+            // Pass all 3 versions — all default exports for the same file.
+            // The sync should pick the LAST one (latest) since callers pass
+            // entities in creation order.
+            const result = await backfillEntityShaOnScenarios(db, [
+                {
+                    sha: 'version-1-sha',
+                    name: 'App',
+                    filePath: 'src/popup/App.tsx',
+                    isDefaultExport: true,
+                },
+                {
+                    sha: 'version-2-sha',
+                    name: 'App',
+                    filePath: 'src/popup/App.tsx',
+                    isDefaultExport: true,
+                },
+                {
+                    sha: 'version-3-sha',
+                    name: 'App',
+                    filePath: 'src/popup/App.tsx',
+                    isDefaultExport: true,
+                },
+            ]);
+            expect(result.updated).toBe(1);
+            const row = rawDb
+                .prepare('SELECT entity_sha FROM editor_scenarios WHERE id = ?')
+                .get('sc-home');
+            expect(row.entity_sha).toBe('version-3-sha');
+        });
+    });
+    describe('countScenariosNeedingEntityBackfill', () => {
+        let db;
+        let rawDb;
+        const projectId = 'test-project-id';
+        beforeEach(async () => {
+            rawDb = new Database(':memory:');
+            db = new Kysely({ dialect: new SqliteDialect({ database: rawDb }) });
+            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('dimensions', 'text')
+                .addColumn('screenshot_paths', 'text')
+                .addColumn('page_file_path', 'varchar')
+                .addColumn('entity_sha', 'varchar')
+                .addColumn('display_name', '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 NOT count scenarios that already have entity_sha', async () => {
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, component_name, component_path, url, type, viewport_width, viewport_height, entity_sha)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-1', projectId, 'Header - Default', 'Header', 'src/components/Header.tsx', '/isolated-components/Header', 'component', 1280, 720, 'existing-sha');
+            const count = await countScenariosNeedingEntityBackfill(db);
+            expect(count).toBe(0);
+        });
+        it('should count scenarios with null entity_sha and page_file_path', async () => {
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, page_file_path, url, type, viewport_width, viewport_height)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-2', projectId, 'Home - Default', 'app/page.tsx', '/', 'application', 1280, 720);
+            const count = await countScenariosNeedingEntityBackfill(db);
+            expect(count).toBe(1);
+        });
+        it('should count scenarios with null entity_sha and component_path', async () => {
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, component_name, component_path, url, type, viewport_width, viewport_height)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-3', projectId, 'Footer - Default', 'Footer', 'src/components/Footer.tsx', '/isolated-components/Footer', 'component', 1280, 720);
+            const count = await countScenariosNeedingEntityBackfill(db);
+            expect(count).toBe(1);
+        });
+        it('should NOT count scenarios with null entity_sha and no file paths', async () => {
+            rawDb
+                .prepare(`INSERT INTO editor_scenarios (id, project_id, name, url, type, viewport_width, viewport_height)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                .run('sc-4', projectId, 'No File Path', '/', 'application', 1280, 720);
+            const count = await countScenariosNeedingEntityBackfill(db);
+            expect(count).toBe(0);
+        });
+    });
+    describe('validateEntityLinkageForAppScenario', () => {
+        let tmpDir;
+        let glossaryPath;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'entity-linkage-'));
+            const codeyamDir = path.join(tmpDir, '.codeyam');
+            fs.mkdirSync(codeyamDir, { recursive: true });
+            glossaryPath = path.join(codeyamDir, 'glossary.json');
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should return error when file is not in glossary', () => {
+            // Write a glossary that does NOT include the target file
+            fs.writeFileSync(glossaryPath, JSON.stringify([
+                { name: 'Header', filePath: 'src/components/Header.tsx' },
+            ]));
+            const result = validateEntityLinkageForAppScenario({
+                lookupFilePath: 'src/App.tsx',
+                scenarioType: 'application',
+                projectRoot: tmpDir,
+            });
+            expect(result.valid).toBe(false);
+            expect(result.error).toContain('No glossary entry found');
+            expect(result.error).toContain('src/App.tsx');
+        });
+        it('should return needsAnalysis when file IS in glossary but no entity exists', () => {
+            // Write a glossary that includes the target file
+            fs.writeFileSync(glossaryPath, JSON.stringify([
+                { name: 'App', filePath: 'src/App.tsx', description: 'Main app' },
+            ]));
+            const result = validateEntityLinkageForAppScenario({
+                lookupFilePath: 'src/App.tsx',
+                scenarioType: 'application',
+                projectRoot: tmpDir,
+            });
+            expect(result.valid).toBe(true);
+            expect(result.needsAnalysis).toBe(true);
+        });
+        it('should skip validation for component-type scenarios', () => {
+            // No glossary file exists at all
+            const result = validateEntityLinkageForAppScenario({
+                lookupFilePath: 'src/components/Header.tsx',
+                scenarioType: 'component',
+                projectRoot: tmpDir,
+            });
+            expect(result.valid).toBe(true);
+            expect(result.needsAnalysis).toBeUndefined();
+        });
+        it('should skip validation when lookupFilePath is null', () => {
+            const result = validateEntityLinkageForAppScenario({
+                lookupFilePath: null,
+                scenarioType: 'application',
+                projectRoot: tmpDir,
+            });
+            expect(result.valid).toBe(true);
+            expect(result.needsAnalysis).toBeUndefined();
+        });
+        it('should handle glossary wrapped in object format', () => {
+            // LLMs sometimes write glossary as {"components": [...]}
+            fs.writeFileSync(glossaryPath, JSON.stringify({
+                components: [
+                    { name: 'App', filePath: 'src/App.tsx', description: 'Main app' },
+                ],
+            }));
+            const result = validateEntityLinkageForAppScenario({
+                lookupFilePath: 'src/App.tsx',
+                scenarioType: 'user',
+                projectRoot: tmpDir,
+            });
+            expect(result.valid).toBe(true);
+            expect(result.needsAnalysis).toBe(true);
+        });
+        it('should return error when glossary file does not exist', () => {
+            // Don't create a glossary file
+            const result = validateEntityLinkageForAppScenario({
+                lookupFilePath: 'src/App.tsx',
+                scenarioType: 'application',
+                projectRoot: tmpDir,
+            });
+            expect(result.valid).toBe(false);
+            expect(result.error).toContain('No glossary entry found');
+        });
+    });
+    describe('validateScenarioCategorization', () => {
+        it('should reject componentName with non-isolation URL', () => {
+            const result = validateScenarioCategorization({
+                componentName: 'Library',
+                url: '/library',
+            });
+            expect(result.valid).toBe(false);
+            expect(result.error).toBeDefined();
+            expect(result.error).toContain('componentName');
+        });
+        it('should accept componentName with /isolated-components/ URL', () => {
+            const result = validateScenarioCategorization({
+                componentName: 'Library',
+                url: '/isolated-components/Library?s=Default',
+            });
+            expect(result.valid).toBe(true);
+        });
+        it('should accept componentName with /codeyam-isolate/ URL', () => {
+            const result = validateScenarioCategorization({
+                componentName: 'Library',
+                url: '/codeyam-isolate/Library?s=Default',
+            });
+            expect(result.valid).toBe(true);
+        });
+        it('should accept application scenario without componentName', () => {
+            const result = validateScenarioCategorization({
+                url: '/library',
+                type: 'application',
+            });
+            expect(result.valid).toBe(true);
+        });
+        it('should accept component with no URL', () => {
+            const result = validateScenarioCategorization({
+                componentName: 'Library',
+                url: null,
+            });
+            expect(result.valid).toBe(true);
+        });
+        it('should suggest both fixes in error message', () => {
+            const result = validateScenarioCategorization({
+                componentName: 'Library',
+                url: '/library',
+            });
+            expect(result.valid).toBe(false);
+            // Should suggest changing URL to isolation route
+            expect(result.error).toContain('/isolated-components/');
+            // Should suggest removing componentName
+            expect(result.error).toContain('remove');
+        });
+    });
+    describe('resolveSeedFrom', () => {
+        let tmpDir;
+        let db;
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'seedfrom-'));
+            fs.mkdirSync(path.join(tmpDir, '.codeyam', 'editor-scenarios'), {
+                recursive: true,
+            });
+            const raw = new Database(':memory:');
+            raw.exec(`
+        CREATE TABLE editor_scenarios (
+          id TEXT PRIMARY KEY,
+          project_id TEXT,
+          name TEXT,
+          description TEXT,
+          component_name TEXT,
+          component_path TEXT,
+          url TEXT,
+          type TEXT,
+          screenshot_path TEXT,
+          viewport_width INTEGER,
+          viewport_height INTEGER,
+          dimensions TEXT,
+          screenshot_paths TEXT,
+          page_file_path TEXT,
+          entity_sha TEXT,
+          display_name TEXT,
+          created_at TEXT DEFAULT (datetime('now')),
+          updated_at TEXT DEFAULT (datetime('now'))
+        )
+      `);
+            db = new Kysely({ dialect: new SqliteDialect({ database: raw }) });
+        });
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+        it('should resolve seed data by scenario ID', async () => {
+            const scenarioId = 'aaaa-bbbb-cccc-dddd';
+            const seedData = { article: [{ id: '1', title: 'Test' }] };
+            // Write the seed file
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${scenarioId}.seed.json`), JSON.stringify(seedData));
+            const result = await resolveSeedFrom(tmpDir, db, scenarioId);
+            expect(result).toEqual(seedData);
+        });
+        it('should resolve seed data by scenario name', async () => {
+            const scenarioId = 'eeee-ffff-1111-2222';
+            const seedData = { user: [{ id: '1', name: 'Alice' }] };
+            // Write the seed file
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${scenarioId}.seed.json`), JSON.stringify(seedData));
+            // Insert scenario into DB so name lookup works
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: scenarioId,
+                project_id: 'proj-1',
+                name: 'Library - Rich Data',
+                viewport_width: 1280,
+                viewport_height: 720,
+            })
+                .execute();
+            const result = await resolveSeedFrom(tmpDir, db, 'Library - Rich Data');
+            expect(result).toEqual(seedData);
+        });
+        it('should fall back to seed from scenario data file when no .seed.json exists', async () => {
+            const scenarioId = 'cccc-dddd-eeee-ffff';
+            const seedData = { tag: [{ id: '1', name: 'AI' }] };
+            // Write the scenario data file (not the .seed.json)
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${scenarioId}.json`), JSON.stringify({ seed: seedData, _metadata: { name: 'Test' } }));
+            const result = await resolveSeedFrom(tmpDir, db, scenarioId);
+            expect(result).toEqual(seedData);
+        });
+        it('should return null when scenario not found', async () => {
+            const result = await resolveSeedFrom(tmpDir, db, 'nonexistent');
+            expect(result).toBeNull();
+        });
+        it('should return null when scenario exists but has no seed data', async () => {
+            const scenarioId = 'no-seed-1111-2222';
+            // Scenario data file with no seed
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${scenarioId}.json`), JSON.stringify({ _metadata: { name: 'No Seed' } }));
+            const result = await resolveSeedFrom(tmpDir, db, scenarioId);
+            expect(result).toBeNull();
+        });
+        it('should return null when seed.json contains invalid JSON', async () => {
+            const scenarioId = 'bad-json-1111';
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${scenarioId}.seed.json`), '{ this is not valid json }}}');
+            const result = await resolveSeedFrom(tmpDir, db, scenarioId);
+            expect(result).toBeNull();
+        });
+        it('should return null when scenario data file contains invalid JSON', async () => {
+            const scenarioId = 'bad-data-2222';
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${scenarioId}.json`), 'not json at all');
+            const result = await resolveSeedFrom(tmpDir, db, scenarioId);
+            expect(result).toBeNull();
+        });
+        it('should pick the most recent scenario when multiple share the same name', async () => {
+            const oldId = 'old-scenario-1111';
+            const newId = 'new-scenario-2222';
+            const oldSeed = { article: [{ id: '1', title: 'Old' }] };
+            const newSeed = { article: [{ id: '2', title: 'New' }] };
+            // Write seed files for both
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${oldId}.seed.json`), JSON.stringify(oldSeed));
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${newId}.seed.json`), JSON.stringify(newSeed));
+            // Insert both with the same name, different created_at
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: oldId,
+                project_id: 'proj-1',
+                name: 'Shared Name',
+                viewport_width: 1280,
+                viewport_height: 720,
+                created_at: '2026-01-01 00:00:00',
+            })
+                .execute();
+            await db
+                .insertInto('editor_scenarios')
+                .values({
+                id: newId,
+                project_id: 'proj-1',
+                name: 'Shared Name',
+                viewport_width: 1280,
+                viewport_height: 720,
+                created_at: '2026-03-01 00:00:00',
+            })
+                .execute();
+            const result = await resolveSeedFrom(tmpDir, db, 'Shared Name');
+            expect(result).toEqual(newSeed);
+        });
+        it('should prefer .seed.json over inline seed in data file', async () => {
+            const scenarioId = 'prefer-seed-file';
+            const seedFileData = { article: [{ id: '1', title: 'From seed file' }] };
+            const inlineData = { article: [{ id: '2', title: 'From inline' }] };
+            // Write both files
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${scenarioId}.seed.json`), JSON.stringify(seedFileData));
+            fs.writeFileSync(path.join(tmpDir, '.codeyam', 'editor-scenarios', `${scenarioId}.json`), JSON.stringify({ seed: inlineData }));
+            const result = await resolveSeedFrom(tmpDir, db, scenarioId);
+            expect(result).toEqual(seedFileData);
+        });
+    });
 });
 //# sourceMappingURL=editorScenarios.test.js.map