blacktrigram 0.7.2

package/lib/hooks/useSkeletalAnimation.d.ts

@@ -0,0 +1,88 @@
+/**
+ * useSkeletalAnimation - Shared hook for skeletal animation management
+ *
+ * Centralizes skeletal animation state and frame updates for player characters.
+ * Reduces code duplication across SkeletalPlayer3D, Player3DWithTransitions,
+ * and screen components.
+ *
+ * PHASE 2: Now uses cached interpolation and batch bone updates for 60fps performance
+ *
+ * @module hooks/useSkeletalAnimation
+ * @category Hooks
+ * @korean 골격애니메이션훅
+ */
+import type { TrigramStance } from "../types/common";
+import type { PlayerAnimation } from "../types/player-visual";
+import type { SkeletalAnimationState, SkeletalRig } from "../types/skeletal";
+/**
+ * Options for useSkeletalAnimation hook
+ * @korean 골격애니메이션훅옵션
+ */
+export interface UseSkeletalAnimationOptions {
+    /** Current animation name */
+    readonly currentAnimation: PlayerAnimation;
+    /** Specific attack animation name (for attack state) */
+    readonly attackAnimation?: string;
+    /** Whether player is blocking */
+    readonly isBlocking?: boolean;
+    /** Current player stance for trigram-specific idle animations */
+    readonly stance?: TrigramStance;
+    /**
+     * Stance laterality (left or right foot forward)
+     *
+     * - "left": Left foot forward (왼발서기 - Oenbal Seogi)
+     * - "right": Right foot forward (오른발서기 - Oreun Bal Seogi)
+     *
+     * This affects animation mirroring - techniques will be mirrored
+     * appropriately based on the laterality, creating 16 distinct stance
+     * configurations (8 trigrams × 2 laterality).
+     *
+     * **Korean**: 측면성 (Cheugmyeonseong - Laterality/Sidedness)
+     */
+    readonly laterality?: "left" | "right";
+    /** Callback when animation completes */
+    readonly onAnimationComplete?: () => void;
+}
+/**
+ * Return type for useSkeletalAnimation hook
+ * @korean 골격애니메이션훅반환타입
+ */
+export interface UseSkeletalAnimationReturn {
+    /** Current animation state */
+    readonly animState: SkeletalAnimationState;
+    /** Animation time reference (seconds) */
+    readonly animTimeRef: React.MutableRefObject<number>;
+    /** Update animation and apply to rig (call in useFrame) */
+    readonly updateRigAnimation: (rig: SkeletalRig, delta: number) => void;
+    /** Diagonal rotation override for step animations */
+    readonly diagonalRotationY: number | null;
+}
+/**
+ * useSkeletalAnimation hook
+ *
+ * Manages skeletal animation state and frame updates for player characters.
+ * Handles animation selection based on player state (idle, walk, attack, etc.)
+ * and applies keyframes to the skeletal rig.
+ *
+ * @param options - Animation options
+ * @returns Animation state and update function
+ *
+ * @example
+ * ```tsx
+ * const { animState, animTimeRef, updateRigAnimation, diagonalRotationY } =
+ *   useSkeletalAnimation({
+ *     currentAnimation: "walk",
+ *     isBlocking: false,
+ *     onAnimationComplete: () => console.log("Animation completed"),
+ *   });
+ *
+ * // In useFrame callback
+ * useFrame((_, delta) => {
+ *   updateRigAnimation(rig, delta);
+ * });
+ * ```
+ *
+ * @korean 골격애니메이션훅
+ */
+export declare function useSkeletalAnimation(options: UseSkeletalAnimationOptions): UseSkeletalAnimationReturn;
+//# sourceMappingURL=useSkeletalAnimation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSkeletalAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useSkeletalAnimation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAeH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAEV,sBAAsB,EACtB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C,6BAA6B;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,eAAe,CAAC;IAC3C,wDAAwD;IACxD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,iCAAiC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,wCAAwC;IACxC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,yCAAyC;IACzC,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACrD,2DAA2D;IAC3D,QAAQ,CAAC,kBAAkB,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvE,qDAAqD;IACrD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,0BAA0B,CAoN5B"}

package/lib/hooks/useSkeletalAnimation.js

