@tpitre/story-ui 3.6.2 → 3.8.0

package/README.md

@@ -66,7 +66,7 @@ Story UI will guide you through:
 | **Gemini** (Google) | Gemini 3 Pro, Gemini 2.0 Flash, Gemini 1.5 Pro | Fast generation, cost efficiency |
 
 ### Production Deployment
-- **Railway**: Node.js backend with PostgreSQL for story persistence
+- **Railway**: Node.js backend with file-based story persistence
 - **MCP Integration**: Connect AI clients directly to production
 
 ---
@@ -248,27 +248,40 @@ export class DataTableComponent { }
 
 Story UI includes a Model Context Protocol (MCP) server, allowing direct integration with AI clients like Claude Desktop and Claude Code.
 
-### Claude Code Integration (Recommended)
+### Claude Desktop Integration (Recommended)
 
-The easiest way to connect is via Claude Code's built-in MCP support:
+The easiest way to connect is via Claude Desktop's built-in connector UI:
+
+1. Open **Claude Desktop**
+2. Go to **Settings** → **Connectors**
+3. Click **"Add custom connector"**
+4. Enter:
+   - **Name**: `Story UI` (or any name you prefer)
+   - **URL**: `https://story-ui-demo.up.railway.app/mcp-remote/mcp` (production)
+5. Click **Add**
+6. **Restart Claude Desktop**
+
+Once connected, you'll have access to all Story UI tools directly in your Claude conversations:
+- `generate-story` - Generate Storybook stories from natural language
+- `list-components` - Discover available components
+- `list-stories` - View existing stories
+- `get-story` / `update-story` / `delete-story` - Manage stories
+- `get-component-props` - Get component property information
+- `test-connection` - Verify MCP connection
+
+### Claude Code Integration
+
+Connect via Claude Code's built-in MCP support:
 
 ```bash
-# Add remote HTTP MCP server
-claude mcp add --transport http story-ui https://your-worker.workers.dev/mcp
+# Add remote HTTP MCP server (production)
+claude mcp add --transport http story-ui https://story-ui-demo.up.railway.app/mcp-remote/mcp
 
 # Or for local development
-claude mcp add --transport http story-ui-local http://localhost:4005/mcp
+claude mcp add --transport http story-ui-local http://localhost:4005/mcp-remote/mcp
 ```
 
-### Claude Desktop Integration
-
-Claude Desktop now supports a connector UI for adding MCP servers. Simply:
-
-1. Open Claude Desktop Settings
-2. Navigate to the MCP Servers section
-3. Add a new server with:
-   - **Name**: Story UI
-   - **URL**: `https://your-worker.workers.dev/mcp` (production) or `http://localhost:4005/mcp` (local)
+### Manual Configuration (Advanced)
 
 For advanced users who prefer manual configuration, add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
@@ -292,7 +305,7 @@ For advanced users who prefer manual configuration, add to your Claude Desktop c
 npx story-ui start
 ```
 
-This starts the Story UI HTTP server with MCP endpoint at `http://localhost:4005/mcp`.
+This starts the Story UI HTTP server with MCP endpoint at `http://localhost:4005/mcp-remote/mcp`.
 
 ### Available MCP Commands
 
@@ -315,22 +328,17 @@ Story UI v3 can be deployed as a standalone web application accessible from anyw
 │                    Railway Deployment                        │
 │  ┌─────────────────────────────────────────────────────────┐│
 │  │              Express MCP Server (Node.js)                ││
-│  │  - Serves React frontend                                 ││
+│  │  - Serves Storybook with Story UI addon                  ││
 │  │  - API routes for story generation                       ││
