@vib3code/sdk 2.0.1

package/types/advanced/WebXRRenderer.d.ts

@@ -0,0 +1,77 @@
+/**
+ * WebXRRenderer TypeScript Definitions
+ * VIB3+ SDK - WebXR VR/AR Renderer with 6DOF
+ */
+
+/** XR session mode */
+export type XRMode = 'immersive-vr' | 'immersive-ar' | 'inline';
+
+/** XR support check result */
+export interface XRSupportResult {
+    available: boolean;
+    vr: boolean;
+    ar: boolean;
+    inline: boolean;
+}
+
+/** 6DOF pose data extracted from XR frame */
+export interface SixDOFPose {
+    position: { x: number; y: number; z: number };
+    orientation: { x: number; y: number; z: number; w: number };
+    linearVelocity?: { x: number; y: number; z: number };
+    angularVelocity?: { x: number; y: number; z: number };
+}
+
+/** Tracking-to-parameter mapping */
+export interface TrackingMapping {
+    [trackingAxis: string]: {
+        param: string;
+        scale?: number;
+        offset?: number;
+    };
+}
+
+/** WebXR frame callback */
+export type XRFrameCallback = (frame: any, pose: SixDOFPose | null) => void;
+
+/** WebXRRenderer event names */
+export type WebXREvent = 'sessionStart' | 'sessionEnd' | 'frameUpdate' | 'inputSourcesChange';
+
+/**
+ * WebXR VR/AR renderer with 6DOF spatial extraction.
+ * Maps head pose to VIB3+ visualization parameters.
+ */
+export declare class WebXRRenderer {
+    readonly isImmersive: boolean;
+    readonly mode: XRMode;
+    xrSession: any | null;
+
+    constructor(engine: any);
+
+    /** Check WebXR API support */
+    checkSupport(): Promise<XRSupportResult>;
+
+    /** Start an XR session */
+    startSession(mode?: XRMode): Promise<any>;
+
+    /** End the current XR session */
+    endSession(): Promise<void>;
+
+    /** Check if a session is active */
+    isSessionActive(): boolean;
+
+    /** Extract head pose from an XR frame */
+    extractHeadPose(frame: any): SixDOFPose | null;
+
+    /** Set how XR tracking maps to visualization parameters */
+    setTrackingToParameterMapping(mapping?: TrackingMapping): void;
+
+    /** XR frame callback (called internally each frame) */
+    onXRFrame(time: number, frame: any): void;
+
+    /** Set a custom frame callback */
+    setFrameCallback(fn: XRFrameCallback): void;
+
+    /** Dispose and end session */
+    dispose(): void;
+}

package/types/advanced/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Advanced Module TypeScript Definitions
+ * VIB3+ SDK - WebXR, WebGPU Compute, MIDI, AI Presets, Offscreen Worker
+ */
+
+export {
+    WebXRRenderer,
+    XRMode,
+    XRSupportResult,
+    SixDOFPose,
+    TrackingMapping,
+    XRFrameCallback,
+    WebXREvent
+} from './WebXRRenderer';
+
+export {
+    WebGPUCompute,
+    ParticleParams
+} from './WebGPUCompute';
+
+export {
+    MIDIController,
+    CCMapping,
+    CCMappingOptions,
+    NoteMapping,
+    MIDIInputInfo,
+    MIDIMappingState,
+    LearnCallback
+} from './MIDIController';
+
+export {
+    AIPresetGenerator,
+    VIB3Preset,
+    ParamRange,
+    ThemeName
+} from './AIPresetGenerator';
+
+export {
+    OffscreenCanvasManager,
+    WorkerMessage,
+    WorkerMessageType,
+    WorkerInitMessage,
+    WorkerParamsMessage,
+    WorkerSwitchMessage,
+    WorkerResizeMessage
+} from './OffscreenWorker';

