@ue-too/board 0.9.4 → 0.10.0

package/camera/camera-mux/animation-and-lock/animation-and-lock.d.ts

@@ -1,50 +1,352 @@
-import { CameraMux } from "../interface";
+import { CameraMux, CameraMuxPanOutput, CameraMuxZoomOutput, CameraMuxRotationOutput } from "../interface";
 import { Point } from "@ue-too/math";
 import { ObservableBoardCamera } from "../../interface";
 import { PanControlStateMachine } from "./pan-control-state-machine";
 import { ZoomControlStateMachine } from "./zoom-control-state-machine";
-import { RotateControlStateMachine } from "./rotation-control-state-machine";
+import { RotateControlStateMachine, RotateControlOutputEvent } from "./rotation-control-state-machine";
 import { CameraRig } from "../../camera-rig";
 /**
- * @description The flow control with animation and lock input.
+ * Advanced camera input multiplexer with animation support and input locking via state machines.
  *
- * This is a customized input flow control that suits a specific use case.
+ * @remarks
+ * This {@link CameraMux} implementation provides sophisticated input flow control using
+ * separate state machines for pan, zoom, and rotation. Each state machine can:
+ * - Block user input during camera animations
+ * - Manage animation playback
+ * - Arbitrate between user input and programmatic camera control
+ * - Handle transitions between different camera control states
  *
- * You can use the default one ({@link SimpleRelayFlowControl}) instead or implement your own.
+ * **Key features:**
+ * - **Animation system**: Support for smooth camera animations (pan-to, zoom-to, rotate-to)
+ * - **Input locking**: Automatically block user input during animations
+ * - **State-based control**: Each camera operation (pan/zoom/rotate) has its own state machine
+ * - **Flexible transitions**: Initiate transitions to interrupt or chain animations
  *
- * The internal ruleset on which input is used and which is ignored is controlled by the state machines.
+ * **Architecture:**
+ * - Three independent state machines: {@link PanControlStateMachine}, {@link ZoomControlStateMachine}, {@link RotateControlStateMachine}
+ * - Each state machine decides whether to allow or block input based on current state
+ * - State machines receive events and produce output events for camera operations
+ *
+ * **When to use:**
+ * - Applications requiring smooth camera animations (e.g., "focus on object", "zoom to region")
+ * - UI where user input should be blocked during programmatic camera movements
+ * - Games or interactive experiences with scripted camera sequences
+ *
+ * **Alternatives:**
+ * - Use {@link Relay} for simple passthrough without animation support
+ * - Implement custom {@link CameraMux} for different state management approaches
+ *
+ * @example
+ * ```typescript
+ * const camera = new DefaultBoardCamera();
+ * const mux = createCameraMuxWithAnimationAndLock(camera);
+ *
+ * // Start a pan animation - user input will be blocked
+ * mux.notifyPanToAnimationInput({ x: 1000, y: 500 });
+ *
+ * // User tries to pan during animation - will be blocked
+ * const result = mux.notifyPanInput({ x: 50, y: 30 });
+ * // result.allowPassThrough = false (blocked during animation)
+ *
+ * // After animation completes, user input allowed again
+ * ```
  *
  * @category Input Flow Control
+ * @see {@link CameraMux} for the interface definition
+ * @see {@link Relay} for simpler passthrough implementation
+ * @see {@link createCameraMuxWithAnimationAndLock} for factory function
  */
 export declare class CameraMuxWithAnimationAndLock implements CameraMux {
     private _panStateMachine;
     private _zoomStateMachine;
     private _rotateStateMachine;
+    /**
+     * Creates a new camera mux with animation and locking capabilities.
+     *
+     * @param panStateMachine - State machine controlling pan operations and animations
+     * @param zoomStateMachine - State machine controlling zoom operations and animations
+     * @param rotateStateMachine - State machine controlling rotation operations and animations
+     *
+     * @remarks
+     * Typically created via factory functions like {@link createCameraMuxWithAnimationAndLock}
+     * rather than direct instantiation.
+     */
     constructor(panStateMachine: PanControlStateMachine, zoomStateMachine: ZoomControlStateMachine, rotateStateMachine: RotateControlStateMachine);
-    notifyPanToAnimationInput(target: Point): void;
-    notifyPanInput(delta: Point): void;
-    notifyZoomInput(delta: number, at: Point): void;
-    notifyRotateByInput(delta: number): void;
-    notifyRotateToAnimationInput(target: number): void;
+    /**
+     * Initiates a pan animation to a target position.
+     *
+     * @param target - Target position in world coordinates
+     * @returns Pan output indicating whether animation was initiated
+     *
+     * @remarks
+     * This method starts a camera pan animation to the specified world position.
+     * The state machine handles:
+     * - Starting the animation
+     * - Blocking user input during animation
+     * - Producing incremental pan deltas each frame
+     *
+     * The animation continues until the camera reaches the target or is interrupted.
+     *
+     * @example
+     * ```typescript
+     * // Animate camera to world position
+     * mux.notifyPanToAnimationInput({ x: 1000, y: 500 });
+     * ```
+     */
+    notifyPanToAnimationInput(target: Point): CameraMuxPanOutput;
+    /**
+     * Processes user pan input (implements {@link CameraMux.notifyPanInput}).
+     *
+     * @param delta - Pan delta in viewport coordinates
+     * @returns Output indicating whether pan is allowed
+     *
+     * @remarks
+     * This method is called when the user attempts to pan the camera (e.g., mouse drag).
+     * The pan state machine determines whether to allow the input based on current state:
+     * - **Allowed**: When in idle state or user control state
+     * - **Blocked**: When camera animation is playing
+     *
+     * @example
+     * ```typescript
+     * // User drags mouse
+     * const result = mux.notifyPanInput({ x: 50, y: 30 });
+     * if (result.allowPassThrough) {
+     *   // Apply pan to camera
+     *   cameraRig.panByViewPort(result.delta);
+     * }
+     * ```
+     */
+    notifyPanInput(delta: Point): CameraMuxPanOutput;
+    /**
+     * Processes user zoom input (implements {@link CameraMux.notifyZoomInput}).
+     *
+     * @param delta - Zoom delta (change in zoom level)
+     * @param at - Anchor point in viewport coordinates
+     * @returns Output indicating whether zoom is allowed
+     *
+     * @remarks
+     * This method is called when the user attempts to zoom (e.g., mouse wheel).
+     * The zoom state machine determines whether to allow the input based on current state:
+     * - **Allowed**: When in idle state or user control state
+     * - **Blocked**: When zoom animation is playing
+     *
+     * @example
+     * ```typescript
+     * // User scrolls mouse wheel
+     * const result = mux.notifyZoomInput(0.1, mousePosition);
+     * if (result.allowPassThrough) {
+     *   // Apply zoom to camera
+     *   cameraRig.zoomByAt(result.delta, result.anchorPoint);
+     * }
+     * ```
+     */
+    notifyZoomInput(delta: number, at: Point): CameraMuxZoomOutput;
+    /**
+     * Processes user rotation input (rotate-by variant).
+     *
+     * @param delta - Rotation delta in radians
+     * @returns Output from rotation state machine
+     *
+     * @remarks
+     * Delegates to the rotation state machine's rotate-by handler.
+     * The state machine determines whether to allow rotation based on current state.
+     */
+    notifyRotateByInput(delta: number): import("@ue-too/being").EventResult<import("./rotation-control-state-machine").RotateControlStates, RotateControlOutputEvent>;
+    /**
+     * Initiates a rotation animation to a target angle.
+     *
+     * @param target - Target rotation angle in radians
+     * @returns Output from rotation state machine
+     *
+     * @remarks
+     * Starts a camera rotation animation to the specified angle.
+     * User input will be blocked during the animation.
+     */
+    notifyRotateToAnimationInput(target: number): import("@ue-too/being").EventResult<import("./rotation-control-state-machine").RotateControlStates, RotateControlOutputEvent>;
+    /**
+     * Initiates a zoom animation to a target level at a viewport position.
+     *
+     * @param targetZoom - Target zoom level
+     * @param at - Anchor point in viewport coordinates (defaults to origin)
+     *
+     * @remarks
+     * Starts a zoom animation that zooms to the specified level while keeping
+     * the anchor point stationary (zoom-to-cursor behavior).
+     * User input will be blocked during the animation.
+     */
     notifyZoomInputAnimation(targetZoom: number, at?: Point): void;
+    /**
+     * Initiates a zoom animation to a target level at a world position.
+     *
+     * @param targetZoom - Target zoom level
+     * @param at - Anchor point in world coordinates (defaults to origin)
+     *
+     * @remarks
+     * Similar to {@link notifyZoomInputAnimation} but accepts world-space coordinates
+     * for the anchor point instead of viewport coordinates.
+     */
     notifyZoomInputAnimationWorld(targetZoom: number, at?: Point): void;
-    notifyRotationInput(delta: number): void;
+    /**
+     * Processes user rotation input (implements {@link CameraMux.notifyRotationInput}).
+     *
+     * @param delta - Rotation delta in radians
+     * @returns Output indicating whether rotation is allowed
+     *
+     * @remarks
+     * This method is called when the user attempts to rotate the camera.
+     * The rotation state machine determines whether to allow the input based on current state:
+     * - **Allowed**: When in idle state or user control state
+     * - **Blocked**: When rotation animation is playing
+     *
+     * @example
+     * ```typescript
+     * // User rotates camera
+     * const result = mux.notifyRotationInput(0.1);
+     * if (result.allowPassThrough) {
+     *   cameraRig.rotateBy(result.delta);
+     * }
+     * ```
+     */
+    notifyRotationInput(delta: number): CameraMuxRotationOutput;
+    /**
+     * Initiates a transition in the pan state machine.
+     *
+     * @remarks
+     * This method forces the pan state machine to transition to its next state.
+     * Can be used to interrupt animations or force state changes.
+     */
     initatePanTransition(): void;
+    /**
+     * Initiates a transition in the zoom state machine.
+     *
+     * @remarks
+     * This method forces the zoom state machine to transition to its next state.
+     * Can be used to interrupt animations or force state changes.
+     */
     initateZoomTransition(): void;
+    /**
+     * Initiates a transition in the rotation state machine.
+     *
+     * @remarks
+     * This method forces the rotation state machine to transition to its next state.
+     * Can be used to interrupt animations or force state changes.
+     */
     initateRotateTransition(): void;
+    /**
+     * Gets the rotation state machine.
+     *
+     * @returns The rotation state machine instance
+     *
+     * @remarks
+     * Provides direct access to the rotation state machine for advanced control
+     * or state inspection.
+     */
     get rotateStateMachine(): RotateControlStateMachine;
+    /**
+     * Gets the pan state machine.
+     *
+     * @returns The pan state machine instance
+     *
+     * @remarks
+     * Provides direct access to the pan state machine for advanced control
+     * or state inspection.
+     */
     get panStateMachine(): PanControlStateMachine;
+    /**
+     * Gets the zoom state machine.
+     *
+     * @returns The zoom state machine instance
+     *
+     * @remarks
+     * Provides direct access to the zoom state machine for advanced control
+     * or state inspection.
+     */
     get zoomStateMachine(): ZoomControlStateMachine;
 }
 /**
- * @description Create a flow control that allows animation and lock inputs.
+ * Creates a camera mux with animation and locking capabilities from a camera instance.
+ *
+ * @param camera - Observable camera to control
+ * @returns Configured camera mux with animation support
+ *
+ * @remarks
+ * This factory function creates a complete camera input flow control system with:
+ * 1. A default {@link CameraRig} wrapping the provided camera
+ * 2. Three state machines (pan, zoom, rotation) for animation control
+ * 3. A {@link CameraMuxWithAnimationAndLock} coordinating the state machines
+ *
+ * **What you get:**
+ * - Smooth camera animations (pan-to, zoom-to, rotate-to)
+ * - Automatic input blocking during animations
+ * - State-based input arbitration
+ * - All with sensible default configurations
+ *
+ * **Use this when:**
+ * - You have a camera and want animation support out-of-the-box
+ * - You don't need custom camera rig configuration
+ * - You want the simplest setup for animated camera control
+ *
+ * @example
+ * ```typescript
+ * const camera = new DefaultBoardCamera(1920, 1080);
+ * const mux = createCameraMuxWithAnimationAndLock(camera);
+ *
+ * // Start a pan animation
+ * mux.notifyPanToAnimationInput({ x: 1000, y: 500 });
+ *
+ * // User input is blocked during animation
+ * const result = mux.notifyPanInput({ x: 50, y: 30 });
+ * console.log(result.allowPassThrough); // false during animation
+ * ```
  *
  * @category Input Flow Control
+ * @see {@link CameraMuxWithAnimationAndLock} for the implementation
+ * @see {@link createCameraMuxWithAnimationAndLockWithCameraRig} for custom rig version
  */
 export declare function createCameraMuxWithAnimationAndLock(camera: ObservableBoardCamera): CameraMux;
 /**
- * @description Create a default flow control with a camera rig.
+ * Creates a camera mux with animation and locking capabilities from a camera rig.
+ *
+ * @param cameraRig - Pre-configured camera rig to use
+ * @returns Configured camera mux with animation support
+ *
+ * @remarks
+ * Similar to {@link createCameraMuxWithAnimationAndLock} but accepts an existing
+ * camera rig instead of creating a default one. Use this when you need:
+ * - Custom camera rig configuration
+ * - Specific pan/zoom/rotation constraints
+ * - Non-default handler pipelines
+ * - To share a camera rig between multiple systems
+ *
+ * **Advantages over camera-only variant:**
+ * - Full control over camera rig settings
+ * - Ability to configure boundaries, restrictions, clamping
+ * - Use custom handler functions
+ * - Reuse existing rig instance
+ *
+ * @example
+ * ```typescript
+ * // Create custom camera rig with specific config
+ * const camera = new DefaultBoardCamera(1920, 1080);
+ * const rig = new DefaultCameraRig({
+ *   limitEntireViewPort: true,
+ *   clampTranslation: true,
+ *   boundaries: {
+ *     min: { x: 0, y: 0 },
+ *     max: { x: 2000, y: 1000 }
+ *   }
+ * }, camera);
+ *
+ * // Create mux with custom rig
+ * const mux = createCameraMuxWithAnimationAndLockWithCameraRig(rig);
+ *
+ * // Animations respect rig's boundaries and constraints
+ * mux.notifyPanToAnimationInput({ x: 3000, y: 1500 });
+ * // Camera will be clamped to boundaries during animation
+ * ```
  *
  * @category Input Flow Control
+ * @see {@link CameraMuxWithAnimationAndLock} for the implementation
+ * @see {@link createCameraMuxWithAnimationAndLock} for simpler camera-only version
  */
 export declare function createCameraMuxWithAnimationAndLockWithCameraRig(cameraRig: CameraRig): CameraMux;

