af-motion 0.0.0-stage → 1.0.0

package/dist/core/performance-intelligence/context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * AF Motion — Unified Performance Context Aggregator
+ *
+ * Synthesizes hardware capabilities, active quality profiles, runtime telemetry,
+ * bottleneck diagnostics, and resource usage into a single coherent state snapshot.
+ */
+import type { DeviceCapabilityProfile } from "../device-capabilities/types.js";
+import type { IAdaptiveQualityController, QualityProfile, QualityPresetName } from "../adaptive-quality/types.js";
+import type { IPerformanceOptimizer, BottleneckAnalysisReport } from "../performance-optimizer/types.js";
+import type { IResourceRegistry, IMemoryMonitor, MemoryPressureLevel, MemorySnapshot } from "../resource-intelligence/types.js";
+import type { UnifiedPerformanceContext } from "./types.js";
+export interface ContextAggregationSources {
+    deviceProfile?: DeviceCapabilityProfile | any;
+    qualityController?: IAdaptiveQualityController;
+    qualityProfile?: Partial<QualityProfile> & {
+        name?: QualityPresetName;
+        isLocked?: boolean;
+    };
+    optimizer?: IPerformanceOptimizer;
+    registry?: IResourceRegistry;
+    resourceManager?: any;
+    memoryMonitor?: IMemoryMonitor;
+    memorySnapshot?: Partial<MemorySnapshot>;
+    memoryPressure?: MemoryPressureLevel;
+    metrics?: {
+        fps?: number;
+        frameDurationMs?: number;
+        frameTimeVariance?: number;
+        frameDrops?: number;
+        longTasksCount?: number;
+    };
+    bottlenecks?: BottleneckAnalysisReport | {
+        dominantBottleneck?: string;
+        dominantBottleneckCategory?: string;
+    };
+    telemetry?: {
+        isVisible?: boolean;
+        batteryLevel?: number;
+        isBatteryCharging?: boolean;
+        isDataSaver?: boolean;
+    };
+    isVisible?: boolean;
+}
+export type PerformanceIntelligenceContextSources = ContextAggregationSources;
+/**
+ * Builds a UnifiedPerformanceContext from the given subsystems or default fallbacks.
+ */
+export declare function buildUnifiedPerformanceContext(sources?: ContextAggregationSources): UnifiedPerformanceContext;

package/dist/core/performance-intelligence/coordinator.d.ts

