af-motion 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,163 @@
+import type { ComposableEffect } from "./effect-composer.js";
+import type { AnimatableProperties, AnimateTarget, DOMAnimationOptions } from "./animate.js";
+import { type MotionDNAOverrides } from "./motion-dna.js";
+import { type AdaptiveMotionConditions } from "./adaptive-motion.js";
+import { type DesignSystem } from "./design-system.js";
+import { type MotionPresetOverrides } from "../presets.js";
+import { type DeclarativeMotionRecipe } from "./motion-recipe.js";
+export declare const CHOREOGRAPHY_SCHEMA_VERSION = "1.0.0";
+export interface MotionChoreographyAnimation {
+    type: "animation";
+    target?: AnimateTarget | string;
+    properties: AnimatableProperties;
+    options?: DOMAnimationOptions;
+    adaptive?: boolean | AdaptiveMotionConditions;
+    motionDNA?: {
+        name: string;
+        overrides?: MotionDNAOverrides;
+    };
+    designSystem?: string | DesignSystem;
+    label?: string;
+    delay?: number;
+    offset?: number;
+}
+export interface MotionChoreographyEffect {
+    type: "effect";
+    effect: ComposableEffect;
+    label?: string;
+    delay?: number;
+}
+export interface MotionChoreographyPreset {
+    type: "preset";
+    preset: string;
+    target?: AnimateTarget | string;
+    label?: string;
+    delay?: number;
+    offset?: number;
+    duration?: number;
+    easing?: string | ((t: number) => number);
+    overrides?: MotionPresetOverrides;
+    adaptive?: boolean | AdaptiveMotionConditions;
+    motionDNA?: {
+        name: string;
+        overrides?: MotionDNAOverrides;
+    };
+    designSystem?: string | DesignSystem;
+}
+export interface MotionChoreographyRecipe {
+    type: "recipe";
+    recipe: string | DeclarativeMotionRecipe;
+    targets?: Record<string, AnimateTarget> | AnimateTarget;
+    label?: string;
+    delay?: number;
+    offset?: number;
+    overrides?: MotionPresetOverrides;
+    stepOverrides?: Record<string, MotionPresetOverrides>;
+    adaptive?: boolean | AdaptiveMotionConditions;
+    motionDNA?: {
+        name: string;
+        overrides?: MotionDNAOverrides;
+    };
+    designSystem?: string | DesignSystem;
+}
+export interface MotionChoreographySequence {
+    type: "sequence";
+    actions: readonly MotionChoreographyAction[];
+    label?: string;
+    delay?: number;
+}
+export interface MotionChoreographyParallel {
+    type: "parallel";
+    actions: readonly MotionChoreographyAction[];
+    label?: string;
+    delay?: number;
+}
+export interface MotionChoreographyBranch {
+    type: "branch";
+    /** Evaluated when this action is reached; may read caller-owned state. */
+    condition: () => boolean;
+    then: readonly MotionChoreographyAction[];
+    else?: readonly MotionChoreographyAction[];
+    label?: string;
+}
+export type MotionChoreographyAction = MotionChoreographyAnimation | MotionChoreographyParallel | MotionChoreographyBranch | MotionChoreographyPreset | MotionChoreographyRecipe | MotionChoreographySequence | MotionChoreographyEffect;
+export interface MotionChoreographyControls {
+    /** Resolves when all choreography actions complete; rejects on failure or cancellation. */
+    readonly finished: Promise<void>;
+    pause(): void;
+    resume(): void;
+    /** Cancels active animations and cleans up active effects. Safe to repeat. */
+    cancel(): void;
+    /** Alias for cancel(). Cleans up active effects and cancels animations. Safe to repeat. */
+    destroy(): void;
+    /** Optional play control when underlying sequence supports forward playback. */
+    play?(): void;
+    /** Optional reverse control when choreography is a pure reversible sequence. */
+    reverse?(): void;
+}
+export interface ChoreographyMetadata {
+    readonly version?: string;
+    readonly author?: string;
+    readonly category?: string;
+    readonly tags?: readonly string[];
+    readonly [key: string]: unknown;
+}
+export type ChoreographyTargetMap = Record<string, AnimateTarget>;
+export interface ChoreographyDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly targets?: readonly string[];
+    readonly motionDNA?: string | {
+        readonly name: string;
+        readonly overrides?: MotionDNAOverrides;
+    };
+    readonly adaptive?: boolean | AdaptiveMotionConditions;
+    readonly designSystem?: string | DesignSystem;
+    readonly actions: readonly MotionChoreographyAction[];
+    readonly metadata?: ChoreographyMetadata;
+}
+export interface ChoreographyRunOptions {
+    targets?: ChoreographyTargetMap | AnimateTarget;
+    motionDNA?: string | {
+        name: string;
+        overrides?: MotionDNAOverrides;
+    };
+    adaptive?: boolean | AdaptiveMotionConditions;
+    designSystem?: string | DesignSystem;
+    stepOverrides?: Record<string, DOMAnimationOptions | MotionPresetOverrides>;
+}
+export interface ChoreographyValidationError {
+    readonly parameter?: string;
+    readonly message: string;
+}
+export interface ChoreographyValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ChoreographyValidationError[];
+}
+export interface ChoreographyQuery {
+    readonly text?: string;
+    readonly category?: string;
+    readonly tag?: string;
+    readonly motionDNA?: string;
+    readonly designSystem?: string;
+}
+export interface ChoreographiesDocument {
+    readonly $schemaVersion: string;
+    readonly timestamp: string;
+    readonly count: number;
+    readonly choreographies: readonly ChoreographyDefinition[];
+}
+export declare const BUILT_IN_CHOREOGRAPHIES: readonly ChoreographyDefinition[];
+export declare function validateChoreography(definition: unknown): ChoreographyValidationResult;
+export declare function registerChoreography(definition: ChoreographyDefinition): void;
+export declare function getChoreography(id: string): ChoreographyDefinition | undefined;
+export declare function listChoreographies(): readonly ChoreographyDefinition[];
+export declare function searchChoreographies(query: ChoreographyQuery | string): readonly ChoreographyDefinition[];
+export declare function removeChoreography(id: string): boolean;
+export declare function resetChoreographyRegistry(): void;
+export declare function exportChoreographyJson(definitionOrId: string | ChoreographyDefinition): string;
+export declare function exportChoreographiesDocument(): string;
+export declare function importChoreographyFromJson(json: string): ChoreographyDefinition;
+/** Runs ordered animations, conditional branches, presets, recipes, and parallel groups. */
+export declare function createMotionChoreography(definition: readonly MotionChoreographyAction[] | ChoreographyDefinition | string, options?: ChoreographyRunOptions): MotionChoreographyControls;

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

