af-motion 0.0.0-stage → 1.0.0

package/dist/graphics/fluid/types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * AF Motion Fluid & Flow Simulation Engine — Type Definitions
+ *
+ * Framework-independent Eulerian fluid simulation architecture supporting
+ * Navier-Stokes velocity advection, pressure projection, flow fields,
+ * obstacle interaction, and particle coupling across GPU and CPU backends.
+ */
+import type { ComputeBackendType } from "../gpu-simulation/types.js";
+import type { GraphicsQualityLevel } from "../composition/types.js";
+export type FluidVector2Tuple = readonly [number, number];
+export type FluidVector3Tuple = readonly [number, number, number];
+export type Vector2Tuple = FluidVector2Tuple;
+export type FluidBoundaryMode = "closed" | "open" | "periodic";
+export type FluidVisualizationMode = "density" | "velocity" | "vector-field" | "pressure" | "smoke" | "ink" | "color-field";
+export type FlowFieldType = "directional" | "radial" | "vortex" | "curl-noise" | "custom" | "composite";
+export interface FluidGridDimensions {
+    readonly width: number;
+    readonly height: number;
+    readonly depth?: number;
+}
+export interface DirectionalFlowFieldConfig {
+    readonly type: "directional";
+    readonly id?: string;
+    readonly direction: Vector2Tuple;
+    readonly strength?: number;
+    readonly weight?: number;
+}
+export interface RadialFlowFieldConfig {
+    readonly type: "radial";
+    readonly id?: string;
+    readonly center: Vector2Tuple;
+    readonly strength: number;
+    readonly radius?: number;
+    readonly falloff?: "linear" | "inverse-square";
+    readonly weight?: number;
+}
+export interface VortexFlowFieldConfig {
+    readonly type: "vortex";
+    readonly id?: string;
+    readonly center: Vector2Tuple;
+    readonly strength: number;
+    readonly radius?: number;
+    readonly inwardPull?: number;
+    readonly weight?: number;
+}
+export interface CurlNoiseFlowFieldConfig {
+    readonly type: "curl-noise";
+    readonly id?: string;
+    readonly frequency?: number;
+    readonly strength?: number;
+    readonly octaves?: number;
+    readonly timeScale?: number;
+    readonly weight?: number;
+}
+export interface CustomFlowFieldConfig {
+    readonly type: "custom";
+    readonly id?: string;
+    readonly evaluate: (x: number, y: number, time: number) => Vector2Tuple;
+    readonly weight?: number;
+}
+export interface CompositeFlowFieldConfig {
+    readonly type: "composite";
+    readonly id?: string;
+    readonly fields: readonly FlowFieldConfig[];
+    readonly weight?: number;
+}
+export type FlowFieldConfig = DirectionalFlowFieldConfig | RadialFlowFieldConfig | VortexFlowFieldConfig | CurlNoiseFlowFieldConfig | CustomFlowFieldConfig | CompositeFlowFieldConfig;
+export interface FlowField {
+    readonly id: string;
+    readonly type: FlowFieldType;
+    enabled: boolean;
+    weight: number;
+    evaluate(x: number, y: number, time: number): Vector2Tuple;
+}
+export interface FluidForce {
+    readonly id?: string;
+    x: number;
+    y: number;
+    fx: number;
+    fy: number;
+    radius?: number;
+    density?: number;
+}
+export type FluidObstacleShape = {
+    readonly type: "circle";
+    readonly center: Vector2Tuple;
+    readonly radius: number;
+} | {
+    readonly type: "box";
+    readonly min: Vector2Tuple;
+    readonly max: Vector2Tuple;
+};
+export interface FluidObstacle {
+    readonly id: string;
+    readonly shape: FluidObstacleShape;
+    enabled: boolean;
+    contains(x: number, y: number): boolean;
+}
+export interface FluidSolverConfig {
+    readonly iterations?: number;
+    readonly viscosity?: number;
+    readonly dissipation?: number;
+    readonly pressureRelaxation?: number;
+    readonly boundaryMode?: FluidBoundaryMode;
+    readonly maxDeltaTime?: number;
+    readonly velocityDissipation?: number;
+}
+export interface FluidSolver {
+    readonly config: FluidSolverConfig;
+    step(grid: FluidGrid, dt: number, forces: readonly FluidForce[], time: number): void;
+}
+export interface FluidGrid {
+    readonly width: number;
+    readonly height: number;
+    readonly size: number;
+    readonly u: Float32Array;
+    readonly v: Float32Array;
+    readonly u0: Float32Array;
+    readonly v0: Float32Array;
+    readonly density: Float32Array;
+    readonly density0: Float32Array;
+    readonly pressure: Float32Array;
+    readonly divergence: Float32Array;
+    readonly obstacles: Uint8Array;
+    swapVelocity(): void;
+    swapDensity(): void;
+    clear(): void;
+    sampleVelocity(normX: number, normY: number): Vector2Tuple;
+    sampleDensity(normX: number, normY: number): number;
+}
+export interface FluidRenderOptions {
+    readonly mode?: FluidVisualizationMode;
+    readonly colorRamp?: readonly [string, string] | readonly string[];
+    readonly opacity?: number;
+    readonly glyphScale?: number;
+    readonly glyphSpacing?: number;
+    readonly smokeColor?: readonly [number, number, number];
+    readonly inkColor?: readonly [number, number, number];
+}
+export interface FluidSimulationMetrics {
+    readonly gridWidth: number;
+    readonly gridHeight: number;
+    readonly activeCells: number;
+    readonly fps: number;
+    readonly stepTimeMs: number;
+    readonly renderTimeMs: number;
+    readonly memoryBytes: number;
+    readonly backend: ComputeBackendType | "canvas2d";
+}
+export type FluidSimulationState = "idle" | "running" | "paused" | "disposed";
+export interface FluidSimulationConfig {
+    readonly id?: string;
+    readonly resolution?: number | FluidGridDimensions;
+    readonly solver?: FluidSolverConfig;
+    readonly flowFields?: readonly FlowFieldConfig[];
+    readonly obstacles?: readonly FluidObstacleShape[];
+    readonly renderOptions?: FluidRenderOptions;
+    readonly backend?: "auto" | ComputeBackendType;
+    readonly quality?: GraphicsQualityLevel;
+    readonly canvas?: HTMLCanvasElement | null;
+    readonly fixedTimestep?: number;
+    readonly autoStart?: boolean;
+}
+export interface FluidSimulation {
+    readonly id: string;
+    readonly state: FluidSimulationState;
+    readonly grid: FluidGrid;
+    readonly metrics: FluidSimulationMetrics;
+    readonly backend: ComputeBackendType | "canvas2d";
+    start(): void;
+    pause(): void;
+    resume(): void;
+    reset(): void;
+    dispose(): void;
+    update(deltaTime?: number): void;
+    render(canvas?: HTMLCanvasElement, context?: unknown): void;
+    addForce(force: FluidForce): void;
+    addObstacle(shape: FluidObstacleShape, id?: string): FluidObstacle;
+    removeObstacle(id: string): boolean;
+    addFlowField(field: FlowField | FlowFieldConfig): FlowField;
+    removeFlowField(id: string): boolean;
+    sampleVelocity(normX: number, normY: number): Vector2Tuple;
+    sampleDensity(normX: number, normY: number): number;
+    getObstacles(): readonly FluidObstacle[];
+    getFlowFields(): readonly FlowField[];
+}

