@vib3code/sdk 2.0.3-canary.6f35b4c → 2.0.3-canary.75a3290

package/DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-15.md

@@ -0,0 +1,142 @@
+# Development Session — 2026-02-15
+
+**Session type**: Layer Architecture Redesign, Codebase Audit, Preset/Reactivity Expansion
+**Branch**: `claude/vib3-sdk-handoff-p00R8`
+**Operator**: Claude Code (Opus 4.6)
+**Parent work**: Builds on Feb 13 agent harness + Feb 6 RendererContract work
+
+---
+
+## Session Overview
+
+### Phase 1 — Layer Architecture Redesign
+
+The original 5-layer canvas system used static multipliers — every layer received identical parameters scaled by hardcoded opacity/density/speed factors. This produced "the same shader pasted 5 times with different opacity" instead of actual inter-layer dynamics.
+
+**Built**: `LayerRelationshipGraph` — a keystone-driven system where one layer drives and others derive their parameters through configurable relationship functions.
+
+6 preset relationship types:
+| Preset | Behavior |
+|--------|----------|
+| `echo` | Attenuated follower (same params, scaled down) |
+| `mirror` | Inverts rotation planes, shifts hue 180° |
+| `complement` | Color complement, density inverted around pivot |
+| `harmonic` | Density at integer multiples, hue at golden angle intervals |
+| `reactive` | Amplifies parameter deltas over time |
+| `chase` | Lerps toward keystone with configurable delay |
+
+5 named profiles that configure the full 5-layer graph:
+- `holographic` — content drives, echo/complement/harmonic/reactive
+- `symmetry` — mirror mode with chase accent
+- `chord` — all harmonic at musical intervals
+- `storm` — all reactive with increasing gain
+- `legacy` — replicates old static multiplier behavior exactly
+
+### Phase 2 — TypeScript Type Audit
+
+Found and fixed 4 type definition issues:
+1. Export name mismatch (RELATIONSHIP_PRESETS → PRESET_REGISTRY)
+2. Missing MultiCanvasBridge type definition
+3. Broken barrel file (types/render/index.d.ts)
+4. Incorrect exports in types/adaptive-sdk.d.ts
+
+### Phase 3 — Comprehensive Codebase Audit
+
+Found and fixed 7 critical issues across the SDK:
+
+| File | Problem | Fix |
+|------|---------|-----|
+| `src/math/index.js` | Top-level `await import()` breaks bundlers | Static imports |
+| `src/render/index.js` | `require()` in ESM package | Static ESM import |
+| `src/scene/index.js` | `require()` in `createSceneContext()` | Use already-imported classes |
+| `src/export/index.js` | 8 missing exports | Added ShaderExporter, VIB3PackageExporter, etc. |
+| `src/reactivity/index.js` | `console.log()` side effect in barrel | Removed |
+| `package.json` | Missing `./creative`, `./export`, `./variations` entry points | Added |
+| `types/` | Mismatched export names, missing barrel re-exports | Fixed all |
+
+### Phase 4 — CLAUDE.md Rewrite
+
+Rewrote CLAUDE.md from 224 → 366 lines:
+- Fixed MCP tool count (12 → 31) with full categorized table
+- Added LayerRelationshipGraph documentation
+- Added all new file references
+- Added recent session work section
+- Added 4 new gotchas (ESM only, 31 tools, layer defaults, initialize check)
+- Updated test count, status, documentation map with staleness notes
+
+### Phase 5 — LayerPresetManager + Reactivity Wiring + MCP Tools
+
+Built the preset management and reactivity-driven layer modulation system:
+
+**LayerPresetManager** (`src/render/LayerPresetManager.js`):
+- Save/load/delete/list user presets
+- Create presets from current graph state
+- Tune individual relationship parameters at runtime
+- Persist presets to localStorage
+- Import/export preset libraries as JSON
+
+**Reactivity-driven layer modulation** (`src/render/LayerReactivityBridge.js`):
+- Audio frequency bands modulate relationship parameters (e.g., bass → reactive gain)
+- Device tilt/gyroscope modulates relationship configs
+- Configurable modulation mappings per input source
+- Pre-built modulation profiles (audioStorm, tiltHarmonic, etc.)
+
+**MCP tools** (5 new layer control tools):
+- `set_layer_profile` — Load a named layer profile
+- `set_layer_relationship` — Set relationship for a specific layer
+- `set_layer_keystone` — Change the keystone layer
+- `get_layer_config` — Get current layer configuration
+- `tune_layer_relationship` — Adjust config on an active relationship
+
+---
+
+## Files Created
+
+| File | Purpose | ~Lines |
+|------|---------|--------|
+| `src/render/LayerRelationshipGraph.js` | Keystone-driven inter-layer parameter system | 610 |
+| `src/render/LayerPresetManager.js` | Preset save/load/tune for layer relationships | ~300 |
+| `src/render/LayerReactivityBridge.js` | Audio/tilt/input → layer relationship modulation | ~280 |
+| `types/render/LayerRelationshipGraph.d.ts` | Full TypeScript definitions | 120 |
+| `types/render/LayerPresetManager.d.ts` | TypeScript definitions for preset manager | ~60 |
+| `types/render/LayerReactivityBridge.d.ts` | TypeScript definitions for reactivity bridge | ~70 |
+| `tests/render/LayerRelationshipGraph.test.js` | 63 tests for relationship graph | 450 |
+| `tests/render/LayerPresetManager.test.js` | Tests for preset manager | ~200 |
+| `tests/render/LayerReactivityBridge.test.js` | Tests for reactivity bridge | ~200 |
+| `pages/layer-demo.html` | Visual demo for testing layer dynamics | ~300 |
+| `DOCS/dev-tracks/DEV_TRACK_SESSION_2026-02-15.md` | This file | — |
+
+## Files Modified
+
+| File | Change |
+|------|--------|
+| `src/render/MultiCanvasBridge.js` | Integrated LayerRelationshipGraph for per-layer parameter resolution |
+| `src/holograms/RealHolographicSystem.js` | Added layer graph integration, `loadRelationshipProfile()`, `setKeystone()`, `setLayerRelationship()` |
+| `src/render/index.js` | Fixed `require()` → ESM, added LayerRelationshipGraph + PresetManager + ReactivityBridge exports |
+| `src/math/index.js` | Fixed top-level `await import()` → static imports |
+| `src/scene/index.js` | Fixed `require()` → use imported classes |
+| `src/export/index.js` | Added 8 missing exports |
+| `src/reactivity/index.js` | Removed `console.log()` side effect |
+| `src/agent/mcp/tools.js` | Added 5 layer control tool definitions |
+| `src/agent/mcp/MCPServer.js` | Added 5 layer control handlers |
+| `package.json` | Added `./creative`, `./export`, `./variations` entry points |
+| `types/adaptive-sdk.d.ts` | Fixed export names, added layer system re-exports |
+| `types/render/index.d.ts` | Added LayerRelationshipGraph, PresetManager, ReactivityBridge re-exports |
+| `types/systems/index.d.ts` | Added layer relationship API to RealHolographicSystem |
+| `CLAUDE.md` | Comprehensive rewrite (224 → 366 lines) |
+
+## Test Results
+
+- **Before session**: 1430 tests, 70 files
+- **After session**: 1702+ tests, 75+ files
+- All passing
+
+## Commits
+
+| Hash | Message |
+|------|---------|
+| `59fb951` | feat(render): add LayerRelationshipGraph — keystone-driven inter-layer parameter system |
+| `bec4cad` | fix(types): correct export names and barrel re-exports for LayerRelationshipGraph |
+| `aeac38c` | fix: resolve 7 broken barrel files, require() in ESM, missing exports |
+| `4031700` | docs: comprehensive CLAUDE.md rewrite |
+| (pending) | feat: LayerPresetManager, LayerReactivityBridge, MCP layer tools, demo page |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib3code/sdk",
-  "version": "2.0.3-canary.6f35b4c",
+  "version": "2.0.3-canary.75a3290",
   "description": "VIB3+ 4D Visualization SDK - Unified engine with 6D rotation, MCP agentic integration, and cross-platform support",
   "type": "module",
   "main": "src/core/VIB3Engine.js",