@@ -0,0 +1,84 @@
+/**
+ * AF Motion — Unified Performance Intelligence Coordinator
+ *
+ * Central orchestrator connecting device detection, adaptive rendering, automatic
+ * optimization, and resource intelligence into a unified, coordinated control loop.
+ */
+import type { IPerformanceIntelligence, UnifiedPerformanceContext, PerformanceHealthScores, PerformanceDecision, ConflictResolutionResult, DecisionExecutionResult, UnifiedPerformanceReport, PerformanceIntelligenceOptions } from "./types.js";
+import { type PerformanceIntelligenceContextSources } from "./context.js";
+export declare class PerformanceIntelligenceCoordinator implements IPerformanceIntelligence {
+    private _isRunning;
+    private _context;
+    private _health;
+    private _intervalTimer;
+    private readonly _options;
+    private readonly _sources?;
+    private readonly _history;
+    private readonly _listeners;
+    constructor(options?: PerformanceIntelligenceOptions, sources?: PerformanceIntelligenceContextSources);
+    get isRunning(): boolean;
+    get context(): UnifiedPerformanceContext;
+    get health(): PerformanceHealthScores;
+    /**
+     * Starts periodic performance evaluation loop.
+     */
+    start(): void;
+    /**
+     * Pauses evaluation loop without disposing state.
+     */
+    pause(): void;
+    /**
+     * Resumes evaluation loop.
+     */
+    resume(): void;
+    /**
+     * Refreshes unified context snapshot from underlying sources.
+     */
+    refresh(): UnifiedPerformanceContext;
+    /**
+     * Re-evaluates multi-dimensional health scores for current context.
+     */
+    evaluateHealth(): PerformanceHealthScores;
+    /**
+     * Synthesizes proposed performance decisions.
+     */
+    generateDecisions(): readonly PerformanceDecision[];
+    /**
+     * Resolves conflicts among decisions.
+     */
+    resolveConflicts(decisions?: readonly PerformanceDecision[]): ConflictResolutionResult;
+    /**
+     * Applies validated decisions to underlying subsystems.
+     */
+    applyDecisions(decisions?: readonly PerformanceDecision[]): Promise<readonly DecisionExecutionResult[]>;
+    /**
+     * Returns snapshot history buffer.
+     */
+    getHistory(): readonly UnifiedPerformanceContext[];
+    /**
+     * Compares two snapshots.
+     */
+    compareSnapshots(before: UnifiedPerformanceContext, after: UnifiedPerformanceContext): import("./history.js").SnapshotComparison;
+    /**
+     * Generates diagnostic report.
+     */
+    getReport(): UnifiedPerformanceReport;
+    /**
+     * Resets history and stops loop.
+     */
+    reset(): void;
+    /**
+     * Disposes all timers and listeners.
+     */
+    dispose(): void;
+    /**
+     * Subscribe to context and health changes.
+     */
+    subscribe(listener: (ctx: UnifiedPerformanceContext, health: PerformanceHealthScores) => void): () => void;
+    private _notify;
+}
+/**
+ * Factory helper for instantiating Unified Performance Intelligence.
+ */
+export declare function createPerformanceIntelligence(options?: PerformanceIntelligenceOptions, sources?: PerformanceIntelligenceContextSources): IPerformanceIntelligence;
+export declare const defaultPerformanceIntelligence: IPerformanceIntelligence;

package/dist/core/performance-intelligence/decisions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AF Motion — Performance Decision Generator
+ *
+ * Evaluates performance context and multi-dimensional health scores against
+ * active decision policies to synthesize actionable, prioritised recommendations.
+ */
+import type { UnifiedPerformanceContext, PerformanceHealthScores, PerformanceDecision } from "./types.js";
+import { type DecisionPolicy } from "./policies.js";
+/**
+ * Generate discrete performance decisions based on current context and health scores.
+ *
+ * @param ctx Current unified performance context snapshot
+ * @param health Evaluated performance health scores
+ * @param policies Optional custom or extended policies to evaluate (defaults to standard set)
+ * @returns Sorted array of performance decisions ordered by priority (highest first)
+ */
+export declare function generatePerformanceDecisions(ctx: UnifiedPerformanceContext, health: PerformanceHealthScores, policies?: readonly DecisionPolicy[]): readonly PerformanceDecision[];

package/dist/core/performance-intelligence/history.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AF Motion — Performance Intelligence History & Analysis
+ *
+ * Tracks bounded temporal history of performance snapshots and decisions,
+ * offering before-and-after comparison and trend analysis.
+ */
+import type { UnifiedPerformanceContext } from "./types.js";
+export interface SnapshotComparison {
+    readonly fpsDelta: number;
+    readonly frameDurationDeltaMs: number;
+    readonly memoryDeltaMB: number;
+    readonly improved: boolean;
+    readonly summary: string;
+}
+export declare class PerformanceHistoryTracker {
+    private readonly capacity;
+    private readonly snapshots;
+    constructor(capacity?: number);
+    /**
+     * Record a context snapshot into the bounded buffer.
+     */
+    push(snapshot: UnifiedPerformanceContext): void;
+    /**
+     * Get all recorded snapshots (oldest to newest).
+     */
+    getHistory(): readonly UnifiedPerformanceContext[];
+    /**
+     * Clear all recorded snapshots.
+     */
+    clear(): void;
+    /**
+     * Compare two snapshots to evaluate impact.
+     */
+    compareSnapshots(before: UnifiedPerformanceContext, after: UnifiedPerformanceContext): SnapshotComparison;
+    /**
+     * Analyze recent trends over the recorded snapshot window.
+     */
+    analyzeTrend(): {
+        fpsTrend: "improving" | "stable" | "degrading";
+        memoryTrend: "growing" | "stable" | "shrinking";
+        averageFps: number;
+        sampleCount: number;
+    };
+}