-│  │  - Multi-provider LLM support                            ││
-│  └─────────────────────────────────────────────────────────┘│
-│                            │                                 │
-│                            ▼                                 │
-│  ┌─────────────────────────────────────────────────────────┐│
-│  │              PostgreSQL Database                         ││
-│  │  - Story persistence across deployments                  ││
+│  │  - Multi-provider LLM support (Claude, OpenAI, Gemini)   ││
+│  │  - File-based story persistence                          ││
 │  └─────────────────────────────────────────────────────────┘│
 └──────────────────────────────────────────────────────────────┘
 ```
 
 ### Deploy to Railway
 
-Railway provides a complete deployment experience with PostgreSQL for story persistence.
+Railway provides a straightforward deployment experience with file-based story persistence.
 
 **Quick Start:**
 
@@ -339,11 +347,8 @@ Railway provides a complete deployment experience with PostgreSQL for story pers
 npm install -g @railway/cli
 railway login
 
-# Initialize project with PostgreSQL
+# Initialize and deploy
 railway init
-railway add --plugin postgresql
-
-# Deploy
 railway up
 ```
 
@@ -351,16 +356,15 @@ railway up
 - `ANTHROPIC_API_KEY` - Required for Claude models
 - `OPENAI_API_KEY` - Optional for OpenAI models
 - `GEMINI_API_KEY` - Optional for Gemini models
-- `DATABASE_URL` - Auto-set by Railway PostgreSQL plugin
 
 **Connect MCP Clients:**
 
 ```bash
 # Add your Railway deployment as an MCP server
-claude mcp add --transport http story-ui https://your-app.up.railway.app/story-ui
+claude mcp add --transport http story-ui https://your-app.up.railway.app/mcp-remote/mcp
 ```
 
-See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions, PostgreSQL setup, and troubleshooting.
+See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions and troubleshooting.
 
 ---
 

package/dist/cli/index.js

@@ -247,11 +247,6 @@ program
     .option('--backend-url <url>', 'Use existing backend URL for app/frontend')
     .option('--storybook-dir <dir>', 'Path to Storybook project')
     .option('--project-name <name>', 'Project name prefix', 'story-ui')
-    // Legacy flags (deprecated)
-    .option('--init', '[DEPRECATED] Use --live instead')
-    .option('--edge', '[DEPRECATED] Use --live instead')
-    .option('--pages', '[DEPRECATED] Use --live instead')
-    .option('--all', '[DEPRECATED] Use --live instead')
     .action(async (options) => {
     await deployCommand(options);
 });

package/dist/cli/setup.js

@@ -851,7 +851,7 @@ Material UI (MUI) is a React component library implementing Material Design.
     }
     // Copy component files
     const templatesDir = path.resolve(__dirname, '../../templates/StoryUI');