@@ -200,6 +200,9 @@
     "./reactivity/config": {
       "import": "./src/reactivity/ReactivityConfig.js"
     },
+    "./creative": {
+      "import": "./src/creative/index.js"
+    },
     "./creative/color-presets": {
       "import": "./src/creative/ColorPresetsSystem.js"
     },
@@ -212,6 +215,9 @@
     "./creative/timeline": {
       "import": "./src/creative/ParameterTimeline.js"
     },
+    "./export": {
+      "import": "./src/export/index.js"
+    },
     "./integrations/react": {
       "import": "./src/integrations/frameworks/Vib3React.js"
     },
@@ -248,6 +254,9 @@
     "./advanced/offscreen": {
       "import": "./src/advanced/OffscreenWorker.js"
     },
+    "./variations": {
+      "import": "./src/variations/VariationManager.js"
+    },
     "./tools/shader-sync": {
       "import": "./tools/shader-sync-verify.js"
     },

package/src/agent/index.js

@@ -68,6 +68,4 @@ export {
     createStreamingCLI
 } from './cli/index.js';
 
-// Default exports
-export { telemetry } from './telemetry/index.js';
-export { mcpServer } from './mcp/index.js';
+// telemetry and mcpServer already exported above

package/src/agent/mcp/MCPServer.js