@@ -0,0 +1,129 @@
+import type { EasingOption } from "../easing/easings.js";
+import type { DOMAnimationOptions } from "./animate.js";
+export declare const MOTION_DNA_SCHEMA_VERSION = "1.0.0";
+export type MotionDNAPersonality = "snappy" | "energetic" | "calm" | "cinematic" | "minimal" | "playful";
+export interface MotionDNASpringConfig {
+    readonly stiffness: number;
+    readonly damping: number;
+    readonly mass: number;
+}
+export interface MotionDNACharacteristics {
+    readonly personality?: MotionDNAPersonality;
+    readonly intensity?: number;
+    readonly distanceMultiplier?: number;
+    readonly entranceEasing?: EasingOption;
+    readonly exitEasing?: EasingOption;
+    readonly interactionEasing?: EasingOption;
+    readonly entranceDurationMultiplier?: number;
+    readonly exitDurationMultiplier?: number;
+    readonly hoverDurationMultiplier?: number;
+    readonly pressDurationMultiplier?: number;
+    readonly spring?: MotionDNASpringConfig;
+}
+export interface MotionDNAConfigurableParameter {
+    readonly name: string;
+    readonly type: string;
+    readonly description: string;
+    readonly default?: unknown;
+    readonly range?: {
+        readonly min?: number;
+        readonly max?: number;
+    };
+}
+export interface MotionDNAProfileMetadata {
+    readonly compatibleSystems: readonly string[];
+    readonly configurableParameters: readonly MotionDNAConfigurableParameter[];
+    readonly tags: readonly string[];
+    readonly exampleUsage: string;
+    readonly examples?: readonly string[];
+}
+export interface MotionDNA {
+    readonly id?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly personality?: MotionDNAPersonality;
+    readonly duration?: number;
+    readonly delay?: number;
+    readonly playbackRate?: number;
+    readonly respectReducedMotion?: boolean;
+    readonly easing?: EasingOption;
+    readonly characteristics?: MotionDNACharacteristics;
+    readonly metadata?: MotionDNAProfileMetadata;
+    readonly compatibleSystems?: readonly string[];
+    readonly configurableParameters?: readonly MotionDNAConfigurableParameter[];
+    readonly tags?: readonly string[];
+    readonly exampleUsage?: string;
+}
+export type MotionDNAOverrides = Partial<DOMAnimationOptions> & {
+    readonly intensity?: number;
+    readonly characteristics?: Partial<MotionDNACharacteristics>;
+};
+export interface MotionDNARegistryApi {
+    get(name: string): MotionDNA | undefined;
+    register(name: string, dna: MotionDNA): void;
+    remove(name: string): boolean;
+}
+export interface MotionDNAValidationError {
+    readonly parameter?: string;
+    readonly message: string;
+}
+export interface MotionDNAValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly MotionDNAValidationError[];
+}
+export interface MotionDNADocument {
+    readonly $schema: string;
+    readonly version: string;
+    readonly totalProfiles: number;
+    readonly profiles: readonly MotionDNA[];
+}
+export declare const BUILT_IN_MOTION_DNA: readonly MotionDNA[];
+/**
+ * Returns a registered or built-in Motion DNA profile by ID or name.
+ */
+export declare function getMotionDNA(name: string): MotionDNA | undefined;
+/**
+ * Lists all registered Motion DNA profiles, including built-ins and custom additions.
+ */
+export declare function listMotionDNA(): readonly MotionDNA[];
+/**
+ * Searches Motion DNA profiles by query keyword matching ID, name, description, personality, or tags.
+ */
+export declare function searchMotionDNA(query: string): readonly MotionDNA[];
+/**
+ * Registers a custom Motion DNA profile. Built-in profile names are reserved.
+ */
+export declare function registerMotionDNA(name: string, dna: MotionDNA): void;
+/**
+ * Removes a custom Motion DNA profile. Built-in profiles cannot be removed.
+ */
+export declare function removeMotionDNA(name: string): boolean;
+/**
+ * Clones an existing Motion DNA profile and applies overrides without mutating the original.
+ */
+export declare function cloneMotionDNA(source: string | MotionDNA, overrides?: Partial<MotionDNA>): MotionDNA;
+/**
+ * Resolves a Motion DNA profile or identity name into a frozen MotionDNA object.
+ */
+export declare function resolveMotionDNA(source: string | MotionDNA, overrides?: MotionDNAOverrides): MotionDNA;
+/**
+ * Validates a Motion DNA configuration object.
+ */
+export declare function validateMotionDNA(dna: unknown): MotionDNAValidationResult;
+/**
+ * Resolves a registered Motion DNA profile and produces DOMAnimationOptions with caller overrides.
+ */
+export declare function applyMotionDNA(name: string, overrides?: MotionDNAOverrides): DOMAnimationOptions;
+/**
+ * Serializes a Motion DNA profile to JSON.
+ */
+export declare function exportMotionDNAJson(dna: MotionDNA, pretty?: boolean): string;
+/**
+ * Exports all registered Motion DNA profiles as a versioned document.
+ */
+export declare function exportMotionDNADocument(): MotionDNADocument;
+/**
+ * Imports and validates a Motion DNA profile from JSON.
+ */
+export declare function importMotionDNAFromJson(json: string): MotionDNA;
+export declare const motionDNARegistry: MotionDNARegistryApi;

