af-motion 0.0.0-stage → 1.0.0

package/dist/graphics/particles/data-layout.d.ts

@@ -0,0 +1,51 @@
+/**
+ * AF Motion Advanced Particle Engine — Memory Layout & Pool
+ *
+ * Implements a high-performance contiguous Float32Array particle storage pool
+ * with an O(1) free-list recycling queue, zero garbage collection allocations,
+ * and GPU buffer mapping compatibility.
+ */
+import type { ParticleAccessor, ParticleDataPool, ParticleSpawnData } from "./types.js";
+export declare const PARTICLE_STRIDE = 24;
+export declare const OFFSET_POS_X = 0;
+export declare const OFFSET_POS_Y = 1;
+export declare const OFFSET_POS_Z = 2;
+export declare const OFFSET_LIFE = 3;
+export declare const OFFSET_VEL_X = 4;
+export declare const OFFSET_VEL_Y = 5;
+export declare const OFFSET_VEL_Z = 6;
+export declare const OFFSET_MAX_LIFE = 7;
+export declare const OFFSET_ACC_X = 8;
+export declare const OFFSET_ACC_Y = 9;
+export declare const OFFSET_ACC_Z = 10;
+export declare const OFFSET_SIZE = 11;
+export declare const OFFSET_ROTATION = 12;
+export declare const OFFSET_ANGULAR_VEL = 13;
+export declare const OFFSET_OPACITY = 14;
+export declare const OFFSET_MASS = 15;
+export declare const OFFSET_COLOR_R = 16;
+export declare const OFFSET_COLOR_G = 17;
+export declare const OFFSET_COLOR_B = 18;
+export declare const OFFSET_COLOR_A = 19;
+export declare const OFFSET_START_SIZE = 20;
+export declare const OFFSET_END_SIZE = 21;
+export declare const OFFSET_START_OPACITY = 22;
+export declare const OFFSET_END_OPACITY = 23;
+export declare class ParticlePoolImpl implements ParticleDataPool {
+    readonly capacity: number;
+    readonly stride = 24;
+    readonly buffer: Float32Array;
+    private freeList;
+    private freeHead;
+    private activeIndices;
+    private activeCount;
+    private slotToActivePos;
+    constructor(capacity: number);
+    get count(): number;
+    spawn(data: ParticleSpawnData): number;
+    kill(slot: number): void;
+    getAccessor(slot: number): ParticleAccessor;
+    getActiveIndices(): Int32Array;
+    clear(): void;
+}
+export declare function createParticleDataPool(capacity: number): ParticleDataPool;

package/dist/graphics/particles/emitters.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AF Motion Advanced Particle Engine — Emitter System
+ *
+ * Implements configurable geometric particle emitters (point, line, circle,
+ * rectangle, sphere, box, cone, custom) with continuous and burst spawning.
+ */
+import type { EmitterShape, ParticleDataPool, ParticleEmitter, ParticleEmitterConfig, ParticleVector3Tuple as Vector3Tuple } from "./types.js";
+export declare class ParticleEmitterImpl implements ParticleEmitter {
+    readonly id: string;
+    readonly config: ParticleEmitterConfig;
+    enabled: boolean;
+    rate: number;
+    private spawnAccumulator;
+    constructor(config: ParticleEmitterConfig);
+    update(dt: number, pool: ParticleDataPool, prng: () => number): number;
+    burst(count: number, pool: ParticleDataPool, prng: () => number): number;
+    private spawnParticles;
+    private generateParticleData;
+}
+/**
+ * Samples a random 3D position vector from a given emitter shape.
+ */
+export declare function sampleShapePosition(shape: EmitterShape, prng: () => number): Vector3Tuple;
+export declare function createParticleEmitter(config: ParticleEmitterConfig): ParticleEmitter;

package/dist/graphics/particles/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion Advanced Particle Engine
+ *
+ * High-performance, framework-independent particle system architecture
+ * supporting millions-scale GPU-accelerated simulation, composable behaviors,
+ * multiple geometric emitters, and deterministic CPU fallback.
+ */
+export * from "./types.js";
+export { createParticlePRNG, parseParticleColor, resolveRange, randomDirectionInCone, } from "./random.js";
+export * from "./data-layout.js";
+export * from "./emitters.js";
+export * from "./behaviors.js";
+export * from "./simulation.js";
+export * from "./rendering.js";
+export * from "./controller.js";

package/dist/graphics/particles/random.d.ts

