@vib3code/sdk 2.0.1

package/src/wasm/index.js

@@ -0,0 +1,132 @@
+/**
+ * WASM Module - VIB3+ SDK
+ *
+ * WebAssembly integration with automatic JavaScript fallback.
+ *
+ * Usage:
+ *   import { init, getModule } from '@vib3code/sdk/wasm';
+ *
+ *   // Initialize (loads WASM if available)
+ *   await init();
+ *
+ *   // Get the module (WASM or JS fallback)
+ *   const vib3 = getModule();
+ *
+ *   // Use math classes
+ *   const v = new vib3.Vec4(1, 2, 3, 4);
+ *   const r = vib3.Rotor4D.fromEuler6(0.1, 0.2, 0.3, 0.4, 0.5, 0.6);
+ */
+
+export {
+    // Loader functions
+    configure,
+    loadWasmModule,
+    init,
+    getModule,
+    getStatus,
+    reset,
+
+    // Feature detection
+    isWasmSupported,
+    isSimdSupported,
+    isWasmLoaded,
+    isFallbackActive,
+
+    // Fallback classes (always available)
+    Vec4Fallback,
+    Rotor4DFallback,
+    Mat4x4Fallback
+} from './WasmLoader.js';
+
+import WasmLoader from './WasmLoader.js';
+export default WasmLoader;
+
+/**
+ * Unified math API that automatically uses WASM or fallback
+ *
+ * This provides a consistent interface regardless of WASM availability.
+ */
+export class UnifiedMath {
+    static #module = null;
+
+    /**
+     * Initialize the unified API
+     * @returns {Promise<void>}
+     */
+    static async init() {
+        const { init, getModule } = await import('./WasmLoader.js');
+        await init();
+        UnifiedMath.#module = getModule();
+    }
+
+    /**
+     * Get the underlying module
+     */
+    static get module() {
+        return UnifiedMath.#module;
+    }
+
+    /**
+     * Create Vec4
+     */
+    static vec4(x = 0, y = 0, z = 0, w = 0) {
+        const m = UnifiedMath.#module;
+        return m ? new m.Vec4(x, y, z, w) : null;
+    }
+
+    /**
+     * Create Rotor4D from plane angle
+     */
+    static rotorFromPlane(plane, angle) {
+        const m = UnifiedMath.#module;
+        return m ? m.Rotor4D.fromPlaneAngle(plane, angle) : null;
+    }
+
+    /**
+     * Create Rotor4D from 6 angles
+     */
+    static rotorFromEuler6(xy, xz, yz, xw, yw, zw) {
+        const m = UnifiedMath.#module;
+        return m ? m.Rotor4D.fromEuler6(xy, xz, yz, xw, yw, zw) : null;
+    }
+
+    /**
+     * Create rotation matrix from 6 angles
+     */
+    static matrixFromAngles(xy, xz, yz, xw, yw, zw) {
+        const m = UnifiedMath.#module;
+        return m ? m.Mat4x4.rotationFromAngles(xy, xz, yz, xw, yw, zw) : null;
+    }
+
+    /**
+     * Project 4D point to 3D (perspective)
+     */
+    static project(v, distance = 2.0) {
+        const m = UnifiedMath.#module;
+        return m ? m.projectPerspective(v, distance) : null;
+    }
+
+    /**
+     * Project batch of 4D points (returns Float32Array)
+     */
+    static projectBatch(points, distance = 2.0) {
+        const m = UnifiedMath.#module;
+        return m ? m.projectToFloatArray(points, distance) : null;
+    }
+
+    /**
+     * Check if WASM is being used
+     */
+    static get isWasm() {
+        const m = UnifiedMath.#module;
+        return m ? (m.isWasm?.() ?? true) : false;
+    }
+
+    /**
+     * Check if SIMD is enabled
+     */
+    static get hasSimd() {
+        const m = UnifiedMath.#module;
+        return m ? (m.hasSimd?.() ?? false) : false;
+    }
+}

package/tools/agentic/mcpTools.js

