@afromero/kin3o 0.2.2 → 0.2.4

package/README.md

@@ -5,6 +5,7 @@
 **Text to Motion. From your terminal.**
 
 [![npm](https://img.shields.io/npm/v/@afromero/kin3o)](https://www.npmjs.com/package/@afromero/kin3o)
+[![downloads](https://img.shields.io/npm/dm/@afromero/kin3o)](https://www.npmjs.com/package/@afromero/kin3o)
 [![CI](https://github.com/affromero/kin3o/actions/workflows/ci.yml/badge.svg)](https://github.com/affromero/kin3o/actions/workflows/ci.yml)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
@@ -92,6 +93,13 @@ kin3o login                                            # Authenticate for publis
 kin3o publish output/anim.json --name "My Anim" --tags "loading,ui"
 kin3o logout                                           # Clear auth token
 
+# Export to video
+kin3o export output/animation.json                     # MP4 (default: 1080p 30fps)
+kin3o export output/animation.json --format gif        # GIF
+kin3o export output/animation.json --format webm       # WebM (supports transparency)
+kin3o export output/animation.lottie --res 720p        # dotLottie → MP4 at 720p
+kin3o export output/animation.json --bg white -o out.mp4  # Custom background + path
+
 # Live preview with hot reload
 kin3o view output/animation.json                       # File watcher + auto-reload
 kin3o view output/animation.lottie --port 3000         # Specific port
@@ -114,6 +122,10 @@ kin3o view output/animation.lottie --port 3000         # Specific port
 | `--no-browser` | Print search results in terminal |
 | `--lottie` | Download `.lottie` format instead of `.json` |
 | `--port <n>` | Port for view server (auto-selects if omitted) |
+| `--format <fmt>` | Export format: `mp4`, `webm`, `gif` (default: `mp4`) |
+| `--res <res>` | Export resolution: `1080p`, `720p`, `480p`, `4k`, or `WxH` |
+| `--fps <n>` | Export frames per second (default: `30`) |
+| `--bg <color>` | Export background color (hex or name) |
 
 ## Using Generated Animations
 
@@ -183,6 +195,7 @@ Lottie covers shapes, paths, easing, color transitions, masking, and — via dot
 ```
 Static:      prompt → generate() → extractJson() → validateLottie() → autoFix() → .json → preview
 Interactive: prompt → generate() → extractInteractiveJson() → validate animations + state machine → .lottie → preview
+Export:      .json/.lottie → headless Chrome (lottie-web) → frame capture → FFmpeg → MP4/WebM/GIF
 Marketplace: search → browse → download → validate → .json/.lottie → refine → publish
 Live preview: view <file> → HTTP server + fs.watch → SSE → browser auto-reload
 ```
@@ -200,6 +213,21 @@ All prompts live in `src/prompts/` with a barrel export at `src/prompts/index.ts
 | `examples-mascot.ts` | kin3o mascot/logo (static + interactive) |
 | `tokens.ts` | Design token loader (hex → Lottie RGBA) |
 
+## Prerequisites for Export
+
+The `export` command requires Chrome/Chromium and FFmpeg installed on your system:
+
+```bash
+# macOS
+brew install --cask google-chrome
+brew install ffmpeg
+
+# Linux
+sudo apt install chromium-browser ffmpeg
+```
+
+Or set `CHROME_PATH` and `FFMPEG_PATH` environment variables to custom paths.
+
 ## Development
 
 ```bash
@@ -210,6 +238,14 @@ npm run ci           # typecheck + test
 npm run build        # Compile to dist/
 ```
 
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [**Fairtrail**](https://github.com/affromero/fairtrail) | Flight price evolution tracker with natural language search |
+| [**PriceToken**](https://github.com/affromero/pricetoken) | Real-time LLM pricing API, npm/PyPI packages, and live dashboard |
+| [**gitpane**](https://github.com/affromero/gitpane) | Multi-repo Git workspace dashboard for the terminal |
+
 ## License
 
 MIT

package/dist/export.d.ts

@@ -0,0 +1,31 @@
+export interface ExportOptions {
+    format: 'mp4' | 'webm' | 'gif';
+    width: number;
+    height: number;
+    fps: number;
+    background: string | 'transparent';
+    output: string;
+}
+export interface AnimationMeta {
+    width: number;
+    height: number;
+    frameRate: number;
+    inPoint: number;
+    outPoint: number;
+    totalFrames: number;
+    durationSeconds: number;
+}
+export declare function parseResolution(res: string): {
+    width: number;
+    height: number;
+};
+export declare function detectChromePath(): string | null;
+export declare function detectFfmpeg(): string | null;
+export declare function extractAnimationMeta(lottieJson: object): AnimationMeta;
+export declare function extractLottieJsonFromFile(filePath: string): Promise<object>;
+export declare function buildFfmpegArgs(ffmpegPath: string, format: ExportOptions['format'], fps: number, outputPath: string, tempDir?: string): {
+    pass1?: string[];
+    pass2: string[];
+    ffmpegPath: string;
+};
+export declare function exportAnimation(filePath: string, options: ExportOptions, onProgress?: (frame: number, total: number) => void): Promise<string>;

package/dist/export.js

@@ -0,0 +1,265 @@
+import { createServer } from 'node:http';
+import { readFileSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawn, execSync } from 'node:child_process';
+import puppeteer from 'puppeteer-core';
+import { readDotLottie } from './packager.js';
+const templateDir = join(fileURLToPath(new URL('.', import.meta.url)), '..', 'preview');
+const RESOLUTION_PRESETS = {
+    '1080p': { width: 1920, height: 1080 },
+    '720p': { width: 1280, height: 720 },
+    '480p': { width: 854, height: 480 },
+    '360p': { width: 640, height: 360 },
+    '4k': { width: 3840, height: 2160 },
+};
+export function parseResolution(res) {
+    const preset = RESOLUTION_PRESETS[res.toLowerCase()];
+    if (preset)
+        return preset;
+    const match = res.match(/^(\d+)x(\d+)$/);
+    if (match) {
+        const width = parseInt(match[1], 10);
+        const height = parseInt(match[2], 10);
+        if (width > 0 && height > 0)
+            return { width, height };
+    }
+    throw new Error(`Invalid resolution "${res}". Use 1080p, 720p, 480p, 360p, 4k, or WxH (e.g. 800x600)`);
+}
+export function detectChromePath() {
+    const envPath = process.env['CHROME_PATH'];
+    if (envPath)
+        return envPath;
+    if (process.platform === 'darwin') {
+        const candidates = [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+            '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+        ];
+        for (const p of candidates) {
+            try {
+                execSync(`test -f "${p}"`, { stdio: 'ignore' });
+                return p;
+            }
+            catch { /* not found */ }
+        }
+    }
+    if (process.platform === 'linux') {
+        const candidates = ['google-chrome', 'chromium-browser', 'chromium'];
+        for (const bin of candidates) {
+            try {
+                return execSync(`which ${bin}`, { encoding: 'utf-8' }).trim();
+            }
+            catch { /* not found */ }
+        }
+    }
+    if (process.platform === 'win32') {
+        const candidates = [
+            'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+            'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+        ];
+        for (const p of candidates) {
+            try {
+                execSync(`if exist "${p}" exit 0`, { stdio: 'ignore' });
+                return p;
+            }
+            catch { /* not found */ }
+        }
+    }
+    return null;
+}
+export function detectFfmpeg() {
+    const envPath = process.env['FFMPEG_PATH'];
+    if (envPath)
+        return envPath;
+    try {
+        return execSync('which ffmpeg', { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function extractAnimationMeta(lottieJson) {
+    const json = lottieJson;
+    const width = json['w'];
+    const height = json['h'];
+    const frameRate = json['fr'];
+    const inPoint = json['ip'];
+    const outPoint = json['op'];
+    if (typeof width !== 'number' || typeof height !== 'number' ||
+        typeof frameRate !== 'number' || typeof inPoint !== 'number' ||
+        typeof outPoint !== 'number') {
+        throw new Error('Invalid Lottie JSON: missing required fields (w, h, fr, ip, op)');
+    }
+    const totalFrames = outPoint - inPoint;
+    if (totalFrames <= 0) {
+        throw new Error(`Animation has zero duration (op=${outPoint} equals ip=${inPoint})`);
+    }
+    const durationSeconds = totalFrames / frameRate;
+    return { width, height, frameRate, inPoint, outPoint, totalFrames, durationSeconds };
+}
+export async function extractLottieJsonFromFile(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    if (ext === '.lottie') {
+        const { animations } = await readDotLottie(filePath);
+        const entries = Object.entries(animations);
+        if (entries.length === 0) {
+            throw new Error('No animations found in .lottie file');
+        }
+        if (entries.length > 1) {
+            console.log(`  Note: .lottie has ${entries.length} animations — exporting "${entries[0][0]}"`);
+        }
+        return entries[0][1];
+    }
+    const raw = readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw);
+}
+export function buildFfmpegArgs(ffmpegPath, format, fps, outputPath, tempDir) {
+    const baseInput = ['-y', '-f', 'image2pipe', '-c:v', 'png', '-framerate', String(fps), '-i', 'pipe:0'];
+    switch (format) {
+        case 'mp4':
+            return {
+                ffmpegPath,
+                pass2: [...baseInput, '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-preset', 'medium', '-crf', '18', outputPath],
+            };
+        case 'webm':
+            return {
+                ffmpegPath,
+                pass2: [...baseInput, '-c:v', 'libvpx-vp9', '-pix_fmt', 'yuva420p', '-crf', '30', '-b:v', '0', outputPath],
+            };
+        case 'gif': {
+            if (!tempDir)
+                throw new Error('GIF export requires a temp directory');
+            const palette = join(tempDir, 'palette.png');
+            return {
+                ffmpegPath,
+                pass1: [
+                    '-y', '-framerate', String(fps),
+                    '-i', join(tempDir, '%06d.png'),
+                    '-vf', 'palettegen=stats_mode=diff',
+                    palette,
+                ],
+                pass2: [
+                    '-y', '-framerate', String(fps),
+                    '-i', join(tempDir, '%06d.png'),
+                    '-i', palette,
+                    '-lavfi', 'paletteuse=dither=floyd_steinberg',
+                    outputPath,
+                ],
+            };
+        }
+    }
+}
+function serveExportPage(lottieJson, background) {
+    const template = readFileSync(join(templateDir, 'template-export.html'), 'utf-8');
+    const html = template
+        .replace('__ANIMATION_DATA__', JSON.stringify(lottieJson))
+        .replace('__BACKGROUND_COLOR__', background === 'transparent' ? 'transparent' : background);
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(html);
+    });
+    return new Promise((resolve) => {
+        server.listen(0, () => {
+            const port = server.address().port;
+            resolve({
+                url: `http://localhost:${port}`,
+                close: () => server.close(),
+            });
+        });
+    });
+}
+function runFfmpeg(ffmpegPath, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(ffmpegPath, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        proc.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`FFmpeg exited with code ${code}: ${stderr.slice(-500)}`));
+        });
+        proc.on('error', reject);
+    });
+}
+export async function exportAnimation(filePath, options, onProgress) {
+    const chromePath = detectChromePath();
+    if (!chromePath) {
+        throw new Error('Chrome or Chromium not found. Install Chrome or set CHROME_PATH environment variable.' +
+            (process.platform === 'darwin' ? '\n  brew install --cask google-chrome' : ''));
+    }
+    const ffmpegPath = detectFfmpeg();
+    if (!ffmpegPath) {
+        throw new Error('FFmpeg not found. Install FFmpeg or set FFMPEG_PATH environment variable.' +
+            (process.platform === 'darwin' ? '\n  brew install ffmpeg' : ''));
+    }
+    const lottieJson = await extractLottieJsonFromFile(filePath);
+    const meta = extractAnimationMeta(lottieJson);
+    const { totalFrames } = meta;
+    const server = await serveExportPage(lottieJson, options.background);
+    const browser = await puppeteer.launch({
+        executablePath: chromePath,
+        headless: true,
+        args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-gpu'],
+    });
+    let tempDir;
+    try {
+        const page = await browser.newPage();
+        await page.setViewport({ width: options.width, height: options.height });
+        await page.goto(server.url, { waitUntil: 'networkidle0' });
+        await page.waitForFunction('window.__animReady === true', { timeout: 10000 });
+        const omitBackground = options.format !== 'mp4' && options.background === 'transparent';
+        if (options.format === 'gif') {
+            tempDir = mkdtempSync(join(tmpdir(), 'kin3o-export-'));
+            for (let i = 0; i < totalFrames; i++) {
+                await page.evaluate((f) => window.__goToFrame(f), i);
+                const buffer = await page.screenshot({ type: 'png', omitBackground });
+                writeFileSync(join(tempDir, `${String(i).padStart(6, '0')}.png`), buffer);
+                onProgress?.(i + 1, totalFrames);
+            }
+            const ffmpegArgs = buildFfmpegArgs(ffmpegPath, 'gif', options.fps, options.output, tempDir);
+            await runFfmpeg(ffmpegPath, ffmpegArgs.pass1);
+            await runFfmpeg(ffmpegPath, ffmpegArgs.pass2);
+        }
+        else {
+            const ffmpegArgs = buildFfmpegArgs(ffmpegPath, options.format, options.fps, options.output);
+            const proc = spawn(ffmpegPath, ffmpegArgs.pass2, { stdio: ['pipe', 'ignore', 'pipe'] });
+            let ffmpegError = '';
+            proc.stderr.on('data', (chunk) => { ffmpegError += chunk.toString(); });
+            const ffmpegDone = new Promise((resolve, reject) => {
+                proc.on('close', (code) => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`FFmpeg exited with code ${code}: ${ffmpegError.slice(-500)}`));
+                });
+                proc.on('error', reject);
+            });
+            for (let i = 0; i < totalFrames; i++) {
+                await page.evaluate((f) => window.__goToFrame(f), i);
+                const buffer = await page.screenshot({ type: 'png', omitBackground });
+                await new Promise((resolve, reject) => {
+                    proc.stdin.write(buffer, (err) => {
+                        if (err)
+                            reject(err);
+                        else
+                            resolve();
+                    });
+                });
+                onProgress?.(i + 1, totalFrames);
+            }
+            proc.stdin.end();
+            await ffmpegDone;
+        }
+        return options.output;
+    }
+    finally {
+        await browser.close();
+        server.close();
+        if (tempDir) {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+    }
+}