package/types/core/ErrorReporter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * ErrorReporter TypeScript Definitions
+ * VIB3+ SDK - Opt-in Error Reporting
+ */
+
+/** Error report payload */
+export interface ErrorReport {
+    type: 'error' | 'unhandledrejection';
+    message: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    stack?: string;
+    timestamp: string;
+    url: string;
+    userAgent: string;
+    sdkVersion: string;
+}
+
+/** ErrorReporter constructor options */
+export interface ErrorReporterOptions {
+    /** Endpoint URL for POST reports */
+    endpoint?: string;
+    /** Custom error handler callback */
+    onError?: (report: ErrorReport) => void;
+    /** Maximum reports to send per session (default: 50) */
+    maxReports?: number;
+    /** Include stack traces (default: true) */
+    includeStack?: boolean;
+}
+
+/**
+ * Opt-in error reporter that captures unhandled errors and promise rejections.
+ * Disabled by default — must call enable() to activate.
+ */
+export declare class ErrorReporter {
+    /** Whether the reporter is currently active */
+    readonly isEnabled: boolean;
+
+    constructor(options?: ErrorReporterOptions);
+
+    /** Enable error capture */
+    enable(): void;
+
+    /** Disable error capture */
+    disable(): void;
+
+    /** Dispose and disable */
+    dispose(): void;
+}

package/types/core/VIB3Engine.d.ts

