af-motion 0.0.0-stage → 1.0.0

package/dist/core/performance-optimizer/profiler.d.ts

@@ -0,0 +1,38 @@
+/**
+ * AF Motion — Performance Profiler Subsystem
+ *
+ * Captures point-in-time performance snapshots, maintains bounded historical samples,
+ * tracks CPU/GPU/Simulation/Memory timings with strict measured vs estimated status tags.
+ */
+import type { IPerformanceProfiler, PerformanceProfilerOptions, PerformanceSnapshot } from "./types.js";
+export declare class PerformanceProfiler implements IPerformanceProfiler {
+    private readonly _windowSize;
+    private readonly _isGpuTimingSupported;
+    private readonly _onSnapshot?;
+    private readonly _snapshots;
+    private _sessionStartTime;
+    private _isProfiling;
+    private _snapshotCounter;
+    private _isDisposed;
+    constructor(options?: PerformanceProfilerOptions);
+    get isProfilingActive(): boolean;
+    get latestSnapshot(): PerformanceSnapshot | null;
+    startSession(label?: string): void;
+    stopSession(): PerformanceSnapshot | null;
+    captureSnapshot(manualInputs?: Partial<PerformanceSnapshot>): PerformanceSnapshot;
+    getHistoricalSnapshots(): readonly PerformanceSnapshot[];
+    getAverageMetrics(): {
+        avgFps: number;
+        avgFrameDurationMs: number;
+        avgSimMs: number;
+        avgRenderMs: number;
+    };
+    reset(): void;
+    dispose(): void;
+    private pushSnapshot;
+    private createDefaultSnapshot;
+}
+/**
+ * Factory function to instantiate a PerformanceProfiler.
+ */
+export declare function createPerformanceProfiler(options?: PerformanceProfilerOptions): PerformanceProfiler;

package/dist/core/performance-optimizer/react.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AF Motion — React Performance Optimizer Hooks & Components
+ *
+ * React 18 & 19 compatible hooks and components with Strict Mode safety,
+ * SSR safety, and minimal re-render subscriptions.
+ */
+import { type ReactNode } from "react";
+import type { IPerformanceProfiler, IPerformanceOptimizer, PerformanceOptimizerOptions, PerformanceProfilerOptions, BottleneckAnalysisReport, AppliedOptimizationRecord, OptimizationCandidate, OptimizationMode } from "./types.js";
+/**
+ * React hook to manage an active PerformanceProfiler session.
+ */
+export declare function usePerformanceProfiler(options?: PerformanceProfilerOptions): IPerformanceProfiler;
+/**
+ * React hook to query the latest performance report and bottlenecks.
+ */
+export declare function usePerformanceReport(optimizerOrProfiler?: IPerformanceOptimizer | IPerformanceProfiler): {
+    bottlenecks: BottleneckAnalysisReport;
+    recommendations: readonly OptimizationCandidate[];
+    refresh: () => void;
+};
+/**
+ * React hook providing full performance optimizer controls.
+ */
+export declare function usePerformanceOptimizer(options?: PerformanceOptimizerOptions): IPerformanceOptimizer;
+/**
+ * React hook to subscribe to optimization history and active optimizations.
+ */
+export declare function useOptimizationHistory(optimizer?: IPerformanceOptimizer): {
+    activeOptimizations: readonly AppliedOptimizationRecord[];
+    history: readonly AppliedOptimizationRecord[];
+};
+/**
+ * Headless or visual Performance Monitor component.
+ */
+export declare function PerformanceMonitor({ optimizer, children, }: {
+    optimizer?: IPerformanceOptimizer;
+    children?: ReactNode;
+}): import("react").DetailedReactHTMLElement<{
+    "data-af-performance-monitor": string;
+    style: {
+        display: "contents";
+    };
+}, HTMLElement>;
+/**
+ * Boundary that catches rendering performance issues and provides automatic rollback.
+ */
+export declare function OptimizationBoundary({ fallbackMode, children, }: {
+    fallbackMode?: OptimizationMode;
+    children?: ReactNode;
+}): import("react").DetailedReactHTMLElement<{
+    "data-af-optimization-boundary": string;
+    style: {
+        display: "contents";
+    };
+}, HTMLElement>;