@@ -0,0 +1,176 @@
+import { getDefensiveAnimation } from "../systems/animation/catalogs/DefensiveAnimations.js";
+import { getAttackAnimation } from "../systems/animation/catalogs/StanceAttackAnimations.js";
+import { getAnimation, getAnimationByName } from "../systems/animation/core/AnimationRegistry.js";
+import { batchUpdateBones, interpolateKeyframeCached, performanceMonitor } from "../systems/animation/core/AnimationOptimizations.js";
+import { applyLaterality } from "../systems/animation/core/LateralityTransform.js";
+import { getStepAnimation } from "../systems/animation/catalogs/StepSkeletalAnimations.js";
+import { getFootworkAnimation } from "../systems/animation/catalogs/FootworkSkeletalAnimations.js";
+import "../systems/animation/index.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+//#region src/hooks/useSkeletalAnimation.ts
+/**
+* useSkeletalAnimation - Shared hook for skeletal animation management
+*
+* Centralizes skeletal animation state and frame updates for player characters.
+* Reduces code duplication across SkeletalPlayer3D, Player3DWithTransitions,
+* and screen components.
+*
+* PHASE 2: Now uses cached interpolation and batch bone updates for 60fps performance
+*
+* @module hooks/useSkeletalAnimation
+* @category Hooks
+* @korean 골격애니메이션훅
+*/
+/**
+* Set of diagonal step animations for O(1) lookup
+* @korean 대각선스텝애니메이션집합
+*/
+var DIAGONAL_STEP_ANIMATIONS = new Set([
+	"step_forward_left",
+	"step_forward_right",
+	"step_back_left",
+	"step_back_right"
+]);
+/**
+* useSkeletalAnimation hook
+*
+* Manages skeletal animation state and frame updates for player characters.
+* Handles animation selection based on player state (idle, walk, attack, etc.)
+* and applies keyframes to the skeletal rig.
+*
+* @param options - Animation options
+* @returns Animation state and update function
+*
+* @example
+* ```tsx
+* const { animState, animTimeRef, updateRigAnimation, diagonalRotationY } =
+*   useSkeletalAnimation({
+*     currentAnimation: "walk",
+*     isBlocking: false,
+*     onAnimationComplete: () => console.log("Animation completed"),
+*   });
+*
+* // In useFrame callback
+* useFrame((_, delta) => {
+*   updateRigAnimation(rig, delta);
+* });
+* ```
+*
+* @korean 골격애니메이션훅
+*/
+function useSkeletalAnimation(options) {
+	const { currentAnimation, attackAnimation, isBlocking = false, stance, laterality = "right", onAnimationComplete } = options;
+	const [animState, setAnimState] = useState({
+		currentAnimation: null,
+		currentTime: 0,
+		isPlaying: false,
+		playbackSpeed: 1,
+		previousKeyframeIndex: 0,
+		nextKeyframeIndex: 1
+	});
+	const animTimeRef = useRef(0);
+	const [diagonalRotationY, setDiagonalRotationY] = useState(null);
+	useEffect(() => {
+		animTimeRef.current = 0;
+		let selectedAnim = null;
+		let playbackSpeed;
+		let shouldClearDiagonalRotation = true;
+		if (currentAnimation === "attack" && attackAnimation) {
+			selectedAnim = getAttackAnimation(attackAnimation) ?? getAnimation(attackAnimation) ?? null;
+			playbackSpeed = 1;
+		} else if (currentAnimation === "defend" || isBlocking) {
+			if (attackAnimation) selectedAnim = getDefensiveAnimation(attackAnimation) ?? null;
+			selectedAnim ??= getAnimation("block") ?? null;
+			playbackSpeed = 1;
+		} else if (currentAnimation === "idle") {
+			if (stance) selectedAnim = getAnimationByName(`stance_${stance}`) ?? null;
+			selectedAnim ??= getAnimation("idle") ?? null;
+			playbackSpeed = .5;
+		} else if (currentAnimation === "walk") {
+			if (stance) selectedAnim = getAnimationByName(`walk_${stance}`) ?? null;
+			selectedAnim ??= getAnimation("walk") ?? null;
+			playbackSpeed = 1;
+		} else if (currentAnimation === "run") {
+			if (stance) selectedAnim = getAnimationByName(`run_${stance}`) ?? null;
+			selectedAnim ??= getAnimation("run") ?? null;
+			playbackSpeed = 1;
+		} else if (currentAnimation?.startsWith("fall_")) {
+			selectedAnim = getAnimation(currentAnimation) ?? null;
+			playbackSpeed = 1;
+		} else if (currentAnimation === "stance_change") {
+			selectedAnim = getAnimation("idle_stance") ?? null;
+			playbackSpeed = 1.2;
+		} else if (currentAnimation === "hit") {
+			setAnimState((prev) => ({
+				...prev,
+				isPlaying: false,
+				currentTime: 0
+			}));
+			return;
+		} else if (currentAnimation?.startsWith("step_")) {
+			selectedAnim = getStepAnimation(currentAnimation) ?? null;
+			playbackSpeed = 1;
+			if (DIAGONAL_STEP_ANIMATIONS.has(currentAnimation)) shouldClearDiagonalRotation = false;
+		} else if (currentAnimation?.startsWith("footwork_")) {
+			selectedAnim = getFootworkAnimation(currentAnimation) ?? null;
+			playbackSpeed = 1;
+		} else if (currentAnimation?.startsWith("stance_")) {
+			selectedAnim = getAnimationByName(currentAnimation) ?? null;
+			playbackSpeed = .5;
+		} else {
+			selectedAnim = getAnimation("idle_stance") ?? null;
+			playbackSpeed = .5;
+		}
+		if (selectedAnim) selectedAnim = applyLaterality(selectedAnim, laterality);
+		if (shouldClearDiagonalRotation) setDiagonalRotationY(null);
+		setAnimState({
+			currentAnimation: selectedAnim,
+			currentTime: 0,
+			isPlaying: true,
+			playbackSpeed,
+			previousKeyframeIndex: 0,
+			nextKeyframeIndex: 1
+		});
+	}, [
+		currentAnimation,
+		attackAnimation,
+		isBlocking,
+		stance,
+		laterality
+	]);
+	return {
+		animState,
+		animTimeRef,
+		updateRigAnimation: useCallback((targetRig, delta) => {
+			if (animState.isPlaying && animState.currentAnimation) {
+				const frameStartTime = performance.now();
+				let newTime = animTimeRef.current + delta * animState.playbackSpeed;
+				let completed = false;
+				if (newTime >= animState.currentAnimation.duration) if (animState.currentAnimation.loop) newTime = newTime % animState.currentAnimation.duration;
+				else {
+					newTime = animState.currentAnimation.duration;
+					completed = true;
+				}
+				const keyframe = interpolateKeyframeCached(animState.currentAnimation.name, animState.currentAnimation, newTime);
+				if (keyframe) batchUpdateBones(targetRig, keyframe);
+				animTimeRef.current = newTime;
+				const frameTime = performance.now() - frameStartTime;
+				performanceMonitor.recordFrame(frameTime);
+				if (completed) {
+					animTimeRef.current = 0;
+					setAnimState((prev) => ({
+						...prev,
+						isPlaying: false,
+						currentTime: 0
+					}));
+					if (onAnimationComplete) onAnimationComplete();
+				}
+			}
+		}, [animState, onAnimationComplete]),
+		diagonalRotationY
+	};
+}
+//#endregion
+export { useSkeletalAnimation };
+
+//# sourceMappingURL=useSkeletalAnimation.js.map

