af-motion 0.0.0-stage → 1.0.0

package/dist/core/adaptive-motion.d.ts

@@ -0,0 +1,100 @@
+import type { MotionDNA, MotionDNAOverrides } from "./motion-dna.js";
+import type { DOMAnimationOptions } from "./animate.js";
+export declare const ADAPTIVE_MOTION_SCHEMA_VERSION = "1.0.0";
+export type AdaptiveReducedMotion = "respect" | "ignore";
+export interface AdaptiveMotionProfile extends MotionDNAOverrides {
+    /** Optional Motion DNA identity used as the timing/easing baseline. */
+    motionDNA?: string;
+    /** Motion intensity from above zero to 1; lower values lengthen animation duration. Defaults to 1. */
+    intensity?: number;
+    /** Intensity used when `conditions.lowPower` is true. Defaults to `intensity`. */
+    lowPowerIntensity?: number;
+    /** How an explicitly reduced-motion condition affects compatible animation options. Defaults to "respect". */
+    reducedMotion?: AdaptiveReducedMotion;
+}
+export interface AdaptiveMotionConditions {
+    /** Explicit reduced-motion condition supplied by the caller. */
+    reducedMotion?: boolean;
+    /** Explicit low-power condition supplied by the caller. */
+    lowPower?: boolean;
+    /** Per-resolution intensity override. Takes precedence over profile intensity values. */
+    intensity?: number;
+}
+export type AdaptiveMotionOverrides = MotionDNAOverrides;
+export interface RuntimeContext {
+    readonly reducedMotion: boolean;
+    readonly lowPower: boolean;
+    readonly saveData: boolean;
+    readonly hardwareConcurrency: number;
+    readonly viewportWidth: number;
+    readonly viewportHeight: number;
+    readonly isMobile: boolean;
+    readonly reducedTransparency: boolean;
+}
+export interface AdaptiveMotionConfig {
+    readonly enabled?: boolean;
+    readonly intensity?: number;
+    readonly lowPowerIntensity?: number;
+    readonly mobileIntensity?: number;
+    readonly reducedMotion?: AdaptiveReducedMotion;
+    readonly autoDetect?: boolean;
+    readonly conditions?: AdaptiveMotionConditions;
+}
+export interface AdaptiveMotionState {
+    readonly enabled: boolean;
+    readonly context: RuntimeContext;
+    readonly config: AdaptiveMotionConfig;
+    readonly effectiveIntensity: number;
+    readonly isReducedMotion: boolean;
+}
+/**
+ * Resolves a deterministic animation-option snapshot from a profile and caller-supplied conditions.
+ * The returned options are suitable for existing animation APIs; no media queries or monitoring are created.
+ */
+export declare function resolveAdaptiveMotion(profile: AdaptiveMotionProfile, conditions?: AdaptiveMotionConditions, overrides?: AdaptiveMotionOverrides): MotionDNA;
+/**
+ * Detects current runtime environment and device context in an SSR-safe manner.
+ */
+export declare function detectRuntimeContext(overrides?: Partial<RuntimeContext>): RuntimeContext;
+/**
+ * Returns a read-only snapshot of the active adaptive motion configuration.
+ */
+export declare function getAdaptiveMotionConfig(): Readonly<AdaptiveMotionConfig>;
+/**
+ * Updates the global adaptive motion configuration.
+ */
+export declare function setAdaptiveMotionConfig(config: Partial<AdaptiveMotionConfig>): void;
+/**
+ * Resets adaptive motion configuration to factory defaults.
+ */
+export declare function resetAdaptiveMotionConfig(): void;
+/**
+ * Explicitly enables or disables adaptive motion.
+ */
+export declare function setAdaptiveMotionEnabled(enabled: boolean): void;
+/**
+ * Alias for setAdaptiveMotionEnabled(true).
+ */
+export declare function enableAdaptiveMotion(enabled?: boolean): void;
+/**
+ * Alias for setAdaptiveMotionEnabled(false).
+ */
+export declare function disableAdaptiveMotion(): void;
+/**
+ * Returns true if adaptive motion is currently enabled.
+ */
+export declare function isAdaptiveMotionEnabled(): boolean;
+/**
+ * Inspects the current state of adaptive motion, resolving effective intensity and reduced-motion status.
+ */
+export declare function inspectAdaptiveMotion(conditions?: AdaptiveMotionConditions): AdaptiveMotionState;
+/**
+ * Subscribes a listener to adaptive motion changes (media queries, viewport changes, and config updates).
+ * Returns an unsubscribe cleanup function.
+ */
+export declare function subscribeAdaptiveMotion(listener: (state: AdaptiveMotionState) => void): () => void;
+/**
+ * Adapts animation options according to current adaptive motion state, applying deterministic precedence:
+ * Accessibility / Reduced-Motion > User Adaptive Intensity > Motion DNA > Presets > Runtime Overrides.
+ */
+export declare function adaptAnimationOptions(options: DOMAnimationOptions, conditions?: AdaptiveMotionConditions): DOMAnimationOptions;

