blacktrigram 0.7.2

package/lib/hooks/useThrottle.js

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
+//#region src/hooks/useThrottle.ts
+/**
+* useThrottle Hook
+* 
+* Throttles a function to execute at most once per specified interval.
+* Useful for high-frequency events like scroll, resize, or touch move.
+* 
+* Uses a ref pattern to ensure the latest callback is always called
+* without recreating the throttled function on every render.
+* 
+* @module hooks/useThrottle
+* @category Performance
+* @korean 쓰로틀 훅
+*/
+/**
+* Hook to throttle a callback function
+* 
+* @param callback - Function to throttle
+* @param delay - Minimum delay between executions in milliseconds
+* @returns Throttled function
+* 
+* @example
+* ```tsx
+* const handleTouchMove = useThrottle((event: TouchEvent) => {
+*   // Handle touch move
+* }, 16); // ~60fps
+* ```
+*/
+function useThrottle(callback, delay) {
+	const lastRunRef = useRef(0);
+	const timeoutRef = useRef(null);
+	const callbackRef = useRef(callback);
+	useLayoutEffect(() => {
+		callbackRef.current = callback;
+	});
+	useEffect(() => {
+		return () => {
+			if (timeoutRef.current) clearTimeout(timeoutRef.current);
+		};
+	}, []);
+	return useCallback((...args) => {
+		const now = Date.now();
+		const timeSinceLastRun = now - lastRunRef.current;
+		if (timeSinceLastRun >= delay) {
+			lastRunRef.current = now;
+			callbackRef.current(...args);
+		} else if (!timeoutRef.current) {
+			const timeUntilNext = delay - timeSinceLastRun;
+			timeoutRef.current = setTimeout(() => {
+				lastRunRef.current = Date.now();
+				timeoutRef.current = null;
+				callbackRef.current(...args);
+			}, timeUntilNext);
+		}
+	}, [delay]);
+}
+//#endregion
+export { useThrottle as default };
+
+//# sourceMappingURL=useThrottle.js.map

