@ue-too/board 0.9.5 → 0.11.0

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

@@ -1,31 +1,44 @@
 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 rotation control state machine.
+ *
+ * @remarks
+ * Three states manage rotation input and animations:
+ * - `ACCEPTING_USER_INPUT`: Normal state, accepts user rotation input
+ * - `TRANSITION`: Animation/transition state, may block user input
+ * - `LOCKED_ON_OBJECT`: Camera locked to follow a specific object rotation
  *
  * @category Input Flow Control
  */
 export type RotateControlStates = "ACCEPTING_USER_INPUT" | "TRANSITION" | "LOCKED_ON_OBJECT";
 /**
- * @description The payload for the rotate by input event.
- *
+ * Payload for rotate-by input events (relative rotation).
  * @category Input Flow Control
  */
 export type RotateByInputEventPayload = {
+    /** Rotation angle delta in radians */
     diff: number;
 };
 /**
- * @description The payload for the rotate to input event.
- *
+ * Payload for rotate-to input events (absolute rotation).
  * @category Input Flow Control
  */
 export type RotateToInputEventPayload = {
+    /** Target rotation angle in radians */
     target: number;
 };
+/** Empty payload for events that don't need data */
 type EmptyPayload = {};
 /**
- * @description The payload mapping for the events of the rotate control state machine.
+ * Event payload type mapping for the rotation control state machine.
+ *
+ * @remarks
+ * Maps event names to their payload types. Events include:
+ * - User input events (`userRotateByInput`, `userRotateToInput`)
+ * - Transition/animation events (`transitionRotateByInput`, `transitionRotateToInput`)
+ * - Locked object events (`lockedOnObjectRotateByInput`, `lockedOnObjectRotateToInput`)
+ * - Control events (`unlock`, `initateTransition`)
  *
  * @category Input Flow Control
  */
@@ -40,92 +53,167 @@ export type RotateEventPayloadMapping = {
     "initateTransition": EmptyPayload;
 };
 /**
- * @description The context for the rotate control state machine.
+ * Discriminated union of output events from rotation control state machine.
+ *
+ * @remarks
+ * Output events instruct the camera system what rotation operation to perform:
+ * - `rotateBy`: Relative rotation by delta angle
+ * - `rotateTo`: Absolute rotation to target angle
+ * - `none`: No operation (input blocked)
  *
  * @category Input Flow Control
  */