@@ -0,0 +1,204 @@
+/**
+ * VIB3Engine TypeScript Definitions
+ * VIB3+ SDK - Unified Visualization Engine
+ */
+
+import { ReactivityManager, ReactivityConfigData, ValidationResult } from '../reactivity';
+import { ReactivityConfig } from '../reactivity';
+
+/** Visualization system name */
+export type SystemName = 'quantum' | 'faceted' | 'holographic';
+
+/** Backend type for the active system */
+export type BackendType = 'webgl' | 'webgpu' | 'direct-webgl' | null;
+
+/** VIB3Engine constructor options */
+export interface VIB3EngineOptions {
+    /** Prefer WebGPU with WebGL fallback (default: true) */
+    preferWebGPU?: boolean;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Initial reactivity configuration */
+    reactivityConfig?: Partial<ReactivityConfigData> | ReactivityConfig;
+}
+
+/** Exported engine state */
+export interface VIB3EngineState {
+    system: SystemName;
+    parameters: Record<string, number>;
+    reactivity: ReactivityConfigData;
+    reactivityActive: boolean;
+    backend: BackendType;
+    timestamp: string;
+    version: string;
+}
+
+/** Geometry names array (24 entries) */
+export type GeometryNames = string[];
+
+/**
+ * VIB3+ Engine - Unified Visualization System
+ *
+ * Coordinates Quantum, Faceted, and Holographic systems.
+ * Supports 24 geometries per system with full 6D rotation.
+ * Backend selection: Faceted supports WebGL/WebGPU via UnifiedRenderBridge.
+ * Quantum and Holographic use direct WebGL (5-layer canvas architecture).
+ */
+export declare class VIB3Engine {
+    /** Whether to prefer WebGPU for systems that support it */
+    readonly preferWebGPU: boolean;
+
+    /** Debug mode */
+    readonly debug: boolean;
+
+    /** Whether the engine is initialized */
+    readonly initialized: boolean;
+
+    /** Current system name */
+    readonly currentSystemName: SystemName;
+
+    constructor(options?: VIB3EngineOptions);
+
+    // ========================================================================
+    // Initialization & System Management
+    // ========================================================================
+
+    /**
+     * Initialize the VIB3+ engine.
+     * @param containerId - DOM container element ID (default: 'vib3-container')
+     * @returns Whether initialization succeeded
+     */
+    initialize(containerId?: string): Promise<boolean>;
+
+    /**
+     * Switch between visualization systems.
+     * Destroys the old system and creates the new one (proper WebGL cleanup).
+     */
+    switchSystem(systemName: SystemName): Promise<boolean>;
+
+    /** Get the active backend type for the current system */
+    getActiveBackendType(): BackendType;
+
+    /** Get current system name */
+    getCurrentSystem(): SystemName;
+
+    /** Get active system instance */
+    getActiveSystemInstance(): any;
+
+    // ========================================================================
+    // Parameters
+    // ========================================================================
+
+    /** Update a single parameter */
+    setParameter(name: string, value: number): void;
+
+    /** Update multiple parameters */
+    setParameters(params: Record<string, number>): void;
+
+    /** Get current parameter value */
+    getParameter(name: string): number;
+
+    /** Get all parameters */
+    getAllParameters(): Record<string, number>;
+
+    /** Randomize all parameters */
+    randomizeAll(): void;
+
+    /** Reset to defaults */
+    resetAll(): void;
+
+    // ========================================================================
+    // Reactivity
+    // ========================================================================
+
+    /** Get the ReactivityManager instance */
+    getReactivityManager(): ReactivityManager;
+
+    /** Load a reactivity configuration */
+    loadReactivityConfig(config: Partial<ReactivityConfigData> | ReactivityConfig): ValidationResult;
+
+    /** Get current reactivity configuration */
+    getReactivityConfig(): ReactivityConfigData;
+
+    /** Start reactivity processing (audio/tilt/interaction) */
+    startReactivity(): void;
+
+    /** Stop reactivity processing */
+    stopReactivity(): void;
+
+    /** Check if reactivity is active */
+    isReactivityActive(): boolean;
+
+    /**
+     * Feed audio data into the reactivity system
+     * @param bass - Bass level 0-1
+     * @param mid - Mid level 0-1
+     * @param high - High level 0-1
+     * @param energy - Overall energy (computed if omitted)
+     */
+    setAudioInput(bass: number, mid: number, high: number, energy?: number): void;
+
+    /**
+     * Feed device tilt data into the reactivity system
+     * @param alpha - Z-axis rotation (0-360)
+     * @param beta - X-axis rotation (-180 to 180)
+     * @param gamma - Y-axis rotation (-90 to 90)
+     */
+    setTiltInput(alpha: number, beta: number, gamma: number): void;
+
+    /**
+     * Feed mouse position into the reactivity system
+     * @param x - Normalized X (0-1)
+     * @param y - Normalized Y (0-1)
+     * @param velocityX - Horizontal velocity
+     * @param velocityY - Vertical velocity
+     */
+    setMouseInput(x: number, y: number, velocityX?: number, velocityY?: number): void;
+
+    /**
+     * Trigger a click event in the reactivity system
+     * @param intensity - Click intensity (default: 1.0)
+     */
+    triggerClick(intensity?: number): void;
+
+    /**
+     * Feed scroll delta into the reactivity system
+     * @param delta - Scroll delta value
+     */
+    setScrollDelta(delta: number): void;
+
+    /**
+     * Feed touch data into the reactivity system
+     * @param touches - Active touch points
+     * @param pinchScale - Pinch zoom scale (default: 1)
+     * @param rotation - Two-finger rotation (default: 0)
+     */
+    setTouchInput(touches: Touch[], pinchScale?: number, rotation?: number): void;
+
+    // ========================================================================
+    // Geometry
+    // ========================================================================
+
+    /**
+     * Get geometry names for current system (24 entries).
+     * Index encoding: core_type * 8 + base_geometry
+     */
+    getGeometryNames(): GeometryNames;
+
+    // ========================================================================
+    // State Management
+    // ========================================================================
+
+    /** Export current engine state */
+    exportState(): VIB3EngineState;
+
+    /** Import engine state (restores system, parameters, and reactivity) */
+    importState(state: Partial<VIB3EngineState>): Promise<void>;
+
+    // ========================================================================
+    // Lifecycle
+    // ========================================================================
+
+    /** Destroy engine and clean up all resources */
+    destroy(): void;
+}