package/dist/graphics/gpu-simulation/backends/backend.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AF Motion GPU Simulation Architecture — Backend Interface & Helpers
+ */
+import type { ComputeBackend, ComputeBackendType, ComputeCapabilities, ComputeTextureFormat } from "../types.js";
+export declare function getBytesPerPixel(format: ComputeTextureFormat): number;
+export declare abstract class BaseComputeBackend implements ComputeBackend {
+    abstract readonly type: ComputeBackendType;
+    abstract readonly capabilities: ComputeCapabilities;
+    protected lost: boolean;
+    protected readonly lostListeners: Set<(reason: string) => void>;
+    protected readonly restoredListeners: Set<() => void>;
+    get isLost(): boolean;
+    onDeviceLost(listener: (reason: string) => void): () => void;
+    onDeviceRestored(listener: () => void): () => void;
+    protected notifyLost(reason: string): void;
+    protected notifyRestored(): void;
+    abstract init(): Promise<void> | void;
+    abstract createBuffer(...args: any[]): any;
+    abstract createTexture(...args: any[]): any;
+    abstract createPipeline(...args: any[]): any;
+    abstract createBindGroup(...args: any[]): any;
+    abstract dispatch(...args: any[]): void;
+    abstract dispose(): void;
+}

package/dist/graphics/gpu-simulation/backends/cpu.d.ts

