retiam 2.0.1 → 2.0.3

package/bin/cli.js

@@ -20,13 +20,17 @@ const exportScript = path.join(__dirname, 'export.js');
 const lintScript = path.join(__dirname, 'lint.js');
 const snapshotScript = path.join(__dirname, 'snapshot.js');
 const initScript = path.join(__dirname, 'init.js');
+const contextScript = path.join(__dirname, 'context.js');
+const lessonScript = path.join(__dirname, 'lesson.js');
 
 function runScript(scriptPath, scriptArgs) {
     if (scriptPath === renderScript || scriptPath === snapshotScript) {
         try {
             createRequire(import.meta.url).resolve('puppeteer');
         } catch {
-            console.error('Retiam installation is incomplete: its required Puppeteer dependency is missing. Reinstall Retiam in your project with: npm install retiam');
+            const message = 'Retiam installation is incomplete: its required Puppeteer dependency is missing. Reinstall Retiam in your project with: npm install retiam';
+            if (scriptPath === snapshotScript && scriptArgs.includes('--json')) console.log(JSON.stringify({ status: 'error', message }));
+            console.error(message);
             process.exit(1);
         }
     }
@@ -48,6 +52,8 @@ Usage:
   npx retiam help <command>                 (detailed help for a single command)
 
 Commands Overview:
+  lesson           Teaching plans, styles, native narration, cue timelines, and captions
+  context          Locate version-matched agent guidance, examples, and API declarations
   init, create     Initialize a complete Retiam WebGPU animation skeleton project
   lint             Statically analyze scenes for runtime hazards and async timing bugs
   snapshot         Capture multi-timestamp visual PNG keyframes via headless WebGPU
@@ -85,7 +91,7 @@ Commands Overview:
 
 ================================================================================
 2. SNAPSHOT (npx retiam snapshot <file> [options])
-   Capture visual PNG keyframe snapshots at specific timeline seconds.
+   Run the named scene directly and capture PNGs at fixed-step timeline seconds.
 
    Arguments:
      <file>                    Target scene TypeScript file (e.g. MyScene.ts)
@@ -95,6 +101,8 @@ Commands Overview:
      -w, --width <px>          Snapshot width in pixels (default: 1280)
      -h, --height <px>         Snapshot height in pixels (default: 720)
      -o, --out <dir>           Output directory for images (default: ./outputs/snapshot)
+     --fps <num>              Timeline step rate (default: 60)
+     --timeout <ms>           Browser operation timeout (default: 120000)
      --json                    Output structured JSON for agents & CI automation
      --help                    Show snapshot-specific help
 
@@ -113,6 +121,8 @@ Commands Overview:
    Options:
      -n, --name <name>         Project name for package.json (default: directory name)
      --title <text>            Hero text for starter Hello World scene (default: Hello World)
+     --template <name>         basic (default) or explainer worked construction
+     --style <name>            mathematical (Dijkstra default), excalidraw, minimal, cinematic
      --pm <manager>            Package manager: npm, pnpm, yarn, bun (default: auto or npm)
      -f, --force               Overwrite destination directory if files already exist
      -y, --yes                 Skip interactive prompts and use defaults
@@ -167,7 +177,13 @@ Commands Overview:
 `);
 }
 
-if (command === 'lint') {
+if (command === 'lesson') {
+    runScript(lessonScript, args.slice(1));
+}
+else if (command === 'context') {
+    runScript(contextScript, args.slice(1));
+}
+else if (command === 'lint') {
     // Usage: npx retiam lint src/MyScene.ts [--json]
     runScript(lintScript, args.slice(1));
 }
@@ -189,7 +205,11 @@ else if (command === 'render') {
 } 
 else if (command === 'help') {
     const sub = args[1];
-    if (sub === 'lint') {
+    if (sub === 'lesson') {
+        runScript(lessonScript, ['--help']);
+    } else if (sub === 'context') {
+        runScript(contextScript, ['--help']);
+    } else if (sub === 'lint') {
         runScript(lintScript, ['--help']);
     } else if (sub === 'snapshot') {
         runScript(snapshotScript, ['--help']);

package/bin/context.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { agentKitRoot } from './agent-kit.js';
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: retiam context [--json]\nLocate guidance, examples, and declarations for this installed Retiam version.');
+} else if (args.some(arg => arg !== '--json')) {
+    const message = 'Unknown option. Usage: retiam context [--json]';
+    if (args.includes('--json')) console.log(JSON.stringify({ status: 'error', message }));
+    else console.error(message);
+    process.exitCode = 1;
+} else {
+    const root = fileURLToPath(new URL('../', import.meta.url));
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    const declarations = path.join(root, manifest.types);
+    const sublibraries = Object.keys(manifest.exports).filter(key => key.startsWith('./') && !key.includes('*'));
+    const libs = path.join(root, 'dist/libs');
+    if (fs.existsSync(libs)) {
+        for (const entry of fs.readdirSync(libs, { withFileTypes: true })) {
+            if (entry.isDirectory() && fs.existsSync(path.join(libs, entry.name, 'index.d.ts'))) sublibraries.push(`./${entry.name}`);
+        }
+    }
+    const result = {
+        status: 'success', version: manifest.version, packageRoot: root,
+        skill: path.join(agentKitRoot, 'skill/SKILL.md'),
+        api: path.join(agentKitRoot, 'skill/references/api.md'),
+        quality: path.join(agentKitRoot, 'skill/references/quality.md'),
+        tts: path.join(agentKitRoot, 'skill/references/tts.md'),
+        explainers: path.join(agentKitRoot, 'skill/references/explainers.md'),
+        styles: path.join(agentKitRoot, 'skill/references/styles.md'),
+        lessonExample: path.join(agentKitRoot, 'templates/explainer/lesson.json'),
+        examples: path.join(agentKitRoot, 'skill/examples'),
+        declarations: fs.existsSync(declarations) ? declarations : null,
+        sublibraries: [...new Set(sublibraries)].map(name => ({
+            import: `retiam/${name.slice(2)}`,
+            declarations: manifest.exports[name]?.types
+                ? path.join(root,manifest.exports[name].types)
+                : name === './license-notices'
+                ? path.join(root, 'bin/third-party.d.ts')
+                : path.join(libs, name.slice(2), 'index.d.ts'),
+        })),
+        commands: {
+            check: 'npm run check',
+            lint: 'retiam lint <scene.ts> --json',
+            snapshot: 'retiam snapshot <scene.ts> --times 0,1,3 --json',
+            render: 'retiam render <scene.ts>',
+            lessonCheck: 'retiam lesson check --json',
+            lessonPrepare: 'retiam lesson prepare',
+            lessonTimeline: 'retiam lesson timeline --json',
+        },
+    };
+    if (args.includes('--json')) console.log(JSON.stringify(result, null, 2));
+    else console.log(`Retiam ${result.version}\n\nSkill: ${result.skill}\nAPI: ${result.api}\nQuality: ${result.quality}\nExamples: ${result.examples}\nDeclarations: ${result.declarations || 'not built'}\n\nType-check → lint → snapshot and inspect → preview → render.\nUse --json for machine-readable paths and commands.`);
+}

package/bin/init.js

@@ -9,6 +9,8 @@ import path from 'path';
 import readline from 'readline/promises';
 import { spawnSync } from 'child_process';
 import { copyThirdPartyNotices } from './third-party.js';
+import { copyAgentKit } from './agent-kit.js';
+import {validateStyleName,explainerSceneSource} from './lesson-project.js';
 
 const args = process.argv.slice(2);
 
@@ -28,6 +30,8 @@ Arguments:
 Options:
   -n, --name <name>         Project name for package.json (default: directory name)
   --title <text>            Hero text to display in Hello World scene (default: Hello World)
+  --template <name>         basic (default) or explainer (worked teaching example)
+  --style <name>            mathematical (Dijkstra default), excalidraw, minimal, cinematic
   --pm <manager>            Package manager: npm, pnpm, yarn, bun (default: auto-detected or npm)
   -f, --force               Overwrite destination directory if files already exist
   -y, --yes                 Skip interactive prompts and use defaults
@@ -65,6 +69,7 @@ let nonInteractive = false;
 let runInstall = false;
 let initGit = false;
 let jsonOutput = false;
+let templateKind='basic', selectedStyle='mathematical';
 
 for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -83,6 +88,10 @@ for (let i = 0; i < args.length; i++) {
         projectName = args[++i];
     } else if (arg === '--title') {
         heroTitle = args[++i] || 'Hello World';
+    } else if(arg==='--template') {
+        templateKind=args[++i];
+    } else if(arg==='--style') {
+        selectedStyle=args[++i];
     } else if (arg === '--pm') {
         packageManager = args[++i] || packageManager;
     } else if (!arg.startsWith('-') && !targetDir) {
@@ -91,6 +100,9 @@ for (let i = 0; i < args.length; i++) {
 }
 
 async function main() {
+    if(typeof selectedStyle!=='string')throw new Error('--style requires a profile name.');
+    validateStyleName(selectedStyle);
+    if(!['basic','explainer'].includes(templateKind))throw new Error('Choose --template basic or explainer.');
     // Interactive setup if TTY and not in --yes / --json mode
     const isTTY = process.stdin.isTTY && !nonInteractive;
 
@@ -147,7 +159,7 @@ async function main() {
 
     // Conflict check
     if (fs.existsSync(resolvedDir)) {
-        const existingFiles = fs.readdirSync(resolvedDir).filter(f => !f.startsWith('.'));
+        const existingFiles = fs.readdirSync(resolvedDir).filter(f => f !== '.git' && f !== '.DS_Store');
         if (existingFiles.length > 0 && !force) {
             if (jsonOutput) {
                 console.log(JSON.stringify({
@@ -175,12 +187,19 @@ async function main() {
         type: 'module',
         scripts: {
             dev: 'node tools/prepare-notices.mjs && vite',
+            check: 'tsc --noEmit',
+            'lint:scene': 'retiam lint src/scenes/HelloWorld.ts',
+            snapshot: 'retiam snapshot',
             build: 'tsc && node tools/prepare-notices.mjs && vite build',
             preview: 'vite preview',
-            render: 'retiam render src/scenes/HelloWorld.ts'
+            render: 'retiam render src/scenes/HelloWorld.ts',
+            'lesson:check': 'retiam lesson check --json',
+            'lesson:prepare': 'retiam lesson prepare',
+            'lesson:timeline': 'retiam lesson timeline --json',
+            'lesson:captions': 'retiam lesson captions'
         },
         dependencies: {
-            retiam: '^1.0.0'
+            retiam: 'latest'
         },
         devDependencies: {
             '@webgpu/types': '^0.1.31',
@@ -200,16 +219,20 @@ async function main() {
             strict: true,
             esModuleInterop: true,
             skipLibCheck: true,
-            isolatedModules: true
+            isolatedModules: true,
+            resolveJsonModule: true
         },
         include: ['src']
     };
 
     // 3. vite.config.ts
     const viteConfig = `import { defineConfig } from 'vite';
+import { msEdgeTTSPlugin } from 'retiam/vite';
 
 export default defineConfig({
+  plugins: [msEdgeTTSPlugin()],
   optimizeDeps: {
+    exclude: ['retiam', 'msedge-tts'],
     esbuildOptions: {
       target: 'es2022',
       supported: {
@@ -278,7 +301,12 @@ async function bootstrap() {
     canvas.height = window.innerHeight;
   });
 
-  const scene = new HelloWorldScene();
+  const file = new URLSearchParams(window.location.search).get('file');
+  const SceneClass = file
+    ? (await import(/* @vite-ignore */ '/' + file.replaceAll('\\\\', '/').replace(/^\\/+/, ''))).default
+    : HelloWorldScene;
+  if (typeof SceneClass !== 'function') throw new Error('The scene must default-export a Scene class.');
+  const scene = new SceneClass();
   await scene.start(canvas);
 }
 
@@ -288,7 +316,9 @@ bootstrap().catch((err) => {
 `;
 
     // 6. src/scenes/HelloWorld.ts
-    const helloWorldTs = `import { Scene, hex, SDFText, Write } from "retiam";
+    const helloWorldTs = `import { CENTER, Scene, hex, Text, Write } from "retiam";
+import {resolveStyle,type StyleInput} from "retiam/explainer";
+import lesson from '../../lesson/lesson.json';
 
 /**
  * Starter Retiam Scene: Hello World
@@ -298,11 +328,12 @@ export default class HelloWorldScene extends Scene {
     public async run(): Promise<void> {
         // 1. Setup camera and obsidian canvas
         this.camera.position.set([0, 0, 14]);
-        this.clearColor(hex("#080C14"));
+        const style=resolveStyle(lesson.style as StyleInput);
+        this.clearColor(hex(style.background));
 
         // 2. Create the hero typography
-        const text = new SDFText("${heroTitle.replace(/"/g, '\\"')}", { fontSize: 1.1 });
-        text.paint.fill = hex("#38BDF8");
+        const text = new Text(${JSON.stringify(heroTitle)}, { fontSize: 1.1, anchor: CENTER, font:style.font });
+        text.paint.fill = hex(style.primary);
         text.center();
 
         // 3. Register entity and frame camera with balanced padding
@@ -352,6 +383,29 @@ A cinematic WebGPU mathematical animation built with [Retiam](https://github.com
 - \`src/scenes/HelloWorld.ts\`: Starter scene with hero typography and \`Write\` animation.
 - \`vite.config.ts\`: Real-time WebGPU bundler configuration with hot module reload.
 
+## AI agents
+
+Start with \`AGENTS.md\` and \`.agents/skills/retiam/SKILL.md\` for the local authoring
+workflow, API notes, checked example, and visual review criteria. Run
+\`npx retiam context --json\` to locate guidance for the installed engine version.
+Type-check with \`npm run check\`, lint each changed scene, then capture and inspect
+snapshots before rendering. See the skill for commands and environment requirements.
+
+Educational projects also include \`lesson/lesson.json\`, style profiles and a review
+record. The default visual/teaching style matches the Dijkstra explainer: navy,
+bright stable colors, continuous constructions and conversational discovery.
+Ask your agent to replace the sample topic and author the corresponding scene.
+\`--template explainer\` starts with a worked square-area construction. To choose
+another look, use \`npx retiam lesson style excalidraw\`; custom JSON profiles can
+extend mathematical, excalidraw, minimal or cinematic. Read the skill's
+\`references/explainers.md\` and \`references/styles.md\` for the full workflow.
+
+Run \`npm run lesson:check\` and \`npm run lesson:timeline\` to inspect the plan.
+The sample previews silently offline. Set \`narration.enabled\` to true and run
+\`npm run lesson:prepare\` for native Retiam speech, then
+\`npm run lesson:captions\` to export timed SRT captions. Inspect frames and listen
+to the final render; automated checks do not establish teaching quality.
+
 ## Licensing
 
 Retiam and its supplied starter code are free for noncommercial use under
@@ -375,8 +429,9 @@ Your own media and dependencies need their own notices and permissions.
     fs.writeFileSync(path.join(resolvedDir, '.gitignore'), gitignore, 'utf8');
     fs.writeFileSync(path.join(resolvedDir, 'README.md'), readme, 'utf8');
     fs.writeFileSync(path.join(srcDir, 'main.ts'), mainTs, 'utf8');
-    fs.writeFileSync(path.join(scenesDir, 'HelloWorld.ts'), helloWorldTs, 'utf8');
+    fs.writeFileSync(path.join(scenesDir, 'HelloWorld.ts'), templateKind==='explainer'?explainerSceneSource():helloWorldTs, 'utf8');
     copyThirdPartyNotices(resolvedDir);
+    const agentFiles = copyAgentKit(resolvedDir,{style:selectedStyle,title:heroTitle==='Hello World'?undefined:heroTitle});
     fs.mkdirSync(path.join(resolvedDir, 'tools'), { recursive: true });
     fs.copyFileSync(new URL('./prepare-notices.js', import.meta.url), path.join(resolvedDir, 'tools/prepare-notices.mjs'));
 
@@ -393,7 +448,8 @@ Your own media and dependencies need their own notices and permissions.
         'COMMERCIAL_LICENSE.md',
         'THIRD_PARTY_NOTICES.md',
         'THIRD_PARTY_LICENSES.txt',
-        'tools/prepare-notices.mjs'
+        'tools/prepare-notices.mjs',
+        ...agentFiles
     ];
 
     // Optional git init
@@ -424,6 +480,8 @@ Your own media and dependencies need their own notices and permissions.
             absolutePath: resolvedDir,
             projectName: resolvedName,
             packageManager,
+            template:templateKind,
+            style:selectedStyle,
             files: createdFiles
         }, null, 2));
     } else {
@@ -444,6 +502,7 @@ Your own media and dependencies need their own notices and permissions.
 }
 
 main().catch((err) => {
-    console.error('Initialization failed:', err);
+    if (jsonOutput) console.log(JSON.stringify({ status: 'error', message: err.message }));
+    else console.error('Initialization failed:', err);
     process.exit(1);
 });

package/bin/lesson-project.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const assets = fileURLToPath(new URL('../agent/templates/explainer/', import.meta.url));
+export function validateStyleName(style = 'mathematical') {
+    const profiles = JSON.parse(fs.readFileSync(path.join(assets, 'styles.json'), 'utf8'));
+    if (!Object.hasOwn(profiles, style))
+        throw new Error(`Unknown style '${style}'. Choose ${Object.keys(profiles).join(', ')}.`);
+    return style;
+}
+export function copyLessonKit(directory, { style = 'mathematical', title } = {}) {
+    validateStyleName(style);
+    const dest = path.join(directory, 'lesson');
+    fs.mkdirSync(dest, { recursive: true });
+    const plan = JSON.parse(fs.readFileSync(path.join(assets, 'lesson.json'), 'utf8'));
+    plan.style = style;
+    if (title)
+        plan.title = title;
+    fs.writeFileSync(path.join(dest, 'lesson.json'), JSON.stringify(plan, null, 2) + '\n');
+    for (const file of ['styles.json', 'review.json'])
+        fs.copyFileSync(path.join(assets, file), path.join(dest, file));
+    return ['lesson/lesson.json', 'lesson/styles.json', 'lesson/review.json'];
+}
+export function explainerSceneSource() {
+    const example = fs.readFileSync(new URL('../agent/skill/examples/AreaLesson.ts', import.meta.url), 'utf8');
+    return example.replace(/\/\/ lesson-config:start[\s\S]*?\/\/ lesson-config:end/, `import lessonData from '../../lesson/lesson.json';
+const plan=lessonData as LessonPlan;
+const preparedFiles=import.meta.glob('../../lesson/prepared.json',{eager:true,import:'default'});
+const prepared=preparedFiles['../../lesson/prepared.json'] as PreparedSpeech|undefined;`);
+}

package/bin/lesson.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+const help = `Usage: retiam lesson <check|prepare|timeline|captions|styles|style> [lesson/lesson.json] [--json]
+
+  check      Validate the plan and any prepared speech; list the remaining human/agent review.
+  prepare    Cache native speech in public/narration and write lesson/prepared.json.
+  timeline   Print the compiled beat, cue and segment times (milliseconds).
+  captions   Write outputs/narration.srt; preserves thinking-pause boundaries.
+  styles     List visual profiles. Default: mathematical (the Dijkstra video aesthetic).
+  style NAME Persist a profile in the lesson. Custom profiles extend one in JSON.
+
+  --out PATH Override the prepared JSON or SRT destination.
+  --json     Emit one machine-readable result; diagnostics go to stderr.
+
+ElevenLabs: set narration.provider to "elevenlabs", choose narration.voice,
+and supply ELEVENLABS_API_KEY in the command environment. The CLI passes it
+directly to provider.init(); no Vite configuration is required.
+
+Examples:
+  retiam lesson style excalidraw
+  retiam lesson check --json
+  retiam lesson prepare
+  retiam lesson timeline --json
+`;
+export async function runLessonCLI(args) {
+    const json = args.includes('--json');
+    if (!args.length || args.includes('--help') || args.includes('-h')) {
+        console.log(help);
+        return;
+    }
+    // Keep stdout machine-readable even when a provider logs directly.
+    if (json) for (const method of ['log', 'info', 'debug']) console[method] = (...values) => console.error(...values);
+    const command = args[0], pos = [];
+    let out;
+    for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--json')
+            continue;
+        if (a === '--out') {
+            out = args[++i];
+            if (!out || out.startsWith('-'))
+                throw new Error('--out requires a path.');
+        }
+        else if (a.startsWith('-'))
+            throw new Error(`Unknown option: ${a}`);
+        else
+            pos.push(a);
+    }
+    if (!['check', 'prepare', 'timeline', 'captions', 'styles', 'style'].includes(command))
+        throw new Error(`Unknown lesson command '${command}'.`);
+    const { validateLesson, assertLesson, resolveStyle, STYLE_PROFILES, voiceKey, speechKey, compileLesson, lessonCaptions } = await import('../dist/libs/explainer/plan.js');
+    const print = result => process.stdout.write((typeof result === 'string' ? result : JSON.stringify(result, null, 2)) + '\n');
+    if (command === 'styles') {
+        if (pos.length || out)
+            throw Error('styles accepts only --json.');
+        print({ status: 'success', default: 'mathematical', profiles: STYLE_PROFILES, custom: 'Set style to {extends:"excalidraw",background:"#102030",...} in the lesson JSON.' });
+        return;
+    }
+    const selected = command === 'style' ? pos.shift() : undefined;
+    if (pos.length > 1)
+        throw Error('Provide one lesson file.');
+    const file = path.resolve(pos[0] ?? 'lesson/lesson.json'), plan = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const preparedFile = path.join(path.dirname(file), 'prepared.json');
+    if (command === 'style') {
+        resolveStyle(selected);
+        plan.style = selected;
+        assertLesson(plan);
+        fs.writeFileSync(file, JSON.stringify(plan, null, 2) + '\n');
+        print({ status: 'success', style: selected, file: path.relative(process.cwd(), file) });
+        return;
+    }
+    const diagnostics = validateLesson(plan);
+    if (diagnostics.length) {
+        print({ status: 'error', diagnostics });
+        process.exitCode = 1;
+        return;
+    }
+    let prepared = fs.existsSync(preparedFile) ? JSON.parse(fs.readFileSync(preparedFile, 'utf8')) : undefined;
+    const warnings = [];
+    if (command === 'prepare') {
+        if (!plan.narration.enabled)
+            throw Error('Narration is disabled. Set narration.enabled to true before preparing speech.');
+        const providerName = plan.narration.provider ?? 'msedge';
+        if (!['msedge', 'elevenlabs'].includes(providerName))
+            throw Error('Import a PreparedSpeech manifest for this provider, or use prepareLesson with a synthesize adapter.');
+        const cache = path.resolve(`node_modules/.cache/${providerName}-tts`), assets = path.resolve('public/narration');
+        fs.mkdirSync(assets, { recursive: true });
+        let server, speechProvider, port;
+        if (providerName === 'elevenlabs') {
+            const { ElevenLabsTTSProvider } = await import('../dist/libs/tts/node/index.js');
+            speechProvider = new ElevenLabsTTSProvider();
+            await speechProvider.init({ ...plan.narration.elevenlabs,
+                apiKey: process.env.ELEVENLABS_API_KEY, voiceId: plan.narration.voice });
+            fs.mkdirSync(cache, { recursive: true });
+        } else {
+            const { createServer } = await import('vite'), { msEdgeTTSPlugin } = await import('../dist/libs/vite/index.js');
+            server = await createServer({ configFile: false, logLevel: 'error', plugins: [msEdgeTTSPlugin({ cacheDir: cache, verbose: false })], server: { host: '127.0.0.1', port: 0, open: false, hmr: false, watch: null }, optimizeDeps: { noDiscovery: true } });
+        }
+        prepared = { version: 1, voiceKey: voiceKey(plan), assets: {} };
+        try {
+            if (server) { await server.listen(); port = server.httpServer.address().port; }
+            // Sequential generation avoids provider throttling; cached requests return immediately.
+            for (const beat of plan.beats)
+                for (const segment of beat.narration) {
+                    const request = providerName === 'msedge'
+                        ? { text: segment.speechText ?? segment.text, voice: plan.narration.voice ?? 'en-US-AndrewNeural', speed: plan.narration.speed ?? 1, pitch: plan.narration.pitch ?? '+0Hz', volume: 1 }
+                        : { text: segment.speechText ?? segment.text, displayText: segment.text, voice: plan.narration.voice, speed: plan.narration.speed, pitch: plan.narration.pitch, elevenlabs: plan.narration.elevenlabs };
+                    const hash = crypto.createHash('sha256').update(JSON.stringify({ provider: providerName, request })).digest('hex');
+                    let result;
+                    if (speechProvider) {
+                        const audioFile = path.join(cache, hash + '.mp3'), metadataFile = path.join(cache, hash + '.json');
+                        if (fs.existsSync(audioFile) && fs.existsSync(metadataFile)) {
+                            result = { ...JSON.parse(fs.readFileSync(metadataFile, 'utf8')), bytes: fs.readFileSync(audioFile) };
+                        } else {
+                            const audio = await speechProvider.synthesize(request.text, request);
+                            result = { bytes: Buffer.from(audio.rawBuffer), durationMs: audio.durationMs, words: audio.wordBoundaries ?? [] };
+                            if (!result.words.length) throw Error('ElevenLabs returned no word timings; narration was not prepared.');
+                            fs.writeFileSync(audioFile, result.bytes);
+                            fs.writeFileSync(metadataFile, JSON.stringify({ durationMs: result.durationMs, words: result.words }));
+                        }
+                    } else for (let attempt = 0; attempt < 3; attempt++) {
+                        try {
+                            const res = await fetch(`http://127.0.0.1:${port}/api/tts/msedge/synthesize`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(request), signal: AbortSignal.timeout(90000) });
+                            if (!res.ok)
+                                throw Error(`Native TTS HTTP ${res.status}: ${await res.text()}`);
+                            const bytes = Buffer.from(await res.arrayBuffer()), durationMs = Number(res.headers.get('x-audio-duration-ms')), words = JSON.parse(decodeURIComponent(res.headers.get('x-word-boundaries') ?? '%5B%5D'));
+                            if (!durationMs || bytes.length < 1000)
+                                throw Error('Native TTS returned empty audio.');
+                            result = { bytes, durationMs, words };
+                            break;
+                        }
+                        catch (error) {
+                            if (attempt === 2)
+                                throw error;
+                            console.error(`Retrying ${beat.id}/${segment.id}: ${error.message}`);
+                        }
+                    }
+                    fs.writeFileSync(path.join(assets, hash + '.mp3'), result.bytes);
+                    prepared.assets[speechKey(beat.id, segment.id)] = { text: segment.text, speechText: segment.speechText, durationMs: result.durationMs, words: result.words, url: `/narration/${hash}.mp3` };
+                }
+        }
+        finally {
+            await server?.close();
+            await speechProvider?.dispose();
+        }
+        compileLesson(plan, prepared);
+        const dest = path.resolve(out ?? preparedFile);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, JSON.stringify(prepared, null, 2) + '\n');
+        print({ status: 'success', file: path.relative(process.cwd(), dest), segments: Object.keys(prepared.assets).length });
+        return;
+    }
+    let timeline;
+    if (plan.narration.enabled && !prepared) {
+        warnings.push('Speech is not prepared. Run retiam lesson prepare before locking narration cues.');
+        if (command !== 'check')
+            throw Error(warnings[0]);
+    }
+    else
+        timeline = compileLesson(plan, prepared);
+    if (plan.narration.enabled && prepared)
+        for (const [id, asset] of Object.entries(prepared.assets)) {
+            if (!asset.url)
+                throw Error(`No audio URL for ${id}.`);
+            if (asset.url.startsWith('/')) {
+                const base = path.resolve('public'), dest = path.resolve(base, '.' + asset.url);
+                if (!dest.startsWith(base + path.sep) || !fs.existsSync(dest))
+                    throw Error(`Missing local audio asset for ${id}: ${asset.url}`);
+            }
+            else
+                warnings.push(`Audio URL ${asset.url} needs runtime availability review.`);
+        }
+    if (command === 'captions') {
+        if (timeline.timing !== 'recorded')
+            throw Error('Silent preview timing is estimated; prepare narration before exporting captions.');
+        const dest = path.resolve(out ?? 'outputs/narration.srt');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, lessonCaptions(timeline));
+        print({ status: 'success', file: path.relative(process.cwd(), dest) });
+        return;
+    }
+    if (command === 'timeline') {
+        print({ status: 'success', ...timeline });
+        return;
+    }
+    print({ status: 'success', automated: { schema: 'passed', timing: timeline?.timing ?? 'not-prepared', speechAssets: plan.narration.enabled ? prepared ? 'checked' : 'not-prepared' : 'disabled' }, warnings, style: resolveStyle(plan.style), snapshotTimes: timeline?.beats.flatMap(b => [b.startMs / 1000, (b.startMs + b.durationMs * .6) / 1000]), requiredReview: ['Verify claims and illustrative assumptions.', 'Inspect rendered frames for overlap, continuity, and readability.', 'Watch motion and narration at normal speed.', 'Check final video/audio streams and caption timing.'] });
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url))
+    runLessonCLI(process.argv.slice(2)).catch(error => { if (process.argv.includes('--json'))
+        process.stdout.write(JSON.stringify({ status: 'error', message: error.message }) + '\n');
+    else
+        console.error(error.message); process.exitCode = 1; });

