af-motion 0.0.0-stage → 1.0.0

package/dist/core/ai-motion-intelligence/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * AF Motion Advanced AI Motion Intelligence Contracts
+ *
+ * Types for motion intent classification, multi-dimensional quality evaluation,
+ * evidence-based recommendation generation, pattern knowledge bases,
+ * explainability, and extensible intelligence providers.
+ */
+import type { MotionComposition } from "../composition.js";
+export declare const AI_MOTION_INTELLIGENCE_VERSION = "1.0.0";
+export type AIMotionIntentType = "entrance" | "exit" | "attention" | "emphasis" | "navigation" | "feedback" | "transition" | "loading" | "ambient" | "interaction" | "scroll-storytelling" | "spatial-movement" | "morphing" | "simulation" | "custom";
+export interface IntentSignal {
+    readonly signal: string;
+    readonly weight: number;
+    readonly sourceField: string;
+}
+export interface SecondaryIntentResult {
+    readonly intent: AIMotionIntentType;
+    readonly confidence: number;
+    readonly reason: string;
+}
+export interface IntentClassificationResult {
+    readonly primaryIntent: AIMotionIntentType;
+    readonly confidence: number;
+    readonly secondaryIntents: readonly SecondaryIntentResult[];
+    readonly signals: readonly IntentSignal[];
+    readonly explanation: string;
+}
+export type QualityFindingSeverity = "critical" | "warning" | "suggestion" | "info";
+export type QualityFindingCategory = "timing" | "easing" | "composition" | "interaction" | "physics" | "performance" | "accessibility";
+export interface QualityFinding {
+    readonly id: string;
+    readonly category: QualityFindingCategory;
+    readonly severity: QualityFindingSeverity;
+    readonly message: string;
+    readonly explanation: string;
+    readonly propertyRef?: string;
+    readonly evidence: string;
+}
+export interface MotionQualityDimensions {
+    readonly overall: number;
+    readonly timing: number;
+    readonly easing: number;
+    readonly composition: number;
+    readonly interaction: number;
+    readonly physics: number;
+    readonly performance: number;
+    readonly accessibility: number;
+}
+export type QualityGrade = "A+" | "A" | "B" | "C" | "D" | "F";
+export interface MotionQualityEvaluationResult {
+    readonly scores: MotionQualityDimensions;
+    readonly grade: QualityGrade;
+    readonly findings: readonly QualityFinding[];
+    readonly summary: string;
+}
+export type RecommendationSeverity = "critical" | "warning" | "suggestion" | "enhancement";
+export type RecommendationStatus = "pending" | "accepted" | "rejected" | "applied";
+export interface IntelligentMotionRecommendation {
+    readonly id: string;
+    readonly category: QualityFindingCategory;
+    readonly severity: RecommendationSeverity;
+    readonly title: string;
+    readonly explanation: string;
+    readonly propertyRef: string;
+    readonly currentValue: unknown;
+    readonly suggestedValue: unknown;
+    readonly expectedBenefit: string;
+    readonly confidence: number;
+    readonly status: RecommendationStatus;
+    readonly patch?: Readonly<Record<string, unknown>>;
+}
+export interface MotionPatternDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly intent: AIMotionIntentType;
+    readonly description: string;
+    readonly suitableContexts: readonly string[];
+    readonly timing: {
+        readonly duration: number;
+        readonly delay?: number;
+        readonly easing: string;
+    };
+    readonly performanceConsiderations: string;
+    readonly accessibilityConsiderations: string;
+    readonly configuration: Readonly<Record<string, unknown>>;
+    readonly tags: readonly string[];
+}
+export interface IntelligenceExplanation {
+    readonly summary: string;
+    readonly intentRationale: readonly string[];
+    readonly qualityRationale: readonly string[];
+    readonly recommendationTradeOffs: readonly string[];
+    readonly keySignals: readonly string[];
+}
+export interface MotionAnalysisInput {
+    readonly id?: string;
+    readonly name?: string;
+    readonly configuration?: Readonly<Record<string, unknown>>;
+    readonly composition?: MotionComposition;
+    readonly target?: {
+        readonly type?: string;
+        readonly selector?: string;
+    };
+    readonly contextHint?: string;
+    readonly reducedMotion?: boolean;
+}
+export interface MotionAnalysisOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly skipCache?: boolean;
+    readonly targetFps?: number;
+    readonly strictAccessibility?: boolean;
+}
+export interface MotionAnalysisResult {
+    readonly targetId: string;
+    readonly intents: IntentClassificationResult;
+    readonly quality: MotionQualityEvaluationResult;
+    readonly recommendations: readonly IntelligentMotionRecommendation[];
+    readonly matchedPatterns: readonly MotionPatternDefinition[];
+    readonly explanations: IntelligenceExplanation;
+    readonly telemetry: {
+        readonly analysisDurationMs: number;
+        readonly cached: boolean;
+        readonly timestamp: number;
+        readonly providerId: string;
+    };
+}
+export interface IAIMotionIntelligenceProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly capabilities: readonly string[];
+    analyze(input: MotionAnalysisInput, options?: MotionAnalysisOptions): Promise<MotionAnalysisResult>;
+}