package/dist/core/motion-path/animator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AF Motion Path Animation Orchestrator
+ *
+ * Drives DOM elements or custom callbacks along 2D/3D motion paths using AF Motion's
+ * shared RAF scheduler, transform layering, and animation controls.
+ */
+import type { MotionPathDefinition, PathAnimationControls, PathAnimationOptions, PathSample } from "./types.js";
+type PathTarget = HTMLElement | string | ((sample: PathSample) => void);
+/**
+ * Animates a target DOM element or callback along an arbitrary 2D/3D motion path.
+ */
+export declare function animateAlongPath(target: PathTarget, pathDefinition: MotionPathDefinition, options?: PathAnimationOptions): PathAnimationControls;
+export {};

package/dist/core/motion-path/engine.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AF Motion Path Sampling & Evaluation Engine
+ *
+ * Core engine providing compilation of motion paths, constant-speed uniform arc-length
+ * sampling, tangent/normal evaluation, curvature estimation, and orientation computation.
+ */
+import type { MotionPath, MotionPathDefinition, MotionPathOptions, PathPoint3D, PathSample, PathTangent, SampleOptions } from "./types.js";
+/**
+ * Compiles an SVG path, waypoint array, or segment list into an optimized MotionPath.
+ */
+export declare function createMotionPath(definition: MotionPathDefinition, options?: MotionPathOptions): MotionPath;
+/**
+ * Returns the total arc-length of a motion path.
+ */
+export declare function getMotionPathLength(definition: MotionPathDefinition): number;
+/**
+ * Samples position along a motion path at normalized progress (0..1).
+ */
+export declare function getMotionPathPoint(definition: MotionPathDefinition, progress: number, options?: SampleOptions): PathPoint3D;
+/**
+ * Samples tangent vector along a motion path at normalized progress (0..1).
+ */
+export declare function getMotionPathTangent(definition: MotionPathDefinition, progress: number, options?: SampleOptions): PathTangent;
+/**
+ * Full sample along a motion path at normalized progress (0..1).
+ */
+export declare function sampleMotionPath(definition: MotionPathDefinition, progress: number, options?: SampleOptions): PathSample;

