@vib3code/sdk 2.0.1 → 2.0.3-canary.0a63e71

package/types/scene/index.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Scene Module TypeScript Definitions
+ * MemoryPool (ObjectPool, TypedArrayPool, Vec4Pool, Mat4x4Pool, PoolManager)
+ */
+
+import { Vec4 } from '../math';
+
+// ============================================================================
+// ObjectPool
+// ============================================================================
+
+/** Pool statistics */
+export interface PoolStats {
+    available: number;
+    inUse: number;
+    totalAllocations: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+}
+
+/** Object pool options */
+export interface ObjectPoolOptions {
+    /** Maximum pool size (0 = unlimited) */
+    maxSize?: number;
+    /** Initial pre-warm count */
+    initialSize?: number;
+    /** Whether to pre-warm on construction (default: true) */
+    preWarm?: boolean;
+}
+
+/**
+ * Generic object pool to reduce GC pressure.
+ * @template T - The type of objects managed by the pool
+ */
+export declare class ObjectPool<T = any> {
+    maxSize: number;
+    initialSize: number;
+    preWarm: boolean;
+
+    /** Number of available (pooled) objects. */
+    readonly available: number;
+
+    /** Number of objects currently in use. */
+    readonly inUse: number;
+
+    constructor(factory: () => T, reset?: ((obj: T) => void) | null, options?: ObjectPoolOptions);
+
+    /** Acquire an object from the pool (creates new if empty). */
+    acquire(): T;
+
+    /** Release an object back to the pool. Returns true if accepted. */
+    release(obj: T): boolean;
+
+    /** Release all in-use objects back to the pool. */
+    releaseAll(): void;
+
+    /** Clear both available and in-use pools. */
+    clear(): void;
+
+    /** Get pool statistics (hit rate, allocations). */
+    getStats(): PoolStats;
+}
+
+// ============================================================================
+// TypedArrayPool
+// ============================================================================
+
+/** TypedArray pool statistics */
+export interface TypedArrayPoolStats {
+    float32Pooled: number;
+    uint16Pooled: number;
+    uint32Pooled: number;
+    totalAllocations: number;
+    hits: number;
+    hitRate: number;
+}
+
+/**
+ * Efficient typed array pool with power-of-2 bucketing.
+ * Manages Float32Array, Uint16Array, and Uint32Array pools.
+ */
+export declare class TypedArrayPool {
+    constructor();
+
+    /** Acquire a Float32Array (size rounded up to power of 2, min 16). */
+    acquireFloat32(size: number): Float32Array;
+
+    /** Release a Float32Array back to the pool (cleared to 0). */
+    releaseFloat32(arr: Float32Array): void;
+
+    /** Acquire a Uint16Array. */
+    acquireUint16(size: number): Uint16Array;
+
+    /** Release a Uint16Array. */
+    releaseUint16(arr: Uint16Array): void;
+
+    /** Acquire a Uint32Array. */
+    acquireUint32(size: number): Uint32Array;
+
+    /** Release a Uint32Array. */
+    releaseUint32(arr: Uint32Array): void;
+
+    /** Clear all pools. */
+    clear(): void;
+
+    /** Get pool statistics. */
+    getStats(): TypedArrayPoolStats;
+}
+
+// ============================================================================
+// Vec4Pool
+// ============================================================================
+
+/**
+ * Specialized pool for Vec4 instances.
+ * Must be initialized with a Vec4 class before use.
+ */
+export declare class Vec4Pool {
+    constructor(initialSize?: number);
+
+    /** Initialize the pool with a Vec4 class. */
+    init(Vec4Class: new (x: number, y: number, z: number, w: number) => Vec4): void;
+
+    /** Acquire a Vec4 with specified values. Throws if not initialized. */
+    acquire(x?: number, y?: number, z?: number, w?: number): Vec4;
+
+    /** Release a Vec4 back to the pool. */
+    release(vec: Vec4): void;
+
+    /** Release all vectors. */
+    releaseAll(): void;
+
+    /** Get pool statistics. */
+    getStats(): { available: number; inUse: number };
+}
+
+// ============================================================================
+// Mat4x4Pool
+// ============================================================================
+
+/**
+ * Specialized pool for 4×4 matrix instances.
+ * Must be initialized with a Mat4x4 class before use.
+ */
+export declare class Mat4x4Pool {
+    constructor(initialSize?: number);
+
+    /** Initialize with a Mat4x4 class. */
+    init(Mat4x4Class: { identity(): any }): void;
+
+    /** Acquire an identity matrix. Throws if not initialized. */
+    acquireIdentity(): any;
+
+    /** Release a matrix. */
+    release(mat: any): void;
+
+    /** Release all matrices. */
+    releaseAll(): void;
+
+    /** Get pool statistics. */
+    getStats(): { available: number; inUse: number };
+}
+
+// ============================================================================
+// PoolManager
+// ============================================================================
+
+/** Combined stats from all pool types */
+export interface PoolManagerStats {
+    objectPools: Record<string, PoolStats>;
+    typedArrays: TypedArrayPoolStats;
+    vec4: { available: number; inUse: number };
+    mat4x4: { available: number; inUse: number };
+}
+
+/**
+ * Global pool manager coordinating all pool types.
+ */
+export declare class PoolManager {
+    typedArrays: TypedArrayPool;
+    vec4: Vec4Pool;
+    mat4x4: Mat4x4Pool;
+
+    constructor();
+
+    /** Initialize Vec4 and Mat4x4 pools with their classes. */
+    initMathPools(Vec4Class: any, Mat4x4Class: any): void;
+
+    /** Register a named custom object pool. */
+    registerPool<T>(name: string, factory: () => T, reset?: ((obj: T) => void) | null, options?: ObjectPoolOptions): ObjectPool<T>;
+
+    /** Get a registered pool by name. */
+    getPool<T = any>(name: string): ObjectPool<T> | undefined;
+
+    /** Clear all pools. */
+    clearAll(): void;
+
+    /** Get combined statistics. */
+    getStats(): PoolManagerStats;
+}
+
+/** Default global pool manager instance. */
+export declare const pools: PoolManager;

