@codeyam/codeyam-cli 0.1.9 → 0.1.11

package/codeyam-cli/src/commands/editor.js

@@ -11,11 +11,11 @@ import { IS_INTERNAL_BUILD } from "../utils/buildFlags.js";
 import { startBackgroundServer } from "../utils/backgroundServer.js";
 import { installClaudeCodeSkills } from "../utils/install-skills.js";
 import { setupClaudeCodeSettings } from "../utils/setupClaudeCodeSettings.js";
-import { ensureAnalyzerFinalized } from "../utils/analyzerFinalization.js";
+import { ensureAnalyzerFinalized, } from "../utils/analyzerFinalization.js";
 import { APP_FORMATS, TECH_STACKS } from "../data/techStacks.js";
 import { getProjectRoot as getStateProjectRoot } from "../state.js";
 import initCommand from "./init.js";
-import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, } from "../utils/scenariosManifest.js";
+import { scanScenarioFiles, syncScenarioFilesToDatabase, backfillScenarioMetadata, migrateScenarioFormats, } from "../utils/scenariosManifest.js";
 import { clearEditorState, clearEditorUserPrompt, validateStepTransition, } from "../utils/editorScenarios.js";
 import { validateSeedData, detectSeedAdapter, } from "../utils/editorSeedAdapter.js";
 import { buildEditorApiRequest, callEditorApi, EDITOR_API_SUBCOMMANDS, } from "../utils/editorApi.js";
@@ -143,6 +143,39 @@ function getServerPort() {
     }
     return process.env.CODEYAM_PORT || '3111';
 }