-export interface RotateContext extends BaseContext {
-    camera: BoardCamera;
-    rotateBy: (delta: number) => void;
-    rotateTo: (target: number) => void;
-}
+export type RotateControlOutputEvent = {
+    type: "rotateBy";
+    delta: number;
+} | {
+    type: "rotateTo";
+    target: number;
+} | {
+    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 rotation control events.
+ * Maps input event names to their corresponding output event types.
  *
  * @category Input Flow Control
  */
-export declare class RotateControlStateMachine extends TemplateStateMachine<RotateEventPayloadMapping, RotateContext, RotateControlStates> {
-    constructor(states: Record<RotateControlStates, State<RotateEventPayloadMapping, RotateContext, RotateControlStates>>, initialState: RotateControlStates, context: RotateContext);
+export type RotateControlOutputMapping = {
+    "userRotateByInput": RotateControlOutputEvent;
+    "userRotateToInput": RotateControlOutputEvent;
+    "transitionRotateByInput": RotateControlOutputEvent;
+    "transitionRotateToInput": RotateControlOutputEvent;
+    "lockedOnObjectRotateByInput": RotateControlOutputEvent;
+    "lockedOnObjectRotateToInput": RotateControlOutputEvent;
+};
+/**
+ * State machine controlling rotation input flow and animations.
+ *
+ * @remarks
+ * This state machine manages the lifecycle of rotation operations:
+ * - **User input handling**: Accepts or blocks user rotation gestures based on state
+ * - **Animation control**: Manages smooth rotate-to animations
+ * - **Object tracking**: Supports locking camera to follow objects with rotation
+ *
+ * **State transitions:**
+ * - `ACCEPTING_USER_INPUT` → `TRANSITION`: Start animation (`initateTransition`)
+ * - `ACCEPTING_USER_INPUT` → `LOCKED_ON_OBJECT`: Lock to object (`lockedOnObjectRotate...`)
+ * - `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 = createDefaultRotateControlStateMachine(cameraRig);
+ *
+ * // User rotates - accepted in ACCEPTING_USER_INPUT state
+ * const result = stateMachine.notifyRotateByInput(Math.PI / 4);
+ *
+ * // Start animation - transitions to TRANSITION state
+ * stateMachine.notifyRotateToAnimationInput(Math.PI);
+ *
+ * // User input now blocked while animating
+ * ```
+ *
+ * @category Input Flow Control
+ * @see {@link createDefaultRotateControlStateMachine} for factory function
+ */
+export declare class RotateControlStateMachine extends TemplateStateMachine<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
+    constructor(states: Record<RotateControlStates, State<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>>, initialState: RotateControlStates, context: BaseContext);
     /**
-     * @description Notify the pan input event.
+     * Notifies the state machine of user rotation input.
+     *
+     * @param diff - Rotation angle delta in radians
+     * @returns Event handling result with output event
      *
-     * @category Input Flow Control
+     * @remarks
+     * Dispatches `userRotateByInput` event. Accepted in `ACCEPTING_USER_INPUT` and `TRANSITION` states,
+     * where it may transition back to `ACCEPTING_USER_INPUT` (user interrupting animation).
      */
-    notifyRotateByInput(diff: number): void;
+    notifyRotateByInput(diff: number): import("@ue-too/being").EventResult<RotateControlStates, RotateControlOutputEvent>;
     /**
-     * @description Notify the rotate to animation input event.
+     * Initiates a rotation animation to a target angle.
+     *
+     * @param target - Target rotation angle in radians
+     * @returns Event handling result
      *
-     * @category Input Flow Control
+     * @remarks
+     * Dispatches `transitionRotateToInput` event, starting a rotation animation.
+     * Transitions to `TRANSITION` state where animation updates occur.
      */
-    notifyRotateToAnimationInput(target: number): void;
+    notifyRotateToAnimationInput(target: number): import("@ue-too/being").EventResult<RotateControlStates, RotateControlOutputEvent>;
     /**
-     * @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;
 }
 /**
- * @description The accepting user input state of the rotate control state machine.
- *
+ * State implementation for accepting user rotation input (idle/normal state).
+ * Accepts user rotation input and can transition to animation or locked states.
  * @category Input Flow Control
  */
-export declare class RotationAcceptingUserInputState extends TemplateState<RotateEventPayloadMapping, RotateContext, RotateControlStates> {
+export declare class RotationAcceptingUserInputState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<RotateEventPayloadMapping, RotateContext, RotateControlStates>;
-    userRotateByInputHandler(context: RotateContext, payload: RotateByInputEventPayload): void;
-    userRotateToInputHandler(context: RotateContext, payload: RotateToInputEventPayload): void;
-    lockedOnObjectRotateByInputHandler(context: RotateContext, payload: RotateByInputEventPayload): void;
-    lockedOnObjectRotateToInputHandler(context: RotateContext, payload: RotateToInputEventPayload): void;
+    eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
+    userRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
+    userRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
+    lockedOnObjectRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
+    lockedOnObjectRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
 }
 /**
- * @description The transition state of the rotate control state machine.
- *
+ * State implementation for rotation animations and transitions.
+ * Processes animation updates and allows user input to interrupt.
  * @category Input Flow Control
  */
-export declare class RotationTransitionState extends TemplateState<RotateEventPayloadMapping, RotateContext, RotateControlStates> {
+export declare class RotationTransitionState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<RotateEventPayloadMapping, RotateContext, RotateControlStates>;
-    userRotateByInputHandler(context: RotateContext, payload: RotateByInputEventPayload): RotateControlStates;
-    userRotateToInputHandler(context: RotateContext, payload: RotateToInputEventPayload): RotateControlStates;
-    transitionRotateByInputHandler(context: RotateContext, payload: RotateByInputEventPayload): RotateControlStates;
-    transitionRotateToInputHandler(context: RotateContext, payload: RotateToInputEventPayload): RotateControlStates;
-    lockedOnObjectRotateByInputHandler(context: RotateContext, payload: RotateByInputEventPayload): RotateControlStates;
-    lockedOnObjectRotateToInputHandler(context: RotateContext, payload: RotateToInputEventPayload): RotateControlStates;
+    eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
+    userRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
+    userRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
+    transitionRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
+    transitionRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
+    lockedOnObjectRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
+    lockedOnObjectRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
 }
 /**
- * @description The locked on object state of the pan control state machine.
- *
+ * State implementation for camera locked to follow an object rotation.
+ * Only accepts locked object rotation events until unlocked.
  * @category Input Flow Control
  */
-export declare class RotationLockedOnObjectState extends TemplateState<RotateEventPayloadMapping, RotateContext, RotateControlStates> {
+export declare class RotationLockedOnObjectState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
     constructor();
-    eventReactions: EventReactions<RotateEventPayloadMapping, RotateContext, RotateControlStates>;
-    lockedOnObjectRotateByInputHandler(context: RotateContext, payload: RotateByInputEventPayload): void;
-    lockedOnObjectRotateToInputHandler(context: RotateContext, payload: RotateToInputEventPayload): void;
+    eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
+    lockedOnObjectRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
+    lockedOnObjectRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
 }
 /**
- * @description Create the object containing the default pan control states.
- *
+ * Creates the default set of rotation control states.
+ * @returns State instances for all rotation control states
  * @category Input Flow Control
  */
-export declare function createDefaultRotateControlStates(): Record<RotateControlStates, State<RotateEventPayloadMapping, RotateContext, RotateControlStates>>;
+export declare function createDefaultRotateControlStates(): Record<RotateControlStates, State<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>>;
 /**
- * @description Create the default rotate control state machine.
+ * Creates a rotation control state machine with default configuration.
+ *
+ * @param context - Camera rig or context for rotation operations
+ * @returns Configured rotation control state machine starting in `ACCEPTING_USER_INPUT` state
+ *
+ * @remarks
+ * Factory function for creating a rotation state machine with sensible defaults.
+ * The machine starts in `ACCEPTING_USER_INPUT` state, ready to accept user rotation gestures.
+ *
+ * @example
+ * ```typescript
+ * const cameraRig = createDefaultCameraRig(camera);
+ * const rotateSM = createDefaultRotateControlStateMachine(cameraRig);
+ * ```
  *
  * @category Input Flow Control
  */
-export declare function createDefaultRotateControlStateMachine(context: RotateContext): RotateControlStateMachine;
+export declare function createDefaultRotateControlStateMachine(context: BaseContext): RotateControlStateMachine;
 export {};

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

@@ -2,47 +2,62 @@ import type { State, EventReactions, BaseContext } from "@ue-too/being";
 import { TemplateState, TemplateStateMachine } from "@ue-too/being";
 import { Point } from "@ue-too/math";
 /**
- * @description The possible states of the zoom control state machine.
+ * State identifiers for the zoom control state machine.
+ *
+ * @remarks
+ * Three states manage zoom input and animations:
+ * - `ACCEPTING_USER_INPUT`: Normal state, accepts user zoom input
+ * - `TRANSITION`: Animation/transition state, may block user input
+ * - `LOCKED_ON_OBJECT`: Camera locked to follow a specific object with zoom
  *
  * @category Input Flow Control
  */
 export type ZoomControlStates = "ACCEPTING_USER_INPUT" | "TRANSITION" | "LOCKED_ON_OBJECT";
 /**
- * @description The payload for the zoom by at input event.
- *
+ * Payload for zoom-by-at input events (relative zoom around a point).
  * @category Input Flow Control
  */
 export type ZoomByAtInputPayload = {
+    /** Zoom delta amount (multiplier) */
     deltaZoom: number;
+    /** Anchor point for zoom operation */
     anchorPoint: Point;
 };
 /**
- * @description The payload for the zoom to at input event.
- *
+ * Payload for zoom-to-at input events (absolute zoom to target around a point).
  * @category Input Flow Control
  */
 export type ZoomToAtInputPayload = {
+    /** Target zoom level */
     targetZoom: number;
+    /** Anchor point for zoom operation */
     anchorPoint: Point;
 };
 /**
- * @description The payload for the zoom by payload.
- *
+ * Payload for zoom-by input events (relative zoom without anchor).
  * @category Input Flow Control
  */
 export type ZoomByPayload = {
+    /** Zoom delta amount (multiplier) */
     deltaZoom: number;
 };
 /**
- * @description The payload for the zoom to payload.
- *
+ * Payload for zoom-to input events (absolute zoom to target level).
  * @category Input Flow Control
  */
 export type ZoomToPayload = {
+    /** Target zoom level */
     targetZoom: number;
 };
 /**
- * @description The payload mapping for the events of the zoom control state machine.
+ * Event payload type mapping for the zoom control state machine.
+ *
+ * @remarks
+ * Maps event names to their payload types. Events include:
+ * - User input events (`userZoomByAtInput`, `userZoomToAtInput`)
+ * - Transition/animation events (`transitionZoomByAtInput`, `transitionZoomToAtInput`, etc.)
+ * - Locked object events (`lockedOnObjectZoomByAtInput`, `lockedOnObjectZoomToAtInput`)
+ * - Control events (`unlock`, `initiateTransition`)
  *
  * @category Input Flow Control
  */
@@ -60,84 +75,216 @@ export type ZoomEventPayloadMapping = {
     "initiateTransition": {};
 };
 /**
- * @description The context for the zoom control state machine.
+ * Discriminated union of output events from zoom control state machine.
+ *
+ * @remarks
+ * Output events instruct the camera system what zoom operation to perform:
+ * - `zoomByAt`: Relative zoom around anchor point
+ * - `zoomToAt`: Absolute zoom to target level around anchor point
+ * - `zoomBy`: Relative zoom without anchor
+ * - `zoomTo`: Absolute zoom to target level without anchor
+ * - `zoomByAtWorld`: Relative zoom around world anchor point
+ * - `zoomToAtWorld`: Absolute zoom to target level around world anchor point
+ * - `none`: No operation (input blocked)
  *
  * @category Input Flow Control
  */
-export interface ZoomContext extends BaseContext {
-    zoomToAt: (targetZoom: number, at: Point) => void;
-    zoomByAt: (delta: number, at: Point) => void;
-    zoomTo: (targetZoom: number) => void;
-    zoomBy: (delta: number) => void;
-    zoomToAtWorld: (targetZoom: number, at: Point) => void;
-    zoomByAtWorld: (delta: number, at: Point) => void;
-}
+export type ZoomControlOutputEvent = {
+    type: "zoomByAt";
+    deltaZoom: number;
+    anchorPoint: Point;
+} | {
+    type: "zoomToAt";
+    targetZoom: number;
+    anchorPoint: Point;
+} | {
+    type: "zoomBy";
+    deltaZoom: number;
+} | {
+    type: "zoomTo";
+    targetZoom: number;
+} | {
+    type: "zoomByAtWorld";
+    deltaZoom: number;
+    anchorPoint: Point;
+} | {
+    type: "zoomToAtWorld";
+    targetZoom: number;
+    anchorPoint: Point;
+} | {
+    type: "none";
+};
 /**
- * @description The accepting user input state of the zoom control state machine.
+ * Output event type mapping for zoom control events.
+ * Maps input event names to their corresponding output event types.
  *
  * @category Input Flow Control
  */
-export declare class ZoomAcceptingUserInputState extends TemplateState<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates> {
+export type ZoomControlOutputMapping = {
+    "userZoomByAtInput": ZoomControlOutputEvent;
+    "userZoomToAtInput": ZoomControlOutputEvent;
+    "transitionZoomByAtInput": ZoomControlOutputEvent;
+    "transitionZoomToAtInput": ZoomControlOutputEvent;
+    "transitionZoomByAtCenterInput": ZoomControlOutputEvent;
+    "transitionZoomToAtCenterInput": ZoomControlOutputEvent;
+    "transitionZoomToAtWorldInput": ZoomControlOutputEvent;
+    "lockedOnObjectZoomByAtInput": ZoomControlOutputEvent;
+    "lockedOnObjectZoomToAtInput": ZoomControlOutputEvent;
+};
+/**
+ * State implementation for accepting user zoom input (idle/normal state).
+ * Accepts user zoom input and can transition to animation or locked states.
+ * @category Input Flow Control
+ */
+export declare class ZoomAcceptingUserInputState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
     private _eventReactions;
-    get eventReactions(): EventReactions<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates>;
-    userZoomByAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): void;
-    userZoomToAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): void;
+    get eventReactions(): EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
+    userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
+    userZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): ZoomControlOutputEvent;
 }
 /**
- * @description The transition state of the zoom control state machine.
- *
+ * State implementation for zoom animations and transitions.
+ * Processes animation updates and allows user input to interrupt.
  * @category Input Flow Control
  */
