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

package/types/adaptive-sdk.d.ts

@@ -5,14 +5,20 @@
  * 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)
+ *   - core (VIB3Engine, CanvasManager, ParameterManager, ParameterMapper, VitalitySystem, RendererContracts, UnifiedResourceManager)
+ *   - math (constants, projections, rotations, Vec4)
+ *   - geometry (GeometryLibrary, generators, BufferBuilder)
+ *   - systems (QuantumEngine, FacetedSystem, RealHolographicSystem)
+ *   - scene (ObjectPool, TypedArrayPool, Vec4Pool, PoolManager)
+ *   - viewer (ViewerPortal, ViewerInputHandler, GalleryUI, CardBending, AudioReactivity, TradingCardExporter)
+ *   - variations (VariationManager)
+ *   - reactivity (ReactivityManager, ReactivityConfig, SpatialInputSystem)
  *   - render (WebGL/WebGPU backends, ShaderProgram, RenderState, CommandBuffer)
- *   - creative (ColorPresets, TransitionAnimator, PostProcessing, Timeline)
+ *   - creative (ColorPresets, TransitionAnimator, PostProcessing, Timeline, AestheticMapper, ChoreographyPlayer)
  *   - integrations (React, Vue, Svelte, Figma, Three.js, TouchDesigner, OBS)
  *   - advanced (WebXR, WebGPU Compute, MIDI, AI Presets, OffscreenWorker)
+ *   - export (ExportManager, ShaderExporter, VIB3PackageExporter, TradingCardGenerator)
+ *   - agent (MCPServer, AgentCLI, TelemetryService)
  */
 
 // Core engine
@@ -99,6 +105,37 @@ export {
     Shader4DOptions
 } from './render/index';
 