+/**
+ * Read the project's default dimension name and available screen size names.
+ * Used by step instructions to show project-specific dimension examples
+ * instead of hardcoded "Desktop".
+ */
+function getProjectDimensions(root) {
+    try {
+        const configPath = path.join(root, '.codeyam', 'config.json');
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const defaultName = config.defaultScreenSize?.name ||
+            (config.screenSizes ? Object.keys(config.screenSizes)[0] : null) ||
+            'Desktop';
+        const names = config.screenSizes ? Object.keys(config.screenSizes) : [];
+        return { defaultName, names };
+    }
+    catch {
+        return { defaultName: 'Desktop', names: [] };
+    }
+}
+/**
+ * Print dimension guidance when the project has multiple screen sizes.
+ * Tells Claude to pick the right dimension for the content being previewed
+ * instead of blindly using the default for everything.
+ */
+function printDimensionGuidance(defaultName, names) {
+    if (names.length <= 1)
+        return;
+    // Find a non-default dimension to suggest as the "other" option
+    const otherName = names.find((n) => n !== defaultName) || names[1];
+    console.log(chalk.yellow(`  IMPORTANT: Choose the dimension that matches what you're previewing. Available: ${names.map((n) => `"${n}"`).join(', ')}.`));
+    console.log(chalk.yellow(`  Do NOT always use "${defaultName}". Full pages, standalone views, and desktop layouts should use "${otherName}".`));
+    console.log(chalk.yellow(`  Think about the CONTENT — a full-page library view needs a large viewport, not a popup-sized one.`));
+}
 /**
  * Print a checklist item.
  * Inline backtick-wrapped text is highlighted in cyan for visibility.
@@ -511,13 +544,15 @@ function printSetup(root) {
     console.log();
     console.log(chalk.dim('  Pre-select based on app format: mobile-responsive-web-app/desktop-app → Desktop, mobile-app → Mobile, chrome-extension → Custom (400×600).'));
     console.log(chalk.dim('  If only one obvious choice, confirm it rather than asking.'));
-    console.log(chalk.dim('  Save the choice via: curl -s -X POST http://localhost:PORT/api/editor-project-info -H "Content-Type: application/json" -d \'{"defaultScreenSize":{"name":"Desktop","width":1440,"height":900}}\''));
+    console.log(chalk.dim(`  Save the choice via: curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" -d '{"defaultScreenSize":{"name":"Desktop","width":1440,"height":900}}'`));
     console.log();
     console.log(chalk.bold('Named Screen Sizes (for multi-resolution apps):'));
     console.log(chalk.dim('  For mobile-responsive web apps or apps that need screenshots at multiple resolutions,'));
     console.log(chalk.dim('  also save named screen sizes. Each scenario can reference a dimension name.'));
-    console.log(chalk.dim('  curl -s -X POST http://localhost:PORT/api/editor-project-info -H "Content-Type: application/json" \\'));
+    console.log(chalk.dim(`  curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" \\`));
     console.log(chalk.dim('    -d \'{"screenSizes":{"Desktop":{"width":1440,"height":900},"Mobile":{"width":375,"height":667}}}\''));
+    console.log(chalk.dim('  If you discover a new viewport is needed mid-workflow, add it to screenSizes the same way and reference by name.'));
+    console.log(chalk.dim('  NOTE: This REPLACES all screenSizes — always include every named size, not just the new one.'));
     console.log();
     console.log(chalk.bold.red('━━━ STOP ━━━'));
     console.log();
@@ -663,6 +698,7 @@ function printStep1(root, feature, options, userPrompt) {
 // ─── Step 2: Prototype ────────────────────────────────────────────────
 function printStep2(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const projectExists = hasProject(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 2;
@@ -751,11 +787,12 @@ function printStep2(root, feature) {
     console.log();
     console.log(chalk.bold.cyan('Keep the preview moving:'));
     console.log(chalk.cyan('  The user is watching the preview. Refresh it after each meaningful change:'));
-    console.log(chalk.cyan(`  codeyam editor preview`));
+    console.log(chalk.cyan(`  codeyam editor preview '{"dimension":"${dim}"}'`));
     console.log(chalk.cyan('  Refresh after: first visible page, adding each UI section, seeding data, styling.'));
     console.log(chalk.cyan('  Aim for 4-8+ refreshes during prototyping — not one big reveal at the end.'));
     console.log(chalk.cyan('  If you build a NEW page (e.g., /drinks/[id]), navigate the preview there:'));
-    console.log(chalk.cyan(`  codeyam editor preview '{"path":"/drinks/1"}'`));
+    console.log(chalk.cyan(`  codeyam editor preview '{"path":"/drinks/1","dimension":"${dim}"}'`));
+    printDimensionGuidance(dim, dimNames);
     console.log();
     console.log(chalk.bold('Verify the dev server:'));
     console.log(chalk.dim(`  # Get dev server URL: codeyam editor dev-server`));
@@ -788,6 +825,7 @@ function printStep2(root, feature) {
 // ─── Step 3: Confirm ──────────────────────────────────────────────────
 function printStep3(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 3;
     const now = new Date().toISOString();
@@ -806,7 +844,7 @@ function printStep3(root, feature) {
     console.log('Summarize what was built and get user confirmation.');
     console.log();
     console.log(chalk.bold('Before presenting — verify everything works:'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\` — check the \`preview\` field for \`healthy: false\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\` — check the \`preview\` field for \`healthy: false\``);
     checkbox('Verify API routes return valid data (curl each route)');
     console.log();
     console.log(chalk.bold.red('  Verify EVERY image loads (this is the #1 source of broken prototypes):'));
@@ -820,7 +858,8 @@ function printStep3(root, feature) {
     console.log();
     console.log(chalk.bold('Then present to the user:'));
     checkbox('Summarize what was built (routes, components, data)');
-    checkbox('Navigate the preview to the feature\'s primary page: `codeyam editor preview \'{"path":"/your-page"}\'`');
+    checkbox(`Navigate the preview to the feature's primary page: \`codeyam editor preview '{"path":"/your-page","dimension":"${dim}"}'\``);
+    printDimensionGuidance(dim, dimNames);
     console.log(chalk.dim('    The user needs to SEE the new feature. If you built a new page, navigate there.'));
     console.log(chalk.dim('    If you modified an existing page, refresh the preview to show the changes.'));
     console.log();
@@ -890,6 +929,7 @@ function printStep4(root, feature) {
 // ─── Step 5: Extract ──────────────────────────────────────────────────
 function printStep5(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 5;
     const now = new Date().toISOString();
@@ -931,7 +971,8 @@ function printStep5(root, feature) {
     checkbox('Run all tests and verify they pass');
     checkbox('Page files contain ONLY imports + component composition — no raw HTML tags');
     checkbox('Every component renders ONE thing or composes sub-components — no multi-section JSX');
-    checkbox(`Refresh the preview after each batch of extractions: \`codeyam editor preview\``);
+    checkbox(`Refresh the preview after each batch of extractions: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
+    printDimensionGuidance(dim, dimNames);
     console.log(chalk.dim('    The user should see the preview stay healthy as you refactor — refresh periodically, not just at the end.'));
     console.log(chalk.dim('Reuse glossary functions when they fit naturally. Extract a new function when the use case diverges.'));
     console.log();
@@ -978,6 +1019,7 @@ function printStep6(root, feature) {
 // ─── Step 7: Analyze ──────────────────────────────────────────────────
 function printStep7(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 7;
     const now = new Date().toISOString();
@@ -1029,9 +1071,15 @@ function printStep7(root, feature) {
     console.log(chalk.dim(`       codeyam editor register '{"name":"ComponentName - Scenario",`));
     console.log(chalk.dim(`         "componentName":"ComponentName","componentPath":"path/to/file.tsx",`));
     console.log(chalk.dim(`         "url":"/isolated-components/ComponentName?s=Scenario",`));
+    console.log(chalk.dim(`         "dimensions":["${dim}"],`));
     console.log(chalk.dim(`         "mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
-    console.log(chalk.dim('       Optional: add "dimension" to use a named screen size, or "viewportWidth"/"viewportHeight" for raw override'));
-    console.log(chalk.dim('       If omitted, captures use the project default from setup. Only override for scenarios that need a different size.'));
+    console.log(chalk.yellow('       ALWAYS include "dimensions" — use the named screen size that matches the component\'s context.'));
+    console.log(chalk.dim(dimNames.length > 0
+        ? `       Available dimensions: ${dimNames.map((n) => `"${n}"`).join(', ')}. Default: "${dim}".`
+        : `       Use "${dim}" for most components. Names must match a key in screenSizes from setup.`));
+    console.log(chalk.dim('       Names must match a key in screenSizes from setup. If you need a new size, add it first:'));
+    console.log(chalk.dim(`       curl -s -X POST http://localhost:${port}/api/editor-project-info -H "Content-Type: application/json" \\`));
+    console.log(chalk.dim(`         -d '{"screenSizes":{...existing..., "New Name":{"width":W,"height":H}}}'  (replaces all — include every size)`));
     console.log(chalk.dim('       url is a PATH (starts with /) — the proxy routes it and intercepts API calls'));
     console.log(chalk.dim('       mockData.routes provides data for API calls the component makes internally'));
     console.log(chalk.dim('       (omit mockData if the component has no internal API calls)'));
@@ -1059,6 +1107,7 @@ function printStep7(root, feature) {
 // ─── Step 8: App Scenarios ────────────────────────────────────────────
 function printStep8(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 8;
     const now = new Date().toISOString();
@@ -1101,12 +1150,20 @@ function printStep8(root, feature) {
     checkbox('Re-register every existing scenario whose page was affected by this feature');
     console.log(chalk.dim('    Use the SAME name to update. Enhance seed data to showcase this feature where relevant.'));
     console.log(chalk.yellow("    Don't just re-register unchanged data — enrich it so the feature is thoroughly demonstrated."));
+    checkbox('ALWAYS include "dimensions" — pick the viewport that best demonstrates the page');
+    console.log(chalk.yellow('    Every app scenario MUST have a "dimensions" field referencing a named screen size from setup.'));
+    console.log(chalk.dim(dimNames.length > 0
+        ? `    Available dimensions: ${dimNames.map((n) => `"${n}"`).join(', ')}. Default: "${dim}".`
+        : `    Use "${dim}" for most scenarios. Names must match a key in screenSizes from setup.`));
+    if (dimNames.length > 1) {
+        const otherDim = dimNames.find((n) => n !== dim) || dimNames[1];
+        console.log(chalk.yellow(`    Think about what fits each scenario: full pages/standalone views → "${otherDim}", popups/widgets → "${dim}".`));
+    }
+    console.log(chalk.dim('    For responsive apps, include multiple dimensions: "dimensions":["Desktop","Mobile"] captures both viewports.'));
+    console.log(chalk.dim('    If you need a new named size mid-workflow, add it via editor-project-info API (include ALL existing sizes — the API replaces, not merges).'));
     checkbox('If the project has a database + seed adapter, use seed-based scenarios:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","seed":{"products":[...],"categories":[...]}}'`));
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","dimensions":["${dim}"],"seed":{"products":[...],"categories":[...]}}'`));
     console.log(chalk.dim('    Seed data is written to the DB via the seed adapter. Real app renders real data.'));
-    checkbox('Optional: add "dimension" to use a named screen size (e.g. "Mobile", "Desktop")');
-    console.log(chalk.dim('    References a named size from config screenSizes. For multi-resolution: register "Home - Desktop" with dimension "Desktop"'));
-    console.log(chalk.dim('    and "Home - Mobile" with dimension "Mobile". Or use raw "viewportWidth"/"viewportHeight" to override directly.'));
     checkbox('IMPORTANT: Always include "url" — the page path to screenshot for this scenario');
     console.log(chalk.dim('    Use "/" for home page, "/drinks/1" for detail pages, etc.'));
     console.log(chalk.dim('    Without url, the screenshot captures the root page regardless of the scenario.'));
@@ -1118,11 +1175,11 @@ function printStep8(root, feature) {
     console.log(chalk.dim(`    "externalApis":{"GET https://api.stripe.com/v1/prices":{"body":[...],"status":200}}`));
     checkbox('If the app uses auth, email, or other patterns: see FEATURE_PATTERNS.md for scenario guidance');
     checkbox('If the app uses localStorage/sessionStorage instead of a database, use localStorage scenarios:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Library","type":"application","url":"/","localStorage":{"articles":[...],"collections":[...]}}'`));
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Full Library","type":"application","url":"/","dimensions":["${dim}"],"localStorage":{"articles":[...],"collections":[...]}}'`));
     console.log(chalk.dim('    The proxy injects data into localStorage before the app loads. Fully interactive — the app can read and write normally.'));
     console.log(chalk.dim('    For an empty state, register with an empty localStorage or omit it entirely.'));
     checkbox('If no database and no localStorage, use component-style mock scenarios:');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"Empty","description":"...","url":"/","mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
+    console.log(chalk.dim(`    codeyam editor register '{"name":"Empty","description":"...","url":"/","dimensions":["${dim}"],"mockData":{"routes":{"/api/...":{"body":[...]}}}}'`));
     checkbox('After each registration, check the response for `clientErrors`');
     console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
     console.log(chalk.yellow('    Fix client errors and re-register before moving on'));
@@ -1182,6 +1239,8 @@ function printStep9(root, feature) {
     console.log(chalk.dim('    Step 8 scenarios already serve as logged-out versions (no session cookie)'));
     checkbox('If there are multiple user roles (admin, regular, etc.), create role-specific variations too');
     console.log(chalk.dim('    Each persona scenario layers user-specific seed data on top of an app scenario'));
+    checkbox('Include "dimensions" — inherit from the base app scenario, or override if the persona implies a different device');
+    console.log(chalk.dim('    e.g. a mobile-first user persona should use "dimensions":["Mobile"] even if the base scenario is Desktop.'));
     checkbox('After each registration, check the response for `clientErrors`');
     console.log(chalk.yellow('    If clientErrors is non-empty → fix the issue and re-register the scenario'));
     console.log();
@@ -1191,6 +1250,7 @@ function printStep9(root, feature) {
 // ─── Step 10: Verify ──────────────────────────────────────────────────
 function printStep10(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 10;
     const now = new Date().toISOString();
@@ -1215,7 +1275,8 @@ function printStep10(root, feature) {
     console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - Scenario",...}'`));
     console.log();
     console.log(chalk.bold('Editor scenarios (App tab) — visual + error check:'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
+    printDimensionGuidance(dim, dimNames);
     checkbox('Click through each app-level and user-persona scenario in the preview');
     checkbox('For seed-based scenarios: verify data renders correctly after switching');
     console.log(chalk.dim('    Switch between scenarios and confirm the app reflects the seeded data each time'));
@@ -1268,6 +1329,7 @@ function printStep11(root, feature) {
 // ─── Step 12: Review ──────────────────────────────────────────────────
 function printStep12(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 12;
     const now = new Date().toISOString();
@@ -1286,7 +1348,8 @@ function printStep12(root, feature) {
     console.log('Verify all screenshots and checks pass before presenting to the user.');
     console.log();
     console.log(chalk.bold('Checklist (do all of this silently):'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
+    printDimensionGuidance(dim, dimNames);
     checkbox('Verify each component has screenshots in the App tab (grouped under Components)');
     checkbox('If any are missing, re-register them using `codeyam editor register`');
     checkbox(`Check for client errors: \`codeyam editor client-errors\``);
@@ -1300,6 +1363,7 @@ function printStep12(root, feature) {
 // ─── Step 13: Present ─────────────────────────────────────────────────
 function printStep13(root, feature) {
     const port = getServerPort();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const prevState = readState(root);
     const isResuming = prevState?.step === 13;
     const now = new Date().toISOString();
@@ -1324,8 +1388,10 @@ function printStep13(root, feature) {
     console.log(chalk.dim('    Prefer scenarios with changeStatus "new" or "edited" (directly changed in this session).'));
     console.log(chalk.dim('    For app-level scenarios, prefer those showing the new/changed functionality.'));
     console.log(chalk.dim('    NEVER pick a scenario with changeStatus null — those are unchanged from a previous commit.'));
-    checkbox('Switch the preview to that scenario using its `id`:');
-    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>"}'`));
+    checkbox('Switch the preview to that scenario using its `id` and `dimension`:');
+    console.log(chalk.dim(`    codeyam editor preview '{"scenarioId":"<id>","dimension":"${dim}"}'`));
+    console.log(chalk.dim('    Use the dimension that matches the scenario — check its registered dimensions.'));
+    printDimensionGuidance(dim, dimNames);
     checkbox(`Show the results panel: \`codeyam editor show-results\``);
     console.log(chalk.dim('    This opens a visual panel below the terminal showing all scenarios with screenshots.'));
     console.log(chalk.dim('    The user can click scenarios to switch the live preview.'));
@@ -1769,8 +1835,9 @@ function formatApiSubcommandResult(subcommand, data) {
  */
 async function handleRegister(jsonArg) {
     if (!jsonArg) {
+        const { defaultName: dim } = getProjectDimensions(getProjectRoot());
         console.error(chalk.red('Error: JSON argument required.'));
-        console.error(chalk.dim('  Usage: codeyam editor register \'{"name":"DrinkCard - Default","componentName":"DrinkCard","url":"/isolated-components/DrinkCard?s=Default"}\''));
+        console.error(chalk.dim(`  Usage: codeyam editor register '{"name":"DrinkCard - Default","componentName":"DrinkCard","url":"/isolated-components/DrinkCard?s=Default","dimensions":["${dim}"]}'`));
         console.error(chalk.dim('  For large payloads: codeyam editor register @/tmp/scenario.json'));
         process.exit(1);
     }
@@ -1782,57 +1849,74 @@ async function handleRegister(jsonArg) {
         }
         process.exit(1);
     }
