retiam 1.0.0 → 1.0.1

package/bin/render.js

@@ -1,600 +1,517 @@
-#!/usr/bin/env node
-
-// =========================================================================
-// File: bin/render.js
-// =========================================================================
-
-import { spawn, spawnSync } from 'child_process';
-import { WebSocketServer } from 'ws';
-import puppeteer from 'puppeteer';
-import cliProgress from 'cli-progress';
-import fs from 'fs';
-import path from 'path';
-import { pathToFileURL } from 'url';
-import { createServer } from 'vite';
-
-const scriptStartTime = Date.now();
-const projectRoot = process.cwd(); // Target the user's current working directory
-
-// 1. Resolve and Load Configuration File (retiam.config.js or config.js in project root)
-let configPath = path.resolve(projectRoot, 'retiam.config.js');
-if (!fs.existsSync(configPath)) {
-    configPath = path.resolve(projectRoot, 'config.js');
-}
-
-let defaultConfig = {};
-let configSource = 'built-in defaults';
-
-if (fs.existsSync(configPath)) {
-    try {
-        const configModule = await import(pathToFileURL(configPath).href);
-        defaultConfig = configModule.default || {};
-        configSource = path.basename(configPath);
-    } catch (err) {
-        console.warn(`⚠️  Failed to import ${path.basename(configPath)}, falling back to default values.`, err);
-    }
-}
-
-const args = process.argv.slice(2);
-
-// Check for --help before parsing options
-const isHelp = args.includes('--help') || args.some((arg, idx) => arg === '-h' && (idx + 1 >= args.length || isNaN(parseInt(args[idx + 1], 10))));
-if (isHelp) {
-    console.log(`
-🎬 Retiam WebGPU Engine - Video Renderer
-
-Usage:
-  npx retiam render [file] [options]
-  npx retiam [file] [options]
-
-Arguments:
-  [file]                    Target scene TypeScript file (e.g. src/scenes/AStarScene.ts)
-                            If omitted, renders the default scene defined in src/main.ts.
-
-Options:
-  -w, --width <px>          Output video width in pixels (default: 1920)
-  -h, --height <px>         Output video height in pixels (default: 1080)
-  -f, --fps <num>           Render frame rate (default: 60)
-  -d, --duration <ms>       Maximum rendering duration limit in milliseconds
-  -o, --out <dir>           Output directory for rendered video (default: ./outputs/video)
-  --raytrace [true|false]   Enable or disable hardware raytracing
-  --no-raytrace             Explicitly disable raytracing
-  --denoiser <format>       Denoiser pipeline ('none', 'spatial', 'oidn', 'native')
-  --raw                     Use native raw HDR frame buffer export
-  --replay <file.json>      Replay recorded interactions JSON during rendering
-  --help                    Show this help message and exit
-
-Examples:
-  npx retiam render src/scenes/AStarScene.ts
-  npx retiam render MyScene.ts -w 1920 -h 1080 -f 60
-  npx retiam render MyScene.ts -o ./outputs/video -d 15000
-`);
-    process.exit(0);
-}
-
-let targetFile = null;
-if (args[0] && !args[0].startsWith('-')) {
-    targetFile = args[0];
-}
-
-const config = {
-    fps: defaultConfig.fps ?? 60,
-    width: defaultConfig.width ?? 1920,
-    height: defaultConfig.height ?? 1080,
-    bitrate: defaultConfig.videoBitrate ?? '20M',
-    maxDuration: defaultConfig.maxDuration ?? 0,
-    wsPort: defaultConfig.wsPort ?? 5001,
-    devServerPort: defaultConfig.devServerPort ?? 5173,
-};
-
-const renderConfigKeys = [
-    'raytraceEnabled', 'rtSamples', 'rtMaxAccumulation', 'bvhMethod', 'gamma',
-    'denoiser', 'oidnModel', 'sample_count', 'AA', 'AA_Function', 'PPLL'
-];
-
-const renderConfigOverrides = {};
-for (const key of renderConfigKeys) {
-    if (defaultConfig[key] !== undefined) {
-        renderConfigOverrides[key] = defaultConfig[key];
-    }
-}
-
-const flagStartIndex = targetFile ? 1 : 0;
-const overrides = [];
-let replayFile = null; 
-let customOutputDir = null;
-
-for (let i = flagStartIndex; i < args.length; i++) {
-    if (args[i] === '-w' || args[i] === '--width') { config.width = parseInt(args[++i]); overrides.push(`width: ${config.width}px`); }
-    else if (args[i] === '-h' || args[i] === '--height') { config.height = parseInt(args[++i]); overrides.push(`height: ${config.height}px`); }
-    else if (args[i] === '-f' || args[i] === '--fps') { config.fps = parseInt(args[++i]); overrides.push(`fps: ${config.fps}`); }
-    else if (args[i] === '-d' || args[i] === '--duration') { config.maxDuration = parseInt(args[++i]); overrides.push(`duration: ${config.maxDuration}ms`); }
-    else if (args[i] === '-o' || args[i] === '--out') {
-        customOutputDir = path.resolve(projectRoot, args[++i]);
-        overrides.push(`out: ${customOutputDir}`);
-    }
-    else if (args[i] === '--raytrace') {
-        const val = args[i + 1];
-        if (val === 'true' || val === 'false') {
-            renderConfigOverrides.raytraceEnabled = (val === 'true');
-            i++;
-        } else {
-            renderConfigOverrides.raytraceEnabled = true;
-        }
-    }
-    else if (args[i] === '--no-raytrace') {
-        renderConfigOverrides.raytraceEnabled = false;
-    }
-    else if (args[i] === '--denoiser') {
-        renderConfigOverrides.denoiser = args[++i];
-    }
-    else if (args[i] === '--raw') {
-        renderConfigOverrides.denoiser = 'native';
-    }
-    else if (args[i] === '--replay') { replayFile = args[++i]; }
-    else if (args[i].endsWith('.json') && !replayFile) { replayFile = args[i]; }
-}
-
-// Native OIDN mode requires denoiser === 'native' AND raytraceEnabled
-const activeDenoiser = renderConfigOverrides.denoiser || defaultConfig.denoiser || 'none';
-const isNativeDenoiser = activeDenoiser === 'native';
-config.useRawFrames = Boolean(isNativeDenoiser && renderConfigOverrides.raytraceEnabled !== false);
-config.exportAlbedoNormal = isNativeDenoiser;
-
-const defaultVideoDir = path.resolve(projectRoot, 'outputs/video');
-const outputDir = customOutputDir || (defaultConfig.outputDir ? path.resolve(projectRoot, defaultConfig.outputDir) : defaultVideoDir);
-const outputFormat = defaultConfig.outputFormat || 'mp4';
-const outputFile = path.join(outputDir, `output_${Date.now()}.${outputFormat}`);
-const tempVideoFile = path.join(outputDir, `.temp_video_${Date.now()}.${outputFormat}`);
-const tempAudioFile = path.join(outputDir, `.temp_audio_${Date.now()}.wav`);
-let hasAudio = false;
-
-if (!fs.existsSync(path.dirname(outputFile))) {
-    fs.mkdirSync(path.dirname(outputFile), { recursive: true });
-}
-
-// --- DIRECTORY SETUP FOR VIRTUAL MEMORY FRAMES ---
-let framesDir = '';
-if (config.useRawFrames) {
-    framesDir = path.join(outputDir, `temp_workspace_${Date.now()}`);
-    if (!fs.existsSync(framesDir)) fs.mkdirSync(framesDir, { recursive: true });
-}
-
-// --- HELPER: Write WebGPU Buffer to Portable Float Map (PFM) for OIDN ---
-function savePFM(filePath, buffer, width, height) {
-    const header = Buffer.from(`PF\n${width} ${height}\n-1.0\n`);
-    const bytesPerPixel = 16; 
-    const unalignedBytesPerRow = width * bytesPerPixel;
-    const bytesPerRow = Math.ceil(unalignedBytesPerRow / 256) * 256;
-    
-    const rgbFloats = new Float32Array(width * height * 3);
-    const dataView = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
-
-    for (let y = 0; y < height; y++) {
-        const flippedY = height - 1 - y; 
-        for (let x = 0; x < width; x++) {
-            const srcByteOffset = (y * bytesPerRow) + (x * bytesPerPixel);
-            const dstFloatOffset = (flippedY * width + x) * 3;
-            
-            rgbFloats[dstFloatOffset] = dataView.getFloat32(srcByteOffset, true);     
-            rgbFloats[dstFloatOffset + 1] = dataView.getFloat32(srcByteOffset + 4, true); 
-            rgbFloats[dstFloatOffset + 2] = dataView.getFloat32(srcByteOffset + 8, true); 
-        }
-    }
-    const out = Buffer.concat([header, Buffer.from(rgbFloats.buffer)]);
-    fs.writeFileSync(filePath, out);
-}
-
-// --- HELPER: ACES Film Tonemapping ---
-function ACESFilm(x) {
-    const a = 2.51, b = 0.03, c = 2.43, d = 0.59, e = 0.14;
-    return Math.max(0, Math.min(1, (x * (a * x + b)) / (x * (c * x + d) + e)));
-}
-
-// --- HELPER: Print Total Time and Exit ---
-function printTotalTime(code) {
-    const totalTimeMs = Date.now() - scriptStartTime;
-    const hours = Math.floor(totalTimeMs / 3600000);
-    const minutes = Math.floor((totalTimeMs % 3600000) / 60000);
-    const seconds = ((totalTimeMs % 60000) / 1000).toFixed(2);
-    
-    let timeTaken = '';
-    if (hours > 0) timeTaken += `${hours}h `;
-    if (minutes > 0 || hours > 0) timeTaken += `${minutes}m `;
-    timeTaken += `${seconds}s`;
-
-    console.log(); // Clear progress bar
-    if (code === 0 || !code) {
-        console.log(`✅ Rendering Complete! Video saved to: ${outputFile}`);
-        console.log(`⏱️  Total time taken: ${timeTaken}\n`);
-    } else {
-        console.log(`❌ Process Failed with code ${code}.`);
-        console.log(`⏱️  Time elapsed before failure: ${timeTaken}\n`);
-    }
-    process.exit(code || 0);
-}
-
-console.log(`\n⚙️  Configurations loaded from: ${configSource}`);
-console.log(`   Resolution:   ${config.width}x${config.height}`);
-console.log(`   Frame Rate:   ${config.fps} fps`);
-if (config.useRawFrames) console.log(`   OIDN Denoiser: Native (Memory-to-Memory Virtual Pipeline)`);
-else console.log(`   Render Mode: Standard Canvas (Direct Video Stream)`);
-
-let replayEvents = null;
-let replayIndex = 0;
-
-if (replayFile) {
-    const fullReplayPath = path.resolve(projectRoot, replayFile);
-    if (fs.existsSync(fullReplayPath)) {
-        replayEvents = JSON.parse(fs.readFileSync(fullReplayPath, 'utf8'));
-    }
-}
-
-console.log(`\n🚀 Starting local servers...`);
-const userViteConfig = path.resolve(projectRoot, 'vite.config.ts');
-const viteServer = await createServer({
-    configFile: fs.existsSync(userViteConfig) ? userViteConfig : undefined,
-    root: projectRoot, // Serve from user project root
-    server: { host: '127.0.0.1', port: config.devServerPort, strictPort: false },
-    logLevel: 'error' // Silence Vite logs to keep the console clean
-});
-await viteServer.listen();
-
-const address = viteServer.httpServer.address();
-const actualPort = (address && typeof address === 'object') ? address.port : config.devServerPort;
-
-// --- STRICT FFMPEG RAW VIDEO DEMUXER FLAGS ---
-const ffmpegArgs = config.useRawFrames 
-    ? [
-        '-y', '-loglevel', 'error', 
-        '-f', 'rawvideo', 
-        '-pixel_format', 'rgb24', 
-        '-video_size', `${config.width}x${config.height}`, 
-        '-framerate', config.fps.toString(), 
-        '-i', '-',
-        '-c:v', 'libx264', '-preset', 'slow', '-crf', '18', '-b:v', config.bitrate,
-        '-pix_fmt', 'yuv420p', tempVideoFile
-    ]
-    : [
-        '-y', '-loglevel', 'error', 
-        '-f', 'image2pipe', '-vcodec', 'mjpeg', '-r', config.fps.toString(),
-        '-i', '-', '-c:v', 'libx264', '-preset', 'slow', '-crf', '18',
-        '-b:v', config.bitrate, '-pix_fmt', 'yuv420p', tempVideoFile
-    ];
-
-const ffmpegProcess = spawn('ffmpeg', ffmpegArgs, { stdio: ['pipe', 'ignore', 'inherit'] });
-ffmpegProcess.on('close', async (code) => {
-    if (code !== 0) {
-        if (fs.existsSync(tempVideoFile)) try { fs.unlinkSync(tempVideoFile); } catch (e) {}
-        if (fs.existsSync(tempAudioFile)) try { fs.unlinkSync(tempAudioFile); } catch (e) {}
-        printTotalTime(code);
-        return;
-    }
-
-    if (hasAudio && fs.existsSync(tempAudioFile) && fs.statSync(tempAudioFile).size > 44) {
-        console.log(`\n🎛️  Muxing audio and video streams...`);
-        const isWebm = (outputFormat === 'webm');
-        const audioCodec = isWebm ? 'libopus' : 'aac';
-        const audioBitrate = isWebm ? '128k' : '192k';
-
-        const muxArgs = [
-            '-y', '-loglevel', 'error',
-            '-i', tempVideoFile,
-            '-i', tempAudioFile,
-            '-c:v', 'copy',
-            '-c:a', audioCodec,
-            '-b:a', audioBitrate,
-            '-shortest',
-            outputFile
-        ];
-
-        const muxResult = spawnSync('ffmpeg', muxArgs, { stdio: 'inherit' });
-        if (muxResult.status === 0) {
-            console.log(`✨ Audio and video successfully muxed.`);
-            try { fs.unlinkSync(tempVideoFile); } catch (e) {}
-            try { fs.unlinkSync(tempAudioFile); } catch (e) {}
-            printTotalTime(0);
-        } else {
-            console.warn(`⚠️ FFmpeg muxing failed with code ${muxResult.status}. Falling back to video without audio.`);
-            try { fs.renameSync(tempVideoFile, outputFile); } catch (e) {}
-            try { fs.unlinkSync(tempAudioFile); } catch (e) {}
-            printTotalTime(0);
-        }
-    } else {
-        if (fs.existsSync(tempVideoFile)) {
-            try { fs.renameSync(tempVideoFile, outputFile); } catch (e) {}
-        }
-        if (fs.existsSync(tempAudioFile)) {
-            try { fs.unlinkSync(tempAudioFile); } catch (e) {}
-        }
-        printTotalTime(code);
-    }
-});
-
-let wss = null;
-let actualWsPort = config.wsPort;
-
-for (let offset = 0; offset < 20; offset++) {
-    const tryPort = config.wsPort + offset;
-    try {
-        wss = await new Promise((resolve, reject) => {
-            const server = new WebSocketServer({ 
-                host: '127.0.0.1',
-                port: tryPort, 
-                maxPayload: 1024 * 1024 * 500 
-            });
-            server.on('listening', () => resolve(server));
-            server.on('error', (err) => reject(err));
-        });
-        actualWsPort = tryPort;
-        break;
-    } catch (err) {
-        if (err.code === 'EADDRINUSE' && offset < 19) {
-            continue;
-        }
-        throw err;
-    }
-}
-const progressBar = new cliProgress.SingleBar({
-    format: 'Rendering | {bar} | {percentage}% | Frame: {value}/{total} | Time: {time}ms',
-    barCompleteChar: '\u2588', barIncompleteChar: '\u2591', hideCursor: true
-}, cliProgress.Presets.shades_classic);
-
-let isProgressStarted = false;
-let expectedTotalFrames = config.maxDuration > 0 ? Math.ceil((config.maxDuration / 1000) * config.fps) : 1000;
-let browser = null;
-let activePage = null;
-
-const shutdown = async () => {
-    progressBar.stop();
-    if (browser) try { await browser.close(); } catch (e) { }
-    if (viteServer) try { await viteServer.close(); } catch (e) { }
-    
-    if (ffmpegProcess) ffmpegProcess.stdin.end();
-    
-    // Clean up virtual workspace directory
-    if (config.useRawFrames && fs.existsSync(framesDir)) {
-        try { fs.rmSync(framesDir, { recursive: true, force: true }); } catch (e) {}
-    }
-    
-    wss.close();
-};
-
-async function replayPuppeteerEvents(time) {
-    if (!replayEvents || !activePage || replayIndex >= replayEvents.length) return;
-    while (replayIndex < replayEvents.length && replayEvents[replayIndex].time <= time) {
-        const event = replayEvents[replayIndex];
-        replayIndex++;
-        const d = event.data;
-        const x = d.clientX !== undefined ? d.clientX * config.width : 0;
-        const y = d.clientY !== undefined ? d.clientY * config.height : 0;
-        try {
-            if (event.type === 'keydown') { if (d.code || d.key) await activePage.keyboard.down(d.code || d.key); }
-            else if (event.type === 'keyup') { if (d.code || d.key) await activePage.keyboard.up(d.code || d.key); }
-            else if (event.type === 'pointerdown' || event.type === 'mousedown') {
-                await activePage.mouse.move(x, y); await activePage.mouse.down({ button: d.button === 0 ? 'left' : (d.button === 1 ? 'middle' : 'right') });
-            }
-            else if (event.type === 'pointerup' || event.type === 'mouseup') {
-                await activePage.mouse.move(x, y); await activePage.mouse.up({ button: d.button === 0 ? 'left' : (d.button === 1 ? 'middle' : 'right') });
-            }
-            else if (event.type === 'pointermove' || event.type === 'mousemove') { await activePage.mouse.move(x, y); }
-        } catch (err) { }
-    }
-}
-
-// --- DYNAMIC OIDN & TONEMAP PIPELINE (Uses Virtual Memory Overwriting & Stream Backpressure) ---
-async function processAndPipeFrame() {
-    const colorFile = path.join(framesDir, `temp_color.pfm`);
-    const albedoFile = path.join(framesDir, `temp_albedo.pfm`);
-    const normalFile = path.join(framesDir, `temp_normal.pfm`);
-    const outFile = path.join(framesDir, `temp_denoised.pfm`);
-
-    // 1. Run Native OIDN
-    const oidnArgs = ['--hdr', colorFile];
-    if (config.exportAlbedoNormal) {
-        oidnArgs.push('--albedo', albedoFile, '--normal', normalFile);
-    }
-    oidnArgs.push('--output', outFile);
-
-    const result = spawnSync('oidnDenoise', oidnArgs, { stdio: 'ignore' });
-    if (result.status !== 0) {
-        console.error(`\n❌ oidnDenoise failed. Ensure the OIDN executable is in your PATH.`);
-        await shutdown();
-        process.exit(1);
-    }
-
-    // 2. Read Denoised Float Map
-    const pfmData = fs.readFileSync(outFile);
-    const headerStr = pfmData.toString('utf8', 0, 50);
-    const match = headerStr.match(/^PF\n(\d+) (\d+)\n-1\.0\n/);
-    if (!match) throw new Error("Invalid PFM header");
-
-    const width = parseInt(match[1]);
-    const height = parseInt(match[2]);
-    const headerBytes = match[0].length;
-
-    const floatBuffer = pfmData.subarray(headerBytes);
-    const alignedBuffer = floatBuffer.buffer.slice(floatBuffer.byteOffset, floatBuffer.byteOffset + floatBuffer.byteLength);
-    const floatView = new Float32Array(alignedBuffer);
-    
-    // 3. Tonemap directly into a raw RGB byte buffer
-    const rgbBuffer = Buffer.allocUnsafe(width * height * 3);
-    
-    for (let j = 0; j < floatView.length; j += 3) {
-        let r = ACESFilm(floatView[j]);
-        let g = ACESFilm(floatView[j+1]);
-        let b = ACESFilm(floatView[j+2]);
-        
-        r = Math.pow(r, 1.0 / 2.2);
-        g = Math.pow(g, 1.0 / 2.2);
-        b = Math.pow(b, 1.0 / 2.2);
-        
-        const pixelIdx = j / 3;
-        const x = pixelIdx % width;
-        const y = Math.floor(pixelIdx / width);
-        const flippedY = height - 1 - y; 
-        
-        const targetIdx = (flippedY * width + x) * 3;
-        rgbBuffer[targetIdx] = Math.max(0, Math.min(255, r * 255));
-        rgbBuffer[targetIdx + 1] = Math.max(0, Math.min(255, g * 255));
-        rgbBuffer[targetIdx + 2] = Math.max(0, Math.min(255, b * 255));
-    }
-    
-    // 4. Send to FFmpeg and WAIT if the pipe is full (Node.js Stream Backpressure)
-    const canWrite = ffmpegProcess.stdin.write(rgbBuffer);
-    if (!canWrite) {
-        await new Promise(resolve => ffmpegProcess.stdin.once('drain', resolve));
-    }
-}
-
-wss.on('connection', (ws) => {
-    let nextIsBinary = false;
-    let nextIsAudioBinary = false;
-    let currentTime = 0;
-    let currentFrameType = 'color';
-    let currentIsFloat = false;
-
-    ws.on('message', async (message) => {
-        if (nextIsAudioBinary) {
-            nextIsAudioBinary = false;
-            try {
-                fs.writeFileSync(tempAudioFile, Buffer.from(message));
-                hasAudio = true;
-                console.log(`\n🎵 Audio track received (${Buffer.byteLength(message)} bytes).`);
-            } catch (err) {
-                console.error(`⚠️ Failed to save offline audio track:`, err);
-            }
-            ws.send("ack");
-            return;
-        }
-
-        if (nextIsBinary) {
-            nextIsBinary = false;
-
-            if (config.useRawFrames && currentIsFloat) {
-                const filePath = path.join(framesDir, `temp_${currentFrameType}.pfm`);
-                savePFM(filePath, message, config.width, config.height);
-
-                let isFrameComplete = false;
-                if (config.exportAlbedoNormal && currentFrameType === 'normal') isFrameComplete = true;
-                if (!config.exportAlbedoNormal && currentFrameType === 'color') isFrameComplete = true;
-
-                if (isFrameComplete) {
-                    await processAndPipeFrame();
-                    
-                    if (!isProgressStarted) {
-                        console.log("🎬 Rendering in progress...");
-                        progressBar.start(expectedTotalFrames, 0);
-                        isProgressStarted = true;
-                    }
-                    progressBar.increment(1, { time: currentTime.toFixed(0) });
-                }
-            } 
-            else if (!config.useRawFrames && currentFrameType === 'color' && !currentIsFloat) {
-                const canWrite = ffmpegProcess.stdin.write(message);
-                if (!canWrite) {
-                    await new Promise(resolve => ffmpegProcess.stdin.once('drain', resolve));
-                }
-                if (!isProgressStarted) {
-                    console.log("🎬 Rendering in progress...");
-                    progressBar.start(expectedTotalFrames, 0);
-                    isProgressStarted = true;
-                }
-                progressBar.increment(1, { time: currentTime.toFixed(0) });
-            }
-
-            ws.send("ack");
-        } else {
-            try {
-                const data = JSON.parse(message.toString());
-                if (data.type === 'request_replay') {
-                    await replayPuppeteerEvents(data.time);
-                    ws.send("replay_done");
-                } else if (data.type === 'frame') {
-                    currentTime = data.time;
-                    currentFrameType = data.frameType || 'color';
-                    currentIsFloat = data.isFloat || false;
-                    nextIsBinary = true;
-                } else if (data.type === 'audio') {
-                    nextIsAudioBinary = true;
-                } else if (data.type === 'finish') {
-                    await shutdown();
-                }
-            } catch (err) { }
-        }
-    });
-});
-
-process.on('SIGINT', async () => {
-    await shutdown();
-    if (fs.existsSync(tempVideoFile)) try { fs.unlinkSync(tempVideoFile); } catch (e) {}
-    if (fs.existsSync(tempAudioFile)) try { fs.unlinkSync(tempAudioFile); } catch (e) {}
-    process.exit(1);
-});
-
-(async () => {
-    console.log(`🌐 Launching Headless Chrome...`);
-    browser = await puppeteer.launch({ 
-        headless: "new", 
-        args: [
-            '--enable-unsafe-webgpu', 
-            '--disable-web-security', 
-            '--no-sandbox',
-            '--enable-experimental-web-platform-features',
-            '--autoplay-policy=no-user-gesture-required',
-            '--disable-background-networking'
-        ], 
-        channel: 'chrome' 
-    });
-    activePage = await browser.newPage();
-    activePage.on('console', async msg => {
-        let text = msg.text();
-        try {
-            const args = await Promise.all(msg.args().map(async a => {
-                try {
-                    return await a.evaluate(val => {
-                        if (val instanceof Error) return `${val.name}: ${val.message}\n${val.stack}`;
-                        if (typeof val === 'object') {
-                            try { return JSON.stringify(val); } catch { return String(val); }
-                        }
-                        return String(val);
-                    });
-                } catch {
-                    return a.toString();
-                }
-            }));
-            if (args.length > 0) text = args.join(' ');
-        } catch {}
-        if (text.includes('ERR_NETWORK_CHANGED') || text.includes('favicon.ico')) return;
-        console.log(`🌐 [Browser Console] [${msg.type()}] ${text}`);
-    });
-    activePage.on('pageerror', err => {
-        console.error(`🌐 [Browser Error]`, err);
-    });
-    activePage.on('response', res => {
-        if (res.status() >= 400 && !res.url().includes('favicon.ico')) {
-            console.log(`🌐 [HTTP ${res.status()}] ${res.url()}`);
-        }
-    });
-    await activePage.setViewport({ width: config.width, height: config.height, deviceScaleFactor: 1.0 });
-
-    let url = `http://127.0.0.1:${actualPort}?offline=true&width=${config.width}&height=${config.height}&fps=${config.fps}&maxDuration=${config.maxDuration}&wsUrl=ws://127.0.0.1:${actualWsPort}`;
-    if (targetFile) url += `&file=${targetFile}`;
-    if (Object.keys(renderConfigOverrides).length > 0) url += `&renderConfig=${encodeURIComponent(JSON.stringify(renderConfigOverrides))}`;
-
-    let retries = 3;
-    while (retries > 0) {
-        try {
-            await activePage.goto(url, { waitUntil: 'domcontentloaded' });
-            break;
-        } catch (e) {
-            retries--;
-            if (retries === 0) {
-                console.error(`\n❌ Failed to connect to local server:`, e.message || e);
-                await shutdown();
-                process.exit(1);
-            }
-            await new Promise(r => setTimeout(r, 800));
-        }
-    }
-})();
+#!/usr/bin/env node
+
+// =========================================================================
+// File: bin/render.js
+// =========================================================================
+
+import { spawn, spawnSync } from 'child_process';
+import { WebSocketServer } from 'ws';
+import puppeteer from 'puppeteer';
+import cliProgress from 'cli-progress';
+import fs from 'fs';
+import path from 'path';
+import { createServer } from 'vite';
+import { loadRenderConfig, resolveRenderOptions } from './render-config.js';
+
+const scriptStartTime = Date.now();
+const projectRoot = process.cwd(); // Target the user's current working directory
+
+const { defaultConfig, configSource } = await loadRenderConfig(projectRoot);
+
+const args = process.argv.slice(2);
+
+// Check for --help before parsing options
+const isHelp = args.includes('--help') || args.some((arg, idx) => arg === '-h' && (idx + 1 >= args.length || isNaN(parseInt(args[idx + 1], 10))));
+if (isHelp) {
+    console.log(`
+🎬 Retiam WebGPU Engine - Video Renderer
+
+Usage:
+  npx retiam render [file] [options]
+  npx retiam [file] [options]
+
+Arguments:
+  [file]                    Target scene TypeScript file (e.g. src/scenes/AStarScene.ts)
+                            If omitted, renders the default scene defined in src/main.ts.
+
+Options:
+  -w, --width <px>          Output video width in pixels (default: 1920)
+  -h, --height <px>         Output video height in pixels (default: 1080)
+  -f, --fps <num>           Render frame rate (default: 60)
+  -d, --duration <ms>       Maximum rendering duration limit in milliseconds
+  -o, --out <dir>           Output directory for rendered video (default: ./outputs/video)
+  --raytrace [true|false]   Enable or disable hardware raytracing
+  --no-raytrace             Explicitly disable raytracing
+  --denoiser <format>       Denoiser pipeline ('none', 'spatial', 'oidn', 'native')
+  --raw                     Use native raw HDR frame buffer export
+  --replay <file.json>      Replay recorded interactions JSON during rendering
+  --help                    Show this help message and exit
+
+Examples:
+  npx retiam render src/scenes/AStarScene.ts
+  npx retiam render MyScene.ts -w 1920 -h 1080 -f 60
+  npx retiam render MyScene.ts -o ./outputs/video -d 15000
+
+Configuration:
+  Reads config.js in the project root (retiam.config.js takes priority).
+  Command-line flags override file settings. Duration is in milliseconds.
+`);
+    process.exit(0);
+}
+
+const { config, renderConfigOverrides, targetFile, replayFile, outputDir, outputFormat } =
+    resolveRenderOptions(defaultConfig, args, projectRoot);
+const outputFile = path.join(outputDir, `output_${Date.now()}.${outputFormat}`);
+const tempVideoFile = path.join(outputDir, `.temp_video_${Date.now()}.${outputFormat}`);
+const tempAudioFile = path.join(outputDir, `.temp_audio_${Date.now()}.wav`);
+let hasAudio = false;
+
+if (!fs.existsSync(path.dirname(outputFile))) {
+    fs.mkdirSync(path.dirname(outputFile), { recursive: true });
+}
+
+// --- DIRECTORY SETUP FOR VIRTUAL MEMORY FRAMES ---
+let framesDir = '';
+if (config.useRawFrames) {
+    framesDir = path.join(outputDir, `temp_workspace_${Date.now()}`);
+    if (!fs.existsSync(framesDir)) fs.mkdirSync(framesDir, { recursive: true });
+}
+
+// --- HELPER: Write WebGPU Buffer to Portable Float Map (PFM) for OIDN ---
+function savePFM(filePath, buffer, width, height) {
+    const header = Buffer.from(`PF\n${width} ${height}\n-1.0\n`);
+    const bytesPerPixel = 16; 
+    const unalignedBytesPerRow = width * bytesPerPixel;
+    const bytesPerRow = Math.ceil(unalignedBytesPerRow / 256) * 256;
+    
+    const rgbFloats = new Float32Array(width * height * 3);
+    const dataView = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+
+    for (let y = 0; y < height; y++) {
+        const flippedY = height - 1 - y; 
+        for (let x = 0; x < width; x++) {
+            const srcByteOffset = (y * bytesPerRow) + (x * bytesPerPixel);
+            const dstFloatOffset = (flippedY * width + x) * 3;
+            
+            rgbFloats[dstFloatOffset] = dataView.getFloat32(srcByteOffset, true);     
+            rgbFloats[dstFloatOffset + 1] = dataView.getFloat32(srcByteOffset + 4, true); 
+            rgbFloats[dstFloatOffset + 2] = dataView.getFloat32(srcByteOffset + 8, true); 
+        }
+    }
+    const out = Buffer.concat([header, Buffer.from(rgbFloats.buffer)]);
+    fs.writeFileSync(filePath, out);
+}
+
+// --- HELPER: ACES Film Tonemapping ---
+function ACESFilm(x) {
+    const a = 2.51, b = 0.03, c = 2.43, d = 0.59, e = 0.14;
+    return Math.max(0, Math.min(1, (x * (a * x + b)) / (x * (c * x + d) + e)));
+}
+
+// --- HELPER: Print Total Time and Exit ---
+function printTotalTime(code) {
+    const totalTimeMs = Date.now() - scriptStartTime;
+    const hours = Math.floor(totalTimeMs / 3600000);
+    const minutes = Math.floor((totalTimeMs % 3600000) / 60000);
+    const seconds = ((totalTimeMs % 60000) / 1000).toFixed(2);
+    
+    let timeTaken = '';
+    if (hours > 0) timeTaken += `${hours}h `;
+    if (minutes > 0 || hours > 0) timeTaken += `${minutes}m `;
+    timeTaken += `${seconds}s`;
+
+    console.log(); // Clear progress bar
+    if (code === 0 || !code) {
+        console.log(`✅ Rendering Complete! Video saved to: ${outputFile}`);
+        console.log(`⏱️  Total time taken: ${timeTaken}\n`);
+    } else {
+        console.log(`❌ Process Failed with code ${code}.`);
+        console.log(`⏱️  Time elapsed before failure: ${timeTaken}\n`);
+    }
+    process.exit(code || 0);
+}
+
+console.log(`\n⚙️  Configurations loaded from: ${configSource}`);
+console.log(`   Resolution:   ${config.width}x${config.height}`);
+console.log(`   Frame Rate:   ${config.fps} fps`);
+if (config.useRawFrames) console.log(`   OIDN Denoiser: Native (Memory-to-Memory Virtual Pipeline)`);
+else console.log(`   Render Mode: Standard Canvas (Direct Video Stream)`);
+
+let replayEvents = null;
+let replayIndex = 0;
+
+if (replayFile) {
+    const fullReplayPath = path.resolve(projectRoot, replayFile);
+    if (fs.existsSync(fullReplayPath)) {
+        replayEvents = JSON.parse(fs.readFileSync(fullReplayPath, 'utf8'));
+    }
+}
+
+console.log(`\n🚀 Starting local servers...`);
+const userViteConfig = path.resolve(projectRoot, 'vite.config.ts');
+const viteServer = await createServer({
+    configFile: fs.existsSync(userViteConfig) ? userViteConfig : undefined,
+    root: projectRoot, // Serve from user project root
+    server: { host: '127.0.0.1', port: config.devServerPort, strictPort: false, open: false },
+    logLevel: 'error' // Silence Vite logs to keep the console clean
+});
+await viteServer.listen();
+
+const address = viteServer.httpServer.address();
+const actualPort = (address && typeof address === 'object') ? address.port : config.devServerPort;
+
+// --- STRICT FFMPEG RAW VIDEO DEMUXER FLAGS ---
+const ffmpegArgs = config.useRawFrames 
+    ? [
+        '-y', '-loglevel', 'error', 
+        '-f', 'rawvideo', 
+        '-pixel_format', 'rgb24', 
+        '-video_size', `${config.width}x${config.height}`, 
+        '-framerate', config.fps.toString(), 
+        '-i', '-',
+        '-c:v', 'libx264', '-preset', 'slow', '-crf', '18', '-b:v', config.bitrate,
+        '-pix_fmt', 'yuv420p', tempVideoFile
+    ]
+    : [
+        '-y', '-loglevel', 'error', 
+        '-f', 'image2pipe', '-vcodec', 'mjpeg', '-r', config.fps.toString(),
+        '-i', '-', '-c:v', 'libx264', '-preset', 'slow', '-crf', '18',
+        '-b:v', config.bitrate, '-pix_fmt', 'yuv420p', tempVideoFile
+    ];
+
+const ffmpegProcess = spawn('ffmpeg', ffmpegArgs, { stdio: ['pipe', 'ignore', 'inherit'] });
+ffmpegProcess.on('close', async (code) => {
+    if (code !== 0) {
+        if (fs.existsSync(tempVideoFile)) try { fs.unlinkSync(tempVideoFile); } catch (e) {}
+        if (fs.existsSync(tempAudioFile)) try { fs.unlinkSync(tempAudioFile); } catch (e) {}
+        printTotalTime(code);
+        return;
+    }
+
+    if (hasAudio && fs.existsSync(tempAudioFile) && fs.statSync(tempAudioFile).size > 44) {
+        console.log(`\n🎛️  Muxing audio and video streams...`);
+        const isWebm = (outputFormat === 'webm');
+        const audioCodec = isWebm ? 'libopus' : 'aac';
+        const audioBitrate = isWebm ? '128k' : '192k';
+
+        const muxArgs = [
+            '-y', '-loglevel', 'error',
+            '-i', tempVideoFile,
+            '-i', tempAudioFile,
+            '-c:v', 'copy',
+            '-c:a', audioCodec,
+            '-b:a', audioBitrate,
+            '-shortest',
+            outputFile
+        ];
+
+        const muxResult = spawnSync('ffmpeg', muxArgs, { stdio: 'inherit' });
+        if (muxResult.status === 0) {
+            console.log(`✨ Audio and video successfully muxed.`);
+            try { fs.unlinkSync(tempVideoFile); } catch (e) {}
+            try { fs.unlinkSync(tempAudioFile); } catch (e) {}
+            printTotalTime(0);
+        } else {
+            console.warn(`⚠️ FFmpeg muxing failed with code ${muxResult.status}. Falling back to video without audio.`);
+            try { fs.renameSync(tempVideoFile, outputFile); } catch (e) {}
+            try { fs.unlinkSync(tempAudioFile); } catch (e) {}
+            printTotalTime(0);
+        }
+    } else {
+        if (fs.existsSync(tempVideoFile)) {
+            try { fs.renameSync(tempVideoFile, outputFile); } catch (e) {}
+        }
+        if (fs.existsSync(tempAudioFile)) {
+            try { fs.unlinkSync(tempAudioFile); } catch (e) {}
+        }
+        printTotalTime(code);
+    }
+});
+
+let wss = null;
+let actualWsPort = config.wsPort;
+
+for (let offset = 0; offset < 20; offset++) {
+    const tryPort = config.wsPort + offset;
+    try {
+        wss = await new Promise((resolve, reject) => {
+            const server = new WebSocketServer({ 
+                host: '127.0.0.1',
+                port: tryPort, 
+                maxPayload: 1024 * 1024 * 500 
+            });
+            server.on('listening', () => resolve(server));
+            server.on('error', (err) => reject(err));
+        });
+        actualWsPort = tryPort;
+        break;
+    } catch (err) {
+        if (err.code === 'EADDRINUSE' && offset < 19) {
+            continue;
+        }
+        throw err;
+    }
+}
+const progressBar = new cliProgress.SingleBar({
+    format: 'Rendering | {bar} | {percentage}% | Frame: {value}/{total} | Time: {time}ms',
+    barCompleteChar: '\u2588', barIncompleteChar: '\u2591', hideCursor: true
+}, cliProgress.Presets.shades_classic);
+
+let isProgressStarted = false;
+let expectedTotalFrames = config.maxDuration > 0 ? Math.ceil((config.maxDuration / 1000) * config.fps) : 1000;
+let browser = null;
+let activePage = null;
+
+const shutdown = async () => {
+    progressBar.stop();
+    if (browser) try { await browser.close(); } catch (e) { }
+    if (viteServer) try { await viteServer.close(); } catch (e) { }
+    
+    if (ffmpegProcess) ffmpegProcess.stdin.end();
+    
+    // Clean up virtual workspace directory
+    if (config.useRawFrames && fs.existsSync(framesDir)) {
+        try { fs.rmSync(framesDir, { recursive: true, force: true }); } catch (e) {}
+    }
+    
+    wss.close();
+};
+
+async function replayPuppeteerEvents(time) {
+    if (!replayEvents || !activePage || replayIndex >= replayEvents.length) return;
+    while (replayIndex < replayEvents.length && replayEvents[replayIndex].time <= time) {
+        const event = replayEvents[replayIndex];
+        replayIndex++;
+        const d = event.data;
+        const x = d.clientX !== undefined ? d.clientX * config.width : 0;
+        const y = d.clientY !== undefined ? d.clientY * config.height : 0;
+        try {
+            if (event.type === 'keydown') { if (d.code || d.key) await activePage.keyboard.down(d.code || d.key); }
+            else if (event.type === 'keyup') { if (d.code || d.key) await activePage.keyboard.up(d.code || d.key); }
+            else if (event.type === 'pointerdown' || event.type === 'mousedown') {
+                await activePage.mouse.move(x, y); await activePage.mouse.down({ button: d.button === 0 ? 'left' : (d.button === 1 ? 'middle' : 'right') });
+            }
+            else if (event.type === 'pointerup' || event.type === 'mouseup') {
+                await activePage.mouse.move(x, y); await activePage.mouse.up({ button: d.button === 0 ? 'left' : (d.button === 1 ? 'middle' : 'right') });
+            }
+            else if (event.type === 'pointermove' || event.type === 'mousemove') { await activePage.mouse.move(x, y); }
+        } catch (err) { }
+    }
+}
+
+// --- DYNAMIC OIDN & TONEMAP PIPELINE (Uses Virtual Memory Overwriting & Stream Backpressure) ---
+async function processAndPipeFrame() {
+    const colorFile = path.join(framesDir, `temp_color.pfm`);
+    const albedoFile = path.join(framesDir, `temp_albedo.pfm`);
+    const normalFile = path.join(framesDir, `temp_normal.pfm`);
+    const outFile = path.join(framesDir, `temp_denoised.pfm`);
+
+    // 1. Run Native OIDN
+    const oidnArgs = ['--hdr', colorFile];
+    if (config.exportAlbedoNormal) {
+        oidnArgs.push('--albedo', albedoFile, '--normal', normalFile);
+    }
+    oidnArgs.push('--output', outFile);
+
+    const result = spawnSync('oidnDenoise', oidnArgs, { stdio: 'ignore' });
+    if (result.status !== 0) {
+        console.error(`\n❌ oidnDenoise failed. Ensure the OIDN executable is in your PATH.`);
+        await shutdown();
+        process.exit(1);
+    }
+
+    // 2. Read Denoised Float Map
+    const pfmData = fs.readFileSync(outFile);
+    const headerStr = pfmData.toString('utf8', 0, 50);
+    const match = headerStr.match(/^PF\n(\d+) (\d+)\n-1\.0\n/);
+    if (!match) throw new Error("Invalid PFM header");
+
+    const width = parseInt(match[1]);
+    const height = parseInt(match[2]);
+    const headerBytes = match[0].length;
+
+    const floatBuffer = pfmData.subarray(headerBytes);
+    const alignedBuffer = floatBuffer.buffer.slice(floatBuffer.byteOffset, floatBuffer.byteOffset + floatBuffer.byteLength);
+    const floatView = new Float32Array(alignedBuffer);
+    
+    // 3. Tonemap directly into a raw RGB byte buffer
+    const rgbBuffer = Buffer.allocUnsafe(width * height * 3);
+    
+    for (let j = 0; j < floatView.length; j += 3) {
+        let r = ACESFilm(floatView[j]);
+        let g = ACESFilm(floatView[j+1]);
+        let b = ACESFilm(floatView[j+2]);
+        
+        r = Math.pow(r, 1.0 / 2.2);
+        g = Math.pow(g, 1.0 / 2.2);
+        b = Math.pow(b, 1.0 / 2.2);
+        
+        const pixelIdx = j / 3;
+        const x = pixelIdx % width;
+        const y = Math.floor(pixelIdx / width);
+        const flippedY = height - 1 - y; 
+        
+        const targetIdx = (flippedY * width + x) * 3;
+        rgbBuffer[targetIdx] = Math.max(0, Math.min(255, r * 255));
+        rgbBuffer[targetIdx + 1] = Math.max(0, Math.min(255, g * 255));
+        rgbBuffer[targetIdx + 2] = Math.max(0, Math.min(255, b * 255));
+    }
+    
+    // 4. Send to FFmpeg and WAIT if the pipe is full (Node.js Stream Backpressure)
+    const canWrite = ffmpegProcess.stdin.write(rgbBuffer);
+    if (!canWrite) {
+        await new Promise(resolve => ffmpegProcess.stdin.once('drain', resolve));
+    }
+}
+
+wss.on('connection', (ws) => {
+    let nextIsBinary = false;
+    let nextIsAudioBinary = false;
+    let currentTime = 0;
+    let currentFrameType = 'color';
+    let currentIsFloat = false;
+
+    ws.on('message', async (message) => {
+        if (nextIsAudioBinary) {
+            nextIsAudioBinary = false;
+            try {
+                fs.writeFileSync(tempAudioFile, Buffer.from(message));
+                hasAudio = true;
+                console.log(`\n🎵 Audio track received (${Buffer.byteLength(message)} bytes).`);
+            } catch (err) {
+                console.error(`⚠️ Failed to save offline audio track:`, err);
+            }
+            ws.send("ack");
+            return;
+        }
+
+        if (nextIsBinary) {
+            nextIsBinary = false;
+
+            if (config.useRawFrames && currentIsFloat) {
+                const filePath = path.join(framesDir, `temp_${currentFrameType}.pfm`);
+                savePFM(filePath, message, config.width, config.height);
+
+                let isFrameComplete = false;
+                if (config.exportAlbedoNormal && currentFrameType === 'normal') isFrameComplete = true;
+                if (!config.exportAlbedoNormal && currentFrameType === 'color') isFrameComplete = true;
+
+                if (isFrameComplete) {
+                    await processAndPipeFrame();
+                    
+                    if (!isProgressStarted) {
+                        console.log("🎬 Rendering in progress...");
+                        progressBar.start(expectedTotalFrames, 0);
+                        isProgressStarted = true;
+                    }
+                    progressBar.increment(1, { time: currentTime.toFixed(0) });
+                }
+            } 
+            else if (!config.useRawFrames && currentFrameType === 'color' && !currentIsFloat) {
+                const canWrite = ffmpegProcess.stdin.write(message);
+                if (!canWrite) {
+                    await new Promise(resolve => ffmpegProcess.stdin.once('drain', resolve));
+                }
+                if (!isProgressStarted) {
+                    console.log("🎬 Rendering in progress...");
+                    progressBar.start(expectedTotalFrames, 0);
+                    isProgressStarted = true;
+                }
+                progressBar.increment(1, { time: currentTime.toFixed(0) });
+            }
+
+            ws.send("ack");
+        } else {
+            try {
+                const data = JSON.parse(message.toString());
+                if (data.type === 'request_replay') {
+                    await replayPuppeteerEvents(data.time);
+                    ws.send("replay_done");
+                } else if (data.type === 'frame') {
+                    currentTime = data.time;
+                    currentFrameType = data.frameType || 'color';
+                    currentIsFloat = data.isFloat || false;
+                    nextIsBinary = true;
+                } else if (data.type === 'audio') {
+                    nextIsAudioBinary = true;
+                } else if (data.type === 'finish') {
+                    await shutdown();
+                }
+            } catch (err) { }
+        }
+    });
+});
+
+process.on('SIGINT', async () => {
+    await shutdown();
+    if (fs.existsSync(tempVideoFile)) try { fs.unlinkSync(tempVideoFile); } catch (e) {}
+    if (fs.existsSync(tempAudioFile)) try { fs.unlinkSync(tempAudioFile); } catch (e) {}
+    process.exit(1);
+});
+
+(async () => {
+    console.log(`🌐 Launching Headless Chrome...`);
+    browser = await puppeteer.launch({ 
+        headless: "new", 
+        args: [
+            '--enable-unsafe-webgpu', 
+            '--disable-web-security', 
+            '--no-sandbox',
+            '--enable-experimental-web-platform-features',
+            '--autoplay-policy=no-user-gesture-required',
+            '--disable-background-networking'
+        ], 
+        channel: 'chrome' 
+    });
+    activePage = await browser.newPage();
+    activePage.on('console', async msg => {
+        let text = msg.text();
+        try {
+            const args = await Promise.all(msg.args().map(async a => {
+                try {
+                    return await a.evaluate(val => {
+                        if (val instanceof Error) return `${val.name}: ${val.message}\n${val.stack}`;
+                        if (typeof val === 'object') {
+                            try { return JSON.stringify(val); } catch { return String(val); }
+                        }
+                        return String(val);
+                    });
+                } catch {
+                    return a.toString();
+                }
+            }));
+            if (args.length > 0) text = args.join(' ');
+        } catch {}
+        if (text.includes('ERR_NETWORK_CHANGED') || text.includes('favicon.ico')) return;
+        console.log(`🌐 [Browser Console] [${msg.type()}] ${text}`);
+    });
+    activePage.on('pageerror', err => {
+        console.error(`🌐 [Browser Error]`, err);
+    });
+    activePage.on('response', res => {
+        if (res.status() >= 400 && !res.url().includes('favicon.ico')) {
+            console.log(`🌐 [HTTP ${res.status()}] ${res.url()}`);
+        }
+    });
+    await activePage.setViewport({ width: config.width, height: config.height, deviceScaleFactor: 1.0 });
+
+    let url = `http://127.0.0.1:${actualPort}?offline=true&width=${config.width}&height=${config.height}&fps=${config.fps}&maxDuration=${config.maxDuration}&wsUrl=ws://127.0.0.1:${actualWsPort}`;
+    if (targetFile) url += `&file=${encodeURIComponent(targetFile)}`;
+    if (Object.keys(renderConfigOverrides).length > 0) url += `&renderConfig=${encodeURIComponent(JSON.stringify(renderConfigOverrides))}`;
+
+    let retries = 3;
+    while (retries > 0) {
+        try {
+            await activePage.goto(url, { waitUntil: 'domcontentloaded' });
+            break;
+        } catch (e) {
+            retries--;
+            if (retries === 0) {
+                console.error(`\n❌ Failed to connect to local server:`, e.message || e);
+                await shutdown();
+                process.exit(1);
+            }
+            await new Promise(r => setTimeout(r, 800));
+        }
+    }
+})();