package/dist/core/adaptive-quality/controller.d.ts

@@ -0,0 +1,61 @@
+/**
+ * AF Motion — Adaptive Quality Controller
+ *
+ * Coordinates real-time frame monitoring, hysteresis-protected degradation/recovery,
+ * power-aware policies, dynamic resolution scaling, and user overrides.
+ */
+import type { IAdaptiveQualityController, AdaptiveQualityControllerOptions, QualityPresetName, QualityProfile, QualityRecommendation, PerformanceMetrics, QualityAdaptationEvent, DynamicResolutionResult, SystemQualityPolicies, QualityChangeListener, QualitySubscription, QualitySettingKey, FrameMetricsInput, UnifiedQualitySettings } from "./types.js";
+export declare class AdaptiveQualityController implements IAdaptiveQualityController {
+    private _profile;
+    private readonly _recommendation;
+    private readonly _tracker;
+    private readonly _resolution;
+    private readonly _options;
+    private readonly _history;
+    private readonly _maxHistory;
+    private readonly _listeners;
+    private readonly _lockedSettings;
+    private _consecutiveSlowFrames;
+    private _consecutiveFastFrames;
+    private _lastAdaptationTime;
+    private _isDisposed;
+    constructor(options?: AdaptiveQualityControllerOptions);
+    get profile(): QualityProfile;
+    get metrics(): PerformanceMetrics;
+    get recommendation(): QualityRecommendation;
+    getCurrentQuality(): QualityPresetName;
+    getQualityProfile(): QualityProfile;
+    getRecommendedProfile(): QualityRecommendation;
+    getPerformanceMetrics(): PerformanceMetrics;
+    getEffectiveResolution(cssWidth: number, cssHeight: number): DynamicResolutionResult;
+    getSystemPolicies(): SystemQualityPolicies;
+    recordFrame(deltaTimeMs: number, extraMetrics?: Partial<FrameMetricsInput>): PerformanceMetrics;
+    updatePerformanceMetrics(input: FrameMetricsInput): PerformanceMetrics;
+    /**
+     * Evaluates rolling performance metrics and triggers adaptation when sustained.
+     */
+    private evaluateAdaptation;
+    /**
+     * Explicitly triggers adaptation step if criteria are met.
+     */
+    adaptQuality(): boolean;
+    private degradeQuality;
+    private recoverQuality;
+    private applyPresetChange;
+    setQualityPreset(preset: QualityPresetName): void;
+    setQualityOverride<K extends QualitySettingKey>(key: K, value: UnifiedQualitySettings[K]["current"]): void;
+    clearQualityOverride(key: QualitySettingKey): void;
+    clearAllQualityOverrides(): void;
+    lockQualitySettings(locked: boolean): void;
+    unlockQualitySettings(): void;
+    resetToRecommendedQuality(): void;
+    getQualityAdaptationHistory(): readonly QualityAdaptationEvent[];
+    subscribe(listener: QualityChangeListener): QualitySubscription;
+    private pushHistory;
+    private notifyListeners;
+    dispose(): void;
+}
+/**
+ * Factory function to create an AdaptiveQualityController instance.
+ */
+export declare function createAdaptiveQualityController(options?: AdaptiveQualityControllerOptions): AdaptiveQualityController;