package/types/creative/ColorPresetsSystem.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ColorPresetsSystem TypeScript Definitions
+ * VIB3+ SDK - Themed Color Presets
+ */
+
+import { ParameterUpdateFn } from '../reactivity/index';
+
+/** Color preset configuration */
+export interface ColorPresetConfig {
+    hue: number;
+    saturation?: number;
+    intensity?: number;
+    speed?: number;
+    chaos?: number;
+    morphFactor?: number;
+    gridDensity?: number;
+    dimension?: number;
+}
+
+/** Preset info with metadata */
+export interface PresetInfo {
+    name: string;
+    config: ColorPresetConfig;
+    isCustom: boolean;
+}
+
+/** Presets grouped by category */
+export type PresetsByCategory = Record<string, PresetInfo[]>;
+
+/** Built-in preset names */
+export type BuiltinPresetName =
+    | 'Ocean' | 'Lava' | 'Neon' | 'Monochrome' | 'Sunset'
+    | 'Aurora' | 'Forest' | 'Candy' | 'Midnight' | 'Coral'
+    | 'Arctic' | 'Desert' | 'Toxic' | 'Rose' | 'Storm'
+    | 'Ember' | 'Frost' | 'Jungle' | 'Lavender' | 'Chrome'
+    | 'Hologram' | 'Blood';
+
+/**
+ * 22 themed color presets with group parameter application.
+ * Supports custom presets, transitions, and import/export.
+ */
+export declare class ColorPresetsSystem {
+    readonly currentPreset: string | null;
+
+    constructor(parameterUpdateFn: ParameterUpdateFn);
+
+    /** Get all presets (built-in and custom) */
+    getPresets(): PresetInfo[];
+
+    /** Get presets grouped by category */
+    getPresetsByCategory(): PresetsByCategory;
+
+    /** Get a specific preset config */
+    getPreset(name: string): ColorPresetConfig | null;
+
+    /** Get the currently applied preset name */
+    getCurrentPreset(): string | null;
+
+    /** Whether a transition is currently active */
+    isTransitioning(): boolean;
+
+    /** Apply a preset by name, optionally with smooth transition */
+    applyPreset(name: string, transition?: boolean, duration?: number, onComplete?: () => void): boolean;
+
+    /** Apply a raw config, optionally with smooth transition */
+    applyConfig(config: ColorPresetConfig, transition?: boolean, duration?: number): void;
+
+    /** Create a custom preset */
+    createCustomPreset(name: string, config: ColorPresetConfig): boolean;
+
+    /** Update an existing custom preset */
+    updateCustomPreset(name: string, config: ColorPresetConfig): boolean;
+
+    /** Delete a custom preset */
+    deleteCustomPreset(name: string): boolean;
+
+    /** Export a preset (or current) as a serializable object */
+    exportPreset(name?: string): Record<string, any> | null;
+
+    /** Export all custom presets */
+    exportAllCustomPresets(): Record<string, any>;
+
+    /** Import a preset from serialized data */
+    importPreset(data: Record<string, any>): boolean;
+
+    /** Cancel an active transition */
+    cancelTransition(): void;
+
+    /** Dispose and clean up */
+    dispose(): void;
+}

package/types/creative/ParameterTimeline.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ParameterTimeline TypeScript Definitions
+ * VIB3+ SDK - Keyframe Animation with BPM Sync
+ */
+
+import { ParameterUpdateFn } from '../reactivity/index';
+import { EasingName } from './TransitionAnimator';
+
+/** Loop mode for timeline playback */
+export type LoopMode = 'loop' | 'bounce' | 'once';
+
+/** A single keyframe on a track */
+export interface Keyframe {
+    time: number;
+    value: number;
+    easing?: EasingName;
+}
+
+/** Serialized timeline state */
+export interface TimelineState {
+    tracks: Record<string, Keyframe[]>;
+    duration: number;
+    loopMode: LoopMode;
+    playbackSpeed: number;
+    bpm: number;
+}
+
+/**
+ * Keyframe-based parameter animation with BPM synchronization.
+ * Supports multiple parameter tracks, playback control, and serialization.
+ */
+export declare class ParameterTimeline {
+    readonly playing: boolean;
+    readonly currentTime: number;
+    duration: number;
+    loopMode: LoopMode;
+    playbackSpeed: number;
+    bpm: number;
+
+    constructor(parameterUpdateFn: ParameterUpdateFn);
+
+    // Track management
+    addTrack(param: string): boolean;
+    removeTrack(param: string): boolean;
+    setTrackEnabled(param: string, enabled: boolean): boolean;
+    getTrackNames(): string[];
+    getTrackKeyframes(param: string): Keyframe[] | null;
+
+    // Keyframe management
+    addKeyframe(param: string, time: number, value: number, easing?: EasingName): boolean;
+    updateKeyframe(param: string, time: number, newValue: number, easing?: EasingName): boolean;
+    removeKeyframe(param: string, time: number): boolean;
+    clearTrack(param: string): void;
+
+    // Playback
+    setDuration(ms: number): void;
+    play(): void;
+    pause(): void;
+    stop(): void;
+    seek(time: number): void;
+    setLoopMode(mode: LoopMode): void;
+    setPlaybackSpeed(speed: number): void;
+
+    // Callbacks
+    onComplete(callback: () => void): void;
+    onTick(callback: (time: number, progress: number) => void): void;
+
+    // Serialization
+    exportState(): TimelineState;
+    importState(data: TimelineState): boolean;
+
+    // Lifecycle
+    dispose(): void;
+}