@@ -0,0 +1,25 @@
+/**
+ * AF Motion Advanced Particle Engine — Deterministic Randomness
+ *
+ * Provides seeded Mulberry32 pseudo-random number generation for deterministic,
+ * reproducible particle simulations, random distributions, and vectors.
+ */
+import type { ParticleColorInput, ParticleVector3Tuple, ParticleVector4Tuple } from "./types.js";
+/**
+ * Creates a deterministic PRNG returning numbers in [0, 1), reusing the textures Mulberry32 engine.
+ */
+export declare function createParticlePRNG(seed?: number | string): () => number;
+export { createParticlePRNG as createPRNG };
+/**
+ * Resolves a range [min, max] or fixed number with a given PRNG.
+ */
+export declare function resolveRange(value: number | readonly [number, number] | undefined, defaultVal: number, prng: () => number): number;
+/**
+ * Generates a random unit vector on a sphere surface or inside a cone.
+ */
+export declare function randomDirectionInCone(baseDirection: ParticleVector3Tuple, spreadAngleRad: number, prng: () => number): ParticleVector3Tuple;
+/**
+ * Parses a ParticleColorInput into an RGBA [r, g, b, a] normalized [0, 1] tuple.
+ */
+export declare function parseParticleColor(color: ParticleColorInput | undefined, defaultColor?: ParticleVector4Tuple): ParticleVector4Tuple;
+export { parseParticleColor as parseColor };

package/dist/graphics/particles/rendering.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion Advanced Particle Engine — Rendering Strategies
+ *
+ * Implements GPU-accelerated point-sprite & instanced rendering via WebGL2,
+ * alongside high-performance Canvas2D batch rendering fallback.
+ */
+import type { ParticleDataPool, ParticleRenderOptions } from "./types.js";
+export interface WebGL2ParticleRenderer {
+    render(pool: ParticleDataPool, options?: ParticleRenderOptions): void;
+    dispose(): void;
+}
+export declare function createWebGL2ParticleRenderer(gl: WebGL2RenderingContext): WebGL2ParticleRenderer;
+/**
+ * High-performance 2D Canvas particle renderer fallback.
+ */
+export declare function renderParticlesCanvas2D(pool: ParticleDataPool, canvas: HTMLCanvasElement, options?: ParticleRenderOptions): void;

package/dist/graphics/particles/simulation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AF Motion Advanced Particle Engine — Simulation Stepper
+ *
+ * Implements deterministic physics integration, substepping, lifetime decay,
+ * property interpolation (size, opacity, rotation), and dead particle recycling.
+ */
+import type { ParticleBehavior, ParticleDataPool, ParticleEmitter } from "./types.js";
+export interface SimulationStepOptions {
+    readonly pool: ParticleDataPool;
+    readonly emitters: readonly ParticleEmitter[];
+    readonly behaviors: readonly ParticleBehavior[];
+    readonly dt: number;
+    readonly substeps?: number;
+    readonly prng: () => number;
+}
+/**
+ * Performs a complete simulation update cycle (spawning, behaviors, integration, recycling).
+ */
+export declare function stepParticleSimulation(options: SimulationStepOptions): void;
+/**
+ * Updates positions, velocities, lifetimes, sizes, opacities, and recycles dead particles.
+ */
+export declare function integrateParticles(pool: ParticleDataPool, dt: number): void;

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