package/dist/core/adaptive-quality/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AF Motion — Adaptive Rendering & Quality Engine
+ *
+ * Framework-independent adaptive rendering, quality profiles, real-time performance monitoring,
+ * hysteresis adaptation, dynamic resolution intelligence, system policies, and React integration.
+ */
+export * from "./types.js";
+export * from "./profile.js";
+export * from "./recommendation.js";
+export * from "./metrics.js";
+export * from "./resolution.js";
+export * from "./policies.js";
+export * from "./controller.js";

package/dist/core/adaptive-quality/metrics.d.ts

@@ -0,0 +1,33 @@
+/**
+ * AF Motion — Real-Time Performance Monitor & Bounded Metrics Tracker
+ *
+ * Zero-allocation ring buffer measuring frame duration, FPS, variance,
+ * long frames, drops, CPU simulation/render execution, and GPU timings.
+ */
+import type { PerformanceMetrics, FrameMetricsInput } from "./types.js";
+export interface PerformanceTrackerOptions {
+    windowSize?: number;
+    targetFps?: number;
+    isGpuTimingSupported?: boolean;
+}
+export declare class PerformanceTracker {
+    private readonly windowSize;
+    private readonly frameDurations;
+    private head;
+    private count;
+    private totalDurationSum;
+    private latestDuration;
+    private latestSimTime;
+    private latestRenderTime;
+    private latestGpuTime;
+    private latestWorkload;
+    private latestResourcePressure;
+    private targetFps;
+    private readonly targetBudgetMs;
+    private readonly isGpuTimingSupported;
+    constructor(options?: PerformanceTrackerOptions);
+    record(input: number | FrameMetricsInput): PerformanceMetrics;
+    getMetrics(): PerformanceMetrics;
+    reset(): void;
+    setTargetFps(fps: number): void;
+}

package/dist/core/adaptive-quality/policies.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AF Motion — System-Specific Quality Adaptation Policies
+ *
+ * Concrete adapters transforming unified quality values into actionable runtime parameters
+ * for 3D Scenes, Particles, Fluid, Environmental, GPU Simulation, Physics, and Model LOD.
+ */
+import type { QualityValues, System3DQualityPolicy, SystemParticlesQualityPolicy, SystemFluidQualityPolicy, SystemEnvironmentQualityPolicy, SystemGpuSimulationQualityPolicy, SystemPhysicsQualityPolicy, SystemModelLodQualityPolicy, SystemQualityPolicies } from "./types.js";
+/**
+ * Derives 3D scene rendering policy.
+ */
+export declare function get3DQualityPolicy(values: QualityValues): System3DQualityPolicy;
+/**
+ * Derives Particle system simulation and rendering policy.
+ */
+export declare function getParticlesQualityPolicy(values: QualityValues): SystemParticlesQualityPolicy;
+/**
+ * Derives Fluid solver resolution and iteration policy.
+ */
+export declare function getFluidQualityPolicy(values: QualityValues): SystemFluidQualityPolicy;
+/**
+ * Derives Environmental effects policy.
+ */
+export declare function getEnvironmentQualityPolicy(values: QualityValues): SystemEnvironmentQualityPolicy;
+/**
+ * Derives GPU Simulation compute backend and buffer policy.
+ */
+export declare function getGpuSimulationQualityPolicy(values: QualityValues): SystemGpuSimulationQualityPolicy;
+/**
+ * Derives Physics simulation frequency and solver policy.
+ * Preserves physics invariants and never alters critical correctness.
+ */
+export declare function getPhysicsQualityPolicy(values: QualityValues): SystemPhysicsQualityPolicy;
+/**
+ * Derives Model LOD decimation and simplification policy.
+ */
+export declare function getModelLodQualityPolicy(values: QualityValues): SystemModelLodQualityPolicy;
+/**
+ * Combines all individual system policies into a single snapshot.
+ */
+export declare function aggregateSystemPolicies(values: QualityValues): SystemQualityPolicies;