+// Layer relationship system
+export {
+    LayerRelationshipGraph,
+    RelationshipFn,
+    RelationshipPreset,
+    RelationshipConfig,
+    LayerRelationshipProfile,
+    LayerRelationshipExport,
+    LAYER_ORDER as RENDER_LAYER_ORDER,
+    PRESET_REGISTRY,
+    PROFILES
+} from './render/LayerRelationshipGraph';
+
+// Layer preset manager
+export {
+    LayerPresetManager,
+    LayerPreset,
+    PresetMetadata,
+    PresetLibrary,
+    PresetManagerOptions
+} from './render/LayerPresetManager';
+
+// Layer reactivity bridge
+export {
+    LayerReactivityBridge,
+    ModulationMapping,
+    InputState as LayerInputState,
+    ReactivityBridgeConfig,
+    MODULATION_PROFILES
+} from './render/LayerReactivityBridge';
+
 // Creative tooling
 export {
     ColorPresetsSystem,
@@ -183,3 +220,165 @@ export {
     WorkerSwitchMessage,
     WorkerResizeMessage
 } from './advanced/index';
+
+// Export system
+export {
+    ExportManager,
+    ShaderExporter,
+    VIB3PackageExporter,
+    TradingCardGenerator,
+    TradingCardManager,
+    CardGeneratorBase,
+    FacetedCardGenerator,
+    QuantumCardGenerator,
+    HolographicCardGenerator,
+    TradingCardSystemFaceted,
+    TradingCardSystemHolographic,
+    TradingCardSystemQuantum,
+    VIB3_PACKAGE_VERSION,
+    exportSVG,
+    downloadSVG,
+    exportCSS,
+    downloadCSS,
+    toStyleObject,
+    exportLottie,
+    downloadLottie,
+    createVIB3Package
+} from './export/index';
+
+// Core - expanded types (CanvasManager, Parameters, RendererContracts, etc.)
+export {
+    CanvasManager,
+    CanvasLayer,
+    ParameterManager,
+    ParameterDef,
+    VIB3Parameters,
+    ParameterConfiguration,
+    ParameterMapper,
+    MappableSystem,
+    VitalitySystem,
+    RendererContract,
+    RendererContractAdapter,
+    ResourceManagerContract,
+    FrameState,
+    UnifiedResourceManager
+} from './core/index';
+
+// Math - constants, projections, rotations, Vec4
+export {
+    PI, TAU, HALF_PI, QUARTER_PI,
+    DEG_TO_RAD, RAD_TO_DEG,
+    EPSILON,
+    PHI, PHI_INV,
+    PLANE_NAMES as ROTATION_PLANE_NAMES,
+    encodeGeometry,
+    decodeGeometry,
+    toRadians,
+    toDegrees,
+    clamp,
+    lerp,
+    smoothstep,
+    smootherstep,
+    perspectiveProject4D,
+    stereographicProject4D,
+    ProjectionResult,
+    createRotationMatrix4D,
+    identityMatrix4x4,
+    multiplyMatrix4x4,
+    transposeMatrix4x4,
+    applyMatrix4x4,
+    vectorLength4D,
+    normalizeVector4D,
+    normalizeRotationAngles,
+    composeRotationMatrixFromAngles,
+    RotationPlane,
+    Matrix4x4,
+    Vector4D,
+    Vec4
+} from './math/index';
+
+// Geometry - library, generators, buffers
+export {
+    GeometryLibrary,
+    Geometry4D,
+    VariationParameters,
+    GeometryBuffers,
+    buildVertexBuffer,
+    buildEdgeIndexBuffer,
+    buildFaceIndexBuffer,
+    buildGeometryBuffers,
+    generateTesseract,
+    generateSphere,
+    generateTorus
+} from './geometry/index';
+
+// Visualization systems
+export {
+    QuantumEngine,
+    QuantumEngineOptions,
+    FacetedSystem,
+    FacetedSystemOptions,
+    RealHolographicSystem,
+    HolographicSystemOptions,
+    CanvasSet,
+    AudioData,
+    RenderMode
+} from './systems/index';
+
+// Scene - memory pools
+export {
+    ObjectPool,
+    TypedArrayPool,
+    Vec4Pool,
+    Mat4x4Pool,
+    PoolManager,
+    pools,
+    PoolStats,
+    ObjectPoolOptions
+} from './scene/index';
+
+// Viewer - portal, input, gallery, cards
+export {
+    ViewerPortal,
+    ViewerInputHandler,
+    GalleryUI,
+    CardBending,
+    AudioReactivity as ViewerAudioReactivity,
+    TradingCardExporter,
+    PortalMode,
+    RotationState,
+    InputSource,
+    InputPreset,
+    GalleryViewMode,
+    BendPreset,
+    FrameStyle,
+    RarityLevel
+} from './viewer/index';
+
+// Variations
+export {
+    VariationManager,
+    VariationSlot,
+    VariationOptions
+} from './variations/index';
+
+// Agent system
+export {
+    MCPServer,
+    mcpServer,
+    toolDefinitions,
+    AgentCLI,
+    BatchExecutor,
+    CommandType,
+    ResponseStatus,
+    TelemetryService,
+    TelemetrySpan,
+    EventType,
+    telemetry,
+    EventStreamServer,
+    EventStreamClient,
+    PrometheusExporter,
+    JSONExporter,
+    NDJSONExporter,
+    ConsoleExporter
+} from './agent/index';

package/types/agent/cli.d.ts

@@ -0,0 +1,78 @@
+/**
+ * VIB3+ Agent CLI Type Definitions
+ */
+import { EventEmitter } from 'events';
+
+export declare const CommandType: {
+    SET_PARAMETER: 'set_parameter';
+    GET_PARAMETER: 'get_parameter';
+    SET_GEOMETRY: 'set_geometry';
+    SET_SYSTEM: 'set_system';
+    ROTATE: 'rotate';
+    RESET_ROTATION: 'reset_rotation';
+    BATCH: 'batch';
+    BATCH_ROTATE: 'batch_rotate';
+    GET_METRICS: 'get_metrics';
+    GET_SPANS: 'get_spans';
+    FLUSH_TELEMETRY: 'flush_telemetry';
+    PING: 'ping';
+    STATUS: 'status';
+    HELP: 'help';
+    QUIT: 'quit';
+};
+
+export declare const ResponseStatus: {
+    OK: 'ok';
+    ERROR: 'error';
+    PARTIAL: 'partial';
+};
+
+export interface CLIOptions {
+    inputStream?: NodeJS.ReadableStream;
+    outputStream?: NodeJS.WritableStream;
+    errorStream?: NodeJS.WritableStream;
+    format?: 'jsonl' | 'json' | 'text';
+    pretty?: boolean;
+    enableTelemetry?: boolean;
+}
+
+export interface CLICommand {
+    type: string;
+    id?: string;
+    [key: string]: any;
+}
+
+export interface CLIResponse {
+    id?: string;
+    status: 'ok' | 'error' | 'partial';
+    result?: any;
+    error?: string;
+    durationMs?: number;
+}
+
+export class AgentCLI extends EventEmitter {
+    engine: any;
+    options: CLIOptions;
+    constructor(engine: any, options?: CLIOptions);
+    start(): void;
+    stop(): void;
+    registerHandler(type: string, handler: (command: CLICommand) => any | Promise<any>): void;
+    execute(command: CLICommand): Promise<any>;
+}
+
+export class BatchExecutor {
+    cli: AgentCLI;
+    queue: CLICommand[];
+    results: Array<{ status: string; command: string; result?: any; error?: string }>;
+    constructor(cli: AgentCLI);
+    add(command: CLICommand): this;
+    execute(): Promise<Array<{ status: string; command: string; result?: any; error?: string }>>;
+    executeParallel(): Promise<Array<{ status: string; command: string; result?: any; error?: string }>>;
+}
+
+export interface StreamingCLIResult {
+    cli: AgentCLI;
+    streamServer: any;
+}
+
+export function createStreamingCLI(engine: any, httpServer: any, options?: CLIOptions): StreamingCLIResult;

package/types/agent/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * VIB3+ SDK Agent Module Type Definitions
+ * @module @vib3code/sdk/agent
+ */
+
+// ─── Re-exports ───
+export { MCPServer, mcpServer, toolDefinitions, getToolList, getToolNames, getTool, validateToolInput } from './mcp';
+export { AgentCLI, BatchExecutor, CommandType, ResponseStatus, createStreamingCLI } from './cli';
+export {
+    TelemetryService, TelemetrySpan, EventType, SpanStatus,
+    withTelemetry, withTelemetrySync, telemetry,
+    PrometheusExporter, JSONExporter, NDJSONExporter, ConsoleExporter, createExporter,
+    StreamEventType, EventStreamServer, EventStreamClient, SSEConnection,
+    createSSEHandler, connectTelemetryToStream,
+    configureTelemetry, getTelemetry, trace, traceFunction,
+    traceAsyncIterable, instrumentClass, traceObject, withTiming,
+    meter, traceBatch, TraceContext
+} from './telemetry';

package/types/agent/mcp.d.ts

@@ -0,0 +1,87 @@
+/**
+ * VIB3+ MCP Server Type Definitions
+ */
+
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, any>;
+}
+
+export interface ToolResponse {
+    success: boolean;
+    operation: string;
+    timestamp: string;
+    duration_ms?: number;
+    error?: {
+        type: string;
+        code: string;
+        message: string;
+        suggestion?: string;
+    };
+    [key: string]: any;
+}
+
+export interface RotationArgs {
+    XY?: number;
+    XZ?: number;
+    YZ?: number;
+    XW?: number;
+    YW?: number;
+    ZW?: number;
+}
+
+export interface VisualParameterArgs {
+    hue?: number;
+    saturation?: number;
+    intensity?: number;
+    speed?: number;
+    chaos?: number;
+    morphFactor?: number;
+    gridDensity?: number;
+    dimension?: number;
+}
+
+export interface GeometryArgs {
+    geometry_index?: number;
+    base_geometry?: number;
+    core_type?: number;
+}
+
+export class MCPServer {
+    constructor(engine?: any);
+    setEngine(engine: any): void;
+    buildResponse(operation: string, data: Record<string, any>, options?: { success?: boolean; startTime?: number }): ToolResponse;
+    validateToolResponse(response: ToolResponse): ToolResponse;
+    handleToolCall(toolName: string, args?: Record<string, any>): Promise<ToolResponse>;
+    createVisualization(args: { system?: string; geometry_index?: number; projection?: string }): Promise<ToolResponse>;
+    setRotation(args: RotationArgs): ToolResponse;
+    setVisualParameters(args: VisualParameterArgs): ToolResponse;
+    switchSystem(args: { system: string }): Promise<ToolResponse>;
+    changeGeometry(args: GeometryArgs): ToolResponse;
+    getState(): ToolResponse;
+    randomizeParameters(args?: { preserve_system?: boolean; preserve_geometry?: boolean }): ToolResponse;
+    resetParameters(): ToolResponse;
+    saveToGallery(args: { name?: string }): ToolResponse;
+    loadFromGallery(args: { id?: number; name?: string }): ToolResponse;
+    searchGeometries(args: { core_type?: string; query?: string }): ToolResponse;
+    getParameterSchema(): ToolResponse;
+    getSDKContext(): ToolResponse;
+    listTools(includeSchemas?: boolean): ToolDefinition[];
+    setReactivityConfig(args: Record<string, any>): ToolResponse;
+    getReactivityConfig(): ToolResponse;
+    configureAudioBand(args: Record<string, any>): ToolResponse;
+    exportPackage(args: Record<string, any>): ToolResponse;
+    applyBehaviorPreset(args: { preset: string }): ToolResponse;
+    listBehaviorPresets(): ToolResponse;
+    describeVisualState(): ToolResponse;
+    batchSetParameters(args: { parameters: Record<string, any>[] }): Promise<ToolResponse>;
+}
+
+export const mcpServer: MCPServer;
+export const toolDefinitions: ToolDefinition[];
+
+export function getToolList(): ToolDefinition[];
+export function getToolNames(): string[];
+export function getTool(name: string): ToolDefinition | undefined;
+export function validateToolInput(toolName: string, input: Record<string, any>): { valid: boolean; errors?: string[] };