-export declare class ZoomTransitionState extends TemplateState<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates> {
+export declare class ZoomTransitionState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
     constructor();
     private _eventReactions;
-    get eventReactions(): EventReactions<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates>;
-    lockedOnObjectZoomByAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomByAtInput"]): void;
-    lockedOnObjectZoomToAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomToAtInput"]): void;
-    userZoomByAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): void;
-    userZoomToAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): void;
-    transitionZoomByAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["transitionZoomByAtInput"]): void;
-    transitionZoomByAtCenterInput(context: ZoomContext, payload: ZoomEventPayloadMapping["transitionZoomByAtCenterInput"]): void;
-    transitionZoomToAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["transitionZoomToAtInput"]): void;
-    transitionZoomToAtCenterInput(context: ZoomContext, payload: ZoomEventPayloadMapping["transitionZoomToAtCenterInput"]): void;
-    transitionZoomToAtWorldInput(context: ZoomContext, payload: ZoomEventPayloadMapping["transitionZoomToAtWorldInput"]): void;
+    get eventReactions(): EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
+    lockedOnObjectZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomByAtInput"]): ZoomControlOutputEvent;
+    lockedOnObjectZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomToAtInput"]): ZoomControlOutputEvent;
+    userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
+    userZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): ZoomControlOutputEvent;
+    transitionZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomByAtInput"]): ZoomControlOutputEvent;
+    transitionZoomByAtCenterInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomByAtCenterInput"]): ZoomControlOutputEvent;
+    transitionZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomToAtInput"]): ZoomControlOutputEvent;
+    transitionZoomToAtCenterInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomToAtCenterInput"]): ZoomControlOutputEvent;
+    transitionZoomToAtWorldInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomToAtWorldInput"]): ZoomControlOutputEvent;
 }
 /**
- * @description The locked on object state of the zoom control state machine.
- *
+ * State implementation for camera locked to follow an object with zoom.
+ * Accepts locked object zoom events and user input to unlock.
  * @category Input Flow Control
  */