package/lib/hooks/useSkeletalAnimation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSkeletalAnimation.js","names":[],"sources":["../../src/hooks/useSkeletalAnimation.ts"],"sourcesContent":["/**\n * useSkeletalAnimation - Shared hook for skeletal animation management\n *\n * Centralizes skeletal animation state and frame updates for player characters.\n * Reduces code duplication across SkeletalPlayer3D, Player3DWithTransitions,\n * and screen components.\n *\n * PHASE 2: Now uses cached interpolation and batch bone updates for 60fps performance\n *\n * @module hooks/useSkeletalAnimation\n * @category Hooks\n * @korean 골격애니메이션훅\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\nimport {\n  batchUpdateBones,\n  getAnimation,\n  getAnimationByName,\n  getAttackAnimation,\n  getDefensiveAnimation,\n  getFootworkAnimation,\n  getStepAnimation,\n  interpolateKeyframeCached,\n  performanceMonitor,\n} from \"../systems/animation\";\nimport { applyLaterality } from \"../systems/animation/core/LateralityTransform\";\nimport type { TrigramStance } from \"../types/common\";\nimport type { PlayerAnimation } from \"../types/player-visual\";\nimport type {\n  SkeletalAnimation,\n  SkeletalAnimationState,\n  SkeletalRig,\n} from \"../types/skeletal\";\n\n/**\n * Options for useSkeletalAnimation hook\n * @korean 골격애니메이션훅옵션\n */\nexport interface UseSkeletalAnimationOptions {\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  /** Current player stance for trigram-specific idle animations */\n  readonly stance?: TrigramStance;\n  /**\n   * Stance laterality (left or right foot forward)\n   *\n   * - \"left\": Left foot forward (왼발서기 - Oenbal Seogi)\n   * - \"right\": Right foot forward (오른발서기 - Oreun Bal Seogi)\n   *\n   * This affects animation mirroring - techniques will be mirrored\n   * appropriately based on the laterality, creating 16 distinct stance\n   * configurations (8 trigrams × 2 laterality).\n   *\n   * **Korean**: 측면성 (Cheugmyeonseong - Laterality/Sidedness)\n   */\n  readonly laterality?: \"left\" | \"right\";\n  /** Callback when animation completes */\n  readonly onAnimationComplete?: () => void;\n}\n\n/**\n * Return type for useSkeletalAnimation hook\n * @korean 골격애니메이션훅반환타입\n */\nexport interface UseSkeletalAnimationReturn {\n  /** Current animation state */\n  readonly animState: SkeletalAnimationState;\n  /** Animation time reference (seconds) */\n  readonly animTimeRef: React.MutableRefObject<number>;\n  /** Update animation and apply to rig (call in useFrame) */\n  readonly updateRigAnimation: (rig: SkeletalRig, delta: number) => void;\n  /** Diagonal rotation override for step animations */\n  readonly diagonalRotationY: number | null;\n}\n\n/**\n * Set of diagonal step animations for O(1) lookup\n * @korean 대각선스텝애니메이션집합\n */\nconst DIAGONAL_STEP_ANIMATIONS = new Set([\n  \"step_forward_left\",\n  \"step_forward_right\",\n  \"step_back_left\",\n  \"step_back_right\",\n]);\n\n/**\n * useSkeletalAnimation hook\n *\n * Manages skeletal animation state and frame updates for player characters.\n * Handles animation selection based on player state (idle, walk, attack, etc.)\n * and applies keyframes to the skeletal rig.\n *\n * @param options - Animation options\n * @returns Animation state and update function\n *\n * @example\n * ```tsx\n * const { animState, animTimeRef, updateRigAnimation, diagonalRotationY } =\n *   useSkeletalAnimation({\n *     currentAnimation: \"walk\",\n *     isBlocking: false,\n *     onAnimationComplete: () => console.log(\"Animation completed\"),\n *   });\n *\n * // In useFrame callback\n * useFrame((_, delta) => {\n *   updateRigAnimation(rig, delta);\n * });\n * ```\n *\n * @korean 골격애니메이션훅\n */\nexport function useSkeletalAnimation(\n  options: UseSkeletalAnimationOptions,\n): UseSkeletalAnimationReturn {\n  const {\n    currentAnimation,\n    attackAnimation,\n    isBlocking = false,\n    stance,\n    laterality = \"right\",\n    onAnimationComplete,\n  } = options;\n\n  // Animation state\n  const [animState, setAnimState] = useState<SkeletalAnimationState>({\n    currentAnimation: null,\n    currentTime: 0,\n    isPlaying: false,\n    playbackSpeed: 1.0,\n    previousKeyframeIndex: 0,\n    nextKeyframeIndex: 1,\n  });\n\n  // Animation time ref (updated at 60fps without triggering re-renders)\n  const animTimeRef = useRef(0);\n\n  // Diagonal step rotation override (Y-axis rotation in radians)\n  const [diagonalRotationY, setDiagonalRotationY] = useState<number | null>(\n    null,\n  );\n\n  // Load animation when currentAnimation, blocking state, or laterality changes\n  useEffect(() => {\n    // Reset animation time whenever animation changes\n    animTimeRef.current = 0;\n\n    let selectedAnim: SkeletalAnimation | null = null;\n    let playbackSpeed: number;\n    let shouldClearDiagonalRotation = true;\n\n    if (currentAnimation === \"attack\" && attackAnimation) {\n      // Attack animation - first check stance-specific attacks, then generic\n      selectedAnim =\n        getAttackAnimation(attackAnimation) ??\n        getAnimation(attackAnimation) ??\n        null;\n      playbackSpeed = 1.0;\n    } else if (currentAnimation === \"defend\" || isBlocking) {\n      // Block/defend animation - check stance-specific defensive animations first\n      // If attackAnimation contains a defensive animation name, use it\n      if (attackAnimation) {\n        selectedAnim = getDefensiveAnimation(attackAnimation) ?? null;\n      }\n      // Fall back to generic block animation\n      selectedAnim ??= getAnimation(\"block\") ?? null;\n      playbackSpeed = 1.0;\n    } else if (currentAnimation === \"idle\") {\n      // Idle animation - use trigram-specific stance idle if stance is provided\n      // Otherwise fall back to generic idle breathing animation\n      if (stance) {\n        const stanceIdleAnim = `stance_${stance}` as PlayerAnimation;\n        selectedAnim = getAnimationByName(stanceIdleAnim) ?? null;\n      }\n      // Fall back to generic idle if no stance or stance animation not found\n      selectedAnim ??= getAnimation(\"idle\") ?? null;\n      playbackSpeed = 0.5; // Slow breathing animation\n    } else if (currentAnimation === \"walk\") {\n      // Walking animation - use trigram-specific walk if stance is provided\n      if (stance) {\n        const stanceWalkAnim = `walk_${stance}` as PlayerAnimation;\n        selectedAnim = getAnimationByName(stanceWalkAnim) ?? null;\n      }\n      // Fall back to generic walk if no stance or stance animation not found\n      selectedAnim ??= getAnimation(\"walk\") ?? null;\n      playbackSpeed = 1.0;\n    } else if (currentAnimation === \"run\") {\n      // Running animation - use trigram-specific run if stance is provided\n      if (stance) {\n        const stanceRunAnim = `run_${stance}` as PlayerAnimation;\n        selectedAnim = getAnimationByName(stanceRunAnim) ?? null;\n      }\n      // Fall back to generic run if no stance or stance animation not found\n      selectedAnim ??= getAnimation(\"run\") ?? null;\n      playbackSpeed = 1.0;\n    } else if (currentAnimation?.startsWith(\"fall_\")) {\n      // Fall animations - directional falls from BasicAnimations\n      selectedAnim = getAnimation(currentAnimation) ?? null;\n      playbackSpeed = 1.0;\n    } else if (currentAnimation === \"stance_change\") {\n      // Stance change animation\n      selectedAnim = getAnimation(\"idle_stance\") ?? null;\n      playbackSpeed = 1.2; // Slightly faster for responsiveness\n    } else if (currentAnimation === \"hit\") {\n      // Hit reaction - stop animation\n      setAnimState((prev) => ({\n        ...prev,\n        isPlaying: false,\n        currentTime: 0,\n      }));\n      return;\n    } else if (currentAnimation?.startsWith(\"step_\")) {\n      // Tactical step animation\n      selectedAnim = getStepAnimation(currentAnimation) ?? null;\n      playbackSpeed = 1.0;\n\n      // Handle diagonal step rotation\n      if (DIAGONAL_STEP_ANIMATIONS.has(currentAnimation)) {\n        shouldClearDiagonalRotation = false;\n        // Diagonal rotation will be handled by parent component\n        // This hook only manages the flag\n      }\n    } else if (currentAnimation?.startsWith(\"footwork_\")) {\n      // Footwork pattern animation\n      selectedAnim = getFootworkAnimation(currentAnimation) ?? null;\n      playbackSpeed = 1.0;\n    } else if (currentAnimation?.startsWith(\"stance_\")) {\n      // Stance-specific idle animation with proper biomechanics\n      // Use getAnimationByName which searches ALL_ANIMATIONS (includes STANCE_ANIMATIONS)\n      selectedAnim = getAnimationByName(currentAnimation) ?? null;\n      playbackSpeed = 0.5; // Slow breathing animation for stance idle\n    } else {\n      // Idle animation (fallback)\n      selectedAnim = getAnimation(\"idle_stance\") ?? null;\n      playbackSpeed = 0.5; // Slow breathing animation\n    }\n\n    // Apply laterality transformation if selectedAnim exists\n    // laterality directly affects animation mirroring:\n    // \"left\" = left foot forward (왼발서기) → animations mirrored\n    // \"right\" = right foot forward (오른발서기) → base animations (default)\n    if (selectedAnim) {\n      selectedAnim = applyLaterality(selectedAnim, laterality);\n    }\n\n    // Clear diagonal rotation for non-diagonal animations\n    if (shouldClearDiagonalRotation) {\n      setDiagonalRotationY(null);\n    }\n\n    setAnimState({\n      currentAnimation: selectedAnim,\n      currentTime: 0,\n      isPlaying: true,\n      playbackSpeed,\n      previousKeyframeIndex: 0,\n      nextKeyframeIndex: 1,\n    });\n  }, [currentAnimation, attackAnimation, isBlocking, stance, laterality]);\n\n  // Update animation and apply to rig (called at 60fps in useFrame)\n  // PHASE 2: Now uses cached interpolation and batch bone updates\n  const updateRigAnimation = useCallback(\n    (targetRig: SkeletalRig, delta: number) => {\n      if (animState.isPlaying && animState.currentAnimation) {\n        const frameStartTime = performance.now();\n\n        // Advance animation time\n        let newTime = animTimeRef.current + delta * animState.playbackSpeed;\n        let completed = false;\n\n        // Handle looping or completion\n        if (newTime >= animState.currentAnimation.duration) {\n          if (animState.currentAnimation.loop) {\n            newTime = newTime % animState.currentAnimation.duration;\n          } else {\n            newTime = animState.currentAnimation.duration;\n            completed = true;\n          }\n        }\n\n        // Use cached interpolation for 90%+ cache hit rate\n        // Use animation.name as the unique identifier\n        const keyframe = interpolateKeyframeCached(\n          animState.currentAnimation.name,\n          animState.currentAnimation,\n          newTime,\n        );\n\n        if (keyframe) {\n          // Batch update bones (60% faster than individual updates)\n          batchUpdateBones(targetRig, keyframe);\n        }\n\n        // Update time ref\n        animTimeRef.current = newTime;\n\n        // Record performance metrics\n        const frameTime = performance.now() - frameStartTime;\n        performanceMonitor.recordFrame(frameTime);\n\n        // Handle animation completion\n        if (completed) {\n          animTimeRef.current = 0;\n          setAnimState((prev) => ({\n            ...prev,\n            isPlaying: false,\n            currentTime: 0,\n          }));\n\n          // Trigger callback\n          if (onAnimationComplete) {\n            onAnimationComplete();\n          }\n        }\n      }\n    },\n    [animState, onAnimationComplete],\n  );\n\n  return {\n    animState,\n    animTimeRef,\n    updateRigAnimation,\n    diagonalRotationY,\n  };\n}\n"],"mappings":"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"}

