@vib3code/sdk 2.0.1

package/tools/telemetry/manifestPipeline.js

@@ -0,0 +1,141 @@
+import crypto from 'node:crypto';
+
+/**
+ * Utility to produce deterministic hashes for manifest payloads and assets.
+ * Accepts strings, Buffers, or objects (stringified with stable JSON ordering).
+ */
+function stableStringify(value) {
+    if (value === undefined) {
+        return 'null';
+    }
+
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+    }
+
+    const keys = Object.keys(value).sort();
+    const entries = keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+    return `{${entries.join(',')}}`;
+}
+
+export function computeAssetHash(payload) {
+    if (payload === undefined || payload === null) {
+        return crypto.createHash('sha256').update('null').digest('hex');
+    }
+
+    if (Buffer.isBuffer(payload)) {
+        return crypto.createHash('sha256').update(payload).digest('hex');
+    }
+
+    if (typeof payload === 'string') {
+        return crypto.createHash('sha256').update(payload).digest('hex');
+    }
+
+    const stable = stableStringify(payload);
+    return crypto.createHash('sha256').update(stable).digest('hex');
+}
+
+function normalizePalette(palette = []) {
+    return palette.map((entry) => ({
+        name: entry.name || 'unnamed',
+        swatches: entry.swatches || [],
+    }));
+}
+
+function normalizeTypography(tokens = {}) {
+    return {
+        families: tokens.families || ['Inter', 'Space Grotesk'],
+        scales: tokens.scales || {
+            display: '72px/1.05',
+            heading: '32px/1.2',
+            body: '16px/1.6',
+            caption: '13px/1.4',
+        },
+    };
+}
+
+function normalizeBreakpoints(breakpoints = {}) {
+    return {
+        xs: breakpoints.xs || '360px',
+        sm: breakpoints.sm || '640px',
+        md: breakpoints.md || '960px',
+        lg: breakpoints.lg || '1280px',
+        xl: breakpoints.xl || '1600px',
+    };
+}
+
+/**
+ * Build a manifest with enriched metadata for downstream telemetry.
+ */
+export function buildTelemetryManifest({
+    baseManifest = {},
+    license = 'SEE LICENSE IN DOCS/LICENSE_ATTESTATION_PROFILE_CATALOG.md',
+    themeTags = [],
+    colorPalettes = [],
+    typography = {},
+    breakpoints = {},
+    previews = [],
+    assets = [],
+}) {
+    const normalizedPalettes = normalizePalette(colorPalettes);
+    const normalizedTypography = normalizeTypography(typography);
+    const normalizedBreakpoints = normalizeBreakpoints(breakpoints);
+
+    const manifest = {
+        ...baseManifest,
+        license,
+        themeTags: Array.from(new Set(themeTags)),
+        colorPalettes: normalizedPalettes,
+        typography: normalizedTypography,
+        responsiveBreakpoints: normalizedBreakpoints,
+        previews: previews.map((preview) => ({
+            ...preview,
+            hash: preview.hash || computeAssetHash(preview.src || preview.dataUrl || preview.id),
+        })),
+        assets: assets.map((asset) => ({
+            ...asset,
+            hash: asset.hash || computeAssetHash(asset.contents || asset.url || asset.path),
+        })),
+    };
+
+    return {
+        manifest,
+        hash: computeAssetHash(manifest),
+    };
+}
+
+/**
+ * Format export output for CLI usage with deterministic hashes for diffing.
+ */
+export function formatExportSummary(manifestResult) {
+    const lines = [
+        `manifest hash: ${manifestResult.hash}`,
+        `assets: ${manifestResult.manifest.assets.length}`,
+        `previews: ${manifestResult.manifest.previews.length}`,
+    ];
+
+    manifestResult.manifest.assets.forEach((asset) => {
+        lines.push(` • ${asset.name || asset.path || 'asset'} => ${asset.hash}`);
+    });
+
+    manifestResult.manifest.previews.forEach((preview) => {
+        lines.push(` • preview:${preview.id || preview.name} => ${preview.hash}`);
+    });
+
+    return lines.join('\n');
+}
+
+/**
+ * High-level helper used by export pipelines.
+ */
+export function exportTelemetryManifest(config) {
+    const manifestResult = buildTelemetryManifest(config);
+    return {
+        ...manifestResult,
+        summary: formatExportSummary(manifestResult),
+    };
+}

