af-motion 0.0.0-stage → 1.0.0

package/dist/core/interactions/gesture-classifier.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AF Motion Gesture Classifier & Confidence Engine
+ *
+ * Deterministic gesture classification with multidimensional confidence scoring
+ * and explainable breakdowns based on direction, velocity, duration, distance,
+ * pointer count, linearity, scale, rotation, and edge containment.
+ */
+import type { CustomGestureDefinition, GestureClassificationResult, GestureDirection, GestureExplanation, GestureSample } from "./types.js";
+/**
+ * Computes the angle in degrees [0, 360) from deltaX, deltaY.
+ */
+export declare function calculateAngle(dx: number, dy: number): number;
+/**
+ * Detects the predominant gesture direction from displacement.
+ */
+export declare function detectDirection(dx: number, dy: number, minDistance?: number): GestureDirection | null;
+/**
+ * Computes gesture path linearity (net displacement / path length).
+ */
+export declare function calculateLinearity(sample: GestureSample): number;
+/**
+ * Produces an explainable breakdown of a gesture classification candidate.
+ */
+export declare function explainGesture(sample: GestureSample, def: CustomGestureDefinition): GestureExplanation;
+/**
+ * Calculates gesture definition specificity score.
+ * Highly constrained gestures (swipes, pinches, edge gestures) score higher
+ * than generic catch-all gestures (drag, pan).
+ */
+export declare function calculateSpecificity(def: CustomGestureDefinition): number;
+/**
+ * Evaluates a single gesture candidate against a definition and computes confidence.
+ */
+export declare function evaluateGestureMatch(sample: GestureSample, def: CustomGestureDefinition, minConfidence?: number): GestureClassificationResult;
+/**
+ * Classifies an input gesture sample against all registered gestures or a specific definition.
+ */
+export declare function classifyGesture(sample: GestureSample, targetDefinition?: CustomGestureDefinition, minConfidence?: number): GestureClassificationResult;
+/**
+ * Classifies a gesture sample against all registered definitions, returning all results sorted by
+ * confidence and gesture specificity.
+ */
+export declare function classifyAllGestures(sample: GestureSample, definitions?: readonly CustomGestureDefinition[], minConfidence?: number): readonly GestureClassificationResult[];

package/dist/core/interactions/gesture-intelligence-controller.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AF Motion Gesture Intelligence Controller
+ *
+ * High-performance, framework-independent gesture recognition intelligence engine.
+ * Connects pointer tracking, live gesture classification, candidate scoring,
+ * sequence state machines, and priority resolution.
+ */
+import type { GestureRecognitionController, GestureRecognitionOptions } from "./types.js";
+export declare function createGestureRecognizer(target: HTMLElement, options?: GestureRecognitionOptions): GestureRecognitionController;

package/dist/core/interactions/gesture-recognizers.d.ts

