af-motion 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,87 @@
+/**
+ * AF Motion Choreography Intelligence & Cross-System Synchronization Contracts
+ *
+ * Framework-independent contracts for coordinating animation across DOM, React,
+ * Graphics Engine, and 3D scenes with deterministic progress synchronization.
+ */
+import type { AnimatableProperties } from "../animate.js";
+export declare const CHOREOGRAPHY_INTELLIGENCE_VERSION = "1.0.0";
+export type ChoreographySystemType = "dom" | "graphics" | "3d" | "react-state" | "custom";
+export declare const CHOREOGRAPHY_SYSTEMS: readonly ChoreographySystemType[];
+export type ChoreographyPattern = "multi-element-entrance" | "multi-element-exit" | "sequential" | "parallel" | "staggered" | "dom-graphics-sync" | "dom-3d-sync" | "graphics-3d-sync" | "full-cross-system" | "scroll-choreography" | "interaction-choreography" | "storytelling-sequence" | "loading-completion";
+export declare const CHOREOGRAPHY_PATTERNS: readonly ChoreographyPattern[];
+export interface ChoreographyParticipant {
+    readonly id: string;
+    readonly system: ChoreographySystemType;
+    readonly name?: string;
+    readonly target?: any;
+    readonly startProgress: number;
+    readonly endProgress: number;
+    readonly properties?: Readonly<AnimatableProperties>;
+    readonly easing?: string;
+    readonly weight?: number;
+    readonly onUpdate?: (normalizedProgress: number, localProgress: number) => void;
+    readonly onStart?: () => void;
+    readonly onComplete?: () => void;
+    readonly onCancel?: () => void;
+}
+export interface ChoreographyDependency {
+    readonly participantId: string;
+    readonly dependsOnId: string;
+    readonly type?: "start-after-end" | "start-with-start" | "offset";
+    readonly offsetProgress?: number;
+}
+export interface ChoreographyPlan {
+    readonly id: string;
+    readonly name: string;
+    readonly pattern: ChoreographyPattern;
+    readonly duration: number;
+    readonly participants: readonly ChoreographyParticipant[];
+    readonly dependencies: readonly ChoreographyDependency[];
+    readonly easing: string;
+    readonly compatibilityScore: number;
+    readonly explanation: string;
+    readonly respectReducedMotion: boolean;
+    readonly reducedMotionPlan?: ChoreographyPlan;
+}
+export interface ChoreographyIntelligenceContext {
+    readonly intent?: string;
+    readonly pattern?: ChoreographyPattern;
+    readonly systems?: readonly ChoreographySystemType[];
+    readonly participantCount?: number;
+    readonly duration?: number;
+    readonly visualStyle?: string;
+    readonly motionDNA?: string;
+    readonly reducedMotion?: boolean;
+    readonly deviceTier?: "low" | "medium" | "high";
+    readonly loop?: boolean;
+}
+export interface ChoreographyIntelligenceResult {
+    readonly plan: ChoreographyPlan;
+    readonly alternatives: readonly ChoreographyPlan[];
+    readonly compatibilityScore: number;
+    readonly warnings: readonly string[];
+    readonly explanation: string;
+    readonly context: ChoreographyIntelligenceContext;
+}
+export interface ClassifiedChoreographyIntent {
+    readonly pattern: ChoreographyPattern;
+    readonly detectedSystems: readonly ChoreographySystemType[];
+    readonly confidence: number;
+    readonly matchedKeywords: readonly string[];
+}
+export interface CrossSystemSyncBridgeControls {
+    readonly getProgress: () => number;
+    readonly isPlaying: () => boolean;
+    readonly seek: (progress: number) => void;
+    readonly play: () => Promise<void>;
+    readonly pause: () => void;
+    readonly resume: () => void;
+    readonly reverse: () => Promise<void>;
+    readonly cancel: () => void;
+    readonly destroy: () => void;
+    readonly addParticipant: (participant: ChoreographyParticipant) => () => void;
+    readonly removeParticipant: (id: string) => void;
+    readonly getParticipants: () => readonly ChoreographyParticipant[];
+    readonly subscribe: (listener: (progress: number) => void) => () => void;
+}