package/dist/core/motion-path/follower.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AF Motion Path Follower
+ *
+ * Stateful path follower providing position/orientation tracking, distance-based stepping,
+ * CSS transform generation, orientation smoothing, and dynamic path retargeting.
+ */
+import type { MotionPathDefinition, PathFollower, PathFollowerOptions } from "./types.js";
+export declare function createPathFollower(initialPath: MotionPathDefinition, options?: PathFollowerOptions): PathFollower;

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

@@ -0,0 +1,15 @@
+/**
+ * AF Motion Path Subsystem
+ *
+ * Framework-independent motion path engine for 2D and 3D paths, path sampling,
+ * uniform arc-length parameterization, orientation calculation, path followers,
+ * and element/callback path animation.
+ */
+export * from "./types.js";
+export { toPoint3D, createPoint3D, clonePoint3D, angle2D, radians2D, normal2D, eulerFromTangent, computeOrientationFrame, vec3Add, vec3Sub, vec3Scale, vec3Lerp, vec3Dot, vec3Cross, vec3Length, vec3LengthSq, vec3Distance, vec3DistanceSq, vec3Normalize, } from "./vector3.js";
+export * from "./segments.js";
+export * from "./lut.js";
+export * from "./parser.js";
+export * from "./engine.js";
+export * from "./follower.js";
+export * from "./animator.js";

package/dist/core/motion-path/lut.d.ts

@@ -0,0 +1,33 @@
+/**
+ * AF Motion Path Arc-Length & Lookup Table (LUT) Engine
+ *
+ * Implements high-precision numerical arc-length integration via Gauss-Legendre
+ * quadrature, precomputed cumulative distance tables, and binary-search distance inversion
+ * for uniform-distance, constant-speed path traversal.
+ */
+import type { MotionPathSegment } from "./types.js";
+/**
+ * Computes the arc length of a single path segment using 5-point Gauss-Legendre quadrature.
+ */
+export declare function computeSegmentLength(segment: MotionPathSegment): number;
+export interface PathLUT {
+    readonly totalLength: number;
+    readonly sampleCount: number;
+    readonly distances: Float64Array;
+    readonly segmentIndices: Int32Array;
+    readonly segmentTs: Float64Array;
+}
+/**
+ * Builds an arc-length lookup table across all path segments.
+ */
+export declare function buildPathLUT(segments: ReadonlyArray<MotionPathSegment>, resolutionPerSegment?: number): {
+    lut: PathLUT;
+    updatedSegments: MotionPathSegment[];
+};
+/**
+ * Inverts a target distance to segment index and segment parameter t using binary search.
+ */
+export declare function lookupDistanceInLUT(lut: PathLUT, targetDistance: number): {
+    segmentIndex: number;
+    segmentT: number;
+};

package/dist/core/motion-path/parser.d.ts