package/camera/camera-mux/animation-and-lock/index.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Animation and input locking module exports.
+ *
+ * @remarks
+ * This module provides the {@link CameraMuxWithAnimationAndLock} implementation and its supporting
+ * state machines for pan, zoom, and rotation control. Each operation has its own state machine that
+ * manages animation playback and input blocking.
+ *
+ * ## State Machines
+ *
+ * Each state machine manages three states:
+ * - **ACCEPTING_USER_INPUT**: Normal state, accepts user input
+ * - **TRANSITION**: Animation/transition state, may block user input
+ * - **LOCKED_ON_OBJECT**: Camera locked to follow an object (blocks user input)
+ *
+ * ## Components
+ *
+ * - **{@link CameraMuxWithAnimationAndLock}**: Main multiplexer with animation support
+ * - **{@link PanControlStateMachine}**: State machine for pan input flow control
+ * - **{@link ZoomControlStateMachine}**: State machine for zoom input flow control
+ * - **{@link RotateControlStateMachine}**: State machine for rotation input flow control
+ *
+ * @see {@link CameraMuxWithAnimationAndLock} for the main implementation
+ * @see {@link createCameraMuxWithAnimationAndLock} for factory function
+ *
+ * @module
+ */
 export * from "./animation-and-lock";
 export * from "./pan-control-state-machine";
 export * from "./zoom-control-state-machine";