package/dist/core/performance-optimizer/strategies.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AF Motion — Registered Optimization Strategies
+ *
+ * Concrete optimization strategies across CPU, Memory, GPU, Simulation, and Worker tiers.
+ * Each strategy defines its target bottleneck, safety score, estimated benefit, and execution hooks.
+ */
+import type { OptimizationStrategyId, OptimizationCategory, OptimizationMode, OptimizationCandidate, BottleneckItem } from "./types.js";
+export interface StrategyDefinition {
+    id: OptimizationStrategyId;
+    category: OptimizationCategory;
+    title: string;
+    description: string;
+    targetBottleneckPatterns: string[];
+    safetyScore: number;
+    estimatedBenefitMs: number;
+    minModeRequired: OptimizationMode;
+    apply: () => void | Promise<void>;
+    rollback: () => void | Promise<void>;
+}
+export declare const REGISTERED_STRATEGIES: readonly StrategyDefinition[];
+export declare function getStrategyById(id: OptimizationStrategyId): StrategyDefinition | undefined;
+export declare function getCandidatesForBottlenecks(bottlenecks: readonly BottleneckItem[], mode?: OptimizationMode, enabledCategories?: ReadonlySet<OptimizationCategory> | readonly OptimizationCategory[]): OptimizationCandidate[];

package/dist/core/performance-optimizer/types.d.ts