package/types/agent/telemetry.d.ts

@@ -0,0 +1,190 @@
+/**
+ * VIB3+ Telemetry Type Definitions
+ */
+import { EventEmitter } from 'events';
+
+// ─── Event Types ───
+
+export declare const EventType: {
+    TOOL_INVOCATION: string;
+    TOOL_ERROR: string;
+    SYSTEM_SWITCH: string;
+    PARAMETER_CHANGE: string;
+    RENDER_FRAME: string;
+    AUDIO_UPDATE: string;
+    ERROR: string;
+    LIFECYCLE: string;
+    PERFORMANCE: string;
+};
+
+export declare const SpanStatus: {
+    UNSET: 'unset';
+    OK: 'ok';
+    ERROR: 'error';
+};
+
+// ─── TelemetrySpan ───
+
+export interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes: Record<string, any>;
+}
+
+export class TelemetrySpan {
+    name: string;
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    startTime: number;
+    endTime: number | null;
+    duration: number | null;
+    status: string;
+    statusMessage: string | null;
+    attributes: Record<string, any>;
+    events: SpanEvent[];
+
+    constructor(name: string, traceId: string, parentSpanId?: string | null, attributes?: Record<string, any>);
+    addEvent(name: string, attributes?: Record<string, any>): void;
+    setAttribute(key: string, value: any): void;
+    setAttributes(attrs: Record<string, any>): void;
+    setStatus(status: string, message?: string | null): void;
+    end(): void;
+    toJSON(): Record<string, any>;
+}
+
+// ─── TelemetryService ───
+
+export interface TelemetryOptions {
+    maxSpans?: number;
+    maxEvents?: number;
+    flushIntervalMs?: number;
+    enabled?: boolean;
+}
+
+export interface TelemetryMetrics {
+    spans_total: number;
+    events_total: number;
+    errors_total: number;
+    tool_invocations: number;
+    render_frames: number;
+    [key: string]: number;
+}
+
+export class TelemetryService {
+    constructor(options?: TelemetryOptions);
+    startTrace(): string;
+    getTraceId(): string;
+    createSpan(name: string, attributes?: Record<string, any>, parentSpanId?: string | null): TelemetrySpan;
+    recordSpan(span: TelemetrySpan): void;
+    recordEvent(type: string, attributes?: Record<string, any>): void;
+    subscribe(eventType: string, callback: (data: any) => void): () => void;
+    emit(eventType: string, data: any): void;
+    flush(): { spans: any[]; events: any[]; metrics: TelemetryMetrics };
+    getMetrics(): TelemetryMetrics;
+    getSpans(): TelemetrySpan[];
+    resetMetrics(): void;
+    setEnabled(enabled: boolean): void;
+    destroy(): void;
+}
+
+export const telemetry: TelemetryService;
+
+export function withTelemetry<T>(service: TelemetryService, operationName: string, fn: (span: TelemetrySpan) => Promise<T>, attributes?: Record<string, any>): Promise<T>;
+export function withTelemetrySync<T>(service: TelemetryService, operationName: string, fn: (span: TelemetrySpan) => T, attributes?: Record<string, any>): T;
+
+// ─── Exporters ───
+
+export class PrometheusExporter {
+    export(metrics: TelemetryMetrics): string;
+}
+
+export class JSONExporter {
+    export(data: any): string;
+}
+
+export class NDJSONExporter {
+    export(data: any[]): string;
+}
+
+export class ConsoleExporter {
+    export(data: any): void;
+}
+
+export function createExporter(type: 'prometheus' | 'json' | 'ndjson' | 'console', options?: Record<string, any>): PrometheusExporter | JSONExporter | NDJSONExporter | ConsoleExporter;
+
+// ─── Event Streaming ───
+
+export declare const StreamEventType: {
+    SPAN_START: string;
+    SPAN_END: string;
+    METRIC: string;
+    ERROR: string;
+    HEARTBEAT: string;
+    TELEMETRY: string;
+};
+
+export interface StreamEvent {
+    type: string;
+    data: any;
+    id?: string;
+    channel?: string;
+    timestamp?: number;
+}
+
+export class EventStreamServer extends EventEmitter {
+    constructor(options?: { heartbeatIntervalMs?: number; maxReplayBuffer?: number; channels?: string[] });
+    handleConnection(req: any, res: any, options?: { channel?: string; filters?: string[] }): void;
+    broadcast(event: StreamEvent, channel?: string): void;
+    sendTo(connectionId: string, event: StreamEvent): void;
+    streamTelemetry(telemetryEvent: any): void;
+    streamSpanStart(span: TelemetrySpan): void;
+    streamSpanEnd(span: TelemetrySpan): void;
+    streamMetric(name: string, value: number, labels?: Record<string, string>): void;
+    streamError(error: Error): void;
+    getConnectionIds(): string[];
+    closeConnection(connectionId: string): void;
+    close(): void;
+}
+
+export class SSEConnection {
+    id: string;
+    constructor(options: { req: any; res: any; channel?: string; filters?: string[] });
+    send(event: StreamEvent): void;
+    matchesChannel(channel: string): boolean;
+    matchesFilters(event: StreamEvent): boolean;
+    close(): void;
+}
+
+export class EventStreamClient extends EventEmitter {
+    constructor(url: string, options?: { autoReconnect?: boolean; maxRetries?: number; retryDelayMs?: number });
+    connect(): void;
+    disconnect(): void;
+}
+
+export function createSSEHandler(server: EventStreamServer): (req: any, res: any) => void;
+export function connectTelemetryToStream(telemetryService: TelemetryService, streamServer: EventStreamServer): void;
+
+// ─── Instrumentation ───
+
+export function configureTelemetry(telemetryService: TelemetryService): void;
+export function getTelemetry(): TelemetryService;
+
+export interface TraceOptions {
+    attributes?: Record<string, any>;
+    recordArgs?: boolean;
+    recordResult?: boolean;
+}
+
+export function trace(spanName: string, options?: TraceOptions): MethodDecorator;
+export function traceFunction<T extends (...args: any[]) => any>(fn: T, name?: string, options?: TraceOptions): T;
+export function traceAsyncIterable<T>(iterable: AsyncIterable<T>, name: string, options?: TraceOptions): AsyncIterable<T>;
+export function instrumentClass(ClassConstructor: new (...args: any[]) => any, options?: { methods?: string[]; exclude?: string[] }): void;
+export function traceObject(target: Record<string, any>, name: string, options?: { methods?: string[] }): Record<string, any>;
+export function withTiming<T>(fn: () => T, callback: (durationMs: number) => void): T;
+export function meter(metricName: string, options?: { unit?: string; description?: string }): (value: number, labels?: Record<string, string>) => void;
+export function traceBatch(operations: Array<() => any>, name: string): Promise<any[]>;
+
+export class TraceContext {
+    constructor(telemetry: TelemetryService);
+}