package/tools/telemetry/telemetryEvents.js

@@ -0,0 +1,35 @@
+import crypto from 'node:crypto';
+
+function generateSpanId() {
+    return crypto.randomBytes(8).toString('hex');
+}
+
+export function createTelemetrySpan(name, attributes = {}) {
+    return {
+        id: generateSpanId(),
+        name,
+        startTime: new Date().toISOString(),
+        attributes,
+    };
+}
+
+export function endTelemetrySpan(span, status = 'ok') {
+    return {
+        ...span,
+        endTime: new Date().toISOString(),
+        status,
+    };
+}
+
+export function buildTelemetryError({ code, message, suggestion, validOptions = [], meta = {} }) {
+    return {
+        error: {
+            type: 'ValidationError',
+            code,
+            message,
+            suggestion,
+            validOptions,
+            meta,
+        },
+    };
+}

package/types/adaptive-sdk.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @vib3code/sdk — Adaptive SDK TypeScript Definitions
+ * VIB3+ 4D Visualization Engine v2.0.0
+ *
+ * Barrel re-export for all typed modules.
+ *
+ * Typed modules:
+ *   - core/VIB3Engine (engine, systems, parameters, state)
+ *   - core/ErrorReporter (opt-in error capture)
+ *   - reactivity (ReactivityManager, ReactivityConfig, all input types)
+ *   - reactivity/SpatialInputSystem (universal spatial input)
+ *   - render (WebGL/WebGPU backends, ShaderProgram, RenderState, CommandBuffer)
+ *   - creative (ColorPresets, TransitionAnimator, PostProcessing, Timeline)
+ *   - integrations (React, Vue, Svelte, Figma, Three.js, TouchDesigner, OBS)
+ *   - advanced (WebXR, WebGPU Compute, MIDI, AI Presets, OffscreenWorker)
+ */
+
+// Core engine
+export {
+    VIB3Engine,
+    VIB3EngineOptions,
+    VIB3EngineState,
+    SystemName,
+    BackendType,
+    GeometryNames
+} from './core/VIB3Engine';
+
+// Core - Error Reporter
+export {
+    ErrorReporter,
+    ErrorReporterOptions,
+    ErrorReport
+} from './core/ErrorReporter';
+
+// Reactivity system
+export {
+    ReactivityManager,
+    ReactivityConfig,
+    ReactivityConfigData,
+    ReactivityEvent,
+    ValidationResult,
+    AudioConfig,
+    AudioBandConfig,
+    AudioTarget,
+    AudioBand,
+    TiltConfig,
+    TiltAxisMapping,
+    InteractionConfig,
+    MouseInteractionConfig,
+    ClickInteractionConfig,
+    ScrollInteractionConfig,
+    TouchInteractionConfig,
+    MouseMode,
+    ClickMode,
+    ScrollMode,
+    BlendMode,
+    TargetableParameter,
+    ParameterUpdateFn,
+    InputState,
+    AudioInputState,
+    TiltInputState,
+    MouseInputState,
+    ClickInputState,
+    ScrollInputState,
+    TouchInputState,
+    TARGETABLE_PARAMETERS,
+    AUDIO_BANDS,
+    BLEND_MODES,
+    INTERACTION_MODES,
+    DEFAULT_REACTIVITY_CONFIG
+} from './reactivity/index';
+
+// Spatial Input System
+export {
+    SpatialInputSystem,
+    createSpatialInputSystem,
+    SpatialInputOptions,
+    SpatialState,
+    SpatialAxis,
+    SourceType,
+    SourceInfo,
+    MappingEntry,
+    ProfileDef,
+    BuiltinProfile,
+    SpatialEvent,
+    SOURCE_TYPES,
+    SPATIAL_AXES
+} from './reactivity/SpatialInputSystem';
+
+// Render system
+export {
+    RenderContext,
+    RenderContextOptions,
+    AsyncRenderContextOptions,
+    createRenderContext,
+    createRenderContextAsync,
+    RenderPresets,
+    Shader4D,
+    Shader4DOptions
+} from './render/index';
+
+// Creative tooling
+export {
+    ColorPresetsSystem,
+    ColorPresetConfig,
+    PresetInfo,
+    PresetsByCategory,
+    BuiltinPresetName,
+    TransitionAnimator,
+    EasingName,
+    SequenceStep,
+    PostProcessingPipeline,
+    BuiltinEffectName,
+    PresetChainName,
+    EffectParamDef,
+    EffectDetail,
+    PresetChainInfo,
+    PipelineState,
+    ParameterTimeline,
+    LoopMode,
+    Keyframe,
+    TimelineState
+} from './creative/index';
+
+// Platform integrations
+export {
+    Vib3ReactWrapper,
+    Vib3CanvasProps,
+    UseVib3Return,
+    GeneratedPackage,
+    Vib3VueWrapper,
+    Vib3VueProps,
+    UseVib3ComposableReturn,
+    Vib3SvelteWrapper,
+    Vib3SvelteProps,
+    Vib3Store,
+    Vib3StoreValue,
+    Vib3FigmaPlugin,
+    FigmaManifest,
+    FigmaManifestOptions,
+    FigmaCodeOptions,
+    Vib3ThreeJsPackage,
+    ShaderMaterialConfig,
+    ShaderMaterialOptions,
+    UniformValue,
+    Vib3TouchDesignerExport,
+    GLSLTOPOptions,
+    TDUniformMapping,
+    Vib3OBSMode,
+    CaptureMode,
+    OBSModeOptions,
+    OBSBrowserSourceConfig,
+    OBSRecommendedSettings
+} from './integrations/index';
+
+// Advanced features
+export {
+    WebXRRenderer,
+    XRMode,
+    XRSupportResult,
+    SixDOFPose,
+    TrackingMapping,
+    XRFrameCallback,
+    WebXREvent,
+    WebGPUCompute,
+    ParticleParams,
+    MIDIController,
+    CCMapping,
+    CCMappingOptions,
+    NoteMapping,
+    MIDIInputInfo,
+    MIDIMappingState,
+    LearnCallback,
+    AIPresetGenerator,
+    VIB3Preset,
+    ParamRange,
+    ThemeName,
+    OffscreenCanvasManager,
+    WorkerMessage,
+    WorkerMessageType,
+    WorkerInitMessage,
+    WorkerParamsMessage,
+    WorkerSwitchMessage,
+    WorkerResizeMessage
+} from './advanced/index';