package/dist/core/composition.d.ts

@@ -0,0 +1,170 @@
+/**
+ * AF Motion Component & Scene Composition Engine
+ *
+ * Framework-independent engine allowing AI agents and developer tools to combine
+ * capabilities into structured, deterministic, machine-readable component and scene compositions.
+ */
+import type { AIMotionRegistry } from "./ai-motion-registry.js";
+import type { DesignContext } from "./design-intelligence.js";
+import type { MotionSpecification, MotionTriggerType } from "./natural-motion.js";
+import { type SchemaCapabilityCategory } from "./schema.js";
+export declare const COMPOSITION_SPEC_VERSION = "1.0.0";
+export type CompositionNodeType = "scene" | "component" | "element" | "effect" | "background";
+export interface NodeTargetDescriptor {
+    readonly selector?: string;
+    readonly tag?: string;
+    readonly role?: string;
+    readonly isCollection?: boolean;
+}
+export interface NodeTimingConfig {
+    readonly duration?: number;
+    readonly delay?: number;
+    readonly easing?: string;
+}
+export interface NodeStaggerConfig {
+    readonly delay: number;
+    readonly from?: "start" | "first" | "center" | "end" | "last" | "edges" | "random";
+}
+export interface NodeLayoutMetadata {
+    readonly display?: "block" | "flex" | "grid" | "inline" | "inline-block" | "none";
+    readonly position?: "static" | "relative" | "absolute" | "fixed" | "sticky";
+    readonly zIndex?: number;
+    readonly width?: string;
+    readonly height?: string;
+}
+export interface CompositionNode {
+    readonly id: string;
+    readonly name: string;
+    readonly type: CompositionNodeType;
+    readonly target?: NodeTargetDescriptor;
+    readonly parentId?: string;
+    readonly children?: readonly string[];
+    readonly capabilityId?: string;
+    readonly category?: SchemaCapabilityCategory;
+    readonly configuration?: Readonly<Record<string, unknown>>;
+    readonly trigger?: MotionTriggerType;
+    readonly timing?: NodeTimingConfig;
+    readonly stagger?: NodeStaggerConfig;
+    readonly dependencies?: readonly string[];
+    readonly layout?: NodeLayoutMetadata;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface CompositionAccessibilitySettings {
+    readonly respectReducedMotion: boolean;
+    readonly reducedMotionBehavior?: "skips-to-endpoint" | "disables-animation" | "static-fallback";
+    readonly announceTransitions?: boolean;
+}
+export interface MotionComposition {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly version: string;
+    readonly rootNodeId: string;
+    readonly nodes: Readonly<Record<string, CompositionNode>>;
+    readonly motionDNA?: string;
+    readonly designSystem?: string;
+    readonly paletteId?: string;
+    readonly accessibility: CompositionAccessibilitySettings;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface CompositionTree {
+    readonly root: CompositionNode;
+    readonly depth: number;
+    readonly totalNodes: number;
+    readonly nodesById: Readonly<Record<string, CompositionNode>>;
+    readonly childrenByParentId: Readonly<Record<string, readonly CompositionNode[]>>;
+}
+export interface CompositionValidationError {
+    readonly nodeId?: string;
+    readonly field?: string;
+    readonly message: string;
+    readonly rule: "structure" | "schema" | "circular_dependency" | "missing_node" | "missing_capability" | "duplicate_id";
+}
+export interface CompositionConflict {
+    readonly id: string;
+    readonly type: "animation_collision" | "z_index_conflict" | "accessibility_conflict" | "dependency_cycle";
+    readonly severity: "warning" | "error";
+    readonly message: string;
+    readonly nodeIds: readonly string[];
+    readonly resolution?: string;
+}
+export interface CompositionValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly CompositionValidationError[];
+    readonly warnings: readonly string[];
+    readonly conflicts: readonly CompositionConflict[];
+}
+export interface CompositionResult {
+    readonly success: boolean;
+    readonly composition: MotionComposition;
+    readonly tree?: CompositionTree;
+    readonly executionOrder: readonly string[];
+    readonly validation: CompositionValidationResult;
+    readonly conflicts: readonly CompositionConflict[];
+}
+export interface CompositionOptions {
+    readonly registry?: AIMotionRegistry;
+    readonly validateSchemas?: boolean;
+    readonly designContext?: DesignContext;
+    readonly motionSpecification?: MotionSpecification;
+    readonly strictDependencies?: boolean;
+}
+export interface ComposeSceneRequest {
+    readonly type: "hero" | "card-grid" | "interactive-button" | "scroll-section" | "background-effect" | "landing-page";
+    readonly name?: string;
+    readonly description?: string;
+    readonly targetSelector?: string;
+    readonly cardCount?: number;
+    readonly backgroundCapability?: string;
+    readonly effectCapability?: string;
+    readonly motionDNA?: string;
+    readonly designSystem?: string;
+    readonly paletteId?: string;
+    readonly customNodes?: readonly CompositionNode[];
+}
+/**
+ * Registers the global AI Motion Registry resolver to maintain zero circular dependencies.
+ */
+export declare function setCompositionRegistryResolver(resolver: () => AIMotionRegistry | undefined): void;
+/**
+ * Resolves the effective registry from options or global resolver.
+ */
+export declare function getEffectiveCompositionRegistry(options?: CompositionOptions): AIMotionRegistry | undefined;
+/**
+ * Creates a new strongly-typed MotionComposition.
+ */
+export declare function createComposition(initial?: Partial<MotionComposition>): MotionComposition;
+/**
+ * Adds a node to the composition, optionally updating its parent's children list.
+ */
+export declare function addCompositionNode(composition: MotionComposition, node: CompositionNode, parentId?: string): MotionComposition;
+/**
+ * Removes a node and recursively removes all of its children from the composition.
+ */
+export declare function removeCompositionNode(composition: MotionComposition, nodeId: string): MotionComposition;
+/**
+ * Updates an existing node in the composition.
+ */
+export declare function updateCompositionNode(composition: MotionComposition, nodeId: string, updates: Partial<CompositionNode>): MotionComposition;
+/**
+ * Validates a MotionComposition and checks capability schemas and conflicts.
+ */
+export declare function validateComposition(composition: MotionComposition, options?: CompositionOptions): CompositionValidationResult;
+/**
+ * Builds a structured CompositionTree and computes topological execution order.
+ */
+export declare function buildCompositionTree(composition: MotionComposition, options?: CompositionOptions): CompositionResult;
+/**
+ * Serializes a MotionComposition to a JSON string.
+ */
+export declare function exportCompositionJson(composition: MotionComposition, options?: {
+    pretty?: boolean;
+}): string;
+/**
+ * Deserializes a JSON string into a validated MotionComposition.
+ */
+export declare function importCompositionFromJson(json: string, options?: CompositionOptions): CompositionResult;
+/**
+ * Automates the creation of standard structured animated scenes and components.
+ */
+export declare function composeScene(request: ComposeSceneRequest, options?: CompositionOptions): CompositionResult;

package/dist/core/configuration-corrector.d.ts

@@ -0,0 +1,85 @@
+/**
+ * AF Motion Intelligent Configuration Validation & Automatic Correction Engine
+ *
+ * Framework-independent engine that inspects AF Motion configurations and compositions,
+ * identifies schema violations, type mismatches, and out-of-range parameters,
+ * and safely computes deterministic, schema-compliant corrections without modifying user intent.
+ */
+import type { AIMotionRegistry } from "./ai-motion-registry.js";
+import type { MotionComposition } from "./composition.js";
+import { type UnifiedMotionSchema } from "./schema.js";
+export declare const CORRECTION_ENGINE_VERSION = "1.0.0";
+export type CorrectionSafety = "safe" | "requires_approval" | "unresolvable";
+export type CorrectionRuleType = "out_of_range" | "invalid_type" | "missing_required" | "resolve_default" | "invalid_enum" | "unsupported_property" | "accessibility_violation" | "incompatible_combination" | "missing_dependency" | "structure" | "unknown";
+export interface CorrectionSuggestion {
+    readonly path: string;
+    readonly property: string;
+    readonly originalValue: unknown;
+    readonly correctedValue: unknown;
+    readonly reason: string;
+    readonly rule: CorrectionRuleType;
+    readonly safety: CorrectionSafety;
+    readonly confidence: number;
+}
+export interface ConfigurationIssue {
+    readonly path: string;
+    readonly property?: string;
+    readonly message: string;
+    readonly rule: string;
+    readonly severity: "error" | "warning" | "info";
+    readonly received?: unknown;
+    readonly expected?: string;
+    readonly suggestion?: CorrectionSuggestion;
+}
+export interface CorrectionReport {
+    readonly totalIssues: number;
+    readonly safeFixesCount: number;
+    readonly approvalRequiredCount: number;
+    readonly unresolvableCount: number;
+    readonly summary: string;
+}
+export interface CorrectionOptions {
+    readonly registry?: AIMotionRegistry;
+    readonly strictMode?: boolean;
+    readonly allowUnsupportedRemoval?: boolean;
+    readonly clampNumbers?: boolean;
+    readonly coerceTypes?: boolean;
+    readonly requireApprovalForBreaking?: boolean;
+    readonly resolveDefaults?: boolean;
+    readonly target?: string;
+}
+export interface CorrectionResult<T = Record<string, unknown>> {
+    readonly valid: boolean;
+    readonly corrected: boolean;
+    readonly originalConfiguration: Readonly<Record<string, unknown>>;
+    readonly correctedConfiguration: T;
+    readonly issues: readonly ConfigurationIssue[];
+    readonly suggestions: readonly CorrectionSuggestion[];
+    readonly appliedCorrections: readonly CorrectionSuggestion[];
+    readonly unresolvableIssues: readonly ConfigurationIssue[];
+    readonly report: CorrectionReport;
+}
+export interface CompositionCorrectionResult {
+    readonly valid: boolean;
+    readonly corrected: boolean;
+    readonly originalComposition: MotionComposition;
+    readonly correctedComposition: MotionComposition;
+    readonly nodeResults: Readonly<Record<string, CorrectionResult>>;
+    readonly compositionIssues: readonly ConfigurationIssue[];
+    readonly report: CorrectionReport;
+}
+export declare function setCorrectorRegistryResolver(resolver: () => AIMotionRegistry | undefined): void;
+export declare function getEffectiveCorrectorRegistry(options?: CorrectionOptions): AIMotionRegistry | undefined;
+/**
+ * Inspects a configuration against a capability schema and produces safe, deterministic corrections.
+ */
+export declare function correctConfiguration<T = Record<string, unknown>>(capabilityIdOrSchema: string | UnifiedMotionSchema, configuration?: unknown, options?: CorrectionOptions): CorrectionResult<T>;
+/**
+ * Validates and corrects a configuration, returning structured diagnosis and suggestions.
+ */
+export declare const validateAndCorrectConfiguration: typeof correctConfiguration;
+/**
+ * Validates and corrects an entire MotionComposition, fixing individual node configurations,
+ * missing targets, and broken hierarchy references.
+ */
+export declare function correctComposition(composition: MotionComposition, options?: CorrectionOptions): CompositionCorrectionResult;

package/dist/core/design-intelligence.d.ts

@@ -0,0 +1,199 @@
+/**
+ * AF Motion Design Intelligence & Context Interpretation Engine
+ *
+ * Framework-independent interpretation layer that analyzes natural-language design briefs,
+ * project requirements, or structured context inputs and produces machine-readable
+ * DesignContext specifications and motion recommendations.
+ */
+import type { AIMotionRegistry } from "./ai-motion-registry.js";
+import type { InterpretOptions } from "./natural-motion.js";
+export declare const DESIGN_CONTEXT_SPEC_VERSION = "1.0.0";
+export type WebsiteCategory = "portfolio" | "saas" | "dashboard" | "ecommerce" | "landing-page" | "blog" | "enterprise" | "creative-agency" | "mobile-app" | "documentation" | "fintech" | "general";
+export type BrandPersonality = "minimal" | "futuristic" | "elegant" | "playful" | "professional" | "editorial" | "brutalist" | "bold" | "organic" | "tech" | "balanced";
+export type ColorModePreference = "dark" | "light" | "system" | "high-contrast";
+export type VisualVibrancy = "muted" | "vibrant" | "pastel" | "monochrome" | "neon" | "balanced";
+export type LayoutDensity = "compact" | "comfortable" | "spacious";
+export type LayoutStructure = "bento" | "grid" | "asymmetric" | "centered" | "editorial" | "full-screen" | "split" | "standard";
+export type MotionIntensity = "none" | "subtle" | "moderate" | "expressive";
+export type TargetAudience = "b2b" | "b2c" | "developer" | "consumer" | "enterprise" | "creative" | "general";
+export type IndustrySector = "tech" | "fintech" | "healthcare" | "ecommerce" | "gaming" | "luxury" | "fashion" | "education" | "media" | "general";
+export interface ComponentRequirements {
+    readonly hero?: boolean;
+    readonly cards?: boolean;
+    readonly buttons?: boolean;
+    readonly tables?: boolean;
+    readonly charts?: boolean;
+    readonly navigation?: boolean;
+    readonly modals?: boolean;
+    readonly forms?: boolean;
+    readonly carousel?: boolean;
+    readonly pricing?: boolean;
+    readonly customComponents?: readonly string[];
+}
+export interface InteractionRequirements {
+    readonly hoverIntensity?: "none" | "subtle" | "prominent";
+    readonly pointerTracking?: boolean;
+    readonly magneticElements?: boolean;
+    readonly scrollDriven?: boolean;
+    readonly microInteractions?: boolean;
+}
+export interface ResponsivenessRequirements {
+    readonly mobileFirst?: boolean;
+    readonly adaptiveLayout?: boolean;
+    readonly touchOptimized?: boolean;
+    readonly breakpointDensity?: boolean;
+}
+export interface AccessibilityRequirements {
+    readonly respectReducedMotion: boolean;
+    readonly highContrastMode?: boolean;
+    readonly screenReaderOptimized?: boolean;
+    readonly keyboardNavigable?: boolean;
+    readonly minimumTouchTarget?: boolean;
+}
+export interface PerformanceConstraints {
+    readonly targetFps?: 30 | 60 | 120;
+    readonly maxCanvasInstances?: number;
+    readonly lowPowerMode?: boolean;
+    readonly gpuAcceleration?: boolean;
+}
+export interface MotionPreferences {
+    readonly intensity: MotionIntensity;
+    readonly motionDNA?: string;
+    readonly springPreference?: boolean;
+    readonly preferredEasing?: string;
+    readonly reducedMotionBehavior?: "skips-to-endpoint" | "disables-animation" | "static-fallback";
+}
+export interface VisualDirection {
+    readonly colorMode: ColorModePreference;
+    readonly vibrancy: VisualVibrancy;
+    readonly density: LayoutDensity;
+    readonly contrast: "standard" | "high";
+    readonly glassmorphism?: boolean;
+    readonly roundedCorners?: "none" | "small" | "medium" | "large" | "full";
+}
+export interface ContentHierarchy {
+    readonly primaryFocus?: string;
+    readonly visualWeight?: "light" | "balanced" | "heavy";
+    readonly informationDensity?: LayoutDensity;
+}
+export interface DesignContext {
+    readonly version: string;
+    readonly category: WebsiteCategory;
+    readonly industry: IndustrySector;
+    readonly audience: TargetAudience;
+    readonly personality: BrandPersonality;
+    readonly visualDirection: VisualDirection;
+    readonly layout: LayoutStructure;
+    readonly contentHierarchy: ContentHierarchy;
+    readonly components: ComponentRequirements;
+    readonly interactions: InteractionRequirements;
+    readonly responsiveness: ResponsivenessRequirements;
+    readonly accessibility: AccessibilityRequirements;
+    readonly performance: PerformanceConstraints;
+    readonly motion: MotionPreferences;
+    readonly visualStyles: readonly string[];
+    readonly palettePreference?: string;
+    readonly typographyPreference?: {
+        readonly headingFont?: string;
+        readonly bodyFont?: string;
+        readonly style?: "sans" | "serif" | "mono" | "display";
+    };
+    readonly rawPrompt?: string;
+}
+export interface DesignConflict {
+    readonly id: string;
+    readonly type: "personality_mismatch" | "accessibility_conflict" | "density_conflict" | "performance_conflict" | "visual_conflict";
+    readonly severity: "warning" | "error";
+    readonly description: string;
+    readonly fields: readonly string[];
+    readonly resolutionSuggestion: string;
+}
+export interface RecommendedVisualStyle {
+    readonly styleId: string;
+    readonly capabilityId?: string;
+    readonly name: string;
+    readonly category: string;
+    readonly confidence: number;
+    readonly rationale: string;
+    readonly isRegistered: boolean;
+}
+export interface RecommendedMotion {
+    readonly intensity: MotionIntensity;
+    readonly motionDNA: string;
+    readonly designSystem: string;
+    readonly recommendedPresets: readonly string[];
+    readonly recommendedBackgrounds: readonly string[];
+    readonly recommendedEffects: readonly string[];
+    readonly defaultEasing: string;
+    readonly defaultDuration: number;
+    readonly respectReducedMotion: boolean;
+}
+export interface DesignDetectedCharacteristics {
+    readonly keywords: readonly string[];
+    readonly detectedCategory?: WebsiteCategory;
+    readonly detectedPersonality?: BrandPersonality;
+    readonly detectedColorMode?: ColorModePreference;
+    readonly detectedLayout?: LayoutStructure;
+    readonly explicitComponents: readonly string[];
+    readonly explicitInteractions: readonly string[];
+    readonly accessibilityFlags: readonly string[];
+}
+export interface DesignInterpretationResult {
+    readonly success: boolean;
+    readonly confidence: number;
+    readonly normalizedContext: DesignContext;
+    readonly detectedCharacteristics: DesignDetectedCharacteristics;
+    readonly recommendedVisualStyles: readonly RecommendedVisualStyle[];
+    readonly motionRecommendations: RecommendedMotion;
+    readonly conflicts: readonly DesignConflict[];
+    readonly warnings: readonly string[];
+    readonly missingInformation: readonly string[];
+    readonly validation: {
+        readonly valid: boolean;
+        readonly errors: readonly string[];
+    };
+}
+export interface DesignInterpretationOptions {
+    readonly registry?: AIMotionRegistry;
+    readonly defaultCategory?: WebsiteCategory;
+    readonly defaultPersonality?: BrandPersonality;
+    readonly defaultColorMode?: ColorModePreference;
+    readonly strictValidation?: boolean;
+}
+export interface DesignContextValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+}
+/**
+ * Registers the global AI Motion Registry resolver to maintain zero circular dependencies.
+ */
+export declare function setDesignRegistryResolver(resolver: () => AIMotionRegistry | undefined): void;
+/**
+ * Resolves the effective registry from options or global resolver.
+ */
+export declare function getEffectiveDesignRegistry(options?: DesignInterpretationOptions): AIMotionRegistry | undefined;
+/**
+ * Default fallback design context.
+ */
+export declare const DEFAULT_DESIGN_CONTEXT: Readonly<DesignContext>;
+/**
+ * Normalizes a partial design context into a fully populated, valid DesignContext.
+ */
+export declare function normalizeDesignContext(partial?: Partial<DesignContext>): DesignContext;
+/**
+ * Factory for creating a strongly-typed DesignContext.
+ */
+export declare function createDesignContext(initial?: Partial<DesignContext>): DesignContext;
+/**
+ * Validates a DesignContext for structural integrity and constraint satisfaction.
+ */
+export declare function validateDesignContext(context: unknown): DesignContextValidationResult;
+/**
+ * Converts a DesignContext into contextual defaults for Prompt 59's interpretMotionPrompt.
+ */
+export declare function toNaturalMotionContext(context: DesignContext): InterpretOptions["context"];
+/**
+ * Interprets a natural language design brief or partial design context into a structured DesignInterpretationResult.
+ */
+export declare function interpretDesignRequirements(input: string | Partial<DesignContext>, options?: DesignInterpretationOptions): DesignInterpretationResult;