package/types/core/VIB3Engine.d.ts

@@ -14,6 +14,8 @@ export type BackendType = 'webgl' | 'webgpu' | 'direct-webgl' | null;
 
 /** VIB3Engine constructor options */
 export interface VIB3EngineOptions {
+    /** Initial system to create (default: 'quantum') */
+    system?: SystemName;
     /** Prefer WebGPU with WebGL fallback (default: true) */
     preferWebGPU?: boolean;
     /** Enable debug logging (default: false) */
@@ -195,6 +197,30 @@ export declare class VIB3Engine {
     /** Import engine state (restores system, parameters, and reactivity) */
     importState(state: Partial<VIB3EngineState>): Promise<void>;
 
+    // ========================================================================
+    // Convenience Methods
+    // ========================================================================
+
+    /**
+     * Create a parameter update callback for creative modules.
+     * Returns `(name, value) => void` that calls `setParameter` internally.
+     * Eliminates boilerplate wiring.
+     */
+    createParameterCallback(): (name: string, value: number) => void;
+
+    /**
+     * Get current breath value from VitalitySystem (0-1).
+     * Avoids reaching into `engine.vitality.getBreath()` directly.
+     */
+    getBreath(): number;
+
+    /**
+     * Register a listener for parameter changes.
+     * Callback receives the full parameter object after each change.
+     * @returns Unsubscribe function
+     */
+    onParameterChange(callback: (params: Record<string, number>) => void): () => void;
+
     // ========================================================================
     // Lifecycle
     // ========================================================================