package/types/advanced/AIPresetGenerator.d.ts

@@ -0,0 +1,81 @@
+/**
+ * AIPresetGenerator TypeScript Definitions
+ * VIB3+ SDK - Text-to-Preset via LLM + Mutation/Crossbreeding
+ */
+
+/** VIB3 preset object */
+export interface VIB3Preset {
+    name?: string;
+    system?: string;
+    geometry?: number;
+    hue?: number;
+    saturation?: number;
+    intensity?: number;
+    speed?: number;
+    gridDensity?: number;
+    morphFactor?: number;
+    chaos?: number;
+    dimension?: number;
+    rot4dXY?: number;
+    rot4dXZ?: number;
+    rot4dYZ?: number;
+    rot4dXW?: number;
+    rot4dYW?: number;
+    rot4dZW?: number;
+    [key: string]: any;
+}
+
+/** Parameter range constraint */
+export interface ParamRange {
+    min: number;
+    max: number;
+    step?: number;
+}
+
+/** Theme names available for random generation */
+export type ThemeName = string;
+
+/**
+ * AI-powered preset generator.
+ * Generates presets from text descriptions, mutates existing presets,
+ * and crossbreeds two presets to produce offspring.
+ */
+export declare class AIPresetGenerator {
+    /** Parameter range constraints */
+    static readonly PARAM_RANGES: Record<string, ParamRange>;
+
+    /** Style vocabulary for text-to-preset mapping */
+    static readonly STYLE_VOCABULARY: Record<string, Record<string, number>>;
+
+    /** Named theme presets */
+    static readonly THEMES: Record<string, VIB3Preset>;
+
+    constructor(engine?: any);
+
+    /** Generate a preset from a text description */
+    generateFromText(description: string): Promise<VIB3Preset>;
+
+    /** Generate a random preset, optionally within a theme */
+    generateRandom(theme?: ThemeName): VIB3Preset;
+
+    /** Mutate a preset by a given intensity (0-1) */
+    mutate(preset: VIB3Preset, intensity?: number): VIB3Preset;
+
+    /** Crossbreed two presets with an optional bias (0=all A, 1=all B) */
+    crossbreed(preset1: VIB3Preset, preset2: VIB3Preset, bias?: number): VIB3Preset;
+
+    /** Set the MCP endpoint for LLM-powered generation */
+    setMCPEndpoint(endpoint: string): void;
+
+    /** Get generation history */
+    getHistory(): VIB3Preset[];
+
+    /** Clear generation history */
+    clearHistory(): void;
+
+    /** Export a preset as a serializable object */
+    exportPreset(preset: VIB3Preset): Record<string, any>;
+
+    /** Import a preset from serialized data */
+    importPreset(data: Record<string, any>): VIB3Preset | null;
+}

