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

package/types/math/index.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Math Module TypeScript Definitions
+ * Constants, projections, rotations, Vec4
+ */
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export declare const PI: number;
+export declare const TAU: number;
+export declare const HALF_PI: number;
+export declare const QUARTER_PI: number;
+
+export declare const DEG_TO_RAD: number;
+export declare const RAD_TO_DEG: number;
+
+export declare const EPSILON: number;
+export declare const EPSILON_NORMAL: number;
+export declare const EPSILON_EQUAL: number;
+
+export declare const PHI: number;
+export declare const PHI_INV: number;
+
+// 4D Polytope topology constants
+export declare const TESSERACT_VERTICES: 16;
+export declare const TESSERACT_EDGES: 32;
+export declare const TESSERACT_FACES: 24;
+export declare const TESSERACT_CELLS: 8;
+
+export declare const CELL24_VERTICES: 24;
+export declare const CELL24_EDGES: 96;
+export declare const CELL24_FACES: 96;
+export declare const CELL24_CELLS: 24;
+
+export declare const CELL120_VERTICES: 600;
+export declare const CELL120_EDGES: 1200;
+export declare const CELL120_FACES: 720;
+export declare const CELL120_CELLS: 120;
+
+export declare const CELL600_VERTICES: 120;
+export declare const CELL600_EDGES: 720;
+export declare const CELL600_FACES: 1200;
+export declare const CELL600_CELLS: 600;
+
+// Rotation plane indices
+export declare const PLANE_XY: 0;
+export declare const PLANE_XZ: 1;
+export declare const PLANE_YZ: 2;
+export declare const PLANE_XW: 3;
+export declare const PLANE_YW: 4;
+export declare const PLANE_ZW: 5;
+
+export declare const PLANE_NAMES: ['XY', 'XZ', 'YZ', 'XW', 'YW', 'ZW'];
+
+// Base geometry indices
+export declare const GEOMETRY_TETRAHEDRON: 0;
+export declare const GEOMETRY_HYPERCUBE: 1;
+export declare const GEOMETRY_SPHERE: 2;
+export declare const GEOMETRY_TORUS: 3;
+export declare const GEOMETRY_KLEIN: 4;
+export declare const GEOMETRY_FRACTAL: 5;
+export declare const GEOMETRY_WAVE: 6;
+export declare const GEOMETRY_CRYSTAL: 7;
+
+// Core type indices
+export declare const CORE_BASE: 0;
+export declare const CORE_HYPERSPHERE: 1;
+export declare const CORE_HYPERTETRAHEDRON: 2;
+
+/** Encode base + core type into geometry index (0-23). */
+export declare function encodeGeometry(baseIndex: number, coreIndex: number): number;
+
+/** Decode geometry index into base and core type. */
+export declare function decodeGeometry(geometryIndex: number): { baseIndex: number; coreIndex: number };
+
+/** Convert degrees to radians. */
+export declare function toRadians(degrees: number): number;
+
+/** Convert radians to degrees. */
+export declare function toDegrees(radians: number): number;
+
+/** Clamp value to [min, max]. */
+export declare function clamp(value: number, min: number, max: number): number;
+
+/** Linear interpolation: a + (b - a) * t. */
+export declare function lerp(a: number, b: number, t: number): number;
+
+/** Smooth Hermite interpolation (cubic). */
+export declare function smoothstep(t: number): number;
+
+/** Smoother step interpolation (quintic). */
+export declare function smootherstep(t: number): number;
+
+// ============================================================================
+// Projections
+// ============================================================================
+
+/** Result of a 4D→3D projection */
+export interface ProjectionResult {
+    x: number;
+    y: number;
+    z: number;
+    denom: number;
+}
+
+/** Options for perspective projection */
+export interface PerspectiveOptions {
+    /** Projection distance (default: 2) */
+    distance?: number;
+    /** Minimum absolute denominator (default: 1e-5) */
+    epsilon?: number;
+}
+
+/** Options for stereographic projection */
+export interface StereographicOptions {
+    /** Minimum absolute denominator (default: 1e-5) */
+    epsilon?: number;
+}
+
+/**
+ * Perspective projection: P.xyz = v.xyz / (distance - v.w)
+ * Most intuitive projection — closer objects appear larger.
+ */
+export declare function perspectiveProject4D(v: number[], options?: PerspectiveOptions): ProjectionResult;
+
+/**
+ * Stereographic projection: P.xyz = v.xyz / (1 - v.w)
+ * Conformal — preserves angles locally.
+ */
+export declare function stereographicProject4D(v: number[], options?: StereographicOptions): ProjectionResult;
+
+// ============================================================================
+// Rotations
+// ============================================================================
+
+/** Canonical rotation plane name */
+export type RotationPlane = 'XY' | 'XZ' | 'YZ' | 'XW' | 'YW' | 'ZW';
+
+/** 16-element column-major 4×4 matrix */
+export type Matrix4x4 = number[];
+
+/** 4-element vector [x, y, z, w] */
+export type Vector4D = number[];
+
+/** Sparse angle map (plane name → angle in radians) */
+export type AngleMap = Partial<Record<RotationPlane, number>>;
+
+export declare const ROTATION_PLANES: RotationPlane[];
+
+/** Create a 4D rotation matrix for a given plane and angle. */
+export declare function createRotationMatrix4D(plane: RotationPlane | string, angle: number): Matrix4x4;
+
+/** Return a 16-element identity matrix. */
+export declare function identityMatrix4x4(): Matrix4x4;
+
+/** Multiply two 16-element column-major matrices. */
+export declare function multiplyMatrix4x4(a: Matrix4x4, b: Matrix4x4): Matrix4x4;
+
+/** Transpose a 16-element column-major matrix. */
+export declare function transposeMatrix4x4(m: Matrix4x4): Matrix4x4;
+
+/** Apply a 4×4 matrix to a 4-element vector. */
+export declare function applyMatrix4x4(m: Matrix4x4, v: Vector4D): Vector4D;
+
+/** Compute Euclidean length of a 4D vector. */
+export declare function vectorLength4D(v: Vector4D): number;
+
+/** Normalize a 4D vector to unit length. */
+export declare function normalizeVector4D(v: Vector4D): Vector4D;
+
+/** Normalize angle keys to uppercase, filling missing planes with 0. */
+export declare function normalizeRotationAngles(angles: Record<string, number>): Record<RotationPlane, number>;
+
+/** Create rotation matrices for all 6 planes from an angle map. */
+export declare function createRotationMatricesFromAngles(angles: Record<string, number>): Record<RotationPlane, Matrix4x4>;
+
+/** Compose a single rotation matrix from angles (XY*XZ*YZ*XW*YW*ZW order). */
+export declare function composeRotationMatrixFromAngles(angles: Record<string, number>): Matrix4x4;
+
+// ============================================================================
+// Vec4
+// ============================================================================
+
+/** 4D vector class */
+export declare class Vec4 {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+
+    constructor(x?: number, y?: number, z?: number, w?: number);
+
+    /** Linear interpolation to another Vec4. */
+    lerp(other: Vec4, t: number): Vec4;
+
+    /** Euclidean distance to another Vec4. */
+    distanceTo(other: Vec4): number;
+
+    /** Vector length. */
+    length(): number;
+
+    /** Normalize to unit length. */
+    normalize(): Vec4;
+
+    /** Dot product. */
+    dot(other: Vec4): number;
+
+    /** Clone this vector. */
+    clone(): Vec4;
+
+    /** Convert to array [x, y, z, w]. */
+    toArray(): number[];
+}