@@ -0,0 +1,88 @@
+import { createRotationMatrix4D } from '../../src/math/rotations.js';
+import { buildTelemetryError } from '../telemetry/telemetryEvents.js';
+
+const VALID_PLANES = ['XY', 'XZ', 'YZ', 'XW', 'YW', 'ZW'];
+
+export const MCP_TOOL_DEFINITIONS = [
+    {
+        name: 'create_scene',
+        description: 'Create a 4D visualization scene with geometry and projection.',
+        parameters: {
+            type: 'object',
+            required: ['geometryType', 'projection'],
+            properties: {
+                geometryType: { type: 'string' },
+                projection: { type: 'string', enum: ['stereographic', 'perspective', 'orthographic'] },
+                metadata: { type: 'object' },
+            },
+        },
+    },
+    {
+        name: 'apply_rotation',
+        description: 'Apply a 4D rotation to a scene using a plane + angle.',
+        parameters: {
+            type: 'object',
+            required: ['sceneId', 'plane', 'angle'],
+            properties: {
+                sceneId: { type: 'string' },
+                plane: { type: 'string', enum: VALID_PLANES },
+                angle: { type: 'number' },
+            },
+        },
+    },
+    {
+        name: 'render_preview',
+        description: 'Render a preview frame for a scene.',
+        parameters: {
+            type: 'object',
+            required: ['sceneId'],
+            properties: {
+                sceneId: { type: 'string' },
+                width: { type: 'number' },
+                height: { type: 'number' },
+            },
+        },
+    },
+];
+
+export function invokeTool(toolName, payload) {
+    switch (toolName) {
+        case 'create_scene':
+            return {
+                sceneId: payload.sceneId || `scene-${Date.now()}`,
+                geometryType: payload.geometryType,
+                projection: payload.projection,
+                metadata: payload.metadata || {},
+                suggestedNextActions: ['apply_rotation', 'render_preview'],
+            };
+        case 'apply_rotation':
+            if (!VALID_PLANES.includes(payload.plane)) {
+                return buildTelemetryError({
+                    code: 'INVALID_ROTATION_PLANE',
+                    message: `Rotation plane '${payload.plane}' is not valid`,
+                    suggestion: 'Use one of the six rotation planes.',
+                    validOptions: VALID_PLANES,
+                });
+            }
+            return {
+                sceneId: payload.sceneId,
+                plane: payload.plane,
+                angle: payload.angle,
+                rotationMatrix: createRotationMatrix4D(payload.plane, payload.angle),
+            };
+        case 'render_preview':
+            return {
+                sceneId: payload.sceneId,
+                width: payload.width || 320,
+                height: payload.height || 180,
+                previewHint: 'Use TelemetryDirector.generatePreviewSprites for real rendering.',
+            };
+        default:
+            return buildTelemetryError({
+                code: 'UNKNOWN_TOOL',
+                message: `Tool '${toolName}' is not registered.`,
+                suggestion: 'Use one of the MCP_TOOL_DEFINITIONS entries.',
+                validOptions: MCP_TOOL_DEFINITIONS.map((tool) => tool.name),
+            });
+    }
+}

package/tools/cli/agent-cli.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { TelemetryDirector } from '../../js/core/telemetry-director.js';
+import { buildTelemetryError, createTelemetrySpan, endTelemetrySpan } from '../telemetry/telemetryEvents.js';
+
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const result = { command: args[0], flags: {}, positional: [] };
+
+    for (let i = 1; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const [key, value] = arg.replace(/^--/, '').split('=');
+            result.flags[key] = value ?? true;
+        } else {
+            result.positional.push(arg);
+        }
+    }
+
+    return result;
+}
+
+function readJson(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw);
+}
+
+async function runTelemetryExport({ packPath, previewCount }) {
+    const pack = readJson(packPath);
+    const director = new TelemetryDirector();
+    return director.exportPack(pack, { previewCount });
+}
+
+async function main() {
+    const { command, flags, positional } = parseArgs(process.argv);
+    const jsonOutput = Boolean(flags.json);
+    const nonInteractive = Boolean(flags['non-interactive']);
+
+    if (!command || command === '--help' || flags.help) {
+        console.log('Usage: node tools/cli/agent-cli.js telemetry:export <pack.json> [--json] [--non-interactive] [--preview-count=4]');
+        process.exit(0);
+    }
+
+    if (nonInteractive && !jsonOutput) {
+        console.error('Non-interactive mode requires --json output.');
+        process.exit(1);
+    }
+
+    if (command === 'telemetry:export') {
+        const packPath = positional[0];
+        if (!packPath) {
+            console.error('Missing pack path for telemetry:export.');
+            process.exit(1);
+        }
+
+        const span = createTelemetrySpan('telemetry.export', { packPath, previewCount: flags['preview-count'] });
+        try {
+            const result = await runTelemetryExport({
+                packPath,
+                previewCount: Number(flags['preview-count']) || 4,
+            });
+            const completedSpan = endTelemetrySpan(span, 'ok');
+
+            if (jsonOutput) {
+                console.log(JSON.stringify({ ...result, span: completedSpan }, null, 2));
+            } else {
+                console.log(result.summary);
+            }
+            return;
+        } catch (error) {
+            const completedSpan = endTelemetrySpan(span, 'error');
+            const errorPayload = buildTelemetryError({
+                code: 'INVALID_PACK_JSON',
+                message: error.message || 'Failed to parse pack JSON.',
+                suggestion: 'Ensure the pack file is valid JSON with scenes or states.',
+                meta: { packPath },
+            });
+
+            if (jsonOutput) {
+                console.log(JSON.stringify({ ...errorPayload, span: completedSpan }, null, 2));
+            } else {
+                console.error(errorPayload.error.message);
+            }
+            process.exit(1);
+        }
+    }
+
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+}
+
+main();

