blacktrigram 0.7.2

package/lib/hooks/useHandPoseTransitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHandPoseTransitions.js","names":[],"sources":["../../src/hooks/useHandPoseTransitions.ts"],"sourcesContent":["/**\n * useHandPoseTransitions - Shared hook for hand animation management\n *\n * Manages hand pose transitions and animation state for both hands.\n * Reduces code duplication in skeletal animation components.\n *\n * @module hooks/useHandPoseTransitions\n * @category Hooks\n * @korean 손자세전환훅\n */\n\nimport { useEffect, useRef, useState } from \"react\";\nimport {\n  createInitialHandAnimationState,\n  getTechniqueHandPose,\n  updateHandAnimationState,\n} from \"../systems/animation\";\nimport type { HandAnimationState } from \"../types/hand-animation\";\nimport { HandPoseType } from \"../types/hand-animation\";\nimport type { PlayerAnimation } from \"../types/player-visual\";\n\n/**\n * Default transition duration for hand pose changes (in seconds)\n * @korean 손자세전환기본지속시간\n */\nconst DEFAULT_HAND_TRANSITION_DURATION = 0.2;\n\n/**\n * Frequency of React state syncs during hand animations.\n * Value of 20 means sync every 5% progress (~every 3 frames at 60fps).\n * Reduces React re-renders from 60/sec to ~20/sec during transitions.\n * @korean 손상태동기화빈도\n */\nconst HAND_STATE_SYNC_FREQUENCY = 20;\n\n/**\n * Options for useHandPoseTransitions hook\n * @korean 손자세전환훅옵션\n */\nexport interface UseHandPoseTransitionsOptions {\n  /** Current animation name */\n  readonly currentAnimation: PlayerAnimation;\n  /** Specific attack animation name (for attack state) */\n  readonly attackAnimation?: string;\n  /** Whether player is blocking */\n  readonly isBlocking?: boolean;\n}\n\n/**\n * Return type for useHandPoseTransitions hook\n * @korean 손자세전환훅반환타입\n */\nexport interface UseHandPoseTransitionsReturn {\n  /** Left hand animation state */\n  readonly leftHandState: HandAnimationState;\n  /** Right hand animation state */\n  readonly rightHandState: HandAnimationState;\n  /** Update hand animations (call in useFrame) */\n  readonly updateHandAnimations: (delta: number) => void;\n}\n\n/**\n * Updates hand animation state for a single hand at 60fps.\n * Uses refs to avoid triggering React re-renders on every frame.\n * Only syncs to React state periodically or when transition completes.\n *\n * @param handStateRef - Ref storing current hand animation state\n * @param setHandState - React setState function to update hand state\n * @param delta - Time elapsed since last frame (in seconds)\n * @korean 손애니메이션프레임업데이트\n */\nconst updateHandAnimationFrame = (\n  handStateRef: React.MutableRefObject<HandAnimationState>,\n  setHandState: React.Dispatch<React.SetStateAction<HandAnimationState>>,\n  delta: number\n): void => {\n  if (handStateRef.current && handStateRef.current.targetPose !== null) {\n    const previousState = handStateRef.current;\n    const updatedState = updateHandAnimationState(\n      previousState,\n      previousState.targetPose,\n      delta,\n      DEFAULT_HAND_TRANSITION_DURATION\n    );\n\n    handStateRef.current = updatedState;\n\n    // Sync to React state periodically (approximately every 3 frames at 60fps)\n    if (\n      updatedState.targetPose === null ||\n      Math.floor(updatedState.transitionProgress * HAND_STATE_SYNC_FREQUENCY) !==\n        Math.floor(\n          previousState.transitionProgress * HAND_STATE_SYNC_FREQUENCY\n        )\n    ) {\n      setHandState(updatedState);\n    }\n  }\n};\n\n/**\n * useHandPoseTransitions hook\n *\n * Manages hand pose transitions for both hands based on current animation.\n * Automatically selects appropriate hand poses for different techniques\n * and handles smooth transitions at 60fps.\n *\n * @param options - Hand animation options\n * @returns Hand states and update function\n *\n * @example\n * ```tsx\n * const { leftHandState, rightHandState, updateHandAnimations } =\n *   useHandPoseTransitions({\n *     currentAnimation: \"attack\",\n *     attackAnimation: \"jab\",\n *     isBlocking: false,\n *   });\n *\n * // In useFrame callback\n * useFrame((_, delta) => {\n *   updateHandAnimations(delta);\n * });\n * ```\n *\n * @korean 손자세전환훅\n */\nexport function useHandPoseTransitions(\n  options: UseHandPoseTransitionsOptions\n): UseHandPoseTransitionsReturn {\n  const { currentAnimation, attackAnimation, isBlocking = false } = options;\n\n  // Hand animation states\n  const [leftHandState, setLeftHandState] = useState<HandAnimationState>(\n    createInitialHandAnimationState(HandPoseType.OPEN)\n  );\n  const [rightHandState, setRightHandState] = useState<HandAnimationState>(\n    createInitialHandAnimationState(HandPoseType.OPEN)\n  );\n\n  // Refs for 60fps animation updates without triggering React re-renders\n  const leftHandStateRef = useRef<HandAnimationState>(leftHandState);\n  const rightHandStateRef = useRef<HandAnimationState>(rightHandState);\n\n  // Sync refs with state\n  useEffect(() => {\n    leftHandStateRef.current = leftHandState;\n  }, [leftHandState]);\n\n  useEffect(() => {\n    rightHandStateRef.current = rightHandState;\n  }, [rightHandState]);\n\n  // Update hand poses based on current animation\n  useEffect(() => {\n    if (currentAnimation === \"attack\" && attackAnimation) {\n      // Attack animation - use technique-specific hand poses\n      const handPose = getTechniqueHandPose(attackAnimation);\n      setLeftHandState((prev) =>\n        updateHandAnimationState(\n          prev,\n          handPose.leftHandPose,\n          0,\n          handPose.transitionDuration\n        )\n      );\n      setRightHandState((prev) =>\n        updateHandAnimationState(\n          prev,\n          handPose.rightHandPose,\n          0,\n          handPose.transitionDuration\n        )\n      );\n    } else if (currentAnimation === \"defend\" || isBlocking) {\n      // Open hands for blocking\n      setLeftHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.OPEN, 0, 0.1)\n      );\n      setRightHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.OPEN, 0, 0.1)\n      );\n    } else if (currentAnimation === \"walk\") {\n      // Relaxed hands while walking\n      setLeftHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.RELAXED, 0, 0.2)\n      );\n      setRightHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.RELAXED, 0, 0.2)\n      );\n    } else if (currentAnimation === \"stance_change\") {\n      // Guard hands during stance change\n      setLeftHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.OPEN, 0, 0.15)\n      );\n      setRightHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.OPEN, 0, 0.15)\n      );\n    } else if (\n      currentAnimation?.startsWith(\"step_\") ||\n      currentAnimation?.startsWith(\"footwork_\")\n    ) {\n      // Maintain guard hands during steps and footwork\n      setLeftHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.OPEN, 0, 0.1)\n      );\n      setRightHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.OPEN, 0, 0.1)\n      );\n    } else if (currentAnimation?.startsWith(\"stance_guard_\")) {\n      // Guard hands in open position\n      setLeftHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.OPEN, 0, 0.2)\n      );\n      setRightHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.OPEN, 0, 0.2)\n      );\n    } else {\n      // Idle - return to relaxed hand pose\n      setLeftHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.RELAXED, 0, 0.3)\n      );\n      setRightHandState((prev) =>\n        updateHandAnimationState(prev, HandPoseType.RELAXED, 0, 0.3)\n      );\n    }\n  }, [currentAnimation, attackAnimation, isBlocking]);\n\n  // Update hand animations at 60fps\n  const updateHandAnimations = (delta: number): void => {\n    updateHandAnimationFrame(leftHandStateRef, setLeftHandState, delta);\n    updateHandAnimationFrame(rightHandStateRef, setRightHandState, delta);\n  };\n\n  return {\n    leftHandState,\n    rightHandState,\n    updateHandAnimations,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAyBA,IAAM,mCAAmC;;;;;;;AAQzC,IAAM,4BAA4B;;;;;;;;;;;AAsClC,IAAM,4BACJ,cACA,cACA,UACS;AACT,KAAI,aAAa,WAAW,aAAa,QAAQ,eAAe,MAAM;EACpE,MAAM,gBAAgB,aAAa;EACnC,MAAM,eAAe,yBACnB,eACA,cAAc,YACd,OACA,iCACD;AAED,eAAa,UAAU;AAGvB,MACE,aAAa,eAAe,QAC5B,KAAK,MAAM,aAAa,qBAAqB,0BAA0B,KACrE,KAAK,MACH,cAAc,qBAAqB,0BACpC,CAEH,cAAa,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgChC,SAAgB,uBACd,SAC8B;CAC9B,MAAM,EAAE,kBAAkB,iBAAiB,aAAa,UAAU;CAGlE,MAAM,CAAC,eAAe,oBAAoB,SACxC,gCAAgC,aAAa,KAAK,CACnD;CACD,MAAM,CAAC,gBAAgB,qBAAqB,SAC1C,gCAAgC,aAAa,KAAK,CACnD;CAGD,MAAM,mBAAmB,OAA2B,cAAc;CAClE,MAAM,oBAAoB,OAA2B,eAAe;AAGpE,iBAAgB;AACd,mBAAiB,UAAU;IAC1B,CAAC,cAAc,CAAC;AAEnB,iBAAgB;AACd,oBAAkB,UAAU;IAC3B,CAAC,eAAe,CAAC;AAGpB,iBAAgB;AACd,MAAI,qBAAqB,YAAY,iBAAiB;GAEpD,MAAM,WAAW,qBAAqB,gBAAgB;AACtD,qBAAkB,SAChB,yBACE,MACA,SAAS,cACT,GACA,SAAS,mBACV,CACF;AACD,sBAAmB,SACjB,yBACE,MACA,SAAS,eACT,GACA,SAAS,mBACV,CACF;aACQ,qBAAqB,YAAY,YAAY;AAEtD,qBAAkB,SAChB,yBAAyB,MAAM,aAAa,MAAM,GAAG,GAAI,CAC1D;AACD,sBAAmB,SACjB,yBAAyB,MAAM,aAAa,MAAM,GAAG,GAAI,CAC1D;aACQ,qBAAqB,QAAQ;AAEtC,qBAAkB,SAChB,yBAAyB,MAAM,aAAa,SAAS,GAAG,GAAI,CAC7D;AACD,sBAAmB,SACjB,yBAAyB,MAAM,aAAa,SAAS,GAAG,GAAI,CAC7D;aACQ,qBAAqB,iBAAiB;AAE/C,qBAAkB,SAChB,yBAAyB,MAAM,aAAa,MAAM,GAAG,IAAK,CAC3D;AACD,sBAAmB,SACjB,yBAAyB,MAAM,aAAa,MAAM,GAAG,IAAK,CAC3D;aAED,kBAAkB,WAAW,QAAQ,IACrC,kBAAkB,WAAW,YAAY,EACzC;AAEA,qBAAkB,SAChB,yBAAyB,MAAM,aAAa,MAAM,GAAG,GAAI,CAC1D;AACD,sBAAmB,SACjB,yBAAyB,MAAM,aAAa,MAAM,GAAG,GAAI,CAC1D;aACQ,kBAAkB,WAAW,gBAAgB,EAAE;AAExD,qBAAkB,SAChB,yBAAyB,MAAM,aAAa,MAAM,GAAG,GAAI,CAC1D;AACD,sBAAmB,SACjB,yBAAyB,MAAM,aAAa,MAAM,GAAG,GAAI,CAC1D;SACI;AAEL,qBAAkB,SAChB,yBAAyB,MAAM,aAAa,SAAS,GAAG,GAAI,CAC7D;AACD,sBAAmB,SACjB,yBAAyB,MAAM,aAAa,SAAS,GAAG,GAAI,CAC7D;;IAEF;EAAC;EAAkB;EAAiB;EAAW,CAAC;CAGnD,MAAM,wBAAwB,UAAwB;AACpD,2BAAyB,kBAAkB,kBAAkB,MAAM;AACnE,2BAAyB,mBAAmB,mBAAmB,MAAM;;AAGvE,QAAO;EACL;EACA;EACA;EACD"}

