@vib3code/sdk 2.0.3-canary.60bc0f0 → 2.0.3-canary.74aebb4

package/src/agent/mcp/MCPServer.js

@@ -173,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':
@@ -650,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)];
 
-        results.percentage = Math.round((results.score / results.max_score) * 100);
+        return {
+            system: 'holographic',
+            layer_count: layerRoles.length,
+            layers,
+            suggested_next_actions: ['set_holographic_layer', 'batch_set_parameters', 'describe_visual_state']
+        };
+    }
 
-        // 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.`;
+    /**
+     * 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;
+
+        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']
+        };
     }
 
     /**

package/src/agent/mcp/tools.js

@@ -222,51 +222,64 @@ export const toolDefinitions = {
     // Onboarding Tools
     get_sdk_context: {
         name: 'get_sdk_context',
-        description: 'Returns essential SDK context for agent onboarding. Call this first to understand the system.',
+        description: 'Returns a compact capability manifest: what systems exist, what tools are available, what parameter ranges are valid, and what the current engine state is. Designed for injection into agent context — call once at session start, not repeatedly.',
         inputSchema: {
             type: 'object',
-            properties: {}
+            properties: {
+                include_state: {
+                    type: 'boolean',
+                    default: true,
+                    description: 'Include current engine state in response'
+                },
+                include_tools: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Include tool summary list (names + one-line descriptions)'
+                }
+            }
         }
     },
 
-    verify_knowledge: {
-        name: 'verify_knowledge',
-        description: 'Verifies agent has absorbed SDK context. Multiple choice quiz - submit letter answers (a/b/c/d).',
+    inspect_layers: {
+        name: 'inspect_layers',
+        description: 'Returns the current state of all holographic canvas layers with per-layer metadata: role, opacity, blend mode, reactivity multiplier, role-specific parameters, and enabled state. Only meaningful when holographic system is active.',
         inputSchema: {
             type: 'object',
             properties: {
-                q1_rotation_planes: {
-                    type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q1: How many rotation planes? a)3 b)4 c)6 d)8'
-                },
-                q2_geometry_formula: {
-                    type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q2: Geometry encoding formula? a)base*3+core b)core*8+base c)base+core d)core*base'
-                },
-                q3_canvas_layers: {
+                layer: {
                     type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q3: Canvas layers per system? a)3 b)4 c)5 d)6'
-                },
-                q4_active_systems: {
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent', 'all'],
+                    default: 'all',
+                    description: 'Inspect a specific layer or all layers'
+                }
+            }
+        }
+    },
+
+    set_holographic_layer: {
+        name: 'set_holographic_layer',
+        description: 'Controls individual holographic layer properties. Set opacity, blend mode, enable/disable, or override role parameters for any of the 5 layers (background, shadow, content, highlight, accent). Only works when holographic system is active.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layer: {
                     type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q4: Which are the 3 ACTIVE systems? a)quantum,faceted,holographic b)quantum,faceted,polychora c)faceted,holographic,polychora d)all four'
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent'],
+                    description: 'Target layer role name'
                 },
-                q5_base_geometries: {
+                opacity: { type: 'number', minimum: 0, maximum: 1, description: 'Layer opacity (0=invisible, 1=full)' },
+                blendMode: {
                     type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q5: How many base geometry types? a)6 b)8 c)10 d)24'
+                    enum: ['normal', 'screen', 'multiply', 'add', 'overlay'],
+                    description: 'CSS blend mode for this layer'
                 },
-                q6_core_types: {
-                    type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q6: Core warp types? a)base,sphere,cube b)base,hypersphere,hypertetrahedron c)none,partial,full d)2D,3D,4D'
-                }
+                enabled: { type: 'boolean', description: 'Show/hide this layer' },
+                colorShift: { type: 'number', minimum: 0, maximum: 360, description: 'Hue offset for this layer' },
+                densityMult: { type: 'number', minimum: 0.1, maximum: 5, description: 'Grid density multiplier' },
+                speedMult: { type: 'number', minimum: 0, maximum: 3, description: 'Animation speed multiplier' },
+                reactivity: { type: 'number', minimum: 0, maximum: 3, description: 'Mouse/touch reactivity multiplier' }
             },
-            required: ['q1_rotation_planes', 'q2_geometry_formula', 'q3_canvas_layers']
+            required: ['layer']
         }
     },
 
@@ -651,7 +664,7 @@ export const toolDefinitions = {
 
     capture_screenshot: {
         name: 'capture_screenshot',
-        description: 'Captures the current visualization as a base64-encoded PNG image by compositing all 5 canvas layers. Only works in browser context. Returns image data that multimodal agents can analyze for visual feedback.',
+        description: 'Captures current visualization as a base64-encoded PNG by compositing canvas layers. BROWSER-ONLY: returns an EnvironmentError with capability report in headless/Node contexts. When available, returns data_url for multimodal analysis. Use describe_visual_state as a text-based alternative in non-browser environments.',
         inputSchema: {
             type: 'object',
             properties: {

package/src/experimental/GameLoop.js

@@ -0,0 +1,72 @@
+/**
+ * GameLoop - Fixed-Timestep Physics Loop
+ *
+ * Provides a robust game loop that decouples physics updates (fixed step)
+ * from rendering (variable step). This is crucial for consistent physics
+ * and smooth rendering across different device capabilities.
+ *
+ * @experimental
+ */
+export class GameLoop {
+    /**
+     * @param {function(number)} updateFn - Physics update (fixed dt)
+     * @param {function(number)} renderFn - Render update (interpolated alpha)
+     * @param {number} step - Physics step size in seconds (default 1/60)
+     */
+    constructor(updateFn, renderFn, step = 1 / 60) {
+        this.updateFn = updateFn;
+        this.renderFn = renderFn;
+        this.step = step;
+        this.dt = 0;
+        this.last = 0;
+        this.now = 0;
+        this.accumulator = 0;
+        this.running = false;
+        this.rafId = null;
+
+        // Bind loop
+        this.frame = this.frame.bind(this);
+    }
+
+    start() {
+        if (this.running) return;
+        this.running = true;
+        this.last = performance.now();
+        this.accumulator = 0;
+        this.rafId = requestAnimationFrame(this.frame);
+        console.log('GameLoop: Started.');
+    }
+
+    stop() {
+        this.running = false;
+        if (this.rafId) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
+        console.log('GameLoop: Stopped.');
+    }
+
+    frame(timestamp) {
+        if (!this.running) return;
+
+        this.now = timestamp;
+        // Cap dt to avoid "spiral of death" on lag spikes (max 1s)
+        this.dt = Math.min(1, (this.now - this.last) / 1000);
+        this.last = this.now;
+
+        this.accumulator += this.dt;
+
+        // Consume accumulator in fixed steps
+        while (this.accumulator >= this.step) {
+            this.updateFn(this.step);
+            this.accumulator -= this.step;
+        }
+
+        // Render with interpolation factor alpha
+        // alpha = accumulator / step
+        // Allows renderer to interpolate between previous and current physics state
+        this.renderFn(this.accumulator / this.step);
+
+        this.rafId = requestAnimationFrame(this.frame);
+    }
+}