package/types/advanced/MIDIController.d.ts

@@ -0,0 +1,100 @@
+/**
+ * MIDIController TypeScript Definitions
+ * VIB3+ SDK - Web MIDI API with Learn Mode
+ */
+
+import { ParameterUpdateFn } from '../reactivity/index';
+
+/** CC mapping options */
+export interface CCMappingOptions {
+    min?: number;
+    max?: number;
+    curve?: 'linear' | 'exponential' | 'logarithmic';
+    invert?: boolean;
+}
+
+/** CC mapping entry */
+export interface CCMapping {
+    channel: number;
+    cc: number;
+    param: string;
+    min: number;
+    max: number;
+    curve: string;
+    invert: boolean;
+}
+
+/** Note mapping entry */
+export interface NoteMapping {
+    channel: number;
+    note: number;
+    action: string;
+    trigger: 'noteOn' | 'noteOff' | 'toggle';
+}
+
+/** MIDI input device info */
+export interface MIDIInputInfo {
+    id: string;
+    name: string;
+}
+
+/** Serialized mapping state */
+export interface MIDIMappingState {
+    cc: Record<string, CCMapping>;
+    notes: Record<string, NoteMapping>;
+}
+
+/** Learn callback */
+export type LearnCallback = (channel: number, cc: number) => void;
+
+/**
+ * Web MIDI controller with CC/note mapping and learn mode.
+ * Maps MIDI control changes to VIB3+ parameters in real-time.
+ */
+export declare class MIDIController {
+    readonly learning: boolean;
+
+    constructor(parameterUpdateFn: ParameterUpdateFn);
+
+    /** Initialize Web MIDI API access */
+    initialize(): Promise<any>;
+
+    /** Load the default CC mapping */
+    loadDefaultMapping(): void;
+
+    /** Map a MIDI CC to a parameter */
+    mapCC(channel: number, cc: number, param: string, options?: CCMappingOptions): void;
+
+    /** Unmap a MIDI CC */
+    unmapCC(channel: number, cc: number): boolean;
+
+    /** Map a MIDI note to an action */
+    mapNote(channel: number, note: number, action: string, trigger?: 'noteOn' | 'noteOff' | 'toggle'): void;
+
+    /** Unmap a MIDI note */
+    unmapNote(channel: number, note: number): boolean;
+
+    /** Start learn mode: next CC received will be mapped to param */
+    startLearn(param: string, callback: LearnCallback): void;
+
+    /** Stop learn mode */
+    stopLearn(): void;
+
+    /** Process a MIDI message (called internally) */
+    onMIDIMessage(event: any): void;
+
+    /** List connected MIDI inputs */
+    listInputs(): MIDIInputInfo[];
+
+    /** Get a specific CC mapping */
+    getMapping(channel: number, cc: number): CCMapping | null;
+
+    /** Export all mappings */
+    exportMappings(): MIDIMappingState;
+
+    /** Import mappings from serialized data */
+    importMappings(data: MIDIMappingState): boolean;
+
+    /** Destroy and disconnect */
+    destroy(): void;
+}

package/types/advanced/OffscreenWorker.d.ts