package/lib/hooks/useTechniqueSelection.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Custom hook for managing technique selection and execution.
+ *
+ * **Korean**: 기술 선택 관리 (Technique Selection Management)
+ *
+ * Handles technique selection state, keyboard shortcuts, cooldown tracking,
+ * and validation of technique execution based on player resources and stance.
+ *
+ * @module hooks/useTechniqueSelection
+ * @category Combat Hooks
+ * @korean 기술선택훅
+ */
+import { PlayerState } from "../systems/player";
+import { Technique, TechniqueCooldown, TechniqueValidation } from "../types";
+/**
+ * Configuration for technique selection hook.
+ */
+export interface UseTechniqueSelectionConfig {
+    /** Player state with resources and stance */
+    readonly player: PlayerState;
+    /** Whether technique selection is enabled */
+    readonly enabled?: boolean;
+    /** Callback when technique is selected */
+    readonly onTechniqueSelected?: (technique: Technique) => void;
+    /** Callback when technique execution is attempted */
+    readonly onTechniqueExecute?: (technique: Technique) => void;
+}
+/**
+ * Technique selection state and actions.
+ */
+export interface UseTechniqueSelectionResult {
+    /** Available techniques for player archetype */
+    readonly availableTechniques: readonly Technique[];
+    /** Currently selected technique index */
+    readonly selectedIndex: number;
+    /** Active cooldowns for techniques */
+    readonly activeCooldowns: readonly TechniqueCooldown[];
+    /** Select technique by index */
+    readonly selectTechnique: (index: number) => void;
+    /** Execute currently selected technique */
+    readonly executeTechnique: (indexOverride?: number) => void;
+    /** Check if technique can be executed */
+    readonly validateTechnique: (technique: Technique) => TechniqueValidation;
+    /** Check if technique is on cooldown */
+    readonly isOnCooldown: (techniqueId: string) => boolean;
+    /** Get remaining cooldown time in ms */
+    readonly getRemainingCooldown: (techniqueId: string) => number;
+    /** Check if player has sufficient resources */
+    readonly hasResources: (technique: Technique) => boolean;
+}
+/**
+ * Custom hook for managing technique selection and execution.
+ *
+ * @param config - Configuration options
+ * @returns Technique selection state and actions
+ *
+ * @example
+ * ```typescript
+ * const techniqueSelection = useTechniqueSelection({
+ *   player: playerState,
+ *   enabled: !isPaused && combatActive,
+ *   onTechniqueExecute: (technique) => {
+ *     // Execute technique logic
+ *     executeCombatTechnique(playerState, opponent, technique);
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function useTechniqueSelection(config: UseTechniqueSelectionConfig): UseTechniqueSelectionResult;
+export default useTechniqueSelection;
+//# sourceMappingURL=useTechniqueSelection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useTechniqueSelection.d.ts","sourceRoot":"","sources":["../../src/hooks/useTechniqueSelection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAE3B,0CAA0C;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IAE9D,qDAAqD;IACrD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,QAAQ,CAAC,mBAAmB,EAAE,SAAS,SAAS,EAAE,CAAC;IAEnD,yCAAyC;IACzC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,sCAAsC;IACtC,QAAQ,CAAC,eAAe,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAEvD,gCAAgC;IAChC,QAAQ,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAElD,2CAA2C;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,CAAC,aAAa,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5D,yCAAyC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,mBAAmB,CAAC;IAE1E,wCAAwC;IACxC,QAAQ,CAAC,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;IAExD,wCAAwC;IACxC,QAAQ,CAAC,oBAAoB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;IAE/D,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,2BAA2B,GAClC,2BAA2B,CAkP7B;AAED,eAAe,qBAAqB,CAAC"}

package/lib/hooks/useTechniqueSelection.js

@@ -0,0 +1,190 @@
+import { getTechniquesForStanceAndArchetype } from "../data/techniques.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+//#region src/hooks/useTechniqueSelection.ts
+/**
+* Custom hook for managing technique selection and execution.
+*
+* **Korean**: 기술 선택 관리 (Technique Selection Management)
+*
+* Handles technique selection state, keyboard shortcuts, cooldown tracking,
+* and validation of technique execution based on player resources and stance.
+*
+* @module hooks/useTechniqueSelection
+* @category Combat Hooks
+* @korean 기술선택훅
+*/
+/**
+* Custom hook for managing technique selection and execution.
+*
+* @param config - Configuration options
+* @returns Technique selection state and actions
+*
+* @example
+* ```typescript
+* const techniqueSelection = useTechniqueSelection({
+*   player: playerState,
+*   enabled: !isPaused && combatActive,
+*   onTechniqueExecute: (technique) => {
+*     // Execute technique logic
+*     executeCombatTechnique(playerState, opponent, technique);
+*   }
+* });
+* ```
+*
+* @public
+*/
+function useTechniqueSelection(config) {
+	const { player, enabled = true, onTechniqueSelected, onTechniqueExecute } = config;
+	const availableTechniques = useMemo(() => getTechniquesForStanceAndArchetype(player.currentStance, player.archetype), [player.currentStance, player.archetype]);
+	const [selectedIndex, setSelectedIndex] = useState(0);
+	const [activeCooldowns, setActiveCooldowns] = useState([]);
+	const cooldownUpdateIntervalRef = useRef(null);
+	useEffect(() => {
+		if (activeCooldowns.length === 0) {
+			if (cooldownUpdateIntervalRef.current) {
+				clearInterval(cooldownUpdateIntervalRef.current);
+				cooldownUpdateIntervalRef.current = null;
+			}
+			return;
+		}
+		let isMounted = true;
+		cooldownUpdateIntervalRef.current = setInterval(() => {
+			if (!isMounted) return;
+			const now = Date.now();
+			setActiveCooldowns((prev) => {
+				return prev.map((cd) => ({
+					...cd,
+					remaining: Math.max(0, cd.startTime + cd.duration - now)
+				})).filter((cd) => cd.remaining > 0);
+			});
+		}, 100);
+		return () => {
+			isMounted = false;
+			if (cooldownUpdateIntervalRef.current) {
+				clearInterval(cooldownUpdateIntervalRef.current);
+				cooldownUpdateIntervalRef.current = null;
+			}
+		};
+	}, [activeCooldowns.length]);
+	const isOnCooldown = useCallback((techniqueId) => {
+		return activeCooldowns.some((cd) => cd.techniqueId === techniqueId && cd.remaining > 0);
+	}, [activeCooldowns]);
+	const getRemainingCooldown = useCallback((techniqueId) => {
+		return activeCooldowns.find((cd) => cd.techniqueId === techniqueId)?.remaining ?? 0;
+	}, [activeCooldowns]);
+	const hasResources = useCallback((technique) => {
+		return player.stamina >= technique.staminaCost && player.ki >= technique.kiCost;
+	}, [player.stamina, player.ki]);
+	const validateTechnique = useCallback((technique) => {
+		if (player.stamina < technique.staminaCost) return {
+			canExecute: false,
+			reason: "Insufficient stamina",
+			insufficientStamina: true
+		};
+		if (player.ki < technique.kiCost) return {
+			canExecute: false,
+			reason: "Insufficient Ki",
+			insufficientKi: true
+		};
+		if (isOnCooldown(technique.id)) return {
+			canExecute: false,
+			reason: "Technique on cooldown",
+			onCooldown: true
+		};
+		if (technique.requiredStance && player.currentStance !== technique.requiredStance) return {
+			canExecute: false,
+			reason: `Requires ${technique.requiredStance} stance`,
+			wrongStance: true
+		};
+		return { canExecute: true };
+	}, [
+		player.stamina,
+		player.ki,
+		player.currentStance,
+		isOnCooldown
+	]);
+	const selectTechnique = useCallback((index) => {
+		if (index < 0 || index >= availableTechniques.length) return;
+		if (!enabled) return;
+		setSelectedIndex(index);
+		const technique = availableTechniques[index];
+		onTechniqueSelected?.(technique);
+	}, [
+		availableTechniques,
+		enabled,
+		onTechniqueSelected
+	]);
+	const executeTechnique = useCallback((indexOverride) => {
+		if (!enabled) return;
+		const technique = availableTechniques[indexOverride ?? selectedIndex];
+		if (!technique) return;
+		const validation = validateTechnique(technique);
+		if (!validation.canExecute) {
+			console.warn(`Cannot execute technique: ${validation.reason}`);
+			return;
+		}
+		const now = Date.now();
+		const cooldown = {
+			techniqueId: technique.id,
+			startTime: now,
+			duration: technique.cooldown,
+			remaining: technique.cooldown
+		};
+		setActiveCooldowns((prev) => [...prev, cooldown]);
+		onTechniqueExecute?.(technique);
+	}, [
+		enabled,
+		availableTechniques,
+		selectedIndex,
+		validateTechnique,
+		onTechniqueExecute
+	]);
+	useEffect(() => {
+		if (!enabled) return;
+		const handleKeyPress = (e) => {
+			const target = e.target;
+			if (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.isContentEditable) return;
+			const key = e.key.toUpperCase();
+			const techniqueKeys = [
+				"Q",
+				"E",
+				"R",
+				"T",
+				"Y",
+				"F",
+				"G",
+				"Z",
+				"X",
+				"C"
+			];
+			if (techniqueKeys.includes(key)) e.preventDefault();
+			const techniqueIndex = techniqueKeys.indexOf(key);
+			if (techniqueIndex !== -1 && techniqueIndex < availableTechniques.length) {
+				selectTechnique(techniqueIndex);
+				executeTechnique(techniqueIndex);
+			}
+		};
+		window.addEventListener("keydown", handleKeyPress);
+		return () => window.removeEventListener("keydown", handleKeyPress);
+	}, [
+		enabled,
+		availableTechniques,
+		selectTechnique,
+		executeTechnique
+	]);
+	return {
+		availableTechniques,
+		selectedIndex,
+		activeCooldowns,
+		selectTechnique,
+		executeTechnique,
+		validateTechnique,
+		isOnCooldown,
+		getRemainingCooldown,
+		hasResources
+	};
+}
+//#endregion
+export { useTechniqueSelection as default };
+
+//# sourceMappingURL=useTechniqueSelection.js.map