package/types/render/LayerPresetManager.d.ts

@@ -0,0 +1,78 @@
+/**
+ * LayerPresetManager TypeScript Definitions
+ */
+
+import { LayerRelationshipGraph } from './LayerRelationshipGraph';
+
+export interface PresetMetadata {
+    description?: string;
+    author?: string;
+    tags?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+
+export interface LayerPreset {
+    name: string;
+    config: ReturnType<LayerRelationshipGraph['exportConfig']>;
+    metadata: PresetMetadata;
+}
+
+export interface PresetLibrary {
+    version: string;
+    type: 'vib3_layer_presets';
+    exportedAt: string;
+    count: number;
+    presets: Record<string, LayerPreset>;
+}
+
+export interface PresetManagerOptions {
+    storage?: Storage | null;
+    storageKey?: string;
+}
+
+export declare class LayerPresetManager {
+    constructor(graph: LayerRelationshipGraph, options?: PresetManagerOptions);
+
+    /** Save the current graph state as a named preset. */
+    save(name: string, metadata?: Partial<PresetMetadata>): LayerPreset;
+
+    /** Load a preset by name into the live graph. */
+    load(name: string): boolean;
+
+    /** Delete a user preset. */
+    delete(name: string): boolean;
+
+    /** Check if a preset exists (user or built-in). */
+    has(name: string): boolean;
+
+    /** Get a preset's data without loading it. */
+    get(name: string): LayerPreset | null;
+
+    /** List all available presets. */
+    list(): { user: string[]; builtIn: string[] };
+
+    /** List all preset names as a flat array. */
+    listAll(): string[];
+
+    /** Number of user presets. */
+    readonly count: number;
+
+    /** Tune a layer's relationship config at runtime. */
+    tune(layerName: string, configOverrides: Record<string, unknown>): boolean;
+
+    /** Get the current config for a layer. */
+    getLayerConfig(layerName: string): { preset: string; config: Record<string, unknown> } | null;
+
+    /** Export all user presets as a library. */
+    exportLibrary(): PresetLibrary;
+
+    /** Import presets from a library. */
+    importLibrary(library: PresetLibrary, options?: { overwrite?: boolean }): { imported: number; skipped: number };
+
+    /** Clear all user presets. */
+    clear(): void;
+}
+
+export default LayerPresetManager;

package/types/render/LayerReactivityBridge.d.ts

@@ -0,0 +1,85 @@
+/**
+ * LayerReactivityBridge TypeScript Definitions
+ */
+
+import { LayerRelationshipGraph } from './LayerRelationshipGraph';
+import { LayerPresetManager } from './LayerPresetManager';
+
+export interface ModulationMapping {
+    source: 'audio' | 'tilt' | 'mouse' | 'click' | 'custom';
+    channel: string;
+    layerName: string;
+    configKey: string;
+    scale: number;
+    baseline: number;
+    min?: number;
+    max?: number;
+    mode?: 'add' | 'multiply';
+}
+
+export interface InputState {
+    audio?: { bass?: number; mid?: number; high?: number; energy?: number };
+    tilt?: { alpha?: number; beta?: number; gamma?: number };
+    mouse?: { x?: number; y?: number; velocityX?: number; velocityY?: number };
+    click?: { intensity?: number };
+    custom?: Record<string, number>;
+}
+
+export interface ReactivityBridgeConfig {
+    profile: string | null;
+    mappings: ModulationMapping[];
+    active: boolean;
+}
+
+export declare const MODULATION_PROFILES: Record<string, ModulationMapping[]>;
+
+export declare class LayerReactivityBridge {
+    constructor(graph: LayerRelationshipGraph, presetManager?: LayerPresetManager | null);
+
+    /** Add a single modulation mapping. */
+    addModulation(
+        source: string,
+        channel: string,
+        layerName: string,
+        configKey: string,
+        options?: Partial<Pick<ModulationMapping, 'scale' | 'baseline' | 'min' | 'max' | 'mode'>>
+    ): void;
+
+    /** Remove all modulation mappings for a specific layer. */
+    removeModulationsForLayer(layerName: string): number;
+
+    /** Remove all modulation mappings. */
+    clearModulations(): void;
+
+    /** Load a pre-built modulation profile. */
+    loadModulationProfile(profileName: string): boolean;
+
+    /** Available modulation profile names. */
+    static readonly profileNames: string[];
+
+    /** Active modulation profile name. */
+    readonly activeProfile: string | null;
+
+    /** All current modulation mappings. */
+    readonly mappings: ModulationMapping[];
+
+    /** Enable modulation processing. */
+    activate(): void;
+
+    /** Disable modulation processing. */
+    deactivate(): void;
+
+    /** Whether modulation is active. */
+    readonly isActive: boolean;
+
+    /** Process input state and apply modulations. */
+    update(inputState: InputState): Record<string, Record<string, number>>;
+
+    /** Export modulation configuration. */
+    exportConfig(): ReactivityBridgeConfig;
+
+    /** Import modulation configuration. */
+    importConfig(config: ReactivityBridgeConfig): void;
+}
+
+export default LayerReactivityBridge;

package/types/render/LayerRelationshipGraph.d.ts

@@ -0,0 +1,174 @@
+/**
+ * LayerRelationshipGraph — TypeScript definitions
+ *
+ * Keystone-driven inter-layer parameter system for the VIB3+ 5-layer canvas architecture.
+ */
+
+/** Standard layer names, back to front */
+export type LayerName = 'background' | 'shadow' | 'content' | 'highlight' | 'accent';
+
+/** Layer order array */
+export declare const LAYER_ORDER: readonly LayerName[];
+
+/**
+ * A relationship function takes keystone parameters and time,
+ * and returns derived parameters for a dependent layer.
+ */
+export type RelationshipFn = (keystoneParams: Record<string, unknown>, time: number) => Record<string, unknown>;
+
+/** Available preset relationship names */
+export type RelationshipPreset = 'echo' | 'mirror' | 'complement' | 'harmonic' | 'reactive' | 'chase';
+
+/** Available profile names */
+export type RelationshipProfileName = 'holographic' | 'symmetry' | 'chord' | 'storm' | 'legacy';
+
+// ============================================================================
+// Preset Configs
+// ============================================================================
+
+export interface EchoConfig {
+    opacity?: number;
+    densityScale?: number;
+    speedScale?: number;
+    intensityScale?: number;
+}
+
+export interface MirrorConfig {
+    opacity?: number;
+    invertRotation?: boolean;
+    hueShift?: number;
+}
+
+export interface ComplementConfig {
+    opacity?: number;
+    densityPivot?: number;
+    chaosInvert?: boolean;
+}
+
+export interface HarmonicConfig {
+    opacity?: number;
+    densityHarmonic?: number;
+    speedRatio?: number;
+    hueAngle?: number;
+}
+
+export interface ReactiveConfig {
+    opacity?: number;
+    gain?: number;
+    decay?: number;
+}
+
+export interface ChaseConfig {
+    opacity?: number;
+    lerpRate?: number;
+}
+
+/** Union of all preset config types */
+export type PresetConfig = EchoConfig | MirrorConfig | ComplementConfig | HarmonicConfig | ReactiveConfig | ChaseConfig;
+
+/** Serializable relationship specification */
+export interface RelationshipConfig {
+    preset: RelationshipPreset;
+    config?: PresetConfig;
+}
+
+// ============================================================================
+// Profiles
+// ============================================================================
+
+export interface LayerRelationshipProfile {
+    keystone: LayerName;
+    relationships: Partial<Record<LayerName, RelationshipConfig>>;
+}
+
+// ============================================================================
+// Export/Import
+// ============================================================================
+
+export interface LayerRelationshipExport {
+    keystone: LayerName;
+    profile: RelationshipProfileName | null;
+    relationships: Partial<Record<LayerName, RelationshipConfig | null>>;
+    shaders: Partial<Record<LayerName, string>>;
+}
+
+// ============================================================================
+// Preset Factories
+// ============================================================================
+
+export declare function echo(config?: EchoConfig): RelationshipFn;
+export declare function mirror(config?: MirrorConfig): RelationshipFn;
+export declare function complement(config?: ComplementConfig): RelationshipFn;
+export declare function harmonic(config?: HarmonicConfig): RelationshipFn;
+export declare function reactive(config?: ReactiveConfig): RelationshipFn;
+export declare function chase(config?: ChaseConfig): RelationshipFn;
+
+export declare const PRESET_REGISTRY: Record<RelationshipPreset, (...args: any[]) => RelationshipFn>;
+export declare const PROFILES: Record<RelationshipProfileName, LayerRelationshipProfile>;
+
+// ============================================================================
+// LayerRelationshipGraph
+// ============================================================================
+
+export interface LayerRelationshipGraphOptions {
+    keystone?: LayerName;
+    profile?: RelationshipProfileName;
+}
+
+export declare class LayerRelationshipGraph {
+    constructor(config?: LayerRelationshipGraphOptions);
+
+    /** The current keystone (driver) layer */
+    readonly keystone: LayerName;
+
+    /** Currently active profile name, or null if custom */
+    readonly activeProfile: RelationshipProfileName | null;
+
+    /** Available profile names */
+    static readonly profileNames: RelationshipProfileName[];
+
+    /** Available preset relationship names */
+    static readonly presetNames: RelationshipPreset[];
+
+    /** Set the keystone (driver) layer */
+    setKeystone(layerName: LayerName): void;
+
+    /**
+     * Set the relationship for a dependent layer.
+     * Accepts a preset name, a custom function, or a { preset, config } object.
+     */
+    setRelationship(
+        layerName: LayerName,
+        relationship: RelationshipPreset | RelationshipFn | RelationshipConfig
+    ): void;
+
+    /** Set the shader program for a specific layer */
+    setLayerShader(layerName: LayerName, shaderName: string): void;
+
+    /** Get the shader name for a layer (null = use default) */
+    getLayerShader(layerName: LayerName): string | null;
+
+    /** Load a named profile, configuring the full graph at once */
+    loadProfile(profileName: RelationshipProfileName): void;
+
+    /** Resolve parameters for a single dependent layer */
+    resolve(
+        keystoneParams: Record<string, unknown>,
+        layerName: LayerName,
+        time: number
+    ): Record<string, unknown>;
+
+    /** Resolve parameters for all layers at once */
+    resolveAll(
+        keystoneParams: Record<string, unknown>,
+        time: number
+    ): Record<LayerName, Record<string, unknown>>;
+
+    /** Export the graph configuration for saving */
+    exportConfig(): LayerRelationshipExport;
+
+    /** Import a graph configuration */
+    importConfig(config: LayerRelationshipExport): void;
+}
+
+export default LayerRelationshipGraph;

package/types/render/index.d.ts

@@ -12,6 +12,9 @@ export * from './ShaderProgram';
 export * from './WebGLBackend';
 export * from './WebGPUBackend';
 export * from './UnifiedRenderBridge';
+export * from './LayerRelationshipGraph';
+export * from './LayerPresetManager';
+export * from './LayerReactivityBridge';
 
 import { RenderState, BlendMode, CullFace } from './RenderState';
 import { CommandBuffer, CommandBufferOptions } from './CommandBuffer';