package/dist/core/ai-motion-registry.d.ts

@@ -0,0 +1,201 @@
+/**
+ * AF Motion AI Motion Registry
+ *
+ * Foundational machine-readable registry allowing AI agents, MCP tools,
+ * IDE plugins, and developer tools to discover, inspect, configure,
+ * and validate AF Motion's full spectrum of capabilities.
+ */
+export declare const REGISTRY_SCHEMA_VERSION = "1.0.0";
+import { type UnifiedMotionSchema, type SchemaFilterOptions, type SchemasDocument } from "./schema.js";
+export type AIMotionCategory = "animation" | "effect" | "interaction" | "background" | "preset" | "recipe" | "choreography" | "motion-dna" | "adaptive-motion" | "design-system" | "palette" | "visual-style" | "graphics" | "3d-scene" | "core-animation" | "visual-effect" | "text-effect" | "pointer" | "scroll" | "svg" | "gesture" | "composition" | "react" | (string & {});
+export type ParameterKind = "positional" | "option" | "prop";
+export interface ParameterMetadata {
+    readonly name: string;
+    readonly kind: ParameterKind;
+    readonly type: string;
+    readonly required: boolean;
+    readonly default?: unknown;
+    readonly description: string;
+    readonly placeholder?: string;
+    readonly range?: {
+        readonly min?: number;
+        readonly max?: number;
+    };
+    readonly enum?: readonly (string | number)[];
+    readonly itemType?: string;
+    readonly dependsOn?: string;
+    readonly example?: unknown;
+}
+export interface CallbackParameterDescriptor {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+}
+export interface CallbackDescriptor {
+    readonly name: string;
+    readonly parameters: readonly CallbackParameterDescriptor[];
+    readonly returnType: string;
+    readonly description: string;
+}
+export interface CompatibilityMetadata {
+    readonly browser: boolean;
+    readonly ssr: boolean;
+    readonly requiresCanvas?: boolean;
+    readonly requiresDom?: boolean;
+}
+export interface UsageSignature {
+    readonly importStatement: string;
+    readonly invocation: string;
+    readonly exampleCode: string;
+}
+export type ReducedMotionBehavior = "skips-to-endpoint" | "disables-animation" | "static-fallback" | "respects-profile" | "not-applicable";
+export interface CapabilityConfigurationProperty {
+    readonly type: string;
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly enum?: readonly (string | number)[];
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly items?: {
+        readonly type: string;
+    };
+}
+export interface CapabilityConfigurationSchema {
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, CapabilityConfigurationProperty>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+}
+export interface CapabilityExample {
+    readonly title: string;
+    readonly description?: string;
+    readonly code: string;
+    readonly configuration?: Record<string, unknown>;
+}
+export interface CapabilityReactMetadata {
+    readonly available: boolean;
+    readonly componentName?: string;
+    readonly hookName?: string;
+    readonly importPath?: string;
+}
+export interface CapabilityAccessibilityMetadata {
+    readonly considerations?: readonly string[];
+    readonly ariaAttributes?: readonly string[];
+    readonly keyboardSupport?: boolean;
+    readonly screenReaderSafe?: boolean;
+}
+export interface CapabilityDependencies {
+    readonly required?: readonly string[];
+    readonly optional?: readonly string[];
+}
+export interface AIMotionCapability {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category: AIMotionCategory;
+    readonly tags?: readonly string[];
+    readonly version?: string;
+    readonly schema?: CapabilityConfigurationSchema;
+    readonly parameters?: readonly ParameterMetadata[];
+    readonly defaultConfiguration?: Readonly<Record<string, unknown>>;
+    readonly dependencies?: CapabilityDependencies;
+    readonly compatibility?: CompatibilityMetadata;
+    readonly react?: CapabilityReactMetadata;
+    readonly accessibility?: CapabilityAccessibilityMetadata;
+    readonly reducedMotion?: ReducedMotionBehavior;
+    readonly supportedTargets?: readonly string[];
+    readonly signature?: UsageSignature;
+    readonly examples?: readonly CapabilityExample[];
+    readonly controls?: readonly string[];
+    readonly callbacks?: readonly string[];
+    readonly callbackDescriptors?: readonly CallbackDescriptor[];
+    readonly custom?: boolean;
+}
+export interface CapabilityFilterOptions {
+    readonly category?: AIMotionCategory;
+    readonly tags?: readonly string[];
+    readonly target?: string;
+    readonly search?: string;
+    readonly ssrCompatible?: boolean;
+    readonly requiresCanvas?: boolean;
+    readonly reactAvailable?: boolean;
+    readonly customOnly?: boolean;
+}
+export interface CapabilitySearchQuery {
+    readonly term?: string;
+    readonly category?: AIMotionCategory;
+    readonly tags?: readonly string[];
+    readonly limit?: number;
+}
+export interface CapabilitySchemaInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly category: AIMotionCategory;
+    readonly schema: CapabilityConfigurationSchema;
+    readonly defaultConfiguration: Readonly<Record<string, unknown>>;
+    readonly parameters: readonly ParameterMetadata[];
+    readonly examples: readonly CapabilityExample[];
+}
+export interface CapabilityRegistrationValidationError {
+    readonly field: string;
+    readonly message: string;
+}
+export interface CapabilityValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly CapabilityRegistrationValidationError[];
+}
+export interface RegistryExportOptions {
+    readonly pretty?: boolean;
+    readonly includeCustom?: boolean;
+    readonly category?: AIMotionCategory;
+}
+export interface RegistryDocument {
+    readonly $schema: string;
+    readonly version: string;
+    readonly totalCapabilities: number;
+    readonly builtInCount: number;
+    readonly customCount: number;
+    readonly categories: readonly string[];
+    readonly tags: readonly string[];
+    readonly capabilities: readonly AIMotionCapability[];
+}
+export interface AIMotionRegistry {
+    registerCapability(capability: AIMotionCapability, options?: {
+        override?: boolean;
+    }): void;
+    unregisterCapability(id: string): boolean;
+    getCapability(id: string): AIMotionCapability | undefined;
+    hasCapability(id: string): boolean;
+    listCapabilities(filter?: CapabilityFilterOptions): readonly AIMotionCapability[];
+    searchCapabilities(query: string | CapabilitySearchQuery): readonly AIMotionCapability[];
+    getCapabilitiesByCategory(category: AIMotionCategory): readonly AIMotionCapability[];
+    getCapabilitiesByTag(tag: string): readonly AIMotionCapability[];
+    getCapabilitySchema(id: string): UnifiedMotionSchema | undefined;
+    getSchemaById(schemaId: string): UnifiedMotionSchema | undefined;
+    listSchemas(filter?: SchemaFilterOptions): readonly UnifiedMotionSchema[];
+    exportSchemas(options?: {
+        pretty?: boolean;
+        category?: string;
+    }): SchemasDocument;
+    getCapabilityCategories(): readonly string[];
+    getCapabilityTags(): readonly string[];
+    getCategories(): readonly string[];
+    getTags(): readonly string[];
+    subscribe(listener: () => void): () => void;
+    exportRegistry(options?: RegistryExportOptions): RegistryDocument;
+    resetCustomCapabilities(): void;
+    reset(): void;
+    getVersion(): number;
+}
+/**
+ * Validates capability metadata before registration.
+ */
+export declare function validateCapability(capability: unknown): CapabilityValidationResult;
+/**
+ * Derives a JSON schema from parameter metadata if no explicit schema is provided.
+ */
+export declare function deriveJsonSchemaFromParameters(parameters: readonly ParameterMetadata[] | undefined, defaultConfig: Readonly<Record<string, unknown>> | undefined): CapabilityConfigurationSchema;
+/**
+ * Creates an instance of the AI Motion Registry.
+ */
+export declare function createAIMotionRegistry(initialCapabilities?: readonly AIMotionCapability[]): AIMotionRegistry;