@@ -0,0 +1,227 @@
+/**
+ * AF Motion — Automatic Performance Optimization Engine Types
+ *
+ * Interfaces, metric classifications, bottleneck taxonomy, optimization candidates,
+ * worker execution contracts, and optimization history.
+ */
+import type { DeviceCapabilityProfile } from "../device-capabilities/types.js";
+import type { IAdaptiveQualityController } from "../adaptive-quality/types.js";
+/**
+ * Metric measurement status.
+ */
+export type MetricMeasurementStatus = "measured" | "estimated" | "unsupported";
+/**
+ * Value tagged with measurement integrity, status, and confidence.
+ */
+export interface PerformanceMetricValue<T> {
+    readonly value: T;
+    readonly status: MetricMeasurementStatus;
+    readonly confidence: number;
+    readonly timestamp: number;
+}
+/**
+ * Comprehensive performance snapshot representing a point-in-time profiling capture.
+ */
+export interface PerformanceSnapshot {
+    readonly id: string;
+    readonly timestamp: number;
+    readonly sessionDurationMs: number;
+    readonly frameDurationMs: PerformanceMetricValue<number>;
+    readonly fps: PerformanceMetricValue<number>;
+    readonly animationUpdateMs: PerformanceMetricValue<number>;
+    readonly simulationDurationMs: PerformanceMetricValue<number>;
+    readonly renderSubmissionMs: PerformanceMetricValue<number>;
+    readonly geometryProcessingMs: PerformanceMetricValue<number>;
+    readonly modelLoadingMs: PerformanceMetricValue<number>;
+    readonly gpuExecutionMs: PerformanceMetricValue<number>;
+    readonly isGpuTimingSupported: boolean;
+    readonly memoryAllocationRateKBPerFrame: PerformanceMetricValue<number>;
+    readonly estimatedHeapUsedMB: PerformanceMetricValue<number>;
+    readonly resourceUtilizationRatio: PerformanceMetricValue<number>;
+    readonly longTasksCount: PerformanceMetricValue<number>;
+    readonly eventProcessingMs: PerformanceMetricValue<number>;
+    readonly repeatedCalculationsCount: PerformanceMetricValue<number>;
+    readonly activeWorkloadItems: number;
+}
+/**
+ * Bottleneck classification categories.
+ */
+export type BottleneckCategory = "cpu" | "gpu" | "memory" | "simulation";
+/**
+ * Bottleneck severity levels.
+ */
+export type BottleneckSeverity = "low" | "medium" | "high" | "critical";
+/**
+ * Identified performance bottleneck descriptor.
+ */
+export interface BottleneckItem {
+    readonly id: string;
+    readonly category: BottleneckCategory;
+    readonly severity: BottleneckSeverity;
+    readonly title: string;
+    readonly description: string;
+    readonly confidence: number;
+    readonly isHardwareConfirmed: boolean;
+    readonly primaryMetric: string;
+    readonly metricValue: number;
+    readonly threshold: number;
+    readonly recommendedAction: string;
+}
+/**
+ * Consolidated bottleneck analysis report.
+ */
+export interface BottleneckAnalysisReport {
+    readonly timestamp: number;
+    readonly bottlenecks: readonly BottleneckItem[];
+    readonly dominantBottleneckCategory: BottleneckCategory | "none";
+    readonly overallHealthScore: number;
+    readonly summary: string;
+    readonly recommendations: readonly string[];
+}
+/**
+ * Optimization operational categories.
+ */
+export type OptimizationCategory = "cpu" | "memory" | "gpu" | "simulation" | "worker";
+/**
+ * Optimization orchestration modes.
+ */
+export type OptimizationMode = "conservative" | "balanced" | "aggressive" | "custom";
+/**
+ * Unique identifier for registered optimization strategies.
+ */
+export type OptimizationStrategyId = "cpu_batch_operations" | "cpu_memoize_math" | "cpu_spatial_query_throttle" | "cpu_chunk_large_workloads" | "mem_recycle_typed_arrays" | "mem_lru_cache_trimming" | "mem_dispose_stale_resources" | "gpu_recommend_instancing" | "gpu_shader_variant_deduplication" | "gpu_texture_mip_clamping" | "sim_adaptive_particle_batching" | "sim_fluid_iteration_damping" | "sim_physics_sleeping_enhancement" | "sim_visibility_culling" | "worker_offload_geometry";
+/**
+ * Candidate optimization recommended by the engine.
+ */
+export interface OptimizationCandidate {
+    readonly id: OptimizationStrategyId;
+    readonly category: OptimizationCategory;
+    readonly title: string;
+    readonly description: string;
+    readonly targetBottleneckId: string;
+    readonly safetyScore: number;
+    readonly estimatedBenefitMs: number;
+    readonly minModeRequired: OptimizationMode;
+    readonly isCompatible: boolean;
+    readonly incompatibilities: readonly string[];
+}
+/**
+ * Record of an applied optimization action and its verification outcome.
+ */
+export interface AppliedOptimizationRecord {
+    readonly id: string;
+    readonly strategyId: OptimizationStrategyId;
+    readonly category: OptimizationCategory;
+    readonly appliedAt: number;
+    readonly baselineFps: number;
+    readonly baselineFrameDurationMs: number;
+    readonly postFps?: number;
+    readonly postFrameDurationMs?: number;
+    readonly status: "applied" | "verified_improved" | "verified_neutral" | "rolled_back" | "failed";
+    readonly deltaFrameDurationMs?: number;
+    readonly rollbackReason?: string;
+}
+/**
+ * Configuration options for the Performance Profiler.
+ */
+export interface PerformanceProfilerOptions {
+    samplingWindowSize?: number;
+    enableDetailedTimers?: boolean;
+    isGpuTimingSupported?: boolean;
+    onSnapshot?: (snapshot: PerformanceSnapshot) => void;
+}
+/**
+ * Configuration options for the Automatic Performance Optimizer.
+ */
+export interface PerformanceOptimizerOptions {
+    mode?: OptimizationMode;
+    enabledCategories?: ReadonlySet<OptimizationCategory> | readonly OptimizationCategory[];
+    deviceProfile?: DeviceCapabilityProfile;
+    adaptiveQualityController?: IAdaptiveQualityController;
+    verificationWindowFrames?: number;
+    autoRollbackHarmful?: boolean;
+    maxActiveOptimizations?: number;
+    profilerOptions?: PerformanceProfilerOptions;
+}
+/**
+ * Worker task execution priority.
+ */
+export type WorkerTaskPriority = "low" | "medium" | "high" | "critical";
+/**
+ * Task definition submitted to WorkerTaskManager.
+ */
+export interface WorkerTaskDefinition<TInput = any, TOutput = any> {
+    readonly id: string;
+    readonly type: string;
+    readonly priority?: WorkerTaskPriority;
+    readonly payload: TInput;
+    readonly transferables?: readonly Transferable[];
+    readonly signal?: AbortSignal;
+    readonly computeFallback?: (payload: TInput) => Promise<TOutput> | TOutput;
+}
+/**
+ * Result returned from WorkerTaskManager.
+ */
+export interface WorkerTaskResult<TOutput = any> {
+    readonly taskId: string;
+    readonly success: boolean;
+    readonly data?: TOutput;
+    readonly error?: string;
+    readonly executionTimeMs: number;
+    readonly executedInWorker: boolean;
+}
+/**
+ * Contract for worker task scheduler.
+ */
+export interface IWorkerTaskManager {
+    readonly isWorkerSupported: boolean;
+    readonly activeWorkerCount: number;
+    readonly queuedTaskCount: number;
+    executeTask<TInput, TOutput>(task: WorkerTaskDefinition<TInput, TOutput>): Promise<WorkerTaskResult<TOutput>>;
+    cancelTask(taskId: string): boolean;
+    dispose(): void;
+}
+/**
+ * Public interface of Performance Profiler.
+ */
+export interface IPerformanceProfiler {
+    readonly isProfilingActive: boolean;
+    readonly latestSnapshot: PerformanceSnapshot | null;
+    startSession(label?: string): void;
+    stopSession(): PerformanceSnapshot | null;
+    captureSnapshot(manualInputs?: Partial<PerformanceSnapshot>): PerformanceSnapshot;
+    getHistoricalSnapshots(): readonly PerformanceSnapshot[];
+    getAverageMetrics(): {
+        avgFps: number;
+        avgFrameDurationMs: number;
+        avgSimMs: number;
+        avgRenderMs: number;
+    };
+    reset(): void;
+    dispose(): void;
+}
+/**
+ * Public interface of Automatic Performance Optimizer.
+ */
+export interface IPerformanceOptimizer {
+    readonly mode: OptimizationMode;
+    readonly profiler: IPerformanceProfiler;
+    readonly activeOptimizations: readonly AppliedOptimizationRecord[];
+    readonly bottleneckReport: BottleneckAnalysisReport;
+    setMode(mode: OptimizationMode): void;
+    setCategoryEnabled(category: OptimizationCategory, enabled: boolean): void;
+    isCategoryEnabled(category: OptimizationCategory): boolean;
+    analyzeBottlenecks(): BottleneckAnalysisReport;
+    recommendOptimizations(): readonly OptimizationCandidate[];
+    applyOptimization(strategyId: OptimizationStrategyId): Promise<AppliedOptimizationRecord>;
+    rollbackOptimization(strategyId: OptimizationStrategyId, reason?: string): boolean;
+    rollbackAllOptimizations(reason?: string): void;
+    getOptimizationHistory(): readonly AppliedOptimizationRecord[];
+    getPerformanceReport(): {
+        bottlenecks: BottleneckAnalysisReport;
+        activeOptimizations: readonly AppliedOptimizationRecord[];
+        latestSnapshot: PerformanceSnapshot | null;
+        recommendations: readonly OptimizationCandidate[];
+    };
+    dispose(): void;
+}

