retiam 0.0.0-stage → 1.0.0

package/bin/cli.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+// =========================================================================
+// File: bin/cli.js - Retiam Unified CLI Entrypoint
+// =========================================================================
+
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const renderScript = path.join(__dirname, 'render.js');
+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');
+
+function runScript(scriptPath, scriptArgs) {
+    if (scriptPath === renderScript || scriptPath === snapshotScript) {
+        try {
+            createRequire(import.meta.url).resolve('puppeteer');
+        } catch {
+            console.error('Retiam render and snapshot require the optional Puppeteer dependency. Install it in your project with: npm install --save-dev puppeteer');
+            process.exit(1);
+        }
+    }
+    const child = spawn(process.execPath, [scriptPath, ...scriptArgs], { stdio: 'inherit' });
+    child.on('error', (error) => {
+        console.error(`Unable to start Retiam command: ${error.message}`);
+        process.exit(1);
+    });
+    child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+}
+
+function printRootHelp() {
+    console.log(`
+🎬 Retiam WebGPU Engine CLI (Agent-Native Edition)
+
+Usage:
+  npx retiam <command> [file] [options]
+  npx retiam [file] [options]               (shortcut for render)
+  npx retiam help <command>                 (detailed help for a single command)
+
+Commands Overview:
+  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
+  render           Render high-fidelity video (MP4/WebM) via WebGPU & FFmpeg
+  export           Bundle scene into an embeddable <retiam-scene> Web Component
+
+================================================================================
+1. RENDER (npx retiam render [file] [options])
+   Render a scene into an MP4/WebM video via headless Chrome and FFmpeg.
+
+   Arguments:
+     [file]                    Target scene TypeScript file (default: src/main.ts)
+
+   Options:
+     -w, --width <px>          Output video width (default: 1920)
+     -h, --height <px>         Output video height (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 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 render-specific help
+
+   Examples:
+     npx retiam render src/scenes/AStarScene.ts
+     npx retiam render MyScene.ts -w 1920 -h 1080 -f 60
+     npx retiam render MyScene.ts -d 15000 --raytrace false
+
+================================================================================
+2. SNAPSHOT (npx retiam snapshot <file> [options])
+   Capture visual PNG keyframe snapshots at specific timeline seconds.
+
+   Arguments:
+     <file>                    Target scene TypeScript file (e.g. MyScene.ts)
+
+   Options:
+     --times <sec,sec,...>     Comma-separated timeline seconds (default: 1.0, 2.5)
+     -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)
+     --json                    Output structured JSON for agents & CI automation
+     --help                    Show snapshot-specific help
+
+   Examples:
+     npx retiam snapshot MyScene.ts
+     npx retiam snapshot MyScene.ts --times 1.0,3.5,7.0 -w 1920 -h 1080
+     npx retiam snapshot MyScene.ts --times 5.0 --out ./outputs/snapshot --json
+
+================================================================================
+3. INIT / CREATE (npx retiam init [directory] [options])
+   Initialize a complete, ready-to-run Retiam WebGPU animation project skeleton.
+
+   Arguments:
+     [directory]               Destination directory (default: ./retiam-animation)
+
+   Options:
+     -n, --name <name>         Project name for package.json (default: directory name)
+     --title <text>            Hero text for starter Hello World scene (default: Hello World)
+     --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
+     --install                 Automatically install dependencies after initialization
+     --git                     Initialize a Git repository (git init)
+     --json                    Output structured JSON for agents & CI automation
+     --help, -h                Show init-specific help
+
+   Examples:
+     npx retiam init
+     npx retiam init my-animation
+     npx retiam create quantum-viz --title "Quantum Mechanics" --pm pnpm
+     npx retiam init intro-scene -y --install
+
+================================================================================
+4. LINT (npx retiam lint <file> [options])
+   Static analyzer and AST validator detecting common animation bugs and timing hazards.
+
+   Arguments:
+     <file>                    Target scene file to analyze (e.g. MyScene.ts)
+
+   Options:
+     --json                    Output machine-readable JSON with line numbers & suggested fixes
+     --help, -h                Show lint-specific help
+
+   Checks Performed:
+     - Validates Scene class structure and async run() contract
+     - Detects un-awaited this.play() or this.wait() timing races
+     - Warns about dangling entities not attached to scene graph
+     - Catches Three.js / Python Manim hallucinations
+     - Flags extreme world coordinates exceeding standard camera frustum
+
+   Examples:
+     npx retiam lint MyScene.ts
+     npx retiam lint MyScene.ts --json
+
+================================================================================
+5. EXPORT (npx retiam export [file] [outDir] [options])
+   Compile the scene into a standalone, zero-dependency <retiam-scene> Web Component.
+
+   Arguments:
+     [file]                    Source scene file to bundle (default: src/main.ts)
+     [outDir]                  Target distribution folder (default: outputs/embed)
+
+   Options:
+     -o, --out <dir>           Target distribution folder (default: outputs/embed)
+     --help, -h                Show export-specific help
+
+   Examples:
+     npx retiam export MyScene.ts
+     npx retiam export MyScene.ts ./outputs/embed
+`);
+}
+
+if (command === 'lint') {
+    // Usage: npx retiam lint src/MyScene.ts [--json]
+    runScript(lintScript, args.slice(1));
+}
+else if (command === 'snapshot') {
+    // Usage: npx retiam snapshot src/MyScene.ts [--times 1.0,2.5] [--out ./outputs/snapshot] [--json]
+    runScript(snapshotScript, args.slice(1));
+}
+else if (command === 'init' || command === 'create' || command === 'scaffold') {
+    // Usage: npx retiam init [directory] [options]
+    runScript(initScript, args.slice(1));
+}
+else if (command === 'export') {
+    // Usage: npx retiam export src/main.ts
+    runScript(exportScript, args.slice(1));
+} 
+else if (command === 'render') {
+    // Usage: npx retiam render src/main.ts
+    runScript(renderScript, args.slice(1));
+} 
+else if (command === 'help') {
+    const sub = args[1];
+    if (sub === 'lint') {
+        runScript(lintScript, ['--help']);
+    } else if (sub === 'snapshot') {
+        runScript(snapshotScript, ['--help']);
+    } else if (sub === 'init' || sub === 'create' || sub === 'scaffold') {
+        runScript(initScript, ['--help']);
+    } else if (sub === 'export') {
+        runScript(exportScript, ['--help']);
+    } else if (sub === 'render') {
+        runScript(renderScript, ['--help']);
+    } else {
+        printRootHelp();
+    }
+} 
+else if (command === '-h' || command === '--help' || !command) {
+    printRootHelp();
+} 
+else {
+    // Fallback: Default to rendering if a file path or flag is passed directly
+    // Usage: npx retiam src/main.ts
+    runScript(renderScript, args);
+}