package/types/systems/index.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Visualization Systems TypeScript Definitions
+ * QuantumEngine, FacetedSystem, RealHolographicSystem
+ */
+
+import { ParameterManager, VIB3Parameters } from '../core';
+
+// ============================================================================
+// Common
+// ============================================================================
+
+/** Canvas set for 5-layer rendering */
+export interface CanvasSet {
+    background: HTMLCanvasElement;
+    shadow: HTMLCanvasElement;
+    content: HTMLCanvasElement;
+    highlight: HTMLCanvasElement;
+    accent: HTMLCanvasElement;
+}
+
+/** Audio data for reactivity */
+export interface AudioData {
+    bass: number;
+    mid: number;
+    high: number;
+    energy?: number;
+}
+
+/** Render mode: direct WebGL or via UnifiedRenderBridge */
+export type RenderMode = 'direct' | 'bridge';
+
+// ============================================================================
+// QuantumEngine
+// ============================================================================
+
+export interface QuantumEngineOptions {
+    /** Auto-start render loop (default: true) */
+    autoStart?: boolean;
+    /** Single canvas override for content-only mode */
+    canvas?: HTMLCanvasElement;
+    /** Multi-canvas set for 5-layer mode */
+    canvases?: CanvasSet;
+}
+
+/**
+ * Quantum visualization system.
+ * Renders quantum-inspired lattice patterns via procedural fragment shaders.
+ * Supports 5-layer canvas architecture and audio/gesture reactivity.
+ */
+export declare class QuantumEngine {
+    visualizers: any[];
+    parameters: ParameterManager;
+    isActive: boolean;
+    autoStart: boolean;
+    canvasOverride: HTMLCanvasElement | null;
+    canvasSet: CanvasSet | null;
+    audioData: AudioData;
+
+    constructor(options?: QuantumEngineOptions);
+
+    /** Initialize quantum system (creates visualizers, sets up reactivity). */
+    init(): void;
+
+    /** Create visualizers for all 5 layers (or single content layer). */
+    createVisualizers(): void;
+
+    /** Start the render loop. */
+    startRenderLoop(): void;
+
+    /** Stop the render loop. */
+    stopRenderLoop(): void;
+
+    /** Update parameters on all visualizers. */
+    updateParameters(params: Partial<VIB3Parameters>): void;
+
+    /** Set active state. */
+    setActive(active: boolean): void;
+
+    /** Destroy all visualizers and clean up resources. */
+    destroy(): void;
+
+    /** Switch to a geometry variant by index. */
+    switchVariant(index: number): void;
+
+    /** Get current audio data. */
+    getAudioData(): AudioData;
+
+    /** Toggle audio reactivity. */
+    toggleAudio(): Promise<boolean>;
+}
+
+// ============================================================================
+// FacetedSystem
+// ============================================================================
+
+export interface FacetedSystemOptions {
+    /** Prefer WebGPU rendering (default: true) */
+    preferWebGPU?: boolean;
+    /** Single canvas override */
+    canvas?: HTMLCanvasElement;
+    /** Auto-start render loop (default: true) */
+    autoStart?: boolean;
+}
+
+/**
+ * Faceted visualization system.
+ * Renders precise 2D geometric patterns from 4D rotation.
+ * Supports WebGL and WebGPU via UnifiedRenderBridge.
+ * All 24 geometry variants with HSL color control.
+ */
+export declare class FacetedSystem {
+    canvas: HTMLCanvasElement | null;
+    gl: WebGLRenderingContext | null;
+    program: WebGLProgram | null;
+    isActive: boolean;
+    animationFrameId: number | null;
+    startTime: number;
+
+    /** Uniform locations for shader parameters */
+    uniforms: Record<string, WebGLUniformLocation | null>;
+
+    /** Current parameter values */
+    currentParams: {
+        geometry: number;
+        rot4dXY: number;
+        rot4dXZ: number;
+        rot4dYZ: number;
+        rot4dXW: number;
+        rot4dYW: number;
+        rot4dZW: number;
+        dimension: number;
+        gridDensity: number;
+        morphFactor: number;
+        chaos: number;
+        speed: number;
+        hue: number;
+        intensity: number;
+        saturation: number;
+    };
+
+    constructor(options?: FacetedSystemOptions);
+
+    /** Initialize with WebGL/WebGPU context. */
+    init(canvas?: HTMLCanvasElement): Promise<boolean>;
+
+    /** Start the render loop. */
+    startRenderLoop(): void;
+
+    /** Stop the render loop. */
+    stopRenderLoop(): void;
+
+    /** Update parameters. */
+    updateParameters(params: Partial<VIB3Parameters>): void;
+
+    /** Set active state. */
+    setActive(active: boolean): void;
+
+    /** Handle canvas resize. */
+    resize(width: number, height: number, dpr?: number): void;
+
+    /** Destroy and clean up all resources. */
+    destroy(): void;
+
+    /** Get the active backend type ('webgl' | 'webgpu'). */
+    getBackendType(): string;
+}
+
+// ============================================================================
+// RealHolographicSystem
+// ============================================================================
+
+export interface HolographicSystemOptions {
+    /** Single canvas override for content-only mode */
+    canvas?: HTMLCanvasElement;
+    /** Multi-canvas set for 5-layer mode */
+    canvases?: CanvasSet;
+    /** Named relationship profile to load (default: 'holographic') */
+    relationshipProfile?: 'holographic' | 'symmetry' | 'chord' | 'storm' | 'legacy';
+}
+
+/**
+ * Holographic visualization system.
+ * Renders through 5-layer glassmorphic canvas stack with per-layer shaders.
+ * Native microphone input for audio reactivity with beat/melody detection.
+ */
+export declare class RealHolographicSystem {
+    visualizers: any[];
+    currentVariant: number;
+    totalVariants: number;
+    isActive: boolean;
+    canvasOverride: HTMLCanvasElement | null;
+    canvasSet: CanvasSet | null;
+    audioEnabled: boolean;
+    audioContext: AudioContext | null;
+    audioData: AudioData;
+    variantNames: string[];
+
+    constructor(options?: HolographicSystemOptions);
+
+    /** Initialize holographic system. */
+    initialize(): void;
+
+    /** Create visualizers for all 5 layers. */
+    createVisualizers(): void;
+
+    /** Start the render loop. */
+    startRenderLoop(): void;
+
+    /** Stop the render loop. */
+    stopRenderLoop(): void;
+
+    /** Update parameters on all visualizers. */
+    updateParameters(params: Partial<VIB3Parameters>): void;
+
+    /** Set active state. */
+    setActive(active: boolean): void;
+
+    /** Destroy all visualizers and clean up resources. */
+    destroy(): void;
+
+    /** Switch to a variant by index. */
+    switchVariant(index: number): void;
+
+    /** Toggle audio reactivity. */
+    toggleAudio(): Promise<boolean>;
+
+    /** Get variant name by index. */
+    getVariantName(index: number): string;
+
+    /** The layer relationship graph instance. */
+    readonly layerGraph: import('../render/LayerRelationshipGraph').LayerRelationshipGraph;
+
+    /** Load a relationship profile by name. */
+    loadRelationshipProfile(profileName: 'holographic' | 'symmetry' | 'chord' | 'storm' | 'legacy'): void;
+
+    /** Set the keystone (driver) layer. */
+    setKeystone(layerName: 'background' | 'shadow' | 'content' | 'highlight' | 'accent'): void;
+
+    /** Set the relationship for a dependent layer. */
+    setLayerRelationship(
+        layerName: 'background' | 'shadow' | 'content' | 'highlight' | 'accent',
+        relationship: string | Function | { preset: string; config?: Record<string, unknown> }
+    ): void;
+}

