af-motion 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,362 @@
+/**
+ * AF Motion — Adaptive Rendering & Quality Engine Types
+ *
+ * Core interfaces, presets, setting keys, metrics, system policies,
+ * and controller contracts for real-time adaptive rendering and simulation.
+ */
+import type { DeviceCapabilityProfile } from "../device-capabilities/types.js";
+/**
+ * Standard named quality presets.
+ */
+export type QualityPresetName = "ultra" | "high" | "balanced" | "performance" | "battery-saver" | "custom";
+/**
+ * Categorical quality tiers for individual subsystems and features.
+ */
+export type FeatureQualityTier = "low" | "medium" | "high" | "ultra";
+export type ShadowQualityTier = "disabled" | "low" | "medium" | "high";
+export type LightingQualityTier = "simple" | "standard" | "advanced";
+export type MaterialQualityTier = "basic" | "standard" | "pbr";
+export type TextureQualityTier = "low" | "medium" | "high" | "full";
+export type PostProcessingQualityTier = "disabled" | "low" | "medium" | "high";
+export type EnvironmentalQualityTier = "low" | "medium" | "high";
+export type GpuSimulationQualityTier = "cpu" | "webgl2" | "webgpu";
+/**
+ * Individual quality setting descriptor containing value, bounds, priority, and override state.
+ */
+export interface QualitySettingDescriptor<T> {
+    /** Current effective value (override if set, otherwise auto value). */
+    readonly current: T;
+    /** Auto-computed value derived from active preset or adaptation logic. */
+    readonly autoValue: T;
+    /** Minimum permitted value (for numeric dimensions). */
+    readonly min?: number;
+    /** Maximum permitted value (for numeric dimensions). */
+    readonly max?: number;
+    /** Overall quality level associated with this setting. */
+    readonly qualityLevel: QualityPresetName;
+    /** Adaptation priority (1 = lowest/cut first, 10 = highest/preserve longest). */
+    readonly adaptationPriority: number;
+    /** Estimated relative performance impact of this dimension. */
+    readonly estimatedImpact: "low" | "medium" | "high";
+    /** Optional user override value. */
+    readonly override?: T;
+    /** Mode: "auto" when driven by the engine, "manual" when user override is active. */
+    readonly mode: "auto" | "manual";
+    /** Whether this setting is locked against automated adaptation. */
+    readonly isLocked?: boolean;
+}
+/**
+ * Unified quality settings map containing all 15 adaptive rendering dimensions.
+ */
+export interface UnifiedQualitySettings {
+    /** Resolution scale factor (e.g. 0.25 to 1.0). */
+    resolutionScale: QualitySettingDescriptor<number>;
+    /** Device pixel ratio cap (e.g. 1.0 to 3.0). */
+    dpr: QualitySettingDescriptor<number>;
+    /** Geometry detail tier. */
+    geometryDetail: QualitySettingDescriptor<FeatureQualityTier>;
+    /** Model LOD level index (0 = full detail, 1 = 50%, 2 = 25%, 3 = 10%). */
+    modelLod: QualitySettingDescriptor<number>;
+    /** Shadow rendering quality. */
+    shadowQuality: QualitySettingDescriptor<ShadowQualityTier>;
+    /** Lighting computation quality. */
+    lightingQuality: QualitySettingDescriptor<LightingQualityTier>;
+    /** Material rendering quality. */
+    materialQuality: QualitySettingDescriptor<MaterialQualityTier>;
+    /** Texture resolution tier. */
+    textureResolution: QualitySettingDescriptor<TextureQualityTier>;
+    /** Post-processing effects tier. */
+    postProcessing: QualitySettingDescriptor<PostProcessingQualityTier>;
+    /** Particle density multiplier (e.g. 0.1 to 2.0). */
+    particleDensity: QualitySettingDescriptor<number>;
+    /** Fluid simulation resolution multiplier (e.g. 0.25 to 1.0). */
+    fluidResolution: QualitySettingDescriptor<number>;
+    /** Environmental effects detail tier. */
+    environmentalDetail: QualitySettingDescriptor<EnvironmentalQualityTier>;
+    /** Physics simulation frequency in Hz (e.g. 30 to 120). */
+    physicsFrequency: QualitySettingDescriptor<number>;
+    /** Animation update quality tier. */
+    animationQuality: QualitySettingDescriptor<FeatureQualityTier>;
+    /** GPU simulation compute backend and precision tier. */
+    gpuSimulationQuality: QualitySettingDescriptor<GpuSimulationQualityTier>;
+}
+export type QualitySettingKey = keyof UnifiedQualitySettings;
+/**
+ * Raw values of all settings in a quality profile.
+ */
+export type QualityValues = {
+    [K in QualitySettingKey]: UnifiedQualitySettings[K]["current"];
+};
+/**
+ * Partial overrides for quality values.
+ */
+export type QualityOverrides = Partial<QualityValues>;
+/**
+ * Unified quality profile object.
+ */
+export interface QualityProfile {
+    /** Active preset name or "custom". */
+    readonly preset: QualityPresetName;
+    /** Full settings map with descriptors, limits, priorities, and override states. */
+    readonly settings: UnifiedQualitySettings;
+    /** Fast lookup of current values. */
+    readonly values: QualityValues;
+    /** Whether overall automatic adaptation is currently enabled. */
+    readonly isAutoAdaptive: boolean;
+    /** Whether the entire profile is locked against automated adaptation. */
+    readonly isLocked: boolean;
+    /** Timestamp when this profile was generated or modified. */
+    readonly timestamp: number;
+}
+/**
+ * Initial quality recommendation result based on device capabilities.
+ */
+export interface QualityRecommendation {
+    /** Recommended preset name. */
+    readonly preset: QualityPresetName;
+    /** Recommended baseline values. */
+    readonly values: QualityValues;
+    /** Human-readable rationale explaining the recommendation. */
+    readonly rationale: string[];
+    /** Underlying capability scores used for the decision. */
+    readonly scores: {
+        cpu: number;
+        memory: number;
+        gpu: number;
+        composite: number;
+    };
+    /** Device category identified during detection. */
+    readonly deviceCategory: string;
+    /** Confidence score (0 to 1) for the recommendation. */
+    readonly confidence: number;
+}
+/**
+ * Real-time performance metrics snapshot.
+ */
+export interface PerformanceMetrics {
+    /** Duration of the latest measured frame in milliseconds. */
+    readonly frameDurationMs: number;
+    /** Rolling average frames per second. */
+    readonly averageFps: number;
+    /** Frame duration variance (standard deviation in ms). */
+    readonly frameTimeVariance: number;
+    /** Total frame drops detected within the current sampling window. */
+    readonly frameDrops: number;
+    /** Count of long frames (> 33.3ms) in the sampling window. */
+    readonly longFrames: number;
+    /** CPU execution time spent on simulation in ms (if recorded). */
+    readonly simulationTimeMs: number;
+    /** CPU execution time spent on render submission in ms (if recorded). */
+    readonly renderTimeMs: number;
+    /** GPU timing in ms (if supported by WebGL timer queries or WebGPU). */
+    readonly gpuTimeMs?: number;
+    /** Whether true hardware GPU timing is supported in the current environment. */
+    readonly isGpuTimingSupported: boolean;
+    /** Workload complexity score or item count (e.g. active particles + meshes). */
+    readonly workloadComplexity: number;
+    /** Resource pressure score (0 to 1, estimated memory/thermal load). */
+    readonly resourcePressure: number;
+    /** Timestamp of the metrics snapshot. */
+    readonly timestamp: number;
+}
+/**
+ * Real-time frame submission input for recording.
+ */
+export interface FrameMetricsInput {
+    /** Frame duration in milliseconds (required). */
+    frameDurationMs: number;
+    /** Optional simulation CPU duration in ms. */
+    simulationTimeMs?: number;
+    /** Optional render CPU duration in ms. */
+    renderTimeMs?: number;
+    /** Optional hardware GPU duration in ms. */
+    gpuTimeMs?: number;
+    /** Optional workload item count or complexity score. */
+    workloadComplexity?: number;
+    /** Optional resource pressure (0 to 1). */
+    resourcePressure?: number;
+}
+/**
+ * Adaptation event record stored in bounded history.
+ */
+export interface QualityAdaptationEvent {
+    readonly timestamp: number;
+    readonly type: "degrade" | "recover" | "preset_change" | "user_override" | "power_save";
+    readonly previousPreset: QualityPresetName;
+    readonly newPreset: QualityPresetName;
+    readonly changedSettings: Partial<Record<QualitySettingKey, {
+        from: any;
+        to: any;
+    }>>;
+    readonly reason: string;
+    readonly triggerMetric?: {
+        averageFps: number;
+        frameDurationMs: number;
+        frameDrops: number;
+    };
+}
+/**
+ * System-specific policy configurations derived from active quality values.
+ */
+export interface System3DQualityPolicy {
+    maxLodLevel: number;
+    shadowResolution: number;
+    shadowsEnabled: boolean;
+    maxLights: number;
+    pbrMaterials: boolean;
+    antialiasing: boolean;
+    maxDrawCalls: number;
+}
+export interface SystemParticlesQualityPolicy {
+    activeCountMultiplier: number;
+    maxActiveParticles: number;
+    spawnRateFactor: number;
+    updateFrequency: number;
+    useInstancing: boolean;
+}
+export interface SystemFluidQualityPolicy {
+    gridResolutionScale: number;
+    solverIterations: number;
+    updateFrequency: number;
+    highPrecision: boolean;
+}
+export interface SystemEnvironmentQualityPolicy {
+    rainSnowDensityFactor: number;
+    fogQuality: EnvironmentalQualityTier;
+    cloudsEnabled: boolean;
+    cloudDetail: EnvironmentalQualityTier;
+    fireSmokeMaxParticles: number;
+}
+export interface SystemGpuSimulationQualityPolicy {
+    preferredBackend: GpuSimulationQualityTier;
+    workgroupSize: number;
+    maxComputeBufferBytes: number;
+    allowCpuFallback: boolean;
+}
+export interface SystemPhysicsQualityPolicy {
+    substeps: number;
+    simulationHz: number;
+    solverIterations: number;
+    enableSleeping: boolean;
+    throttleNonCritical: boolean;
+}
+export interface SystemModelLodQualityPolicy {
+    distanceMultiplier: number;
+    targetTriangleRatio: number;
+    maxLODIndex: number;
+    allowSimplification: boolean;
+}
+/**
+ * Aggregated system-specific policies container.
+ */
+export interface SystemQualityPolicies {
+    scene3d: System3DQualityPolicy;
+    particles: SystemParticlesQualityPolicy;
+    fluid: SystemFluidQualityPolicy;
+    environment: SystemEnvironmentQualityPolicy;
+    gpuSimulation: SystemGpuSimulationQualityPolicy;
+    physics: SystemPhysicsQualityPolicy;
+    modelLod: SystemModelLodQualityPolicy;
+}
+/**
+ * Dynamic resolution calculation result.
+ */
+export interface DynamicResolutionResult {
+    /** Scaled width in physical canvas pixels. */
+    readonly physicalWidth: number;
+    /** Scaled height in physical canvas pixels. */
+    readonly physicalHeight: number;
+    /** Scaled width in CSS logical pixels. */
+    readonly cssWidth: number;
+    /** Scaled height in CSS logical pixels. */
+    readonly cssHeight: number;
+    /** Effective device pixel ratio applied. */
+    readonly effectiveDpr: number;
+    /** Resolution scale applied (e.g. 0.25 to 1.0). */
+    readonly resolutionScale: number;
+    /** Total physical pixels. */
+    readonly totalPixels: number;
+    /** Whether the resolution was capped by the maximum pixel budget. */
+    readonly isPixelBudgetCapped: boolean;
+}
+/**
+ * User quality preferences supplied during controller initialization or recommendation.
+ */
+export interface UserQualityPreferences {
+    /** Desired target frame rate (default 60, e.g. 30, 60, 120). */
+    targetFps?: number;
+    /** Priority preference: "quality" favors visual fidelity, "performance" favors smooth frame rates, "power" favors battery. */
+    preference?: "quality" | "performance" | "power";
+    /** Maximum allowable DPR regardless of screen density. */
+    maxDpr?: number;
+    /** Minimum allowable resolution scale. */
+    minResolutionScale?: number;
+    /** Hard cap on total physical pixels (e.g. 1920 * 1080 = 2073600). */
+    maxPixelBudget?: number;
+    /** Initial preset choice to start with. */
+    initialPreset?: QualityPresetName;
+    /** Explicit per-setting overrides. */
+    overrides?: QualityOverrides;
+    /** Whether automated adaptation should be enabled initially (default true). */
+    autoAdapt?: boolean;
+}
+/**
+ * Configuration options for creating an Adaptive Quality Controller.
+ */
+export interface AdaptiveQualityControllerOptions {
+    /** Optional pre-detected device capability profile (falls back to detection). */
+    deviceProfile?: DeviceCapabilityProfile;
+    /** User quality preferences. */
+    preferences?: UserQualityPreferences;
+    /** Number of frame measurements kept in sliding window (default 60, min 10, max 120). */
+    samplingWindowSize?: number;
+    /** FPS drop tolerance before triggering degradation (default: 8 FPS below target). */
+    degradeFpsTolerance?: number;
+    /** FPS recovery tolerance above target before triggering recovery (default: 2 FPS below target). */
+    recoverFpsTolerance?: number;
+    /** Consecutive slow frames needed to trigger degradation (default 15). */
+    consecutiveSlowFramesThreshold?: number;
+    /** Consecutive fast frames needed to trigger recovery (default 45). */
+    consecutiveFastFramesThreshold?: number;
+    /** Minimum cooldown between adaptation steps in milliseconds (default 1500). */
+    adaptationCooldownMs?: number;
+    /** Whether to automatically adapt to battery and power states (default true). */
+    powerAware?: boolean;
+}
+/**
+ * Listener function called when quality profile or metrics adapt.
+ */
+export type QualityChangeListener = (profile: QualityProfile, event?: QualityAdaptationEvent) => void;
+/**
+ * Subscription handle for unsubscribing listeners.
+ */
+export interface QualitySubscription {
+    unsubscribe: () => void;
+}
+/**
+ * Public interface of an Adaptive Quality Controller instance.
+ */
+export interface IAdaptiveQualityController {
+    readonly profile: QualityProfile;
+    readonly metrics: PerformanceMetrics;
+    readonly 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;
+    adaptQuality(): boolean;
+    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;
+    dispose(): void;
+}