-export declare class ZoomLockedOnObjectState extends TemplateState<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates> {
+export declare class ZoomLockedOnObjectState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
     constructor();
     private _eventReactions;
-    get eventReactions(): EventReactions<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates>;
-    lockedOnObjectZoomByAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomByAtInput"]): void;
-    lockedOnObjectZoomToAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomToAtInput"]): void;
-    userZoomByAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): void;
-    userZoomToAtInput(context: ZoomContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): void;
+    get eventReactions(): EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
+    lockedOnObjectZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomByAtInput"]): ZoomControlOutputEvent;
+    lockedOnObjectZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomToAtInput"]): ZoomControlOutputEvent;
+    userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
+    userZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): ZoomControlOutputEvent;
 }
 /**
- * @description The zoom control state machine.
+ * State machine controlling zoom input flow and animations.
+ *
+ * @remarks
+ * This state machine manages the lifecycle of zoom operations:
+ * - **User input handling**: Accepts or blocks user zoom gestures based on state
+ * - **Animation control**: Manages smooth zoom-to animations
+ * - **Object tracking**: Supports locking camera to follow objects with zoom
+ *
+ * **State transitions:**
+ * - `ACCEPTING_USER_INPUT` → `TRANSITION`: Start animation (`initiateTransition`)
+ * - `ACCEPTING_USER_INPUT` → `LOCKED_ON_OBJECT`: Lock to object (`lockedOnObjectZoom...`)
+ * - `TRANSITION` → `ACCEPTING_USER_INPUT`: User input interrupts animation
+ * - `LOCKED_ON_OBJECT` → `ACCEPTING_USER_INPUT`: User input unlocks
+ *
+ * Helper methods simplify event dispatching without memorizing event names.
+ *
+ * @example
+ * ```typescript
+ * const stateMachine = createDefaultZoomControlStateMachine(cameraRig);
+ *
+ * // User zooms - accepted in ACCEPTING_USER_INPUT state
+ * const result = stateMachine.notifyZoomByAtInput(1.2, { x: 400, y: 300 });
+ *
+ * // Start animation - transitions to TRANSITION state
+ * stateMachine.notifyZoomToAtWorldInput(2.0, { x: 1000, y: 500 });
+ *
+ * // User input now may interrupt animation
+ * ```
  *
  * @category Input Flow Control
+ * @see {@link createDefaultZoomControlStateMachine} for factory function
  */
