@vib3code/sdk 2.0.3-canary.6f35b4c → 2.0.3-canary.74aebb4

package/src/agent/mcp/MCPServer.js

@@ -9,6 +9,9 @@ import { telemetry, EventType, withTelemetry } from '../telemetry/index.js';
 import { AestheticMapper } from '../../creative/AestheticMapper.js';
 import { ChoreographyPlayer } from '../../creative/ChoreographyPlayer.js';
 import { ParameterTimeline } from '../../creative/ParameterTimeline.js';
+import { ColorPresetsSystem } from '../../creative/ColorPresetsSystem.js';
+import { TransitionAnimator } from '../../creative/TransitionAnimator.js';
+import { PRESET_REGISTRY } from '../../render/LayerRelationshipGraph.js';
 
 /**
  * Generate unique IDs
@@ -41,6 +44,36 @@ export class MCPServer {
         this.engine = engine;
         this.sceneId = null;
         this.initialized = false;
+        this._gallerySlots = new Map();
+    }
+
+    /**
+     * Get or lazily create ColorPresetsSystem instance.
+     * Requires engine for the parameter update callback.
+     * @returns {ColorPresetsSystem|null}
+     */
+    _getColorPresets() {
+        if (this._colorPresets) return this._colorPresets;
+        if (!this.engine) return null;
+        this._colorPresets = new ColorPresetsSystem(
+            (name, value) => this.engine.setParameter(name, value)
+        );
+        return this._colorPresets;
+    }
+
+    /**
+     * Get or lazily create TransitionAnimator instance.
+     * Requires engine for the parameter update/get callbacks.
+     * @returns {TransitionAnimator|null}
+     */
+    _getTransitionAnimator() {
+        if (this._transitionAnimator) return this._transitionAnimator;
+        if (!this.engine) return null;
+        this._transitionAnimator = new TransitionAnimator(
+            (name, value) => this.engine.setParameter(name, value),
+            (name) => this.engine.getParameter(name)
+        );
+        return this._transitionAnimator;
     }
 
     buildResponse(operation, data, options = {}) {
@@ -140,10 +173,13 @@ export class MCPServer {
                     result = this.getParameterSchema();
                     break;
                 case 'get_sdk_context':
-                    result = this.getSDKContext();
+                    result = this.getSDKContext(args);
                     break;
-                case 'verify_knowledge':
-                    result = this.verifyKnowledge(args);
+                case 'inspect_layers':
+                    result = this.inspectLayers(args);
+                    break;
+                case 'set_holographic_layer':
+                    result = this.setHolographicLayer(args);
                     break;
                 // Reactivity tools (Phase 6.5)
                 case 'set_reactivity_config':
@@ -204,6 +240,22 @@ export class MCPServer {
                 case 'control_timeline':
                     result = this.controlTimeline(args);
                     break;
+                // Layer relationship tools (Phase 8)
+                case 'set_layer_profile':
+                    result = this.setLayerProfile(args);
+                    break;
+                case 'set_layer_relationship':
+                    result = this.setLayerRelationship(args);
+                    break;
+                case 'set_layer_keystone':
+                    result = this.setLayerKeystone(args);
+                    break;
+                case 'get_layer_config':
+                    result = this.getLayerConfig();
+                    break;
+                case 'tune_layer_relationship':
+                    result = this.tuneLayerRelationship(args);
+                    break;
                 default:
                     throw new Error(`Unknown tool: ${toolName}`);
             }
@@ -467,32 +519,68 @@ export class MCPServer {
 
         telemetry.recordEvent(EventType.GALLERY_SAVE, { slot });
 
+        // Persist actual engine state if available
+        if (this.engine) {
+            const state = this.engine.exportState();
+            this._gallerySlots.set(slot, {
+                name: name || `Variation ${slot}`,
+                saved_at: new Date().toISOString(),
+                state
+            });
+        }
+
         return {
             slot,
             name: name || `Variation ${slot}`,
             saved_at: new Date().toISOString(),
+            persisted: !!this.engine,
+            gallery_size: this._gallerySlots.size,
             suggested_next_actions: ['load_from_gallery', 'randomize_parameters']
         };
     }
 
     /**
-     * Load from gallery
+     * Load from gallery — restores previously saved state
      */
     loadFromGallery(args) {
         const { slot } = args;
 
-        if (this.engine) {
-            // Apply variation
-            const params = this.engine.parameters?.generateVariationParameters?.(slot) || {};
-            this.engine.setParameters(params);
+        telemetry.recordEvent(EventType.GALLERY_LOAD, { slot });
+
+        const saved = this._gallerySlots.get(slot);
+        if (saved && this.engine) {
+            // Restore saved state
+            this.engine.importState(saved.state);
+            return {
+                slot,
+                name: saved.name,
+                saved_at: saved.saved_at,
+                loaded_at: new Date().toISOString(),
+                restored: true,
+                ...this.getState()
+            };
         }
 
-        telemetry.recordEvent(EventType.GALLERY_LOAD, { slot });
+        if (!saved) {
+            // No saved state — fall back to random variation
+            if (this.engine) {
+                const params = this.engine.parameters?.generateVariationParameters?.(slot) || {};
+                this.engine.setParameters(params);
+            }
+            return {
+                slot,
+                loaded_at: new Date().toISOString(),
+                restored: false,
+                note: 'No saved state in this slot — generated random variation',
+                ...this.getState()
+            };
+        }
 
         return {
             slot,
             loaded_at: new Date().toISOString(),
-            ...this.getState()
+            restored: false,
+            note: 'Engine not initialized — cannot apply state'
         };
     }
 
@@ -565,162 +653,218 @@ export class MCPServer {
     /**
      * Get SDK context for agent onboarding
      */
-    getSDKContext() {
-        return {
-            sdk_name: 'VIB3+ SDK',
-            version: '1.9.0',
-            purpose: 'General-purpose 4D rotation visualization SDK for plugins, extensions, wearables, and agentic use',
-
-            quick_reference: {
-                active_visualization_systems: 3,
-                placeholder_systems: 1,
-                rotation_planes: 6,
-                base_geometries: 8,
-                core_warp_types: 3,
-                total_geometries: 24,
-                canvas_layers_per_system: 5
-            },
-
-            systems: {
-                ACTIVE: [
-                    { name: 'quantum', description: 'Complex quantum lattice visualizations with 24 geometries' },
-                    { name: 'faceted', description: 'Clean 2D geometric patterns with 4D rotation' },
-                    { name: 'holographic', description: '5-layer audio-reactive holographic effects' }
-                ],
-                PLACEHOLDER_TBD: [
-                    { name: 'polychora', status: 'TBD', description: '4D polytopes - placeholder, not production ready' }
-                ]
+    getSDKContext(args = {}) {
+        const { include_state = true, include_tools = false } = args;
+
+        const context = {
+            sdk: 'VIB3+ 4D Visualization Engine',
+            version: '2.0.3',
+
+            // Capability manifest — what this engine can do
+            capabilities: {
+                systems: ['quantum', 'faceted', 'holographic'],
+                geometries: { count: 24, formula: 'core_type * 8 + base_geometry', base: 8, warps: 3 },
+                rotation: { planes: 6, '3D': ['XY', 'XZ', 'YZ'], '4D': ['XW', 'YW', 'ZW'], range: '±6.28 rad' },
+                layers: { count: 5, roles: ['background', 'shadow', 'content', 'highlight', 'accent'], addressable: true },
+                audio: { bands: ['bass', 'mid', 'high'], modes: ['add', 'multiply', 'replace', 'max', 'min'] },
+                input: { sources: ['deviceTilt', 'mousePosition', 'gyroscope', 'gamepad', 'perspective', 'programmatic', 'audio', 'midi'] },
+                creative: {
+                    color_presets: 22,
+                    easing_functions: 14,
+                    post_effects: 14,
+                    aesthetic_keywords: '130+',
+                    choreography: true,
+                    timeline_bpm_sync: true
+                },
+                environment: {
+                    browser: typeof document !== 'undefined',
+                    screenshot: typeof document !== 'undefined',
+                    webgpu: typeof navigator !== 'undefined' && !!navigator.gpu,
+                    wasm: typeof WebAssembly !== 'undefined'
+                }
             },
 
-            geometry_encoding: {
-                formula: 'geometry_index = core_index * 8 + base_index',
-                base_geometries: ['tetrahedron', 'hypercube', 'sphere', 'torus', 'klein_bottle', 'fractal', 'wave', 'crystal'],
-                core_types: ['base (0)', 'hypersphere (1)', 'hypertetrahedron (2)'],
-                example: 'geometry 10 = hypersphere(sphere) because 1*8+2=10'
+            // Parameter ranges — the agent needs these to generate valid values
+            parameter_ranges: {
+                geometry: { min: 0, max: 23, type: 'integer' },
+                hue: { min: 0, max: 360, type: 'integer' },
+                saturation: { min: 0, max: 1 },
+                intensity: { min: 0, max: 1 },
+                speed: { min: 0.1, max: 3 },
+                chaos: { min: 0, max: 1 },
+                morphFactor: { min: 0, max: 2 },
+                gridDensity: { min: 4, max: 100 },
+                dimension: { min: 3.0, max: 4.5 },
+                rot4dXY: { min: -6.28, max: 6.28 },
+                rot4dXW: { min: -6.28, max: 6.28 }
             },
 
-            rotation_planes: {
-                total: 6,
-                '3D_space': ['XY', 'XZ', 'YZ'],
-                '4D_hyperspace': ['XW', 'YW', 'ZW'],
-                range: '-6.28 to 6.28 radians'
+            // Workflow hints — what tool sequences accomplish creative goals
+            workflows: {
+                quick_design: 'design_from_description → describe_visual_state → batch_set_parameters',
+                choreography: 'create_choreography → play_choreography → describe_visual_state',
+                evolve: 'batch_set_parameters → describe_visual_state → batch_set_parameters (iterate)',
+                layer_control: 'inspect_layers → set_holographic_layer → inspect_layers',
+                audio_reactive: 'configure_audio_band → apply_behavior_preset → describe_visual_state'
             },
 
-            canvas_layers: {
-                count: 5,
-                names: ['background', 'shadow', 'content', 'highlight', 'accent']
-            },
+            // Geometry quick-reference
+            geometry_map: {
+                'sphere': 2, 'hypersphere+sphere': 10, 'hypertetra+sphere': 18,
+                'torus': 3, 'hypersphere+torus': 11, 'hypertetra+torus': 19,
+                'fractal': 5, 'hypersphere+fractal': 13, 'hypertetra+fractal': 21,
+                'crystal': 7, 'wave': 6, 'klein_bottle': 4, 'hypercube': 1, 'tetrahedron': 0
+            }
+        };
 
-            knowledge_quiz: {
-                IMPORTANT: 'Call verify_knowledge with multiple choice answers (a/b/c/d) to confirm understanding',
-                questions: [
-                    'Q1: How many rotation planes? a)3 b)4 c)6 d)8',
-                    'Q2: Geometry encoding formula? a)base*3+core b)core*8+base c)base+core d)core*base',
-                    'Q3: Canvas layers per system? a)3 b)4 c)5 d)6',
-                    'Q4: Which are the 3 ACTIVE systems? a)quantum,faceted,holographic b)quantum,faceted,polychora c)all four d)none',
-                    'Q5: How many base geometry types? a)6 b)8 c)10 d)24',
-                    'Q6: Core warp types? a)base,sphere,cube b)base,hypersphere,hypertetrahedron c)2D,3D,4D d)none'
-                ]
-            },
+        if (include_state) {
+            context.current_state = this.getState();
+        }
 
-            documentation: {
-                primary: 'DOCS/SYSTEM_INVENTORY.md',
-                geometry: '24-GEOMETRY-6D-ROTATION-SUMMARY.md',
-                controls: 'DOCS/CONTROL_REFERENCE.md',
-                cli: 'DOCS/CLI_ONBOARDING.md'
-            },
+        if (include_tools) {
+            context.tool_summary = Object.entries(toolDefinitions).map(([name, def]) => ({
+                name,
+                description: def.description.split('.')[0] // First sentence only
+            }));
+        }
 
-            suggested_next_actions: ['verify_knowledge', 'create_4d_visualization', 'search_geometries']
-        };
+        return context;
     }
 
     /**
-     * Verify agent knowledge of SDK (multiple choice)
+     * Inspect holographic layer state — returns per-layer metadata in JSON format.
+     * This replaces the old verify_knowledge quiz with something actually useful.
      */
-    verifyKnowledge(answers) {
-        const correctAnswers = {
-            q1_rotation_planes: 'c',      // 6 rotation planes
-            q2_geometry_formula: 'b',     // core*8+base
-            q3_canvas_layers: 'c',        // 5 layers
-            q4_active_systems: 'a',       // quantum, faceted, holographic (polychora is TBD)
-            q5_base_geometries: 'b',      // 8 base geometries
-            q6_core_types: 'b'            // base, hypersphere, hypertetrahedron
-        };
+    inspectLayers(args = {}) {
+        const { layer = 'all' } = args;
 
-        const docReferences = {
-            q1_rotation_planes: {
-                topic: '6D ROTATION SYSTEM',
-                doc: 'DOCS/SYSTEM_INVENTORY.md#the-6d-rotation-system',
-                reason: '6 planes: XY, XZ, YZ (3D) + XW, YW, ZW (4D hyperspace)'
-            },
-            q2_geometry_formula: {
-                topic: 'GEOMETRY ENCODING',
-                doc: '24-GEOMETRY-6D-ROTATION-SUMMARY.md',
-                reason: 'geometry = coreIndex * 8 + baseIndex. Example: 10 = 1*8+2 = hypersphere+sphere'
-            },
-            q3_canvas_layers: {
-                topic: 'CANVAS LAYER SYSTEM',
-                doc: 'DOCS/SYSTEM_INVENTORY.md#the-4-visualization-systems',
-                reason: '5 layers: background, shadow, content, highlight, accent'
-            },
-            q4_active_systems: {
-                topic: 'ACTIVE VS PLACEHOLDER SYSTEMS',
-                doc: 'DOCS/SYSTEM_INVENTORY.md',
-                reason: 'Only 3 ACTIVE: quantum, faceted, holographic. Polychora is TBD/placeholder!'
-            },
-            q5_base_geometries: {
-                topic: 'BASE GEOMETRY TYPES',
-                doc: '24-GEOMETRY-6D-ROTATION-SUMMARY.md',
-                reason: '8 base: tetrahedron, hypercube, sphere, torus, klein, fractal, wave, crystal'
-            },
-            q6_core_types: {
-                topic: 'CORE WARP TYPES',
-                doc: '24-GEOMETRY-6D-ROTATION-SUMMARY.md',
-                reason: '3 cores: base (no warp), hypersphere, hypertetrahedron'
-            }
+        const systemName = this.engine?.currentSystemName || 'unknown';
+        const isHolographic = systemName === 'holographic';
+
+        if (!isHolographic) {
+            return {
+                system: systemName,
+                note: 'Layer inspection is most detailed for the holographic system (5 independent canvas layers). Switch with switch_system("holographic").',
+                layers: [{
+                    role: 'main',
+                    system: systemName,
+                    opacity: 1.0,
+                    enabled: true,
+                    description: `Single canvas for ${systemName} system`
+                }],
+                suggested_next_actions: ['switch_system', 'describe_visual_state']
+            };
+        }
+
+        // Build layer metadata from the holographic system
+        const system = this.engine?.currentSystem;
+        const layerRoles = ['background', 'shadow', 'content', 'highlight', 'accent'];
+        const defaultConfigs = {
+            background: { densityMult: 0.4, speedMult: 0.2, colorShift: 0, intensity: 0.2, reactivity: 0.5 },
+            shadow:     { densityMult: 0.8, speedMult: 0.3, colorShift: 180, intensity: 0.4, reactivity: 0.7 },
+            content:    { densityMult: 1.0, speedMult: 1.0, colorShift: 0, intensity: 1.0, reactivity: 0.9 },
+            highlight:  { densityMult: 1.5, speedMult: 0.8, colorShift: 60, intensity: 0.6, reactivity: 1.1 },
+            accent:     { densityMult: 2.5, speedMult: 0.4, colorShift: 300, intensity: 0.3, reactivity: 1.5 }
         };
 
-        const results = {
-            score: 0,
-            max_score: 6,
-            details: [],
-            REVIEW_REQUIRED: []
+        const buildLayerInfo = (role) => {
+            const config = defaultConfigs[role] || {};
+            const visualizer = system?.visualizers?.find?.(v => v?.role === role);
+            const overrides = this._layerOverrides?.get(role) || {};
+
+            return {
+                role,
+                enabled: overrides.enabled !== undefined ? overrides.enabled : true,
+                opacity: overrides.opacity !== undefined ? overrides.opacity : 1.0,
+                blendMode: overrides.blendMode || 'normal',
+                densityMult: overrides.densityMult ?? config.densityMult,
+                speedMult: overrides.speedMult ?? config.speedMult,
+                colorShift: overrides.colorShift ?? config.colorShift,
+                intensity: overrides.intensity ?? config.intensity,
+                reactivity: overrides.reactivity ?? config.reactivity,
+                has_visualizer: !!visualizer
+            };
         };
 
-        // Check each answer
-        for (const [question, correct] of Object.entries(correctAnswers)) {
-            const given = answers[question]?.toLowerCase?.() || answers[question];
-            if (given === correct) {
-                results.score++;
-                results.details.push({ question, status: '✓ CORRECT' });
-            } else if (given !== undefined) {
-                results.details.push({
-                    question,
-                    status: '✗ WRONG',
-                    your_answer: given,
-                    correct_answer: correct
-                });
-                results.REVIEW_REQUIRED.push(docReferences[question]);
-            }
-        }
+        const layers = layer === 'all'
+            ? layerRoles.map(buildLayerInfo)
+            : [buildLayerInfo(layer)];
+
+        return {
+            system: 'holographic',
+            layer_count: layerRoles.length,
+            layers,
+            suggested_next_actions: ['set_holographic_layer', 'batch_set_parameters', 'describe_visual_state']
+        };
+    }
 
-        results.percentage = Math.round((results.score / results.max_score) * 100);
+    /**
+     * Set properties on an individual holographic layer.
+     * Stores overrides in a layer override map and applies them to the visualizer.
+     */
+    setHolographicLayer(args) {
+        const { layer, opacity, blendMode, enabled, colorShift, densityMult, speedMult, reactivity } = args;
 
-        // Build response
-        if (results.REVIEW_REQUIRED.length > 0) {
-            results.MESSAGE = `Score: ${results.score}/${results.max_score}. YOU MAY PROCEED but PLEASE review the topics below to avoid errors.`;
-            results.URGENT = results.REVIEW_REQUIRED.map(ref => ({
-                TOPIC: ref.topic,
-                READ: ref.doc,
-                WHY: ref.reason
-            }));
-        } else {
-            results.MESSAGE = `PERFECT SCORE! You understand the VIB3+ SDK architecture.`;
+        const systemName = this.engine?.currentSystemName || 'unknown';
+        if (systemName !== 'holographic') {
+            return {
+                error: {
+                    type: 'SystemError',
+                    code: 'NOT_HOLOGRAPHIC',
+                    message: `set_holographic_layer requires holographic system (current: ${systemName})`,
+                    suggestion: 'Call switch_system("holographic") first'
+                }
+            };
         }
 
-        results.suggested_next_actions = ['create_4d_visualization', 'get_state', 'search_geometries'];
+        // Initialize layer override storage
+        if (!this._layerOverrides) this._layerOverrides = new Map();
+        const existing = this._layerOverrides.get(layer) || {};
+        const updates = {};
+
+        if (opacity !== undefined) { existing.opacity = opacity; updates.opacity = opacity; }
+        if (blendMode !== undefined) { existing.blendMode = blendMode; updates.blendMode = blendMode; }
+        if (enabled !== undefined) { existing.enabled = enabled; updates.enabled = enabled; }
+        if (colorShift !== undefined) { existing.colorShift = colorShift; updates.colorShift = colorShift; }
+        if (densityMult !== undefined) { existing.densityMult = densityMult; updates.densityMult = densityMult; }
+        if (speedMult !== undefined) { existing.speedMult = speedMult; updates.speedMult = speedMult; }
+        if (reactivity !== undefined) { existing.reactivity = reactivity; updates.reactivity = reactivity; }
+
+        this._layerOverrides.set(layer, existing);
+
+        // Apply to visualizer if available
+        const system = this.engine?.currentSystem;
+        const visualizer = system?.visualizers?.find?.(v => v?.role === layer);
+        if (visualizer) {
+            if (opacity !== undefined && visualizer.canvas) {
+                visualizer.canvas.style.opacity = String(opacity);
+            }
+            if (blendMode !== undefined && visualizer.canvas) {
+                visualizer.canvas.style.mixBlendMode = blendMode;
+            }
+            if (enabled !== undefined && visualizer.canvas) {
+                visualizer.canvas.style.display = enabled ? '' : 'none';
+            }
+            if (colorShift !== undefined && visualizer.roleParams) {
+                visualizer.roleParams.colorShift = colorShift;
+            }
+            if (densityMult !== undefined && visualizer.roleParams) {
+                visualizer.roleParams.densityMult = densityMult;
+            }
+            if (speedMult !== undefined && visualizer.roleParams) {
+                visualizer.roleParams.speedMult = speedMult;
+            }
+            if (reactivity !== undefined) {
+                visualizer.reactivity = reactivity;
+            }
+        }
 
-        return results;
+        return {
+            layer,
+            applied: updates,
+            current_state: this.inspectLayers({ layer }).layers[0],
+            suggested_next_actions: ['inspect_layers', 'set_holographic_layer', 'describe_visual_state']
+        };
     }
 
     /**
@@ -1200,8 +1344,17 @@ export class MCPServer {
             (sum, step) => sum + step.duration + step.delay, 0
         );
 
+        // Execute live if engine available
+        let executing = false;
+        const animator = this._getTransitionAnimator();
+        if (animator) {
+            const seqId = animator.sequence(normalizedSequence);
+            executing = !!seqId;
+        }
+
         return {
             transition_id: transitionId,
+            executing,
             step_count: normalizedSequence.length,
             total_duration_ms: totalDuration,
             steps: normalizedSequence.map((step, i) => ({
@@ -1211,7 +1364,7 @@ export class MCPServer {
                 easing: step.easing,
                 delay: step.delay
             })),
-            load_code: `const animator = new TransitionAnimator(\n  (n, v) => engine.setParameter(n, v),\n  (n) => engine.getParameter(n)\n);\nanimator.sequence(${JSON.stringify(normalizedSequence)});`,
+            load_code: executing ? null : `const animator = new TransitionAnimator(\n  (n, v) => engine.setParameter(n, v),\n  (n) => engine.getParameter(n)\n);\nanimator.sequence(${JSON.stringify(normalizedSequence)});`,
             suggested_next_actions: ['describe_visual_state', 'create_timeline', 'save_to_gallery']
         };
     }
@@ -1220,55 +1373,41 @@ export class MCPServer {
      * Apply a named color preset
      */
     applyColorPreset(args) {
-        const { preset } = args;
+        const { preset, transition = true, duration = 800 } = args;
 
-        // Color preset hue/saturation mappings (subset — full list in ColorPresetsSystem)
-        const COLOR_PRESETS = {
-            Ocean: { hue: 200, saturation: 0.8, intensity: 0.6 },
-            Lava: { hue: 15, saturation: 0.9, intensity: 0.8 },
-            Neon: { hue: 300, saturation: 1.0, intensity: 0.9 },
-            Monochrome: { hue: 0, saturation: 0.0, intensity: 0.6 },
-            Sunset: { hue: 30, saturation: 0.85, intensity: 0.7 },
-            Aurora: { hue: 140, saturation: 0.7, intensity: 0.6 },
-            Cyberpunk: { hue: 280, saturation: 0.9, intensity: 0.8 },
-            Forest: { hue: 120, saturation: 0.6, intensity: 0.5 },
-            Desert: { hue: 40, saturation: 0.5, intensity: 0.7 },
-            Galaxy: { hue: 260, saturation: 0.8, intensity: 0.4 },
-            Ice: { hue: 190, saturation: 0.5, intensity: 0.8 },
-            Fire: { hue: 10, saturation: 1.0, intensity: 0.9 },
-            Toxic: { hue: 100, saturation: 0.9, intensity: 0.7 },
-            Royal: { hue: 270, saturation: 0.7, intensity: 0.5 },
-            Pastel: { hue: 330, saturation: 0.3, intensity: 0.8 },
-            Retro: { hue: 50, saturation: 0.7, intensity: 0.6 },
-            Midnight: { hue: 240, saturation: 0.6, intensity: 0.3 },
-            Tropical: { hue: 160, saturation: 0.8, intensity: 0.7 },
-            Ethereal: { hue: 220, saturation: 0.4, intensity: 0.7 },
-            Volcanic: { hue: 5, saturation: 0.95, intensity: 0.6 },
-            Holographic: { hue: 180, saturation: 0.6, intensity: 0.8 },
-            Vaporwave: { hue: 310, saturation: 0.7, intensity: 0.7 }
-        };
+        const colorSystem = this._getColorPresets();
+
+        if (colorSystem) {
+            // Use real ColorPresetsSystem — full preset library with transitions
+            const config = colorSystem.getPreset(preset);
+            if (!config) {
+                const allPresets = colorSystem.getPresets().map(p => p.name);
+                return {
+                    error: {
+                        type: 'ValidationError',
+                        code: 'INVALID_COLOR_PRESET',
+                        message: `Unknown color preset: ${preset}`,
+                        valid_options: allPresets
+                    }
+                };
+            }
+
+            colorSystem.applyPreset(preset, transition, duration);
 
-        const presetData = COLOR_PRESETS[preset];
-        if (!presetData) {
             return {
-                error: {
-                    type: 'ValidationError',
-                    code: 'INVALID_COLOR_PRESET',
-                    message: `Unknown color preset: ${preset}`,
-                    valid_options: Object.keys(COLOR_PRESETS)
-                }
+                preset,
+                applied: { hue: config.hue, saturation: config.saturation, intensity: config.intensity },
+                transition: transition ? { enabled: true, duration } : { enabled: false },
+                full_config: config,
+                suggested_next_actions: ['set_post_processing', 'describe_visual_state', 'set_visual_parameters']
             };
         }
 
-        if (this.engine) {
-            this.engine.setParameter('hue', presetData.hue);
-            this.engine.setParameter('saturation', presetData.saturation);
-            this.engine.setParameter('intensity', presetData.intensity);
-        }
-
+        // Fallback: no engine, return preset metadata for artifact mode
         return {
             preset,
-            applied: presetData,
+            applied: null,
+            load_code: `const colors = new ColorPresetsSystem((n, v) => engine.setParameter(n, v));\ncolors.applyPreset('${preset}', ${transition}, ${duration});`,
             suggested_next_actions: ['set_post_processing', 'describe_visual_state', 'set_visual_parameters']
         };
     }
@@ -1279,14 +1418,50 @@ export class MCPServer {
     setPostProcessing(args) {
         const { effects, chain_preset, clear_first = true } = args;
 
+        // Try to execute live in browser context
+        let executing = false;
+        if (typeof document !== 'undefined') {
+            try {
+                const target = document.getElementById('viz-container')
+                    || document.querySelector('.vib3-container')
+                    || document.querySelector('canvas')?.parentElement;
+
+                if (target) {
+                    // Lazy-init pipeline, importing dynamically to avoid Node.js issues
+                    if (!this._postPipeline) {
+                        // PostProcessingPipeline imported statically would fail in Node;
+                        // it's already a known browser-only module, so guard at runtime
+                        const { PostProcessingPipeline: PPP } = { PostProcessingPipeline: globalThis.PostProcessingPipeline };
+                        if (PPP) {
+                            this._postPipeline = new PPP(target);
+                        }
+                    }
+
+                    if (this._postPipeline) {
+                        if (clear_first) this._postPipeline.clearChain?.();
+                        if (chain_preset) {
+                            this._postPipeline.loadPresetChain(chain_preset);
+                        } else if (effects) {
+                            for (const e of effects) {
+                                this._postPipeline.addEffect(e.name, { intensity: e.intensity || 0.5, ...e });
+                            }
+                        }
+                        this._postPipeline.apply();
+                        executing = true;
+                    }
+                }
+            } catch { /* fall through to code generation */ }
+        }
+
         return {
             applied: true,
+            executing,
             effects: effects || [],
             chain_preset: chain_preset || null,
             cleared_previous: clear_first,
-            load_code: effects ?
-                `const pipeline = new PostProcessingPipeline(gl, canvas);\n${effects.map(e => `pipeline.addEffect('${e.name}', { intensity: ${e.intensity || 0.5} });`).join('\n')}` :
-                `pipeline.applyChain('${chain_preset}');`,
+            load_code: executing ? null : (effects ?
+                `const pipeline = new PostProcessingPipeline(document.getElementById('viz-container'));\n${effects.map(e => `pipeline.addEffect('${e.name}', { intensity: ${e.intensity || 0.5} });`).join('\n')}\npipeline.apply();` :
+                `const pipeline = new PostProcessingPipeline(document.getElementById('viz-container'));\npipeline.loadPresetChain('${chain_preset}');\npipeline.apply();`),
             suggested_next_actions: ['describe_visual_state', 'apply_color_preset', 'create_choreography']
         };
     }
@@ -1665,6 +1840,185 @@ export class MCPServer {
             suggested_next_actions: ['control_timeline', 'describe_visual_state', 'capture_screenshot']
         };
     }
+
+    // ====================================================================
+    // Layer Relationship Tools (Phase 8)
+    // ====================================================================
+
+    /**
+     * Get the holographic system's layer graph (if available).
+     * @private
+     * @returns {import('../../render/LayerRelationshipGraph.js').LayerRelationshipGraph|null}
+     */
+    _getLayerGraph() {
+        if (!this.engine) return null;
+        // Try to access the current system's layer graph
+        const system = this.engine.currentSystem || this.engine._activeSystem;
+        if (system && system.layerGraph) {
+            return system.layerGraph;
+        }
+        if (system && system._layerGraph) {
+            return system._layerGraph;
+        }
+        return null;
+    }
+
+    /**
+     * Load a named layer relationship profile.
+     */
+    setLayerProfile(args) {
+        const { profile } = args;
+        const graph = this._getLayerGraph();
+
+        if (!graph) {
+            return {
+                error: 'Layer relationship graph not available. Switch to holographic system first.',
+                suggested_next_actions: ['switch_system']
+            };
+        }
+
+        graph.loadProfile(profile);
+        telemetry.recordEvent(EventType.PARAMETER_CHANGE, { type: 'layer_profile', profile });
+
+        return {
+            profile,
+            keystone: graph.keystone,
+            active_profile: graph.activeProfile,
+            available_profiles: ['holographic', 'symmetry', 'chord', 'storm', 'legacy'],
+            suggested_next_actions: ['get_layer_config', 'set_layer_relationship', 'tune_layer_relationship']
+        };
+    }
+
+    /**
+     * Set relationship for a specific layer.
+     */
+    setLayerRelationship(args) {
+        const { layer, relationship, config } = args;
+        const graph = this._getLayerGraph();
+
+        if (!graph) {
+            return {
+                error: 'Layer relationship graph not available. Switch to holographic system first.',
+                suggested_next_actions: ['switch_system']
+            };
+        }
+
+        if (config) {
+            graph.setRelationship(layer, { preset: relationship, config });
+        } else {
+            graph.setRelationship(layer, relationship);
+        }
+
+        telemetry.recordEvent(EventType.PARAMETER_CHANGE, {
+            type: 'layer_relationship', layer, relationship
+        });
+
+        return {
+            layer,
+            relationship,
+            config: config || {},
+            keystone: graph.keystone,
+            suggested_next_actions: ['get_layer_config', 'tune_layer_relationship', 'describe_visual_state']
+        };
+    }
+
+    /**
+     * Change the keystone (driver) layer.
+     */
+    setLayerKeystone(args) {
+        const { layer } = args;
+        const graph = this._getLayerGraph();
+
+        if (!graph) {
+            return {
+                error: 'Layer relationship graph not available. Switch to holographic system first.',
+                suggested_next_actions: ['switch_system']
+            };
+        }
+
+        graph.setKeystone(layer);
+        telemetry.recordEvent(EventType.PARAMETER_CHANGE, { type: 'layer_keystone', layer });
+
+        return {
+            keystone: layer,
+            note: 'Other layers\' relationships are preserved. Set new relationships for the old keystone if needed.',
+            suggested_next_actions: ['set_layer_relationship', 'get_layer_config']
+        };
+    }
+
+    /**
+     * Get current layer configuration.
+     */
+    getLayerConfig() {
+        const graph = this._getLayerGraph();
+
+        if (!graph) {
+            return {
+                error: 'Layer relationship graph not available. Switch to holographic system first.',
+                suggested_next_actions: ['switch_system']
+            };
+        }
+
+        const config = graph.exportConfig();
+
+        return {
+            keystone: config.keystone,
+            active_profile: config.profile,
+            relationships: config.relationships,
+            shaders: config.shaders,
+            available_profiles: ['holographic', 'symmetry', 'chord', 'storm', 'legacy'],
+            available_presets: ['echo', 'mirror', 'complement', 'harmonic', 'reactive', 'chase'],
+            suggested_next_actions: ['set_layer_profile', 'set_layer_relationship', 'tune_layer_relationship']
+        };
+    }
+
+    /**
+     * Tune a layer's relationship config.
+     */
+    tuneLayerRelationship(args) {
+        const { layer, config: configOverrides } = args;
+        const graph = this._getLayerGraph();
+
+        if (!graph) {
+            return {
+                error: 'Layer relationship graph not available. Switch to holographic system first.',
+                suggested_next_actions: ['switch_system']
+            };
+        }
+
+        const graphConfig = graph.exportConfig();
+        const currentRel = graphConfig.relationships[layer];
+
+        if (!currentRel || !currentRel.preset) {
+            return {
+                error: `Layer "${layer}" has no tunable preset relationship. Set one first with set_layer_relationship.`,
+                suggested_next_actions: ['set_layer_relationship']
+            };
+        }
+
+        const factory = PRESET_REGISTRY[currentRel.preset];
+        if (!factory) {
+            return {
+                error: `Unknown preset "${currentRel.preset}" on layer "${layer}".`,
+                suggested_next_actions: ['set_layer_relationship']
+            };
+        }
+
+        const newConfig = { ...(currentRel.config || {}), ...configOverrides };
+        graph.setRelationship(layer, { preset: currentRel.preset, config: newConfig });
+
+        telemetry.recordEvent(EventType.PARAMETER_CHANGE, {
+            type: 'layer_tune', layer, tuned_keys: Object.keys(configOverrides)
+        });
+
+        return {
+            layer,
+            preset: currentRel.preset,
+            previous_config: currentRel.config,
+            new_config: newConfig,
+            suggested_next_actions: ['get_layer_config', 'describe_visual_state', 'capture_screenshot']
+        };
+    }
 }
 
 // Singleton instance