package/dist/core/performance-intelligence/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion — Unified Performance Intelligence Engine
+ *
+ * Centralized, multi-system coordination engine harmonizing device capability detection,
+ * adaptive quality control, automatic bottleneck optimization, and memory/resource intelligence.
+ */
+export type { PerformanceDecisionCategory, DecisionRiskLevel, ResponsibleSubsystem, PerformanceDecision, DimensionHealthScore, PerformanceHealthScores, UnifiedPerformanceContext, ConflictResolutionResult, DecisionExecutionResult, UnifiedPerformanceReport, PerformanceIntelligenceOptions, IPerformanceIntelligence, } from "./types.js";
+export { buildUnifiedPerformanceContext, type PerformanceIntelligenceContextSources, } from "./context.js";
+export { evaluatePerformanceHealth, determineHealthStatus, HEALTH_SCORING_WEIGHTS, } from "./scoring.js";
+export { type DecisionPolicy, QUALITY_PRESET_LADDER, getLowerQualityPreset, getHigherQualityPreset, QualityDegradationPolicy, QualityRecoveryPolicy, CpuOptimizationPolicy, MemoryPruningPolicy, GpuOptimizationPolicy, SimulationAdjustmentPolicy, BackgroundMaintenancePolicy, DEFAULT_PERFORMANCE_POLICIES, } from "./policies.js";
+export { generatePerformanceDecisions } from "./decisions.js";
+export { resolvePerformanceConflicts } from "./conflicts.js";
+export { PerformanceHistoryTracker, type SnapshotComparison, } from "./history.js";
+export { buildUnifiedPerformanceReport } from "./report.js";
+export { PerformanceIntelligenceCoordinator, createPerformanceIntelligence, defaultPerformanceIntelligence, } from "./coordinator.js";

package/dist/core/performance-intelligence/policies.d.ts

@@ -0,0 +1,59 @@
+/**
+ * AF Motion — Unified Performance Intelligence Policies
+ *
+ * Rule definitions and threshold criteria for generating performance decisions
+ * across quality scaling, resource management, bottleneck mitigation, and simulation tuning.
+ */
+import type { UnifiedPerformanceContext, PerformanceHealthScores, PerformanceDecision, PerformanceDecisionCategory, PerformanceQualityPreset } from "./types.js";
+export interface DecisionPolicy {
+    readonly id: string;
+    readonly category: PerformanceDecisionCategory;
+    readonly name: string;
+    readonly description: string;
+    readonly evaluate: (ctx: UnifiedPerformanceContext, health: PerformanceHealthScores) => PerformanceDecision | null;
+}
+/**
+ * Quality preset hierarchy for progressive stepping.
+ */
+export declare const QUALITY_PRESET_LADDER: readonly PerformanceQualityPreset[];
+/**
+ * Helper to step quality down one notch.
+ */
+export declare function getLowerQualityPreset(current: PerformanceQualityPreset): PerformanceQualityPreset | null;
+/**
+ * Helper to step quality up one notch.
+ */
+export declare function getHigherQualityPreset(current: PerformanceQualityPreset): PerformanceQualityPreset | null;
+/**
+ * 1. Critical Frame Drop & Rendering Policy: Degrade quality when frame health is degraded/critical.
+ */
+export declare const QualityDegradationPolicy: DecisionPolicy;
+/**
+ * 2. Quality Recovery Policy: Promotes quality when stable frame headroom exists.
+ */
+export declare const QualityRecoveryPolicy: DecisionPolicy;
+/**
+ * 3. CPU Bottleneck & Animation Throttling Policy.
+ */
+export declare const CpuOptimizationPolicy: DecisionPolicy;
+/**
+ * 4. Memory Pressure & Resource Pruning Policy.
+ */
+export declare const MemoryPruningPolicy: DecisionPolicy;
+/**
+ * 5. GPU Shading & Resolution Scaling Policy.
+ */
+export declare const GpuOptimizationPolicy: DecisionPolicy;
+/**
+ * 6. Simulation Fidelity Adjustment Policy.
+ * Note: Simulation throttling MUST NOT compromise simulation correctness invariants.
+ */
+export declare const SimulationAdjustmentPolicy: DecisionPolicy;
+/**
+ * 7. Background Visibility Maintenance Policy.
+ */
+export declare const BackgroundMaintenancePolicy: DecisionPolicy;
+/**
+ * Default standard decision policy set.
+ */
+export declare const DEFAULT_PERFORMANCE_POLICIES: readonly DecisionPolicy[];

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