@@ -0,0 +1,21 @@
+/**
+ * AF Motion GPU Simulation Architecture — Deterministic CPU Compute Backend
+ *
+ * Implements a framework-independent, hardware-independent CPU simulation backend
+ * backed by typed arrays and pure kernel functions. Ensures graceful fallback in SSR,
+ * Node.js, and unsupported GPU environments.
+ */
+import type { ComputeBinding, ComputeBindingLayout, ComputeBindGroup, ComputeBuffer, ComputeBufferDescriptor, ComputeCapabilities, ComputeDispatchConfig, ComputePipeline, ComputePipelineDescriptor, ComputeResourceManager, ComputeTexture, ComputeTextureDescriptor } from "../types.js";
+import { BaseComputeBackend } from "./backend.js";
+export declare class CPUComputeBackend extends BaseComputeBackend {
+    readonly type: "cpu";
+    readonly capabilities: ComputeCapabilities;
+    private sequence;
+    init(): void;
+    createBuffer(descriptor: ComputeBufferDescriptor, resourceManager: ComputeResourceManager): ComputeBuffer;
+    createTexture(descriptor: ComputeTextureDescriptor, resourceManager: ComputeResourceManager): ComputeTexture;
+    createPipeline(descriptor: ComputePipelineDescriptor, resourceManager: ComputeResourceManager): ComputePipeline;
+    createBindGroup(_layout: readonly ComputeBindingLayout[], bindings: readonly ComputeBinding[], resourceManager: ComputeResourceManager): ComputeBindGroup;
+    dispatch(pipeline: ComputePipeline, bindGroup: ComputeBindGroup, config: ComputeDispatchConfig): void;
+    dispose(): void;
+}

package/dist/graphics/gpu-simulation/backends/selection.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion GPU Simulation Architecture — Backend Selection & Factory
+ *
+ * Implements deterministic capability-based backend selection, explicit overrides,
+ * and graceful fallback resolution across WebGPU, WebGL2, and CPU execution.
+ */
+import type { BackendSelectionOptions, ComputeBackend, ComputeBackendSelectionResult, ComputeBackendType, ComputeDeviceOptions } from "../types.js";
+/**
+ * Evaluates device capabilities, canvas context, and options to select the optimal compute backend.
+ */
+export declare function selectComputeBackend(options?: BackendSelectionOptions): ComputeBackendSelectionResult;
+/**
+ * Creates a concrete compute backend instance matching the requested type.
+ */
+export declare function createComputeBackend(type: ComputeBackendType, options?: ComputeDeviceOptions): ComputeBackend;

package/dist/graphics/gpu-simulation/backends/webgl2.d.ts

@@ -0,0 +1,28 @@
+/**
+ * AF Motion GPU Simulation Architecture — WebGL2 GPGPU Backend
+ *
+ * Implements GPU-accelerated simulation via WebGL2 textures, framebuffers,
+ * full-screen quad fragment passes, and ping-pong state evolution.
+ */
+import type { ComputeBinding, ComputeBindingLayout, ComputeBindGroup, ComputeBuffer, ComputeBufferDescriptor, ComputeCapabilities, ComputeDeviceOptions, ComputeDispatchConfig, ComputePipeline, ComputePipelineDescriptor, ComputeResourceManager, ComputeTexture, ComputeTextureDescriptor } from "../types.js";
+import { BaseComputeBackend } from "./backend.js";
+export declare class WebGL2ComputeBackend extends BaseComputeBackend {
+    readonly type: "webgl2";
+    capabilities: ComputeCapabilities;
+    private gl;
+    private canvas;
+    private sequence;
+    private quadVao;
+    private quadVbo;
+    private unbindLost;
+    private unbindRestored;
+    constructor(options?: ComputeDeviceOptions);
+    init(options?: ComputeDeviceOptions): void;
+    private initQuad;
+    createBuffer(descriptor: ComputeBufferDescriptor, resourceManager: ComputeResourceManager): ComputeBuffer;
+    createTexture(descriptor: ComputeTextureDescriptor, resourceManager: ComputeResourceManager): ComputeTexture;
+    createPipeline(descriptor: ComputePipelineDescriptor, resourceManager: ComputeResourceManager): ComputePipeline;
+    createBindGroup(_layout: readonly ComputeBindingLayout[], bindings: readonly ComputeBinding[], resourceManager: ComputeResourceManager): ComputeBindGroup;
+    dispatch(pipeline: ComputePipeline, bindGroup: ComputeBindGroup, config: ComputeDispatchConfig): void;
+    dispose(): void;
+}