-export declare class ZoomControlStateMachine extends TemplateStateMachine<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates> {
-    constructor(states: Record<ZoomControlStates, State<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates>>, initialState: ZoomControlStates, context: ZoomContext);
-    notifyZoomByAtInput(delta: number, at: Point): void;
-    notifyZoomByAtInputAnimation(delta: number, at: Point): void;
-    notifyZoomToAtCenterInput(targetZoom: number, at: Point): void;
-    notifyZoomToAtWorldInput(targetZoom: number, at: Point): void;
-    initateTransition(): void;
+export declare class ZoomControlStateMachine extends TemplateStateMachine<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
+    constructor(states: Record<ZoomControlStates, State<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>>, initialState: ZoomControlStates, context: BaseContext);
+    /**
+     * Notifies the state machine of user zoom input around an anchor point.
+     *
+     * @param delta - Zoom delta (multiplier)
+     * @param at - Anchor point for zoom
+     * @returns Event handling result with output event
+     *
+     * @remarks
+     * Dispatches `userZoomByAtInput` event. Accepted in `ACCEPTING_USER_INPUT` and `TRANSITION` states.
+     */
+    notifyZoomByAtInput(delta: number, at: Point): import("@ue-too/being").EventResult<ZoomControlStates, ZoomControlOutputEvent>;
+    /**
+     * Initiates a zoom animation around an anchor point.
+     *
+     * @param delta - Zoom delta (multiplier)
+     * @param at - Anchor point for zoom
+     * @returns Event handling result
+     *
+     * @remarks
+     * Dispatches `transitionZoomByAtInput` event, starting a zoom animation.
+     */
+    notifyZoomByAtInputAnimation(delta: number, at: Point): import("@ue-too/being").EventResult<ZoomControlStates, ZoomControlOutputEvent>;
+    /**
+     * Initiates a zoom animation to target level around center anchor.
+     *
+     * @param targetZoom - Target zoom level
+     * @param at - Anchor point for zoom
+     * @returns Event handling result
+     *
+     * @remarks
+     * Dispatches `transitionZoomToAtCenterInput` event for center-anchored zoom animation.
+     */
+    notifyZoomToAtCenterInput(targetZoom: number, at: Point): import("@ue-too/being").EventResult<ZoomControlStates, ZoomControlOutputEvent>;
+    /**
+     * Initiates a zoom animation to target level around world anchor.
+     *
+     * @param targetZoom - Target zoom level
+     * @param at - World anchor point for zoom
+     * @returns Event handling result
+     *
+     * @remarks
+     * Dispatches `transitionZoomToAtWorldInput` event for world-anchored zoom animation.
+     */
+    notifyZoomToAtWorldInput(targetZoom: number, at: Point): import("@ue-too/being").EventResult<ZoomControlStates, ZoomControlOutputEvent>;
+    /**
+     * Initiates transition to `TRANSITION` state.
+     *
+     * @remarks
+     * Forces state change to begin animation or transition sequence.
+     * Called when starting programmatic camera movements.
+     */
+    initateTransition(): import("@ue-too/being").EventResult<ZoomControlStates, void>;
 }
 /**
- * @description Create the object containing the default zoom control states.
- *
+ * Creates the default set of zoom control states.
+ * @returns State instances for all zoom control states
  * @category Input Flow Control
  */