package/dist/index.js

@@ -13,6 +13,7 @@ import { searchAnimations, featuredAnimations, popularAnimations, recentAnimatio
 import { openSearchResults } from './marketplace-preview.js';
 import { loadAuthToken, loadAuthExpiry, saveAuthToken, clearAuthToken } from './marketplace-auth.js';
 import { startViewServer } from './view.js';
+import { exportAnimation, parseResolution, extractLottieJsonFromFile, extractAnimationMeta } from './export.js';
 const program = new Command();
 program
     .name('kin3o')
@@ -27,6 +28,7 @@ program
     .option('--no-preview', 'Skip opening preview in browser')
     .option('-t, --tokens <path>', 'Path to design tokens JSON (or "sotto" for built-in)')
     .option('-i, --interactive', 'Generate interactive state machine (.lottie output)', false)
+    .option('--timeout <ms>', 'CLI subprocess timeout in milliseconds (default: auto per model)', parseInt)
     .action(async (prompt, options) => {
     const mode = options.interactive ? 'interactive' : 'static';
     console.log(`\nkin3o — Generating ${mode} animation...`);
@@ -55,7 +57,7 @@ program
         : buildSystemPrompt(tokens);
     // 4. Generate
     try {
-        const result = await provider.generate(model, systemPrompt, prompt);
+        const result = await provider.generate(model, systemPrompt, prompt, options.timeout);
         console.log(`  ✓ Generated in ${(result.durationMs / 1000).toFixed(1)}s`);
         if (options.interactive) {
             await handleInteractiveOutput(result.content, prompt, options);
@@ -165,6 +167,7 @@ program
     .option('-o, --output <path>', 'Output file path')
     .option('--no-preview', 'Skip opening preview in browser')
     .option('-t, --tokens <path>', 'Path to design tokens JSON (or "sotto" for built-in)')
+    .option('--timeout <ms>', 'CLI subprocess timeout in milliseconds (default: 600000)', parseInt)
     .action(async (file, prompt, rawOptions) => {
     const resolvedPath = resolve(file);
     // 1. Validate input file
@@ -224,7 +227,7 @@ program
         : buildRefinementUserPrompt(currentJson, prompt);
     // 6. Generate refined output
     try {
-        const result = await provider.generate(model, systemPrompt, userPrompt);
+        const result = await provider.generate(model, systemPrompt, userPrompt, rawOptions.timeout);
         console.log(`  ✓ Refined in ${(result.durationMs / 1000).toFixed(1)}s`);
         // 7. Compute output path
         const outputDir = ensureOutputDir();
@@ -265,6 +268,75 @@ program
         process.exit(1);
     }
 });
+program
+    .command('export <file>')
+    .description('Export a Lottie animation to MP4, WebM, or GIF video')
+    .option('--format <format>', 'Output format: mp4, webm, gif', 'mp4')
+    .option('--res <resolution>', 'Resolution: 1080p, 720p, 480p, 360p, 4k, or WxH', '1080p')
+    .option('--fps <fps>', 'Frames per second', '30')
+    .option('-o, --output <path>', 'Output file path')
+    .option('--bg <color>', 'Background color (hex or name, default: black for mp4, transparent for gif/webm)')
+    .action(async (file, options) => {
+    const resolvedPath = resolve(file);
+    if (!existsSync(resolvedPath)) {
+        console.error(`  ✗ File not found: ${resolvedPath}`);
+        process.exit(1);
+    }
+    const format = options.format.toLowerCase();
+    if (!['mp4', 'webm', 'gif'].includes(format)) {
+        console.error(`  ✗ Unsupported format "${options.format}". Use mp4, webm, or gif.`);
+        process.exit(1);
+    }
+    let resolution;
+    try {
+        resolution = parseResolution(options.res);
+    }
+    catch (err) {
+        console.error(`  ✗ ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    const fps = parseInt(options.fps, 10);
+    if (isNaN(fps) || fps <= 0) {
+        console.error(`  ✗ Invalid fps "${options.fps}". Must be a positive number.`);
+        process.exit(1);
+    }
+    let background = options.bg ?? (format === 'mp4' ? '#000000' : 'transparent');
+    if (format === 'mp4' && background === 'transparent') {
+        console.log('  ⚠ MP4 does not support transparency — using black background. Use --format webm for alpha.');
+        background = '#000000';
+    }
+    const outputDir = ensureOutputDir();
+    const slug = slugify(file.replace(/\.[^.]+$/, '').split('/').pop() ?? 'animation');
+    const outputPath = options.output
+        ? resolve(options.output)
+        : join(outputDir, `${slug}.${format}`);
+    console.log('\nkin3o — Exporting animation...');
+    try {
+        const lottieJson = await extractLottieJsonFromFile(resolvedPath);
+        const meta = extractAnimationMeta(lottieJson);
+        console.log(`  Source: ${file}`);
+        console.log(`  Format: ${format.toUpperCase()} ${resolution.width}x${resolution.height} @ ${fps}fps`);
+        console.log(`  Duration: ${meta.durationSeconds.toFixed(1)}s (${meta.totalFrames} frames)\n`);
+        await exportAnimation(resolvedPath, {
+            format: format,
+            width: resolution.width,
+            height: resolution.height,
+            fps,
+            background,
+            output: outputPath,
+        }, (frame, total) => {
+            const pct = Math.round((frame / total) * 100);
+            process.stdout.write(`\r  Exporting: frame ${frame}/${total} (${pct}%)`);
+        });
+        process.stdout.write('\n');
+        console.log(`  ✓ Exported to ${outputPath}\n`);
+    }
+    catch (err) {
+        process.stdout.write('\n');
+        console.error(`  ✗ Export failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
 program
     .command('view <file>')
     .description('Live preview with hot reload (file watcher + auto-reload)')

package/dist/providers/claude.d.ts

@@ -1,2 +1,2 @@
 import type { GenerationResult } from './registry.js';
-export declare function generateWithClaude(model: string, systemPrompt: string, userPrompt: string): Promise<GenerationResult>;
+export declare function generateWithClaude(model: string, systemPrompt: string, userPrompt: string, timeoutMs?: number): Promise<GenerationResult>;

package/dist/providers/claude.js

@@ -1,13 +1,15 @@
 import { spawn } from 'node:child_process';
+import { getTimeoutMs } from './registry.js';
 import { filterCliStderr } from '../utils.js';
-export async function generateWithClaude(model, systemPrompt, userPrompt) {
+export async function generateWithClaude(model, systemPrompt, userPrompt, timeoutMs) {
     const start = Date.now();
     const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
+    const timeout = getTimeoutMs(timeoutMs);
     const content = await new Promise((resolve, reject) => {
         const env = { ...process.env };
         delete env.ANTHROPIC_API_KEY;
         const proc = spawn('claude', ['--print', '--model', model], {
-            timeout: 240_000,
+            timeout,
             env,
         });
         let stdout = '';
@@ -21,7 +23,8 @@ export async function generateWithClaude(model, systemPrompt, userPrompt) {
         proc.on('close', (code) => {
             if (code !== 0) {
                 const filtered = filterCliStderr(stderr);
-                reject(new Error(`claude CLI exited ${code}: ${filtered}`));
+                const hint = code === 143 ? ` (timed out after ${Math.round(timeout / 1000)}s — try --timeout <ms> or a faster model)` : '';
+                reject(new Error(`claude CLI exited ${code}: ${filtered}${hint}`));
             }
             else {
                 resolve(stdout.trim());

package/dist/providers/codex.d.ts

@@ -1,2 +1,2 @@
 import type { GenerationResult } from './registry.js';
-export declare function generateWithCodex(model: string, systemPrompt: string, userPrompt: string): Promise<GenerationResult>;
+export declare function generateWithCodex(model: string, systemPrompt: string, userPrompt: string, timeoutMs?: number): Promise<GenerationResult>;

package/dist/providers/codex.js

@@ -2,11 +2,13 @@ import { spawn } from 'node:child_process';
 import { mkdtempSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
+import { getTimeoutMs } from './registry.js';
 import { filterCliStderr } from '../utils.js';
-export async function generateWithCodex(model, systemPrompt, userPrompt) {
+export async function generateWithCodex(model, systemPrompt, userPrompt, timeoutMs) {
     const start = Date.now();
     const fullPrompt = `${systemPrompt}\n\n${userPrompt}`;
     const tmpFile = join(mkdtempSync(join(tmpdir(), 'codex-')), 'output.txt');
+    const timeout = getTimeoutMs(timeoutMs);
     const args = [
         'exec', '-',
         '--skip-git-repo-check',
@@ -16,7 +18,7 @@ export async function generateWithCodex(model, systemPrompt, userPrompt) {
     ];
     const content = await new Promise((resolve, reject) => {
         const proc = spawn('codex', args, {
-            timeout: 240_000,
+            timeout,
             env: { ...process.env },
         });
         let stderr = '';
@@ -27,7 +29,9 @@ export async function generateWithCodex(model, systemPrompt, userPrompt) {
             const filtered = filterCliStderr(stderr);
             const hint = filtered.includes('401') || filtered.includes('Unauthorized')
                 ? ' (ensure codex is authenticated via `codex auth`)'
-                : '';
+                : code === 143
+                    ? ` (timed out after ${Math.round(timeout / 1000)}s — try --timeout <ms> or a faster model)`
+                    : '';
             try {
                 const output = readFileSync(tmpFile, 'utf-8').trim();
                 unlinkSync(tmpFile);

package/dist/providers/registry.d.ts

@@ -9,8 +9,10 @@ export interface ProviderConfig {
     models: string[];
     defaultModel: string;
     isAvailable: () => Promise<boolean>;
-    generate: (model: string, systemPrompt: string, userPrompt: string) => Promise<GenerationResult>;
+    generate: (model: string, systemPrompt: string, userPrompt: string, timeoutMs?: number) => Promise<GenerationResult>;
 }
+/** Get timeout with optional user override */
+export declare function getTimeoutMs(userOverride?: number): number;
 export declare const PROVIDERS: Record<string, ProviderConfig>;
 /** Detect which providers are available (binary + auth) */
 export declare function detectAvailableProviders(): Promise<string[]>;

package/dist/providers/registry.js

@@ -4,6 +4,12 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { generateWithClaude } from './claude.js';
 import { generateWithCodex } from './codex.js';
+/** Default CLI subprocess timeout: 10 minutes */
+const DEFAULT_TIMEOUT_MS = 600_000;
+/** Get timeout with optional user override */
+export function getTimeoutMs(userOverride) {
+    return userOverride ?? DEFAULT_TIMEOUT_MS;
+}
 const home = homedir();
 function hasBinary(name) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afromero/kin3o",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "AI-powered Lottie animation generator — text to motion from your terminal",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,9 @@
     "@anthropic-ai/sdk": "^0.78.0",
     "@dotlottie/dotlottie-js": "^1.6.3",
     "commander": "^13.0.0",
-    "open": "^10.1.0"
+    "lottie-react": "^2.4.1",
+    "open": "^10.1.0",
+    "puppeteer-core": "^24.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.0",

package/preview/template-export.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    background: __BACKGROUND_COLOR__;
+    width: 100vw;
+    height: 100vh;
+    overflow: hidden;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  #animation-container {
+    width: 100vw;
+    height: 100vh;
+  }
+</style>
+</head>
+<body>
+<div id="animation-container"></div>
+
+<script src="https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js"></script>
+<script>
+  window.__animReady = false;
+
+  const animData = __ANIMATION_DATA__;
+  const anim = lottie.loadAnimation({
+    container: document.getElementById('animation-container'),
+    renderer: 'svg',
+    loop: false,
+    autoplay: false,
+    animationData: animData,
+  });
+
+  anim.addEventListener('DOMLoaded', function() {
+    window.__animReady = true;
+  });
+
+  window.__goToFrame = function(frame) {
+    anim.goToAndStop(frame, true);
+  };
+</script>
+</body>
+</html>