package/dist/graphics/gpu-simulation/backends/webgpu.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AF Motion GPU Simulation Architecture — WebGPU Compute Backend
+ *
+ * Implements native GPU compute execution via WebGPU (GPUDevice, GPUComputePipeline,
+ * storage buffers, WGSL shaders, and compute pass dispatch). Remains strictly optional
+ * with zero required peer dependencies and graceful fallback to WebGL2 or CPU.
+ */
+import type { ComputeBinding, ComputeBindingLayout, ComputeBindGroup, ComputeBuffer, ComputeBufferDescriptor, ComputeCapabilities, ComputeDeviceOptions, ComputeDispatchConfig, ComputePipeline, ComputePipelineDescriptor, ComputeResourceManager, ComputeTexture, ComputeTextureDescriptor } from "../types.js";
+import { BaseComputeBackend } from "./backend.js";
+export declare class WebGPUComputeBackend extends BaseComputeBackend {
+    readonly type: "webgpu";
+    capabilities: ComputeCapabilities;
+    private device;
+    private sequence;
+    constructor();
+    init(options?: ComputeDeviceOptions): Promise<void>;
+    createBuffer(descriptor: ComputeBufferDescriptor, resourceManager: ComputeResourceManager): ComputeBuffer;
+    createTexture(descriptor: ComputeTextureDescriptor, resourceManager: ComputeResourceManager): ComputeTexture;
+    createPipeline(descriptor: ComputePipelineDescriptor, resourceManager: ComputeResourceManager): ComputePipeline;
+    createBindGroup(layout: readonly ComputeBindingLayout[], bindings: readonly ComputeBinding[], resourceManager: ComputeResourceManager): ComputeBindGroup;
+    dispatch(pipeline: ComputePipeline, bindGroup: ComputeBindGroup, config: ComputeDispatchConfig): void;
+    dispose(): void;
+}

package/dist/graphics/gpu-simulation/capabilities.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AF Motion GPU Simulation Architecture — Capability Detection
+ *
+ * Integrates existing device capability intelligence while probing WebGL2 and WebGPU
+ * compute and texture simulation limits without throwing or triggering browser warnings.
+ */
+import type { ComputeCapabilityOptions, ComputeCapabilities } from "./types.js";
+export declare const DEFAULT_FALLBACK_COMPUTE_CAPABILITIES: ComputeCapabilities;
+/**
+ * Detects GPU compute capabilities defensively across browser, node, SSR,
+ * and headless test environments.
+ */
+export declare function detectComputeCapabilities(options?: ComputeCapabilityOptions): ComputeCapabilities;
+export declare function resetCachedComputeCapabilities(): void;

package/dist/graphics/gpu-simulation/device.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AF Motion GPU Simulation Architecture — Compute Device
+ *
+ * Implements the core ComputeDevice abstraction managing compute backends,
+ * memory-budgeted resource tracking, lifecycle hooks, and safe backend fallback.
+ */
+import type { ComputeDevice, ComputeDeviceOptions } from "./types.js";
+/**
+ * Creates and initializes a framework-independent ComputeDevice.
+ * If GPU initialization fails, automatically falls back to CPU simulation.
+ */
+export declare function createComputeDeviceAsync(options?: ComputeDeviceOptions): Promise<ComputeDevice>;
+/**
+ * Synchronous variant of createComputeDevice. Uses WebGL2 or CPU backend immediately.
+ * If WebGPU is requested, falls back to WebGL2 or CPU synchronously, or use createComputeDeviceAsync for native async WebGPU.
+ */
+export declare function createComputeDevice(options?: ComputeDeviceOptions): ComputeDevice;

package/dist/graphics/gpu-simulation/engine.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AF Motion GPU Simulation Architecture — Simulation Execution Engine
+ *
+ * Implements a framework-independent simulation runner with fixed/variable timestepping,
+ * multi-substep execution, performance metrics accounting, and safe backend fallback.
+ */
+import type { SimulationEngine, SimulationEngineConfig } from "./types.js";
+export declare function createSimulationEngine(config: SimulationEngineConfig): SimulationEngine;

package/dist/graphics/gpu-simulation/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AF Motion GPU Simulation Architecture
+ *
+ * Framework-independent foundation for GPU-accelerated particles, fluid simulations,
+ * environmental effects, and interactive simulation systems across WebGL2, WebGPU,
+ * and deterministic CPU execution.
+ */
+export * from "./types.js";
+export * from "./capabilities.js";
+export * from "./resource-manager.js";
+export * from "./shaders.js";
+export * from "./ping-pong.js";
+export * from "./backends/backend.js";
+export * from "./backends/cpu.js";
+export * from "./backends/webgl2.js";
+export * from "./backends/webgpu.js";
+export * from "./backends/selection.js";
+export * from "./pipeline.js";
+export * from "./device.js";
+export * from "./engine.js";
+export { createSimulationEngine as createGPUSimulation } from "./engine.js";
+export type { SimulationEngineConfig as GPUSimulationConfig, SimulationEngine as GPUSimulationEngine, } from "./types.js";