@@ -0,0 +1,282 @@
+/**
+ * AF Motion Advanced Particle Engine — Type Definitions
+ *
+ * High-performance, framework-independent particle system architecture
+ * supporting millions-scale GPU-accelerated simulation and deterministic CPU fallback.
+ */
+import type { ComputeBackendType, ComputeDevice } from "../gpu-simulation/types.js";
+import type { GraphicsQualityLevel } from "../composition/types.js";
+import type { ColorRGBA } from "../textures/canvas-utils.js";
+export type ParticleVector3Tuple = readonly [number, number, number];
+export type ParticleVector4Tuple = readonly [number, number, number, number];
+export type ParticleBlendMode = "alpha" | "additive" | "multiply" | "screen";
+export type ParticleRenderStrategy = "gpu-points" | "gpu-quads" | "canvas2d" | "auto";
+export type EmitterShapeType = "point" | "line" | "circle" | "rectangle" | "sphere" | "box" | "cone" | "custom";
+export type BoundaryAction = "bounce" | "wrap" | "kill" | "none";
+export type ParticleColorInput = ColorRGBA | ParticleVector4Tuple | string;
+export interface ParticleSpawnData {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    ax: number;
+    ay: number;
+    az: number;
+    life: number;
+    maxLife: number;
+    startSize: number;
+    endSize: number;
+    startRotation: number;
+    angularVelocity: number;
+    startOpacity: number;
+    endOpacity: number;
+    startColor: ParticleVector4Tuple;
+    endColor: ParticleVector4Tuple;
+    mass: number;
+}
+export interface PointEmitterShape {
+    readonly type: "point";
+    readonly position?: ParticleVector3Tuple;
+}
+export interface LineEmitterShape {
+    readonly type: "line";
+    readonly start: ParticleVector3Tuple;
+    readonly end: ParticleVector3Tuple;
+}
+export interface CircleEmitterShape {
+    readonly type: "circle";
+    readonly center?: ParticleVector3Tuple;
+    readonly radius: number;
+    readonly innerRadius?: number;
+    readonly plane?: "xy" | "xz" | "yz";
+}
+export interface RectangleEmitterShape {
+    readonly type: "rectangle";
+    readonly center?: ParticleVector3Tuple;
+    readonly width: number;
+    readonly height: number;
+    readonly plane?: "xy" | "xz" | "yz";
+}
+export interface SphereEmitterShape {
+    readonly type: "sphere";
+    readonly center?: ParticleVector3Tuple;
+    readonly radius: number;
+    readonly innerRadius?: number;
+    readonly surfaceOnly?: boolean;
+}
+export interface BoxEmitterShape {
+    readonly type: "box";
+    readonly center?: ParticleVector3Tuple;
+    readonly dimensions: ParticleVector3Tuple;
+}
+export interface ConeEmitterShape {
+    readonly type: "cone";
+    readonly apex?: ParticleVector3Tuple;
+    readonly direction: ParticleVector3Tuple;
+    readonly angle: number;
+    readonly baseRadius: number;
+    readonly height: number;
+}
+export interface CustomEmitterShape {
+    readonly type: "custom";
+    readonly generate: (index: number, prng: () => number) => Partial<ParticleSpawnData>;
+}
+export type EmitterShape = PointEmitterShape | LineEmitterShape | CircleEmitterShape | RectangleEmitterShape | SphereEmitterShape | BoxEmitterShape | ConeEmitterShape | CustomEmitterShape;
+export interface ParticleEmitterConfig {
+    readonly id?: string;
+    readonly shape?: EmitterShape;
+    readonly rate?: number;
+    readonly burstCount?: number;
+    readonly maxParticles?: number;
+    readonly lifetime?: number | readonly [number, number];
+    readonly speed?: number | readonly [number, number];
+    readonly direction?: ParticleVector3Tuple;
+    readonly spread?: number;
+    readonly size?: number | readonly [number, number];
+    readonly opacity?: number | readonly [number, number];
+    readonly rotation?: number | readonly [number, number];
+    readonly angularVelocity?: number | readonly [number, number];
+    readonly color?: ParticleColorInput | readonly [ParticleColorInput, ParticleColorInput];
+    readonly mass?: number | readonly [number, number];
+    readonly seed?: number;
+    readonly enabled?: boolean;
+}
+export interface ParticleEmitter {
+    readonly id: string;
+    readonly config: ParticleEmitterConfig;
+    enabled: boolean;
+    rate: number;
+    update(dt: number, pool: ParticleDataPool, prng: () => number): number;
+    burst(count: number, pool: ParticleDataPool, prng: () => number): number;
+}
+export interface ParticleAccessor {
+    readonly index: number;
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    ax: number;
+    ay: number;
+    az: number;
+    life: number;
+    maxLife: number;
+    size: number;
+    rotation: number;
+    angularVelocity: number;
+    opacity: number;
+    mass: number;
+    color: ParticleVector4Tuple;
+}
+export type ParticleBehaviorType = "gravity" | "directional-force" | "radial-force" | "attraction" | "repulsion" | "drag" | "friction" | "turbulence" | "velocity-limits" | "boundary-constraints" | "custom";
+export interface GravityBehavior {
+    readonly id?: string;
+    readonly type: "gravity";
+    readonly force?: ParticleVector3Tuple;
+    readonly gpuCompatible?: true;
+}
+export interface DirectionalForceBehavior {
+    readonly id?: string;
+    readonly type: "directional-force";
+    readonly force: ParticleVector3Tuple;
+    readonly gpuCompatible?: true;
+}
+export interface RadialForceBehavior {
+    readonly id?: string;
+    readonly type: "radial-force";
+    readonly center: ParticleVector3Tuple;
+    readonly strength: number;
+    readonly radius?: number;
+    readonly gpuCompatible?: true;
+}
+export interface AttractionBehavior {
+    readonly id?: string;
+    readonly type: "attraction";
+    readonly target: ParticleVector3Tuple;
+    readonly strength: number;
+    readonly radius?: number;
+    readonly falloff?: "linear" | "inverse-square";
+    readonly gpuCompatible?: true;
+}
+export interface RepulsionBehavior {
+    readonly id?: string;
+    readonly type: "repulsion";
+    readonly center: ParticleVector3Tuple;
+    readonly strength: number;
+    readonly radius?: number;
+    readonly gpuCompatible?: true;
+}
+export interface DragBehavior {
+    readonly id?: string;
+    readonly type: "drag";
+    readonly coefficient: number;
+    readonly gpuCompatible?: true;
+}
+export interface FrictionBehavior {
+    readonly id?: string;
+    readonly type: "friction";
+    readonly coefficient: number;
+    readonly gpuCompatible?: true;
+}
+export interface TurbulenceBehavior {
+    readonly id?: string;
+    readonly type: "turbulence";
+    readonly frequency: number;
+    readonly strength: number;
+    readonly octaves?: number;
+    readonly gpuCompatible?: true;
+}
+export interface VelocityLimitsBehavior {
+    readonly id?: string;
+    readonly type: "velocity-limits";
+    readonly minSpeed?: number;
+    readonly maxSpeed?: number;
+    readonly gpuCompatible?: true;
+}
+export interface BoundaryConstraintsBehavior {
+    readonly id?: string;
+    readonly type: "boundary-constraints";
+    readonly bounds: readonly [number, number, number, number, number, number];
+    readonly action?: BoundaryAction;
+    readonly restitution?: number;
+    readonly gpuCompatible?: true;
+}
+export interface CustomBehavior {
+    readonly id?: string;
+    readonly type: "custom";
+    readonly execute: (particle: ParticleAccessor, dt: number) => void;
+    readonly gpuCompatible?: false;
+}
+export type ParticleBehavior = GravityBehavior | DirectionalForceBehavior | RadialForceBehavior | AttractionBehavior | RepulsionBehavior | DragBehavior | FrictionBehavior | TurbulenceBehavior | VelocityLimitsBehavior | BoundaryConstraintsBehavior | CustomBehavior;
+export interface ParticleDataPool {
+    readonly capacity: number;
+    readonly count: number;
+    readonly buffer: Float32Array;
+    readonly stride: number;
+    spawn(data: ParticleSpawnData): number;
+    kill(index: number): void;
+    getAccessor(index: number): ParticleAccessor;
+    clear(): void;
+    getActiveIndices(): Int32Array;
+}
+export interface ParticleSystemMetrics {
+    readonly particleCount: number;
+    readonly maxParticles: number;
+    readonly emitterCount: number;
+    readonly behaviorCount: number;
+    readonly fps: number;
+    readonly stepTimeMs: number;
+    readonly renderTimeMs: number;
+    readonly memoryBytes: number;
+    readonly backend: ComputeBackendType | "canvas2d";
+}
+export type ParticleSystemState = "idle" | "running" | "paused" | "stopped" | "disposed";
+export interface ParticleRenderOptions {
+    readonly strategy?: ParticleRenderStrategy;
+    readonly blendMode?: ParticleBlendMode;
+    readonly pointSizeMultiplier?: number;
+    readonly texture?: HTMLImageElement | HTMLCanvasElement | null;
+    readonly softParticles?: boolean;
+}
+export interface ParticleSystemConfig {
+    readonly id?: string;
+    readonly maxParticles?: number;
+    readonly emitters?: readonly (ParticleEmitterConfig | ParticleEmitter)[];
+    readonly behaviors?: readonly ParticleBehavior[];
+    readonly renderOptions?: ParticleRenderOptions;
+    readonly backend?: "auto" | ComputeBackendType;
+    readonly quality?: GraphicsQualityLevel;
+    readonly device?: ComputeDevice;
+    readonly canvas?: HTMLCanvasElement | null;
+    readonly fixedTimestep?: number;
+    readonly substeps?: number;
+    readonly seed?: number;
+    readonly autoStart?: boolean;
+}
+export interface ParticleSystem {
+    readonly id: string;
+    readonly state: ParticleSystemState;
+    readonly particleCount: number;
+    readonly maxParticles: number;
+    readonly metrics: ParticleSystemMetrics;
+    readonly backend: ComputeBackendType | "canvas2d";
+    start(): void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    reset(): void;
+    clear(): void;
+    dispose(): void;
+    burst(count: number, emitterIndexOrId?: number | string): number;
+    update(deltaTime?: number): void;
+    render(canvas?: HTMLCanvasElement, context?: unknown): void;
+    addEmitter(emitter: ParticleEmitter | ParticleEmitterConfig): ParticleEmitter;
+    removeEmitter(emitterId: string): boolean;
+    addBehavior(behavior: ParticleBehavior): void;
+    removeBehavior(behaviorId: string): boolean;
+    getEmitters(): readonly ParticleEmitter[];
+    getBehaviors(): readonly ParticleBehavior[];
+}

