coursecode 0.1.37 → 0.1.39

package/bin/cli.js

@@ -141,6 +141,7 @@ program
   .option('-f, --force', 'Regenerate all narration (ignore cache)')
   .option('-s, --slide <id>', 'Generate narration for a specific slide only')
   .option('--dry-run', 'Preview what would be generated')
+  .option('--rebuild-cache', 'Rebuild .narration-cache.json from existing audio (no TTS calls)')
   .action(async (options) => {
     const { narration } = await import('../lib/narration.js');
     await narration(options);

package/framework/js/dev/runtime-linter.js

@@ -205,6 +205,23 @@ export async function lintCourse(courseConfig) {
     // Cleanup offscreen container
     cleanupOffscreenContainer();
 
+    // --- 4. Filesystem-backed checks via preview server ---
+    // The browser can't read .narration-cache.json or hash slide source files,
+    // so the preview server exposes /__lint/narration to do that work and
+    // return any stale-narration warnings. Silently ignored if the endpoint
+    // is unavailable (e.g. running outside the preview server).
+    try {
+        const resp = await fetch('/__lint/narration', { cache: 'no-store' });
+        if (resp.ok) {
+            const data = await resp.json();
+            if (Array.isArray(data.warnings)) {
+                warnings.push(...data.warnings);
+            }
+        }
+    } catch {
+        // Endpoint absent (e.g. SCORM package preview) — skip silently.
+    }
+
     // Display warnings individually so each appears as a separate entry in the debug panel
     if (warnings.length > 0) {
         for (const w of warnings) {

package/framework/scripts/generate-narration.js

@@ -32,9 +32,15 @@
 
 import fs from 'fs';
 import path from 'path';
-import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 import { getActiveProvider, printProviderHelp, listProviders as _listProviders } from './tts-providers/index.js';
+import {
+    parseSlideNarration as parseSlideNarrationShared,
+    hashContent,
+    loadNarrationCache,
+    narrationCacheKey,
+    VOICE_SETTING_KEYS as _SHARED_VOICE_KEYS
+} from './narration-parser.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -48,8 +54,8 @@ const AUDIO_DIR = path.join(ASSETS_DIR, 'audio');
 const SLIDES_DIR = path.join(COURSE_DIR, 'slides');
 const CACHE_FILE = path.join(SCORM_TEMPLATE_DIR, '.narration-cache.json');
 
-// Reserved keys for voice settings (not narration content)
-const VOICE_SETTING_KEYS = ['voice_id', 'model_id', 'stability', 'similarity_boost', 'voice', 'model', 'speed', 'rate', 'pitch', 'style'];
+// Reserved keys for voice settings (not narration content) — re-exported from shared module
+const VOICE_SETTING_KEYS = _SHARED_VOICE_KEYS;
 
 // Parse command line arguments
 const args = process.argv.slice(2);
@@ -59,6 +65,10 @@ const VERBOSE = args.includes('--verbose') || args.includes('-v');
 const SLIDE_FILTER = args.includes('--slide') ? args[args.indexOf('--slide') + 1] : null;
 const SHOW_PROVIDERS = args.includes('--providers') || args.includes('--provider');
 const SHOW_HELP = args.includes('--help') || args.includes('-h');
+// Rebuild .narration-cache.json from current slide text without calling any
+// TTS provider. Useful when audio is committed but the cache is missing
+// (e.g. after a fresh clone or migrating a project).
+const REBUILD_CACHE = args.includes('--rebuild-cache');
 
 /**
  * Load environment variables from .env file
@@ -202,195 +212,23 @@ function categorizeAndFilterSources(sources) {
     return result;
 }
 
-/**
- * Load the narration cache
- */
+/** Load the narration cache (delegates to shared module) */
 function loadCache() {
-    if (fs.existsSync(CACHE_FILE)) {
-        try {
-            return JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
-        } catch {
-            return {};
-        }
-    }
-    return {};
+    return loadNarrationCache(CACHE_FILE);
 }
 
-/**
- * Save the narration cache
- */
+/** Save the narration cache */
 function saveCache(cache) {
     fs.writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2));
 }
 
-/**
- * Calculate MD5 hash of content
- */
-function hashContent(content) {
-    return crypto.createHash('md5').update(content).digest('hex');
-}
-
-
-
-/**
- * Extract narration export from a slide file using static analysis.
- * This avoids importing the module (which would fail due to browser-only dependencies).
- * 
- * Supports:
- *   Simple string: export const narration = `text`;
- *   Object with text: export const narration = { text: `...`, voice_id: '...' };
- *   Multi-key object: export const narration = { slide: `...`, 'modal-id': `...`, 'tab-id': `...` };
- * 
- * Returns array of narration items with key, text, settings, outputPath
- */
+/** Wrapper that injects this script's AUDIO_DIR into the shared parser. */
 function parseSlideNarration(filePath, baseName) {
-    let content = fs.readFileSync(filePath, 'utf-8');
-    
-    // Remove block comments (/* ... */) to avoid matching examples in JSDoc
-    content = content.replace(/\/\*[\s\S]*?\*\//g, '');
-    
-    // Remove single-line comments (// ...)
-    content = content.replace(/\/\/.*$/gm, '');
-    
-    // Try to match the full narration export - look for the complete object/value
-    // This regex matches from 'export const narration =' until we hit another export, async, function, etc.
-    const exportMatch = content.match(/export\s+const\s+narration\s*=\s*([\s\S]*?);(?=\s*(?:export|async\s+function|function|const|let|var|class|\/\/|\/\*|$))/);
-    
-    if (!exportMatch) {
-        return null;
-    }
-    
-    const exportValue = exportMatch[1].trim();
-    
-    // Case 1: Simple template literal - export const narration = `text`;
-    if (exportValue.startsWith('`') && exportValue.endsWith('`')) {
-        const text = exportValue.slice(1, -1).trim();
-        return [{
-            key: 'slide',
-            text,
-            settings: {},
-            outputPath: path.join(AUDIO_DIR, `${baseName}.mp3`)
-        }];
-    }
-    
-    // Case 2: Simple quoted string - export const narration = "text" or 'text'
-    if ((exportValue.startsWith('"') && exportValue.endsWith('"')) ||
-        (exportValue.startsWith("'") && exportValue.endsWith("'"))) {
-        const text = exportValue.slice(1, -1).trim();
-        return [{
-            key: 'slide',
-            text,
-            settings: {},
-            outputPath: path.join(AUDIO_DIR, `${baseName}.mp3`)
-        }];
-    }
-    
-    // Case 3: Object - parse keys and values
-    if (exportValue.startsWith('{')) {
-        return parseNarrationObject(exportValue, baseName);
-    }
-    
-    return null;
+    return parseSlideNarrationShared(filePath, baseName, AUDIO_DIR);
 }
 
-/**
- * Parse a narration object with multiple keys
- * Handles: { slide: `...`, 'modal-id': `...`, text: `...`, voice_id: '...' }
- */
-function parseNarrationObject(objectStr, baseName) {
-    const results = [];
-    let globalSettings = {};
-    
-    // Extract voice settings (support both ElevenLabs and common formats)
-    const settingPatterns = [
-        { key: 'voice_id', regex: /voice_id\s*:\s*['"]([^'"]+)['"]/ },
-        { key: 'voice', regex: /voice\s*:\s*['"]([^'"]+)['"]/ },
-        { key: 'model_id', regex: /model_id\s*:\s*['"]([^'"]+)['"]/ },
-        { key: 'model', regex: /model\s*:\s*['"]([^'"]+)['"]/ },
-        { key: 'stability', regex: /stability\s*:\s*([\d.]+)/ },
-        { key: 'similarity_boost', regex: /similarity_boost\s*:\s*([\d.]+)/ },
-        { key: 'speed', regex: /speed\s*:\s*([\d.]+)/ },
-        { key: 'rate', regex: /rate\s*:\s*['"]([^'"]+)['"]/ },
-        { key: 'pitch', regex: /pitch\s*:\s*['"]([^'"]+)['"]/ },
-        { key: 'style', regex: /style\s*:\s*['"]([^'"]+)['"]/ }
-    ];
-    
-    for (const { key, regex } of settingPatterns) {
-        const match = objectStr.match(regex);
-        if (match) globalSettings[key] = match[1];
-    }
-    
-    // Check for old format: { text: `...` } (single narration with settings)
-    const singleTextMatch = objectStr.match(/^\s*\{\s*text\s*:\s*`([\s\S]*?)`/);
-    if (singleTextMatch && !objectStr.match(/slide\s*:/)) {
-        return [{
-            key: 'slide',
-            text: singleTextMatch[1].trim(),
-            settings: globalSettings,
-            outputPath: path.join(AUDIO_DIR, `${baseName}.mp3`)
-        }];
-    }
-    
-    // Multi-key format: { slide: `...`, 'key': `...` }
-    // Match patterns like: slide: `text` or 'modal-id': `text` or "tab-id": `text`
-    const keyValueRegex = /(?:(['"])([\w-]+)\1|(\w+))\s*:\s*`([\s\S]*?)`/g;
-    let match;
-    
-    while ((match = keyValueRegex.exec(objectStr)) !== null) {
-        const key = match[2] || match[3]; // Quoted key or unquoted key
-        const text = match[4].trim();
-        
-        // Skip voice setting keys
-        if (VOICE_SETTING_KEYS.includes(key)) continue;
-        
-        // Skip 'text' key in old format (already handled above)
-        if (key === 'text') continue;
-        
-        // Determine output filename
-        let outputPath;
-        if (key === 'slide') {
-            outputPath = path.join(AUDIO_DIR, `${baseName}.mp3`);
-        } else {
-            outputPath = path.join(AUDIO_DIR, `${baseName}--${key}.mp3`);
-        }
-        
-        results.push({
-            key,
-            text,
-            settings: { ...globalSettings },
-            outputPath
-        });
-    }
-    
-    // Also match quoted string values: 'key': "text" or 'key': 'text'
-    const quotedValueRegex = /(?:(['"])([\w-]+)\1|(\w+))\s*:\s*(['"])([\s\S]*?)\4/g;
-    while ((match = quotedValueRegex.exec(objectStr)) !== null) {
-        const key = match[2] || match[3];
-        const text = match[5].trim();
-        
-        if (VOICE_SETTING_KEYS.includes(key)) continue;
-        if (key === 'text') continue;
-        
-        // Check if we already have this key (from template literal match)
-        if (results.some(r => r.key === key)) continue;
-        
-        let outputPath;
-        if (key === 'slide') {
-            outputPath = path.join(AUDIO_DIR, `${baseName}.mp3`);
-        } else {
-            outputPath = path.join(AUDIO_DIR, `${baseName}--${key}.mp3`);
-        }
-        
-        results.push({
-            key,
-            text,
-            settings: { ...globalSettings },
-            outputPath
-        });
-    }
-    
-    return results.length > 0 ? results : null;
-}
+// Removed: original inline parseSlideNarration / parseNarrationObject implementations
+// now live in framework/scripts/narration-parser.js so the build linter can reuse them.
 
 /**
  * Main execution
@@ -410,11 +248,12 @@ async function main() {
 
 Usage:
    npm run narration                  Generate all changed narration
-   npm run narration -- --force       Regenerate all (ignore cache)
-   npm run narration -- --dry-run     Preview without generating
-   npm run narration -- --slide <id>  Generate specific slide only
-   npm run narration -- --providers   List available TTS providers
-   npm run narration -- --verbose     Show detailed output
+   npm run narration -- --force          Regenerate all (ignore cache)
+   npm run narration -- --dry-run        Preview without generating
+   npm run narration -- --slide <id>     Generate specific slide only
+   npm run narration -- --rebuild-cache  Rebuild cache from existing audio (no TTS calls)
+   npm run narration -- --providers      List available TTS providers
+   npm run narration -- --verbose        Show detailed output
 
 Provider Selection:
    Set TTS_PROVIDER env var to: elevenlabs, openai, or azure
@@ -432,17 +271,22 @@ Examples:
     // Load environment variables
     loadEnv();
     
-    // Initialize TTS provider
+    // Initialize TTS provider — skipped in --rebuild-cache mode since we
+    // never call the provider when only refreshing the cache file.
     let provider;
-    try {
-        provider = getActiveProvider();
-        provider.validateConfig();
-        const defaultVoice = provider.getDefaultVoiceId();
-        console.log(`🔊 Using TTS provider: ${provider.getName()} (voice: ${defaultVoice})\n`);
-    } catch (error) {
-        console.error(`❌ Provider error: ${error.message}\n`);
-        printProviderHelp();
-        process.exit(1);
+    if (REBUILD_CACHE) {
+        console.log('🔁 Rebuild-cache mode: hashing existing audio, no TTS calls.\n');
+    } else {
+        try {
+            provider = getActiveProvider();
+            provider.validateConfig();
+            const defaultVoice = provider.getDefaultVoiceId();
+            console.log(`🔊 Using TTS provider: ${provider.getName()} (voice: ${defaultVoice})\n`);
+        } catch (error) {
+            console.error(`❌ Provider error: ${error.message}\n`);
+            printProviderHelp();
+            process.exit(1);
+        }
     }
     
     // Load course config
@@ -541,7 +385,24 @@ Examples:
             const cacheKey = key === 'slide' ? source.src : `${source.src}#${key}`;
             const cachedHash = cache[cacheKey];
             const outputExists = fs.existsSync(outputPath);
-            
+
+            // --rebuild-cache: hash text+settings for existing audio and move on.
+            // Never call TTS, never write or delete audio files.
+            if (REBUILD_CACHE) {
+                if (outputExists) {
+                    newCache[cacheKey] = contentHash;
+                    skipped++;
+                    if (VERBOSE) {
+                        const label = key === 'slide' ? source.slideId : `${source.slideId}#${key}`;
+                        console.log(`   ✅ ${label}: cached (${path.relative(ROOT_DIR, outputPath)})`);
+                    }
+                } else if (VERBOSE) {
+                    const label = key === 'slide' ? source.slideId : `${source.slideId}#${key}`;
+                    console.log(`   ⏭️  ${label}: no audio yet, skipping`);
+                }
+                continue;
+            }
+
             if (cachedHash === contentHash && outputExists && !FORCE_REGENERATE) {
                 if (VERBOSE) {
                     const label = key === 'slide' ? source.slideId : `${source.slideId}#${key}`;

package/framework/scripts/narration-parser.js

@@ -0,0 +1,204 @@
+/**
+ * Narration Parser - shared static-analysis utilities for narration sources.
+ *
+ * Used by both:
+ *   - framework/scripts/generate-narration.js (audio generation + cache writes)
+ *   - lib/build-linter.js                     (stale narration detection)
+ *
+ * Pure: no TTS calls, no audio I/O. Safe to import in any Node context.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+// Reserved keys for voice settings (not narration content)
+export const VOICE_SETTING_KEYS = [
+    'voice_id', 'model_id', 'stability', 'similarity_boost',
+    'voice', 'model', 'speed', 'rate', 'pitch', 'style'
+];
+
+/**
+ * MD5 hash of arbitrary string content. Matches the generator's algorithm so
+ * the linter can recompute hashes and compare against `.narration-cache.json`.
+ */
+export function hashContent(content) {
+    return crypto.createHash('md5').update(content).digest('hex');
+}
+
+/**
+ * Compute the cache key for a narration item, matching the generator's format.
+ * `slide` key uses the bare source path; other keys are suffixed with `#key`.
+ */
+export function narrationCacheKey(sourceSrc, itemKey) {
+    return itemKey === 'slide' ? sourceSrc : `${sourceSrc}#${itemKey}`;
+}
+
+/**
+ * Compute the audio output path for a narration item.
+ */
+export function narrationAudioPath(audioDir, baseName, itemKey) {
+    return itemKey === 'slide'
+        ? path.join(audioDir, `${baseName}.mp3`)
+        : path.join(audioDir, `${baseName}--${itemKey}.mp3`);
+}
+
+/**
+ * Load the narration cache file. Returns {} if missing or unreadable.
+ */
+export function loadNarrationCache(cacheFile) {
+    if (!fs.existsSync(cacheFile)) return {};
+    try {
+        return JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Extract narration export from a slide file using static analysis.
+ * This avoids importing the module (which would fail due to browser-only deps).
+ *
+ * Returns null if no narration export is present, otherwise an array of items:
+ *   [{ key, text, settings, outputPath }]
+ *
+ * @param {string} filePath - Absolute path to slide JS file.
+ * @param {string} baseName - File stem used to derive output filenames.
+ * @param {string} audioDir - Directory where .mp3 files are written.
+ */
+export function parseSlideNarration(filePath, baseName, audioDir) {
+    let content = fs.readFileSync(filePath, 'utf-8');
+
+    // Remove block comments (/* ... */) to avoid matching JSDoc examples
+    content = content.replace(/\/\*[\s\S]*?\*\//g, '');
+    // Remove single-line comments
+    content = content.replace(/\/\/.*$/gm, '');
+
+    // Match the full narration export up to the next top-level statement
+    const exportMatch = content.match(
+        /export\s+const\s+narration\s*=\s*([\s\S]*?);(?=\s*(?:export|async\s+function|function|const|let|var|class|\/\/|\/\*|$))/
+    );
+
+    if (!exportMatch) return null;
+
+    const exportValue = exportMatch[1].trim();
+
+    // Case 1: template literal — export const narration = `text`;
+    if (exportValue.startsWith('`') && exportValue.endsWith('`')) {
+        return [{
+            key: 'slide',
+            text: exportValue.slice(1, -1).trim(),
+            settings: {},
+            outputPath: narrationAudioPath(audioDir, baseName, 'slide')
+        }];
+    }
+
+    // Case 2: quoted string
+    if ((exportValue.startsWith('"') && exportValue.endsWith('"')) ||
+        (exportValue.startsWith("'") && exportValue.endsWith("'"))) {
+        return [{
+            key: 'slide',
+            text: exportValue.slice(1, -1).trim(),
+            settings: {},
+            outputPath: narrationAudioPath(audioDir, baseName, 'slide')
+        }];
+    }
+
+    // Case 3: object — multi-key or { text, ...settings }
+    if (exportValue.startsWith('{')) {
+        return parseNarrationObject(exportValue, baseName, audioDir);
+    }
+
+    return null;
+}
+
+/**
+ * Parse a narration object literal with multiple keys and/or voice settings.
+ * Handles: { slide: `...`, 'modal-id': `...`, voice_id: '...' }
+ *      and { text: `...`, voice_id: '...' }
+ */
+export function parseNarrationObject(objectStr, baseName, audioDir) {
+    const results = [];
+    const globalSettings = {};
+
+    const settingPatterns = [
+        { key: 'voice_id', regex: /voice_id\s*:\s*['"]([^'"]+)['"]/ },
+        { key: 'voice', regex: /voice\s*:\s*['"]([^'"]+)['"]/ },
+        { key: 'model_id', regex: /model_id\s*:\s*['"]([^'"]+)['"]/ },
+        { key: 'model', regex: /model\s*:\s*['"]([^'"]+)['"]/ },
+        { key: 'stability', regex: /stability\s*:\s*([\d.]+)/ },
+        { key: 'similarity_boost', regex: /similarity_boost\s*:\s*([\d.]+)/ },
+        { key: 'speed', regex: /speed\s*:\s*([\d.]+)/ },
+        { key: 'rate', regex: /rate\s*:\s*['"]([^'"]+)['"]/ },
+        { key: 'pitch', regex: /pitch\s*:\s*['"]([^'"]+)['"]/ },
+        { key: 'style', regex: /style\s*:\s*['"]([^'"]+)['"]/ }
+    ];
+
+    for (const { key, regex } of settingPatterns) {
+        const match = objectStr.match(regex);
+        if (match) globalSettings[key] = match[1];
+    }
+
+    // Old format: { text: `...` } single narration with settings
+    const singleTextMatch = objectStr.match(/^\s*\{\s*text\s*:\s*`([\s\S]*?)`/);
+    if (singleTextMatch && !objectStr.match(/slide\s*:/)) {
+        return [{
+            key: 'slide',
+            text: singleTextMatch[1].trim(),
+            settings: globalSettings,
+            outputPath: narrationAudioPath(audioDir, baseName, 'slide')
+        }];
+    }
+
+    // Multi-key with template literals
+    const keyValueRegex = /(?:(['"])([\w-]+)\1|(\w+))\s*:\s*`([\s\S]*?)`/g;
+    let match;
+    while ((match = keyValueRegex.exec(objectStr)) !== null) {
+        const key = match[2] || match[3];
+        const text = match[4].trim();
+        if (VOICE_SETTING_KEYS.includes(key) || key === 'text') continue;
+        results.push({
+            key,
+            text,
+            settings: { ...globalSettings },
+            outputPath: narrationAudioPath(audioDir, baseName, key)
+        });
+    }
+
+    // Multi-key with quoted string values
+    const quotedValueRegex = /(?:(['"])([\w-]+)\1|(\w+))\s*:\s*(['"])([\s\S]*?)\4/g;
+    while ((match = quotedValueRegex.exec(objectStr)) !== null) {
+        const key = match[2] || match[3];
+        const text = match[5].trim();
+        if (VOICE_SETTING_KEYS.includes(key) || key === 'text') continue;
+        if (results.some(r => r.key === key)) continue;
+        results.push({
+            key,
+            text,
+            settings: { ...globalSettings },
+            outputPath: narrationAudioPath(audioDir, baseName, key)
+        });
+    }
+
+    return results.length > 0 ? results : null;
+}
+
+/**
+ * Classify the freshness of a single narration item. Pure function — caller
+ * supplies the parsed item, the cached hash, and the audio file existence flag.
+ *
+ * Returns one of:
+ *   'ok'      - audio exists AND cached hash matches current text+settings
+ *   'stale'   - audio exists AND cached hash differs (or no cache entry)
+ *   'missing' - text defined but audio file does not exist
+ *   'unknown' - audio exists but no cache file at all (can't determine; caller
+ *               typically suppresses these to avoid noise on fresh clones)
+ */
+export function classifyNarrationFreshness({ item, cachedHash, audioExists, cacheLoaded }) {
+    const currentHash = hashContent(item.text + JSON.stringify(item.settings || {}));
+
+    if (!audioExists) return 'missing';
+    if (!cacheLoaded) return 'unknown';
+    if (cachedHash === currentHash) return 'ok';
+    return 'stale';
+}

package/lib/authoring-api.js

@@ -1110,3 +1110,129 @@ export async function buildCourse(options = {}) {
     });
 }
 
+/**
+ * Run the narration generator script and return a structured result.
+ *
+ * Spawns `framework/scripts/generate-narration.js` from the course root so it
+ * picks up the same .env, course-config, and slide files a manual run would.
+ *
+ * @param {object} options
+ * @param {boolean} [options.dryRun=false]      - Show what would be generated without calling TTS
+ * @param {boolean} [options.force=false]       - Regenerate everything, ignoring the cache
+ * @param {string}  [options.slide]             - Limit to a single slide ID
+ * @param {boolean} [options.rebuildCache=false] - Rebuild .narration-cache.json from existing audio without calling TTS
+ * @returns {Promise<{success, dryRun, summary, generated, skipped, errors, warnings, output, duration}>}
+ */
+export async function generateNarration(options = {}) {
+    const { dryRun = false, force = false, slide, rebuildCache = false } = options;
+    const startTime = Date.now();
+
+    let courseRoot;
+    try {
+        courseRoot = getCourseRoot();
+    } catch (error) {
+        return {
+            success: false,
+            error: error.message,
+            errors: [error.message],
+            warnings: [],
+            output: '',
+            duration: '0s'
+        };
+    }
+
+    const scriptPath = path.join(courseRoot, 'framework', 'scripts', 'generate-narration.js');
+    if (!fs.existsSync(scriptPath)) {
+        const msg = `Narration script not found at ${scriptPath}. Run \`coursecode upgrade\` to install framework scripts.`;
+        return {
+            success: false,
+            error: msg,
+            errors: [msg],
+            warnings: [],
+            output: '',
+            duration: '0s'
+        };
+    }
+
+    const args = [scriptPath];
+    if (force) args.push('--force');
+    if (dryRun) args.push('--dry-run');
+    if (slide) args.push('--slide', slide);
+    if (rebuildCache) args.push('--rebuild-cache');
+
+    return new Promise((resolve) => {
+        const child = spawn('node', args, {
+            cwd: courseRoot,
+            env: process.env,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+
+        let stdout = '';
+        let stderr = '';
+
+        // Cap captured output to keep MCP responses manageable
+        const MAX_OUTPUT = 64 * 1024;
+        child.stdout.on('data', (d) => {
+            if (stdout.length < MAX_OUTPUT) stdout += d.toString();
+        });
+        child.stderr.on('data', (d) => {
+            if (stderr.length < MAX_OUTPUT) stderr += d.toString();
+        });
+
+        child.on('close', (code) => {
+            const duration = ((Date.now() - startTime) / 1000).toFixed(1) + 's';
+            const output = stdout + (stderr ? `\n${stderr}` : '');
+
+            // Parse summary line: "✨ Complete: 3 generated, 5 unchanged, 1 errors"
+            const summaryMatch = output.match(/Complete:\s*(.+?)(?:\n|$)/);
+            const summary = summaryMatch ? summaryMatch[1].trim() : null;
+
+            const numFromSummary = (label) => {
+                if (!summary) return 0;
+                const m = summary.match(new RegExp(`(\\d+)\\s+${label}`));
+                return m ? parseInt(m[1], 10) : 0;
+            };
+
+            const errors = [];
+            const warnings = [];
+            for (const line of output.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed) continue;
+                if (trimmed.startsWith('❌') || trimmed.startsWith('Error:')) errors.push(trimmed);
+                else if (trimmed.startsWith('⚠️')) warnings.push(trimmed);
+            }
+
+            resolve({
+                success: code === 0,
+                dryRun,
+                summary,
+                generated: numFromSummary('generated'),
+                skipped: numFromSummary('unchanged'),
+                noNarration: numFromSummary('no export'),
+                errors,
+                warnings,
+                output: output.slice(-8000), // Tail for MCP response (full available in stdout)
+                duration,
+                message: code === 0
+                    ? `Narration ${dryRun ? '(dry-run) ' : ''}complete in ${duration}${summary ? `: ${summary}` : ''}`
+                    : `Narration failed (exit ${code}). ${errors.length} error(s).`
+            });
+        });
+
+        child.on('error', (error) => {
+            const duration = ((Date.now() - startTime) / 1000).toFixed(1) + 's';
+            resolve({
+                success: false,
+                dryRun,
+                error: error.message,
+                errors: [error.message],
+                warnings: [],
+                output: '',
+                duration,
+                message: `Narration failed: ${error.message}`
+            });
+        });
+    });
+}
+

package/lib/build-linter.js

@@ -14,6 +14,12 @@ import path from 'path';
 import { parseSlideSource, extractAssessment } from './course-parser.js';
 import { getEngagementTrackingMap, getRegisteredComponentTypes } from './schema-extractor.js';
 import { getValidCssClasses, lintCssSelectors } from './css-index.js';
+import {
+  parseSlideNarration,
+  loadNarrationCache,
+  narrationCacheKey,
+  classifyNarrationFreshness
+} from '../framework/scripts/narration-parser.js';
 import { fileURLToPath, pathToFileURL } from 'url';
 import {
   flattenStructure,
@@ -104,6 +110,12 @@ export async function lintCourse(courseConfig, coursePath) {
     await validateSlide(slide, coursePath, objectiveIds, errors, warnings, interactionIdRegistry, validCssIndex);
   }
 
+  // Narration freshness check (opt-out via courseConfig.lint.narrationFreshness === false)
+  const narrationFreshnessEnabled = courseConfig.lint?.narrationFreshness !== false;
+  if (narrationFreshnessEnabled) {
+    checkNarrationFreshness(slides, coursePath, warnings);
+  }
+
   return { errors, warnings };
 }
 
@@ -398,6 +410,82 @@ function collectJsFiles(dir, result) {
   }
 }
 
+/**
+ * Check that generated narration audio is in sync with the narration text in
+ * each slide. Emits warnings when:
+ *   - The .mp3 exists but the cached hash differs from current text+settings (stale)
+ *   - Narration text is defined but no .mp3 exists (missing)
+ *
+ * Silent when:
+ *   - The slide has no narration export
+ *   - No audio file exists AND no cache entry (treat as "narration not yet
+ *     generated" — author may not have configured TTS yet)
+ *   - The narration cache file is absent (can't determine staleness; avoids
+ *     false positives on freshly cloned repos)
+ *
+ * Opt out via courseConfig.lint.narrationFreshness === false.
+ *
+ * @param {Array} slides   - Flattened slide list.
+ * @param {string} coursePath - Path to the course directory (contains slides/).
+ * @param {string[]} warnings - Output array; warnings are pushed in place.
+ */
+export function checkNarrationFreshness(slides, coursePath, warnings) {
+  const slidesDir = path.join(coursePath, 'slides');
+  const audioDir = path.join(coursePath, 'assets', 'audio');
+  // Cache file lives at the project root, one level above coursePath.
+  const projectRoot = path.dirname(coursePath);
+  const cacheFile = path.join(projectRoot, '.narration-cache.json');
+
+  const cacheLoaded = fs.existsSync(cacheFile);
+  const cache = cacheLoaded ? loadNarrationCache(cacheFile) : {};
+
+  for (const slide of slides) {
+    if (!slide.component || !slide.component.startsWith('@slides/')) continue;
+
+    const slideFileName = slide.component.replace('@slides/', '');
+    const slideFilePath = path.join(slidesDir, slideFileName);
+    if (!fs.existsSync(slideFilePath)) continue;
+
+    const baseName = slideFileName.replace(/\.js$/, '');
+
+    let items;
+    try {
+      items = parseSlideNarration(slideFilePath, baseName, audioDir);
+    } catch {
+      continue;
+    }
+    if (!items) continue;
+
+    const sourceSrc = `@slides/${slideFileName}`;
+
+    for (const item of items) {
+      const cacheKey = narrationCacheKey(sourceSrc, item.key);
+      const audioExists = fs.existsSync(item.outputPath);
+
+      // Per spec: if no audio file exists, do NOT warn — author may not have
+      // generated narration yet (TTS provider may not even be configured).
+      if (!audioExists) continue;
+
+      const status = classifyNarrationFreshness({
+        item,
+        cachedHash: cache[cacheKey],
+        audioExists,
+        cacheLoaded
+      });
+
+      if (status === 'stale') {
+        const keyLabel = item.key === 'slide' ? '' : ` (key: "${item.key}")`;
+        const relAudio = path.relative(projectRoot, item.outputPath).replace(/\\/g, '/');
+        warnings.push(
+          `Slide "${slide.id}": narration audio is stale${keyLabel} \u2014 text changed since ${relAudio} was generated. Run \`coursecode narration\` to regenerate.`
+        );
+      }
+      // 'unknown' (cache file missing): silent — avoids noise on fresh clones.
+      // 'ok': silent.
+    }
+  }
+}
+
 /**
  * Lint framework JS source files for banned logging/error patterns.
  * Prevents regression to pre-unified-logger patterns.

package/lib/mcp-prompts.js

@@ -407,6 +407,61 @@ Use AFTER making changes to validate the course.`,
             idempotentHint: true
         }
     },
+    {
+        name: 'coursecode_narration',
+        description: `Generate (or dry-run) audio narration for slides via the configured TTS provider.
+
+Reads \`export const narration = ...\` from each slide file, hashes text+voice settings, and only regenerates audio whose hash changed since the last run (cache: .narration-cache.json). MP3 files are written to course/assets/audio/.
+
+Provider selection follows the same rules as the CLI:
+  TTS_PROVIDER env var, or auto-detect from API keys, default deepgram.
+The .env file at the project root supplies API keys.
+
+USE WHEN:
+- The lint reports stale narration warnings ("narration audio is stale...").
+- You added or modified narration text in a slide.
+- You want to confirm what would be generated (use dryRun: true — no API calls, no audio written).
+
+APPROVAL:
+- Real generation (dryRun omitted or false) calls a TTS provider and writes MP3 files, so it requires explicit user approval before running.
+- Use dryRun: true first when you only need to inspect what would be regenerated.
+
+Returns:
+- success, summary (e.g. "3 generated, 5 unchanged")
+- generated, skipped, noNarration counts
+- errors[], warnings[]
+- output: tail of the generator's console output for debugging
+- dryRun: echoes the input flag
+
+NOT idempotent: real runs call paid TTS APIs and write files. Prefer dryRun first.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                dryRun: {
+                    type: 'boolean',
+                    description: 'Show what would be generated without calling TTS or writing files (default: false).'
+                },
+                force: {
+                    type: 'boolean',
+                    description: 'Regenerate every narration item, ignoring the cache (default: false). Use sparingly — costs API credits.'
+                },
+                slide: {
+                    type: 'string',
+                    description: 'Optional slide ID filter (e.g. "intro"). Only narration for this slide is processed.'
+                },
+                rebuildCache: {
+                    type: 'boolean',
+                    description: 'Rebuild .narration-cache.json from existing audio files without calling TTS (default: false). Use after a fresh clone or when the cache is missing but audio is committed. Free; no API calls.'
+                }
+            },
+            required: []
+        },
+        annotations: {
+            readOnlyHint: false,
+            idempotentHint: false,
+            destructiveHint: false
+        }
+    },
     {
         name: 'coursecode_icon_catalog',
         description: `Get icon information.

package/lib/mcp-server.js

@@ -28,7 +28,8 @@ import {
     getInteractionCatalog,
     getIconCatalog,
     lintCourse,
-    buildCourse
+    buildCourse,
+    generateNarration
 } from './authoring-api.js';
 
 import headless from './headless-browser.js';
@@ -282,6 +283,15 @@ export async function startMcpServer(options = {}) {
                     result = await lintCourse();
                     break;
 
+                case 'coursecode_narration':
+                    result = await generateNarration({
+                        dryRun: args?.dryRun === true,
+                        force: args?.force === true,
+                        slide: args?.slide,
+                        rebuildCache: args?.rebuildCache === true
+                    });
+                    break;
+
 
 
                 default:

package/lib/narration.js

@@ -32,6 +32,7 @@ export async function narration(options = {}) {
   if (options.force) args.push('--force');
   if (options.slide) args.push('--slide', options.slide);
   if (options.dryRun) args.push('--dry-run');
+  if (options.rebuildCache) args.push('--rebuild-cache');
   
   return new Promise((resolve, reject) => {
     const child = spawn('node', args, {

package/lib/preview-routes-api.js

@@ -67,6 +67,47 @@ export async function handleApiRoutes(ctx, req, res, url) {
         return true;
     }
 
+    // Narration freshness check — runtime linter fetches this since it can't
+    // read the filesystem directly. Returns warnings for stale .mp3 files
+    // (audio exists but cached hash differs from current text+settings).
+    // Silent when audio is absent or .narration-cache.json is missing.
+    if (url === '/__lint/narration') {
+        try {
+            const { checkNarrationFreshness } = await import('./build-linter.js');
+            const { flattenStructure } = await import('./validation-rules.js');
+            const configPath = path.join(paths.coursePath, 'course-config.js');
+            if (!fs.existsSync(configPath)) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ warnings: [] }));
+                return true;
+            }
+            // Cache-bust import so edits to course-config.js are picked up
+            const configUrl = `${pathToFileURL(configPath).href}?t=${Date.now()}`;
+            const configModule = await import(configUrl);
+            const courseConfig = configModule.courseConfig || configModule.default;
+            if (!courseConfig?.structure) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ warnings: [] }));
+                return true;
+            }
+            // Respect the same opt-out as the build linter
+            if (courseConfig.lint?.narrationFreshness === false) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ warnings: [], disabled: true }));
+                return true;
+            }
+            const slides = flattenStructure(courseConfig.structure);
+            const warnings = [];
+            checkNarrationFreshness(slides, paths.coursePath, warnings);
+            res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache' });
+            res.end(JSON.stringify({ warnings }));
+        } catch (err) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ warnings: [], error: err.message }));
+        }
+        return true;
+    }
+
     // Refresh course content HTML
     if (url === '/__content') {
         generateContentHtml({ coursePath: paths.coursePath, includeNarration: true })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coursecode",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "Multi-format course authoring framework with CLI tools (SCORM 2004, SCORM 1.2, cmi5, LTI 1.3)",
   "type": "module",
   "bin": {