-export declare function createDefaultZoomControlStates(): Record<ZoomControlStates, State<ZoomEventPayloadMapping, ZoomContext, ZoomControlStates>>;
+export declare function createDefaultZoomControlStates(): Record<ZoomControlStates, State<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>>;
 /**
- * @description Create the default zoom control state machine.
+ * Creates a zoom control state machine with default configuration.
+ *
+ * @param context - Camera rig or context for zoom operations
+ * @returns Configured zoom control state machine starting in `ACCEPTING_USER_INPUT` state
+ *
+ * @remarks
+ * Factory function for creating a zoom state machine with sensible defaults.
+ * The machine starts in `ACCEPTING_USER_INPUT` state, ready to accept user zoom gestures.
+ *
+ * @example
+ * ```typescript
+ * const cameraRig = createDefaultCameraRig(camera);
+ * const zoomSM = createDefaultZoomControlStateMachine(cameraRig);
+ * ```
  *
  * @category Input Flow Control
  */
-export declare function createDefaultZoomControlStateMachine(context: ZoomContext): ZoomControlStateMachine;
+export declare function createDefaultZoomControlStateMachine(context: BaseContext): ZoomControlStateMachine;

package/camera/camera-mux/index.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Camera multiplexer (mux) module exports.
+ *
+ * @remarks
+ * This module provides camera input coordination and arbitration between different control sources
+ * (user input, animations, programmatic control). The camera mux decides whether to allow or block
+ * camera operations based on the current state (e.g., block user input during animations).
+ *
+ * ## Implementations
+ *
+ * - **{@link Relay}**: Simple passthrough mux that allows all operations
+ * - **{@link CameraMuxWithAnimationAndLock}**: Advanced mux with animation support and input blocking
+ *
+ * ## Use Cases
+ *
+ * - Smooth camera animations (pan-to, zoom-to, rotate-to)
+ * - Input locking during programmatic camera movements
+ * - State-based input arbitration
+ * - Animation interruption handling
+ *
+ * @see {@link CameraMux} for the mux interface
+ * @see {@link CameraMuxWithAnimationAndLock} for animation support
+ * @see {@link Relay} for simple passthrough
+ *
+ * @module
+ */
 export * from "./interface";
 export * from "./relay";
 export * from "./animation-and-lock";