package/camera/camera-mux/animation-and-lock/pan-control-state-machine.d.ts

@@ -1,32 +1,45 @@
 import { Point } from "@ue-too/math";
 import type { EventReactions, State, BaseContext } from "@ue-too/being";
 import { TemplateState, TemplateStateMachine } from "@ue-too/being";
-import { BoardCamera } from "../../interface";
 /**
- * @description The states of the pan control state machine.
+ * State identifiers for the pan control state machine.
+ *
+ * @remarks
+ * Three states manage pan input and animations:
+ * - `ACCEPTING_USER_INPUT`: Normal state, accepts user pan input
+ * - `TRANSITION`: Animation/transition state, may block user input
+ * - `LOCKED_ON_OBJECT`: Camera locked to follow a specific object/position
  *
  * @category Input Flow Control
  */
 export type PanControlStates = "ACCEPTING_USER_INPUT" | "TRANSITION" | "LOCKED_ON_OBJECT";
 /**
- * @description The payload for the pan by input event.
- *
+ * Payload for pan-by input events (relative panning).
  * @category Input Flow Control
  */
 export type PanByInputEventPayload = {
+    /** Pan displacement in viewport coordinates */
     diff: Point;
 };
 /**
- * @description The payload for the pan to input event.
- *
+ * Payload for pan-to input events (absolute panning).
  * @category Input Flow Control
  */
 export type PanToInputEventPayload = {
+    /** Target position to pan to */
     target: Point;
 };