package/dist/core/animate.d.ts

@@ -0,0 +1,57 @@
+import type { AnimationControls, AnimationOptions } from "./animation.js";
+import { type AdaptiveMotionConditions } from "./adaptive-motion.js";
+import type { EasingOption } from "../easing/easings.js";
+/** A single element, or a CSS selector resolved with `document.querySelectorAll`. */
+export type AnimateTarget = HTMLElement | SVGElement | string;
+export type AnimationValue = string | number;
+/**
+ * Maps CSS property names (camelCase, kebab-case or `--custom`) to two or more keyframe values.
+ *
+ * Interpolation rules:
+ * - Compatible numeric values are interpolated only when their surrounding
+ *   CSS syntax and units match (e.g. `"10px"` -> `"20px"`,
+ *   `"translateY(24px)"` -> `"translateY(0px)"`).
+ * - Compatible `rgb()`/`rgba()` values interpolate their color channels.
+ * - Otherwise (e.g. `"red"` -> `"blue"`, `"10px"` -> `"2em"`, `"none"` -> `"block"`)
+ *   the value cannot be interpolated: `from` is used until the eased progress
+ *   reaches 1, then `to` is applied.
+ */
+export type AnimatableProperties = Record<string, readonly [AnimationValue, AnimationValue, ...AnimationValue[]]>;
+export interface DOMAnimationOptions extends AnimationOptions {
+    /** Per-property easing overrides. Unspecified properties use the global easing. */
+    propertyEasing?: Partial<Record<string, EasingOption>>;
+    /** Per-property normalized offsets for its keyframes; unspecified properties are evenly spaced. */
+    propertyKeyframeOffsets?: Readonly<Record<string, readonly number[]>>;
+    /** Controls whether animation-applied values are applied during delay and retained after completion. Defaults to legacy behavior. */
+    fill?: "none" | "forwards" | "backwards" | "both";
+    /**
+     * When true (default) and the user prefers reduced motion, the animation
+     * jumps to its final values on the next frame, ignoring delay and duration.
+     * `onComplete` still fires.
+     */
+    respectReducedMotion?: boolean;
+    /**
+     * Optional adaptive motion settings or conditions. When true or provided,
+     * duration scales according to runtime context (e.g. low power, intensity).
+     */
+    adaptive?: boolean | AdaptiveMotionConditions;
+}
+export declare function toCssName(name: string): string;
+export declare function resolveTargets(target: AnimateTarget): HTMLElement[];
+/**
+ * Animates CSS properties of HTML elements and attributes of SVG elements.
+ *
+ * - Only the listed properties are written (via `style.setProperty`); other inline
+ *   styles are untouched.
+ * - With the default fill behavior, `from` values are applied synchronously and
+ *   the exact `to` values remain on completion. Explicit fill modes can restore
+ *   original inline styles or SVG attributes outside the active interval.
+ * - With the default fill behavior, `cancel()` leaves current values in place.
+ * - A selector that matches no animatable element is not an error: nothing is animated,
+ *   no callbacks fire, and no-op controls are returned.
+ * - `repeat` replays the animation the requested number of additional times; `Infinity` loops forever.
+ * - `yoyo` reverses direction at each repeat boundary.
+ * - Throws `SyntaxError` for an invalid selector, and `TypeError` for an invalid
+ *   target or property definition. Invalid duration/delay throw `RangeError`.
+ */
+export declare function animate(target: AnimateTarget, properties: AnimatableProperties, options?: DOMAnimationOptions): AnimationControls;