@@ -0,0 +1,160 @@
+/**
+ * AF Motion Universal Gesture Recognizers
+ *
+ * Extensible, high-performance recognizers for Tap, Double Tap, Long Press,
+ * Drag, Pan, Swipe, Pinch, and Rotation gestures.
+ */
+import type { PointerTracker } from "./pointer-tracker.js";
+import type { DoubleTapOptions, DragOptions, GestureStatus, GestureType, LongPressOptions, NormalizedInputEvent, PanOptions, PinchOptions, RotationOptions, SwipeOptions, TapOptions, TrackedPointer } from "./types.js";
+export interface GestureRecognizer {
+    readonly type: GestureType;
+    readonly status: GestureStatus;
+    processDown(event: NormalizedInputEvent, pointer: TrackedPointer, tracker: PointerTracker): void;
+    processMove(event: NormalizedInputEvent, pointer: TrackedPointer, tracker: PointerTracker): void;
+    processUp(event: NormalizedInputEvent, pointer: TrackedPointer, tracker: PointerTracker): void;
+    processCancel(event: NormalizedInputEvent, pointer: TrackedPointer | null, tracker: PointerTracker): void;
+    cancel(): void;
+    reset(): void;
+}
+export declare class TapRecognizer implements GestureRecognizer {
+    readonly type: "tap";
+    status: GestureStatus;
+    private readonly maxDelayMs;
+    private readonly maxDistance;
+    private readonly onTap?;
+    private startPointerId;
+    private startTime;
+    constructor(options?: TapOptions);
+    processDown(event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processMove(_event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processUp(event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processCancel(): void;
+    cancel(): void;
+    reset(): void;
+}
+export declare class DoubleTapRecognizer implements GestureRecognizer {
+    readonly type: "double-tap";
+    status: GestureStatus;
+    private readonly maxDelayMs;
+    private readonly maxDistance;
+    private readonly onDoubleTap?;
+    private firstTapTime;
+    private firstTapPoint;
+    private timer;
+    constructor(options?: DoubleTapOptions);
+    processDown(): void;
+    processMove(): void;
+    processUp(event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processCancel(): void;
+    cancel(): void;
+    reset(): void;
+    private clearTimer;
+}
+export declare class LongPressRecognizer implements GestureRecognizer {
+    readonly type: "long-press";
+    status: GestureStatus;
+    private readonly minDurationMs;
+    private readonly maxDistance;
+    private readonly onLongPress?;
+    private timer;
+    private activePointerId;
+    private startPoint;
+    constructor(options?: LongPressOptions);
+    processDown(event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processMove(_event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processUp(): void;
+    processCancel(): void;
+    cancel(): void;
+    reset(): void;
+    private clearTimer;
+}
+export declare class DragRecognizer implements GestureRecognizer {
+    readonly type: "drag";
+    status: GestureStatus;
+    private readonly axis;
+    private readonly threshold;
+    private readonly bounds?;
+    private readonly onDragStart?;
+    private readonly onDrag?;
+    private readonly onDragEnd?;
+    private activePointerId;
+    private initialPoint;
+    private currentOffset;
+    constructor(options?: DragOptions);
+    processDown(_event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processMove(event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processUp(event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processCancel(event: NormalizedInputEvent, pointer: TrackedPointer | null): void;
+    cancel(): void;
+    reset(): void;
+    private createGesture;
+}
+export declare class PanRecognizer implements GestureRecognizer {
+    readonly type: "pan";
+    status: GestureStatus;
+    private readonly threshold;
+    private readonly lockAxis;
+    private readonly onPanStart?;
+    private readonly onPan?;
+    private readonly onPanEnd?;
+    private lockedAxis;
+    constructor(options?: PanOptions);
+    processDown(): void;
+    processMove(event: NormalizedInputEvent, pointer: TrackedPointer, tracker: PointerTracker): void;
+    processUp(event: NormalizedInputEvent, pointer: TrackedPointer, tracker: PointerTracker): void;
+    processCancel(event: NormalizedInputEvent, pointer: TrackedPointer | null, tracker: PointerTracker): void;
+    cancel(): void;
+    reset(): void;
+    private createGesture;
+}
+export declare class SwipeRecognizer implements GestureRecognizer {
+    readonly type: "swipe";
+    status: GestureStatus;
+    private readonly minDistance;
+    private readonly maxDuration;
+    private readonly minVelocity;
+    private readonly onSwipe?;
+    constructor(options?: SwipeOptions);
+    processDown(): void;
+    processMove(): void;
+    processUp(event: NormalizedInputEvent, pointer: TrackedPointer): void;
+    processCancel(): void;
+    cancel(): void;
+    reset(): void;
+}
+export declare class PinchRecognizer implements GestureRecognizer {
+    readonly type: "pinch";
+    status: GestureStatus;
+    private readonly minDistance;
+    private readonly onPinchStart?;
+    private readonly onPinch?;
+    private readonly onPinchEnd?;
+    private initialDistance;
+    private previousScale;
+    constructor(options?: PinchOptions);
+    processDown(_event: NormalizedInputEvent, _pointer: TrackedPointer, tracker: PointerTracker): void;
+    processMove(_event: NormalizedInputEvent, _pointer: TrackedPointer, tracker: PointerTracker): void;
+    processUp(_event: NormalizedInputEvent, _pointer: TrackedPointer, tracker: PointerTracker): void;
+    processCancel(_event: NormalizedInputEvent, _pointer: TrackedPointer | null, tracker: PointerTracker): void;
+    cancel(): void;
+    reset(): void;
+    private createGesture;
+}
+export declare class RotationRecognizer implements GestureRecognizer {
+    readonly type: "rotation";
+    status: GestureStatus;
+    private readonly threshold;
+    private readonly onRotationStart?;
+    private readonly onRotation?;
+    private readonly onRotationEnd?;
+    private initialAngle;
+    private previousRotation;
+    constructor(options?: RotationOptions);
+    processDown(_event: NormalizedInputEvent, _pointer: TrackedPointer, tracker: PointerTracker): void;
+    processMove(_event: NormalizedInputEvent, _pointer: TrackedPointer, tracker: PointerTracker): void;
+    processUp(_event: NormalizedInputEvent, _pointer: TrackedPointer, tracker: PointerTracker): void;
+    processCancel(_event: NormalizedInputEvent, _pointer: TrackedPointer | null, tracker: PointerTracker): void;
+    cancel(): void;
+    reset(): void;
+    private createGesture;
+}

package/dist/core/interactions/gesture-sequence.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AF Motion Gesture Sequence State Machine
+ *
+ * Coordinates multi-stage gesture sequences (e.g. tap -> swipe, long-press -> drag)
+ * with individual stage timeouts, optional stages, partial progress tracking,
+ * and deterministic sequence completion.
+ */
+import type { GestureSequenceController, GestureSequenceOptions } from "./types.js";
+export declare function createGestureSequence(options: GestureSequenceOptions): GestureSequenceController;

package/dist/core/interactions/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AF Motion Universal Interaction & Gestures Subsystem (Prompts 105, 106, 107, 108, 109)
+ *
+ * Framework-independent interaction abstraction providing unified pointer, mouse, touch,
+ * keyboard, multi-touch gestures, advanced pointer tracking, drag interactions, multi-touch engine,
+ * intelligent gesture recognition, and cursor & magnetic interaction engine.
+ */
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./input-normalizer.js";
+export * from "./pointer-tracker.js";
+export * from "./gesture-recognizers.js";
+export * from "./keyboard-manager.js";
+export * from "./prioritizer.js";
+export * from "./interaction-manager.js";
+export * from "./device-capabilities.js";
+export * from "./pointer-controller.js";
+export * from "./drag-controller.js";
+export * from "./touch-controller.js";
+export * from "./multitouch-controller.js";
+export * from "./custom-gestures.js";
+export * from "./gesture-classifier.js";
+export * from "./gesture-sequence.js";
+export * from "./gesture-intelligence-controller.js";
+export * from "./cursor-controller.js";
+export * from "./magnetic-controller.js";
+export * from "./magnetic-group.js";

package/dist/core/interactions/input-normalizer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * AF Motion Universal Input Normalizer
+ *
+ * Normalizes browser-specific Pointer, Mouse, Touch, and Keyboard events
+ * into a single unified event representation.
+ */
+import type { NormalizedInputEvent } from "./types.js";
+export declare function normalizeInputEvent(originalEvent: Event, targetOverride?: EventTarget | null): NormalizedInputEvent;

package/dist/core/interactions/interaction-manager.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AF Motion Universal Interaction Manager
+ *
+ * Framework-independent controller coordinating normalized inputs, pointer tracking,
+ * gestures, keyboard controls, prioritization, and leak-free lifecycle management.
+ */
+import type { InteractionControls, InteractionOptions, TrackedPointer } from "./types.js";
+export declare class InteractionManager implements InteractionControls {
+    readonly target: EventTarget;
+    private options;
+    private readonly pointerTracker;
+    private keyboardManager;
+    private prioritizer;
+    private recognizers;
+    private boundListeners;
+    private isDestroyed;
+    constructor(target: EventTarget, options?: InteractionOptions);
+    get activePointers(): ReadonlyMap<number, TrackedPointer>;
+    get isInteracting(): boolean;
+    updateOptions(newOptions: Partial<InteractionOptions>): void;
+    cancel(): void;
+    destroy(): void;
+    private rebuildRecognizers;
+    private attachListeners;
+    private checkPreventDefault;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handlePointerCancel;
+    private handlePointerEnter;
+    private handlePointerLeave;
+    private handleKeyDown;
+    private handleKeyUp;
+    private handleWindowBlur;
+}
+/**
+ * Creates and attaches a Universal Interaction Manager to a target element.
+ */
+export declare function createInteractionManager(target: EventTarget, options?: InteractionOptions): InteractionControls;
+/**
+ * Convenience alias for `createInteractionManager`.
+ */
+export declare const interact: typeof createInteractionManager;

package/dist/core/interactions/keyboard-manager.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion Keyboard Interaction Manager
+ *
+ * Handles keyboard navigation, configurable key bindings, modifier checks,
+ * accessibility activation (Enter/Space), and cancellation (Escape).
+ */
+import type { KeyBinding, KeyboardOptions, NormalizedInputEvent } from "./types.js";
+export declare class KeyboardManager {
+    private readonly options;
+    private readonly bindings;
+    constructor(options?: KeyboardOptions);
+    handleKeyDown(event: NormalizedInputEvent): boolean;
+    handleKeyUp(event: NormalizedInputEvent): void;
+    addBinding(binding: KeyBinding): () => void;
+    private matchesBinding;
+}

package/dist/core/interactions/magnetic-controller.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AF Motion Magnetic Interaction Engine
+ *
+ * Provides smooth, spring-driven magnetic attraction and repulsion for DOM elements
+ * responding to pointer proximity, displacement limits, axis constraints, anchor points,
+ * distance falloffs, and transform layering composition.
+ */
+import type { MagneticController, MagneticControllerOptions } from "./types.js";
+export declare function createMagneticController(target: HTMLElement, initialOptions?: MagneticControllerOptions): MagneticController;

package/dist/core/interactions/magnetic-group.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion Magnetic Group Controller
+ *
+ * Coordinates multi-element magnetic interactions, arbitrating pointer attraction
+ * between adjacent elements to eliminate jitter, oscillation, and conflicting forces.
+ */
+import type { MagneticControllerOptions, MagneticGroupController, MagneticGroupOptions } from "./types.js";
+export declare function createMagneticGroup(initialElements: readonly (HTMLElement | {
+    element: HTMLElement;
+    options?: MagneticControllerOptions;
+})[], groupOptions?: MagneticGroupOptions): MagneticGroupController;

package/dist/core/interactions/multitouch-controller.d.ts

@@ -0,0 +1,62 @@
+/**
+ * AF Motion Multi-Touch Controller
+ *
+ * Framework-independent controller supporting combined pan, pinch-zoom, and rotation,
+ * anti-jump baseline stabilization across changing contact counts, bounds clamping,
+ * scale/rotation limits, inertia momentum, and elastic spring-back.
+ */
+import type { MultiTouchController, MultiTouchControllerOptions, MultiTouchState, Point2D, TouchTransform } from "./types.js";
+export declare class MultiTouchEngine implements MultiTouchController {
+    readonly target: HTMLElement;
+    private readonly options;
+    private readonly tracker;
+    private translation;
+    private scale;
+    private rotation;
+    private deltaCentroid;
+    private deltaScale;
+    private deltaRotation;
+    private pinchDirection;
+    private velocity;
+    private angularVelocity;
+    private scaleVelocity;
+    private baselineCentroid;
+    private baselineDistance;
+    private baselineAngle;
+    private lastTouchCount;
+    private isInteracting;
+    private inertiaPanX;
+    private inertiaPanY;
+    private inertiaRot;
+    private springScale;
+    private springPanX;
+    private springPanY;
+    private readonly originalTouchAction;
+    private boundListeners;
+    private isDestroyed;
+    constructor(target: HTMLElement, options?: MultiTouchControllerOptions);
+    getState(): MultiTouchState;
+    getTransform(): TouchTransform;
+    setTranslation(pos: Partial<Point2D>): void;
+    setScale(scale: number): void;
+    setRotation(rotation: number): void;
+    isActive(): boolean;
+    cancel(): void;
+    reset(): void;
+    destroy(): void;
+    private attach;
+    private checkPreventDefault;
+    private rebaseline;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handlePointerCancel;
+    private handleReleasePhysics;
+    private render;
+    private removeTransform;
+    private stopMomentum;
+}
+/**
+ * Creates and attaches a Multi-Touch Controller to an element.
+ */
+export declare function createMultiTouchController(target: HTMLElement, options?: MultiTouchControllerOptions): MultiTouchController;

package/dist/core/interactions/pointer-controller.d.ts

@@ -0,0 +1,34 @@
+/**
+ * AF Motion Advanced Pointer Controller
+ *
+ * Framework-independent controller providing multi-device pointer tracking,
+ * hover management, pressure/tilt/twist, acceleration, and capture lifecycle.
+ */
+import type { DeviceCapabilities, PointerController, PointerControllerOptions, PointerControllerState, TrackedPointer } from "./types.js";
+export declare class AdvancedPointerController implements PointerController {
+    readonly target: HTMLElement;
+    private readonly options;
+    private readonly tracker;
+    private readonly boundListeners;
+    private hovered;
+    private isDestroyed;
+    constructor(target: HTMLElement, options?: PointerControllerOptions);
+    getState(): PointerControllerState;
+    isHovered(): boolean;
+    getActivePointers(): ReadonlyMap<number, TrackedPointer>;
+    getPrimaryPointer(): TrackedPointer | null;
+    getDeviceCapabilities(): DeviceCapabilities;
+    cancel(): void;
+    destroy(): void;
+    private attach;
+    private handlePointerEnter;
+    private handlePointerLeave;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handlePointerCancel;
+}
+/**
+ * Creates and attaches an Advanced Pointer Controller to an element.
+ */
+export declare function createPointerController(target: HTMLElement, options?: PointerControllerOptions): PointerController;

package/dist/core/interactions/pointer-tracker.d.ts

@@ -0,0 +1,32 @@
+/**
+ * AF Motion Pointer Tracker
+ *
+ * Tracks single and multi-touch pointers, computes velocity, acceleration, movement delta,
+ * distances, contact dimensions, and multi-pointer centroids/angles with pointer capture management.
+ */
+import type { MultiPointerState, NormalizedInputEvent, TrackedPointer } from "./types.js";
+export interface PointerTrackerOptions {
+    sampleWindowMs?: number;
+    maxHistory?: number;
+}
+export declare class PointerTracker {
+    private readonly pointers;
+    private readonly capturedPointers;
+    private readonly sampleWindowMs;
+    private readonly maxHistory;
+    constructor(options?: PointerTrackerOptions);
+    get activePointers(): ReadonlyMap<number, TrackedPointer>;
+    get pointerCount(): number;
+    getPointer(id: number): TrackedPointer | undefined;
+    getPrimaryPointer(): TrackedPointer | undefined;
+    trackDown(event: NormalizedInputEvent): TrackedPointer | null;
+    trackMove(event: NormalizedInputEvent): TrackedPointer | null;
+    trackUp(event: NormalizedInputEvent): TrackedPointer | null;
+    trackCancel(event: NormalizedInputEvent): TrackedPointer | null;
+    clear(): void;
+    getMultiPointerState(): MultiPointerState;
+    capture(element: HTMLElement, pointerId: number): void;
+    release(element: HTMLElement, pointerId: number): void;
+    releaseAll(): void;
+    private calculateVelocity;
+}

package/dist/core/interactions/prioritizer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * AF Motion Interaction & Gesture Prioritizer
+ *
+ * Resolves conflicts between simultaneous interactions and gestures,
+ * enforces priority policies, mutual exclusion, and cancellation.
+ */
+import type { GestureRecognizer } from "./gesture-recognizers.js";
+import type { ConflictPolicy, GesturePrioritizationRule, GestureType, InteractionPriority } from "./types.js";
+export declare function normalizePriority(priority?: InteractionPriority): number;
+export declare class InteractionPrioritizer {
+    private readonly rules;
+    constructor(rules?: readonly GesturePrioritizationRule[]);
+    getRule(gesture: GestureType): GesturePrioritizationRule | undefined;
+    getPriority(gesture: GestureType): number;
+    getConflictPolicy(gesture: GestureType): ConflictPolicy;
+    resolveConflicts(activeRecognizer: GestureRecognizer, allRecognizers: readonly GestureRecognizer[]): void;
+}

package/dist/core/interactions/touch-controller.d.ts

@@ -0,0 +1,35 @@
+/**
+ * AF Motion Touch Controller
+ *
+ * Framework-independent controller providing single and multi-touch tracking,
+ * contact dimension extraction, touch-action management, and Pointer/Touch event deduplication.
+ */
+import type { TouchController, TouchControllerOptions, TouchControllerState, TrackedPointer } from "./types.js";
+export declare class TouchEngine implements TouchController {
+    readonly target: HTMLElement;
+    private readonly options;
+    private readonly tracker;
+    private readonly boundListeners;
+    private readonly originalTouchAction;
+    private lastProcessedTimestamp;
+    private isDestroyed;
+    constructor(target: HTMLElement, options?: TouchControllerOptions);
+    getState(): TouchControllerState;
+    getActiveTouches(): readonly TrackedPointer[];
+    cancel(): void;
+    destroy(): void;
+    private attach;
+    private checkPreventDefault;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handlePointerCancel;
+    private handleTouchStart;
+    private handleTouchMove;
+    private handleTouchEnd;
+    private handleTouchCancel;
+}
+/**
+ * Creates and attaches a Touch Controller to an element.
+ */
+export declare function createTouchController(target: HTMLElement, options?: TouchControllerOptions): TouchController;