@vib3code/sdk 2.0.3-canary.91a95f3 → 2.0.3-canary.98b84da

package/types/core/index.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Core Module TypeScript Definitions
+ * CanvasManager, ParameterManager, ParameterMapper, VitalitySystem,
+ * RendererContracts, UnifiedResourceManager
+ */
+
+// ============================================================================
+// CanvasManager
+// ============================================================================
+
+/** 5-layer canvas names */
+export type CanvasLayer = 'background' | 'shadow' | 'content' | 'highlight' | 'accent';
+
+/**
+ * Manages 5-layer canvas architecture per visualization system.
+ * Creates, tracks, and destroys canvases with WebGL context cleanup.
+ */
+export declare class CanvasManager {
+    readonly containerId: string;
+    readonly container: HTMLElement | null;
+    currentSystem: string | null;
+    createdCanvases: HTMLCanvasElement[];
+    registeredContexts: Map<string, WebGLRenderingContext>;
+
+    constructor(containerId?: string);
+
+    /** Create 5 canvases for a system (tears down previous). Returns canvas IDs. */
+    createSystemCanvases(systemName: string): string[];
+
+    /** Track a WebGL context for cleanup on destroy. */
+    registerContext(canvasId: string, gl: WebGLRenderingContext): void;
+
+    /** Destroy all canvases and force-lose WebGL contexts. */
+    destroy(): void;
+}
+
+// ============================================================================
+// ParameterManager
+// ============================================================================
+
+/** Parameter definition for validation */
+export interface ParameterDef {
+    min: number;
+    max: number;
+    step: number;
+    type: 'int' | 'float';
+}
+
+/** Full parameter set */
+export interface VIB3Parameters {
+    variation: 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;
+    geometry: number;
+    [key: string]: number;
+}
+
+/** Exported configuration format */
+export interface ParameterConfiguration {
+    version: string;
+    timestamp: string;
+    parameters: VIB3Parameters;
+    validation: Record<string, ParameterDef>;
+}
+
+/**
+ * Unified parameter control for all visualization systems.
+ * Provides validation, clamping, randomization, HSV conversion,
+ * export/import, and variation generation.
+ */
+export declare class ParameterManager {
+    params: VIB3Parameters;
+    parameterDefs: Record<string, ParameterDef>;
+    defaults: VIB3Parameters;
+
+    constructor();
+
+    /** Get all current parameters (copy). */
+    getAllParameters(): VIB3Parameters;
+
+    /** Set a single parameter with validation and clamping. Returns success. */
+    setParameter(name: string, value: number): boolean;
+
+    /** Set multiple parameters at once. */
+    setParameters(params: Partial<VIB3Parameters>): void;
+
+    /** Reset all parameters to defaults. */
+    resetToDefaults(): void;
+
+    /** Randomize all visual parameters within valid ranges. */
+    randomize(): void;
+
+    /** Export full configuration with validation schema. */
+    exportConfiguration(): ParameterConfiguration;
+
+    /** Load a previously exported configuration. */
+    loadConfiguration(config: ParameterConfiguration): void;
+
+    /** Generate a variation with controlled deviation. */
+    generateVariation(baseParams: VIB3Parameters, deviation: number): VIB3Parameters;
+
+    /** Convert current HSV parameters to RGB. */
+    getColorRGB(): { r: number; g: number; b: number };
+}
+
+// ============================================================================
+// ParameterMapper
+// ============================================================================
+
+/** System name for parameter mapping */
+export type MappableSystem = 'vib34d' | 'holographic' | 'polychora';
+
+/**
+ * Translates parameters between different visualization system formats.
+ * Handles cross-system pollination with influence blending.
+ */
+export declare class ParameterMapper {
+    mappings: Record<string, { to: Record<string, string>; from: Record<string, string> }>;
+
+    constructor();
+
+    /** Translate parameters from one system format to another. */
+    translate(params: Record<string, any>, fromSystem: MappableSystem, toSystem: MappableSystem): Record<string, any>;
+
+    /** Merge parameters with weighted blending. */
+    merge(base: Record<string, any>, overlay: Record<string, any>, influence?: number): Record<string, any>;
+
+    /** Get unified schema spanning all systems. */
+    getUnifiedSchema(): Record<string, ParameterDef>;
+
+    /** Get default values for a system. */
+    getDefaults(system: MappableSystem): Record<string, any>;
+
+    /** Get valid ranges for a system. */
+    getRanges(system: MappableSystem): Record<string, { min: number; max: number }>;
+
+    /** Cross-pollinate: blend parameters from source system into target. */
+    crossPollinate(sourceParams: Record<string, any>, sourceSystem: MappableSystem, targetSystem: MappableSystem, influence?: number): Record<string, any>;
+}
+
+// ============================================================================
+// VitalitySystem
+// ============================================================================
+
+/**
+ * Generates a global rhythmic breath cycle (6-second sine wave)
+ * that modulates all visualization systems for organic animation feel.
+ */
+export declare class VitalitySystem {
+    time: number;
+    breath: number;
+    cycleDuration: number;
+    isRunning: boolean;
+
+    constructor();
+
+    /** Start the breath cycle. */
+    start(): void;
+
+    /** Stop the breath cycle. */
+    stop(): void;
+
+    /** Update and return current breath value (0-1). */
+    update(deltaTime?: number): number;
+
+    /** Get current breath value without updating. */
+    getBreath(): number;
+}
+
+// ============================================================================
+// RendererContracts
+// ============================================================================
+
+/** Frame state passed to render() */
+export interface FrameState {
+    time?: number;
+    params?: Record<string, number>;
+    audio?: { bass: number; mid: number; high: number; energy?: number };
+}
+
+/**
+ * Abstract renderer contract — base class for all visualization systems.
+ * Methods: init, resize, render, setActive, dispose.
+ */
+export declare class RendererContract {
+    init(context?: any): boolean | Promise<boolean>;
+    resize(width: number, height: number, pixelRatio?: number): void;
+    render(frameState?: FrameState): void;
+    setActive(active: boolean): void;
+    dispose(): void;
+}
+
+/**
+ * Adapter providing default implementations of the RendererContract.
+ * Systems can extend this for easier compliance.
+ */
+export declare class RendererContractAdapter extends RendererContract {
+    protected _initialized: boolean;
+    protected _active: boolean;
+    constructor();
+}
+
+/** Verify that an object implements the RendererContract interface. */
+export declare function verifyRendererContract(instance: any): {
+    valid: boolean;
+    missing: string[];
+    errors: string[];
+};
+
+/**
+ * Contract for resource managers used by renderer systems.
+ */
+export declare class ResourceManagerContract {
+    register(type: string, handle: any, disposer?: () => void, options?: { bytes?: number; label?: string }): any;
+    release(type: string, handle: any): boolean;
+    dispose(type: string, handle: any): boolean;
+    disposeAll(): void;
+    getStats(): { totalResources: number; totalBytes: number };
+}
+
+// ============================================================================
+// UnifiedResourceManager
+// ============================================================================
+
+/** GPU resource types managed by UnifiedResourceManager */
+export type GPUResourceType = 'textures' | 'buffers' | 'programs' | 'framebuffers';
+
+/**
+ * Manages GPU resource lifecycle with memory budgeting and eviction.
+ * Tracks textures, buffers, programs, and framebuffers.
+ */
+export declare class UnifiedResourceManager {
+    readonly gl: WebGLRenderingContext;
+    resources: Record<GPUResourceType, Map<string, any>>;
+    memoryBudget: number;
+    currentUsage: number;
+    onMemoryPressure: (() => void) | null;
+
+    constructor(gl: WebGLRenderingContext);
+
+    /** Calculate memory budget based on device capabilities. */
+    calculateMemoryBudget(): number;
+
+    /** Handle memory pressure (evict unused resources). */
+    handleMemoryPressure(): void;
+
+    /** Dispose all tracked resources and stop monitoring. */
+    dispose(): void;
+}