package/src/experimental/LatticePhysics.js

@@ -0,0 +1,100 @@
+/**
+ * LatticePhysics - Function-Based Collision Detection
+ *
+ * Provides a physics engine for "Lattice Worlds" where geometry is defined
+ * by mathematical density functions (SDFs, fractals).
+ *
+ * @experimental
+ */
+export class LatticePhysics {
+    constructor() {
+        this.gravity = 9.8; // m/s²
+        this.friction = 0.95; // Velocity decay per step
+        this.densityThreshold = 0.8; // Collision threshold (0-1)
+    }
+
+    /**
+     * Update physics for all entities in the universe.
+     * @param {Map<string, object>} entities
+     * @param {number} dt
+     */
+    update(entities, dt) {
+        entities.forEach(entity => {
+            if (entity.physics && entity.active) {
+                this.updateEntity(entity, dt);
+            }
+        });
+    }
+
+    /**
+     * Update a single entity's physics state.
+     * @param {object} entity
+     * @param {number} dt
+     */
+    updateEntity(entity, dt) {
+        const { pos, vel, acc } = entity.physics;
+
+        // Apply forces (Gravity)
+        // In this abstract world, gravity pulls "down" in Y
+        acc.y -= this.gravity * dt;
+
+        // Integrate Velocity (Euler)
+        vel.x += acc.x * dt;
+        vel.y += acc.y * dt;
+        vel.z += acc.z * dt;
+
+        // Reset acceleration (forces are transient)
+        acc.x = 0; acc.y = 0; acc.z = 0;
+
+        // Collision Check (Projected Position)
+        const nextX = pos.x + vel.x * dt;
+        const nextY = pos.y + vel.y * dt;
+        const nextZ = pos.z + vel.z * dt;
+
+        // Sample density at next position
+        const density = this.getDensityAt(nextX, nextY, nextZ);
+
+        if (density > this.densityThreshold) {
+            // Collision!
+            // Simple response: Stop velocity component and push out
+            // A real engine would calculate surface normal from gradient
+
+            // Simplified: Just stop movement and bounce slightly
+            vel.x *= -0.5;
+            vel.y *= -0.5;
+            vel.z *= -0.5;
+
+            // Don't update position into solid
+        } else {
+            // Move freely
+            pos.x = nextX;
+            pos.y = nextY;
+            pos.z = nextZ;
+        }
+
+        // Apply Friction (Air/Ether drag)
+        vel.x *= this.friction;
+        vel.y *= this.friction;
+        vel.z *= this.friction;
+    }
+
+    /**
+     * Sample the "world density" at a given point.
+     * This mimics the shader's generation logic (e.g., fractal noise).
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {number} Density 0.0 to 1.0
+     */
+    getDensityAt(x, y, z) {
+        // Mock function: simple floor plane at y = -2
+        if (y < -2) return 1.0;
+
+        // Mock function: occasional "floating islands" based on sine waves
+        // simulating the VIB3 lattice structure
+        const noise = (Math.sin(x * 0.5) + Math.cos(z * 0.5)) * 0.5 + 0.5;
+        if (y > 0 && y < 1 && noise > 0.8) return 1.0;
+
+        return 0.0;
+    }
+}