@@ -0,0 +1,78 @@
+/**
+ * AF Motion — React Performance Intelligence Hooks & Components
+ *
+ * React 18 & 19 compatible hooks and components with SSR safety, Strict Mode
+ * resilience, and reactive subscriber state synchronization.
+ */
+import { type ReactNode } from "react";
+import type { IPerformanceIntelligence, UnifiedPerformanceContext, PerformanceHealthScores, PerformanceDecision, UnifiedPerformanceReport } from "./types.js";
+import { defaultPerformanceIntelligence } from "./coordinator.js";
+export { defaultPerformanceIntelligence };
+export declare const PerformanceIntelligenceContext: import("react").Context<IPerformanceIntelligence>;
+export interface PerformanceIntelligenceProviderProps {
+    coordinator?: IPerformanceIntelligence;
+    children: ReactNode;
+}
+/**
+ * Context Provider for scoping Performance Intelligence within a React component tree.
+ */
+export declare function PerformanceIntelligenceProvider(props: PerformanceIntelligenceProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<IPerformanceIntelligence>>;
+/**
+ * Hook to access the Performance Intelligence coordinator instance.
+ */
+export declare function usePerformanceIntelligence(): IPerformanceIntelligence;
+/**
+ * Hook to subscribe to the current UnifiedPerformanceContext.
+ */
+export declare function usePerformanceContext(): UnifiedPerformanceContext;
+/**
+ * Hook to subscribe to the evaluated PerformanceHealthScores.
+ */
+export declare function usePerformanceHealth(): PerformanceHealthScores;
+/**
+ * Hook to retrieve and re-evaluate pending performance decisions.
+ */
+export declare function usePerformanceDecisions(): readonly PerformanceDecision[];
+/**
+ * Hook to retrieve the latest comprehensive UnifiedPerformanceReport.
+ */
+export declare function useUnifiedPerformanceReport(): UnifiedPerformanceReport;
+/**
+ * Compact status badge indicating real-time performance health and overall score.
+ */
+export declare function PerformanceStatus(props: {
+    className?: string;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    style: {
+        display: "inline-flex";
+        alignItems: "center";
+        gap: string;
+        padding: string;
+        borderRadius: string;
+        fontSize: string;
+        fontFamily: "monospace";
+        backgroundColor: "rgba(0, 0, 0, 0.75)";
+        color: "#ffffff";
+    };
+}, HTMLElement>;
+/**
+ * Comprehensive visual performance diagnostic dashboard component.
+ */
+export declare function PerformanceDashboard(props: {
+    className?: string;
+    showDecisions?: boolean;
+}): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    "aria-label": string;
+    style: {
+        padding: string;
+        backgroundColor: "#18181b";
+        color: "#f4f4f5";
+        borderRadius: string;
+        fontFamily: "system-ui, -apple-system, sans-serif";
+        fontSize: string;
+        maxWidth: string;
+        boxShadow: "0 4px 12px rgba(0, 0, 0, 0.3)";
+    };
+}, HTMLElement>;

package/dist/core/performance-intelligence/report.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion — Unified Performance Diagnostic Report
+ *
+ * Formulates clean, circular-reference-free diagnostic performance reports
+ * suitable for structured logging, telemetry exports, and debugging dashboards.
+ */
+import type { UnifiedPerformanceContext, PerformanceHealthScores, PerformanceDecision, UnifiedPerformanceReport } from "./types.js";
+/**
+ * Generate a comprehensive, JSON-serializable performance diagnostic report.
+ *
+ * @param ctx Current unified performance context
+ * @param health Evaluated performance health scores
+ * @param decisions Currently pending or proposed decisions
+ * @returns Clean, structured report
+ */
+export declare function buildUnifiedPerformanceReport(ctx: UnifiedPerformanceContext, health: PerformanceHealthScores, decisions?: readonly PerformanceDecision[]): UnifiedPerformanceReport;

package/dist/core/performance-intelligence/scoring.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion — Unified Performance Health Scoring
+ *
+ * Computes individual health scores for CPU, GPU, Memory, Rendering, Simulation,
+ * and Resources, clearly distinguishing inherent hardware capability from live runtime health.
+ */
+import type { UnifiedPerformanceContext, PerformanceHealthScores, DimensionHealthScore } from "./types.js";
+export declare const HEALTH_SCORING_WEIGHTS: {
+    readonly rendering: 0.35;
+    readonly cpu: 0.2;
+    readonly gpu: 0.15;
+    readonly memory: 0.15;
+    readonly simulation: 0.15;
+};
+export declare function determineHealthStatus(score: number): DimensionHealthScore["status"];
+export declare function evaluatePerformanceHealth(ctx: UnifiedPerformanceContext): PerformanceHealthScores;

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

@@ -0,0 +1,203 @@
+/**
+ * AF Motion — Unified Performance Intelligence Engine Types
+ *
+ * Types, interfaces, health scoring models, decision taxonomy, conflict resolution
+ * specifications, and diagnostic reporting structures for centralized performance coordination.
+ */
+import type { QualityPresetName } from "../adaptive-quality/types.js";
+import type { OptimizationStrategyId } from "../performance-optimizer/types.js";
+import type { MemoryPressureLevel } from "../resource-intelligence/types.js";
+/**
+ * High-level decision categories supported by the Performance Intelligence Engine.
+ */
+export type PerformanceDecisionCategory = "maintain" | "reduce_quality" | "increase_quality" | "optimize_cpu" | "optimize_memory" | "optimize_gpu" | "adjust_simulation" | "release_resources" | "switch_backend" | "user_intervention";
+/**
+ * Performance decision risk rating.
+ */
+export type DecisionRiskLevel = "low" | "medium" | "high";
+/**
+ * Subsystem responsible for executing a decision.
+ */
+export type ResponsibleSubsystem = "quality" | "optimizer" | "resource" | "runtime";
+export type PerformanceQualityPreset = QualityPresetName | "low" | "medium";
+/**
+ * Discrete decision proposed by the decision engine.
+ */
+export interface PerformanceDecision {
+    readonly id: string;
+    readonly category: PerformanceDecisionCategory;
+    readonly reason: string;
+    readonly supportingSignals: readonly string[];
+    readonly priority: number;
+    readonly expectedBenefit: string;
+    readonly riskLevel: DecisionRiskLevel;
+    readonly isReversible: boolean;
+    readonly confidence: number;
+    readonly requiredSubsystem: ResponsibleSubsystem;
+    readonly strategyId?: OptimizationStrategyId | (string & {});
+    readonly targetPreset?: PerformanceQualityPreset;
+    readonly payload?: Readonly<Record<string, any>>;
+}
+/**
+ * Dimensional health score with confidence and explanatory rationale.
+ */
+export interface DimensionHealthScore {
+    readonly score: number;
+    readonly status: "optimal" | "acceptable" | "degraded" | "critical";
+    readonly confidence: number;
+    readonly rationale: string;
+}
+/**
+ * Consolidated multi-dimensional performance health scores.
+ */
+export interface PerformanceHealthScores {
+    readonly timestamp: number;
+    readonly cpuHealth: DimensionHealthScore;
+    readonly gpuHealth: DimensionHealthScore;
+    readonly memoryHealth: DimensionHealthScore;
+    readonly renderingHealth: DimensionHealthScore;
+    readonly simulationHealth: DimensionHealthScore;
+    readonly resourceHealth: DimensionHealthScore;
+    readonly overallHealth: DimensionHealthScore;
+    readonly hardwareCapabilityVsRuntimeHealth: {
+        readonly capabilityScore: number;
+        readonly runtimeHealthScore: number;
+        readonly divergenceRationale: string;
+    };
+}
+/**
+ * Centralized snapshot of the entire AF Motion performance state.
+ */
+export interface UnifiedPerformanceContext {
+    readonly timestamp: number;
+    readonly deviceCategory: string;
+    readonly capabilityScores: {
+        cpu: number;
+        memory: number;
+        gpu: number;
+        composite: number;
+    };
+    readonly activeBackend: string;
+    readonly isReducedMotion: boolean;
+    readonly activeQualityPreset: QualityPresetName;
+    readonly isQualityLocked: boolean;
+    readonly resolutionScale: number;
+    readonly dpr: number;
+    readonly fps: number;
+    readonly frameDurationMs: number;
+    readonly frameTimeVariance: number;
+    readonly frameDrops: number;
+    readonly longTasksCount: number;
+    readonly dominantBottleneck: string;
+    readonly activeOptimizationsCount: number;
+    readonly activeOptimizationIds: readonly string[];
+    readonly totalTrackedResources: number;
+    readonly estimatedMemoryBytes: number;
+    readonly memoryPressureLevel: MemoryPressureLevel;
+    readonly budgetUtilizationRatio: number;
+    readonly isVisible: boolean;
+    readonly batteryLevel?: number;
+    readonly isBatteryCharging?: boolean;
+    readonly isDataSaver: boolean;
+}
+/**
+ * Conflict detection and resolution report.
+ */
+export interface ConflictResolutionResult {
+    readonly hasConflict: boolean;
+    readonly conflictsDetected: readonly {
+        readonly decisionA: PerformanceDecision;
+        readonly decisionB: PerformanceDecision;
+        readonly conflictType: string;
+        readonly resolution: string;
+    }[];
+    readonly resolvedDecisions: readonly PerformanceDecision[];
+}
+/**
+ * Execution result for an applied decision.
+ */
+export interface DecisionExecutionResult {
+    readonly decisionId: string;
+    readonly success: boolean;
+    readonly executedAt: number;
+    readonly error?: string;
+    readonly changesApplied: readonly string[];
+}
+/**
+ * Unified diagnostic performance report suitable for JSON export without circular references.
+ */
+export interface UnifiedPerformanceReport {
+    readonly generatedAt: string;
+    readonly timestamp: number;
+    readonly device: {
+        readonly category: string;
+        readonly activeBackend: string;
+        readonly capabilityScore: number;
+    };
+    readonly runtime: {
+        readonly fps: number;
+        readonly frameDurationMs: number;
+        readonly frameTimeVariance: number;
+        readonly frameDrops: number;
+        readonly isVisible: boolean;
+    };
+    readonly memory: {
+        readonly trackedResources: number;
+        readonly estimatedMemoryMB: number;
+        readonly pressureLevel: MemoryPressureLevel;
+        readonly budgetUtilizationPct: number;
+    };
+    readonly optimization: {
+        readonly activePreset: QualityPresetName;
+        readonly dominantBottleneck: string;
+        readonly activeOptimizations: readonly string[];
+        readonly pendingDecisionsCount: number;
+    };
+    readonly health: {
+        readonly overallScore: number;
+        readonly status: string;
+        readonly cpuScore: number;
+        readonly gpuScore: number;
+        readonly memoryScore: number;
+        readonly renderingScore: number;
+        readonly simulationScore: number;
+        readonly resourceScore: number;
+    };
+    readonly recommendations: readonly string[];
+}
+/**
+ * Configuration options for initializing Unified Performance Intelligence.
+ */
+export interface PerformanceIntelligenceOptions {
+    autoStart?: boolean;
+    evaluationIntervalMs?: number;
+    historyCapacity?: number;
+    conflictResolutionPrecedence?: "safety" | "performance" | "quality";
+}
+/**
+ * Contract for Unified Performance Intelligence Coordinator.
+ */
+export interface IPerformanceIntelligence {
+    readonly isRunning: boolean;
+    readonly context: UnifiedPerformanceContext;
+    readonly health: PerformanceHealthScores;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    refresh(): UnifiedPerformanceContext;
+    evaluateHealth(): PerformanceHealthScores;
+    generateDecisions(): readonly PerformanceDecision[];
+    resolveConflicts(decisions?: readonly PerformanceDecision[]): ConflictResolutionResult;
+    applyDecisions(decisions?: readonly PerformanceDecision[]): Promise<readonly DecisionExecutionResult[]>;
+    getHistory(): readonly UnifiedPerformanceContext[];
+    compareSnapshots(before: UnifiedPerformanceContext, after: UnifiedPerformanceContext): {
+        fpsDelta: number;
+        frameDurationDeltaMs: number;
+        memoryDeltaMB: number;
+        improved: boolean;
+        summary: string;
+    };
+    getReport(): UnifiedPerformanceReport;
+    reset(): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * AF Motion — Bottleneck Detection Intelligence
+ *
+ * Deterministically identifies CPU, GPU, Memory, and Simulation bottlenecks,
+ * assigns explainable severity and confidence levels, and produces actionable recommendations.
+ */
+import type { DeviceCapabilityProfile } from "../device-capabilities/types.js";
+import type { PerformanceSnapshot, BottleneckAnalysisReport } from "./types.js";
+export declare function analyzePerformanceBottlenecks(snapshot: PerformanceSnapshot | null, history?: readonly PerformanceSnapshot[], capabilities?: DeviceCapabilityProfile): BottleneckAnalysisReport;

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

@@ -0,0 +1,13 @@
+/**
+ * AF Motion — Automatic Performance Optimization Engine
+ *
+ * Framework-independent performance profiling, bottleneck detection,
+ * strategy execution, memory/CPU/GPU/simulation optimizations, worker task manager,
+ * and React integration.
+ */
+export * from "./types.js";
+export * from "./profiler.js";
+export * from "./bottlenecks.js";
+export * from "./strategies.js";
+export * from "./workers.js";
+export * from "./optimizer.js";

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

@@ -0,0 +1,43 @@
+/**
+ * AF Motion — Automatic Performance Optimizer
+ *
+ * Central orchestrator connecting real-time profiling, bottleneck detection,
+ * strategy execution, verification measurement, and automatic rollback safeguards.
+ */
+import type { IPerformanceOptimizer, PerformanceOptimizerOptions, OptimizationMode, OptimizationCategory, OptimizationStrategyId, OptimizationCandidate, AppliedOptimizationRecord, BottleneckAnalysisReport, IPerformanceProfiler, PerformanceSnapshot } from "./types.js";
+export declare class PerformanceOptimizer implements IPerformanceOptimizer {
+    private _mode;
+    private readonly _enabledCategories;
+    private readonly _deviceProfile?;
+    private readonly _adaptiveQualityController?;
+    private readonly _profiler;
+    private readonly _autoRollbackHarmful;
+    private readonly _maxActiveOptimizations;
+    private readonly _activeOptimizations;
+    private readonly _history;
+    private readonly _maxHistory;
+    private _isDisposed;
+    constructor(options?: PerformanceOptimizerOptions);
+    get mode(): OptimizationMode;
+    get profiler(): IPerformanceProfiler;
+    get activeOptimizations(): readonly AppliedOptimizationRecord[];
+    get 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;
+    private pushHistory;
+}
+export declare function createPerformanceOptimizer(options?: PerformanceOptimizerOptions): PerformanceOptimizer;