-    const body = parsed.body;
+    // Normalize to array for uniform handling
+    const items = Array.isArray(parsed.body) ? parsed.body : [parsed.body];
     const port = getServerPort();
     const url = `http://localhost:${port}/api/editor-register-scenario`;
-    try {
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(body),
-        });
-        const data = await res.json();
-        // Print concise summary instead of raw JSON so Claude doesn't need python3
-        const parts = [];
-        parts.push(`success=${data.success}`);
-        if (data.scenario?.name)
-            parts.push(`name="${data.scenario.name}"`);
-        parts.push(`screenshot=${!!data.screenshotCaptured}`);
-        if (data.capturedViewport) {
-            parts.push(`viewport=${data.capturedViewport.width}×${data.capturedViewport.height}`);
-        }
-        if (data.scenario?.dimension)
-            parts.push(`dimension="${data.scenario.dimension}"`);
-        if (data.clientErrors?.length > 0) {
-            parts.push(chalk.red(`errors=${data.clientErrors.length}`));
-        }
-        else {
-            parts.push(`errors=0`);
-        }
-        if (data.seedResult)
-            parts.push(`seed=${data.seedResult.success}`);
-        if (data.captureError)
-            parts.push(chalk.yellow(`captureError="${data.captureError}"`));
-        console.log(parts.join(' '));
-        // Surface client errors prominently so they can't be missed
-        if (data.clientErrors && data.clientErrors.length > 0) {
-            console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
-            for (const err of data.clientErrors) {
-                console.log(chalk.red(`  → ${err}`));
+    const isBatch = items.length > 1;
+    let succeeded = 0;
+    let failed = 0;
+    for (let i = 0; i < items.length; i++) {
+        const body = items[i];
+        const prefix = isBatch ? chalk.dim(`[${i + 1}/${items.length}] `) : '';
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            const data = await res.json();
+            // Print concise summary instead of raw JSON so Claude doesn't need python3
+            const parts = [];
+            parts.push(`success=${data.success}`);
+            if (data.scenario?.name)
+                parts.push(`name="${data.scenario.name}"`);
+            parts.push(`screenshot=${!!data.screenshotCaptured}`);
+            if (data.capturedViewport) {
+                parts.push(`viewport=${data.capturedViewport.width}×${data.capturedViewport.height}`);
+            }
+            if (data.scenario?.dimension)
+                parts.push(`dimension="${data.scenario.dimension}"`);
+            if (data.clientErrors?.length > 0) {
+                parts.push(chalk.red(`errors=${data.clientErrors.length}`));
+            }
+            else {
+                parts.push(`errors=0`);
+            }
+            if (data.seedResult)
+                parts.push(`seed=${data.seedResult.success}`);
+            if (data.captureError)
+                parts.push(chalk.yellow(`captureError="${data.captureError}"`));
+            console.log(prefix + parts.join(' '));
+            // Surface client errors prominently so they can't be missed
+            if (data.clientErrors && data.clientErrors.length > 0) {
+                console.log(chalk.red.bold(`⚠ WARNING: ${data.clientErrors.length} client error${data.clientErrors.length !== 1 ? 's' : ''} detected during capture:`));
+                for (const err of data.clientErrors) {
+                    console.log(chalk.red(`  → ${err}`));
+                }
+                console.log(chalk.yellow('  The screenshot may show an error screen instead of the actual component.'));
+                console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
+            }
+            if (!res.ok) {
+                console.error(chalk.dim(JSON.stringify(data, null, 2)));
+                failed++;
+            }
+            else {
+                succeeded++;
             }
-            console.log(chalk.yellow('  The screenshot may show an error screen instead of the actual component.'));
-            console.log(chalk.yellow('  Fix the issue and re-register this scenario.'));
         }
-        if (!res.ok) {
-            console.error(chalk.dim(JSON.stringify(data, null, 2)));
-            process.exit(1);
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            console.error(prefix + chalk.red(`Error: Could not reach editor server at ${url}`));
+            console.error(chalk.dim(`  ${msg}`));
+            console.error(chalk.dim('  Is the editor running? Start it with: codeyam editor'));
+            failed++;
         }
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        console.error(chalk.red(`Error: Could not reach editor server at ${url}`));
-        console.error(chalk.dim(`  ${msg}`));
-        console.error(chalk.dim('  Is the editor running? Start it with: codeyam editor'));
+    if (isBatch) {
+        console.log(chalk.dim(`\nBatch complete: ${succeeded}/${items.length} succeeded`));
+    }
+    if (failed > 0) {
         process.exit(1);
     }
 }
@@ -1962,6 +2046,7 @@ async function handleDependents(entityName) {
  */
 function handleChange(feature) {
     const root = getProjectRoot();
+    const { defaultName: dim, names: dimNames } = getProjectDimensions(root);
     const state = readState(root);
     if (!feature) {
         // Try to read feature from state
@@ -1993,7 +2078,8 @@ function handleChange(feature) {
     }
     console.log(chalk.bold.cyan('Keep the preview moving:'));
     console.log(chalk.cyan(`  Refresh after EACH individual change — not after all changes are done:`));
-    console.log(chalk.cyan(`  codeyam editor preview`));
+    console.log(chalk.cyan(`  codeyam editor preview '{"dimension":"${dim}"}'`));
+    printDimensionGuidance(dim, dimNames);
     console.log(chalk.cyan('  The user is watching the preview. Let them see progress incrementally.'));
     console.log();
     console.log(chalk.bold('0. Close the results panel:'));
@@ -2001,7 +2087,7 @@ function handleChange(feature) {
     console.log();
     console.log(chalk.bold('1. Re-register affected component scenarios:'));
     checkbox('For each component you modified, re-register ALL its scenarios');
-    console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - ScenarioName","componentName":"ComponentName","componentPath":"app/components/ComponentName.tsx","url":"/isolated-components/ComponentName?s=ScenarioName"}'`));
+    console.log(chalk.dim(`    codeyam editor register '{"name":"ComponentName - ScenarioName","componentName":"ComponentName","componentPath":"app/components/ComponentName.tsx","url":"/isolated-components/ComponentName?s=ScenarioName","dimensions":["${dim}"]}'`));
     checkbox('For any NEW components: `codeyam editor isolate NewComponent` then create isolation routes and register scenarios');
     console.log();
     console.log(chalk.bold('2. Re-run affected tests:'));
@@ -2025,8 +2111,9 @@ function handleChange(feature) {
     console.log(chalk.dim("    If the screenshot doesn't show the data you put in, the scenario is broken."));
     console.log();
     console.log(chalk.bold('4. Verify completeness:'));
-    checkbox(`Refresh the preview: \`codeyam editor preview\``);
-    checkbox(`Navigate to key pages to verify changes: \`codeyam editor preview '{"path":"/your-route"}'\``);
+    checkbox(`Refresh the preview: \`codeyam editor preview '{"dimension":"${dim}"}'\``);
+    checkbox(`Navigate to key pages to verify changes: \`codeyam editor preview '{"path":"/your-route","dimension":"${dim}"}'\``);
+    printDimensionGuidance(dim, dimNames);
     checkbox('Run `codeyam editor scenario-coverage` — all affected scenarios must be fresh');
     checkbox('Run `codeyam editor audit` — all checks must pass');
     checkbox(`Check for client-side errors: \`codeyam editor client-errors\``);
@@ -2534,6 +2621,34 @@ async function handleSync() {
             parts.push(`${result.skipped} unchanged`);
         console.log(chalk.green(`Synced scenarios: ${parts.join(', ')}`));
     }
+    // Migrate legacy scenario formats after sync, then re-sync if anything was fixed
+    try {
+        const migrateResult = migrateScenarioFormats(root);
+        if (migrateResult.fixed > 0) {
+            console.log(chalk.green(`Migrated ${migrateResult.fixed} scenario file${migrateResult.fixed > 1 ? 's' : ''} to current format`));
+            // Re-sync so the DB reflects the corrected file metadata
+            const refreshedRows = await db
+                .selectFrom('editor_scenarios')
+                .select(['id', 'updated_at'])
+                .where('project_id', '=', project.id)
+                .execute();
+            await syncScenarioFilesToDatabase(root, project.id, refreshedRows, async (row) => {
+                await db
+                    .insertInto('editor_scenarios')
+                    .values(row)
+                    .execute();
+            }, async (id, row) => {
+                await db
+                    .updateTable('editor_scenarios')
+                    .set(row)
+                    .where('id', '=', id)
+                    .execute();
+            });
+        }
+    }
+    catch {
+        // Non-fatal
+    }
 }
 // ─── Verify Images subcommand ─────────────────────────────────────────
 async function handleVerifyImages(jsonArg) {
@@ -3031,6 +3146,43 @@ const editorCommand = {
                         // Non-fatal — sync failure shouldn't block editor startup
                     }
                 }
+                // Migrate legacy scenario formats: resolve null viewports, populate
+                // dimensions arrays, and build screenshotPaths maps from single values.
+                // If files were fixed, re-sync to update the database with corrected values.
+                try {
+                    const migrateResult = migrateScenarioFormats(projectRoot);
+                    if (migrateResult.fixed > 0) {
+                        console.log(chalk.green(`  Migrated ${migrateResult.fixed} scenario file${migrateResult.fixed > 1 ? 's' : ''} to current format`));
+                        // Re-sync so the DB reflects the fixed file metadata
+                        try {
+                            const { getDatabase } = await import('../../../packages/database/index.js');
+                            const db = getDatabase();
+                            const rows = await db
+                                .selectFrom('editor_scenarios')
+                                .select(['id', 'updated_at'])
+                                .where('project_id', '=', project.id)
+                                .execute();
+                            await syncScenarioFilesToDatabase(projectRoot, project.id, rows, async (row) => {
+                                await db
+                                    .insertInto('editor_scenarios')
+                                    .values(row)
+                                    .execute();
+                            }, async (id, row) => {
+                                await db
+                                    .updateTable('editor_scenarios')
+                                    .set(row)
+                                    .where('id', '=', id)
+                                    .execute();
+                            });
+                        }
+                        catch {
+                            // Non-fatal — DB re-sync failure shouldn't block startup
+                        }
+                    }
+                }
+                catch {
+                    // Non-fatal — migration failure shouldn't block editor startup
+                }
                 // `codeyam editor` (no step) always implies editor mode.
                 // The empty-folder heuristic is no longer needed here — running this
                 // command IS the signal.  We still detect empty folders so that
@@ -3070,15 +3222,23 @@ const editorCommand = {
                 });
                 // Auto-finalize analyzer so codeyam analyze works
                 if (editorMode) {
-                    const finalization = ensureAnalyzerFinalized();
-                    if (finalization.needed) {
-                        console.log(`  Setting up simulations (${finalization.stepsRun.join(', ')})...`);
-                    }
+                    const stepLabels = {
+                        'npm-install': 'Installing simulation dependencies...',
+                        'playwright-install': 'Installing browser (Chromium)...',
+                        build: 'Building simulation engine...',
+                    };
+                    const simProgress = new ProgressReporter();
+                    const finalization = ensureAnalyzerFinalized({
+                        onProgress: (step) => simProgress.start(stepLabels[step]),
+                    });
                     if (finalization.errors.length > 0) {
                         for (const err of finalization.errors) {
-                            console.warn(`  Warning: ${err.step} failed: ${err.message}`);
+                            simProgress.warn(`${stepLabels[err.step].replace('...', '')} failed: ${err.message}`);
                         }
                     }
+                    else if (finalization.needed) {
+                        simProgress.succeed('Simulation engine ready');
+                    }
                 }
                 // Start background server (handles killing existing servers internally)
                 const editorPort = argv.port || 3111;