package/dist/core/animation-intelligence/engine.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AF Motion Animation Intelligence Engine
+ *
+ * Deterministic animation decision engine that selects suitable animation families,
+ * easings, durations, and alternative recommendations based on component semantics,
+ * visual styles, interaction intents, Motion DNA, and user preferences.
+ */
+import type { AnimationRecommendation, AnimationRecommendationResult, AnimationSelectionContext, ComponentCategory, ComponentMotionPlan } from "./types.js";
+export interface ComponentMotionOptions {
+    readonly visualStyle?: string;
+    readonly motionDNA?: string;
+    readonly reducedMotion?: boolean;
+    readonly deviceTier?: "low" | "medium" | "high";
+    readonly existingAnimations?: readonly string[];
+}
+export interface ConflictResolutionResult {
+    readonly resolvedRecommendations: readonly AnimationRecommendation[];
+    readonly resolvedConflicts: readonly string[];
+}
+export declare class AnimationIntelligenceEngine {
+    /**
+     * Recommends the optimal animation and top alternatives for a given context.
+     */
+    recommendAnimation(context: AnimationSelectionContext): AnimationRecommendationResult;
+    /**
+     * Generates a complete, multi-trigger motion plan for a component
+     * (e.g. coordinated entrance, exit, hover, focus, and press).
+     */
+    recommendComponentMotion(componentType: ComponentCategory, options?: ComponentMotionOptions): ComponentMotionPlan;
+    /**
+     * Resolves conflicts across multiple proposed animations.
+     */
+    resolveAnimationConflicts(recommendations: readonly AnimationRecommendation[]): ConflictResolutionResult;
+    /**
+     * Produces a human- and agent-readable explanation of an animation recommendation.
+     */
+    explainAnimationSelection(recommendation: AnimationRecommendation): string;
+}
+export declare const animationIntelligenceEngine: AnimationIntelligenceEngine;
+export declare function recommendAnimation(context: AnimationSelectionContext): AnimationRecommendationResult;
+export declare function recommendComponentMotion(componentType: ComponentCategory, options?: ComponentMotionOptions): ComponentMotionPlan;
+export declare function explainAnimationSelection(recommendation: AnimationRecommendation): string;

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

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Animation Intelligence Module
+ *
+ * Component-aware animation selection, motion intent classification,
+ * deterministic scoring, conflict resolution, schema, and AI registry integration.
+ */
+export * from "./types.js";
+export * from "./intent.js";
+export * from "./scoring.js";
+export * from "./engine.js";
+export * from "./schema.js";