@@ -0,0 +1,26 @@
+/**
+ * AF Motion Path Parser & Normalizer
+ *
+ * Normalizes SVG path strings, 2D/3D waypoints, and segment definitions
+ * into unified, continuous 2D/3D motion path segments.
+ */
+import type { MotionPathBounds, MotionPathDefinition, MotionPathOptions, MotionPathSegment } from "./types.js";
+/**
+ * Computes axis-aligned bounding box across all segments.
+ */
+export declare function computePathBounds(segments: ReadonlyArray<MotionPathSegment>): MotionPathBounds;
+/**
+ * Parses an SVG path string into cubic and line segments.
+ */
+export declare function parseSVGPathToSegments(d: string): {
+    segments: MotionPathSegment[];
+    isClosed: boolean;
+};
+/**
+ * Normalizes any MotionPathDefinition into segments and metadata.
+ */
+export declare function parseMotionPath(definition: MotionPathDefinition, options?: MotionPathOptions): {
+    segments: MotionPathSegment[];
+    is3D: boolean;
+    isClosed: boolean;
+};

package/dist/core/motion-path/segments.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion Path Segment Evaluators
+ *
+ * Analytical position, velocity (1st derivative), acceleration (2nd derivative),
+ * and curvature evaluation for lines, quadratic Béziers, and cubic Béziers.
+ */
+import type { MotionPathSegment, PathPoint3D, PathTangent } from "./types.js";
+export declare function evaluateSegmentPoint(segment: MotionPathSegment, t: number): PathPoint3D;
+export declare function evaluateSegmentVelocity(segment: MotionPathSegment, t: number): PathPoint3D;
+export declare function evaluateSegmentAcceleration(segment: MotionPathSegment, t: number): PathPoint3D;
+export declare function evaluateSegmentTangent(segment: MotionPathSegment, t: number): PathTangent;
+export declare function evaluateSegmentCurvature(segment: MotionPathSegment, t: number): number;
+/**
+ * Converts a sequence of 3D waypoints into smooth cubic Bézier segments using Catmull-Rom splines.
+ */
+export declare function waypointsToCubicSegments(points: ReadonlyArray<PathPoint3D>, closed?: boolean, tension?: number): MotionPathSegment[];

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