@@ -9,6 +9,7 @@ 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 { PRESET_REGISTRY } from '../../render/LayerRelationshipGraph.js';
 
 /**
  * Generate unique IDs
@@ -204,6 +205,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}`);
             }
@@ -1665,6 +1682,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

package/src/agent/mcp/index.js

@@ -6,4 +6,4 @@
 export { MCPServer, mcpServer } from './MCPServer.js';
 export { toolDefinitions, getToolList, getToolNames, getTool, validateToolInput } from './tools.js';
 
-export default mcpServer from './MCPServer.js';
+export { mcpServer as default } from './MCPServer.js';

package/src/agent/mcp/tools.js

@@ -762,6 +762,93 @@ export const toolDefinitions = {
             },
             required: ['timeline_id', 'action']
         }
+    },
+
+    // Layer Relationship Tools (Phase 8)
+    set_layer_profile: {
+        name: 'set_layer_profile',
+        description: 'Loads a named layer relationship profile that configures how the 5 canvas layers relate to each other. Profiles: holographic (default), symmetry, chord, storm, legacy (original static behavior).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                profile: {
+                    type: 'string',
+                    enum: ['holographic', 'symmetry', 'chord', 'storm', 'legacy'],
+                    description: 'Named profile to load'
+                }
+            },
+            required: ['profile']
+        }
+    },
+
+    set_layer_relationship: {
+        name: 'set_layer_relationship',
+        description: 'Sets the relationship type for a specific layer relative to the keystone. Available relationships: echo (attenuated follower), mirror (inverted rotation/hue), complement (color opposite), harmonic (musical intervals), reactive (amplifies changes), chase (delayed follower).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layer: {
+                    type: 'string',
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent'],
+                    description: 'Target layer name'
+                },
+                relationship: {
+                    type: 'string',
+                    enum: ['echo', 'mirror', 'complement', 'harmonic', 'reactive', 'chase'],
+                    description: 'Relationship preset name'
+                },
+                config: {
+                    type: 'object',
+                    description: 'Optional config overrides for the relationship (e.g., { opacity: 0.5, gain: 3 })'
+                }
+            },
+            required: ['layer', 'relationship']
+        }
+    },
+
+    set_layer_keystone: {
+        name: 'set_layer_keystone',
+        description: 'Changes which layer acts as the keystone (driver) for the layer relationship graph. Other layers derive their parameters from the keystone through relationship functions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layer: {
+                    type: 'string',
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent'],
+                    description: 'Layer to designate as keystone'
+                }
+            },
+            required: ['layer']
+        }
+    },
+
+    get_layer_config: {
+        name: 'get_layer_config',
+        description: 'Returns the current layer relationship configuration including keystone, profile, and per-layer relationships with their config parameters.',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    },
+
+    tune_layer_relationship: {
+        name: 'tune_layer_relationship',
+        description: 'Hot-patches a layer relationship config without replacing the full graph. Merges provided config values into the existing relationship (e.g., increase reactive gain, shift harmonic hue angle).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layer: {
+                    type: 'string',
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent'],
+                    description: 'Layer to tune'
+                },
+                config: {
+                    type: 'object',
+                    description: 'Config values to merge (e.g., { opacity: 0.6, gain: 3.0, hueAngle: 120 })'
+                }
+            },
+            required: ['layer', 'config']
+        }
     }
 };