package/types/creative/AestheticMapper.d.ts

@@ -0,0 +1,72 @@
+/**
+ * VIB3+ Aesthetic Mapper Type Definitions
+ * Maps natural language descriptions to VIB3+ parameter ranges.
+ */
+
+export interface ParameterRange {
+    min: number;
+    max: number;
+}
+
+export interface AestheticMapping {
+    params?: Record<string, ParameterRange>;
+    suggested_system?: 'quantum' | 'faceted' | 'holographic';
+    suggested_geometry?: number;
+    color_preset?: string;
+    effects?: string[];
+}
+
+export interface AestheticResult {
+    params: Record<string, ParameterRange>;
+    system: string | null;
+    geometry: number | null;
+    colorPreset: string | null;
+    effects: string[];
+    matchCount: number;
+}
+
+export interface AestheticValues {
+    params: Record<string, number>;
+    system: string | null;
+    geometry: number | null;
+    colorPreset: string | null;
+    effects: string[];
+}
+
+export interface VocabularyEntry {
+    word: string;
+    category: string;
+    mapping: AestheticMapping;
+}
+
+export class AestheticMapper {
+    static VOCABULARY: Record<string, AestheticMapping>;
+
+    constructor();
+
+    /**
+     * Map a text description to parameter ranges.
+     * @param description - Natural language description (e.g., "energetic neon geometric")
+     * @returns Mapped result with params, system, geometry, effects
+     */
+    mapDescription(description: string): AestheticResult;
+
+    /**
+     * Map a description to concrete parameter values (midpoints of ranges).
+     * @param description - Natural language description
+     * @returns Resolved values ready for engine.setParameter()
+     */
+    resolveToValues(description: string): AestheticValues;
+
+    /**
+     * Get all vocabulary words.
+     * @returns Array of vocabulary entries
+     */
+    getVocabulary(): VocabularyEntry[];
+
+    /**
+     * Get vocabulary grouped by category.
+     * @returns Object with category keys and arrays of words
+     */
+    getVocabularyByCategory(): Record<string, string[]>;
+}