package/bin/lint.js

@@ -99,11 +99,11 @@ function getLineAndCol(node) {
 
 // Known Retiam Entity classes
 const ENTITY_CLASSES = new Set([
-    'Circle', 'Rect', 'Line', 'Arrow', 'Polygon', 'RegularPolygon',
+    'Circle', 'Rect', 'Line', 'Arrow', 'Poly', 'RegularPolygon',
     'Arc', 'Sector', 'Annulus', 'Dot', 'GlowDot', 'Path', 'SVGShape', 'SVG',
-    'SDFText', 'Tex', 'Code', 'Axes', 'NumberLine', 'Graph', 'BarChart',
-    'PieChart', 'Model', 'Sphere', 'Box3D', 'Cylinder', 'Cone', 'Plane',
-    'Mesh', 'MorphModel', 'TracePath', 'VBox', 'HBox', 'Group'
+    'Text', 'SDFText', 'Tex', 'Code', 'Axes', 'NumberLine', 'Graph', 'BarChart',
+    'PieChart', 'Model', 'Sphere', 'Box', 'Cylinder', 'Cone', 'Plane',
+    'Mesh', 'MorphModel', 'TracePath', 'VBox', 'HBox', 'Group', 'VGroup'
 ]);
 
 // Track instantiated entities to check if they are added
@@ -215,8 +215,8 @@ function checkNode(node) {
                 'retiam/no-threejs',
                 line,
                 col,
-                'Detected Three.js reference. Retiam uses native WebGPU entities (e.g. Model, Sphere, Box3D).',
-                'Use Retiam 3D primitives: import { Model, Sphere, Box3D } from "retiam"'
+                'Detected Three.js reference. Retiam uses native WebGPU entities (e.g. Model, Sphere, Box).',
+                'Use Retiam 3D primitives: import { Model, Sphere, Box } from "retiam"'
             );
         }
     }