package/lib/hooks/useThrottle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThrottle.js","names":[],"sources":["../../src/hooks/useThrottle.ts"],"sourcesContent":["/**\n * useThrottle Hook\n * \n * Throttles a function to execute at most once per specified interval.\n * Useful for high-frequency events like scroll, resize, or touch move.\n * \n * Uses a ref pattern to ensure the latest callback is always called\n * without recreating the throttled function on every render.\n * \n * @module hooks/useThrottle\n * @category Performance\n * @korean 쓰로틀 훅\n */\n\nimport { useCallback, useRef, useLayoutEffect, useEffect } from 'react';\n\n/**\n * Hook to throttle a callback function\n * \n * @param callback - Function to throttle\n * @param delay - Minimum delay between executions in milliseconds\n * @returns Throttled function\n * \n * @example\n * ```tsx\n * const handleTouchMove = useThrottle((event: TouchEvent) => {\n *   // Handle touch move\n * }, 16); // ~60fps\n * ```\n */\nexport function useThrottle<T extends (...args: never[]) => void>(\n  callback: T,\n  delay: number\n): T {\n  const lastRunRef = useRef<number>(0);\n  const timeoutRef = useRef<NodeJS.Timeout | null>(null);\n  const callbackRef = useRef(callback);\n  \n  // Keep callback ref up to date\n  useLayoutEffect(() => {\n    callbackRef.current = callback;\n  });\n\n  // Cleanup pending timeout on unmount\n  useEffect(() => {\n    return () => {\n      if (timeoutRef.current) {\n        clearTimeout(timeoutRef.current);\n      }\n    };\n  }, []);\n\n  return useCallback(\n    (...args: Parameters<T>) => {\n      const now = Date.now();\n      const timeSinceLastRun = now - lastRunRef.current;\n\n      if (timeSinceLastRun >= delay) {\n        // Execute immediately if enough time has passed\n        lastRunRef.current = now;\n        callbackRef.current(...args);\n      } else if (!timeoutRef.current) {\n        // Schedule execution for later\n        const timeUntilNext = delay - timeSinceLastRun;\n        timeoutRef.current = setTimeout(() => {\n          lastRunRef.current = Date.now();\n          timeoutRef.current = null;\n          callbackRef.current(...args);\n        }, timeUntilNext);\n      }\n    },\n    [delay]\n  ) as T;\n}\n\nexport default useThrottle;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,YACd,UACA,OACG;CACH,MAAM,aAAa,OAAe,EAAE;CACpC,MAAM,aAAa,OAA8B,KAAK;CACtD,MAAM,cAAc,OAAO,SAAS;AAGpC,uBAAsB;AACpB,cAAY,UAAU;GACtB;AAGF,iBAAgB;AACd,eAAa;AACX,OAAI,WAAW,QACb,cAAa,WAAW,QAAQ;;IAGnC,EAAE,CAAC;AAEN,QAAO,aACJ,GAAG,SAAwB;EAC1B,MAAM,MAAM,KAAK,KAAK;EACtB,MAAM,mBAAmB,MAAM,WAAW;AAE1C,MAAI,oBAAoB,OAAO;AAE7B,cAAW,UAAU;AACrB,eAAY,QAAQ,GAAG,KAAK;aACnB,CAAC,WAAW,SAAS;GAE9B,MAAM,gBAAgB,QAAQ;AAC9B,cAAW,UAAU,iBAAiB;AACpC,eAAW,UAAU,KAAK,KAAK;AAC/B,eAAW,UAAU;AACrB,gBAAY,QAAQ,GAAG,KAAK;MAC3B,cAAc;;IAGrB,CAAC,MAAM,CACR"}

package/lib/hooks/useTouchControls.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Touch Controls Hook
+ *
+ * Manages touch event handling and gesture recognition for mobile gameplay
+ * Provides swipe detection, multi-touch support, and touch-based movement
+ *
+ * @module hooks/useTouchControls
+ * @category Mobile Controls
+ * @korean 터치 컨트롤 훅
+ */
+/**
+ * Gesture types supported by the touch control system
+ *
+ * Added tactical step gestures for Korean martial arts footwork:
+ * - tap-{direction}: Quick tap for tactical 30cm step
+ * - hold-{direction}: Hold for continuous walk
+ *
+ * @korean 제스처타입
+ */
+export type GestureType = 'swipe-right' | 'swipe-left' | 'swipe-up' | 'swipe-down' | 'two-finger-tap' | 'tap' | 'tap-forward' | 'tap-back' | 'tap-left' | 'tap-right' | 'tap-forward-left' | 'tap-forward-right' | 'tap-back-left' | 'tap-back-right' | 'hold-forward' | 'hold-back' | 'hold-left' | 'hold-right';
+/**
+ * Gesture event data
+ */
+export interface GestureEvent {
+    /** Type of gesture detected */
+    readonly type: GestureType;
+    /** Distance of swipe in pixels (for swipe gestures) */
+    readonly distance?: number;
+    /** Coordinates of touch start */
+    readonly startX?: number;
+    readonly startY?: number;
+    /** Coordinates of touch end */
+    readonly endX?: number;
+    readonly endY?: number;
+}
+/**
+ * Props for useTouchControls hook
+ */
+export interface UseTouchControlsProps {
+    /** Callback when gesture is detected */
+    readonly onGesture: (gesture: GestureEvent) => void;
+    /** Whether touch input is enabled */
+    readonly enabled?: boolean;
+    /** Minimum swipe distance in pixels (default: 50) */
+    readonly minSwipeDistance?: number;
+    /** Maximum time for tap in ms (default: 300) */
+    readonly maxTapDuration?: number;
+    /** Time threshold for hold vs tap in ms (default: 200) */
+    readonly holdThreshold?: number;
+    /** Enable haptic feedback for steps (default: true) */
+    readonly enableHaptics?: boolean;
+}
+/**
+ * Return type for useTouchControls hook
+ */
+export interface UseTouchControlsReturn {
+    /** Whether a touch is currently active */
+    readonly isTouching: boolean;
+}
+/**
+ * Custom hook for handling touch controls and gesture recognition
+ *
+ * Features:
+ * - Swipe detection (horizontal and vertical)
+ * - Two-finger tap detection for vital point mode
+ * - Single tap detection
+ * - Tactical step gestures (tap) vs continuous walk (hold)
+ * - Distance calculation for swipe intensity
+ * - Configurable thresholds
+ * - Haptic feedback for tactical steps
+ *
+ * Gesture Mapping:
+ * - Swipe Right: Advance toward opponent
+ * - Swipe Left: Retreat from opponent
+ * - Swipe Up: High stance mode
+ * - Swipe Down: Low stance mode
+ * - Two-Finger Tap: Activate vital point targeting mode
+ * - Single Tap (directional): Tactical 30cm step (전술적 발걸음)
+ * - Hold (directional): Continuous walk movement
+ *
+ * @example
+ * ```typescript
+ * const { isTouching } = useTouchControls({
+ *   onGesture: (gesture) => {
+ *     switch (gesture.type) {
+ *       case 'tap-forward':
+ *         handleTacticalStep('forward'); // 전진보법
+ *         break;
+ *       case 'hold-forward':
+ *         handleContinuousWalk('forward');
+ *         break;
+ *       case 'two-finger-tap':
+ *         activateVitalPointMode();
+ *         break;
+ *     }
+ *   },
+ *   enabled: !isPaused,
+ *   holdThreshold: 200, // 200ms to distinguish tap from hold
+ *   enableHaptics: true,
+ * });
+ * ```
+ *
+ * @public
+ * @korean 터치컨트롤사용
+ */
+export declare function useTouchControls({ onGesture, enabled, minSwipeDistance, maxTapDuration, holdThreshold, enableHaptics, }: UseTouchControlsProps): UseTouchControlsReturn;
+//# sourceMappingURL=useTouchControls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useTouchControls.d.ts","sourceRoot":"","sources":["../../src/hooks/useTouchControls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GACnB,aAAa,GACb,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,gBAAgB,GAChB,KAAK,GACL,aAAa,GACb,UAAU,GACV,UAAU,GACV,WAAW,GACX,kBAAkB,GAClB,mBAAmB,GACnB,eAAe,GACf,gBAAgB,GAChB,cAAc,GACd,WAAW,GACX,WAAW,GACX,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IACpD,qCAAqC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,uDAAuD;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,SAAS,EACT,OAAc,EACd,gBAAqB,EACrB,cAAoB,EACpB,aAAmB,EACnB,aAAoB,GACrB,EAAE,qBAAqB,GAAG,sBAAsB,CAyRhD"}

package/lib/hooks/useTouchControls.js

@@ -0,0 +1,260 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+//#region src/hooks/useTouchControls.ts
+/**
+* Touch Controls Hook
+* 
+* Manages touch event handling and gesture recognition for mobile gameplay
+* Provides swipe detection, multi-touch support, and touch-based movement
+* 
+* @module hooks/useTouchControls
+* @category Mobile Controls
+* @korean 터치 컨트롤 훅
+*/
+/**
+* Custom hook for handling touch controls and gesture recognition
+* 
+* Features:
+* - Swipe detection (horizontal and vertical)
+* - Two-finger tap detection for vital point mode
+* - Single tap detection
+* - Tactical step gestures (tap) vs continuous walk (hold)
+* - Distance calculation for swipe intensity
+* - Configurable thresholds
+* - Haptic feedback for tactical steps
+* 
+* Gesture Mapping:
+* - Swipe Right: Advance toward opponent
+* - Swipe Left: Retreat from opponent
+* - Swipe Up: High stance mode
+* - Swipe Down: Low stance mode
+* - Two-Finger Tap: Activate vital point targeting mode
+* - Single Tap (directional): Tactical 30cm step (전술적 발걸음)
+* - Hold (directional): Continuous walk movement
+* 
+* @example
+* ```typescript
+* const { isTouching } = useTouchControls({
+*   onGesture: (gesture) => {
+*     switch (gesture.type) {
+*       case 'tap-forward':
+*         handleTacticalStep('forward'); // 전진보법
+*         break;
+*       case 'hold-forward':
+*         handleContinuousWalk('forward');
+*         break;
+*       case 'two-finger-tap':
+*         activateVitalPointMode();
+*         break;
+*     }
+*   },
+*   enabled: !isPaused,
+*   holdThreshold: 200, // 200ms to distinguish tap from hold
+*   enableHaptics: true,
+* });
+* ```
+* 
+* @public
+* @korean 터치컨트롤사용
+*/
+function useTouchControls({ onGesture, enabled = true, minSwipeDistance = 50, maxTapDuration = 300, holdThreshold = 200, enableHaptics = true }) {
+	const touchStartRef = useRef(null);
+	const touchStartTimeRef = useRef(0);
+	const [isTouching, setIsTouching] = useState(false);
+	const holdTimerRef = useRef(null);
+	/**
+	* Trigger haptic feedback for tactical step
+	* Light vibration (10ms) to confirm step input
+	* 
+	* @korean 햅틱피드백
+	*/
+	const triggerStepHaptic = useCallback(() => {
+		if (!enableHaptics || !navigator.vibrate) return;
+		try {
+			navigator.vibrate(10);
+		} catch (error) {
+			console.debug("Haptic feedback not available:", error);
+		}
+	}, [enableHaptics]);
+	/**
+	* Determine directional gesture from touch position
+	* Used for D-pad style controls
+	* Returns null for ambiguous/stationary taps
+	* 
+	* @korean 방향제스처감지
+	*/
+	const getDirectionalGesture = useCallback((startX, startY, endX, endY, isTap) => {
+		const deltaX = endX - startX;
+		const deltaY = endY - startY;
+		const absX = Math.abs(deltaX);
+		const absY = Math.abs(deltaY);
+		const minDirectionalMovement = 15;
+		if (absX < minDirectionalMovement && absY < minDirectionalMovement) return null;
+		const isDiagonal = absX > 20 && absY > 20 && Math.abs(absX - absY) < 30;
+		const prefix = isTap ? "tap" : "hold";
+		if (isDiagonal) {
+			if (isTap) {
+				if (deltaY < 0 && deltaX < 0) return "tap-forward-left";
+				if (deltaY < 0 && deltaX > 0) return "tap-forward-right";
+				if (deltaY > 0 && deltaX < 0) return "tap-back-left";
+				if (deltaY > 0 && deltaX > 0) return "tap-back-right";
+			}
+			return null;
+		}
+		if (absX > absY) return deltaX > 0 ? `${prefix}-right` : `${prefix}-left`;
+		else return deltaY < 0 ? `${prefix}-forward` : `${prefix}-back`;
+	}, []);
+	/**
+	* Handle touch start event
+	*/
+	const handleTouchStart = useCallback((e) => {
+		if (!enabled) return;
+		const touch = e.touches[0];
+		touchStartRef.current = touch;
+		touchStartTimeRef.current = Date.now();
+		setIsTouching(true);
+		if (e.touches.length === 2) {
+			e.preventDefault();
+			onGesture({
+				type: "two-finger-tap",
+				startX: touch.clientX,
+				startY: touch.clientY
+			});
+			return;
+		}
+		const screenCenterX = window.innerWidth / 2;
+		const screenCenterY = window.innerHeight / 2;
+		holdTimerRef.current = window.setTimeout(() => {
+			if (touchStartRef.current) {
+				const { clientX, clientY } = touchStartRef.current;
+				const deltaX = clientX - screenCenterX;
+				const deltaY = screenCenterY - clientY;
+				onGesture({
+					type: Math.abs(deltaX) >= Math.abs(deltaY) ? deltaX > 0 ? "hold-right" : "hold-left" : deltaY > 0 ? "hold-forward" : "hold-back",
+					startX: clientX,
+					startY: clientY
+				});
+			}
+		}, holdThreshold);
+	}, [
+		enabled,
+		onGesture,
+		holdThreshold
+	]);
+	/**
+	* Handle touch end event
+	*/
+	const handleTouchEnd = useCallback((e) => {
+		if (!enabled || !touchStartRef.current) return;
+		const touchEnd = e.changedTouches[0];
+		const touchStart = touchStartRef.current;
+		const touchDuration = Date.now() - touchStartTimeRef.current;
+		if (holdTimerRef.current) {
+			clearTimeout(holdTimerRef.current);
+			holdTimerRef.current = null;
+		}
+		const deltaX = touchEnd.clientX - touchStart.clientX;
+		const deltaY = touchEnd.clientY - touchStart.clientY;
+		const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+		setIsTouching(false);
+		if (distance >= minSwipeDistance) {
+			e.preventDefault();
+			if (Math.abs(deltaX) > Math.abs(deltaY)) if (deltaX > 0) onGesture({
+				type: "swipe-right",
+				distance,
+				startX: touchStart.clientX,
+				startY: touchStart.clientY,
+				endX: touchEnd.clientX,
+				endY: touchEnd.clientY
+			});
+			else onGesture({
+				type: "swipe-left",
+				distance,
+				startX: touchStart.clientX,
+				startY: touchStart.clientY,
+				endX: touchEnd.clientX,
+				endY: touchEnd.clientY
+			});
+			else if (deltaY > 0) onGesture({
+				type: "swipe-down",
+				distance,
+				startX: touchStart.clientX,
+				startY: touchStart.clientY,
+				endX: touchEnd.clientX,
+				endY: touchEnd.clientY
+			});
+			else onGesture({
+				type: "swipe-up",
+				distance,
+				startX: touchStart.clientX,
+				startY: touchStart.clientY,
+				endX: touchEnd.clientX,
+				endY: touchEnd.clientY
+			});
+		} else if (touchDuration <= maxTapDuration && touchDuration < holdThreshold) {
+			e.preventDefault();
+			const tapGesture = getDirectionalGesture(touchStart.clientX, touchStart.clientY, touchEnd.clientX, touchEnd.clientY, true);
+			if (tapGesture) {
+				triggerStepHaptic();
+				onGesture({
+					type: tapGesture,
+					startX: touchStart.clientX,
+					startY: touchStart.clientY,
+					endX: touchEnd.clientX,
+					endY: touchEnd.clientY
+				});
+			} else onGesture({
+				type: "tap",
+				startX: touchStart.clientX,
+				startY: touchStart.clientY,
+				endX: touchEnd.clientX,
+				endY: touchEnd.clientY
+			});
+		}
+		touchStartRef.current = null;
+	}, [
+		enabled,
+		minSwipeDistance,
+		maxTapDuration,
+		holdThreshold,
+		onGesture,
+		getDirectionalGesture,
+		triggerStepHaptic
+	]);
+	/**
+	* Handle touch cancel event
+	*/
+	const handleTouchCancel = useCallback(() => {
+		if (holdTimerRef.current) {
+			clearTimeout(holdTimerRef.current);
+			holdTimerRef.current = null;
+		}
+		touchStartRef.current = null;
+		touchStartTimeRef.current = 0;
+		setIsTouching(false);
+	}, []);
+	/**
+	* Setup touch event listeners
+	*/
+	useEffect(() => {
+		if (!enabled) return;
+		const options = { passive: false };
+		document.addEventListener("touchstart", handleTouchStart, options);
+		document.addEventListener("touchend", handleTouchEnd, options);
+		document.addEventListener("touchcancel", handleTouchCancel, options);
+		return () => {
+			document.removeEventListener("touchstart", handleTouchStart);
+			document.removeEventListener("touchend", handleTouchEnd);
+			document.removeEventListener("touchcancel", handleTouchCancel);
+		};
+	}, [
+		enabled,
+		handleTouchStart,
+		handleTouchEnd,
+		handleTouchCancel
+	]);
+	return { isTouching };
+}
+//#endregion
+export { useTouchControls };
+
+//# sourceMappingURL=useTouchControls.js.map

package/lib/hooks/useTouchControls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTouchControls.js","names":[],"sources":["../../src/hooks/useTouchControls.ts"],"sourcesContent":["/**\n * Touch Controls Hook\n * \n * Manages touch event handling and gesture recognition for mobile gameplay\n * Provides swipe detection, multi-touch support, and touch-based movement\n * \n * @module hooks/useTouchControls\n * @category Mobile Controls\n * @korean 터치 컨트롤 훅\n */\n\nimport { useCallback, useEffect, useRef, useState } from 'react';\n\n/**\n * Gesture types supported by the touch control system\n * \n * Added tactical step gestures for Korean martial arts footwork:\n * - tap-{direction}: Quick tap for tactical 30cm step\n * - hold-{direction}: Hold for continuous walk\n * \n * @korean 제스처타입\n */\nexport type GestureType =\n  | 'swipe-right'\n  | 'swipe-left'\n  | 'swipe-up'\n  | 'swipe-down'\n  | 'two-finger-tap'\n  | 'tap'\n  | 'tap-forward'\n  | 'tap-back'\n  | 'tap-left'\n  | 'tap-right'\n  | 'tap-forward-left'\n  | 'tap-forward-right'\n  | 'tap-back-left'\n  | 'tap-back-right'\n  | 'hold-forward'\n  | 'hold-back'\n  | 'hold-left'\n  | 'hold-right';\n\n/**\n * Gesture event data\n */\nexport interface GestureEvent {\n  /** Type of gesture detected */\n  readonly type: GestureType;\n  /** Distance of swipe in pixels (for swipe gestures) */\n  readonly distance?: number;\n  /** Coordinates of touch start */\n  readonly startX?: number;\n  readonly startY?: number;\n  /** Coordinates of touch end */\n  readonly endX?: number;\n  readonly endY?: number;\n}\n\n/**\n * Props for useTouchControls hook\n */\nexport interface UseTouchControlsProps {\n  /** Callback when gesture is detected */\n  readonly onGesture: (gesture: GestureEvent) => void;\n  /** Whether touch input is enabled */\n  readonly enabled?: boolean;\n  /** Minimum swipe distance in pixels (default: 50) */\n  readonly minSwipeDistance?: number;\n  /** Maximum time for tap in ms (default: 300) */\n  readonly maxTapDuration?: number;\n  /** Time threshold for hold vs tap in ms (default: 200) */\n  readonly holdThreshold?: number;\n  /** Enable haptic feedback for steps (default: true) */\n  readonly enableHaptics?: boolean;\n}\n\n/**\n * Return type for useTouchControls hook\n */\nexport interface UseTouchControlsReturn {\n  /** Whether a touch is currently active */\n  readonly isTouching: boolean;\n}\n\n/**\n * Custom hook for handling touch controls and gesture recognition\n * \n * Features:\n * - Swipe detection (horizontal and vertical)\n * - Two-finger tap detection for vital point mode\n * - Single tap detection\n * - Tactical step gestures (tap) vs continuous walk (hold)\n * - Distance calculation for swipe intensity\n * - Configurable thresholds\n * - Haptic feedback for tactical steps\n * \n * Gesture Mapping:\n * - Swipe Right: Advance toward opponent\n * - Swipe Left: Retreat from opponent\n * - Swipe Up: High stance mode\n * - Swipe Down: Low stance mode\n * - Two-Finger Tap: Activate vital point targeting mode\n * - Single Tap (directional): Tactical 30cm step (전술적 발걸음)\n * - Hold (directional): Continuous walk movement\n * \n * @example\n * ```typescript\n * const { isTouching } = useTouchControls({\n *   onGesture: (gesture) => {\n *     switch (gesture.type) {\n *       case 'tap-forward':\n *         handleTacticalStep('forward'); // 전진보법\n *         break;\n *       case 'hold-forward':\n *         handleContinuousWalk('forward');\n *         break;\n *       case 'two-finger-tap':\n *         activateVitalPointMode();\n *         break;\n *     }\n *   },\n *   enabled: !isPaused,\n *   holdThreshold: 200, // 200ms to distinguish tap from hold\n *   enableHaptics: true,\n * });\n * ```\n * \n * @public\n * @korean 터치컨트롤사용\n */\nexport function useTouchControls({\n  onGesture,\n  enabled = true,\n  minSwipeDistance = 50,\n  maxTapDuration = 300,\n  holdThreshold = 200,\n  enableHaptics = true,\n}: UseTouchControlsProps): UseTouchControlsReturn {\n  const touchStartRef = useRef<Touch | null>(null);\n  const touchStartTimeRef = useRef<number>(0);\n  const [isTouching, setIsTouching] = useState<boolean>(false);\n  const holdTimerRef = useRef<number | null>(null);\n  \n  /**\n   * Trigger haptic feedback for tactical step\n   * Light vibration (10ms) to confirm step input\n   * \n   * @korean 햅틱피드백\n   */\n  const triggerStepHaptic = useCallback(() => {\n    if (!enableHaptics || !navigator.vibrate) return;\n    \n    try {\n      // Short, light vibration for step (10ms)\n      navigator.vibrate(10);\n    } catch (error) {\n      // Haptic feedback not supported or failed\n      console.debug('Haptic feedback not available:', error);\n    }\n  }, [enableHaptics]);\n  \n  /**\n   * Determine directional gesture from touch position\n   * Used for D-pad style controls\n   * Returns null for ambiguous/stationary taps\n   * \n   * @korean 방향제스처감지\n   */\n  const getDirectionalGesture = useCallback((\n    startX: number,\n    startY: number,\n    endX: number,\n    endY: number,\n    isTap: boolean\n  ): GestureType | null => {\n    const deltaX = endX - startX;\n    const deltaY = endY - startY;\n    const absX = Math.abs(deltaX);\n    const absY = Math.abs(deltaY);\n    \n    // If movement is too small, it's not a directional gesture\n    const minDirectionalMovement = 15; // pixels\n    if (absX < minDirectionalMovement && absY < minDirectionalMovement) {\n      return null; // Ambiguous tap, not directional\n    }\n    \n    // Check for diagonal gestures (45-degree threshold)\n    const isDiagonal = absX > 20 && absY > 20 && Math.abs(absX - absY) < 30;\n    \n    const prefix = isTap ? 'tap' : 'hold';\n    \n    if (isDiagonal) {\n      // Diagonal gestures (only for taps/steps)\n      if (isTap) {\n        if (deltaY < 0 && deltaX < 0) return 'tap-forward-left';\n        if (deltaY < 0 && deltaX > 0) return 'tap-forward-right';\n        if (deltaY > 0 && deltaX < 0) return 'tap-back-left';\n        if (deltaY > 0 && deltaX > 0) return 'tap-back-right';\n      }\n      return null;\n    }\n    \n    // Cardinal directions\n    if (absX > absY) {\n      // Horizontal\n      return deltaX > 0 ? `${prefix}-right` as GestureType : `${prefix}-left` as GestureType;\n    } else {\n      // Vertical\n      return deltaY < 0 ? `${prefix}-forward` as GestureType : `${prefix}-back` as GestureType;\n    }\n  }, []);\n\n  /**\n   * Handle touch start event\n   */\n  const handleTouchStart = useCallback((e: TouchEvent) => {\n    if (!enabled) return;\n\n    const touch = e.touches[0];\n    touchStartRef.current = touch;\n    touchStartTimeRef.current = Date.now();\n    setIsTouching(true);\n\n    // Check for two-finger tap immediately\n    if (e.touches.length === 2) {\n      e.preventDefault();\n      onGesture({\n        type: 'two-finger-tap',\n        startX: touch.clientX,\n        startY: touch.clientY,\n      });\n      return;\n    }\n    \n    // Capture screen dimensions at touch start time to prevent incorrect\n    // direction calculation if window is resized during hold\n    const screenCenterX = window.innerWidth / 2;\n    const screenCenterY = window.innerHeight / 2;\n    \n    // Set up hold detection timer\n    // Note: Hold gesture direction is determined from the initial touch position\n    // relative to screen center. This supports D-pad style layouts where each\n    // region of the screen (or an overlaid control) corresponds to a cardinal direction.\n    holdTimerRef.current = window.setTimeout(() => {\n      // Touch held for longer than threshold - trigger hold gesture\n      // Check touchStartRef to ensure touch hasn't ended before timer fired\n      if (touchStartRef.current) {\n        const { clientX, clientY } = touchStartRef.current;\n\n        // Use captured screen center coordinates (from touch start time)\n        const deltaX = clientX - screenCenterX;\n        // Invert Y so that a touch higher on the screen is considered \"forward\"\n        const deltaY = screenCenterY - clientY;\n\n        const holdGesture: GestureType =\n          Math.abs(deltaX) >= Math.abs(deltaY)\n            ? (deltaX > 0 ? 'hold-right' : 'hold-left')\n            : (deltaY > 0 ? 'hold-forward' : 'hold-back');\n\n        onGesture({\n          type: holdGesture,\n          startX: clientX,\n          startY: clientY,\n        });\n      }\n    }, holdThreshold);\n  }, [enabled, onGesture, holdThreshold]);\n\n  /**\n   * Handle touch end event\n   */\n  const handleTouchEnd = useCallback((e: TouchEvent) => {\n    if (!enabled || !touchStartRef.current) return;\n\n    const touchEnd = e.changedTouches[0];\n    const touchStart = touchStartRef.current;\n    const touchDuration = Date.now() - touchStartTimeRef.current;\n\n    // Clear hold timer\n    if (holdTimerRef.current) {\n      clearTimeout(holdTimerRef.current);\n      holdTimerRef.current = null;\n    }\n\n    // Calculate deltas\n    const deltaX = touchEnd.clientX - touchStart.clientX;\n    const deltaY = touchEnd.clientY - touchStart.clientY;\n    const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);\n\n    // Reset touch state\n    setIsTouching(false);\n\n    // Detect gesture type\n    if (distance >= minSwipeDistance) {\n      // Swipe gesture (for quick directional inputs)\n      e.preventDefault();\n\n      // Determine primary direction\n      if (Math.abs(deltaX) > Math.abs(deltaY)) {\n        // Horizontal swipe\n        if (deltaX > 0) {\n          onGesture({\n            type: 'swipe-right',\n            distance,\n            startX: touchStart.clientX,\n            startY: touchStart.clientY,\n            endX: touchEnd.clientX,\n            endY: touchEnd.clientY,\n          });\n        } else {\n          onGesture({\n            type: 'swipe-left',\n            distance,\n            startX: touchStart.clientX,\n            startY: touchStart.clientY,\n            endX: touchEnd.clientX,\n            endY: touchEnd.clientY,\n          });\n        }\n      } else {\n        // Vertical swipe\n        if (deltaY > 0) {\n          onGesture({\n            type: 'swipe-down',\n            distance,\n            startX: touchStart.clientX,\n            startY: touchStart.clientY,\n            endX: touchEnd.clientX,\n            endY: touchEnd.clientY,\n          });\n        } else {\n          onGesture({\n            type: 'swipe-up',\n            distance,\n            startX: touchStart.clientX,\n            startY: touchStart.clientY,\n            endX: touchEnd.clientX,\n            endY: touchEnd.clientY,\n          });\n        }\n      }\n    } else if (touchDuration <= maxTapDuration && touchDuration < holdThreshold) {\n      // Quick tap - tactical step gesture\n      e.preventDefault();\n      \n      const tapGesture = getDirectionalGesture(\n        touchStart.clientX,\n        touchStart.clientY,\n        touchEnd.clientX,\n        touchEnd.clientY,\n        true // Is a tap\n      );\n      \n      if (tapGesture) {\n        // Directional step tap\n        triggerStepHaptic();\n        onGesture({\n          type: tapGesture,\n          startX: touchStart.clientX,\n          startY: touchStart.clientY,\n          endX: touchEnd.clientX,\n          endY: touchEnd.clientY,\n        });\n      } else {\n        // Generic tap (fallback)\n        onGesture({\n          type: 'tap',\n          startX: touchStart.clientX,\n          startY: touchStart.clientY,\n          endX: touchEnd.clientX,\n          endY: touchEnd.clientY,\n        });\n      }\n    }\n\n    // Clear touch start reference\n    touchStartRef.current = null;\n  }, [enabled, minSwipeDistance, maxTapDuration, holdThreshold, onGesture, getDirectionalGesture, triggerStepHaptic]);\n\n  /**\n   * Handle touch cancel event\n   */\n  const handleTouchCancel = useCallback(() => {\n    // Clear hold timer\n    if (holdTimerRef.current) {\n      clearTimeout(holdTimerRef.current);\n      holdTimerRef.current = null;\n    }\n    \n    touchStartRef.current = null;\n    touchStartTimeRef.current = 0;\n    setIsTouching(false);\n  }, []);\n\n  /**\n   * Setup touch event listeners\n   */\n  useEffect(() => {\n    if (!enabled) return;\n\n    const options: AddEventListenerOptions = {\n      passive: false, // Allow preventDefault for gesture handling\n    };\n\n    document.addEventListener('touchstart', handleTouchStart, options);\n    document.addEventListener('touchend', handleTouchEnd, options);\n    document.addEventListener('touchcancel', handleTouchCancel, options);\n\n    return () => {\n      document.removeEventListener('touchstart', handleTouchStart);\n      document.removeEventListener('touchend', handleTouchEnd);\n      document.removeEventListener('touchcancel', handleTouchCancel);\n    };\n  }, [enabled, handleTouchStart, handleTouchEnd, handleTouchCancel]);\n\n  return {\n    isTouching,\n  };\n}\n"],"mappings":"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"}

package/lib/hooks/useWebGLContextLossHandler.d.ts

@@ -0,0 +1,77 @@
+/**
+ * useWebGLContextLossHandler - React hook for handling WebGL context loss
+ *
+ * This hook sets up event listeners for WebGL context loss and restoration,
+ * which can occur due to GPU issues, memory pressure, or browser tab switching.
+ *
+ * @example
+ * ```tsx
+ * const Canvas = () => {
+ *   useWebGLContextLossHandler();
+ *   return <Canvas>...</Canvas>;
+ * };
+ * ```
+ */
+import type React from "react";
+/**
+ * Minimum delay between context loss events to prevent thrashing
+ */
+export declare const MIN_CONTEXT_RECOVERY_DELAY = 100;
+/**
+ * Get global WebGL context state
+ */
+export declare const getWebGLContextState: () => {
+    isLost: boolean;
+    lossCount: number;
+    timeSinceLastLoss: number;
+};
+export interface WebGLContextLossOptions {
+    /**
+     * Callback when context is lost
+     */
+    readonly onContextLost?: () => void;
+    /**
+     * Callback when context is restored
+     */
+    readonly onContextRestored?: () => void;
+    /**
+     * Whether to attempt automatic restoration (default: true)
+     */
+    readonly autoRestore?: boolean;
+    /**
+     * Optional canvas ref to attach to a specific canvas element
+     * If not provided, will query for the first canvas in the document
+     */
+    readonly canvasRef?: React.RefObject<HTMLCanvasElement>;
+    /**
+     * Delay in ms before attempting to query for canvas (default: 50)
+     * Helps avoid race conditions during screen transitions
+     */
+    readonly mountDelay?: number;
+    /**
+     * Maximum attempts to find canvas element (default: 5)
+     */
+    readonly maxRetries?: number;
+}
+export interface WebGLContextState {
+    /** Whether context is currently lost */
+    readonly isContextLost: boolean;
+    /** Number of times context has been lost */
+    readonly lossCount: number;
+    /** Whether the canvas element has been found */
+    readonly isCanvasMounted: boolean;
+}
+/**
+ * Hook to handle WebGL context loss and restoration
+ * Returns state information about the WebGL context
+ */
+export declare const useWebGLContextLossHandler: (options?: WebGLContextLossOptions) => WebGLContextState;
+/**
+ * Check if WebGL is available in the current browser
+ */
+export declare const isWebGLAvailable: () => boolean;
+/**
+ * Check if WebGL2 is available in the current browser
+ */
+export declare const isWebGL2Available: () => boolean;
+//# sourceMappingURL=useWebGLContextLossHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useWebGLContextLossHandler.d.ts","sourceRoot":"","sources":["../../src/hooks/useWebGLContextLossHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAW/B;;GAEG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAO;IACtC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;CAK1B,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GACrC,UAAS,uBAA4B,KACpC,iBAmKF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAAO,OAenC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAO,OAcpC,CAAC"}

package/lib/hooks/useWebGLContextLossHandler.js

@@ -0,0 +1,119 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+//#region src/hooks/useWebGLContextLossHandler.ts
+/**
+* Global WebGL context state tracking
+* Helps coordinate context recovery across multiple Canvas components
+*/
+var globalContextLossCount = 0;
+var globalIsContextLost = false;
+var lastContextLossTime = 0;
+/**
+* Hook to handle WebGL context loss and restoration
+* Returns state information about the WebGL context
+*/
+var useWebGLContextLossHandler = (options = {}) => {
+	const { onContextLost, onContextRestored, autoRestore = true, canvasRef, mountDelay = 50, maxRetries = 5 } = options;
+	const [contextState, setContextState] = useState({
+		isContextLost: globalIsContextLost,
+		lossCount: globalContextLossCount,
+		isCanvasMounted: false
+	});
+	const onContextLostRef = useRef(onContextLost);
+	const onContextRestoredRef = useRef(onContextRestored);
+	const retryCountRef = useRef(0);
+	const mountedRef = useRef(true);
+	useEffect(() => {
+		onContextLostRef.current = onContextLost;
+		onContextRestoredRef.current = onContextRestored;
+	});
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+		};
+	}, []);
+	const handleContextLost = useCallback((event) => {
+		const now = Date.now();
+		globalIsContextLost = true;
+		globalContextLossCount++;
+		lastContextLossTime = now;
+		console.warn(`⚠️ WebGL context lost (count: ${globalContextLossCount}, time since mount: ${now - lastContextLossTime}ms)`);
+		if (autoRestore) event.preventDefault();
+		if (mountedRef.current) setContextState({
+			isContextLost: true,
+			lossCount: globalContextLossCount,
+			isCanvasMounted: true
+		});
+		onContextLostRef.current?.();
+	}, [autoRestore]);
+	const handleContextRestored = useCallback(() => {
+		globalIsContextLost = false;
+		console.log("✅ WebGL context restored successfully");
+		if (mountedRef.current) setContextState((prev) => ({
+			...prev,
+			isContextLost: false
+		}));
+		onContextRestoredRef.current?.();
+	}, []);
+	useEffect(() => {
+		let canvas = canvasRef?.current ?? document.querySelector("canvas");
+		let cleanupFn;
+		let retryTimeout;
+		let observer;
+		const attachListeners = (canvasEl) => {
+			canvasEl.addEventListener("webglcontextlost", handleContextLost, false);
+			canvasEl.addEventListener("webglcontextrestored", handleContextRestored, false);
+			if (mountedRef.current) setContextState((prev) => ({
+				...prev,
+				isCanvasMounted: true
+			}));
+			return () => {
+				canvasEl.removeEventListener("webglcontextlost", handleContextLost);
+				canvasEl.removeEventListener("webglcontextrestored", handleContextRestored);
+			};
+		};
+		const tryFindCanvas = () => {
+			if (!mountedRef.current) return;
+			canvas = canvasRef?.current ?? document.querySelector("canvas");
+			if (canvas) {
+				cleanupFn = attachListeners(canvas);
+				retryCountRef.current = 0;
+			} else if (retryCountRef.current < maxRetries) {
+				retryCountRef.current++;
+				retryTimeout = setTimeout(tryFindCanvas, mountDelay);
+			} else {
+				observer = new MutationObserver(() => {
+					canvas = document.querySelector("canvas");
+					if (canvas && mountedRef.current) {
+						observer?.disconnect();
+						cleanupFn = attachListeners(canvas);
+					}
+				});
+				observer.observe(document.body, {
+					childList: true,
+					subtree: true
+				});
+			}
+		};
+		canvas = canvasRef?.current ?? document.querySelector("canvas");
+		if (canvas) cleanupFn = attachListeners(canvas);
+		else retryTimeout = setTimeout(tryFindCanvas, mountDelay);
+		return () => {
+			if (retryTimeout) clearTimeout(retryTimeout);
+			observer?.disconnect();
+			cleanupFn?.();
+		};
+	}, [
+		autoRestore,
+		canvasRef,
+		handleContextLost,
+		handleContextRestored,
+		maxRetries,
+		mountDelay
+	]);
+	return contextState;
+};
+//#endregion
+export { useWebGLContextLossHandler };
+
+//# sourceMappingURL=useWebGLContextLossHandler.js.map