coursecode 0.1.37 → 0.1.38

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 '../../lib/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);
@@ -202,195 +208,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 lib/narration-parser.js so the build linter can reuse them.
 
 /**
  * Main execution

package/lib/authoring-api.js

@@ -1110,3 +1110,127 @@ 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
+ * @returns {Promise<{success, dryRun, summary, generated, skipped, errors, warnings, output, duration}>}
+ */
+export async function generateNarration(options = {}) {
+    const { dryRun = false, force = false, slide } = 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);
+
+    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 './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,57 @@ 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.'
+                }
+            },
+            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,14 @@ 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
+                    });
+                    break;
+
 
 
                 default:

package/lib/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/package.json

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