package/lib/hooks/useKeyboardControls.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Custom hook for keyboard controls with visual feedback
+ * Manages keyboard input for trigram stance switching and combat actions
+ *
+ * @module hooks/useKeyboardControls
+ * @category Input System
+ * @korean 키보드 컨트롤 훅
+ */
+/**
+ * Queued input for input buffer display
+ */
+export interface QueuedInput {
+    readonly action: string;
+    readonly key: string;
+    readonly timestamp: number;
+}
+/**
+ * Props for useKeyboardControls hook
+ */
+export interface UseKeyboardControlsProps {
+    /** Callback when stance changes (receives stance index 0-7) */
+    readonly onStanceChange: (stance: number) => void;
+    /** Callback for combat actions (attack, block, etc.) */
+    readonly onAction: (action: string) => void;
+    /** Whether keyboard input is enabled */
+    readonly enabled?: boolean;
+    /** Current stance index (0-7) for validation */
+    readonly currentStance?: number;
+    /** Callback when hints toggle is requested */
+    readonly onToggleHints?: () => void;
+    /** Play sound effect function */
+    readonly playSFX?: (soundId: string) => void;
+    /** Current animation state for grounded detection */
+    readonly currentAnimationState?: string;
+}
+/**
+ * Return type for useKeyboardControls hook
+ */
+export interface UseKeyboardControlsReturn {
+    /** Queued inputs for display */
+    readonly queuedInputs: readonly QueuedInput[];
+    /** Whether hints are visible */
+    readonly showHints: boolean;
+    /** Toggle hints visibility */
+    readonly toggleHints: () => void;
+}
+/**
+ * Custom hook for handling keyboard controls with visual feedback
+ *
+ * Features:
+ * - Trigram stance switching (1-8 keys or custom bindings)
+ * - Combat action handling (attack, block, movement)
+ * - Input queue visualization
+ * - Keyboard hints toggle (F1)
+ * - Invalid input prevention
+ * - Audio feedback integration
+ *
+ * @example
+ * ```typescript
+ * const { queuedInputs, showHints, toggleHints } = useKeyboardControls({
+ *   onStanceChange: (stance) => handleStanceChange(stance),
+ *   onAction: (action) => handleAction(action),
+ *   enabled: !isPaused,
+ *   currentStance: player.stance,
+ *   playSFX: audio.playSFX,
+ * });
+ * ```
+ *
+ * @public
+ * @korean 키보드컨트롤사용
+ */
+export declare function useKeyboardControls({ onStanceChange, onAction, enabled, currentStance, onToggleHints, playSFX, currentAnimationState, }: UseKeyboardControlsProps): UseKeyboardControlsReturn;
+//# sourceMappingURL=useKeyboardControls.d.ts.map