package/dist/core/animation-intelligence/intent.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion Intent Classification Engine
+ *
+ * Deterministic intent recognition mapping natural language, interaction context,
+ * and component semantics to AF Motion's 12 core motion intents.
+ */
+import type { ClassifiedIntentResult, ComponentCategory, MotionIntent } from "./types.js";
+/**
+ * Classifies motion intent from a string description or partial context.
+ */
+export declare function classifyMotionIntent(input: string | {
+    componentType?: ComponentCategory;
+    intent?: MotionIntent;
+    description?: string;
+}): ClassifiedIntentResult;

package/dist/core/animation-intelligence/schema.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AF Motion Animation Intelligence Schema & AI Motion Registry Integration
+ *
+ * Machine-readable contracts, capability descriptor, and discovery helpers
+ * for AF Motion's intelligent animation selection system.
+ */
+import { type ComponentCategory, type MotionIntent } from "./types.js";
+export declare const ANIMATION_INTELLIGENCE_SCHEMA_VERSION = "1.0.0";
+export declare const ANIMATION_INTELLIGENCE_CAPABILITY: {
+    id: string;
+    name: string;
+    category: "intelligence";
+    description: string;
+    tags: string[];
+    version: string;
+    parameters: {
+        name: string;
+        kind: "positional";
+        type: string;
+        required: boolean;
+        description: string;
+    }[];
+    supportedTargets: string[];
+    signature: {
+        importStatement: string;
+        invocation: string;
+        exampleCode: string;
+    };
+    controls: string[];
+    callbacks: never[];
+    reducedMotion: "static-fallback";
+    compatibility: {
+        browser: boolean;
+        ssr: boolean;
+        requiresCanvas: boolean;
+    };
+};
+export declare function getAvailableComponentCategories(): readonly ComponentCategory[];
+export declare function getAvailableMotionIntents(): readonly MotionIntent[];
+export declare function registerAnimationIntelligenceCapability(registry: {
+    registerCapability: (cap: any, opts?: any) => void;
+}): void;

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