package/dist/core/performance-optimizer/workers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AF Motion — Parallel Worker Task Manager
+ *
+ * Provides safe background execution with cancellation, priority scheduling,
+ * transferable buffer support, and seamless synchronous fallbacks for SSR/Node environments.
+ */
+import type { IWorkerTaskManager, WorkerTaskDefinition, WorkerTaskResult } from "./types.js";
+export interface WorkerTaskManagerOptions {
+    maxConcurrency?: number;
+    enableWorkers?: boolean;
+}
+export declare class WorkerTaskManager implements IWorkerTaskManager {
+    private readonly _isWorkerSupported;
+    private readonly _maxConcurrency;
+    private readonly _activeTasks;
+    private readonly _taskQueue;
+    private _runningCount;
+    private _isDisposed;
+    constructor(options?: WorkerTaskManagerOptions);
+    get isWorkerSupported(): boolean;
+    get activeWorkerCount(): number;
+    get queuedTaskCount(): number;
+    executeTask<TInput, TOutput>(task: WorkerTaskDefinition<TInput, TOutput>): Promise<WorkerTaskResult<TOutput>>;
+    cancelTask(taskId: string): boolean;
+    dispose(): void;
+}
+export declare function createWorkerTaskManager(options?: WorkerTaskManagerOptions): WorkerTaskManager;

package/dist/core/physics/collision-constraints.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion — Physical Constraints Engine
+ *
+ * Implements fixed-point anchors, distance rods, Hookean spring constraints,
+ * axis locks, min/max rope constraints, and bounding region constraints.
+ */
+import type { CollisionConstraint } from "./collision-types.js";
+/**
+ * Resolves a single physical constraint for the active frame.
+ */
+export declare function resolveConstraint(constraint: CollisionConstraint, dt: number): void;
+/**
+ * Solves a batch of constraints iteratively.
+ */
+export declare function resolveConstraintBatch(constraints: CollisionConstraint[], dt: number, iterations?: number): void;

package/dist/core/physics/collision-detection.d.ts