+/** Empty payload for events that don't need data */
 type EmptyPayload = {};
 /**
- * @description The payload mapping for the events of the pan control state machine.
+ * Event payload type mapping for the pan control state machine.
+ *
+ * @remarks
+ * Maps event names to their payload types. Events include:
+ * - User input events (`userPanByInput`, `userPanToInput`)
+ * - Transition/animation events (`transitionPanByInput`, `transitionPanToInput`)
+ * - Locked object events (`lockedOnObjectPanByInput`, `lockedOnObjectPanToInput`)
+ * - Control events (`unlock`, `initateTransition`)
  *
  * @category Input Flow Control
  */
@@ -41,97 +54,167 @@ export type PanEventPayloadMapping = {
     "initateTransition": EmptyPayload;
 };
 /**
- * @description The context for the pan control state machine.
+ * Discriminated union of output events from pan control state machine.
+ *
+ * @remarks
+ * Output events instruct the camera system what pan operation to perform:
+ * - `panByViewPort`: Relative pan in viewport coordinates
+ * - `panToWorld`: Absolute pan to world position
+ * - `none`: No operation (input blocked)
  *
  * @category Input Flow Control
  */
-export interface PanContext extends BaseContext {
-    camera: BoardCamera;
-    limitEntireViewPort: boolean;
-    panByViewPort: (delta: Point) => void;
-    panToViewPort: (target: Point) => void;
-    panByWorld: (delta: Point) => void;
-    panToWorld: (target: Point) => void;
-}
+export type PanControlOutputEvent = {
+    type: "panByViewPort";
+    delta: Point;
+} | {
+    type: "panToWorld";
+    target: Point;
+} | {
+    type: "none";
+};
 /**
- * @description The pan control state machine.
- * It's not created directly using the TemplateStateMachine class.
- * A few helper functions are in place to make it easier to use. (user don't have to memorize the event names)
+ * Output event type mapping for pan control events.
+ * Maps input event names to their corresponding output event types.
  *
  * @category Input Flow Control
  */