package/types/creative/ChoreographyPlayer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * VIB3+ Choreography Player Type Definitions
+ * Sequenced scene playback with transitions and timelines.
+ */
+
+export interface ChoreographyScene {
+    name?: string;
+    duration_ms?: number;
+    system?: 'quantum' | 'faceted' | 'holographic';
+    geometry?: number;
+    parameters?: Record<string, number>;
+    transition?: {
+        type?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'snap';
+        duration_ms?: number;
+    };
+    timeline?: Array<{
+        time_ms: number;
+        parameter: string;
+        value: number;
+        easing?: string;
+    }>;
+}
+
+export interface ChoreographySpec {
+    name?: string;
+    description?: string;
+    loop?: boolean;
+    scenes: ChoreographyScene[];
+    total_duration_ms?: number;
+}
+
+export interface ChoreographyPlayerOptions {
+    onSceneChange?: (sceneIndex: number, scene: ChoreographyScene) => void;
+    onComplete?: () => void;
+    onTick?: (currentTime: number, totalDuration: number) => void;
+}
+
+export interface ChoreographyState {
+    playing: boolean;
+    currentTime: number;
+    totalDuration: number;
+    activeSceneIndex: number;
+    activeSceneName: string | null;
+    loopMode: 'once' | 'loop';
+    playbackSpeed: number;
+    progress: number;
+    sceneCount: number;
+}
+
+export class ChoreographyPlayer {
+    engine: any;
+    spec: ChoreographySpec | null;
+    playing: boolean;
+    currentTime: number;
+    playbackSpeed: number;
+    loopMode: 'once' | 'loop';
+    activeSceneIndex: number;
+
+    constructor(engine: any, options?: ChoreographyPlayerOptions);
+
+    /**
+     * Load a choreography specification.
+     * @param spec - Choreography data from MCP tool or JSON
+     */
+    load(spec: ChoreographySpec): void;
+
+    /** Start or resume playback. */
+    play(): void;
+
+    /** Pause playback (retains position). */
+    pause(): void;
+
+    /** Stop playback and reset to beginning. */
+    stop(): void;
+
+    /**
+     * Seek to a specific time in the choreography.
+     * @param timeMs - Target time in milliseconds
+     */
+    seek(timeMs: number): void;
+
+    /**
+     * Seek to a percentage through the choreography.
+     * @param percent - 0.0 to 1.0
+     */
+    seekToPercent(percent: number): void;
+
+    /**
+     * Get current playback state.
+     * @returns Current player state
+     */
+    getState(): ChoreographyState;
+
+    /** Clean up resources and stop playback. */
+    destroy(): void;
+}

package/types/creative/index.d.ts

@@ -33,3 +33,20 @@ export {
     Keyframe,
     TimelineState
 } from './ParameterTimeline';