@@ -0,0 +1,93 @@
+/**
+ * AF Motion — Collision Detection Engine
+ *
+ * Implements 2D & 3D narrow-phase collision algorithms, point containment tests,
+ * AABB bounding calculations, and broad-phase spatial filtering.
+ */
+import type { PhysicsVector } from "./types.js";
+import type { CollisionBody, CollisionContact, AABB } from "./collision-types.js";
+/**
+ * Tests if a point lies within a 2D circle.
+ */
+export declare function pointInCircle(point: PhysicsVector, center: PhysicsVector, radius: number): boolean;
+/**
+ * Tests if a point lies within an axis-aligned 2D rectangle.
+ */
+export declare function pointInRectangle(point: PhysicsVector, center: PhysicsVector, width: number, height: number): boolean;
+/**
+ * Tests if a point lies within a 3D sphere.
+ */
+export declare function pointInSphere(point: PhysicsVector, center: PhysicsVector, radius: number): boolean;
+/**
+ * Tests if a point lies within a 3D axis-aligned bounding box.
+ */
+export declare function pointInBox(point: PhysicsVector, center: PhysicsVector, sizeX: number, sizeY: number, sizeZ: number): boolean;
+/**
+ * Computes an axis-aligned bounding box (AABB) enclosing a collision body.
+ */
+export declare function computeBodyAABB(body: CollisionBody): AABB;
+/**
+ * Checks whether two axis-aligned bounding boxes overlap in all dimensions.
+ */
+export declare function aabbOverlap(a: AABB, b: AABB): boolean;
+/**
+ * Determines whether two bodies pass broad-phase collision layer/mask filtering.
+ */
+export declare function canCollide(bodyA: CollisionBody, bodyB: CollisionBody): boolean;
+/**
+ * 2D Circle-to-Circle collision intersection test.
+ */
+export declare function intersectCircleCircle(posA: PhysicsVector, radiusA: number, posB: PhysicsVector, radiusB: number): {
+    collided: boolean;
+    contactPoint: PhysicsVector;
+    normal: PhysicsVector;
+    penetration: number;
+};
+/**
+ * 2D Rectangle-to-Rectangle (AABB) collision intersection test.
+ */
+export declare function intersectRectangleRectangle(posA: PhysicsVector, widthA: number, heightA: number, posB: PhysicsVector, widthB: number, heightB: number): {
+    collided: boolean;
+    contactPoint: PhysicsVector;
+    normal: PhysicsVector;
+    penetration: number;
+};
+/**
+ * 2D Circle-to-Rectangle collision intersection test.
+ */
+export declare function intersectCircleRectangle(posCircle: PhysicsVector, radius: number, posRect: PhysicsVector, width: number, height: number, circleIsA: boolean): {
+    collided: boolean;
+    contactPoint: PhysicsVector;
+    normal: PhysicsVector;
+    penetration: number;
+};
+/**
+ * 3D Sphere-to-Sphere collision intersection test.
+ */
+export declare function intersectSphereSphere(posA: PhysicsVector, radiusA: number, posB: PhysicsVector, radiusB: number): {
+    collided: boolean;
+    contactPoint: PhysicsVector;
+    normal: PhysicsVector;
+    penetration: number;
+};
+/**
+ * 3D Box-to-Box (AABB) collision intersection test.
+ */
+export declare function intersectBoxBox(posA: PhysicsVector, sizeA: {
+    sizeX: number;
+    sizeY: number;
+    sizeZ: number;
+}, posB: PhysicsVector, sizeB: {
+    sizeX: number;
+    sizeY: number;
+    sizeZ: number;
+}): {
+    collided: boolean;
+    contactPoint: PhysicsVector;
+    normal: PhysicsVector;
+    penetration: number;
+};
+/**
+ * Performs narrow-phase collision detection between two arbitrary rigid bodies.
+ */
+export declare function detectBodyCollision(bodyA: CollisionBody, bodyB: CollisionBody): CollisionContact | null;

package/dist/core/physics/collision-response.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AF Motion — Collision Response Engine
+ *
+ * Implements impulse-based velocity resolution, Coulomb surface friction,
+ * mass-aware elastic/inelastic collisions, Baumgarte positional stabilization,
+ * and multi-contact iterative solvers.
+ */
+import type { CollisionContact } from "./collision-types.js";
+/**
+ * Resolves velocity impulses for a collision contact manifold along the normal.
+ */
+export declare function resolveCollisionImpulse(contact: CollisionContact, restitutionOverride?: number): void;
+/**
+ * Resolves tangential friction impulses opposing sliding motion during contact.
+ */
+export declare function resolveFrictionImpulse(contact: CollisionContact, normalImpulseMagnitude: number): void;
+/**
+ * Resolves positional penetration via Baumgarte linear projection without altering velocities.
+ */
+export declare function resolvePositionalCorrection(contact: CollisionContact, slop?: number, percent?: number): void;
+/**
+ * Solves a batch of collision contacts iteratively for numerical stability.
+ */
+export declare function resolveContactBatch(contacts: CollisionContact[], iterations?: number, slop?: number, percent?: number): void;