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

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
     // ========================================================================

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