package/lib/hooks/useKeyboardControls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardControls.d.ts","sourceRoot":"","sources":["../../src/hooks/useKeyboardControls.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA2CH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IACpC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,qDAAqD;IACrD,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,gCAAgC;IAChC,QAAQ,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC;CAClC;AAYD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,cAAc,EACd,QAAQ,EACR,OAAc,EACd,aAAiB,EACjB,aAAa,EACb,OAAO,EACP,qBAAqB,GACtB,EAAE,wBAAwB,GAAG,yBAAyB,CAyXtD"}

package/lib/hooks/useKeyboardControls.js

@@ -0,0 +1,311 @@
+import { FOOTWORK_KOREAN_TERMS } from "../systems/animation/core/types.js";
+import { ControlMapper } from "../utils/controlMapping.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+//#region src/hooks/useKeyboardControls.ts
+/**
+* Custom hook for keyboard controls with visual feedback
+* Manages keyboard input for trigram stance switching and combat actions
+*
+* @module hooks/useKeyboardControls
+* @category Input System
+* @korean 키보드 컨트롤 훅
+*/
+var DIAGONAL_KOREAN_TERMS = {
+	step_forward_left: "전좌측보법 (Forward-Left)",
+	step_forward_right: "전우측보법 (Forward-Right)",
+	step_back_left: "후좌측보법 (Back-Left)",
+	step_back_right: "후우측보법 (Back-Right)"
+};
+var STEP_KOREAN_TERMS = {
+	step_forward: "전진보법 (Forward Step)",
+	step_back: "후퇴보법 (Retreat Step)",
+	step_left: "좌측면보법 (Left Step)",
+	step_right: "우측면보법 (Right Step)"
+};
+var FOOTWORK_DISPLAY_TERMS = {
+	footwork_circular_left: `${FOOTWORK_KOREAN_TERMS.circular.korean} 좌 (Circular Left)`,
+	footwork_circular_right: `${FOOTWORK_KOREAN_TERMS.circular.korean} 우 (Circular Right)`,
+	footwork_pivot_left: `${FOOTWORK_KOREAN_TERMS.pivot.korean} 좌 (Pivot Left)`,
+	footwork_pivot_right: `${FOOTWORK_KOREAN_TERMS.pivot.korean} 우 (Pivot Right)`,
+	footwork_slide_forward: `${FOOTWORK_KOREAN_TERMS.slide.korean} 전 (Slide Forward)`,
+	footwork_slide_back: `${FOOTWORK_KOREAN_TERMS.slide.korean} 후 (Slide Back)`,
+	footwork_slide_left: `${FOOTWORK_KOREAN_TERMS.slide.korean} 좌 (Slide Left)`,
+	footwork_slide_right: `${FOOTWORK_KOREAN_TERMS.slide.korean} 우 (Slide Right)`,
+	footwork_shuffle: `${FOOTWORK_KOREAN_TERMS.shuffle.korean} (Shuffle)`
+};
+var STEP_DIRECTION_MAP = {
+	move_up: "step_forward",
+	move_down: "step_back",
+	move_left: "step_left",
+	move_right: "step_right"
+};
+/**
+* Maximum number of inputs to keep in queue
+*/
+var MAX_QUEUE_SIZE = 3;
+/**
+* Time to keep inputs in queue (milliseconds)
+*/
+var QUEUE_RETENTION_TIME = 2e3;
+/**
+* Custom hook for handling keyboard controls with visual feedback
+*
+* Features:
+* - Trigram stance switching (1-8 keys or custom bindings)
+* - Combat action handling (attack, block, movement)
+* - Input queue visualization
+* - Keyboard hints toggle (F1)
+* - Invalid input prevention
+* - Audio feedback integration
+*
+* @example
+* ```typescript
+* const { queuedInputs, showHints, toggleHints } = useKeyboardControls({
+*   onStanceChange: (stance) => handleStanceChange(stance),
+*   onAction: (action) => handleAction(action),
+*   enabled: !isPaused,
+*   currentStance: player.stance,
+*   playSFX: audio.playSFX,
+* });
+* ```
+*
+* @public
+* @korean 키보드컨트롤사용
+*/
+function useKeyboardControls({ onStanceChange, onAction, enabled = true, currentStance = 0, onToggleHints, playSFX, currentAnimationState }) {
+	const [queuedInputs, setQueuedInputs] = useState([]);
+	const [showHints, setShowHints] = useState(false);
+	const controlMapperRef = useRef(new ControlMapper());
+	const lastStanceChangeRef = useRef(0);
+	const pressedKeysRef = useRef(/* @__PURE__ */ new Set());
+	/**
+	* Toggle hints visibility
+	*/
+	const toggleHints = useCallback(() => {
+		setShowHints((prev) => {
+			const newState = !prev;
+			if (onToggleHints) onToggleHints();
+			if (playSFX) playSFX("menu_select");
+			return newState;
+		});
+	}, [onToggleHints, playSFX]);
+	/**
+	* Detect diagonal step direction from pressed keys
+	* Returns step action for diagonal or null if not diagonal
+	*
+	* @korean 대각선발걸음감지
+	*/
+	const getDiagonalStepAction = useCallback(() => {
+		const keys = pressedKeysRef.current;
+		const mapper = controlMapperRef.current;
+		if (keys.has(mapper.getBindings().movement.up.toLowerCase())) {
+			if (keys.has(mapper.getBindings().movement.left.toLowerCase())) return "step_forward_left";
+			if (keys.has(mapper.getBindings().movement.right.toLowerCase())) return "step_forward_right";
+		}
+		if (keys.has(mapper.getBindings().movement.down.toLowerCase())) {
+			if (keys.has(mapper.getBindings().movement.left.toLowerCase())) return "step_back_left";
+			if (keys.has(mapper.getBindings().movement.right.toLowerCase())) return "step_back_right";
+		}
+		return null;
+	}, []);
+	/**
+	* Add input to queue
+	*/
+	const addToQueue = useCallback((action, key) => {
+		const newInput = {
+			action,
+			key,
+			timestamp: Date.now()
+		};
+		setQueuedInputs((prev) => {
+			return [newInput, ...prev].slice(0, MAX_QUEUE_SIZE);
+		});
+	}, []);
+	/**
+	* Clean up old queued inputs
+	* Single interval for component lifetime to avoid recreating on every input
+	*/
+	useEffect(() => {
+		const interval = setInterval(() => {
+			const now = Date.now();
+			setQueuedInputs((prev) => {
+				if (prev.length === 0) return prev;
+				return prev.filter((input) => now - input.timestamp < QUEUE_RETENTION_TIME);
+			});
+		}, 500);
+		return () => clearInterval(interval);
+	}, []);
+	/**
+	* Handle keyboard input
+	*/
+	useEffect(() => {
+		if (!enabled) return;
+		const pressedKeys = pressedKeysRef.current;
+		const handleKeyDown = (e) => {
+			const mapper = controlMapperRef.current;
+			pressedKeysRef.current.add(e.key.toLowerCase());
+			if (e.key === "F1") {
+				e.preventDefault();
+				toggleHints();
+				return;
+			}
+			if (e.key === "Escape" && showHints) {
+				e.preventDefault();
+				setShowHints(false);
+				return;
+			}
+			if (currentAnimationState?.startsWith("ground_")) {
+				if (e.key === " ") {
+					e.preventDefault();
+					onAction("recovery_quick");
+					addToQueue("기상 (Quick Recovery)", "Space");
+					if (playSFX) playSFX("stance_change");
+					return;
+				}
+				if (e.key.toLowerCase() === "r" || e.key === "Enter") {
+					e.preventDefault();
+					onAction("recovery_roll");
+					addToQueue("회전기상 (Roll Recovery)", e.key);
+					if (playSFX) playSFX("stance_change");
+					return;
+				}
+				if (e.shiftKey) {
+					e.preventDefault();
+					onAction("recovery_defensive");
+					addToQueue("방어기상 (Defensive Getup)", "Shift");
+					if (playSFX) playSFX("stance_change");
+					return;
+				}
+				return;
+			}
+			const stanceIndex = mapper.getStanceForKey(e.key);
+			if (stanceIndex !== null) {
+				e.preventDefault();
+				if (stanceIndex === currentStance) {
+					addToQueue(`Stance ${stanceIndex + 1} (already active)`, e.key);
+					if (playSFX) playSFX("menu_error");
+					return;
+				}
+				const now = Date.now();
+				if (now - lastStanceChangeRef.current < 133) return;
+				lastStanceChangeRef.current = now;
+				onStanceChange(stanceIndex);
+				addToQueue(`Stance ${stanceIndex + 1}`, e.key);
+				if (playSFX) playSFX("stance_change");
+				return;
+			}
+			const action = mapper.getActionForKey(e.key);
+			if (action) {
+				e.preventDefault();
+				switch (action) {
+					case "attack":
+						onAction("attack");
+						addToQueue("Attack", e.key);
+						if (playSFX) playSFX("attack_light");
+						break;
+					case "block":
+						onAction("block");
+						addToQueue("Block", e.key);
+						if (playSFX) playSFX("block");
+						break;
+					case "move_up":
+					case "move_down":
+					case "move_left":
+					case "move_right":
+						if (e.altKey) {
+							let slideFootwork = null;
+							if (action === "move_left") slideFootwork = "footwork_slide_left";
+							else if (action === "move_right") slideFootwork = "footwork_slide_right";
+							if (slideFootwork) {
+								onAction(slideFootwork);
+								addToQueue(FOOTWORK_DISPLAY_TERMS[slideFootwork] ?? "Slide Footwork", `Alt+${e.key}`);
+								if (playSFX) playSFX("footstep");
+							}
+						} else if (e.shiftKey && e.ctrlKey) {
+							let advancedFootwork = null;
+							if (action === "move_left") advancedFootwork = "footwork_pivot_left";
+							else if (action === "move_right") advancedFootwork = "footwork_pivot_right";
+							else if (action === "move_up" || action === "move_down") advancedFootwork = "footwork_shuffle";
+							if (advancedFootwork) {
+								onAction(advancedFootwork);
+								addToQueue(FOOTWORK_DISPLAY_TERMS[advancedFootwork] ?? "Advanced Footwork", `Shift+Ctrl+${e.key}`);
+								if (playSFX) playSFX("footstep");
+							}
+						} else if (e.ctrlKey) {
+							let footworkAction = null;
+							if (action === "move_left") footworkAction = "footwork_circular_left";
+							else if (action === "move_right") footworkAction = "footwork_circular_right";
+							else if (action === "move_up") footworkAction = "footwork_slide_forward";
+							else if (action === "move_down") footworkAction = "footwork_slide_back";
+							if (footworkAction) {
+								onAction(footworkAction);
+								addToQueue(FOOTWORK_DISPLAY_TERMS[footworkAction] ?? "Footwork", `Ctrl+${e.key}`);
+								if (playSFX) playSFX("footstep");
+							}
+						} else if (e.shiftKey) {
+							const diagonalStep = getDiagonalStepAction();
+							if (diagonalStep) {
+								onAction(diagonalStep);
+								addToQueue(DIAGONAL_KOREAN_TERMS[diagonalStep] ?? "Diagonal Step", `Shift+${e.key}`);
+								if (playSFX) playSFX("footstep");
+							} else {
+								const stepDirection = STEP_DIRECTION_MAP[action];
+								onAction(stepDirection);
+								addToQueue(STEP_KOREAN_TERMS[stepDirection] ?? "Step", `Shift+${e.key}`);
+								if (playSFX) playSFX("footstep");
+							}
+						} else {
+							onAction(action);
+							addToQueue(action, e.key);
+						}
+						break;
+					case "stance_side_switch":
+						onAction("stance_side_switch");
+						addToQueue("발 바꿈 (Switch Stance Side)", e.key);
+						if (playSFX) playSFX("stance_change");
+						break;
+					case "vital_points_overlay":
+						onAction("vital_points_overlay");
+						addToQueue("Vital Points", e.key);
+						if (playSFX) playSFX("menu_select");
+						break;
+					case "pause":
+						onAction("pause");
+						addToQueue("Pause", e.key);
+						if (playSFX) playSFX("menu_select");
+						break;
+				}
+			}
+		};
+		const handleKeyUp = (e) => {
+			pressedKeysRef.current.delete(e.key.toLowerCase());
+		};
+		window.addEventListener("keydown", handleKeyDown);
+		window.addEventListener("keyup", handleKeyUp);
+		return () => {
+			window.removeEventListener("keydown", handleKeyDown);
+			window.removeEventListener("keyup", handleKeyUp);
+			pressedKeys.clear();
+		};
+	}, [
+		enabled,
+		currentStance,
+		onStanceChange,
+		onAction,
+		addToQueue,
+		toggleHints,
+		getDiagonalStepAction,
+		showHints,
+		playSFX,
+		currentAnimationState
+	]);
+	return {
+		queuedInputs,
+		showHints,
+		toggleHints
+	};
+}
+//#endregion
+export { useKeyboardControls };
+
+//# sourceMappingURL=useKeyboardControls.js.map