-    const componentFiles = ['StoryUIPanel.tsx', 'StoryUIPanel.stories.tsx'];
+    const componentFiles = ['StoryUIPanel.tsx', 'StoryUIPanel.mdx'];
     console.log(chalk.blue('\n📦 Installing Story UI component...'));
     for (const file of componentFiles) {
         const sourcePath = path.join(templatesDir, file);

package/dist/mcp-server/routes/generateStory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateStory.d.ts","sourceRoot":"","sources":["../../../mcp-server/routes/generateStory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAqZ5C,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,2DAkbxE"}
+{"version":3,"file":"generateStory.d.ts","sourceRoot":"","sources":["../../../mcp-server/routes/generateStory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAgc5C,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,2DAkgBxE"}

package/dist/mcp-server/routes/generateStory.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import { buildClaudePrompt as buildFlexiblePrompt, buildFrameworkAwarePrompt, detectProjectFramework, } from '../../story-generator/promptGenerator.js';
 import { getAdapter } from '../../story-generator/framework-adapters/index.js';
 import { loadUserConfig, validateConfig } from '../../story-generator/configLoader.js';
-import { extractAndValidateCodeBlock, createFallbackStory, validateStoryCode } from '../../story-generator/validateStory.js';
+import { createFallbackStory, validateStoryCode } from '../../story-generator/validateStory.js';
 import { isBlacklistedComponent, isBlacklistedIcon, getBlacklistErrorMessage, ICON_CORRECTIONS } from '../../story-generator/componentBlacklist.js';
 import { StoryTracker } from '../../story-generator/storyTracker.js';
 import { EnhancedComponentDiscovery } from '../../story-generator/enhancedComponentDiscovery.js';
@@ -17,6 +17,23 @@ import { UrlRedirectService } from '../../story-generator/urlRedirectService.js'
 import { chatCompletion, generateTitle as llmGenerateTitle, isProviderConfigured, getProviderInfo, chatCompletionWithImages, buildMessageWithImages } from '../../story-generator/llm-providers/story-llm-service.js';
 import { processImageInputs } from '../../story-generator/imageProcessor.js';
 import { buildVisionAwarePrompt } from '../../story-generator/visionPrompts.js';
+import { aggregateValidationErrors, shouldContinueRetrying, buildSelfHealingPrompt, hasNoErrors, getTotalErrorCount, createEmptyErrors, formatErrorsForLog, selectBestAttempt, } from '../../story-generator/selfHealingLoop.js';
+import { validateStoryRuntime, formatRuntimeErrorForHealing, isRuntimeValidationEnabled, } from '../../story-generator/runtimeValidator.js';
+// Build suggestion using the user's actual discovered components (design-system agnostic)
+function buildComponentSuggestion(components) {
+    if (!components?.length) {
+        return 'Check your story-ui.config.js to ensure components are properly configured.';
+    }
+    // Show a sample of the user's actual available components (up to 5)
+    const sampleComponents = components
+        .slice(0, 5)
+        .map(c => c.name)
+        .join(', ');
+    const moreCount = components.length > 5
+        ? ` and ${components.length - 5} more`
+        : '';
+    return `Your available components include: ${sampleComponents}${moreCount}. Check story-ui.config.js if expected components are missing.`;
+}
 // Legacy function - now uses flexible system with enhanced discovery
 async function buildClaudePrompt(userPrompt) {
     const config = loadUserConfig();
@@ -33,17 +50,27 @@ async function buildClaudePromptWithContext(userPrompt, config, conversation, pr
     let useFrameworkAware = false;
     let frameworkOptions;
     if (options?.framework) {
-        // Explicit framework specified
+        // Explicit framework specified in request
         useFrameworkAware = true;
         frameworkOptions = { framework: options.framework };
         logger.log(`📦 Using specified framework: ${options.framework}`);
     }
+    else if (config.componentFramework || config.framework) {
+        // Framework configured in story-ui.config.js
+        const configFramework = (config.componentFramework || config.framework);
+        useFrameworkAware = true;
+        frameworkOptions = { framework: configFramework };
+        logger.log(`📦 Using framework from config: ${configFramework}`);
+    }
     else if (options?.autoDetectFramework) {
         // Auto-detect framework from project
         try {
             const detectedFramework = await detectProjectFramework(process.cwd());
             useFrameworkAware = true;
             frameworkOptions = { framework: detectedFramework };
+            // CRITICAL: Also set config.componentFramework so validateStoryCode receives the correct framework
+            // This ensures React imports are properly removed for non-React frameworks during post-processing
+            config.componentFramework = detectedFramework;
             logger.log(`📦 Auto-detected framework: ${detectedFramework}`);
         }
         catch (error) {
@@ -323,7 +350,7 @@ function findSimilarIcon(iconName, allowedIcons) {
     }
     return null;
 }
-function fileNameFromTitle(title, hash) {
+function fileNameFromTitle(title, hash, extension = '.stories.tsx') {
     if (!title || typeof title !== 'string') {
         title = 'untitled';
     }
@@ -337,7 +364,7 @@ function fileNameFromTitle(title, hash) {
         .replace(/^-+|-+$/g, '')
         .replace(/"|'/g, '')
         .slice(0, 60);
-    return `${base}-${hash}.stories.tsx`;
+    return `${base}-${hash}${extension}`;
 }
 export async function generateStoryFromPrompt(req, res) {
     const { prompt, fileName, conversation, isUpdate, originalTitle, storyId: providedStoryId, framework, // Explicit framework (react, vue, angular, svelte, web-components)
@@ -408,11 +435,12 @@ export async function generateStoryFromPrompt(req, res) {
                 }
             }
         }
-        // --- Start of Validation and Retry Loop ---
+        // --- Start of Self-Healing Validation and Retry Loop ---
         let aiText = '';
         let validationErrors = [];
         const maxRetries = 3;
         let attempts = 0;
+        let selfHealingUsed = false;
         // Build framework-aware options with vision support
         const frameworkOptions = {
             framework: framework,
@@ -420,6 +448,20 @@ export async function generateStoryFromPrompt(req, res) {
             visionMode: visionMode,
             designSystem: designSystem,
         };
+        // Create enhanced component discovery BEFORE the loop for use in self-healing
+        const discovery = new EnhancedComponentDiscovery(config);
+        const discoveredComponents = await discovery.discoverAll();
+        const componentNames = discoveredComponents.map(c => c.name);
+        // Self-healing options for retry prompts
+        const selfHealingOptions = {
+            maxAttempts: maxRetries,
+            availableComponents: componentNames,
+            framework: frameworkOptions.framework || 'react',
+            importPath: config.importPath || 'your-library',
+        };
+        // Track all attempts for best-attempt selection
+        const allAttempts = [];
+        const errorHistory = [];
         const initialPrompt = await buildClaudePromptWithContext(prompt, config, conversation, previousCode, frameworkOptions);
         const messages = [{ role: 'user', content: initialPrompt }];
         while (attempts < maxRetries) {
@@ -443,95 +485,90 @@ export async function generateStoryFromPrompt(req, res) {
             else {
                 aiText = extractedCode;
             }
+            // --- COMPREHENSIVE VALIDATION (Pattern + AST + Import) ---
+            // 1. Pattern validation (storyValidator)
             validationErrors = validateStory(aiText);
-            if (validationErrors.length === 0) {
-                logger.log('✅ Validation successful!');
+            // 2. TypeScript AST validation (validateStory.ts)
+            const astValidation = validateStoryCode(aiText, 'story.tsx', config);
+            // 3. Import validation (check against discovered components)
+            const importValidation = await preValidateImports(aiText, config, discovery);
+            // Aggregate all errors
+            const aggregatedErrors = aggregateValidationErrors(astValidation, validationErrors, importValidation.isValid ? [] : importValidation.errors);
+            // Track this attempt
+            const autoFixApplied = !!astValidation.fixedCode;
+            allAttempts.push({
+                code: astValidation.fixedCode || aiText,
+                errors: aggregatedErrors,
+                autoFixed: autoFixApplied,
+            });
+            errorHistory.push(aggregatedErrors);
+            // Log validation results
+            logger.log(`Validation: ${formatErrorsForLog(aggregatedErrors)}`);
+            if (autoFixApplied) {
+                logger.log('Auto-fix applied to code');
+                aiText = astValidation.fixedCode;
+            }
+            // Check if all validations pass
+            if (hasNoErrors(aggregatedErrors)) {
+                logger.log('✅ All validations passed!');
                 break; // Exit loop on success
             }
-            logger.log(`❌ Validation failed with ${validationErrors.length} errors:`);
-            validationErrors.forEach(err => logger.log(`  - Line ${err.line}: ${err.message}`));
-            if (attempts < maxRetries) {
-                const errorFeedback = validationErrors
-                    .map(err => `- Line ${err.line}: ${err.message}`)
-                    .join('\n');
-                const retryPrompt = `Your previous attempt failed validation with the following errors:\n${errorFeedback}\n\nPlease correct these issues and provide the full, valid story code. Do not use the forbidden patterns.`;
-                messages.push({ role: 'assistant', content: claudeResponse });
-                messages.push({ role: 'user', content: retryPrompt });
+            // Check if we should continue retrying
+            const retryDecision = shouldContinueRetrying(attempts, maxRetries, errorHistory);
+            if (!retryDecision.shouldRetry) {
+                logger.log(`🛑 Stopping retries: ${retryDecision.reason}`);
+                break;
             }
+            // --- SELF-HEALING: Send errors back to LLM for correction ---
+            selfHealingUsed = true;
+            logger.log(`🔄 Self-healing attempt ${attempts} of ${maxRetries}`);
+            logger.log(`   Errors: Syntax(${aggregatedErrors.syntaxErrors.length}), Pattern(${aggregatedErrors.patternErrors.length}), Import(${aggregatedErrors.importErrors.length})`);
+            // Build the self-healing prompt with all errors
+            const selfHealingPrompt = buildSelfHealingPrompt(aiText, aggregatedErrors, attempts, selfHealingOptions);
+            messages.push({ role: 'assistant', content: claudeResponse });
+            messages.push({ role: 'user', content: selfHealingPrompt });
         }
-        if (validationErrors.length > 0) {
-            console.error(`Story generation failed after ${maxRetries} attempts.`);
-            // Optional: decide if you want to return an error or proceed with the last attempt
-            // For now, we'll proceed with the last attempt and let the user see the result
-        }
-        // --- End of Validation and Retry Loop ---
-        logger.log('Claude final response:', aiText);
-        // Create enhanced component discovery for validation
-        const discovery = new EnhancedComponentDiscovery(config);
-        await discovery.discoverAll();
-        // Pre-validate imports in the raw AI text to catch blacklisted components early
-        const preValidation = await preValidateImports(aiText, config, discovery);
-        if (!preValidation.isValid) {
-            console.error('Pre-validation failed - blacklisted components detected:', preValidation.errors);
-            // Return error immediately without creating file
-            return res.status(400).json({
-                error: 'Generated code contains invalid imports',
-                details: preValidation.errors,
-                suggestion: 'The AI tried to use components that do not exist. Please try rephrasing your request using basic components like Box, Stack, Header, Button, etc.'
-            });
-        }
-        // Use the new robust validation system
-        const validationResult = extractAndValidateCodeBlock(aiText, config);
+        // --- End of Self-Healing Validation and Retry Loop ---
+        // Determine the best code to use
         let fileContents;
         let hasValidationWarnings = false;
-        logger.log('Validation result:', {
-            isValid: validationResult.isValid,
-            errors: validationResult.errors,
-            warnings: validationResult.warnings,
-            hasFixedCode: !!validationResult.fixedCode
-        });
-        if (!validationResult.isValid && !validationResult.fixedCode) {
-            console.error('Generated code validation failed:', validationResult.errors);
-            // Create fallback story only if we can't fix the code
-            logger.log('Creating fallback story due to validation failure');
-            fileContents = createFallbackStory(prompt, config);
-            hasValidationWarnings = true;
-        }
-        else {
-            // Use fixed code if available, otherwise use the extracted code
-            if (validationResult.fixedCode) {
-                fileContents = validationResult.fixedCode;
+        // Select the best attempt (fewest errors)
+        const bestAttempt = selectBestAttempt(allAttempts);
+        const finalErrors = bestAttempt ? bestAttempt.errors : createEmptyErrors();
+        const finalErrorCount = getTotalErrorCount(finalErrors);
+        logger.log(`Generation complete: ${attempts} attempts, self-healing=${selfHealingUsed}, final errors=${finalErrorCount}`);
+        if (finalErrorCount > 0 && bestAttempt) {
+            logger.log(`⚠️ Using best attempt with ${finalErrorCount} remaining errors`);
+            logger.log(`   Remaining: ${formatErrorsForLog(finalErrors)}`);
+            // If there are still errors but we have an attempt, use the best one
+            // Only create fallback if we have no valid code at all
+            if (bestAttempt.code && bestAttempt.code.includes('export')) {
+                fileContents = bestAttempt.code;
                 hasValidationWarnings = true;
-                logger.log('Using auto-fixed code');
             }
             else {
-                // Extract the validated code
-                const codeMatch = aiText.match(/```(?:tsx|jsx|typescript|ts|js|javascript)?\s*([\s\S]*?)\s*```/i);
-                if (codeMatch) {
-                    fileContents = codeMatch[1].trim();
-                }
-                else {
-                    // Fallback: extract from import to end of valid TypeScript
-                    const importIdx = aiText.indexOf('import');
-                    if (importIdx !== -1) {
-                        fileContents = aiText;
-                    }
-                    else {
-                        fileContents = aiText.trim();
-                    }
-                }
-            }
-            if (validationResult.warnings && validationResult.warnings.length > 0) {
+                // Create fallback story only if we have no usable code
+                logger.log('Creating fallback story - no usable code generated');
+                fileContents = createFallbackStory(prompt, config);
                 hasValidationWarnings = true;
-                logger.log('Validation warnings:', validationResult.warnings);
             }
         }
+        else if (bestAttempt) {
+            // Success - use the best attempt (which should have no errors)
+            fileContents = bestAttempt.code;
+        }
+        else {
+            // No attempts at all (shouldn't happen)
+            fileContents = aiText;
+        }
         if (!fileContents) {
             console.error('No valid code could be extracted or generated.');
             return res.status(500).json({ error: 'Failed to generate valid TypeScript code.' });
         }
-        // Determine the framework being used (priority: request > config > auto-detect > default)
+        // Determine the framework being used (priority: request > config.componentFramework > config.framework > auto-detect > default)
+        // CRITICAL: Check config.componentFramework BEFORE config.framework - many projects use componentFramework (not framework)
         const detectedFramework = frameworkOptions.framework ||
+            config.componentFramework ||
             config.framework ||
             (frameworkOptions.autoDetectFramework ? await detectProjectFramework(process.cwd()).catch(() => 'react') : 'react');
         logger.log(`🎯 Framework detection: request=${frameworkOptions.framework}, config=${config.framework}, detected=${detectedFramework}`);
@@ -591,14 +628,17 @@ export async function generateStoryFromPrompt(req, res) {
         // FIX #5: Final validation after ALL post-processing
         // This catches any syntax errors introduced by post-processing (e.g., buggy regex replacements)
         const finalValidation = validateStoryCode(fixedFileContents, 'story.tsx', config);
+        // ALWAYS apply fixedCode if it exists - handles both:
+        // 1. Syntax error fixes (where isValid = false)
+        // 2. React import removal for non-React frameworks (where isValid = true but fixedCode exists)
+        if (finalValidation.fixedCode) {
+            logger.log('✅ Applied validation fixes (React import removal or syntax fixes)');
+            fixedFileContents = finalValidation.fixedCode;
+        }
         if (!finalValidation.isValid) {
             logger.log('⚠️ Post-processing introduced syntax errors:', finalValidation.errors);
-            // If we have fixed code from validation, use it
-            if (finalValidation.fixedCode) {
-                logger.log('✅ Auto-fixed post-processing errors');
-                fixedFileContents = finalValidation.fixedCode;
-            }
-            else {
+            // If we don't have fixed code at this point, we can't recover
+            if (!finalValidation.fixedCode) {
                 // Post-processing broke the code and we can't fix it
                 // Return an error rather than serving broken code
                 console.error('Post-processing introduced unfixable syntax errors:', finalValidation.errors);
@@ -633,7 +673,19 @@ export async function generateStoryFromPrompt(req, res) {
         let hash, finalFileName, storyId;
         if (isActualUpdate && (fileName || providedStoryId)) {
             // For updates, preserve the existing fileName and ID
-            finalFileName = fileName;
+            // Ensure the filename has the proper .stories.tsx extension
+            // FIX: Handle case where fileName is undefined but providedStoryId exists
+            if (fileName) {
+                finalFileName = fileName;
+            }
+            else if (providedStoryId) {
+                // Generate filename from storyId when fileName not provided
+                finalFileName = `${providedStoryId}.stories.tsx`;
+                logger.log('📝 Generated filename from storyId:', finalFileName);
+            }
+            if (finalFileName && !finalFileName.endsWith('.stories.tsx')) {
+                finalFileName = finalFileName + '.stories.tsx';
+            }
             // Use provided storyId or extract from fileName
             if (providedStoryId) {
                 storyId = providedStoryId;
@@ -653,9 +705,11 @@ export async function generateStoryFromPrompt(req, res) {
             // For new stories, ALWAYS generate new IDs with timestamp to ensure uniqueness
             const timestamp = Date.now();
             hash = crypto.createHash('sha1').update(prompt + timestamp).digest('hex').slice(0, 8);
-            finalFileName = fileName || fileNameFromTitle(aiTitle, hash);
+            // Use the framework adapter's defaultExtension for the correct file extension
+            const fileExtension = frameworkAdapter?.defaultExtension || '.stories.tsx';
+            finalFileName = fileName || fileNameFromTitle(aiTitle, hash, fileExtension);
             storyId = `story-${hash}`;
-            logger.log('🆕 Creating new story:', { storyId, fileName: finalFileName });
+            logger.log('🆕 Creating new story:', { storyId, fileName: finalFileName, extension: fileExtension });
         }
         // Write story to file system
         const outPath = generateStory({
@@ -677,6 +731,33 @@ export async function generateStoryFromPrompt(req, res) {
         // Save to history
         historyManager.addVersion(finalFileName, prompt, fixedFileContents, parentVersionId);
         logger.log(`Story ${isActualUpdate ? 'updated' : 'written'} to:`, outPath);
+        // --- RUNTIME VALIDATION: Check if story loads in Storybook ---
+        // This catches errors that static validation cannot detect, like CSF module loader errors
+        let runtimeValidationResult = { success: true, storyExists: true };
+        let hasRuntimeError = false;
+        if (isRuntimeValidationEnabled()) {
+            logger.info('🔍 Running runtime validation...');
+            try {
+                runtimeValidationResult = await validateStoryRuntime(fixedFileContents, aiTitle, config.storyPrefix);
+                if (!runtimeValidationResult.success) {
+                    hasRuntimeError = true;
+                    hasValidationWarnings = true;
+                    logger.error(`❌ Runtime validation failed: ${runtimeValidationResult.renderError}`);
+                    logger.error(`   Error type: ${runtimeValidationResult.errorType}`);
+                    // Format the error for potential future self-healing
+                    const runtimeErrorMessage = formatRuntimeErrorForHealing(runtimeValidationResult);
+                    logger.debug('Runtime error details:', runtimeErrorMessage);
+                }
+                else {
+                    logger.info('✅ Runtime validation passed - story loads correctly in Storybook');
+                }
+            }
+            catch (runtimeErr) {
+                // Don't fail the request if runtime validation itself fails (e.g., Storybook not running)
+                logger.warn(`⚠️ Runtime validation could not complete: ${runtimeErr.message}`);
+                logger.warn('   Story was saved but runtime status is unknown');
+            }
+        }
         // Track URL redirect if this is an update and the title changed
         if (isActualUpdate && oldTitle && oldStoryUrl) {
             const newTitleMatch = fixedFileContents.match(/title:\s*["']([^"']+)['"]/);
@@ -702,8 +783,18 @@ export async function generateStoryFromPrompt(req, res) {
             isUpdate: isActualUpdate,
             validation: {
                 hasWarnings: hasValidationWarnings,
-                errors: validationResult?.errors || [],
-                warnings: validationResult?.warnings || []
+                errors: [...finalErrors.syntaxErrors, ...finalErrors.patternErrors, ...finalErrors.importErrors],
+                warnings: [],
+                selfHealingUsed,
+                attempts
+            },
+            runtimeValidation: {
+                enabled: isRuntimeValidationEnabled(),
+                success: runtimeValidationResult.success,
+                storyExists: runtimeValidationResult.storyExists,
+                error: runtimeValidationResult.renderError,
+                errorType: runtimeValidationResult.errorType,
+                details: runtimeValidationResult.details
             }
         });
     }

package/dist/mcp-server/routes/generateStoryStream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateStoryStream.d.ts","sourceRoot":"","sources":["../../../mcp-server/routes/generateStoryStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAwa5C,wBAAsB,6BAA6B,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,iBAob9E"}
+{"version":3,"file":"generateStoryStream.d.ts","sourceRoot":"","sources":["../../../mcp-server/routes/generateStoryStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AA2c5C,wBAAsB,6BAA6B,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,iBAqhB9E"}