package/types/creative/PostProcessingPipeline.d.ts

@@ -0,0 +1,109 @@
+/**
+ * PostProcessingPipeline TypeScript Definitions
+ * VIB3+ SDK - Composable Post-Processing Effects
+ */
+
+/** Built-in effect names */
+export type BuiltinEffectName =
+    | 'bloom' | 'blur' | 'hueRotate' | 'invert' | 'sharpen'
+    | 'chromaticAberration' | 'filmGrain' | 'vignette' | 'scanlines'
+    | 'glitch' | 'pixelate' | 'kaleidoscope' | 'mirror' | 'posterize';
+
+/** Preset chain names */
+export type PresetChainName =
+    | 'Retro CRT' | 'Holographic' | 'Glitch Art' | 'Clean'
+    | 'Cinematic' | 'Psychedelic' | 'Lo-Fi';
+
+/** Effect parameter definition */
+export interface EffectParamDef {
+    min: number;
+    max: number;
+    default: number;
+    step?: number;
+}
+
+/** Effect detail info */
+export interface EffectDetail {
+    name: string;
+    enabled: boolean;
+    type: string;
+    params: Record<string, number>;
+    paramDefs: Record<string, EffectParamDef>;
+}
+
+/** Preset chain info */
+export interface PresetChainInfo {
+    name: PresetChainName;
+    description: string;
+}
+
+/** Serialized pipeline state */
+export interface PipelineState {
+    chain: string[];
+    effects: Record<string, Record<string, number>>;
+    enabled: boolean;
+}
+
+/**
+ * 14 composable post-processing effects with 7 preset chains.
+ * Effects are applied in chain order via CSS filters and canvas overlays.
+ */
+export declare class PostProcessingPipeline {
+    readonly enabled: boolean;
+
+    constructor(targetElement: HTMLElement);
+
+    /** Add an effect to the chain */
+    addEffect(name: BuiltinEffectName | string, params?: Record<string, number>): boolean;
+
+    /** Remove an effect from the chain */
+    removeEffect(name: string): boolean;
+
+    /** Toggle an effect on/off */
+    toggleEffect(name: string): boolean | false;
+
+    /** Set a single parameter on an effect */
+    setEffectParam(effectName: string, param: string, value: number): boolean;
+
+    /** Set multiple parameters on an effect */
+    setEffectParams(effectName: string, params: Record<string, number>): void;
+
+    /** Reorder the effect chain */
+    reorder(newOrder: string[]): void;
+
+    /** Apply all active effects */
+    apply(): void;
+
+    /** Clear all effects */
+    clear(): void;
+
+    /** Load a preset chain by name */
+    loadPresetChain(name: PresetChainName): boolean;
+
+    /** Get all available preset chains */
+    getPresetChains(): PresetChainInfo[];
+
+    /** Get the active preset chain name, or null */
+    getActivePresetChain(): string | null;
+
+    /** Get all effects with their current state */
+    getEffects(): EffectDetail[];
+
+    /** Get the current chain order */
+    getChain(): string[];
+
+    /** Get detail for a specific effect */
+    getEffect(name: string): EffectDetail | null;
+
+    /** Export pipeline state */
+    exportState(): PipelineState;
+
+    /** Import pipeline state */
+    importState(data: PipelineState): boolean;
+
+    /** Enable/disable the entire pipeline */
+    setEnabled(enabled: boolean): void;
+
+    /** Dispose and clean up */
+    dispose(): void;
+}