@@ -0,0 +1,15 @@
+/**
+ * AF Motion Deterministic Scoring & Recommendation Engine
+ *
+ * Evaluates candidate animations across component affinity, motion intent,
+ * visual style, Motion DNA, performance constraints, and accessibility requirements.
+ */
+import type { AnimationRecommendation, AnimationSelectionContext } from "./types.js";
+/**
+ * Deterministically scores candidate animations for a context.
+ */
+export declare function scoreCandidates(context: AnimationSelectionContext): readonly AnimationRecommendation[];
+/**
+ * Detects potential conflicts with existing animations.
+ */
+export declare function detectAnimationConflicts(candidate: AnimationRecommendation, existingAnimations?: readonly string[]): readonly string[];

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

@@ -0,0 +1,91 @@
+/**
+ * AF Motion Animation Intelligence Contracts
+ *
+ * Types for component-aware animation selection, motion intent classification,
+ * deterministic scoring, accessibility/performance evaluation, and motion planning.
+ */
+import type { AnimatableProperties } from "../animate.js";
+import type { MotionDNA, MotionDNAPersonality } from "../motion-dna.js";
+import type { DesignSystem } from "../design-system.js";
+export declare const ANIMATION_INTELLIGENCE_VERSION = "1.0.0";
+export type ComponentCategory = "button" | "card" | "navigation" | "modal" | "menu" | "form" | "media" | "typography" | "chart" | "background" | "3d-object" | "custom";
+export declare const COMPONENT_CATEGORIES: readonly ComponentCategory[];
+export type MotionIntent = "attention" | "feedback" | "navigation" | "disclosure" | "emphasis" | "celebration" | "loading" | "progress" | "discovery" | "transition" | "storytelling" | "ambient";
+export declare const MOTION_INTENTS: readonly MotionIntent[];
+export type AnimationTrigger = "entrance" | "exit" | "hover" | "focus" | "press" | "continuous" | "interaction";
+export declare const ANIMATION_TRIGGERS: readonly AnimationTrigger[];
+export type AnimationFamily = "fade" | "slide" | "scale" | "lift" | "pulse" | "bounce" | "shake" | "glow" | "tilt" | "flip" | "morph" | "float";
+export interface PerformanceSuitability {
+    readonly hardwareTier: "low" | "medium" | "high";
+    readonly gpuAccelerated: boolean;
+    readonly compositeOnly: boolean;
+    readonly estimatedFpsImpact: "negligible" | "low" | "moderate" | "high";
+}
+export interface AccessibilityCompatibility {
+    readonly supportsReducedMotion: boolean;
+    readonly reducedMotionFallback: string;
+    readonly screenReaderSafe: boolean;
+    readonly highContrastSafe: boolean;
+}
+export interface SelectionRationale {
+    readonly intentMatch: string;
+    readonly componentContext: string;
+    readonly styleAlignment: string;
+    readonly dnaInfluence: string;
+    readonly summary: string;
+}
+export interface AnimationRecommendation {
+    readonly id: string;
+    readonly name: string;
+    readonly family: AnimationFamily;
+    readonly presetId?: string;
+    readonly properties: Readonly<AnimatableProperties>;
+    readonly duration: number;
+    readonly delay: number;
+    readonly easing: string;
+    readonly trigger: AnimationTrigger;
+    readonly intent: MotionIntent;
+    readonly componentType: ComponentCategory;
+    readonly compatibilityScore: number;
+    readonly performanceSuitability: PerformanceSuitability;
+    readonly accessibilityCompatibility: AccessibilityCompatibility;
+    readonly selectionRationale: SelectionRationale;
+}
+export interface AnimationSelectionContext {
+    readonly componentType: ComponentCategory;
+    readonly intent: MotionIntent;
+    readonly trigger?: AnimationTrigger;
+    readonly visualStyle?: string;
+    readonly motionDNA?: MotionDNA | MotionDNAPersonality | string;
+    readonly designSystem?: DesignSystem | string;
+    readonly reducedMotion?: boolean;
+    readonly targetAudience?: string;
+    readonly deviceTier?: "low" | "medium" | "high";
+    readonly existingAnimations?: readonly string[];
+    readonly customRequirements?: Record<string, unknown>;
+}
+export interface AnimationRecommendationResult {
+    readonly selected: AnimationRecommendation;
+    readonly alternatives: readonly AnimationRecommendation[];
+    readonly compatibilityScore: number;
+    readonly conflictWarnings: readonly string[];
+    readonly context: AnimationSelectionContext;
+}
+export interface ComponentMotionPlan {
+    readonly componentType: ComponentCategory;
+    readonly visualStyle?: string;
+    readonly overallCompatibility: number;
+    readonly entrance?: AnimationRecommendation;
+    readonly exit?: AnimationRecommendation;
+    readonly hover?: AnimationRecommendation;
+    readonly focus?: AnimationRecommendation;
+    readonly press?: AnimationRecommendation;
+    readonly ambient?: AnimationRecommendation;
+    readonly conflicts: readonly string[];
+}
+export interface ClassifiedIntentResult {
+    readonly intent: MotionIntent;
+    readonly confidence: number;
+    readonly matchedKeywords: readonly string[];
+    readonly inferredFromComponent?: boolean;
+}