package/lib/hooks/useKeyboardControls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardControls.js","names":[],"sources":["../../src/hooks/useKeyboardControls.ts"],"sourcesContent":["/**\n * Custom hook for keyboard controls with visual feedback\n * Manages keyboard input for trigram stance switching and combat actions\n *\n * @module hooks/useKeyboardControls\n * @category Input System\n * @korean 키보드 컨트롤 훅\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\nimport { FOOTWORK_KOREAN_TERMS } from \"../systems/animation/core/types\";\nimport { ControlMapper } from \"../utils/controlMapping\";\n\n// Korean terminology constants (module-level to avoid recreation on every keystroke)\nconst DIAGONAL_KOREAN_TERMS: Record<string, string> = {\n  step_forward_left: \"전좌측보법 (Forward-Left)\",\n  step_forward_right: \"전우측보법 (Forward-Right)\",\n  step_back_left: \"후좌측보법 (Back-Left)\",\n  step_back_right: \"후우측보법 (Back-Right)\",\n};\n\nconst STEP_KOREAN_TERMS: Record<string, string> = {\n  step_forward: \"전진보법 (Forward Step)\",\n  step_back: \"후퇴보법 (Retreat Step)\",\n  step_left: \"좌측면보법 (Left Step)\",\n  step_right: \"우측면보법 (Right Step)\",\n};\n\n// Footwork pattern Korean terminology - maps animation states to display names\n// Reuses FOOTWORK_KOREAN_TERMS from types.ts but adds specific animation state labels\nconst FOOTWORK_DISPLAY_TERMS: Record<string, string> = {\n  footwork_circular_left: `${FOOTWORK_KOREAN_TERMS.circular.korean} 좌 (Circular Left)`,\n  footwork_circular_right: `${FOOTWORK_KOREAN_TERMS.circular.korean} 우 (Circular Right)`,\n  footwork_pivot_left: `${FOOTWORK_KOREAN_TERMS.pivot.korean} 좌 (Pivot Left)`,\n  footwork_pivot_right: `${FOOTWORK_KOREAN_TERMS.pivot.korean} 우 (Pivot Right)`,\n  footwork_slide_forward: `${FOOTWORK_KOREAN_TERMS.slide.korean} 전 (Slide Forward)`,\n  footwork_slide_back: `${FOOTWORK_KOREAN_TERMS.slide.korean} 후 (Slide Back)`,\n  footwork_slide_left: `${FOOTWORK_KOREAN_TERMS.slide.korean} 좌 (Slide Left)`,\n  footwork_slide_right: `${FOOTWORK_KOREAN_TERMS.slide.korean} 우 (Slide Right)`,\n  footwork_shuffle: `${FOOTWORK_KOREAN_TERMS.shuffle.korean} (Shuffle)`,\n};\n\n// Step direction mapping (all move_* actions covered explicitly)\nconst STEP_DIRECTION_MAP: Record<string, string> = {\n  move_up: \"step_forward\",\n  move_down: \"step_back\",\n  move_left: \"step_left\",\n  move_right: \"step_right\",\n};\n\n/**\n * Queued input for input buffer display\n */\nexport interface QueuedInput {\n  readonly action: string;\n  readonly key: string;\n  readonly timestamp: number;\n}\n\n/**\n * Props for useKeyboardControls hook\n */\nexport interface UseKeyboardControlsProps {\n  /** Callback when stance changes (receives stance index 0-7) */\n  readonly onStanceChange: (stance: number) => void;\n  /** Callback for combat actions (attack, block, etc.) */\n  readonly onAction: (action: string) => void;\n  /** Whether keyboard input is enabled */\n  readonly enabled?: boolean;\n  /** Current stance index (0-7) for validation */\n  readonly currentStance?: number;\n  /** Callback when hints toggle is requested */\n  readonly onToggleHints?: () => void;\n  /** Play sound effect function */\n  readonly playSFX?: (soundId: string) => void;\n  /** Current animation state for grounded detection */\n  readonly currentAnimationState?: string;\n}\n\n/**\n * Return type for useKeyboardControls hook\n */\nexport interface UseKeyboardControlsReturn {\n  /** Queued inputs for display */\n  readonly queuedInputs: readonly QueuedInput[];\n  /** Whether hints are visible */\n  readonly showHints: boolean;\n  /** Toggle hints visibility */\n  readonly toggleHints: () => void;\n}\n\n/**\n * Maximum number of inputs to keep in queue\n */\nconst MAX_QUEUE_SIZE = 3;\n\n/**\n * Time to keep inputs in queue (milliseconds)\n */\nconst QUEUE_RETENTION_TIME = 2000;\n\n/**\n * Custom hook for handling keyboard controls with visual feedback\n *\n * Features:\n * - Trigram stance switching (1-8 keys or custom bindings)\n * - Combat action handling (attack, block, movement)\n * - Input queue visualization\n * - Keyboard hints toggle (F1)\n * - Invalid input prevention\n * - Audio feedback integration\n *\n * @example\n * ```typescript\n * const { queuedInputs, showHints, toggleHints } = useKeyboardControls({\n *   onStanceChange: (stance) => handleStanceChange(stance),\n *   onAction: (action) => handleAction(action),\n *   enabled: !isPaused,\n *   currentStance: player.stance,\n *   playSFX: audio.playSFX,\n * });\n * ```\n *\n * @public\n * @korean 키보드컨트롤사용\n */\nexport function useKeyboardControls({\n  onStanceChange,\n  onAction,\n  enabled = true,\n  currentStance = 0,\n  onToggleHints,\n  playSFX,\n  currentAnimationState,\n}: UseKeyboardControlsProps): UseKeyboardControlsReturn {\n  const [queuedInputs, setQueuedInputs] = useState<readonly QueuedInput[]>([]);\n  const [showHints, setShowHints] = useState(false);\n  const controlMapperRef = useRef<ControlMapper>(new ControlMapper());\n  const lastStanceChangeRef = useRef<number>(0);\n\n  // Track currently pressed keys for diagonal step detection\n  const pressedKeysRef = useRef<Set<string>>(new Set());\n\n  /**\n   * Toggle hints visibility\n   */\n  const toggleHints = useCallback(() => {\n    setShowHints((prev) => {\n      const newState = !prev;\n      if (onToggleHints) {\n        onToggleHints();\n      }\n      // Play UI sound\n      if (playSFX) {\n        playSFX(\"menu_select\");\n      }\n      return newState;\n    });\n  }, [onToggleHints, playSFX]);\n\n  /**\n   * Detect diagonal step direction from pressed keys\n   * Returns step action for diagonal or null if not diagonal\n   *\n   * @korean 대각선발걸음감지\n   */\n  const getDiagonalStepAction = useCallback((): string | null => {\n    const keys = pressedKeysRef.current;\n    const mapper = controlMapperRef.current;\n\n    // Check for forward diagonals\n    if (keys.has(mapper.getBindings().movement.up.toLowerCase())) {\n      if (keys.has(mapper.getBindings().movement.left.toLowerCase())) {\n        return \"step_forward_left\"; // 전좌측보법\n      }\n      if (keys.has(mapper.getBindings().movement.right.toLowerCase())) {\n        return \"step_forward_right\"; // 전우측보법\n      }\n    }\n\n    // Check for backward diagonals\n    if (keys.has(mapper.getBindings().movement.down.toLowerCase())) {\n      if (keys.has(mapper.getBindings().movement.left.toLowerCase())) {\n        return \"step_back_left\"; // 후좌측보법\n      }\n      if (keys.has(mapper.getBindings().movement.right.toLowerCase())) {\n        return \"step_back_right\"; // 후우측보법\n      }\n    }\n\n    return null;\n  }, []);\n\n  /**\n   * Add input to queue\n   */\n  const addToQueue = useCallback((action: string, key: string) => {\n    const newInput: QueuedInput = {\n      action,\n      key,\n      timestamp: Date.now(),\n    };\n\n    setQueuedInputs((prev) => {\n      const updated = [newInput, ...prev].slice(0, MAX_QUEUE_SIZE);\n      return updated;\n    });\n  }, []);\n\n  /**\n   * Clean up old queued inputs\n   * Single interval for component lifetime to avoid recreating on every input\n   */\n  useEffect(() => {\n    const interval = setInterval(() => {\n      const now = Date.now();\n      setQueuedInputs((prev) => {\n        if (prev.length === 0) return prev;\n        return prev.filter(\n          (input) => now - input.timestamp < QUEUE_RETENTION_TIME\n        );\n      });\n    }, 500);\n\n    return () => clearInterval(interval);\n  }, []); // Empty deps - single interval for component lifetime\n\n  /**\n   * Handle keyboard input\n   */\n  useEffect(() => {\n    if (!enabled) return;\n\n    // Copy ref value for cleanup\n    const pressedKeys = pressedKeysRef.current;\n\n    const handleKeyDown = (e: KeyboardEvent) => {\n      const mapper = controlMapperRef.current;\n\n      // Track pressed keys for diagonal detection\n      pressedKeysRef.current.add(e.key.toLowerCase());\n\n      // F1: Toggle hints (prevent default browser help)\n      if (e.key === \"F1\") {\n        e.preventDefault();\n        toggleHints();\n        return;\n      }\n\n      // Escape: Close hints if open\n      if (e.key === \"Escape\" && showHints) {\n        e.preventDefault();\n        setShowHints(false);\n        return;\n      }\n\n      // Recovery input detection (기상 입력 감지)\n      // When player is in ground state, any button triggers recovery options\n      const isGrounded = currentAnimationState?.startsWith(\"ground_\");\n\n      if (isGrounded) {\n        // Space: Quick/default recovery\n        if (e.key === \" \") {\n          e.preventDefault();\n          onAction(\"recovery_quick\");\n          addToQueue(\"기상 (Quick Recovery)\", \"Space\");\n          if (playSFX) playSFX(\"stance_change\");\n          return;\n        }\n\n        // R or Enter: Roll recovery (회전기상) - fast but costs stamina\n        if (e.key.toLowerCase() === \"r\" || e.key === \"Enter\") {\n          e.preventDefault();\n          onAction(\"recovery_roll\");\n          addToQueue(\"회전기상 (Roll Recovery)\", e.key);\n          if (playSFX) playSFX(\"stance_change\");\n          return;\n        }\n\n        // Shift: Defensive getup (방어기상) - slow but protected\n        if (e.shiftKey) {\n          e.preventDefault();\n          onAction(\"recovery_defensive\");\n          addToQueue(\"방어기상 (Defensive Getup)\", \"Shift\");\n          if (playSFX) playSFX(\"stance_change\");\n          return;\n        }\n\n        // If grounded, don't process other inputs (can't attack/move while down)\n        return;\n      }\n\n      // Check for stance change (1-8 or custom bindings)\n      const stanceIndex = mapper.getStanceForKey(e.key);\n      if (stanceIndex !== null) {\n        e.preventDefault();\n\n        // Prevent switching to the same stance\n        if (stanceIndex === currentStance) {\n          // Invalid input feedback (shake animation trigger)\n          addToQueue(`Stance ${stanceIndex + 1} (already active)`, e.key);\n\n          // Play error sound\n          if (playSFX) {\n            playSFX(\"menu_error\");\n          }\n          return;\n        }\n\n        // Throttle stance changes (minimum 8 frames at 60fps = 133ms)\n        const now = Date.now();\n        if (now - lastStanceChangeRef.current < 133) {\n          return;\n        }\n        lastStanceChangeRef.current = now;\n\n        // Execute stance change\n        onStanceChange(stanceIndex);\n        addToQueue(`Stance ${stanceIndex + 1}`, e.key);\n\n        // Play stance change sound\n        if (playSFX) {\n          playSFX(\"stance_change\");\n        }\n        return;\n      }\n\n      // Handle other actions\n      const action = mapper.getActionForKey(e.key);\n      if (action) {\n        e.preventDefault();\n\n        switch (action) {\n          case \"attack\":\n            onAction(\"attack\");\n            addToQueue(\"Attack\", e.key);\n            if (playSFX) playSFX(\"attack_light\");\n            break;\n\n          case \"block\":\n            onAction(\"block\");\n            addToQueue(\"Block\", e.key);\n            if (playSFX) playSFX(\"block\");\n            break;\n\n          case \"move_up\":\n          case \"move_down\":\n          case \"move_left\":\n          case \"move_right\":\n            // Check for Alt+A/D modifier for slide left/right (MUST be checked first)\n            if (e.altKey) {\n              // Alt modifier for slide left/right footwork patterns\n              let slideFootwork: string | null = null;\n\n              if (action === \"move_left\") {\n                // Alt+A: Slide left (미끄럼보 좌)\n                slideFootwork = \"footwork_slide_left\";\n              } else if (action === \"move_right\") {\n                // Alt+D: Slide right (미끄럼보 우)\n                slideFootwork = \"footwork_slide_right\";\n              }\n\n              if (slideFootwork) {\n                onAction(slideFootwork);\n                addToQueue(\n                  FOOTWORK_DISPLAY_TERMS[slideFootwork] ?? \"Slide Footwork\",\n                  `Alt+${e.key}`\n                );\n                if (playSFX) playSFX(\"footstep\");\n              }\n            } else if (e.shiftKey && e.ctrlKey) {\n              // Shift+Ctrl modifier for advanced footwork patterns\n              let advancedFootwork: string | null = null;\n\n              if (action === \"move_left\") {\n                // Shift+Ctrl+A: Pivot left (축족회전 좌)\n                advancedFootwork = \"footwork_pivot_left\";\n              } else if (action === \"move_right\") {\n                // Shift+Ctrl+D: Pivot right (축족회전 우)\n                advancedFootwork = \"footwork_pivot_right\";\n              } else if (action === \"move_up\" || action === \"move_down\") {\n                // Shift+Ctrl+W or Shift+Ctrl+S: Shuffle step (섞음보)\n                advancedFootwork = \"footwork_shuffle\";\n              }\n\n              if (advancedFootwork) {\n                onAction(advancedFootwork);\n                addToQueue(\n                  FOOTWORK_DISPLAY_TERMS[advancedFootwork] ??\n                    \"Advanced Footwork\",\n                  `Shift+Ctrl+${e.key}`\n                );\n                if (playSFX) playSFX(\"footstep\");\n              }\n            } else if (e.ctrlKey) {\n              // Footwork patterns with Ctrl+WASD\n              let footworkAction: string | null = null;\n\n              if (action === \"move_left\") {\n                // Ctrl+A: Circular step left (원형보)\n                footworkAction = \"footwork_circular_left\";\n              } else if (action === \"move_right\") {\n                // Ctrl+D: Circular step right (원형보)\n                footworkAction = \"footwork_circular_right\";\n              } else if (action === \"move_up\") {\n                // Ctrl+W: Slide forward (미끄럼보)\n                footworkAction = \"footwork_slide_forward\";\n              } else if (action === \"move_down\") {\n                // Ctrl+S: Slide back (미끄럼보)\n                footworkAction = \"footwork_slide_back\";\n              }\n\n              if (footworkAction) {\n                onAction(footworkAction);\n                addToQueue(\n                  FOOTWORK_DISPLAY_TERMS[footworkAction] ?? \"Footwork\",\n                  `Ctrl+${e.key}`\n                );\n                if (playSFX) playSFX(\"footstep\");\n              }\n            } else if (e.shiftKey) {\n              // Check if Shift is held for tactical step instead of walk\n              // Check for diagonal step first\n              const diagonalStep = getDiagonalStepAction();\n\n              if (diagonalStep) {\n                // Diagonal tactical step\n                onAction(diagonalStep);\n\n                addToQueue(\n                  DIAGONAL_KOREAN_TERMS[diagonalStep] ?? \"Diagonal Step\",\n                  `Shift+${e.key}`\n                );\n\n                if (playSFX) playSFX(\"footstep\");\n              } else {\n                // Cardinal direction tactical step\n                // Map move_up/move_down to step_forward/step_back to match AnimationState\n                const stepDirection = STEP_DIRECTION_MAP[action];\n                onAction(stepDirection);\n\n                addToQueue(\n                  STEP_KOREAN_TERMS[stepDirection] ?? \"Step\",\n                  `Shift+${e.key}`\n                );\n\n                if (playSFX) playSFX(\"footstep\");\n              }\n            } else {\n              // Regular movement\n              onAction(action);\n              addToQueue(action, e.key);\n            }\n            break;\n\n          case \"stance_side_switch\":\n            // H key: Switch front foot (stance side switch)\n            onAction(\"stance_side_switch\");\n            addToQueue(\"발 바꿈 (Switch Stance Side)\", e.key);\n            if (playSFX) playSFX(\"stance_change\");\n            break;\n\n          case \"vital_points_overlay\":\n            // Vital points overlay toggle\n            onAction(\"vital_points_overlay\");\n            addToQueue(\"Vital Points\", e.key);\n            if (playSFX) playSFX(\"menu_select\");\n            break;\n\n          case \"pause\":\n            // Pause menu toggle\n            onAction(\"pause\");\n            addToQueue(\"Pause\", e.key);\n            if (playSFX) playSFX(\"menu_select\");\n            break;\n        }\n      }\n    };\n\n    const handleKeyUp = (e: KeyboardEvent) => {\n      // Remove key from pressed keys set\n      pressedKeysRef.current.delete(e.key.toLowerCase());\n    };\n\n    window.addEventListener(\"keydown\", handleKeyDown);\n    window.addEventListener(\"keyup\", handleKeyUp);\n\n    return () => {\n      window.removeEventListener(\"keydown\", handleKeyDown);\n      window.removeEventListener(\"keyup\", handleKeyUp);\n      // Clear pressed keys on cleanup using copied ref value\n      pressedKeys.clear();\n    };\n  }, [\n    enabled,\n    currentStance,\n    onStanceChange,\n    onAction,\n    addToQueue,\n    toggleHints,\n    getDiagonalStepAction,\n    showHints,\n    playSFX,\n    currentAnimationState,\n  ]);\n\n  return {\n    queuedInputs,\n    showHints,\n    toggleHints,\n  };\n}\n"],"mappings":"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"}

package/lib/hooks/useMatchCountdown.d.ts

@@ -0,0 +1,87 @@
+/**
+ * useMatchCountdown Hook - Manages match start countdown sequence
+ *
+ * Korean: 매치 시작 카운트다운 훅 (Match Start Countdown Hook)
+ *
+ * Handles the state machine for match start countdown:
+ * - idle: Waiting to start
+ * - ready: Showing "Ready?" message
+ * - counting: Counting down "3... 2... 1..."
+ * - fight: Showing "Fight!" announcement
+ * - complete: Countdown finished, combat can begin
+ *
+ * @module hooks/useMatchCountdown
+ * @category Combat Hooks
+ */
+/**
+ * Match countdown states
+ *
+ * Korean: 매치 카운트다운 상태
+ */
+export type MatchCountdownState = "idle" | "ready" | "counting" | "fight" | "complete";
+/**
+ * Match countdown configuration
+ */
+export interface MatchCountdownConfig {
+    /** Duration of "Ready?" display in seconds */
+    readonly readyDuration?: number;
+    /** Duration of each countdown number in seconds */
+    readonly countdownInterval?: number;
+    /** Duration of "Fight!" display in seconds */
+    readonly fightDuration?: number;
+    /** Starting countdown number */
+    readonly startNumber?: number;
+}
+/**
+ * Match countdown hook state
+ */
+export interface UseMatchCountdownResult {
+    /** Current countdown state */
+    readonly state: MatchCountdownState;
+    /** Current countdown number (3, 2, 1, or 0) */
+    readonly currentNumber: number;
+    /** Start countdown sequence */
+    readonly startCountdown: () => void;
+    /** Skip countdown and proceed immediately */
+    readonly skipCountdown: () => void;
+    /** Reset countdown to idle state */
+    readonly resetCountdown: () => void;
+    /** Whether countdown is in progress */
+    readonly isActive: boolean;
+}
+/**
+ * useMatchCountdown Hook
+ *
+ * Manages the complete match start countdown flow:
+ * 1. Idle state waiting for match start
+ * 2. Ready state shows "Ready?" message (1s)
+ * 3. Counting state counts down from 3 to 1 (1s intervals)
+ * 4. Fight state shows "Fight!" message (1s)
+ * 5. Complete state signals combat can begin
+ *
+ * @param config - Configuration for countdown timings
+ * @param onComplete - Callback when countdown completes
+ * @returns Match countdown state and control functions
+ *
+ * @example
+ * ```typescript
+ * const {
+ *   state,
+ *   currentNumber,
+ *   startCountdown,
+ *   skipCountdown,
+ * } = useMatchCountdown(
+ *   { startNumber: 3 },
+ *   () => {
+ *     // Enable combat inputs
+ *     enableCombatControls();
+ *   }
+ * );
+ *
+ * // When match initializes
+ * startCountdown();
+ * ```
+ */
+export declare function useMatchCountdown(config?: MatchCountdownConfig, onComplete?: () => void): UseMatchCountdownResult;
+export default useMatchCountdown;
+//# sourceMappingURL=useMatchCountdown.d.ts.map

package/lib/hooks/useMatchCountdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMatchCountdown.d.ts","sourceRoot":"","sources":["../../src/hooks/useMatchCountdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN,OAAO,GACP,UAAU,GACV,OAAO,GACP,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,gCAAgC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC;IACnC,oCAAoC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC;IACpC,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,oBAAyB,EACjC,UAAU,CAAC,EAAE,MAAM,IAAI,GACtB,uBAAuB,CA0HzB;AAED,eAAe,iBAAiB,CAAC"}