package/dist/graphics/renderer.d.ts

@@ -0,0 +1,66 @@
+import type { GraphicsCapabilities, Renderer, RendererBackend, RendererOptions, RenderFrameContext } from "./types.js";
+/**
+ * Headless Null Renderer for SSR, Node, and test environments.
+ */
+export declare class NullRenderer implements Renderer {
+    readonly backend: RendererBackend;
+    isInitialized: boolean;
+    canvas: HTMLCanvasElement | null;
+    private readonly lostListeners;
+    private readonly restoredListeners;
+    init(canvas: HTMLCanvasElement, _options?: RendererOptions): void;
+    render(_context: RenderFrameContext): void;
+    resize(_width: number, _height: number, _dpr: number): void;
+    clear(_color?: readonly [number, number, number, number]): void;
+    getCapabilities(): GraphicsCapabilities;
+    destroy(): void;
+    onContextLost(listener: () => void): () => void;
+    onContextRestored(listener: () => void): () => void;
+}
+/**
+ * Solid, production-grade Canvas 2D Renderer with high-DPI scaling.
+ */
+export declare class Canvas2DRenderer implements Renderer {
+    readonly backend: RendererBackend;
+    isInitialized: boolean;
+    canvas: HTMLCanvasElement | null;
+    ctx: CanvasRenderingContext2D | null;
+    private options;
+    private readonly lostListeners;
+    private readonly restoredListeners;
+    init(canvas: HTMLCanvasElement, options?: RendererOptions): void;
+    render(_context: RenderFrameContext): void;
+    resize(width: number, height: number, dpr: number): void;
+    clear(color?: readonly [number, number, number, number]): void;
+    getCapabilities(): GraphicsCapabilities;
+    destroy(): void;
+    onContextLost(listener: () => void): () => void;
+    onContextRestored(listener: () => void): () => void;
+}
+/**
+ * Standard WebGL 1/2 Renderer with context loss and restore handling.
+ */
+export declare class WebGLRenderer implements Renderer {
+    backend: RendererBackend;
+    isInitialized: boolean;
+    canvas: HTMLCanvasElement | null;
+    gl: WebGLRenderingContext | WebGL2RenderingContext | null;
+    private options;
+    private readonly lostListeners;
+    private readonly restoredListeners;
+    private unbindContextLost;
+    private unbindContextRestored;
+    init(canvas: HTMLCanvasElement, options?: RendererOptions): void;
+    render(_context: RenderFrameContext): void;
+    resize(width: number, height: number, dpr: number): void;
+    clear(color?: readonly [number, number, number, number]): void;
+    getCapabilities(): GraphicsCapabilities;
+    destroy(): void;
+    onContextLost(listener: () => void): () => void;
+    onContextRestored(listener: () => void): () => void;
+}
+/**
+ * Creates an appropriate renderer based on requested options with graceful fallback.
+ * If WebGL is requested but fails, falls back cleanly to Canvas2D (or NullRenderer in headless).
+ */
+export declare function createRenderer(options?: RendererOptions): Renderer;

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

@@ -0,0 +1,6 @@
+import type { ResourceManager } from "./types.js";
+/**
+ * Creates a deterministic, idempotent Resource Manager for tracking
+ * graphics assets (buffers, textures, shaders, framebuffers, timers, event unbinds).
+ */
+export declare function createResourceManager(): ResourceManager;