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

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();
+}

package/types/geometry/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Geometry Module TypeScript Definitions
+ * GeometryLibrary, generators, BufferBuilder
+ */
+
+import { Vec4 } from '../math';
+
+// ============================================================================
+// GeometryLibrary
+// ============================================================================
+
+/** Base geometry names (8 types) */
+export type BaseGeometryName = 'TETRAHEDRON' | 'HYPERCUBE' | 'SPHERE' | 'TORUS' | 'KLEIN BOTTLE' | 'FRACTAL' | 'WAVE' | 'CRYSTAL';
+
+/** Variation parameters for a geometry at a given level */
+export interface VariationParameters {
+    gridDensity: number;
+    morphFactor: number;
+    chaos: number;
+    speed: number;
+    hue: number;
+}
+
+/** Static geometry library for the 8 base geometries. */
+export declare class GeometryLibrary {
+    /** Get all 8 geometry names. */
+    static getGeometryNames(): BaseGeometryName[];
+
+    /** Get name for a geometry type index (0-7). Returns 'UNKNOWN' for invalid. */
+    static getGeometryName(type: number): string;
+
+    /** Get variation parameters for a geometry type at a given level. */
+    static getVariationParameters(geometryType: number, level: number): VariationParameters;
+}
+
+// ============================================================================
+// Geometry Object (common return type from generators)
+// ============================================================================
+
+/** Standard geometry output from generators */
+export interface Geometry4D {
+    name: string;
+    vertices: Vec4[];
+    edges: number[][];
+    faces: number[][];
+    cells?: number;
+    vertexCount: number;
+    edgeCount: number;
+    faceCount: number;
+    radius?: number;
+    tubeRadius?: number;
+}
+
+// ============================================================================
+// Generators
+// ============================================================================
+
+// Tesseract
+export declare function generateTesseractVertices(size?: number): Vec4[];
+export declare function generateTesseractEdges(): number[][];
+export declare function generateTesseractFaces(): number[][];
+export declare function generateTesseract(size?: number): Geometry4D;
+export declare function generateTesseractSubdivided(size?: number, subdivisions?: number): Geometry4D;
+
+// Sphere (Hypersphere)
+export declare function generateHypersphereVertices(radius?: number, segments?: number): Vec4[];
+export declare function generateHypersphereFibonacci(radius?: number, count?: number): Vec4[];
+export declare function generateHypersphereEdges(vertices: Vec4[], threshold?: number): number[][];
+export declare function generateSphere(radius?: number, density?: number): Geometry4D;
+
+// Torus
+export declare function generateCliffordTorusVertices(radius?: number, segments?: number): Vec4[];
+export declare function generateCliffordTorusEdges(segments?: number): number[][];
+export declare function generateTorusVertices(majorRadius?: number, minorRadius?: number, majorSegments?: number, minorSegments?: number, wOffset?: number): Vec4[];
+export declare function generateTorus(radius?: number, density?: number): Geometry4D;
+export declare function generateCliffordTorus(radius?: number, tubeRadius?: number, segments?: number): Geometry4D;
+export declare function generateTorus4D(radius?: number, segments?: number): Geometry4D;
+export declare function generate4DTorus(r1?: number, r2?: number, r3?: number, segments?: number): Geometry4D;
+
+// Tetrahedron
+export declare function generateTetrahedron(size?: number): Geometry4D;
+
+// Klein Bottle
+export declare function generateKleinBottle(radius?: number, density?: number): Geometry4D;
+
+// Fractal
+export declare function generateFractal(depth?: number, size?: number): Geometry4D;
+
+// Wave
+export declare function generateWave(amplitude?: number, frequency?: number, segments?: number): Geometry4D;
+
+// Crystal
+export declare function generateCrystal(size?: number, facets?: number): Geometry4D;
+
+// ============================================================================
+// Warp Cores
+// ============================================================================
+
+/** Apply hypersphere (S³) projection warp to geometry vertices. */
+export declare function applyHypersphereWarp(vertices: Vec4[], radius?: number): Vec4[];
+
+/** Apply hypertetrahedron (pentatope) warp to geometry vertices. */
+export declare function applyHypertetraWarp(vertices: Vec4[], scale?: number): Vec4[];
+
+// ============================================================================
+// BufferBuilder
+// ============================================================================
+
+/** Vertex buffer format */
+export type VertexFormat = 'xyz' | 'xyzw';
+
+/** Color generation mode */
+export type ColorMode = 'wDepth' | 'rainbow' | 'uniform';
+
+/** WebGL-ready geometry buffers */
+export interface GeometryBuffers {
+    vertices: Float32Array;
+    vertexCount: number;
+    stride: 3 | 4;
+    edgeIndices?: Uint16Array | Uint32Array;
+    edgeCount?: number;
+    faceIndices?: Uint16Array | Uint32Array;
+    faceCount?: number;
+    normals?: Float32Array;
+    colors?: Float32Array;
+}
+
+export interface GeometryBufferOptions {
+    format?: VertexFormat;
+    includeNormals?: boolean;
+    includeColors?: boolean;
+    colorMode?: ColorMode;
+    uniformColor?: number[];
+    use32BitIndices?: boolean;
+}
+
+/** Build Float32Array vertex buffer from Vec4 vertices. */
+export declare function buildVertexBuffer(vertices: Vec4[], format?: VertexFormat): Float32Array;
+
+/** Build edge index buffer from edge pairs. */
+export declare function buildEdgeIndexBuffer(edges: number[][], use32Bit?: boolean): Uint16Array | Uint32Array;
+
+/** Build triangle index buffer from faces (triangulates quads/polygons). */
+export declare function buildFaceIndexBuffer(faces: number[][], use32Bit?: boolean): Uint16Array | Uint32Array;
+
+/** Build interleaved position + color buffer. */
+export declare function buildInterleavedBuffer(vertices: Vec4[], colors: number[][], format?: VertexFormat): Float32Array;
+
+/** Build normal vectors from vertex and face data. */
+export declare function buildNormalBuffer(vertices: Vec4[], faces: number[][]): Float32Array;
+
+/** Generate W-depth based RGBA colors. */
+export declare function generateWDepthColors(vertices: Vec4[], colorMap?: {
+    nearColor?: number[];
+    farColor?: number[];
+    midColor?: number[];
+    range?: number;
+}): number[][];
+
+/** Generate rainbow RGBA colors by vertex index. */
+export declare function generateRainbowColors(vertexCount: number, saturation?: number, lightness?: number): number[][];
+
+/** Build complete WebGL-ready geometry buffers. */
+export declare function buildGeometryBuffers(geometry: Geometry4D, options?: GeometryBufferOptions): GeometryBuffers;