-export declare class PanControlStateMachine extends TemplateStateMachine<PanEventPayloadMapping, PanContext, PanControlStates> {
-    constructor(states: Record<PanControlStates, State<PanEventPayloadMapping, PanContext, PanControlStates>>, initialState: PanControlStates, context: PanContext);
+export type PanControlOutputMapping = {
+    "userPanByInput": PanControlOutputEvent;
+    "userPanToInput": PanControlOutputEvent;
+    "transitionPanByInput": PanControlOutputEvent;
+    "transitionPanToInput": PanControlOutputEvent;
+    "lockedOnObjectPanByInput": PanControlOutputEvent;
+    "lockedOnObjectPanToInput": PanControlOutputEvent;
+};
+/**
+ * State machine controlling pan input flow and animations.
+ *
+ * @remarks
+ * This state machine manages the lifecycle of pan operations:
+ * - **User input handling**: Accepts or blocks user pan gestures based on state
+ * - **Animation control**: Manages smooth pan-to animations
+ * - **Object tracking**: Supports locking camera to follow objects
+ *
+ * **State transitions:**
+ * - `ACCEPTING_USER_INPUT` → `TRANSITION`: Start animation (`initateTransition`)
+ * - `ACCEPTING_USER_INPUT` → `LOCKED_ON_OBJECT`: Lock to object (`lockedOnObjectPan...`)
+ * - `TRANSITION` → `ACCEPTING_USER_INPUT`: User input interrupts animation
+ * - `LOCKED_ON_OBJECT` → `ACCEPTING_USER_INPUT`: Unlock (`unlock` event)
+ *
+ * Helper methods simplify event dispatching without memorizing event names.
+ *
+ * @example
+ * ```typescript
+ * const stateMachine = createDefaultPanControlStateMachine(cameraRig);
+ *
+ * // User pans - accepted in ACCEPTING_USER_INPUT state
+ * const result = stateMachine.notifyPanInput({ x: 50, y: 30 });
+ *
+ * // Start animation - transitions to TRANSITION state
+ * stateMachine.notifyPanToAnimationInput({ x: 1000, y: 500 });
+ *
+ * // User input now blocked while animating
+ * ```
+ *
+ * @category Input Flow Control
+ * @see {@link createDefaultPanControlStateMachine} for factory function
+ */
+export declare class PanControlStateMachine extends TemplateStateMachine<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping> {
+    constructor(states: Record<PanControlStates, State<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>>, initialState: PanControlStates, context: BaseContext);
     /**
-     * @description Notify the pan input event.
+     * Notifies the state machine of user pan input.
+     *
+     * @param diff - Pan displacement in viewport coordinates
+     * @returns Event handling result with output event
      *
-     * @category Input Flow Control
+     * @remarks
+     * Dispatches `userPanByInput` event. Accepted in `ACCEPTING_USER_INPUT` and `TRANSITION` states,
+     * where it may transition back to `ACCEPTING_USER_INPUT` (user interrupting animation).
      */
-    notifyPanInput(diff: Point): void;
+    notifyPanInput(diff: Point): import("@ue-too/being").EventResult<PanControlStates, PanControlOutputEvent>;
     /**
-     * @description Notify the pan to animation input event.
+     * Initiates a pan animation to a target position.
+     *
+     * @param target - Target position in world coordinates
+     * @returns Event handling result
      *
-     * @category Input Flow Control
+     * @remarks
+     * Dispatches `transitionPanToInput` event, starting a pan animation.
+     * Transitions to `TRANSITION` state where animation updates occur.
      */
-    notifyPanToAnimationInput(target: Point): void;
+    notifyPanToAnimationInput(target: Point): import("@ue-too/being").EventResult<PanControlStates, PanControlOutputEvent>;
     /**
-     * @description Initate the transition.
+     * Initiates transition to `TRANSITION` state.
      *
-     * @category Input Flow Control
+     * @remarks
+     * Forces state change to begin animation or transition sequence.
+     * Called when starting programmatic camera movements.
      */
     initateTransition(): void;
-    set limitEntireViewPort(limit: boolean);
-    get limitEntireViewPort(): boolean;
 }
 /**
- * @description The accepting user input state of the pan control state machine.
- *
+ * State implementation for accepting user pan input (idle/normal state).
+ * Accepts user pan input and can transition to animation or locked states.
  * @category Input Flow Control
  */
-export declare class AcceptingUserInputState extends TemplateState<PanEventPayloadMapping, PanContext, PanControlStates> {
+export declare class AcceptingUserInputState extends TemplateState<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<PanEventPayloadMapping, PanContext, PanControlStates>;
-    userPanByInputHandler(context: PanContext, payload: PanByInputEventPayload): void;
-    userPanToInputHandler(context: PanContext, payload: PanToInputEventPayload): void;
-    lockedOnObjectPanByInputHandler(context: PanContext, payload: PanByInputEventPayload): void;
-    lockedOnObjectPanToInputHandler(context: PanContext, payload: PanToInputEventPayload): void;
+    eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
+    userPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
+    userPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
+    lockedOnObjectPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
+    lockedOnObjectPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
 }
 /**
- * @description The transition state of the pan control state machine.
- *
+ * State implementation for pan animations and transitions.
+ * Processes animation updates and allows user input to interrupt.
  * @category Input Flow Control
  */
-export declare class TransitionState extends TemplateState<PanEventPayloadMapping, PanContext, PanControlStates> {
+export declare class TransitionState extends TemplateState<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<PanEventPayloadMapping, PanContext, PanControlStates>;
-    userPanByInputHandler(context: PanContext, payload: PanByInputEventPayload): PanControlStates;
-    userPanToInputHandler(context: PanContext, payload: PanToInputEventPayload): PanControlStates;
-    transitionPanByInputHandler(context: PanContext, payload: PanByInputEventPayload): PanControlStates;
-    transitionPanToInputHandler(context: PanContext, payload: PanToInputEventPayload): PanControlStates;
-    lockedOnObjectPanByInputHandler(context: PanContext, payload: PanByInputEventPayload): PanControlStates;
-    lockedOnObjectPanToInputHandler(context: PanContext, payload: PanToInputEventPayload): PanControlStates;
+    eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
+    userPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
+    userPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
+    transitionPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
+    transitionPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
+    lockedOnObjectPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
+    lockedOnObjectPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
 }
 /**
- * @description The locked on object state of the pan control state machine.
- *
+ * State implementation for camera locked to follow an object.
+ * Only accepts locked object pan events until unlocked.
  * @category Input Flow Control
  */
-export declare class LockedOnObjectState extends TemplateState<PanEventPayloadMapping, PanContext, PanControlStates> {
+export declare class LockedOnObjectState extends TemplateState<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<PanEventPayloadMapping, PanContext, PanControlStates>;
-    lockedOnObjectPanByInputHandler(context: PanContext, payload: PanByInputEventPayload): void;
-    lockedOnObjectPanToInputHandler(context: PanContext, payload: PanToInputEventPayload): void;
+    eventReactions: EventReactions<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>;
+    lockedOnObjectPanByInputHandler(context: BaseContext, payload: PanByInputEventPayload): PanControlOutputEvent;
+    lockedOnObjectPanToInputHandler(context: BaseContext, payload: PanToInputEventPayload): PanControlOutputEvent;
 }
 /**
- * @description Create the object containing the default pan control states.
- *
+ * Creates the default set of pan control states.
+ * @returns State instances for all pan control states
  * @category Input Flow Control
  */
-export declare function createDefaultPanControlStates(): Record<PanControlStates, State<PanEventPayloadMapping, PanContext, PanControlStates>>;
+export declare function createDefaultPanControlStates(): Record<PanControlStates, State<PanEventPayloadMapping, BaseContext, PanControlStates, PanControlOutputMapping>>;
 /**
- * @description Create the default pan control state machine.
+ * Creates a pan control state machine with default configuration.
+ *
+ * @param context - Camera rig or context for pan operations
+ * @returns Configured pan control state machine starting in `ACCEPTING_USER_INPUT` state
+ *
+ * @remarks
+ * Factory function for creating a pan state machine with sensible defaults.
+ * The machine starts in `ACCEPTING_USER_INPUT` state, ready to accept user pan gestures.
+ *
+ * @example
+ * ```typescript
+ * const cameraRig = createDefaultCameraRig(camera);
+ * const panSM = createDefaultPanControlStateMachine(cameraRig);
+ * ```
  *
  * @category Input Flow Control
  */
-export declare function createDefaultPanControlStateMachine(context: PanContext): PanControlStateMachine;
+export declare function createDefaultPanControlStateMachine(context: BaseContext): PanControlStateMachine;
 export {};