package/bin/export.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+
+// tools/builder/build-embed.js
+import { build } from 'vite';
+import path from 'path';
+import fs from 'fs';
+
+const rootDir = process.cwd();
+
+const args = process.argv.slice(2);
+const isHelp = args.includes('--help') || args.includes('-h') || args.includes('help');
+if (isHelp) {
+    console.log(`
+📦 Retiam WebGPU Engine - Web Embed Bundle Exporter
+
+Usage:
+  npx retiam export [file] [outputDir] [options]
+
+Arguments:
+  [file]                    Source scene file to bundle (default: src/main.ts)
+  [outputDir]               Target distribution folder (default: outputs/embed)
+
+Options:
+  -o, --out <dir>           Target distribution folder (default: outputs/embed)
+  --help, -h                Show this help message and exit
+
+Description:
+  Compiles the scene and Retiam engine into a self-contained, standalone
+  JavaScript web component (<retiam-scene>) for embedding into web pages,
+  blogs, and documentation with zero external dependencies.
+
+Examples:
+  npx retiam export src/scenes/AStarScene.ts
+  npx retiam export src/scenes/AStarScene.ts ./outputs/embed
+  npx retiam export src/scenes/AStarScene.ts -o ./public/embeds
+`);
+    process.exit(0);
+}
+
+let targetOutDir = 'outputs/embed';
+let inputPath = null;
+
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-o' || args[i] === '--out') {
+        targetOutDir = args[++i];
+    } else if (!args[i].startsWith('-')) {
+        if (!inputPath) {
+            inputPath = args[i];
+        } else {
+            targetOutDir = args[i];
+        }
+    }
+}
+
+inputPath = inputPath || 'src/main.ts';
+const fullInputPath = path.resolve(rootDir, inputPath);
+
+if (!fs.existsSync(fullInputPath)) {
+    console.error(`❌ Error: Scene file not found at "${inputPath}"`);
+    console.log('Run "npx retiam export --help" for more details.');
+    process.exit(1);
+}
+
+const sceneName = path.basename(inputPath, path.extname(inputPath)).toLowerCase();
+const outputFile = `${sceneName}.js`;
+
+const tempEntryPath = path.resolve(rootDir, 'src/_temp_embed_entry.ts');
+let rel = path.relative(path.dirname(tempEntryPath), fullInputPath).replace(/\\/g, '/');
+if (!rel.startsWith('.')) rel = './' + rel;
+const relativeScenePath = rel;
+
+const entryCode = `
+import { Scene } from "./engine/_core/Scene";
+import * as SceneModule from "${relativeScenePath}";
+
+export class RetiamElement extends HTMLElement {
+    private canvas;
+    public sceneInstance;
+    private resizeObserver;
+
+    async connectedCallback() {
+        if (!navigator.gpu) {
+            this.innerHTML = '<div style="color:red;padding:20px;">WebGPU not supported</div>';
+            return;
+        }
+
+        // Base styles if not specified
+        if (!this.style.display) this.style.display = "block";
+        if (!this.style.position) this.style.position = "relative";
+
+        this.canvas = document.createElement("canvas");
+        this.canvas.style.display = "block";
+        this.canvas.style.width = "100%";
+        this.canvas.style.height = "100%";
+        this.appendChild(this.canvas);
+
+        const updateCanvasSize = () => {
+            if (!this.canvas) return;
+            const rect = this.getBoundingClientRect();
+            const dpr = window.devicePixelRatio || 1;
+            const w = Math.floor((rect.width || 800) * dpr);
+            const h = Math.floor((rect.height || 450) * dpr);
+            if (w > 0 && h > 0 && (this.canvas.width !== w || this.canvas.height !== h)) {
+                this.canvas.width = w;
+                this.canvas.height = h;
+            }
+        };
+
+        updateCanvasSize();
+
+        this.resizeObserver = new ResizeObserver(() => {
+            updateCanvasSize();
+        });
+        this.resizeObserver.observe(this);
+
+        try {
+            // 1. Search exports for an actual Scene class (e.g., SubnetRouteGame)
+            let SceneClass = null;
+            for (const key of Object.keys(SceneModule)) {
+                const item = (SceneModule as any)[key];
+                if (item && item.prototype && item.prototype instanceof Scene) {
+                    SceneClass = item;
+                    break;
+                }
+            }
+
+            if (SceneClass) {
+                // Instantiate class directly with the component's canvas
+                this.sceneInstance = new (SceneClass as any)();
+                await this.sceneInstance.start(this.canvas);
+            } else {
+                // 2. Fallback: If no Scene class was exported, pass canvas to default export
+                const defaultFn = (SceneModule as any).default;
+                if (typeof defaultFn === 'function') {
+                    const origGetElementById = document.getElementById.bind(document);
+                    const compCanvas = this.canvas;
+                    const origStart = Scene.prototype.start;
+                    const self = this;
+
+                    // Intercept Scene.prototype.start to capture the instantiated Scene
+                    Scene.prototype.start = async function(...args: any[]) {
+                        self.sceneInstance = this;
+                        return await origStart.apply(this, args);
+                    };
+
+                    document.getElementById = function(id) {
+                        if (id === 'canvas') return compCanvas;
+                        return origGetElementById(id);
+                    };
+
+                    try {
+                        await defaultFn(this.canvas);
+                    } finally {
+                        document.getElementById = origGetElementById;
+                        Scene.prototype.start = origStart;
+                    }
+                }
+            }
+
+            if (this.sceneInstance) {
+                (window as any).retiamScene = this.sceneInstance;
+                (window as any).retiamElement = this;
+                this.dispatchEvent(new CustomEvent("retiam-ready", {
+                    detail: { scene: this.sceneInstance, element: this },
+                    bubbles: true
+                }));
+                this.dispatchEvent(new CustomEvent("retiam-scene-ready", {
+                    detail: { scene: this.sceneInstance, element: this },
+                    bubbles: true
+                }));
+            }
+        } catch (err) {
+            console.error("[Retiam Embed] Scene execution error:", err);
+        }
+    }
+
+    disconnectedCallback() {
+        if (this.resizeObserver) {
+            this.resizeObserver.disconnect();
+            this.resizeObserver = null;
+        }
+        if (this.sceneInstance) {
+            this.sceneInstance.destroy();
+            this.sceneInstance = null;
+        }
+        if ((window as any).retiamScene === this.sceneInstance) {
+            (window as any).retiamScene = null;
+        }
+    }
+}
+
+export const RetiamSceneElement = RetiamElement;
+
+try {
+    if (!customElements.get("retiam")) {
+        customElements.define("retiam", RetiamElement);
+    }
+} catch (e) {}
+
+if (!customElements.get("retiam-scene")) {
+    customElements.define("retiam-scene", RetiamElement);
+}
+
+function autoMountRetiamTags() {
+    const nodes = document.querySelectorAll("retiam, Retiam");
+    nodes.forEach(node => {
+        if (!(node as any).__retiamMounted) {
+            (node as any).__retiamMounted = true;
+            const elem = document.createElement("retiam-scene");
+            for (let i = 0; i < node.attributes.length; i++) {
+                const attr = node.attributes[i];
+                elem.setAttribute(attr.name, attr.value);
+            }
+            node.replaceWith(elem);
+        }
+    });
+}
+
+if (typeof document !== "undefined") {
+    const styleId = "retiam-embed-default-style";
+    if (!document.getElementById(styleId)) {
+        const style = document.createElement("style");
+        style.id = styleId;
+        style.textContent = "retiam, retiam-scene { display: block; position: relative; }";
+        document.head?.appendChild(style);
+    }
+
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", autoMountRetiamTags);
+    } else {
+        autoMountRetiamTags();
+    }
+
+    try {
+        const obs = new MutationObserver(() => autoMountRetiamTags());
+        obs.observe(document.documentElement || document.body, { childList: true, subtree: true });
+    } catch (e) {}
+}
+`;
+
+fs.writeFileSync(tempEntryPath, entryCode);
+
+function minifyWGSL(code) {
+    return code
+        .replace(/\/\*[\s\S]*?\*\//g, '')  // Remove block comments
+        .replace(/\/\/.*/g, '')             // Remove line comments
+        .split('\n')                        // Process line by line
+        .map(line => line.trim())           // Trim whitespace per line
+        .filter(line => line.length > 0)    // Remove empty lines
+        .join('\n');                        // Preserve line breaks for WebGPU debugging
+}
+
+const wgslPlugin = () => ({
+    name: 'wgsl-loader',
+    transform(code, id) {
+        if (id.endsWith('.wgsl')) {
+            const minified = minifyWGSL(code);
+            return { code: `export default ${JSON.stringify(minified)};`, map: null };
+        }
+    }
+});
+
+const tzaPlugin = () => ({
+    name: 'tza-loader',
+    enforce: 'pre',
+    load(id) {
+        if (/\.(tza|ttf|png)$/i.test(id) || id.endsWith('.json?url')) {
+            const filePath = id.replace(/\?url$/, '');
+            const source = fs.readFileSync(filePath);
+            const referenceId = this.emitFile({
+                type: 'asset',
+                fileName: `assets/${path.basename(filePath)}`,
+                source: source
+            });
+            return `export default import.meta.ROLLUP_FILE_URL_${referenceId};`;
+        }
+        return null;
+    }
+});
+
+console.log(`🚀 Building standalone embed for: ${inputPath} -> ${targetOutDir}/${outputFile}`);
+
+try {
+    await build({
+        configFile: false,
+        publicDir: false,
+        assetsInclude: ['**/*.tza', '**/*.ttf', '**/*.png'],
+        plugins: [tzaPlugin(), wgslPlugin()],
+        resolve: {
+            alias: [
+                { find: '../../index', replacement: path.resolve(rootDir, 'src/engine/_core/Constants.ts') },
+                { find: '../index', replacement: path.resolve(rootDir, 'src/engine/_core/Constants.ts') }
+            ]
+        },
+        build: {
+            outDir: targetOutDir,
+            emptyOutDir: false,
+            lib: {
+                entry: tempEntryPath,
+                name: 'RetiamEmbed',
+                fileName: () => outputFile,
+                formats: ['iife']
+            },
+            rollupOptions: {
+                output: { inlineDynamicImports: true }
+            },
+            minify: 'esbuild'
+        },
+        esbuild: {
+            drop: ['debugger'],
+            legalComments: 'none',
+            treeShaking: true
+        }
+    });
+
+    console.log(`✅ Build successful! Output: ${targetOutDir}/${outputFile}`);
+} catch (e) {
+    console.error("❌ Build failed:", e);
+} finally {
+    if (fs.existsSync(tempEntryPath)) {
+        fs.unlinkSync(tempEntryPath);
+    }
+}