@vib3code/sdk 2.0.3-canary.91a95f3 → 2.0.3-canary.98b84da

package/src/cli/index.js

@@ -5,9 +5,34 @@
  */
 
 import { performance } from 'node:perf_hooks';
+import path from 'node:path';
 import { mcpServer, toolDefinitions } from '../agent/index.js';
 import { schemaRegistry } from '../schemas/index.js';
 
+/**
+ * Resolves a file path and ensures it is within the current working directory.
+ * @param {string} filePath The path to validate
+ * @returns {string} The resolved absolute path
+ * @throws {Error} If the path is outside the allowed directory
+ */
+function getSafePath(filePath) {
+    if (!filePath) return filePath;
+
+    const cwd = process.cwd();
+    const resolvedPath = path.resolve(cwd, filePath);
+    const relative = path.relative(cwd, resolvedPath);
+
+    const isOutside = relative.startsWith('..') || path.isAbsolute(relative);
+
+    if (isOutside) {
+        const error = new Error('Security Error: Path traversal detected. Access denied.');
+        error.code = 'EACCES';
+        throw error;
+    }
+
+    return resolvedPath;
+}
+
 /**
  * CLI Configuration
  */
@@ -172,7 +197,8 @@ function showHelp(isJson) {
         description: 'VIB3+ 4D Visualization Engine CLI',
         usage: `${CLI_NAME} <command> [options]`,
         commands: {
-            create: 'Create a new 4D visualization',
+            init: 'Scaffold a new VIB3+ project (--template vanilla|react|vue|svelte)',
+            create: 'Create a new 4D visualization (--describe, --preset, --color, --hue, --XW, etc.)',
             state: 'Get current engine state',
             set: 'Set parameters (rotation, visual)',
             geometry: 'Change or list geometries',
@@ -190,7 +216,14 @@ function showHelp(isJson) {
             '--verbose': 'Verbose output'
         },
         examples: [
+            `${CLI_NAME} init my-app`,
+            `${CLI_NAME} init my-app --template react`,
+            `${CLI_NAME} init my-app --template vue`,
+            `${CLI_NAME} init my-app --template svelte`,
             `${CLI_NAME} create --system quantum --geometry 8 --json`,
+            `${CLI_NAME} create --describe "serene ocean deep organic"`,
+            `${CLI_NAME} create --system holographic --preset energetic --color neon`,
+            `${CLI_NAME} create --system faceted --geometry 16 --XW 0.8 --YW 0.5 --hue 200`,
             `${CLI_NAME} set rotation --XW 1.5 --YW 0.5`,
             `${CLI_NAME} set visual --hue 200 --chaos 0.3`,
             `${CLI_NAME} geometry list --core-type hypersphere`,
@@ -224,15 +257,84 @@ function showVersion(isJson) {
 
 /**
  * Handle 'create' command
+ *
+ * Supports full creative parameter control:
+ *   vib3 create --system quantum --geometry 11 --hue 200 --chaos 0.3
+ *   vib3 create --system holographic --preset energetic
+ *   vib3 create --describe "serene ocean deep organic"
+ *   vib3 create --system faceted --geometry 16 --XW 0.8 --YW 0.5 --speed 0.6
  */
 async function handleCreate(parsed) {
-    const args = {
-        system: parsed.options.system || 'quantum',
-        geometry_index: parseInt(parsed.options.geometry || '0'),
-        projection: parsed.options.projection || 'perspective'
+    const opts = parsed.options;
+
+    // Natural language description path — uses AestheticMapper
+    if (opts.describe || opts.description) {
+        const description = opts.describe || opts.description;
+        return await mcpServer.handleToolCall('design_from_description', {
+            description,
+            apply: true
+        });
+    }
+
+    // Step 1: Create the visualization scene
+    const createArgs = {
+        system: opts.system || 'quantum',
+        geometry_index: parseInt(opts.geometry || '0'),
+        projection: opts.projection || 'perspective'
     };
+    const createResult = await mcpServer.handleToolCall('create_4d_visualization', createArgs);
+
+    // Step 2: Apply rotation if any 6D rotation flags provided
+    const rotationPlanes = ['XY', 'XZ', 'YZ', 'XW', 'YW', 'ZW'];
+    const rotationArgs = {};
+    let hasRotation = false;
+    for (const plane of rotationPlanes) {
+        if (opts[plane] !== undefined) {
+            rotationArgs[plane] = parseFloat(opts[plane]);
+            hasRotation = true;
+        }
+    }
+    if (hasRotation) {
+        await mcpServer.handleToolCall('set_rotation', rotationArgs);
+    }
 
-    return await mcpServer.handleToolCall('create_4d_visualization', args);
+    // Step 3: Apply visual parameters if any provided
+    const visualKeys = ['hue', 'saturation', 'intensity', 'speed', 'chaos', 'morphFactor', 'gridDensity', 'dimension'];
+    const visualArgs = {};
+    let hasVisual = false;
+    for (const key of visualKeys) {
+        if (opts[key] !== undefined) {
+            visualArgs[key] = key === 'hue' ? parseInt(opts[key]) : parseFloat(opts[key]);
+            hasVisual = true;
+        }
+    }
+    if (hasVisual) {
+        await mcpServer.handleToolCall('set_visual_parameters', visualArgs);
+    }
+
+    // Step 4: Apply behavior preset if specified (ambient, reactive, immersive, energetic, calm, cinematic)
+    if (opts.preset) {
+        const presetDefaults = {
+            ambient:    { speed: 0.3, chaos: 0.1 },
+            reactive:   { speed: 1.0, chaos: 0.3 },
+            immersive:  { speed: 0.8, chaos: 0.15 },
+            energetic:  { speed: 2.5, chaos: 0.8 },
+            calm:       { speed: 0.2, chaos: 0.05 },
+            cinematic:  { speed: 0.5, chaos: 0.2 }
+        };
+        const presetParams = presetDefaults[opts.preset];
+        if (presetParams) {
+            await mcpServer.handleToolCall('set_visual_parameters', presetParams);
+        }
+    }
+
+    // Step 5: Apply color preset if specified (ocean, neon, galaxy, etc.)
+    if (opts.color || opts.colorPreset) {
+        const colorName = opts.color || opts.colorPreset;
+        await mcpServer.handleToolCall('apply_color_preset', { preset: colorName });
+    }
+
+    return createResult;
 }
 
 /**
@@ -369,7 +471,7 @@ async function handleTools(parsed, startTime) {
  */
 async function handleValidate(parsed, startTime) {
     const subcommand = parsed.subcommand || 'pack';
-    const filePath = parsed.options.file || parsed.options.f || parsed.positional[0];
+    let filePath = parsed.options.file || parsed.options.f || parsed.positional[0];
 
     if (!filePath && subcommand !== 'schema') {
         return wrapResponse('validate', {
@@ -383,6 +485,10 @@ async function handleValidate(parsed, startTime) {
     }
 
     try {
+        if (filePath) {
+            filePath = getSafePath(filePath);
+        }
+
         switch (subcommand) {
             case 'pack': {
                 // Validate a .vib3 scene pack file
@@ -456,6 +562,17 @@ async function handleValidate(parsed, startTime) {
                 }, false, performance.now() - startTime);
         }
     } catch (error) {
+        if (error.code === 'EACCES') {
+            return wrapResponse('validate', {
+                error: {
+                    type: 'SecurityError',
+                    code: 'ACCESS_DENIED',
+                    message: error.message,
+                    suggestion: 'Ensure the file path is within the project directory'
+                }
+            }, false, performance.now() - startTime);
+        }
+
         if (error.code === 'ENOENT') {
             return wrapResponse('validate', {
                 error: {
@@ -578,13 +695,43 @@ async function main() {
 
 /**
  * Handle init command — scaffold a new VIB3+ project
+ * Supports --template vanilla|react|vue|svelte
  */
 async function handleInit(parsed, startTime) {
     const { writeFileSync, mkdirSync, existsSync } = await import('node:fs');
-    const { join } = await import('node:path');
 
-    const projectName = parsed.positional[0] || 'my-vib3-app';
-    const projectDir = join(process.cwd(), projectName);
+    const projectName = parsed.subcommand || parsed.positional[0] || 'my-vib3-app';
+    const template = parsed.options.template || parsed.options.t || 'vanilla';
+    const validTemplates = ['vanilla', 'react', 'vue', 'svelte'];
+
+    if (!validTemplates.includes(template)) {
+        return wrapResponse('init', {
+            error: {
+                type: 'ValidationError',
+                code: 'INVALID_TEMPLATE',
+                message: `Unknown template: ${template}`,
+                valid_options: validTemplates,
+                suggestion: `Use --template ${validTemplates.join('|')}`
+            }
+        }, false, performance.now() - startTime);
+    }
+
+    let projectDir;
+    try {
+        projectDir = getSafePath(projectName);
+    } catch (error) {
+        if (error.code === 'EACCES') {
+            return wrapResponse('init', {
+                error: {
+                    type: 'SecurityError',
+                    code: 'ACCESS_DENIED',
+                    message: error.message,
+                    suggestion: 'Choose a project name that results in a valid subdirectory'
+                }
+            }, false, performance.now() - startTime);
+        }
+        throw error;
+    }
 
     if (existsSync(projectDir)) {
         return wrapResponse('init', {
@@ -599,25 +746,277 @@ async function handleInit(parsed, startTime) {
 
     mkdirSync(projectDir, { recursive: true });
 
-    // package.json
-    writeFileSync(join(projectDir, 'package.json'), JSON.stringify({
-        name: projectName,
-        version: '0.1.0',
-        type: 'module',
-        scripts: {
-            dev: 'npx vite --open',
-            build: 'npx vite build'
-        },
-        dependencies: {
-            '@vib3code/sdk': '^2.0.0'
-        },
-        devDependencies: {
-            vite: '^5.3.0'
+    const files = getTemplateFiles(template, projectName);
+
+    for (const [filename, content] of Object.entries(files)) {
+        const filepath = path.join(projectDir, filename);
+        const dir = path.join(projectDir, filename.split('/').slice(0, -1).join('/'));
+        if (dir !== projectDir) {
+            mkdirSync(dir, { recursive: true });
         }
-    }, null, 2) + '\n');
+        writeFileSync(filepath, content);
+    }
 
-    // index.html
-    writeFileSync(join(projectDir, 'index.html'), `<!DOCTYPE html>
+    const fileNames = Object.keys(files);
+    const tree = fileNames.map((f, i) =>
+        `  ${i === fileNames.length - 1 ? '└── ' : '├── '}${f}`
+    ).join('\n');
+
+    console.log(`\n  Created ${projectName}/ (${template} template)`);
+    console.log(tree);
+    console.log(`\n  Next steps:`);
+    console.log(`    cd ${projectName}`);
+    console.log('    npm install');
+    console.log('    npm run dev\n');
+
+    return wrapResponse('init', {
+        project: projectName,
+        template,
+        files: fileNames,
+        next_steps: [`cd ${projectName}`, 'npm install', 'npm run dev']
+    }, true, performance.now() - startTime);
+}
+
+/**
+ * Generate template files based on framework choice
+ */
+function getTemplateFiles(template, projectName) {
+    const sdkDep = { '@vib3code/sdk': '^2.0.0' };
+    const viteDep = { vite: '^5.3.0' };
+
+    switch (template) {
+        case 'react':
+            return {
+                'package.json': JSON.stringify({
+                    name: projectName,
+                    version: '0.1.0',
+                    type: 'module',
+                    scripts: { dev: 'npx vite --open', build: 'npx vite build' },
+                    dependencies: { ...sdkDep, react: '^18.3.0', 'react-dom': '^18.3.0' },
+                    devDependencies: { ...viteDep, '@vitejs/plugin-react': '^4.3.0' }
+                }, null, 2) + '\n',
+                'vite.config.js': `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+export default defineConfig({ plugins: [react()] });
+`,
+                'index.html': `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${projectName}</title>
+</head>
+<body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+</body>
+</html>
+`,
+                'src/main.jsx': `import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App.jsx';
+
+ReactDOM.createRoot(document.getElementById('root')).render(<App />);
+`,
+                'src/App.jsx': `import React, { useRef, useEffect, useState } from 'react';
+import { VIB3Engine } from '@vib3code/sdk/core';
+
+export default function App() {
+    const engineRef = useRef(null);
+    const [system, setSystem] = useState('quantum');
+    const [geometry, setGeometry] = useState(0);
+    const [hue, setHue] = useState(200);
+
+    useEffect(() => {
+        const engine = new VIB3Engine();
+        engineRef.current = engine;
+        engine.initialize().then(() => engine.switchSystem(system));
+        return () => engine.destroy();
+    }, []);
+
+    useEffect(() => {
+        engineRef.current?.switchSystem(system);
+    }, [system]);
+
+    useEffect(() => {
+        engineRef.current?.setParameter('geometry', geometry);
+    }, [geometry]);
+
+    useEffect(() => {
+        engineRef.current?.setParameter('hue', hue);
+    }, [hue]);
+
+    return (
+        <div style={{ margin: 0, background: '#07070f', minHeight: '100vh' }}>
+            <div style={{ position: 'fixed', top: 12, left: 12, zIndex: 10, font: '13px monospace', color: '#0fc', display: 'flex', gap: 12 }}>
+                <label>System:
+                    <select value={system} onChange={e => setSystem(e.target.value)} style={{ marginLeft: 6 }}>
+                        <option>quantum</option>
+                        <option>faceted</option>
+                        <option>holographic</option>
+                    </select>
+                </label>
+                <label>Geometry: <input type="range" min="0" max="23" value={geometry} onChange={e => setGeometry(+e.target.value)} /></label>
+                <label>Hue: <input type="range" min="0" max="360" value={hue} onChange={e => setHue(+e.target.value)} /></label>
+            </div>
+        </div>
+    );
+}
+`
+            };
+
+        case 'vue':
+            return {
+                'package.json': JSON.stringify({
+                    name: projectName,
+                    version: '0.1.0',
+                    type: 'module',
+                    scripts: { dev: 'npx vite --open', build: 'npx vite build' },
+                    dependencies: { ...sdkDep, vue: '^3.4.0' },
+                    devDependencies: { ...viteDep, '@vitejs/plugin-vue': '^5.1.0' }
+                }, null, 2) + '\n',
+                'vite.config.js': `import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+export default defineConfig({ plugins: [vue()] });
+`,
+                'index.html': `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${projectName}</title>
+</head>
+<body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+</body>
+</html>
+`,
+                'src/main.js': `import { createApp } from 'vue';
+import App from './App.vue';
+createApp(App).mount('#app');
+`,
+                'src/App.vue': `<script setup>
+import { ref, onMounted, onUnmounted, watch } from 'vue';
+import { VIB3Engine } from '@vib3code/sdk/core';
+
+const engine = ref(null);
+const system = ref('quantum');
+const geometry = ref(0);
+const hue = ref(200);
+
+onMounted(async () => {
+    engine.value = new VIB3Engine();
+    await engine.value.initialize();
+    await engine.value.switchSystem(system.value);
+});
+
+onUnmounted(() => engine.value?.destroy());
+
+watch(system, (val) => engine.value?.switchSystem(val));
+watch(geometry, (val) => engine.value?.setParameter('geometry', val));
+watch(hue, (val) => engine.value?.setParameter('hue', val));
+</script>
+
+<template>
+    <div style="margin: 0; background: #07070f; min-height: 100vh">
+        <div style="position: fixed; top: 12px; left: 12px; z-index: 10; font: 13px monospace; color: #0fc; display: flex; gap: 12px">
+            <label>System:
+                <select v-model="system" style="margin-left: 6px">
+                    <option>quantum</option>
+                    <option>faceted</option>
+                    <option>holographic</option>
+                </select>
+            </label>
+            <label>Geometry: <input type="range" min="0" max="23" v-model.number="geometry" /></label>
+            <label>Hue: <input type="range" min="0" max="360" v-model.number="hue" /></label>
+        </div>
+    </div>
+</template>
+`
+            };
+
+        case 'svelte':
+            return {
+                'package.json': JSON.stringify({
+                    name: projectName,
+                    version: '0.1.0',
+                    type: 'module',
+                    scripts: { dev: 'npx vite --open', build: 'npx vite build' },
+                    dependencies: sdkDep,
+                    devDependencies: { ...viteDep, '@sveltejs/vite-plugin-svelte': '^3.2.0', svelte: '^4.2.0' }
+                }, null, 2) + '\n',
+                'vite.config.js': `import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+export default defineConfig({ plugins: [svelte()] });
+`,
+                'index.html': `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${projectName}</title>
+</head>
+<body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+</body>
+</html>
+`,
+                'src/main.js': `import App from './App.svelte';
+const app = new App({ target: document.getElementById('app') });
+export default app;
+`,
+                'src/App.svelte': `<script>
+    import { onMount, onDestroy } from 'svelte';
+    import { VIB3Engine } from '@vib3code/sdk/core';
+
+    let engine = null;
+    let system = 'quantum';
+    let geometry = 0;
+    let hue = 200;
+
+    onMount(async () => {
+        engine = new VIB3Engine();
+        await engine.initialize();
+        await engine.switchSystem(system);
+    });
+
+    onDestroy(() => engine?.destroy());
+
+    $: engine?.switchSystem(system);
+    $: engine?.setParameter('geometry', geometry);
+    $: engine?.setParameter('hue', hue);
+</script>
+
+<div style="margin: 0; background: #07070f; min-height: 100vh">
+    <div style="position: fixed; top: 12px; left: 12px; z-index: 10; font: 13px monospace; color: #0fc; display: flex; gap: 12px">
+        <label>System:
+            <select bind:value={system} style="margin-left: 6px">
+                <option>quantum</option>
+                <option>faceted</option>
+                <option>holographic</option>
+            </select>
+        </label>
+        <label>Geometry: <input type="range" min="0" max="23" bind:value={geometry} /></label>
+        <label>Hue: <input type="range" min="0" max="360" bind:value={hue} /></label>
+    </div>
+</div>
+`
+            };
+
+        case 'vanilla':
+        default:
+            return {
+                'package.json': JSON.stringify({
+                    name: projectName,
+                    version: '0.1.0',
+                    type: 'module',
+                    scripts: { dev: 'npx vite --open', build: 'npx vite build' },
+                    dependencies: sdkDep,
+                    devDependencies: viteDep
+                }, null, 2) + '\n',
+                'index.html': `<!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="utf-8">
@@ -638,10 +1037,8 @@ async function handleInit(parsed, startTime) {
     <script type="module" src="main.js"></script>
 </body>
 </html>
-`);
-
-    // main.js
-    writeFileSync(join(projectDir, 'main.js'), `import { VIB3Engine } from '@vib3code/sdk/core';
+`,
+                'main.js': `import { VIB3Engine } from '@vib3code/sdk/core';
 
 const engine = new VIB3Engine();
 await engine.initialize();
@@ -650,22 +1047,9 @@ await engine.switchSystem('quantum');
 document.getElementById('sys').addEventListener('change', (e) => engine.switchSystem(e.target.value));
 document.getElementById('geo').addEventListener('input', (e) => engine.setParameter('geometry', +e.target.value));
 document.getElementById('hue').addEventListener('input', (e) => engine.setParameter('hue', +e.target.value));
-`);
-
-    console.log(`\\n  Created ${projectName}/`);
-    console.log('  ├── package.json');
-    console.log('  ├── index.html');
-    console.log('  └── main.js');
-    console.log(`\\n  Next steps:`);
-    console.log(`    cd ${projectName}`);
-    console.log('    npm install');
-    console.log('    npm run dev\\n');
-
-    return wrapResponse('init', {
-        project: projectName,
-        files: ['package.json', 'index.html', 'main.js'],
-        next_steps: [`cd ${projectName}`, 'npm install', 'npm run dev']
-    }, true, performance.now() - startTime);
+`
+            };
+    }
 }
 
 // Run CLI

package/src/core/VIB3Engine.js

@@ -26,7 +26,7 @@ export class VIB3Engine {
      */
     constructor(options = {}) {
         this.activeSystem = null; // Only one system active at a time
-        this.currentSystemName = 'quantum';
+        this.currentSystemName = options.system || 'quantum';
         this.parameters = new ParameterManager();
         this.initialized = false;
         this.canvasManager = null;
@@ -82,7 +82,11 @@ export class VIB3Engine {
         }
 
         // Initialize starting system
-        await this.switchSystem(this.currentSystemName);
+        const systemOk = await this.switchSystem(this.currentSystemName);
+        if (!systemOk) {
+            console.error(`VIB3+ Engine: Failed to create initial system "${this.currentSystemName}"`);
+            return false;
+        }
 
         // Sync base parameters to reactivity manager
         this.reactivity.setBaseParameters(this.parameters.getAllParameters());
@@ -167,7 +171,7 @@ export class VIB3Engine {
                         }
                     }
 
-                    const facetedSuccess = system.initialize();
+                    const facetedSuccess = await system.initialize();
                     if (!facetedSuccess) {
                         throw new Error('Faceted system initialization failed');
                     }
@@ -273,6 +277,17 @@ export class VIB3Engine {
 
         if (this.activeSystem && this.activeSystem.updateParameters) {
             this.activeSystem.updateParameters(params);
+        } else if (this.debug && this.activeSystem && !this.activeSystem.updateParameters) {
+            console.warn('VIB3+ Engine [debug]: activeSystem missing updateParameters() method');
+        } else if (this.debug && !this.activeSystem) {
+            console.warn('VIB3+ Engine [debug]: updateCurrentSystemParameters() called with no activeSystem');
+        }
+
+        // Notify parameter change listeners
+        if (this._parameterListeners && this._parameterListeners.size > 0) {
+            for (const listener of this._parameterListeners) {
+                try { listener(params); } catch (_) { /* listener error */ }
+            }
         }
     }
 
@@ -632,6 +647,43 @@ export class VIB3Engine {
         }
     }
 
+    // ========================================================================
+    // Convenience Methods (dogfood feedback)
+    // ========================================================================
+
+    /**
+     * Create a parameter update callback for use with creative modules.
+     * Returns (name, value) => void that calls setParameter internally.
+     * Eliminates boilerplate: `(name, value) => engine.setParameter(name, value)`.
+     * @returns {(name: string, value: number) => void}
+     */
+    createParameterCallback() {
+        return (name, value) => this.setParameter(name, value);
+    }
+
+    /**
+     * Get current breath value from VitalitySystem (0-1).
+     * Avoids reaching into engine.vitality.getBreath() directly.
+     * @returns {number}
+     */
+    getBreath() {
+        return this.vitality.getBreath();
+    }
+
+    /**
+     * Register a listener for parameter changes.
+     * Callback receives the full parameter object after each change.
+     * @param {(params: object) => void} callback
+     * @returns {() => void} Unsubscribe function
+     */
+    onParameterChange(callback) {
+        if (!this._parameterListeners) {
+            this._parameterListeners = new Set();
+        }
+        this._parameterListeners.add(callback);
+        return () => this._parameterListeners.delete(callback);
+    }
+
     /**
      * Destroy engine and clean up
      */

package/src/core/index.js

@@ -0,0 +1,18 @@
+/**
+ * VIB3+ Core Module
+ * @module core
+ */
+
+export { VIB3Engine } from './VIB3Engine.js';
+export { CanvasManager } from './CanvasManager.js';
+export { ParameterManager } from './Parameters.js';
+export { ParameterMapper } from './ParameterMapper.js';
+export { ErrorReporter } from './ErrorReporter.js';
+export { VitalitySystem } from './VitalitySystem.js';
+export { UnifiedResourceManager } from './UnifiedResourceManager.js';
+export {
+    RendererContract,
+    RendererContractAdapter,
+    verifyRendererContract,
+    ResourceManagerContract
+} from './RendererContracts.js';