package/dist/core/advanced-motion/adapters.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AF Motion Multi-System Motion Adapters
+ *
+ * Normalizes disparate motion engine controls (SVG morph, motion paths,
+ * kinetic typography, shared elements, view transitions, animation, physics, custom)
+ * into a unified participant contract with lifecycle safety.
+ */
+import type { MotionEngineAdapter, MotionParticipantConfig, MotionParticipantInstance } from "./types.js";
+/**
+ * Registers a custom motion engine adapter.
+ */
+export declare function registerMotionAdapter(system: string, adapter: MotionEngineAdapter): void;
+/**
+ * Retrieves a registered motion engine adapter.
+ */
+export declare function getMotionAdapter(system: string): MotionEngineAdapter | undefined;
+/**
+ * Creates an instance of a motion participant according to its system type.
+ */
+export declare function createParticipantInstance(config: MotionParticipantConfig): MotionParticipantInstance;

package/dist/core/advanced-motion/controller.d.ts

@@ -0,0 +1,52 @@
+/**
+ * AF Motion Unified Advanced Motion Composition Controller
+ *
+ * Coordinates playback, seeking, pausing, reversal, shared RAF animation,
+ * and lifecycle safety across multiple synchronized motion engines.
+ */
+import type { AdvancedMotionCompositionController, AdvancedMotionCompositionDefinition, CompositionPlaybackState, MotionParticipantState, ScheduledTrack } from "./types.js";
+export declare class AdvancedMotionCompositionControllerImpl implements AdvancedMotionCompositionController {
+    readonly id: string;
+    private readonly definition;
+    private readonly tracks;
+    private readonly trackMap;
+    private readonly totalDuration;
+    private _state;
+    private _progress;
+    private _isPlaying;
+    private _error;
+    private animControls;
+    private resolvePlayPromise;
+    private rejectPlayPromise;
+    constructor(definition: AdvancedMotionCompositionDefinition);
+    get state(): CompositionPlaybackState;
+    get progress(): number;
+    get isPlaying(): boolean;
+    get duration(): number;
+    get error(): Error | null;
+    get activeParticipants(): readonly string[];
+    getState(): CompositionPlaybackState;
+    getTracks(): readonly ScheduledTrack[];
+    getParticipantProgress(id: string): number;
+    getParticipantState(id: string): MotionParticipantState | undefined;
+    /**
+     * Applies global timeline progress (0 to 1) across all scheduled participant tracks.
+     */
+    private applyProgress;
+    /**
+     * Plays the composition from current progress to completion.
+     */
+    play(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    reverse(): void;
+    seek(progressOrLabel: number | string): void;
+    restart(): Promise<void>;
+    cancel(): void;
+    finish(): void;
+    dispose(): void;
+}
+/**
+ * Creates an advanced motion composition controller.
+ */
+export declare function createAdvancedComposition(definition: AdvancedMotionCompositionDefinition): AdvancedMotionCompositionController;

package/dist/core/advanced-motion/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion Unified Advanced Motion Composition Module
+ *
+ * Orchestrates SVG morphing, motion paths, kinetic typography, shared elements,
+ * view transitions, layout, and physics into cohesive, deterministic motion experiences.
+ */
+export * from "./types.js";
+export * from "./validation.js";
+export * from "./adapters.js";
+export * from "./timeline.js";
+export * from "./controller.js";
+export * from "./recipes.js";

package/dist/core/advanced-motion/recipes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion Advanced Composition Recipes & Presets
+ *
+ * Pre-configured recipes combining SVG morphing, motion paths, kinetic typography,
+ * shared elements, layout, and physics into cohesive multi-system motion experiences.
+ */
+import type { AdvancedCompositionPresetName, AdvancedMotionCompositionDefinition } from "./types.js";
+export declare const ADVANCED_COMPOSITION_PRESETS: Record<AdvancedCompositionPresetName, (overrides?: Partial<AdvancedMotionCompositionDefinition>) => AdvancedMotionCompositionDefinition>;
+/**
+ * Returns a configured Advanced Motion Composition definition from a preset name.
+ */
+export declare function getAdvancedCompositionPreset(name: AdvancedCompositionPresetName, overrides?: Partial<AdvancedMotionCompositionDefinition>): AdvancedMotionCompositionDefinition;
+/**
+ * Lists all available preset names.
+ */
+export declare function listAdvancedCompositionPresets(): AdvancedCompositionPresetName[];

package/dist/core/advanced-motion/timeline.d.ts

@@ -0,0 +1,35 @@
+/**
+ * AF Motion Advanced Timeline & Dependency Scheduler
+ *
+ * Computes deterministic track schedules, resolves relative offsets,
+ * maps timeline labels, enforces topological dependencies, and calculates total duration.
+ */
+import type { AdvancedMotionCompositionDefinition, MotionParticipantConfig, ScheduledTrack } from "./types.js";
+/**
+ * Parses time offsets such as "+=150", "-=100", ">", "<", or direct milliseconds / labels.
+ */
+export declare function parseTimelineOffset(at: number | string | undefined, previousTrackEnd: number, previousTrackStart: number, labels?: Record<string, number>): number;
+/**
+ * Computes deterministic scheduled tracks from composition participants.
+ */
+export declare function scheduleCompositionTracks(definition: AdvancedMotionCompositionDefinition): {
+    tracks: ScheduledTrack[];
+    totalDuration: number;
+};
+/**
+ * Standalone Advanced Timeline class for incremental track building.
+ */
+export declare class AdvancedTimeline {
+    private readonly participants;
+    private readonly labels;
+    add(participant: MotionParticipantConfig): this;
+    addLabel(name: string, timeMs: number): this;
+    getSchedule(id?: string): {
+        tracks: ScheduledTrack[];
+        totalDuration: number;
+    };
+}
+/**
+ * Creates an Advanced Timeline builder.
+ */
+export declare function createAdvancedTimeline(): AdvancedTimeline;

package/dist/core/advanced-motion/types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * AF Motion Unified Advanced Motion Composition Contracts
+ *
+ * Framework-independent contracts for orchestrating SVG morphing, motion paths,
+ * kinetic typography, shared elements, view transitions, layout, and physics.
+ */
+import type { EasingFunction } from "../animation.js";
+import type { MorphAnimationOptions } from "../svg-morph/types.js";
+import type { PathAnimationOptions, MotionPathDefinition } from "../motion-path/types.js";
+import type { TypographyAnimationOptions } from "../typography/types.js";
+import type { SharedElementTransitionConfig, SharedElementRect } from "../transitions/types.js";
+export declare const ADVANCED_MOTION_SPEC_VERSION = "1.0.0";
+export type MotionParticipantSystem = "svg-morph" | "motion-path" | "typography" | "shared-element" | "view-transition" | "animation" | "physics" | "custom";
+export type MotionParticipantState = "idle" | "pending" | "running" | "paused" | "completed" | "cancelled" | "failed";
+export type CompositionPlaybackState = "idle" | "running" | "paused" | "completed" | "cancelled" | "disposed";
+export type CompositionFailurePolicy = "abort" | "continue" | "rollback";
+export interface BaseParticipantConfig {
+    /** Unique participant identifier within the composition. */
+    readonly id: string;
+    /** Motion system type. */
+    readonly system: MotionParticipantSystem;
+    /** Explicit list of participant IDs that must complete before this starts. */
+    readonly dependsOn?: readonly string[];
+    /** Absolute start time in ms or timeline label/offset (e.g., 200, "+=100", ">", "<", "labelName"). */
+    readonly at?: number | string;
+    /** Duration in milliseconds. If omitted, derived from system config. */
+    readonly duration?: number;
+    /** Initial delay before this participant runs once scheduled. */
+    readonly delay?: number;
+    /** Easing curve for progress distribution. */
+    readonly easing?: string | EasingFunction;
+    /** Optional human-readable label. */
+    readonly label?: string;
+    /** Whether this participant can be skipped if reduced-motion is preferred. */
+    readonly respectReducedMotion?: boolean;
+}
+export interface SVGMorphParticipantConfig extends BaseParticipantConfig {
+    readonly system: "svg-morph";
+    readonly target: SVGPathElement | string;
+    readonly to: string;
+    readonly options?: MorphAnimationOptions;
+}
+export interface MotionPathParticipantConfig extends BaseParticipantConfig {
+    readonly system: "motion-path";
+    readonly target: HTMLElement | SVGElement | string;
+    readonly path: MotionPathDefinition;
+    readonly options?: PathAnimationOptions;
+}
+export interface TypographyParticipantConfig extends BaseParticipantConfig {
+    readonly system: "typography";
+    readonly target: HTMLElement | string;
+    readonly options?: TypographyAnimationOptions;
+}
+export interface SharedElementParticipantConfig extends BaseParticipantConfig {
+    readonly system: "shared-element";
+    readonly source?: HTMLElement | string | SharedElementRect;
+    readonly destination?: HTMLElement | string | SharedElementRect;
+    readonly options?: SharedElementTransitionConfig;
+}
+export interface ViewTransitionParticipantConfig extends BaseParticipantConfig {
+    readonly system: "view-transition";
+    readonly update: () => void | Promise<void>;
+    readonly options?: Record<string, unknown>;
+}
+export interface AnimationParticipantConfig extends BaseParticipantConfig {
+    readonly system: "animation";
+    readonly target: HTMLElement | SVGElement | string;
+    readonly keyframes: Record<string, unknown>;
+    readonly options?: Record<string, unknown>;
+}
+export interface PhysicsParticipantConfig extends BaseParticipantConfig {
+    readonly system: "physics";
+    readonly target: HTMLElement | string;
+    readonly type?: "spring" | "inertia";
+    readonly options?: Record<string, unknown>;
+}
+export interface CustomParticipantConfig extends BaseParticipantConfig {
+    readonly system: "custom";
+    readonly run: (progress: number, state: MotionParticipantState) => void | Promise<void>;
+    readonly onCancel?: () => void;
+    readonly onFinish?: () => void;
+    readonly onDispose?: () => void;
+}
+export type MotionParticipantConfig = SVGMorphParticipantConfig | MotionPathParticipantConfig | TypographyParticipantConfig | SharedElementParticipantConfig | ViewTransitionParticipantConfig | AnimationParticipantConfig | PhysicsParticipantConfig | CustomParticipantConfig;
+export interface AdvancedMotionCompositionDefinition {
+    /** Unique composition identifier. */
+    readonly id: string;
+    /** Optional human-readable title. */
+    readonly name?: string;
+    /** Motion participants in this composition. */
+    readonly participants: readonly MotionParticipantConfig[];
+    /** Overall composition timing overrides. */
+    readonly duration?: number;
+    readonly delay?: number;
+    readonly easing?: string | EasingFunction;
+    readonly iterations?: number;
+    readonly playbackRate?: number;
+    readonly respectReducedMotion?: boolean;
+    readonly failurePolicy?: CompositionFailurePolicy;
+    /** Named timeline markers mapping name to millisecond timestamp. */
+    readonly labels?: Record<string, number>;
+    /** Metadata and developer diagnostics. */
+    readonly metadata?: Record<string, unknown>;
+    /** Lifecycle callbacks. */
+    readonly onStart?: () => void;
+    readonly onUpdate?: (progress: number) => void;
+    readonly onComplete?: () => void;
+    readonly onError?: (error: Error) => void;
+    readonly onCancel?: () => void;
+}
+export interface MotionParticipantInstance {
+    readonly id: string;
+    readonly system: MotionParticipantSystem;
+    start(): Promise<void> | void;
+    pause(): void;
+    resume(): void;
+    reverse(): void;
+    seek(progress: number): void;
+    cancel(): void;
+    finish(): void;
+    dispose(): void;
+    getProgress(): number;
+    getState(): MotionParticipantState;
+    readonly finished?: Promise<void>;
+}
+export interface MotionEngineAdapter {
+    readonly system: MotionParticipantSystem;
+    createInstance(config: MotionParticipantConfig): MotionParticipantInstance;
+}
+export interface ScheduledTrack {
+    readonly participant: MotionParticipantConfig;
+    readonly instance: MotionParticipantInstance;
+    readonly startTime: number;
+    readonly endTime: number;
+    readonly duration: number;
+    state: MotionParticipantState;
+    progress: number;
+}
+export interface AdvancedMotionCompositionController {
+    readonly id: string;
+    readonly state: CompositionPlaybackState;
+    readonly progress: number;
+    readonly isPlaying: boolean;
+    readonly duration: number;
+    readonly activeParticipants: readonly string[];
+    readonly error: Error | null;
+    play(): Promise<void>;
+    pause(): void;
+    resume(): void;
+    reverse(): void;
+    seek(progressOrLabel: number | string): void;
+    restart(): Promise<void>;
+    cancel(): void;
+    finish(): void;
+    dispose(): void;
+    getState(): CompositionPlaybackState;
+    getParticipantProgress(id: string): number;
+    getParticipantState(id: string): MotionParticipantState | undefined;
+    getTracks(): readonly ScheduledTrack[];
+}
+export interface AdvancedCompositionValidationError {
+    readonly participantId?: string;
+    readonly field?: string;
+    readonly code: "DUPLICATE_ID" | "EMPTY_ID" | "UNKNOWN_SYSTEM" | "INVALID_TIMING" | "CIRCULAR_DEPENDENCY" | "MISSING_DEPENDENCY" | "ADAPTER_ERROR" | "INVALID_PARTICIPANT";
+    readonly message: string;
+}
+export type CompositionValidationError = AdvancedCompositionValidationError;
+export interface AdvancedCompositionValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly AdvancedCompositionValidationError[];
+    readonly warnings: readonly string[];
+}
+export type CompositionValidationResult = AdvancedCompositionValidationResult;
+export type AdvancedCompositionPresetName = "svg-morph-and-path" | "typography-and-path" | "shared-element-and-layout" | "typography-and-shared-element" | "multi-element-coordinated-reveal" | "morphing-scene-transition" | "cinematic-page-transition" | "physics-path-choreography";