package/types/variations/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Variations Module TypeScript Definitions
+ */
+
+import { VIB3Parameters } from '../core';
+
+/** Variation slot */
+export interface VariationSlot {
+    index: number;
+    parameters: VIB3Parameters;
+    name: string;
+    system: string;
+    geometry: number;
+    timestamp: string;
+    thumbnail?: string;
+}
+
+/** Variation generation options */
+export interface VariationOptions {
+    /** Base parameters to deviate from */
+    baseParams: VIB3Parameters;
+    /** Amount of deviation (0-1) */
+    deviation?: number;
+    /** Lock specific parameters from changing */
+    locked?: string[];
+    /** System to generate for */
+    system?: string;
+}
+
+/**
+ * Manages 100 variation slots per system for exploring parameter space.
+ */
+export declare class VariationManager {
+    slots: VariationSlot[];
+    maxSlots: number;
+
+    constructor(maxSlots?: number);
+
+    /** Generate a variation from base parameters. */
+    generate(options: VariationOptions): VariationSlot;
+
+    /** Generate multiple variations at once. */
+    generateBatch(options: VariationOptions, count: number): VariationSlot[];
+
+    /** Get a slot by index. */
+    getSlot(index: number): VariationSlot | undefined;
+
+    /** Save a variation to a slot. */
+    saveSlot(index: number, slot: VariationSlot): void;
+
+    /** Clear a slot. */
+    clearSlot(index: number): void;
+
+    /** Clear all slots. */
+    clearAll(): void;
+
+    /** Export all slots as JSON. */
+    exportAll(): string;
+
+    /** Import slots from JSON. */
+    importAll(json: string): void;
+}