package/lib/hooks/useTechniqueSelection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTechniqueSelection.js","names":[],"sources":["../../src/hooks/useTechniqueSelection.ts"],"sourcesContent":["/**\n * Custom hook for managing technique selection and execution.\n *\n * **Korean**: 기술 선택 관리 (Technique Selection Management)\n *\n * Handles technique selection state, keyboard shortcuts, cooldown tracking,\n * and validation of technique execution based on player resources and stance.\n *\n * @module hooks/useTechniqueSelection\n * @category Combat Hooks\n * @korean 기술선택훅\n */\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { getTechniquesForStanceAndArchetype } from \"../data/techniques\";\nimport { PlayerState } from \"../systems/player\";\nimport {\n  Technique,\n  TechniqueCooldown,\n  TechniqueValidation,\n} from \"../types\";\n\n/**\n * Configuration for technique selection hook.\n */\nexport interface UseTechniqueSelectionConfig {\n  /** Player state with resources and stance */\n  readonly player: PlayerState;\n\n  /** Whether technique selection is enabled */\n  readonly enabled?: boolean;\n\n  /** Callback when technique is selected */\n  readonly onTechniqueSelected?: (technique: Technique) => void;\n\n  /** Callback when technique execution is attempted */\n  readonly onTechniqueExecute?: (technique: Technique) => void;\n}\n\n/**\n * Technique selection state and actions.\n */\nexport interface UseTechniqueSelectionResult {\n  /** Available techniques for player archetype */\n  readonly availableTechniques: readonly Technique[];\n\n  /** Currently selected technique index */\n  readonly selectedIndex: number;\n\n  /** Active cooldowns for techniques */\n  readonly activeCooldowns: readonly TechniqueCooldown[];\n\n  /** Select technique by index */\n  readonly selectTechnique: (index: number) => void;\n\n  /** Execute currently selected technique */\n  readonly executeTechnique: (indexOverride?: number) => void;\n\n  /** Check if technique can be executed */\n  readonly validateTechnique: (technique: Technique) => TechniqueValidation;\n\n  /** Check if technique is on cooldown */\n  readonly isOnCooldown: (techniqueId: string) => boolean;\n\n  /** Get remaining cooldown time in ms */\n  readonly getRemainingCooldown: (techniqueId: string) => number;\n\n  /** Check if player has sufficient resources */\n  readonly hasResources: (technique: Technique) => boolean;\n}\n\n/**\n * Custom hook for managing technique selection and execution.\n *\n * @param config - Configuration options\n * @returns Technique selection state and actions\n *\n * @example\n * ```typescript\n * const techniqueSelection = useTechniqueSelection({\n *   player: playerState,\n *   enabled: !isPaused && combatActive,\n *   onTechniqueExecute: (technique) => {\n *     // Execute technique logic\n *     executeCombatTechnique(playerState, opponent, technique);\n *   }\n * });\n * ```\n *\n * @public\n */\nexport function useTechniqueSelection(\n  config: UseTechniqueSelectionConfig\n): UseTechniqueSelectionResult {\n  const {\n    player,\n    enabled = true,\n    onTechniqueSelected,\n    onTechniqueExecute,\n  } = config;\n\n  // Get available techniques based on player's current stance and archetype\n  const availableTechniques = useMemo(\n    () =>\n      getTechniquesForStanceAndArchetype(\n        player.currentStance,\n        player.archetype\n      ),\n    [player.currentStance, player.archetype]\n  );\n\n  // Selected technique state\n  const [selectedIndex, setSelectedIndex] = useState(0);\n\n  // Cooldown tracking\n  const [activeCooldowns, setActiveCooldowns] = useState<TechniqueCooldown[]>(\n    []\n  );\n\n  // Ref for cleanup\n  const cooldownUpdateIntervalRef = useRef<NodeJS.Timeout | null>(null);\n\n  // Update cooldowns every 100ms\n  useEffect(() => {\n    if (activeCooldowns.length === 0) {\n      // Clear any existing interval when no cooldowns\n      if (cooldownUpdateIntervalRef.current) {\n        clearInterval(cooldownUpdateIntervalRef.current);\n        cooldownUpdateIntervalRef.current = null;\n      }\n      return;\n    }\n\n    let isMounted = true;\n    cooldownUpdateIntervalRef.current = setInterval(() => {\n      if (!isMounted) return;\n      const now = Date.now();\n      setActiveCooldowns((prev) => {\n        return prev\n          .map((cd) => ({\n            ...cd,\n            remaining: Math.max(0, cd.startTime + cd.duration - now),\n          }))\n          .filter((cd) => cd.remaining > 0);\n      });\n    }, 100);\n\n    return () => {\n      isMounted = false;\n      if (cooldownUpdateIntervalRef.current) {\n        clearInterval(cooldownUpdateIntervalRef.current);\n        cooldownUpdateIntervalRef.current = null;\n      }\n    };\n  }, [activeCooldowns.length]);\n\n  // Check if technique is on cooldown\n  const isOnCooldown = useCallback(\n    (techniqueId: string): boolean => {\n      return activeCooldowns.some(\n        (cd) => cd.techniqueId === techniqueId && cd.remaining > 0\n      );\n    },\n    [activeCooldowns]\n  );\n\n  // Get remaining cooldown time\n  const getRemainingCooldown = useCallback(\n    (techniqueId: string): number => {\n      const cooldown = activeCooldowns.find(\n        (cd) => cd.techniqueId === techniqueId\n      );\n      return cooldown?.remaining ?? 0;\n    },\n    [activeCooldowns]\n  );\n\n  // Check if player has sufficient resources\n  const hasResources = useCallback(\n    (technique: Technique): boolean => {\n      return (\n        player.stamina >= technique.staminaCost && player.ki >= technique.kiCost\n      );\n    },\n    [player.stamina, player.ki]\n  );\n\n  // Validate technique execution\n  const validateTechnique = useCallback(\n    (technique: Technique): TechniqueValidation => {\n      // Check stamina\n      if (player.stamina < technique.staminaCost) {\n        return {\n          canExecute: false,\n          reason: \"Insufficient stamina\",\n          insufficientStamina: true,\n        };\n      }\n\n      // Check Ki\n      if (player.ki < technique.kiCost) {\n        return {\n          canExecute: false,\n          reason: \"Insufficient Ki\",\n          insufficientKi: true,\n        };\n      }\n\n      // Check cooldown\n      if (isOnCooldown(technique.id)) {\n        return {\n          canExecute: false,\n          reason: \"Technique on cooldown\",\n          onCooldown: true,\n        };\n      }\n\n      // Check required stance\n      if (\n        technique.requiredStance &&\n        player.currentStance !== technique.requiredStance\n      ) {\n        return {\n          canExecute: false,\n          reason: `Requires ${technique.requiredStance} stance`,\n          wrongStance: true,\n        };\n      }\n\n      return {\n        canExecute: true,\n      };\n    },\n    [player.stamina, player.ki, player.currentStance, isOnCooldown]\n  );\n\n  // Select technique by index\n  const selectTechnique = useCallback(\n    (index: number) => {\n      if (index < 0 || index >= availableTechniques.length) return;\n      if (!enabled) return;\n\n      setSelectedIndex(index);\n      const technique = availableTechniques[index];\n      onTechniqueSelected?.(technique);\n    },\n    [availableTechniques, enabled, onTechniqueSelected]\n  );\n\n  // Execute currently selected technique\n  const executeTechnique = useCallback(\n    (indexOverride?: number) => {\n      if (!enabled) return;\n\n      const index = indexOverride ?? selectedIndex;\n      const technique = availableTechniques[index];\n      if (!technique) return;\n\n      // Validate technique execution\n      const validation = validateTechnique(technique);\n      if (!validation.canExecute) {\n        console.warn(`Cannot execute technique: ${validation.reason}`);\n        return;\n      }\n\n      // Start cooldown\n      const now = Date.now();\n      const cooldown: TechniqueCooldown = {\n        techniqueId: technique.id,\n        startTime: now,\n        duration: technique.cooldown,\n        remaining: technique.cooldown,\n      };\n      setActiveCooldowns((prev) => [...prev, cooldown]);\n\n      // Execute technique\n      onTechniqueExecute?.(technique);\n    },\n    [\n      enabled,\n      availableTechniques,\n      selectedIndex,\n      validateTechnique,\n      onTechniqueExecute,\n    ]\n  );\n\n  // Keyboard shortcuts for technique selection (Q-E-R-T-Y-F-G-Z-X-C)\n  useEffect(() => {\n    if (!enabled) return;\n\n    const handleKeyPress = (e: KeyboardEvent) => {\n      // Ignore keypresses when typing in input fields\n      const target = e.target as HTMLElement;\n      if (\n        target.tagName === \"INPUT\" ||\n        target.tagName === \"TEXTAREA\" ||\n        target.isContentEditable\n      ) {\n        return;\n      }\n\n      const key = e.key.toUpperCase();\n      \n      // Technique keys: Q, E, R, T, Y, F, G, Z, X, C (10 keys around WASD)\n      const techniqueKeys = [\"Q\", \"E\", \"R\", \"T\", \"Y\", \"F\", \"G\", \"Z\", \"X\", \"C\"];\n\n      // Prevent default for all technique keys during combat\n      if (techniqueKeys.includes(key)) {\n        e.preventDefault();\n      }\n\n      // Map keys to technique indices\n      const techniqueIndex = techniqueKeys.indexOf(key);\n      if (techniqueIndex !== -1 && techniqueIndex < availableTechniques.length) {\n        selectTechnique(techniqueIndex);\n        executeTechnique(techniqueIndex);\n      }\n    };\n\n    window.addEventListener(\"keydown\", handleKeyPress);\n    return () => window.removeEventListener(\"keydown\", handleKeyPress);\n  }, [enabled, availableTechniques, selectTechnique, executeTechnique]);\n\n  return {\n    availableTechniques,\n    selectedIndex,\n    activeCooldowns,\n    selectTechnique,\n    executeTechnique,\n    validateTechnique,\n    isOnCooldown,\n    getRemainingCooldown,\n    hasResources,\n  };\n}\n\nexport default useTechniqueSelection;\n"],"mappings":"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"}

package/lib/hooks/useThrottle.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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
+ * ```
+ */
+export declare function useThrottle<T extends (...args: never[]) => void>(callback: T, delay: number): T;
+export default useThrottle;
+//# sourceMappingURL=useThrottle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useThrottle.d.ts","sourceRoot":"","sources":["../../src/hooks/useThrottle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,EAC9D,QAAQ,EAAE,CAAC,EACX,KAAK,EAAE,MAAM,GACZ,CAAC,CAwCH;AAED,eAAe,WAAW,CAAC"}