@@ -0,0 +1,178 @@
+/**
+ * AF Motion Path Types & Contracts
+ *
+ * Framework-independent contracts for 2D and 3D motion paths, path sampling,
+ * arc-length lookup tables, path followers, and path animations.
+ */
+import type { EasingOption } from "../../easing/easings.js";
+export interface PathPoint3D {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface PathPoint2D {
+    x: number;
+    y: number;
+}
+export type PathPointInput = PathPoint3D | PathPoint2D | readonly [x: number, y: number] | readonly [x: number, y: number, z: number];
+export interface PathTangent {
+    x: number;
+    y: number;
+    z: number;
+}
+export type MotionPathSegmentType = "line" | "quadratic" | "cubic";
+export interface MotionPathSegmentDefinition {
+    type: MotionPathSegmentType;
+    start: PathPointInput;
+    end: PathPointInput;
+    controlPoints?: PathPointInput[];
+}
+export interface MotionPathSegment {
+    readonly type: MotionPathSegmentType;
+    readonly start: PathPoint3D;
+    readonly end: PathPoint3D;
+    readonly controlPoints: readonly PathPoint3D[];
+    readonly length: number;
+    readonly startDistance: number;
+    readonly endDistance: number;
+}
+export interface PathSample {
+    readonly position: PathPoint3D;
+    readonly tangent: PathTangent;
+    readonly normal: PathPoint3D;
+    readonly binormal: PathPoint3D;
+    /** Rotation angle around z-axis in degrees (for 2D CSS rotate). */
+    readonly angle: number;
+    /** Rotation angle around z-axis in radians. */
+    readonly radians: number;
+    /** Euler pitch angle in degrees (rotation around x-axis). */
+    readonly pitch: number;
+    /** Euler yaw angle in degrees (rotation around y-axis). */
+    readonly yaw: number;
+    /** Euler roll angle in degrees (rotation around z-axis). */
+    readonly roll: number;
+    /** Signed curvature estimate at the sample point. */
+    readonly curvature: number;
+    /** Traversed arc distance from path start. */
+    readonly distance: number;
+    /** Normalized path progress (0..1). */
+    readonly progress: number;
+    /** Index of the containing segment. */
+    readonly segmentIndex: number;
+    /** Normalized progress within the containing segment (0..1). */
+    readonly segmentProgress: number;
+}
+export interface MotionPathBounds {
+    readonly min: PathPoint3D;
+    readonly max: PathPoint3D;
+}
+export interface MotionPathOptions {
+    /** Whether the path forms a closed loop. Defaults to false. */
+    closed?: boolean;
+    /** Catmull-Rom spline tension when converting waypoints to smooth curves. Defaults to 0.5. */
+    tension?: number;
+    /** Number of LUT samples per segment for arc-length approximation. Defaults to 64. */
+    lutResolution?: number;
+    /** Whether to force 3D interpretation. Inferred from points by default. */
+    is3D?: boolean;
+}
+export interface SampleOptions {
+    /** Whether to traverse at constant linear speed using arc-length parameterization. Defaults to true. */
+    constantSpeed?: boolean;
+    /** How to handle progress values outside 0..1: "clamp" | "loop" | "pingpong". Defaults to "clamp". */
+    overflow?: "clamp" | "loop" | "pingpong";
+}
+export interface MotionPath {
+    readonly id: string;
+    readonly is3D: boolean;
+    readonly isClosed: boolean;
+    readonly totalLength: number;
+    readonly segments: ReadonlyArray<MotionPathSegment>;
+    readonly bounds: MotionPathBounds;
+    sample(progress: number, options?: SampleOptions): PathSample;
+    sampleAtDistance(distance: number, options?: SampleOptions): PathSample;
+    getPoint(progress: number, options?: SampleOptions): PathPoint3D;
+    getTangent(progress: number, options?: SampleOptions): PathTangent;
+}
+export type MotionPathDefinition = string | ReadonlyArray<PathPointInput> | ReadonlyArray<MotionPathSegmentDefinition> | MotionPath;
+export interface PathFollowerOptions {
+    /** Automatically orient elements along the path tangent. Defaults to true. */
+    autoRotate?: boolean;
+    /** Angular offset in degrees added to the tangent rotation. Defaults to 0. */
+    rotationOffset?: number;
+    /** Loop continuously around closed paths. Defaults to false. */
+    loop?: boolean;
+    /** Constant-speed arc-length parameterization. Defaults to true. */
+    constantSpeed?: boolean;
+    /** Angular smoothing factor (0 = none, 0..1 = smoothed). Defaults to 0. */
+    smoothing?: number;
+}
+export interface RetargetOptions {
+    /** Duration in milliseconds to smoothly transition from current state to the new path. Defaults to 0 (immediate). */
+    duration?: number;
+    /** Target progress on the new path to transition towards. Defaults to 0 or nearest point. */
+    targetProgress?: number;
+}
+export interface PathFollower {
+    seek(progress: number): PathSample;
+    step(deltaDistance: number): PathSample;
+    getPosition(): PathPoint3D;
+    getTangent(): PathTangent;
+    getSample(): PathSample;
+    getTransform(options?: {
+        translateZ?: boolean;
+        precision?: number;
+    }): string;
+    retarget(newPath: MotionPathDefinition, options?: RetargetOptions): void;
+}
+export interface PathAnimationOptions {
+    /** Total animation duration in milliseconds. If omitted, computed from `speed`. */
+    duration?: number;
+    /** Constant movement speed in distance units per second. Used if `duration` is not set. */
+    speed?: number;
+    /** Delay in milliseconds before movement starts. Defaults to 0. */
+    delay?: number;
+    /** Easing function or string identifier. Defaults to "linear". */
+    easing?: EasingOption;
+    /** Number of repeat iterations. Defaults to 0 (plays once). Use Infinity for endless. */
+    repeat?: number;
+    /** Reverse direction on alternate iterations. Defaults to false. */
+    yoyo?: boolean;
+    /** Use arc-length constant speed traversal. Defaults to true. */
+    constantSpeed?: boolean;
+    /** Automatically orient along path tangent. Defaults to true. */
+    autoRotate?: boolean;
+    /** Fixed rotation offset in degrees. Defaults to 0. */
+    rotationOffset?: number;
+    /** Normalized start offset on the path (0..1). Defaults to 0. */
+    startOffset?: number;
+    /** Normalized end offset on the path (0..1). Defaults to 1. */
+    endOffset?: number;
+    /** Direction of traversal. Defaults to "forward". */
+    direction?: "forward" | "reverse";
+    /** Unique owner token for setTransformLayer. Created automatically if not provided. */
+    transformOwner?: object;
+    /** Called once when animation begins. */
+    onStart?: () => void;
+    /** Called on every frame with the updated path sample. */
+    onUpdate?: (sample: PathSample) => void;
+    /** Called on every frame with progress (0..1) and sample. */
+    onProgress?: (progress: number, sample: PathSample) => void;
+    /** Called once when playback completes. */
+    onComplete?: () => void;
+    /** Called if playback is cancelled. */
+    onCancel?: () => void;
+}
+export interface PathAnimationControls {
+    seek(progress: number): void;
+    pause(): void;
+    resume(): void;
+    reverse(): void;
+    setPlaybackRate(rate: number): void;
+    getPlaybackRate(): number;
+    cancel(): void;
+    finish(): void;
+    retarget(newPath: MotionPathDefinition, options?: RetargetOptions): void;
+    getCurrentSample(): PathSample;
+    readonly finished: Promise<void>;
+}

package/dist/core/motion-path/vector3.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AF Motion Path Vector & Matrix Math Utilities
+ *
+ * High-performance, allocation-conscious 2D/3D vector math for path sampling,
+ * tangent evaluation, coordinate normalization, and orientation frames.
+ */
+import type { PathPoint3D, PathPointInput, PathTangent } from "./types.js";
+export declare function toPoint3D(input: PathPointInput): PathPoint3D;
+export declare function createPoint3D(x?: number, y?: number, z?: number): PathPoint3D;
+export declare function clonePoint3D(p: PathPoint3D): PathPoint3D;
+export declare function add(a: PathPoint3D, b: PathPoint3D): PathPoint3D;
+export declare function sub(a: PathPoint3D, b: PathPoint3D): PathPoint3D;
+export declare function scale(p: PathPoint3D, s: number): PathPoint3D;
+export declare function lerp(a: PathPoint3D, b: PathPoint3D, t: number): PathPoint3D;
+export declare function dot(a: PathPoint3D, b: PathPoint3D): number;
+export declare function cross(a: PathPoint3D, b: PathPoint3D): PathPoint3D;
+export declare function lengthSq(p: PathPoint3D): number;
+export declare function length(p: PathPoint3D): number;
+export declare function distanceSq(a: PathPoint3D, b: PathPoint3D): number;
+export declare function distance(a: PathPoint3D, b: PathPoint3D): number;
+export declare function normalize(p: PathPoint3D, fallback?: PathPoint3D): PathPoint3D;
+/**
+ * Calculates the 2D rotation angle in degrees from a tangent vector in the XY plane.
+ */
+export declare function angle2D(tangent: PathTangent): number;
+/**
+ * Calculates the 2D rotation angle in radians from a tangent vector in the XY plane.
+ */
+export declare function radians2D(tangent: PathTangent): number;
+/**
+ * Returns a 2D normal vector perpendicular to the given 2D tangent in the XY plane.
+ */
+export declare function normal2D(tangent: PathTangent): PathPoint3D;
+/**
+ * Derives 3D Euler angles (pitch, yaw, roll in degrees) from a normalized 3D tangent vector.
+ */
+export declare function eulerFromTangent(tangent: PathTangent): {
+    pitch: number;
+    yaw: number;
+    roll: number;
+};
+/**
+ * Computes Frenet/Bishop normal and binormal for a given 3D tangent vector.
+ */
+export declare function computeOrientationFrame(tangent: PathTangent, secondDerivative?: PathPoint3D, previousNormal?: PathPoint3D): {
+    normal: PathPoint3D;
+    binormal: PathPoint3D;
+};
+export { add as vec3Add, sub as vec3Sub, scale as vec3Scale, lerp as vec3Lerp, dot as vec3Dot, cross as vec3Cross, length as vec3Length, lengthSq as vec3LengthSq, distance as vec3Distance, distanceSq as vec3DistanceSq, normalize as vec3Normalize, };