+
+export {
+    AestheticMapper,
+    AestheticMapping,
+    AestheticResult,
+    AestheticValues,
+    ParameterRange,
+    VocabularyEntry
+} from './AestheticMapper';
+
+export {
+    ChoreographyPlayer,
+    ChoreographySpec,
+    ChoreographyScene,
+    ChoreographyPlayerOptions,
+    ChoreographyState
+} from './ChoreographyPlayer';

package/types/export/index.d.ts

@@ -0,0 +1,243 @@
+/**
+ * VIB3+ SDK Export Module Type Definitions
+ * @module @vib3code/sdk/export
+ */
+
+// ─── Common Types ───
+
+export interface VIB3Parameters {
+    geometry?: number;
+    gridDensity?: number;
+    morphFactor?: number;
+    chaos?: number;
+    speed?: number;
+    hue?: number;
+    saturation?: number;
+    intensity?: number;
+    dimension?: number;
+    rot4dXY?: number;
+    rot4dXZ?: number;
+    rot4dYZ?: number;
+    rot4dXW?: number;
+    rot4dYW?: number;
+    rot4dZW?: number;
+    system?: 'quantum' | 'faceted' | 'holographic';
+    mouseIntensity?: number;
+    clickIntensity?: number;
+    bass?: number;
+    mid?: number;
+    high?: number;
+    mouse?: [number, number];
+}
+
+// ─── ExportManager ───
+
+export class ExportManager {
+    engine: any;
+    constructor(engine: any);
+    setupFileInputs(): void;
+    exportJSON(): void;
+    saveToGallery(customName?: string | null): void;
+    exportCSS(): void;
+    exportHTML(): void;
+    exportPNG(): void;
+    importJSON(): void;
+    importFolder(): void;
+    handleJSONImport(event: Event): Promise<void>;
+    handleFolderImport(event: Event): Promise<void>;
+    validateConfiguration(config: Record<string, any>): boolean;
+    loadConfiguration(config: Record<string, any>): void;
+    saveAsCustomVariation(config: Record<string, any>): void;
+    downloadFile(content: string, filename: string, mimeType: string): void;
+    getGeometryName(index: number): string;
+}
+
+// ─── ShaderExporter ───
+
+export interface ShaderExportConfig {
+    system?: 'quantum' | 'faceted' | 'holographic';
+    geometry?: number;
+    hue?: number;
+    saturation?: number;
+    intensity?: number;
+    gridDensity?: number;
+    dimension?: number;
+    morphFactor?: number;
+    chaos?: number;
+    speed?: number;
+    rot4dXY?: number;
+    rot4dXZ?: number;
+    rot4dYZ?: number;
+    rot4dXW?: number;
+    rot4dYW?: number;
+    rot4dZW?: number;
+}
+
+export class ShaderExporter {
+    static getQuantumShader(): string;
+    static getFacetedShader(): string;
+    static getHolographicShader(): string;
+    static exportHTML(config: ShaderExportConfig): string;
+}
+
+// ─── SVG Exporter ───
+
+export interface SVGExportOptions {
+    width?: number;
+    height?: number;
+    strokeWidth?: number;
+    includeMetadata?: boolean;
+    includeWatermark?: boolean;
+    watermarkText?: string;
+    backgroundColor?: string;
+    precision?: number;
+}
+
+export function exportSVG(params: VIB3Parameters, options?: SVGExportOptions): string;
+export function downloadSVG(params: VIB3Parameters, options?: SVGExportOptions, filename?: string): void;
+
+// ─── CSS Exporter ───
+
+export interface CSSExportOptions {
+    prefix?: string;
+    includeAnimations?: boolean;
+    includeVariables?: boolean;
+    includeKeyframes?: boolean;
+}
+
+export function exportCSS(params: VIB3Parameters, options?: CSSExportOptions): string;
+export function downloadCSS(params: VIB3Parameters, options?: CSSExportOptions, filename?: string): void;
+export function toStyleObject(params: VIB3Parameters, prefix?: string): Record<string, string>;
+
+// ─── Lottie Exporter ───
+
+export interface LottieExportOptions {
+    width?: number;
+    height?: number;
+    fps?: number;
+    duration?: number;
+    includeMetadata?: boolean;
+}
+
+export function exportLottie(params: VIB3Parameters, options?: LottieExportOptions): Record<string, any>;
+export function downloadLottie(params: VIB3Parameters, options?: LottieExportOptions, filename?: string): void;
+
+// ─── VIB3 Package Exporter ───
+
+export interface VIB3PackageOptions {
+    includeReact?: boolean;
+    includeVue?: boolean;
+    includeSvelte?: boolean;
+    includeCSS?: boolean;
+}
+
+export interface VIB3Package {
+    id: string;
+    version: string;
+    created: string;
+    visual_params: VIB3Parameters;
+    reactivity_config: Record<string, any>;
+    metadata: Record<string, any>;
+    embed_code: string;
+    html_embed: string;
+    css_embed: string;
+    js_embed: string;
+    integrations: Record<string, string>;
+}
+
+export const VIB3_PACKAGE_VERSION: string;
+
+export class VIB3PackageExporter {
+    constructor(options?: VIB3PackageOptions);
+    createPackage(visualParams: VIB3Parameters, reactivityConfig: Record<string, any>, metadata?: Record<string, any>): VIB3Package;
+    generateEmbedCode(visualParams: VIB3Parameters, reactivityConfig: Record<string, any>, packageId: string): string;
+    generateHTMLEmbed(visualParams: VIB3Parameters, reactivityConfig: Record<string, any>, packageId: string): string;
+    generateCSSEmbed(visualParams: VIB3Parameters): string;
+    generateJSEmbed(visualParams: VIB3Parameters, reactivityConfig: Record<string, any>, packageId: string): string;
+    generateIntegrations(packageId: string, visualParams: VIB3Parameters): Record<string, string>;
+    exportToJSON(package_: VIB3Package, pretty?: boolean): string;
+    downloadPackage(package_: VIB3Package, filename?: string | null): void;
+    downloadHTMLEmbed(package_: VIB3Package, filename?: string | null): void;
+    static loadFromJSON(json: string): VIB3Package;
+}
+
+export function createVIB3Package(visualParams: VIB3Parameters, reactivityConfig: Record<string, any>, metadata?: Record<string, any>): VIB3Package;
+
+// ─── Trading Card System ───
+
+export type CardRarity = 'Common' | 'Uncommon' | 'Rare' | 'Epic' | 'Legendary' | 'Mythic';
+
+export interface CardState {
+    system: 'quantum' | 'faceted' | 'holographic';
+    geometry: number;
+    geometryName: string;
+    coreType: string;
+    hue: number;
+    saturation: number;
+    intensity: number;
+    gridDensity: number;
+    dimension: number;
+    morphFactor: number;
+    chaos: number;
+    speed: number;
+    rot4dXW: number;
+    rot4dYW: number;
+    rot4dZW: number;
+    rarity: CardRarity;
+    rarityScore: number;
+}
+
+export class CardGeneratorBase {
+    constructor();
+    generateCard(state: CardState, canvasImage: string): string;
+}
+
+export class FacetedCardGenerator extends CardGeneratorBase {
+    constructor();
+}
+
+export class QuantumCardGenerator extends CardGeneratorBase {
+    constructor();
+}
+
+export class HolographicCardGenerator extends CardGeneratorBase {
+    constructor();
+}
+
+export class TradingCardGenerator {
+    engine: any;
+    constructor(engine: any);
+    detectCurrentSystem(): string;
+    captureCurrentState(): CardState;
+    getActiveGeometryIndex(): number;
+    calculateRarity(params: VIB3Parameters): { rarity: CardRarity; score: number };
+    generateClassicCard(state: CardState, canvasImage: string): string;
+    generateSocialCard(state: CardState, canvasImage: string): string;
+    generateVisualizationCode(state: CardState): string;
+    generateLiveFacetedSystem(state: CardState): string;
+    generateLiveQuantumSystem(state: CardState): string;
+    generateLiveHolographicSystem(state: CardState): string;
+    generateFacetedVisualizationCode(state: CardState): string;
+    generateHolographicVisualizationCode(state: CardState): string;
+    generateFallbackVisualizationCode(state: CardState): string;
+    generateImageVisualization(imageData: string): string;
+}
+
+export class TradingCardManager {
+    engine: any;
+    constructor(engine: any);
+}
+
+// ─── Trading Card Systems (per-renderer) ───
+
+export class TradingCardSystemFaceted {
+    constructor();
+}
+
+export class TradingCardSystemHolographic {
+    constructor();
+}
+
+export class TradingCardSystemQuantum {
+    constructor();
+}