package/dist/core/adaptive-quality/profile.d.ts

@@ -0,0 +1,58 @@
+/**
+ * AF Motion — Adaptive Quality Profiles & Presets
+ *
+ * Preset definitions (Ultra, High, Balanced, Performance, Battery Saver, Custom),
+ * setting descriptors with bounds, priorities, and validation rules.
+ */
+import type { QualityPresetName, QualitySettingKey, QualityValues, QualityOverrides, UnifiedQualitySettings, QualityProfile } from "./types.js";
+/**
+ * Adaptation priority mapping (1 = degraded first, 15 = preserved longest).
+ */
+export declare const SETTING_ADAPTATION_PRIORITIES: Readonly<Record<QualitySettingKey, number>>;
+/**
+ * Estimated performance impact categorization.
+ */
+export declare const SETTING_PERFORMANCE_IMPACT: Readonly<Record<QualitySettingKey, "low" | "medium" | "high">>;
+/**
+ * Numeric bounds for continuous settings.
+ */
+export declare const NUMERIC_SETTING_BOUNDS: Readonly<Partial<Record<QualitySettingKey, {
+    min: number;
+    max: number;
+}>>>;
+/**
+ * Preset quality raw values.
+ */
+export declare const QUALITY_PRESET_VALUES: Readonly<Record<Exclude<QualityPresetName, "custom">, QualityValues>>;
+/**
+ * Ordered list of presets from highest visual fidelity to lowest.
+ */
+export declare const ORDERED_PRESETS: readonly Exclude<QualityPresetName, "custom">[];
+/**
+ * Clamps numeric values according to dimension limits.
+ */
+export declare function clampNumericSetting(key: QualitySettingKey, value: number): number;
+/**
+ * Constructs a full UnifiedQualitySettings object from raw values and overrides.
+ */
+export declare function buildUnifiedSettings(values: QualityValues, preset: QualityPresetName, overrides?: QualityOverrides, lockedSettings?: Set<QualitySettingKey>): UnifiedQualitySettings;
+/**
+ * Extracts raw current values from a UnifiedQualitySettings map.
+ */
+export declare function extractQualityValues(settings: UnifiedQualitySettings): QualityValues;
+/**
+ * Creates a complete QualityProfile from a preset name or custom options.
+ */
+export declare function createQualityProfile(presetOrOverrides?: QualityPresetName | QualityOverrides, overrides?: QualityOverrides, options?: {
+    isAutoAdaptive?: boolean;
+    isLocked?: boolean;
+    lockedSettings?: Set<QualitySettingKey>;
+}): QualityProfile;
+/**
+ * Returns the next lower preset in the degradation ladder, or null if already at lowest.
+ */
+export declare function getLowerPreset(current: QualityPresetName): Exclude<QualityPresetName, "custom"> | null;
+/**
+ * Returns the next higher preset in the recovery ladder, or null if already at highest.
+ */
+export declare function getHigherPreset(current: QualityPresetName): Exclude<QualityPresetName, "custom"> | null;

package/dist/core/adaptive-quality/react.d.ts