package/dist/graphics/gpu-simulation/ping-pong.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AF Motion GPU Simulation Architecture — Ping-Pong Framebuffer Infrastructure
+ *
+ * Implements deterministic double-buffered ping-pong texture and framebuffer swapping
+ * for WebGL2 GPGPU simulation pipelines with completeness validation and cleanup.
+ */
+import type { ComputeTexture, PingPongFramebuffer, PingPongTextures } from "./types.js";
+/**
+ * Creates a generic ping-pong state container.
+ */
+export declare function createPingPongPair<T>(itemA: T, itemB: T): {
+    current: T;
+    next: T;
+    swap(): void;
+};
+/**
+ * Creates a ping-pong pair of ComputeTextures.
+ */
+export declare function createPingPongTextures(texA: ComputeTexture, texB: ComputeTexture): PingPongTextures;
+/**
+ * Creates a WebGL2 Ping-Pong Framebuffer pair bound to two textures for GPGPU simulation.
+ */
+export declare function createWebGL2PingPongFramebuffer(gl: WebGL2RenderingContext, textureA: WebGLTexture, textureB: WebGLTexture): PingPongFramebuffer;

package/dist/graphics/gpu-simulation/pipeline.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AF Motion GPU Simulation Architecture — Compute Pipeline
+ *
+ * Provides typed compute pipeline creation, shader binding layout validation,
+ * and lifecycle tracking across WebGPU, WebGL2, and CPU backends.
+ */
+import type { ComputeDevice, ComputePipeline, ComputePipelineDescriptor } from "./types.js";
+/**
+ * Validates a compute pipeline descriptor before creation.
+ */
+export declare function validatePipelineDescriptor(descriptor: ComputePipelineDescriptor): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Creates and registers a compute pipeline on the target compute device.
+ */
+export declare function createComputePipeline(device: ComputeDevice, descriptor: ComputePipelineDescriptor): ComputePipeline;

package/dist/graphics/gpu-simulation/resource-manager.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AF Motion GPU Simulation Architecture — Compute Resource Manager
+ *
+ * Provides lifecycle tracking, memory accounting, double-disposal protection,
+ * limit validation, and context-loss recovery for GPU and CPU compute resources.
+ */
+import type { ComputeResourceManager, ComputeResourceManagerOptions } from "./types.js";
+export declare function createComputeResourceManager(options?: ComputeResourceManagerOptions): ComputeResourceManager;

package/dist/graphics/gpu-simulation/shaders.d.ts

@@ -0,0 +1,50 @@
+/**
+ * AF Motion GPU Simulation Architecture — Shader Infrastructure
+ *
+ * Provides shader compilation, validation, caching, uniform extraction,
+ * and error reporting across WebGL2 GLSL ES 3.0, WebGPU WGSL, and CPU kernels.
+ */
+import type { ComputeShaderDescriptor, ComputeShaderLanguage } from "./types.js";
+export interface ShaderCompilationResult {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+    readonly compiledObject?: unknown;
+}
+export interface CachedShaderEntry {
+    readonly id: string;
+    readonly key: string;
+    readonly language: ComputeShaderLanguage;
+    readonly compiledObject: unknown;
+    readonly timestamp: number;
+}
+/**
+ * Computes a deterministic cache key from shader source and metadata.
+ */
+export declare function computeShaderCacheKey(descriptor: ComputeShaderDescriptor): string;
+/**
+ * Validates shader descriptor structure and uniform signatures.
+ */
+export declare function validateShaderDescriptor(descriptor: ComputeShaderDescriptor): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Compiles and validates a WebGL2 GLSL fragment shader for GPU simulation.
+ */
+export declare function compileWebGL2Shader(gl: WebGL2RenderingContext, source: string, type?: number): ShaderCompilationResult;
+/**
+ * Creates and links a WebGL2 simulation program with a pass-through full-screen quad vertex shader.
+ */
+export declare const WEBGL2_QUAD_VERTEX_SHADER = "#version 300 es\nin vec2 a_position;\nout vec2 v_uv;\nvoid main() {\n  v_uv = (a_position + 1.0) * 0.5;\n  gl_Position = vec4(a_position, 0.0, 1.0);\n}\n";
+export declare function createWebGL2SimulationProgram(gl: WebGL2RenderingContext, fragmentShaderSource: string): {
+    program: WebGLProgram | null;
+    errors: string[];
+};
+/**
+ * Formats raw shader error logs with line-referenced code context.
+ */
+export declare function formatShaderErrorLog(infoLog: string, source: string): string;
+/**
+ * Clears the shader compilation cache.
+ */
+export declare function clearShaderCache(): void;