@vib3code/sdk 2.0.1

package/src/schemas/extension.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "extension.schema.json",
+  "title": "VIB3+ Extension Manifest",
+  "description": "Manifest describing VIB3 extensions for partner marketplace distribution.",
+  "type": "object",
+  "properties": {
+    "manifest_version": {
+      "type": "string",
+      "description": "Manifest schema version (semver)."
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9_-]+(\\.[a-z0-9_-]+)*$",
+      "description": "Stable extension identifier."
+    },
+    "name": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string",
+      "description": "Extension version (semver)."
+    },
+    "vendor": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "url": { "type": "string", "format": "uri" },
+        "support_email": { "type": "string", "format": "email" }
+      },
+      "required": ["name"]
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "renderers": { "type": "boolean", "default": false },
+        "geometry": { "type": "boolean", "default": false },
+        "ui": { "type": "boolean", "default": false },
+        "agent_tools": { "type": "boolean", "default": false },
+        "telemetry": { "type": "boolean", "default": false }
+      },
+      "additionalProperties": false
+    },
+    "entrypoints": {
+      "type": "object",
+      "properties": {
+        "runtime": { "type": "string" },
+        "ui": { "type": "string" },
+        "toolpack": { "type": "string" }
+      },
+      "required": ["runtime"],
+      "additionalProperties": false
+    },
+    "compatibility": {
+      "type": "object",
+      "properties": {
+        "core_version": { "type": "string" },
+        "renderer_contract": { "type": "string" },
+        "feature_flags": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "required": ["core_version"]
+    },
+    "marketplace": {
+      "type": "object",
+      "properties": {
+        "title": { "type": "string" },
+        "summary": { "type": "string" },
+        "categories": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "preview_images": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["manifest_version", "id", "name", "version", "vendor", "capabilities", "entrypoints", "compatibility"],
+  "additionalProperties": false
+}

package/src/schemas/index.js

@@ -0,0 +1,214 @@
+/**
+ * VIB3+ Schema Registry
+ * Centralized schema loading with AJV validation
+ *
+ * NOTE: Using dynamic imports with 'with' syntax for Node.js 22+ compatibility.
+ * The 'assert' syntax was deprecated in favor of 'with' in Node.js 22.
+ */
+
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { createRequire } from 'module';
+
+// Use createRequire for JSON imports (works in all Node.js versions)
+const require = createRequire(import.meta.url);
+
+// Import schemas using require (Node.js compatible)
+const parametersSchema = require('./parameters.schema.json');
+const toolResponseSchema = require('./tool-response.schema.json');
+const errorSchema = require('./error.schema.json');
+const extensionSchema = require('./extension.schema.json');
+const toolPackSchema = require('./tool-pack.schema.json');
+
+class SchemaRegistry {
+    constructor() {
+        this.ajv = new Ajv({
+            allErrors: true,
+            verbose: true,
+            strict: false
+        });
+
+        // Add format validators
+        try {
+            addFormats(this.ajv);
+        } catch (e) {
+            // addFormats may not be available in all environments
+            console.warn('ajv-formats not available, some format validations disabled');
+        }
+
+        // Register schemas
+        this.schemas = {
+            parameters: parametersSchema,
+            toolResponse: toolResponseSchema,
+            error: errorSchema,
+            extension: extensionSchema,
+            toolPack: toolPackSchema
+        };
+
+        // Add all schemas to AJV first (required for $ref resolution)
+        // Error schema must be added before tool-response which refs it
+        this.ajv.addSchema(errorSchema, 'error.schema.json');
+        this.ajv.addSchema(parametersSchema, 'parameters.schema.json');
+        this.ajv.addSchema(extensionSchema, 'extension.schema.json');
+        this.ajv.addSchema(toolPackSchema, 'tool-pack.schema.json');
+
+        // Now compile validators (refs will resolve)
+        this.validators = {};
+        try {
+            this.validators.error = this.ajv.compile(errorSchema);
+            this.validators.parameters = this.ajv.compile(parametersSchema);
+            this.validators.extension = this.ajv.compile(extensionSchema);
+            this.validators.toolPack = this.ajv.compile(toolPackSchema);
+            this.validators.toolResponse = this.ajv.compile(toolResponseSchema);
+        } catch (e) {
+            console.error('Schema compilation error:', e.message);
+            // Provide stub validators that always pass (graceful degradation)
+            for (const name of Object.keys(this.schemas)) {
+                if (!this.validators[name]) {
+                    this.validators[name] = () => true;
+                }
+            }
+        }
+    }
+
+    /**
+     * Validate data against a schema
+     * @param {string} schemaName - Name of the schema
+     * @param {object} data - Data to validate
+     * @returns {{ valid: boolean, errors: array|null }}
+     */
+    validate(schemaName, data) {
+        const validator = this.validators[schemaName];
+        if (!validator) {
+            return {
+                valid: false,
+                errors: [{ message: `Unknown schema: ${schemaName}` }]
+            };
+        }
+
+        const valid = validator(data);
+        return {
+            valid,
+            errors: valid ? null : validator.errors
+        };
+    }
+
+    /**
+     * Validate parameters and return normalized structure
+     * @param {object} params - Raw parameters
+     * @returns {{ valid: boolean, normalized: object|null, errors: array|null }}
+     */
+    validateParameters(params) {
+        // Normalize flat parameter format to nested structure
+        const normalized = this.normalizeParameters(params);
+        const result = this.validate('parameters', normalized);
+
+        return {
+            ...result,
+            normalized: result.valid ? normalized : null
+        };
+    }
+
+    /**
+     * Normalize flat parameters to nested schema structure
+     */
+    normalizeParameters(params) {
+        return {
+            system: params.system || 'quantum',
+            variation: params.variation ?? 0,
+            geometry: params.geometry ?? 0,
+            rotation: {
+                XY: params.rot4dXY ?? params.rotation?.XY ?? 0,
+                XZ: params.rot4dXZ ?? params.rotation?.XZ ?? 0,
+                YZ: params.rot4dYZ ?? params.rotation?.YZ ?? 0,
+                XW: params.rot4dXW ?? params.rotation?.XW ?? 0,
+                YW: params.rot4dYW ?? params.rotation?.YW ?? 0,
+                ZW: params.rot4dZW ?? params.rotation?.ZW ?? 0
+            },
+            visual: {
+                dimension: params.dimension ?? params.visual?.dimension ?? 3.5,
+                gridDensity: params.gridDensity ?? params.visual?.gridDensity ?? 15,
+                morphFactor: params.morphFactor ?? params.visual?.morphFactor ?? 1.0,
+                chaos: params.chaos ?? params.visual?.chaos ?? 0.2,
+                speed: params.speed ?? params.visual?.speed ?? 1.0,
+                hue: params.hue ?? params.visual?.hue ?? 200,
+                intensity: params.intensity ?? params.visual?.intensity ?? 0.5,
+                saturation: params.saturation ?? params.visual?.saturation ?? 0.8
+            }
+        };
+    }
+
+    /**
+     * Flatten normalized parameters back to engine format
+     */
+    flattenParameters(normalized) {
+        return {
+            system: normalized.system,
+            variation: normalized.variation,
+            geometry: normalized.geometry,
+            rot4dXY: normalized.rotation.XY,
+            rot4dXZ: normalized.rotation.XZ,
+            rot4dYZ: normalized.rotation.YZ,
+            rot4dXW: normalized.rotation.XW,
+            rot4dYW: normalized.rotation.YW,
+            rot4dZW: normalized.rotation.ZW,
+            dimension: normalized.visual.dimension,
+            gridDensity: normalized.visual.gridDensity,
+            morphFactor: normalized.visual.morphFactor,
+            chaos: normalized.visual.chaos,
+            speed: normalized.visual.speed,
+            hue: normalized.visual.hue,
+            intensity: normalized.visual.intensity,
+            saturation: normalized.visual.saturation
+        };
+    }
+
+    /**
+     * Create an actionable error response
+     */
+    createError(type, code, message, details = {}) {
+        return {
+            error: {
+                type,
+                code,
+                message,
+                ...details,
+                retry_possible: details.retry_possible ?? false
+            }
+        };
+    }
+
+    /**
+     * Create a tool response
+     */
+    createToolResponse(operation, data) {
+        return {
+            success: true,
+            operation,
+            timestamp: new Date().toISOString(),
+            ...data
+        };
+    }
+
+    /**
+     * Get schema for documentation/tooling
+     */
+    getSchema(name) {
+        return this.schemas[name];
+    }
+
+    /**
+     * Get all schemas for MCP tool registration
+     */
+    getAllSchemas() {
+        return { ...this.schemas };
+    }
+}
+
+// Singleton instance
+export const schemaRegistry = new SchemaRegistry();
+
+// Named exports
+export { parametersSchema, toolResponseSchema, errorSchema };
+export { extensionSchema, toolPackSchema };
+export default schemaRegistry;

package/src/schemas/parameters.schema.json

@@ -0,0 +1,142 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "parameters.schema.json",
+  "title": "VIB3+ Parameter Schema",
+  "description": "Complete parameter schema for VIB3+ 4D visualization engine with 6-plane rotation support",
+  "type": "object",
+  "properties": {
+    "system": {
+      "type": "string",
+      "enum": ["quantum", "faceted", "holographic"],
+      "description": "Active visualization system",
+      "default": "quantum"
+    },
+    "variation": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 99,
+      "description": "Variation slot (0-29 default, 30-99 custom)",
+      "default": 0
+    },
+    "geometry": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 23,
+      "description": "Geometry index: 0-7 base, 8-15 hypersphere core, 16-23 hypertetrahedron core",
+      "default": 0
+    },
+    "rotation": {
+      "type": "object",
+      "description": "6D rotation angles in radians",
+      "properties": {
+        "XY": {
+          "type": "number",
+          "minimum": -6.283185307,
+          "maximum": 6.283185307,
+          "description": "X-Y plane rotation (3D space)",
+          "default": 0
+        },
+        "XZ": {
+          "type": "number",
+          "minimum": -6.283185307,
+          "maximum": 6.283185307,
+          "description": "X-Z plane rotation (3D space)",
+          "default": 0
+        },
+        "YZ": {
+          "type": "number",
+          "minimum": -6.283185307,
+          "maximum": 6.283185307,
+          "description": "Y-Z plane rotation (3D space)",
+          "default": 0
+        },
+        "XW": {
+          "type": "number",
+          "minimum": -6.283185307,
+          "maximum": 6.283185307,
+          "description": "X-W plane rotation (4D hyperspace - inside-out effect)",
+          "default": 0
+        },
+        "YW": {
+          "type": "number",
+          "minimum": -6.283185307,
+          "maximum": 6.283185307,
+          "description": "Y-W plane rotation (4D hyperspace)",
+          "default": 0
+        },
+        "ZW": {
+          "type": "number",
+          "minimum": -6.283185307,
+          "maximum": 6.283185307,
+          "description": "Z-W plane rotation (4D hyperspace)",
+          "default": 0
+        }
+      },
+      "additionalProperties": false
+    },
+    "visual": {
+      "type": "object",
+      "description": "Visual rendering parameters",
+      "properties": {
+        "dimension": {
+          "type": "number",
+          "minimum": 3.0,
+          "maximum": 4.5,
+          "description": "Dimensional interpolation level",
+          "default": 3.5
+        },
+        "gridDensity": {
+          "type": "number",
+          "minimum": 4,
+          "maximum": 100,
+          "description": "Geometric detail/grid density",
+          "default": 15
+        },
+        "morphFactor": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2,
+          "description": "Shape transformation factor",
+          "default": 1.0
+        },
+        "chaos": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Randomization/turbulence level",
+          "default": 0.2
+        },
+        "speed": {
+          "type": "number",
+          "minimum": 0.1,
+          "maximum": 3,
+          "description": "Animation speed multiplier",
+          "default": 1.0
+        },
+        "hue": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 360,
+          "description": "Base color hue in degrees",
+          "default": 200
+        },
+        "intensity": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Visual brightness/intensity",
+          "default": 0.5
+        },
+        "saturation": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Color saturation",
+          "default": 0.8
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/src/schemas/tool-pack.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "tool-pack.schema.json",
+  "title": "VIB3+ Tool Pack Manifest",
+  "description": "Tool pack manifest describing grouped MCP tools for partner platforms.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9_-]+(\\.[a-z0-9_-]+)*$"
+    },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "description": { "type": "string" },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "schema_ref": { "type": "string" }
+        },
+        "required": ["name"]
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "marketplace": {
+      "type": "object",
+      "properties": {
+        "listing_id": { "type": "string" },
+        "categories": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["id", "name", "version", "tools"],
+  "additionalProperties": false
+}

package/src/schemas/tool-response.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "tool-response.schema.json",
+  "title": "VIB3+ Tool Response Schema",
+  "description": "Semantically rich response format for agentic API tools",
+  "type": "object",
+  "properties": {
+    "success": {
+      "type": "boolean",
+      "description": "Whether the operation succeeded"
+    },
+    "operation": {
+      "type": "string",
+      "description": "The operation that was performed",
+      "enum": [
+        "create_visualization",
+        "set_parameters",
+        "get_state",
+        "render_preview",
+        "search_geometries",
+        "switch_system",
+        "randomize",
+        "reset",
+        "export_state",
+        "import_state",
+        "create_4d_visualization",
+        "set_rotation",
+        "set_visual_parameters",
+        "change_geometry",
+        "randomize_parameters",
+        "reset_parameters",
+        "save_to_gallery",
+        "load_from_gallery",
+        "get_parameter_schema",
+        "list_tools"
+      ]
+    },
+    "scene_id": {
+      "type": "string",
+      "pattern": "^scene_[a-z0-9]+$",
+      "description": "Unique scene identifier"
+    },
+    "geometry": {
+      "type": "object",
+      "properties": {
+        "index": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 23
+        },
+        "base_type": {
+          "type": "string",
+          "enum": ["tetrahedron", "hypercube", "sphere", "torus", "klein_bottle", "fractal", "wave", "crystal"]
+        },
+        "core_type": {
+          "type": "string",
+          "enum": ["base", "hypersphere", "hypertetrahedron"]
+        },
+        "vertex_count": {
+          "type": "integer",
+          "minimum": 4
+        },
+        "edge_count": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "rotation_state": {
+      "type": "object",
+      "properties": {
+        "XY": { "type": "number" },
+        "XZ": { "type": "number" },
+        "YZ": { "type": "number" },
+        "XW": { "type": "number" },
+        "YW": { "type": "number" },
+        "ZW": { "type": "number" }
+      }
+    },
+    "render_info": {
+      "type": "object",
+      "properties": {
+        "complexity": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "very_high"]
+        },
+        "estimated_fps": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 144
+        },
+        "gpu_memory_mb": {
+          "type": "number",
+          "minimum": 0
+        }
+      }
+    },
+    "suggested_next_actions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Contextually relevant actions the agent might take next"
+    },
+    "error": {
+      "$ref": "error.schema.json"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "duration_ms": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Operation duration in milliseconds"
+    },
+    "validation_errors": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      },
+      "description": "Schema validation errors, if any"
+    }
+  },
+  "required": ["success", "operation"],
+  "additionalProperties": true
+}

package/src/shaders/common/fullscreen.vert.glsl

@@ -0,0 +1,5 @@
+// VIB3+ Fullscreen Quad Vertex Shader (GLSL)
+attribute vec2 a_position;
+void main() {
+    gl_Position = vec4(a_position, 0.0, 1.0);
+}

package/src/shaders/common/fullscreen.vert.wgsl

@@ -0,0 +1,17 @@
+// VIB3+ Fullscreen Triangle Vertex Shader (WGSL)
+// Uses the oversized triangle technique - no vertex buffer needed
+
+struct VertexOutput {
+    @builtin(position) position: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+};
+
+@vertex
+fn main(@builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
+    var output: VertexOutput;
+    let x = f32(i32(vertexIndex & 1u) * 4 - 1);
+    let y = f32(i32(vertexIndex >> 1u) * 4 - 1);
+    output.position = vec4<f32>(x, y, 0.0, 1.0);
+    output.uv = vec2<f32>((x + 1.0) * 0.5, (1.0 - y) * 0.5);
+    return output;
+}