package/tools/export/formats.js

@@ -0,0 +1,24 @@
+export const EXPORT_FORMATS = [
+    {
+        id: 'svg-sprite',
+        name: 'SVG Sprite Sheet',
+        extension: '.svg',
+        description: 'Vector sprite sheet for web and design tooling.',
+    },
+    {
+        id: 'lottie-json',
+        name: 'Lottie JSON',
+        extension: '.json',
+        description: 'Motion-ready JSON payload for Lottie renderers.',
+    },
+    {
+        id: 'css-variables',
+        name: 'CSS Variables',
+        extension: '.css',
+        description: 'CSS custom properties for theming pipelines.',
+    },
+];
+
+export function getExportFormat(id) {
+    return EXPORT_FORMATS.find((format) => format.id === id) || null;
+}

package/tools/math/rotation-baseline.mjs

@@ -0,0 +1,64 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { Projection } from '../../src/math/Projection.js';
+import { Rotor4D } from '../../src/math/Rotor4D.js';
+import { Vec4 } from '../../src/math/Vec4.js';
+
+const iterations = 4000;
+const renormInterval = 25;
+const step = Rotor4D.fromEuler6({ xy: 0.003, xw: 0.002, zw: -0.001 });
+
+let rotorNoRenorm = Rotor4D.identity();
+let rotorRenorm = Rotor4D.identity();
+
+for (let i = 1; i <= iterations; i += 1) {
+    rotorNoRenorm = rotorNoRenorm.multiply(step);
+    rotorRenorm = rotorRenorm.multiply(step);
+    if (i % renormInterval === 0) {
+        rotorRenorm.normalizeInPlace();
+    }
+}
+
+const driftNoRenorm = Math.abs(rotorNoRenorm.norm() - 1);
+const driftRenorm = Math.abs(rotorRenorm.norm() - 1);
+
+let vector = new Vec4(0.2, -0.7, 1.1, 0.4);
+const baselineLength = vector.length();
+const stepRotor = Rotor4D.fromPlaneAngle('XW', 0.01);
+
+for (let i = 1; i <= 2000; i += 1) {
+    vector = stepRotor.rotate(vector);
+}
+
+const vectorLengthDrift = Math.abs(vector.length() - baselineLength);
+
+const perspectiveSample = Projection.perspective(new Vec4(1, 1, 1, 2), 2, { epsilon: 1e-4 });
+const stereographicSample = Projection.stereographic(new Vec4(1, 0, 0, 1), { epsilon: 1e-4 });
+
+const output = {
+    generated_at: new Date().toISOString(),
+    rotor_precision: {
+        iterations,
+        renorm_interval: renormInterval,
+        drift_without_renorm: driftNoRenorm,
+        drift_with_renorm: driftRenorm,
+        vector_length_drift: vectorLengthDrift,
+    },
+    projection_clamp: {
+        epsilon: 1e-4,
+        perspective_sample: {
+            x: perspectiveSample.x,
+            y: perspectiveSample.y,
+            z: perspectiveSample.z,
+        },
+        stereographic_sample: {
+            x: stereographicSample.x,
+            y: stereographicSample.y,
+            z: stereographicSample.z,
+        },
+    },
+};
+
+const outputPath = resolve('docs/src/math/rotation-baseline.json');
+await writeFile(outputPath, `${JSON.stringify(output, null, 2)}\n`, 'utf8');