@@ -0,0 +1,82 @@
+/**
+ * OffscreenWorker TypeScript Definitions
+ * VIB3+ SDK - OffscreenCanvas Worker Rendering
+ */
+
+import { SystemName } from '../core/VIB3Engine';
+
+/** Worker message types (sent to worker) */
+export type WorkerMessageType = 'init' | 'params' | 'switchSystem' | 'resize';
+
+/** Init message data */
+export interface WorkerInitMessage {
+    type: 'init';
+    canvas: OffscreenCanvas;
+    system: SystemName;
+    width: number;
+    height: number;
+    params: Record<string, number>;
+    pixelRatio: number;
+    sharedBuffer?: SharedArrayBuffer;
+}
+
+/** Parameter update message */
+export interface WorkerParamsMessage {
+    type: 'params';
+    params: Record<string, number>;
+}
+
+/** System switch message */
+export interface WorkerSwitchMessage {
+    type: 'switchSystem';
+    system: SystemName;
+}
+
+/** Resize message */
+export interface WorkerResizeMessage {
+    type: 'resize';
+    width: number;
+    height: number;
+}
+
+/** Any worker message */
+export type WorkerMessage =
+    | WorkerInitMessage
+    | WorkerParamsMessage
+    | WorkerSwitchMessage
+    | WorkerResizeMessage;
+
+/**
+ * Manages OffscreenCanvas worker rendering for background GPU work.
+ * Uses transferControlToOffscreen() and optional SharedArrayBuffer for parameters.
+ */
+export declare class OffscreenCanvasManager {
+    constructor();
+
+    /** Create a worker renderer for a canvas element */
+    createWorkerRenderer(canvasId: string, system?: SystemName): Promise<Worker>;
+
+    /** Update all parameters on all workers */
+    updateParameters(params: Record<string, number>): void;
+
+    /** Set a single parameter on all workers */
+    setParameter(name: string, value: number): void;
+
+    /** Switch system on all workers */
+    switchSystem(system: SystemName): void;
+
+    /** Resize a specific worker's canvas */
+    resizeCanvas(canvasId: string, width: number, height: number): void;
+
+    /** Terminate a specific worker */
+    terminateWorker(canvasId: string): void;
+
+    /** Get the worker blob URL (for manual worker creation) */
+    getWorkerBlobURL(): string;
+
+    /** Get the worker script source */
+    getWorkerScript(): string;
+
+    /** Destroy all workers */
+    destroy(): void;
+}

package/types/advanced/WebGPUCompute.d.ts

@@ -0,0 +1,52 @@
+/**
+ * WebGPUCompute TypeScript Definitions
+ * VIB3+ SDK - WGSL Particle Simulation & Audio FFT Compute Shaders
+ */
+
+/** Particle simulation parameters */
+export interface ParticleParams {
+    gravity?: number;
+    speed?: number;
+    turbulence?: number;
+    attraction?: number;
+    damping?: number;
+    [key: string]: number | undefined;
+}
+
+/**
+ * WebGPU compute shader pipeline for particle simulation and audio FFT.
+ * Runs WGSL compute shaders on the GPU for high-performance parallel processing.
+ */
+export declare class WebGPUCompute {
+    /** WGSL particle simulation shader source */
+    static readonly PARTICLE_COMPUTE_WGSL: string;
+
+    /** WGSL audio FFT shader source */
+    static readonly AUDIO_FFT_COMPUTE_WGSL: string;
+
+    readonly device: any | null;
+    readonly particleCount: number;
+
+    constructor(device?: any);
+
+    /** Initialize with a GPUDevice */
+    initialize(device: any): Promise<void>;
+
+    /** Create a particle system with N particles */
+    createParticleSystem(count?: number): Promise<void>;
+
+    /** Run one simulation step */
+    updateParticles(params: ParticleParams, deltaTime: number): Promise<void>;
+
+    /** Read back particle positions from GPU */
+    readParticleData(): Promise<Float32Array>;
+
+    /** Run audio FFT compute shader */
+    computeAudioFFT(audioBuffer: Float32Array): Float32Array;
+
+    /** Set geometry attractor for particle system */
+    setGeometryAttractor(geometry: number): void;
+
+    /** Dispose GPU resources */
+    dispose(): void;
+}