@@ -0,0 +1,57 @@
+/**
+ * AF Motion — React Adaptive Quality Hooks & Providers
+ *
+ * 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 { IAdaptiveQualityController, AdaptiveQualityControllerOptions, QualityProfile, PerformanceMetrics, QualityPresetName, QualitySettingKey, UnifiedQualitySettings, QualityAdaptationEvent } from "./types.js";
+export declare const AdaptiveQualityContext: import("react").Context<IAdaptiveQualityController | null>;
+export interface AdaptiveQualityProviderProps {
+    controller?: IAdaptiveQualityController;
+    options?: AdaptiveQualityControllerOptions;
+    children?: ReactNode;
+}
+/**
+ * Provides an AdaptiveQualityController to child React components via Context.
+ */
+export declare function AdaptiveQualityProvider({ controller: externalController, options, children, }: AdaptiveQualityProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<IAdaptiveQualityController | null>>;
+/**
+ * Accesses or creates an AdaptiveQualityController.
+ */
+export declare function useAdaptiveQuality(options?: AdaptiveQualityControllerOptions): IAdaptiveQualityController;
+/**
+ * Hook to access and subscribe to the active QualityProfile.
+ * SSR-safe: returns default SSR profile initially.
+ */
+export declare function useQualityProfile(controllerOrOptions?: IAdaptiveQualityController | AdaptiveQualityControllerOptions): QualityProfile;
+/**
+ * Hook to query rolling PerformanceMetrics from an active controller.
+ */
+export declare function usePerformanceMetrics(controller?: IAdaptiveQualityController): PerformanceMetrics;
+/**
+ * Full adaptive quality management hook exposing profile, metrics, history, and mutation actions.
+ */
+export declare function useQualityAdaptation(controller?: IAdaptiveQualityController): {
+    profile: QualityProfile;
+    metrics: PerformanceMetrics;
+    history: readonly QualityAdaptationEvent[];
+    effectiveResolution: (width: number, height: number) => import("./types.js").DynamicResolutionResult;
+    systemPolicies: import("./types.js").SystemQualityPolicies;
+    setQualityPreset: (preset: QualityPresetName) => void;
+    setQualityOverride: <K extends QualitySettingKey>(key: K, value: UnifiedQualitySettings[K]["current"]) => void;
+    clearQualityOverride: (key: QualitySettingKey) => void;
+    lockQualitySettings: (locked: boolean) => void;
+    resetToRecommendedQuality: () => void;
+};
+/**
+ * Boundary component that provides isolated quality fallback when unhandled errors occur.
+ */
+export declare function AdaptiveQualityBoundary({ fallbackQuality, children, }: {
+    fallbackQuality?: QualityPresetName;
+    children: ReactNode;
+}): import("react").DetailedReactHTMLElement<{
+    style: {
+        display: "contents";
+    };
+}, HTMLElement> | import("react").FunctionComponentElement<AdaptiveQualityProviderProps>;

package/dist/core/adaptive-quality/recommendation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion — Initial Quality Recommendation Engine
+ *
+ * Synthesizes hardware capabilities, GPU/CPU benchmarks, power state,
+ * display traits, and user preferences into explainable initial quality profiles.
+ */
+import type { DeviceCapabilityProfile } from "../device-capabilities/types.js";
+import type { QualityRecommendation, UserQualityPreferences } from "./types.js";
+/**
+ * Generates an initial quality recommendation based on device capability signals.
+ */
+export declare function getRecommendedQuality(capabilities?: DeviceCapabilityProfile, preferences?: UserQualityPreferences): QualityRecommendation;

package/dist/core/adaptive-quality/resolution.d.ts

@@ -0,0 +1,22 @@
+/**
+ * AF Motion — Rendering Resolution Intelligence
+ *
+ * Dynamic DPR clamping, viewport-aware resolution scaling,
+ * maximum pixel budget enforcement, and canvas resizing thrash prevention.
+ */
+import type { DynamicResolutionResult, QualityValues } from "./types.js";
+export interface ResolutionCalculatorOptions {
+    maxPixelBudget?: number;
+    minResolutionScale?: number;
+    maxDpr?: number;
+}
+export declare class ResolutionIntelligence {
+    private lastPhysicalWidth;
+    private lastPhysicalHeight;
+    private readonly thresholdPx;
+    /**
+     * Calculates optimal physical render resolution and effective DPR.
+     */
+    computeResolution(cssWidth: number, cssHeight: number, values: Pick<QualityValues, "dpr" | "resolutionScale">, options?: ResolutionCalculatorOptions): DynamicResolutionResult;
+    reset(): void;
+}