package/dist/core/animation-parallel.d.ts

@@ -0,0 +1,37 @@
+import type { AnimatableProperties, AnimateTarget, DOMAnimationOptions } from "./animate.js";
+export interface AnimationParallelStep {
+    /** Target for this step; may be shared with other concurrently running steps. */
+    target: AnimateTarget;
+    /** Properties animated by this step. */
+    properties: AnimatableProperties;
+    /** Options passed to `animate()`; this step runs concurrently with its siblings. */
+    options?: DOMAnimationOptions;
+}
+export interface AnimationParallelOptions {
+    /** Called once when the first step begins, after its delay. */
+    onStart?: () => void;
+    /** Called once after all steps have completed successfully. */
+    onComplete?: () => void;
+    /** Called once when the group is explicitly cancelled. */
+    onCancel?: () => void;
+}
+export interface AnimationParallelControls {
+    /** Resolves after all steps complete; rejects if a step fails or the group is cancelled. */
+    finished: Promise<void>;
+    /** Pauses every active step. */
+    pause(): void;
+    /** Resumes every paused step. */
+    resume(): void;
+    /** Reverses playback of every active step. */
+    reverse(): void;
+    /** Sets the playback speed of active steps. */
+    setPlaybackRate(rate: number): void;
+    /** Returns the active steps' playback speed, or the configured group speed. */
+    getPlaybackRate(): number;
+    /** Cancels all active steps and rejects `finished` with an AbortError. Safe to call repeatedly. */
+    cancel(): void;
+}
+/**
+ * Runs DOM animations concurrently by delegating each step to the existing `animate()` engine.
+ */
+export declare function animateParallel(steps: readonly AnimationParallelStep[], options?: AnimationParallelOptions): AnimationParallelControls;