blacktrigram 0.7.2

package/lib/components/shared/three/anatomy/Hand3D.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hand3D.js","names":[],"sources":["../../../../../src/components/shared/three/anatomy/Hand3D.tsx"],"sourcesContent":["/**\n * Hand3D component with finger geometry for martial arts techniques\n *\n * Renders detailed hand with palm and 5 fingers, supporting multiple\n * Korean martial arts hand poses (Fist, Knife-hand, Spear-hand, etc.).\n *\n * Implements LOD (Level of Detail) for performance optimization:\n * - High detail (<5 units): Full finger bones (4 segments per finger)\n * - Medium detail (5-15 units): Simplified fingers (3 segments)\n * - Low detail (>15 units): No finger detail (hand as single unit)\n *\n * @module components/three/Hand3D\n * @category 3D Components\n * @korean 손3D컴포넌트\n */\n\nimport React, { useEffect, useMemo } from \"react\";\nimport * as THREE from \"three\";\nimport { KOREAN_COLORS } from \"../../../../types/constants\";\nimport type {\n  FingerCurl,\n  HandLODConfig,\n  HandPoseType,\n  HandSide,\n} from \"../../../../types/hand-animation\";\n\n/**\n * Props for Hand3D component\n *\n * @public\n * @korean 손3D속성\n */\nexport interface Hand3DProps {\n  /**\n   * Hand side (left or right)\n   * @korean 손쪽\n   */\n  readonly side: HandSide;\n\n  /**\n   * Current hand pose\n   * @korean 현재손자세\n   */\n  readonly pose: HandPoseType;\n\n  /**\n   * Finger curl amounts (0-1 per finger)\n   * @korean 손가락구부림\n   */\n  readonly fingerCurl: FingerCurl;\n\n  /**\n   * Distance from camera for LOD\n   * @korean 카메라거리\n   */\n  readonly distanceFromCamera: number;\n\n  /**\n   * Wrist rotation\n   * @korean 손목회전\n   */\n  readonly wristRotation: THREE.Euler;\n\n  /**\n   * Whether hand is highlighted for vital point targeting\n   * @korean 표시여부\n   */\n  readonly isHighlighted?: boolean;\n\n  /**\n   * Highlight mode for striking surfaces\n   * @korean 표시모드\n   */\n  readonly highlightMode?:\n    | \"none\"\n    | \"knuckles\"\n    | \"palm\"\n    | \"knife_edge\"\n    | \"fingertips\"\n    | null;\n\n  /**\n   * Base skin color\n   * @korean 피부색\n   */\n  readonly skinColor?: number;\n\n  /**\n   * Scale multiplier\n   * @korean 크기배율\n   */\n  readonly scale?: number;\n}\n\n/**\n * Determine LOD config based on camera distance\n *\n * @param distance - Distance from camera\n * @returns LOD configuration\n * @korean LOD설정결정\n */\nconst getLODConfig = (distance: number): HandLODConfig => {\n  if (distance < 5) {\n    return {\n      detailLevel: \"high\",\n      distanceThresholds: { high: 5, medium: 15, low: 100 },\n      renderFingers: true,\n      fingerSegments: 4,\n    };\n  } else if (distance < 15) {\n    return {\n      detailLevel: \"medium\",\n      distanceThresholds: { high: 5, medium: 15, low: 100 },\n      renderFingers: true,\n      fingerSegments: 3,\n    };\n  } else {\n    return {\n      detailLevel: \"low\",\n      distanceThresholds: { high: 5, medium: 15, low: 100 },\n      renderFingers: false,\n      fingerSegments: 0,\n    };\n  }\n};\n\n/**\n * Finger segment component\n *\n * Renders a single finger segment (proximal, intermediate, or distal phalanx).\n *\n * @korean 손가락세그먼트컴포넌트\n */\ninterface FingerSegmentProps {\n  readonly position: [number, number, number];\n  readonly rotation: [number, number, number];\n  readonly length: number;\n  readonly radius: number;\n  readonly color: number;\n}\n\nconst FingerSegment: React.FC<FingerSegmentProps> = ({\n  position,\n  rotation,\n  length,\n  radius,\n  color,\n}) => {\n  // Memoize material to avoid recreating on every render\n  const material = useMemo(\n    () =>\n      new THREE.MeshPhysicalMaterial({\n        color: color,\n        metalness: 0,\n        roughness: 0.6,\n        clearcoat: 0.3,\n        clearcoatRoughness: 0.5,\n        // PBR skin properties\n        transmission: 0,\n        thickness: 0.1,\n        ior: 1.4, // Index of refraction for skin\n        sheen: 0.1, // Subtle skin sheen\n        sheenRoughness: 0.8,\n        // Subtle emissive for alive appearance\n        emissive: new THREE.Color(color),\n        emissiveIntensity: 0.02,\n      }),\n    [color],\n  );\n\n  // Dispose material on unmount to prevent memory leaks\n  useEffect(() => {\n    return () => {\n      material.dispose();\n    };\n  }, [material]);\n\n  return (\n    <mesh position={position} rotation={rotation} castShadow receiveShadow>\n      <capsuleGeometry args={[radius, length, 4, 8]} />\n      <primitive object={material} attach=\"material\" />\n    </mesh>\n  );\n};\n\n/**\n * Single finger component with curl animation\n *\n * @korean 손가락컴포넌트\n */\ninterface FingerProps {\n  readonly fingerName: string;\n  readonly basePosition: [number, number, number];\n  readonly curl: number;\n  readonly segments: number;\n  readonly isHighlighted: boolean;\n  readonly skinColor: number;\n}\n\nconst Finger: React.FC<FingerProps> = ({\n  fingerName,\n  basePosition,\n  curl,\n  segments,\n  isHighlighted,\n  skinColor,\n}) => {\n  // Finger dimensions based on anatomical proportions\n  // For ~180cm person: index ~7cm, middle ~8cm, ring ~7.5cm, pinky ~6cm, thumb ~5cm\n  // These dimensions are in METERS for Three.js\n  const dimensions = useMemo(() => {\n    // Finger segment lengths based on anatomical proportions (in meters)\n    // Total finger length: proximal + intermediate + distal\n    // Index: ~7cm total = 0.03 + 0.022 + 0.018\n    const baseLength =\n      fingerName === \"thumb\"\n        ? 0.025 // Thumb proximal is shorter\n        : fingerName === \"pinky\"\n          ? 0.022 // Pinky is shorter\n          : 0.03; // Other fingers\n\n    // Finger thickness: ~1.5-1.8cm diameter (0.75-0.9cm radius)\n    const baseRadius =\n      fingerName === \"pinky\"\n        ? 0.006 // Pinky is thinner\n        : fingerName === \"thumb\"\n          ? 0.009 // Thumb is thicker\n          : 0.007;\n\n    return {\n      proximalLength: baseLength,\n      intermediateLength: baseLength * 0.75,\n      distalLength: baseLength * 0.55,\n      radius: baseRadius,\n    };\n  }, [fingerName]);\n\n  // Calculate curl rotations for each segment\n  // Curl value 0-1 maps to rotation angles\n  // These factors represent biomechanical constraints of human finger joints\n  const PROXIMAL_CURL_FACTOR = 0.5; // Proximal joint bends less (0-90 degrees)\n  const INTERMEDIATE_CURL_FACTOR = 0.7; // Middle joint bends moderately (0-126 degrees)\n  const DISTAL_CURL_FACTOR = 1.0; // Distal joint bends most (0-180 degrees)\n\n  const proximalCurl = curl * PROXIMAL_CURL_FACTOR * Math.PI;\n  const intermediateCurl = curl * INTERMEDIATE_CURL_FACTOR * Math.PI;\n  const distalCurl = curl * DISTAL_CURL_FACTOR * Math.PI;\n\n  // Highlight with color change only (NO glow/emissive)\n  const highlightColor = isHighlighted ? KOREAN_COLORS.ACCENT_RED : skinColor;\n\n  return (\n    <group position={basePosition}>\n      {/* Proximal phalanx (knuckle joint) */}\n      <FingerSegment\n        position={[0, dimensions.proximalLength / 2, 0]}\n        rotation={[0, 0, proximalCurl]}\n        length={dimensions.proximalLength}\n        radius={dimensions.radius}\n        color={highlightColor}\n      />\n\n      {/* Intermediate phalanx (middle joint) - skip for thumb or low detail */}\n      {segments >= 4 && fingerName !== \"thumb\" && (\n        <FingerSegment\n          position={[\n            0,\n            dimensions.proximalLength + dimensions.intermediateLength / 2,\n            0,\n          ]}\n          rotation={[0, 0, intermediateCurl]}\n          length={dimensions.intermediateLength}\n          radius={dimensions.radius * 0.9}\n          color={highlightColor}\n        />\n      )}\n\n      {/* Distal phalanx (fingertip) */}\n      <FingerSegment\n        position={[\n          0,\n          dimensions.proximalLength +\n            (fingerName !== \"thumb\" && segments >= 4\n              ? dimensions.intermediateLength\n              : 0) +\n            dimensions.distalLength / 2,\n          0,\n        ]}\n        rotation={[0, 0, distalCurl]}\n        length={dimensions.distalLength}\n        radius={dimensions.radius * 0.7}\n        color={highlightColor}\n      />\n    </group>\n  );\n};\n\n/**\n * Hand3D Component\n *\n * Complete hand with palm and 5 fingers, supporting Korean martial arts\n * hand poses with LOD optimization for performance.\n *\n * @example\n * ```tsx\n * <Hand3D\n *   side=\"right\"\n *   pose={HandPoseType.FIST}\n *   fingerCurl={{\n *     thumb: 0.8,\n *     index: 1.0,\n *     middle: 1.0,\n *     ring: 1.0,\n *     pinky: 1.0,\n *   }}\n *   distanceFromCamera={3}\n *   wristRotation={new THREE.Euler(0, 0, 0)}\n *   isHighlighted={false}\n *   highlightMode=\"knuckles\"\n * />\n * ```\n *\n * @korean 손3D컴포넌트\n */\nexport const Hand3D: React.FC<Hand3DProps> = ({\n  side,\n  // pose, // TODO: Reserved for future pose-specific hand adjustments (e.g., different palm sizes per pose)\n  fingerCurl,\n  distanceFromCamera,\n  wristRotation,\n  isHighlighted = false,\n  highlightMode = null,\n  skinColor = 0xffdbac,\n  scale = 1.0,\n}) => {\n  // Determine LOD based on distance\n  const lodConfig = useMemo(\n    () => getLODConfig(distanceFromCamera),\n    [distanceFromCamera],\n  );\n\n  // Hand orientation\n  const sideMultiplier = side === \"left\" ? -1 : 1;\n\n  // Palm dimensions (realistic for ~180cm person)\n  // Palm width: ~8-9cm, Palm length (metacarpal area): ~9-10cm\n  // Total hand length including palm and fingers: ~18-19cm\n  // These dimensions are in METERS for Three.js\n  const palmWidth = 0.085 * scale; // 8.5cm palm width\n  const palmLength = 0.095 * scale; // 9.5cm palm/metacarpal length\n  const palmThickness = 0.025 * scale; // 2.5cm palm thickness\n\n  // Determine which parts to highlight\n  const highlightKnuckles = highlightMode === \"knuckles\";\n  const highlightPalm = highlightMode === \"palm\";\n  const highlightKnifeEdge = highlightMode === \"knife_edge\";\n  const highlightFingertips = highlightMode === \"fingertips\";\n\n  // Palm color (highlight with brighter color, NO emissive/glow)\n  const palmColor =\n    isHighlighted && highlightPalm ? KOREAN_COLORS.ACCENT_GOLD : skinColor;\n\n  return (\n    <group\n      rotation={[wristRotation.x, wristRotation.y, wristRotation.z]}\n      name={`hand-3d-${side}`}\n    >\n      {/* Wrist connector - smooth sphere bridging forearm to palm */}\n      <mesh\n        position={[0, -palmLength * 0.45, 0]}\n        castShadow\n        receiveShadow\n        name={`hand-wrist-bridge-${side}`}\n      >\n        <sphereGeometry args={[palmWidth * 0.35, 8, 8]} />\n        <meshPhysicalMaterial\n          color={skinColor}\n          metalness={0}\n          roughness={0.6}\n          clearcoat={0.3}\n          clearcoatRoughness={0.5}\n          transmission={0}\n          thickness={0.1}\n          ior={1.4}\n          sheen={0.1}\n          sheenRoughness={0.8}\n          emissive={new THREE.Color(0xff6040)}\n          emissiveIntensity={0.02}\n        />\n      </mesh>\n\n      {/* Palm */}\n      <mesh castShadow receiveShadow name={`hand-palm-${side}`}>\n        <boxGeometry args={[palmWidth, palmLength, palmThickness]} />\n        <meshPhysicalMaterial\n          color={palmColor}\n          metalness={0}\n          roughness={0.6}\n          clearcoat={0.3}\n          clearcoatRoughness={0.5}\n          // PBR skin properties\n          transmission={0}\n          thickness={0.1}\n          ior={1.4} // Index of refraction for skin\n          sheen={0.1} // Subtle skin sheen\n          sheenRoughness={0.8}\n          // Subtle emissive for alive appearance\n          emissive={new THREE.Color(0xff6040)}\n          emissiveIntensity={0.02}\n        />\n      </mesh>\n\n      {/* Knife edge highlight (pinky side of hand) - emissive highlight for visibility */}\n      {isHighlighted && highlightKnifeEdge && (\n        <mesh\n          position={[(-palmWidth / 2) * sideMultiplier, 0, 0]}\n          castShadow\n          receiveShadow\n          name={`hand-knife-edge-${side}`}\n        >\n          <boxGeometry args={[0.005, palmLength, palmThickness]} />\n          <meshPhysicalMaterial\n            color={KOREAN_COLORS.ACCENT_GOLD}\n            metalness={0.8}\n            roughness={0.2}\n            clearcoat={0.8}\n            clearcoatRoughness={0.1}\n            // High emissive for striking surface visibility\n            emissive={KOREAN_COLORS.ACCENT_GOLD}\n            emissiveIntensity={2.0}\n            transmission={0}\n            thickness={0.05}\n          />\n        </mesh>\n      )}\n\n      {/* Render fingers based on LOD */}\n      {lodConfig.renderFingers && (\n        <>\n          {/* Thumb - offset toward palm center and forward */}\n          <Finger\n            fingerName=\"thumb\"\n            basePosition={[\n              0.015 * sideMultiplier * scale,\n              palmLength / 2,\n              palmThickness / 2,\n            ]}\n            curl={fingerCurl.thumb}\n            segments={3} // Thumb has no intermediate phalanx\n            isHighlighted={isHighlighted && highlightFingertips}\n            skinColor={skinColor}\n          />\n\n          {/* Index finger */}\n          <Finger\n            fingerName=\"index\"\n            basePosition={[0.015 * sideMultiplier * scale, palmLength / 2, 0]}\n            curl={fingerCurl.index}\n            segments={lodConfig.fingerSegments}\n            isHighlighted={\n              isHighlighted && (highlightFingertips || highlightKnuckles)\n            }\n            skinColor={skinColor}\n          />\n\n          {/* Middle finger */}\n          <Finger\n            fingerName=\"middle\"\n            basePosition={[0.005 * sideMultiplier * scale, palmLength / 2, 0]}\n            curl={fingerCurl.middle}\n            segments={lodConfig.fingerSegments}\n            isHighlighted={\n              isHighlighted && (highlightFingertips || highlightKnuckles)\n            }\n            skinColor={skinColor}\n          />\n\n          {/* Ring finger */}\n          <Finger\n            fingerName=\"ring\"\n            basePosition={[-0.005 * sideMultiplier * scale, palmLength / 2, 0]}\n            curl={fingerCurl.ring}\n            segments={lodConfig.fingerSegments}\n            isHighlighted={\n              isHighlighted && (highlightFingertips || highlightKnuckles)\n            }\n            skinColor={skinColor}\n          />\n\n          {/* Pinky finger */}\n          <Finger\n            fingerName=\"pinky\"\n            basePosition={[-0.015 * sideMultiplier * scale, palmLength / 2, 0]}\n            curl={fingerCurl.pinky}\n            segments={lodConfig.fingerSegments}\n            isHighlighted={\n              isHighlighted && (highlightFingertips || highlightKnuckles)\n            }\n            skinColor={skinColor}\n          />\n        </>\n      )}\n\n      {/* Low detail: just palm, no fingers */}\n      {!lodConfig.renderFingers && (\n        <mesh\n          position={[0, palmLength / 2, 0]}\n          castShadow\n          receiveShadow\n          name={`hand-simple-${side}`}\n        >\n          <capsuleGeometry args={[palmWidth / 2, palmLength * 0.3, 4, 8]} />\n          <meshStandardMaterial\n            color={skinColor}\n            metalness={0.1}\n            roughness={0.8}\n          />\n        </mesh>\n      )}\n    </group>\n  );\n};\n\nexport default Hand3D;\n"],"mappings":"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"}

package/lib/components/shared/three/effects/ActionFeedback.d.ts

@@ -0,0 +1,78 @@
+/**
+ * ActionFeedback - Combat action feedback display component
+ *
+ * Displays action indicators like "Perfect!", "Critical!", "Blocked", "Dodged",
+ * and technique names with Korean-English bilingual text.
+ *
+ * Uses Html overlay from @react-three/drei for rendering within 3D scenes.
+ *
+ * @module components/shared/three/effects/ActionFeedback
+ * @category Shared Effects
+ * @korean 액션피드백
+ */
+import React from "react";
+import { ActionFeedback as ActionFeedbackData } from "../../../../hooks/useActionFeedback";
+import { type PhysicsArenaBounds } from "../../../../types/PhysicsTypes";
+/**
+ * Props for the ActionFeedback component
+ */
+export interface ActionFeedbackProps {
+    /** Array of action feedbacks to display */
+    readonly feedbacks: readonly ActionFeedbackData[];
+    /** Whether to use mobile-optimized sizing */
+    readonly isMobile?: boolean;
+    /** Arena bounds for 3D positioning (physics-first with meter dimensions) */
+    readonly arenaBounds?: PhysicsArenaBounds;
+    /** Duration of animation in ms (default: 1200) */
+    readonly animationDuration?: number;
+}
+/**
+ * Props for technique name display
+ */
+export interface TechniqueNameProps {
+    /** Korean technique name */
+    readonly korean: string;
+    /** English technique name */
+    readonly english: string;
+    /** Whether to use mobile-optimized sizing */
+    readonly isMobile?: boolean;
+    /** Animation duration in ms */
+    readonly duration?: number;
+    /** Callback when animation completes */
+    readonly onComplete?: () => void;
+}
+/**
+ * ActionFeedback Component
+ *
+ * Renders multiple action feedback indicators in the 3D scene.
+ * Each indicator floats upward and fades out over time.
+ *
+ * @example
+ * ```tsx
+ * <ActionFeedback
+ *   feedbacks={actionFeedbacks}
+ *   isMobile={isMobile}
+ *   arenaBounds={arenaBounds}
+ * />
+ * ```
+ */
+export declare const ActionFeedback: React.FC<ActionFeedbackProps>;
+/**
+ * TechniqueName Component
+ *
+ * Displays the current technique name in Korean and English.
+ * Appears at the center of the screen with a dramatic animation.
+ *
+ * @example
+ * ```tsx
+ * <TechniqueName
+ *   korean="천둥벽력"
+ *   english="Thunder Strike"
+ *   isMobile={isMobile}
+ *   duration={2000}
+ * />
+ * ```
+ */
+export declare const TechniqueName: React.FC<TechniqueNameProps>;
+export default ActionFeedback;
+//# sourceMappingURL=ActionFeedback.d.ts.map

package/lib/components/shared/three/effects/ActionFeedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionFeedback.d.ts","sourceRoot":"","sources":["../../../../../src/components/shared/three/effects/ActionFeedback.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAoC,MAAM,OAAO,CAAC;AACzD,OAAO,EACL,cAAc,IAAI,kBAAkB,EAErC,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAgC,KAAK,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AASvG;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAClD,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CAClC;AAkID;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAsBxD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CA6GtD,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/lib/components/shared/three/effects/ActionFeedback.js

@@ -0,0 +1,236 @@
+import { KOREAN_COLORS } from "../../../../types/constants/colors.js";
+import { FONT_FAMILY } from "../../../../types/constants/typography.js";
+import "../../../../types/constants/index.js";
+import { DEFAULT_PHYSICS_ARENA_BOUNDS } from "../../../../types/PhysicsTypes.js";
+import { hexColorToCSS, hexToRgbaString } from "../../../../utils/colorUtils.js";
+import { useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { Html } from "@react-three/drei";
+//#region src/components/shared/three/effects/ActionFeedback.tsx
+/**
+* ActionFeedback - Combat action feedback display component
+*
+* Displays action indicators like "Perfect!", "Critical!", "Blocked", "Dodged",
+* and technique names with Korean-English bilingual text.
+*
+* Uses Html overlay from @react-three/drei for rendering within 3D scenes.
+*
+* @module components/shared/three/effects/ActionFeedback
+* @category Shared Effects
+* @korean 액션피드백
+*/
+/** Fade in completes at 20% of total duration */
+var FADE_IN_THRESHOLD = .2;
+/** Fade out begins at 80% of total duration */
+var FADE_OUT_THRESHOLD = .8;
+/**
+* Get color based on feedback type
+*/
+function getFeedbackColor(type) {
+	switch (type) {
+		case "perfect": return hexColorToCSS(KOREAN_COLORS.ACCENT_GOLD);
+		case "critical": return hexColorToCSS(KOREAN_COLORS.ACCENT_RED);
+		case "blocked": return hexColorToCSS(KOREAN_COLORS.ACCENT_CYAN);
+		case "dodged": return hexColorToCSS(KOREAN_COLORS.ACCENT_GREEN);
+		case "technique": return hexColorToCSS(KOREAN_COLORS.SECONDARY_MAGENTA);
+		case "combo_milestone": return hexColorToCSS(KOREAN_COLORS.ACCENT_GOLD);
+		default: return hexColorToCSS(KOREAN_COLORS.TEXT_PRIMARY);
+	}
+}
+/**
+* Get glow color based on feedback type
+*/
+function getGlowColor(type) {
+	switch (type) {
+		case "perfect": return hexToRgbaString(KOREAN_COLORS.ACCENT_GOLD, .8);
+		case "critical": return hexToRgbaString(KOREAN_COLORS.ACCENT_RED, .8);
+		case "blocked": return hexToRgbaString(KOREAN_COLORS.ACCENT_CYAN, .6);
+		case "dodged": return hexToRgbaString(KOREAN_COLORS.ACCENT_GREEN, .6);
+		case "technique": return hexToRgbaString(KOREAN_COLORS.SECONDARY_MAGENTA, .8);
+		case "combo_milestone": return hexToRgbaString(KOREAN_COLORS.ACCENT_GOLD, .8);
+		default: return hexToRgbaString(KOREAN_COLORS.TEXT_PRIMARY, .4);
+	}
+}
+var SingleFeedback = ({ feedback, isMobile, arenaBounds, animationDuration }) => {
+	const [progress, setProgress] = useState(0);
+	const startTimeRef = useRef(feedback.timestamp);
+	const halfWidth = arenaBounds.worldWidthMeters / 2;
+	const halfDepth = arenaBounds.worldDepthMeters / 2;
+	const clampedX = Math.min(halfWidth, Math.max(-halfWidth, feedback.position.x));
+	const clampedZ = Math.min(halfDepth, Math.max(-halfDepth, feedback.position.y));
+	const position3D = [
+		clampedX,
+		2.5 + progress * 1.5,
+		clampedZ
+	];
+	useFrame(() => {
+		const elapsed = Date.now() - startTimeRef.current;
+		setProgress(Math.min(elapsed / animationDuration, 1));
+	});
+	if (progress >= 1) return null;
+	const opacity = 1 - progress;
+	const scale = 1 + (progress < .2 ? progress * 2 : (1 - progress) * .5);
+	const fontSize = isMobile ? 18 : 24;
+	const color = getFeedbackColor(feedback.type);
+	const glowColor = getGlowColor(feedback.type);
+	return /* @__PURE__ */ jsx(Html, {
+		position: position3D,
+		center: true,
+		distanceFactor: 10,
+		style: { pointerEvents: "none" },
+		children: /* @__PURE__ */ jsxs("div", {
+			"data-testid": `action-feedback-${feedback.id}`,
+			style: {
+				fontSize: `${fontSize}px`,
+				fontWeight: "bold",
+				fontFamily: FONT_FAMILY.KOREAN,
+				color,
+				opacity,
+				transform: `scale(${scale})`,
+				textShadow: `
+            0 0 10px ${glowColor},
+            0 0 20px ${glowColor},
+            2px 2px 4px rgba(0, 0, 0, 0.9)
+          `,
+				whiteSpace: "nowrap",
+				userSelect: "none",
+				textAlign: "center"
+			},
+			children: [
+				feedback.textKorean,
+				" | ",
+				feedback.text
+			]
+		})
+	});
+};
+/**
+* ActionFeedback Component
+*
+* Renders multiple action feedback indicators in the 3D scene.
+* Each indicator floats upward and fades out over time.
+*
+* @example
+* ```tsx
+* <ActionFeedback
+*   feedbacks={actionFeedbacks}
+*   isMobile={isMobile}
+*   arenaBounds={arenaBounds}
+* />
+* ```
+*/
+var ActionFeedback = ({ feedbacks, isMobile = false, arenaBounds = DEFAULT_PHYSICS_ARENA_BOUNDS, animationDuration = 1200 }) => {
+	const visibleFeedbacks = useMemo(() => [...feedbacks], [feedbacks]);
+	return /* @__PURE__ */ jsx("group", {
+		"data-testid": "action-feedback-container",
+		children: visibleFeedbacks.map((feedback) => /* @__PURE__ */ jsx(SingleFeedback, {
+			feedback,
+			isMobile,
+			arenaBounds,
+			animationDuration
+		}, feedback.id))
+	});
+};
+/**
+* TechniqueName Component
+*
+* Displays the current technique name in Korean and English.
+* Appears at the center of the screen with a dramatic animation.
+*
+* @example
+* ```tsx
+* <TechniqueName
+*   korean="천둥벽력"
+*   english="Thunder Strike"
+*   isMobile={isMobile}
+*   duration={2000}
+* />
+* ```
+*/
+var TechniqueName = ({ korean, english, isMobile = false, duration = 2e3, onComplete }) => {
+	const [opacity, setOpacity] = useState(0);
+	const [scale, setScale] = useState(.5);
+	const [startTime] = useState(() => Date.now());
+	const startTimeRef = useRef(startTime);
+	useFrame(() => {
+		const elapsed = Date.now() - startTimeRef.current;
+		const progress = Math.min(elapsed / duration, 1);
+		if (progress < FADE_IN_THRESHOLD) {
+			const fadeInProgress = progress / FADE_IN_THRESHOLD;
+			setOpacity(fadeInProgress);
+			setScale(.5 + fadeInProgress * .5);
+		} else if (progress < FADE_OUT_THRESHOLD) {
+			setOpacity(1);
+			setScale(1);
+		} else {
+			const fadeOutProgress = (progress - FADE_OUT_THRESHOLD) / (1 - FADE_OUT_THRESHOLD);
+			setOpacity(1 - fadeOutProgress);
+			setScale(1 + fadeOutProgress * .2);
+		}
+		if (progress >= 1 && onComplete) onComplete();
+	});
+	const position3D = [
+		0,
+		3.5,
+		0
+	];
+	const mainFontSize = isMobile ? 28 : 42;
+	const subFontSize = isMobile ? 16 : 24;
+	const color = hexColorToCSS(KOREAN_COLORS.SECONDARY_MAGENTA);
+	const glowColor = hexToRgbaString(KOREAN_COLORS.SECONDARY_MAGENTA, .8);
+	return /* @__PURE__ */ jsx(Html, {
+		position: position3D,
+		center: true,
+		distanceFactor: 10,
+		style: { pointerEvents: "none" },
+		children: /* @__PURE__ */ jsxs("div", {
+			"data-testid": "technique-name",
+			style: {
+				textAlign: "center",
+				opacity,
+				transform: `scale(${scale})`,
+				transition: "transform 0.1s ease-out"
+			},
+			children: [
+				/* @__PURE__ */ jsx("div", {
+					style: {
+						fontSize: `${mainFontSize}px`,
+						fontWeight: "bold",
+						fontFamily: FONT_FAMILY.KOREAN,
+						color,
+						textShadow: `
+              0 0 15px ${glowColor},
+              0 0 30px ${glowColor},
+              3px 3px 6px rgba(0, 0, 0, 0.9)
+            `,
+						letterSpacing: "4px"
+					},
+					children: korean
+				}),
+				/* @__PURE__ */ jsx("div", { style: {
+					width: "60px",
+					height: "2px",
+					background: `linear-gradient(90deg, transparent, ${color}, transparent)`,
+					margin: "8px auto"
+				} }),
+				/* @__PURE__ */ jsx("div", {
+					style: {
+						fontSize: `${subFontSize}px`,
+						fontWeight: "bold",
+						fontFamily: FONT_FAMILY.KOREAN,
+						color: hexColorToCSS(KOREAN_COLORS.TEXT_SECONDARY),
+						textShadow: "2px 2px 4px rgba(0, 0, 0, 0.8)",
+						letterSpacing: "2px",
+						textTransform: "uppercase"
+					},
+					children: english
+				})
+			]
+		})
+	});
+};
+//#endregion
+export { TechniqueName, ActionFeedback as default };
+
+//# sourceMappingURL=ActionFeedback.js.map

package/lib/components/shared/three/effects/ActionFeedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionFeedback.js","names":[],"sources":["../../../../../src/components/shared/three/effects/ActionFeedback.tsx"],"sourcesContent":["/**\n * ActionFeedback - Combat action feedback display component\n *\n * Displays action indicators like \"Perfect!\", \"Critical!\", \"Blocked\", \"Dodged\",\n * and technique names with Korean-English bilingual text.\n *\n * Uses Html overlay from @react-three/drei for rendering within 3D scenes.\n *\n * @module components/shared/three/effects/ActionFeedback\n * @category Shared Effects\n * @korean 액션피드백\n */\n\nimport { Html } from \"@react-three/drei\";\nimport { useFrame } from \"@react-three/fiber\";\nimport React, { useMemo, useRef, useState } from \"react\";\nimport {\n  ActionFeedback as ActionFeedbackData,\n  ActionFeedbackType,\n} from \"../../../../hooks/useActionFeedback\";\nimport { FONT_FAMILY, KOREAN_COLORS } from \"../../../../types/constants\";\nimport { DEFAULT_PHYSICS_ARENA_BOUNDS, type PhysicsArenaBounds } from \"../../../../types/PhysicsTypes\";\nimport { hexColorToCSS, hexToRgbaString } from \"../../../../utils/colorUtils\";\n\n// Animation phase thresholds (as percentage of total duration)\n/** Fade in completes at 20% of total duration */\nconst FADE_IN_THRESHOLD = 0.2;\n/** Fade out begins at 80% of total duration */\nconst FADE_OUT_THRESHOLD = 0.8;\n\n/**\n * Props for the ActionFeedback component\n */\nexport interface ActionFeedbackProps {\n  /** Array of action feedbacks to display */\n  readonly feedbacks: readonly ActionFeedbackData[];\n  /** Whether to use mobile-optimized sizing */\n  readonly isMobile?: boolean;\n  /** Arena bounds for 3D positioning (physics-first with meter dimensions) */\n  readonly arenaBounds?: PhysicsArenaBounds;\n  /** Duration of animation in ms (default: 1200) */\n  readonly animationDuration?: number;\n}\n\n/**\n * Props for technique name display\n */\nexport interface TechniqueNameProps {\n  /** Korean technique name */\n  readonly korean: string;\n  /** English technique name */\n  readonly english: string;\n  /** Whether to use mobile-optimized sizing */\n  readonly isMobile?: boolean;\n  /** Animation duration in ms */\n  readonly duration?: number;\n  /** Callback when animation completes */\n  readonly onComplete?: () => void;\n}\n\n/**\n * Get color based on feedback type\n */\nfunction getFeedbackColor(type: ActionFeedbackType): string {\n  switch (type) {\n    case \"perfect\":\n      return hexColorToCSS(KOREAN_COLORS.ACCENT_GOLD);\n    case \"critical\":\n      return hexColorToCSS(KOREAN_COLORS.ACCENT_RED);\n    case \"blocked\":\n      return hexColorToCSS(KOREAN_COLORS.ACCENT_CYAN);\n    case \"dodged\":\n      return hexColorToCSS(KOREAN_COLORS.ACCENT_GREEN);\n    case \"technique\":\n      return hexColorToCSS(KOREAN_COLORS.SECONDARY_MAGENTA);\n    case \"combo_milestone\":\n      return hexColorToCSS(KOREAN_COLORS.ACCENT_GOLD);\n    default:\n      return hexColorToCSS(KOREAN_COLORS.TEXT_PRIMARY);\n  }\n}\n\n/**\n * Get glow color based on feedback type\n */\nfunction getGlowColor(type: ActionFeedbackType): string {\n  switch (type) {\n    case \"perfect\":\n      return hexToRgbaString(KOREAN_COLORS.ACCENT_GOLD, 0.8);\n    case \"critical\":\n      return hexToRgbaString(KOREAN_COLORS.ACCENT_RED, 0.8);\n    case \"blocked\":\n      return hexToRgbaString(KOREAN_COLORS.ACCENT_CYAN, 0.6);\n    case \"dodged\":\n      return hexToRgbaString(KOREAN_COLORS.ACCENT_GREEN, 0.6);\n    case \"technique\":\n      return hexToRgbaString(KOREAN_COLORS.SECONDARY_MAGENTA, 0.8);\n    case \"combo_milestone\":\n      return hexToRgbaString(KOREAN_COLORS.ACCENT_GOLD, 0.8);\n    default:\n      return hexToRgbaString(KOREAN_COLORS.TEXT_PRIMARY, 0.4);\n  }\n}\n\n/**\n * Individual action feedback display\n */\ninterface SingleFeedbackProps {\n  readonly feedback: ActionFeedbackData;\n  readonly isMobile: boolean;\n  readonly arenaBounds: PhysicsArenaBounds;\n  readonly animationDuration: number;\n}\n\nconst SingleFeedback: React.FC<SingleFeedbackProps> = ({\n  feedback,\n  isMobile,\n  arenaBounds,\n  animationDuration,\n}) => {\n  const [progress, setProgress] = useState(0);\n  const startTimeRef = useRef(feedback.timestamp);\n\n  // Calculate 3D position from meter-based coordinates (physics-first architecture)\n  // Position is in meters relative to arena center (0, 0)\n  // Player models use meter coordinates directly: position={[playerPos.x, 0, playerPos.y]}\n  // So we use meter coordinates directly too for alignment\n  const halfWidth = arenaBounds.worldWidthMeters / 2;\n  const halfDepth = arenaBounds.worldDepthMeters / 2;\n  \n  // Clamp position to arena boundaries in meters\n  const clampedX = Math.min(halfWidth, Math.max(-halfWidth, feedback.position.x));\n  const clampedZ = Math.min(halfDepth, Math.max(-halfDepth, feedback.position.y));\n  \n  // Use clamped meter coordinates directly in 3D space (no remapping)\n  const x = clampedX; // Meter position X\n  const y = 2.5 + progress * 1.5; // Float upward\n  const z = clampedZ; // Meter position Z (depth)\n  const position3D: [number, number, number] = [x, y, z];\n\n  // Update progress using useFrame\n  useFrame(() => {\n    const elapsed = Date.now() - startTimeRef.current;\n    const newProgress = Math.min(elapsed / animationDuration, 1);\n    setProgress(newProgress);\n  });\n\n  // Don't render if expired\n  if (progress >= 1) return null;\n\n  const opacity = 1 - progress;\n  const scale = 1 + (progress < 0.2 ? progress * 2 : (1 - progress) * 0.5);\n  const fontSize = isMobile ? 18 : 24;\n  const color = getFeedbackColor(feedback.type);\n  const glowColor = getGlowColor(feedback.type);\n\n  return (\n    <Html\n      position={position3D}\n      center\n      distanceFactor={10}\n      style={{ pointerEvents: \"none\" }}\n    >\n      <div\n        data-testid={`action-feedback-${feedback.id}`}\n        style={{\n          fontSize: `${fontSize}px`,\n          fontWeight: \"bold\",\n          fontFamily: FONT_FAMILY.KOREAN,\n          color,\n          opacity,\n          transform: `scale(${scale})`,\n          textShadow: `\n            0 0 10px ${glowColor},\n            0 0 20px ${glowColor},\n            2px 2px 4px rgba(0, 0, 0, 0.9)\n          `,\n          whiteSpace: \"nowrap\",\n          userSelect: \"none\",\n          textAlign: \"center\",\n        }}\n      >\n        {feedback.textKorean} | {feedback.text}\n      </div>\n    </Html>\n  );\n};\n\n/**\n * ActionFeedback Component\n *\n * Renders multiple action feedback indicators in the 3D scene.\n * Each indicator floats upward and fades out over time.\n *\n * @example\n * ```tsx\n * <ActionFeedback\n *   feedbacks={actionFeedbacks}\n *   isMobile={isMobile}\n *   arenaBounds={arenaBounds}\n * />\n * ```\n */\nexport const ActionFeedback: React.FC<ActionFeedbackProps> = ({\n  feedbacks,\n  isMobile = false,\n  arenaBounds = DEFAULT_PHYSICS_ARENA_BOUNDS,\n  animationDuration = 1200,\n}) => {\n  // Derive visible feedbacks from props - no need for state sync\n  const visibleFeedbacks = useMemo(() => [...feedbacks], [feedbacks]);\n\n  return (\n    <group data-testid=\"action-feedback-container\">\n      {visibleFeedbacks.map((feedback) => (\n        <SingleFeedback\n          key={feedback.id}\n          feedback={feedback}\n          isMobile={isMobile}\n          arenaBounds={arenaBounds}\n          animationDuration={animationDuration}\n        />\n      ))}\n    </group>\n  );\n};\n\n/**\n * TechniqueName Component\n *\n * Displays the current technique name in Korean and English.\n * Appears at the center of the screen with a dramatic animation.\n *\n * @example\n * ```tsx\n * <TechniqueName\n *   korean=\"천둥벽력\"\n *   english=\"Thunder Strike\"\n *   isMobile={isMobile}\n *   duration={2000}\n * />\n * ```\n */\nexport const TechniqueName: React.FC<TechniqueNameProps> = ({\n  korean,\n  english,\n  isMobile = false,\n  duration = 2000,\n  onComplete,\n}) => {\n  const [opacity, setOpacity] = useState(0);\n  const [scale, setScale] = useState(0.5);\n  // Use useState lazy initializer for Date.now() to avoid impure function during render\n  const [startTime] = useState(() => Date.now());\n  const startTimeRef = useRef(startTime);\n\n  // Animation phases: fade in (0-FADE_IN_THRESHOLD), hold (FADE_IN_THRESHOLD-FADE_OUT_THRESHOLD), fade out (FADE_OUT_THRESHOLD-1)\n  useFrame(() => {\n    const elapsed = Date.now() - startTimeRef.current;\n    const progress = Math.min(elapsed / duration, 1);\n\n    if (progress < FADE_IN_THRESHOLD) {\n      // Fade in phase\n      const fadeInProgress = progress / FADE_IN_THRESHOLD;\n      setOpacity(fadeInProgress);\n      setScale(0.5 + fadeInProgress * 0.5);\n    } else if (progress < FADE_OUT_THRESHOLD) {\n      // Hold phase\n      setOpacity(1);\n      setScale(1);\n    } else {\n      // Fade out phase\n      const fadeOutProgress =\n        (progress - FADE_OUT_THRESHOLD) / (1 - FADE_OUT_THRESHOLD);\n      setOpacity(1 - fadeOutProgress);\n      setScale(1 + fadeOutProgress * 0.2);\n    }\n\n    if (progress >= 1 && onComplete) {\n      onComplete();\n    }\n  });\n\n  // Position at center of scene, slightly below top\n  const position3D: [number, number, number] = [0, 3.5, 0];\n\n  const mainFontSize = isMobile ? 28 : 42;\n  const subFontSize = isMobile ? 16 : 24;\n  const color = hexColorToCSS(KOREAN_COLORS.SECONDARY_MAGENTA);\n  const glowColor = hexToRgbaString(KOREAN_COLORS.SECONDARY_MAGENTA, 0.8);\n\n  return (\n    <Html\n      position={position3D}\n      center\n      distanceFactor={10}\n      style={{ pointerEvents: \"none\" }}\n    >\n      <div\n        data-testid=\"technique-name\"\n        style={{\n          textAlign: \"center\",\n          opacity,\n          transform: `scale(${scale})`,\n          transition: \"transform 0.1s ease-out\",\n        }}\n      >\n        {/* Korean name */}\n        <div\n          style={{\n            fontSize: `${mainFontSize}px`,\n            fontWeight: \"bold\",\n            fontFamily: FONT_FAMILY.KOREAN,\n            color,\n            textShadow: `\n              0 0 15px ${glowColor},\n              0 0 30px ${glowColor},\n              3px 3px 6px rgba(0, 0, 0, 0.9)\n            `,\n            letterSpacing: \"4px\",\n          }}\n        >\n          {korean}\n        </div>\n\n        {/* Divider */}\n        <div\n          style={{\n            width: \"60px\",\n            height: \"2px\",\n            background: `linear-gradient(90deg, transparent, ${color}, transparent)`,\n            margin: \"8px auto\",\n          }}\n        />\n\n        {/* English name */}\n        <div\n          style={{\n            fontSize: `${subFontSize}px`,\n            fontWeight: \"bold\",\n            fontFamily: FONT_FAMILY.KOREAN,\n            color: hexColorToCSS(KOREAN_COLORS.TEXT_SECONDARY),\n            textShadow: \"2px 2px 4px rgba(0, 0, 0, 0.8)\",\n            letterSpacing: \"2px\",\n            textTransform: \"uppercase\",\n          }}\n        >\n          {english}\n        </div>\n      </div>\n    </Html>\n  );\n};\n\nexport default ActionFeedback;\n"],"mappings":"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"}

package/lib/components/shared/three/effects/DamageNumbers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * DamageNumbers - Floating damage number display component
+ *
+ * Displays floating damage numbers that animate upward and fade out.
+ * Color-coded based on damage type: normal (cyan), critical (gold), vital (red).
+ *
+ * Uses Html overlays from @react-three/drei for rendering within 3D scenes.
+ * Performance optimized with React.memo to reduce unnecessary re-renders.
+ *
+ * @module components/shared/three/effects/DamageNumbers
+ * @category Shared Effects
+ * @korean 피해숫자
+ */
+import React from "react";
+import { DamageNumber } from "../../../../hooks/useActionFeedback";
+import { type PhysicsArenaBounds } from "../../../../types/PhysicsTypes";
+/**
+ * Props for the DamageNumbers component
+ */
+export interface DamageNumbersProps {
+    /** Array of damage numbers to display */
+    readonly damages: readonly DamageNumber[];
+    /** Whether to use mobile-optimized sizing */
+    readonly isMobile?: boolean;
+    /** Arena bounds for 3D positioning (physics-first with meter dimensions) */
+    readonly arenaBounds?: PhysicsArenaBounds;
+    /** Duration of animation in ms (default: 1500) */
+    readonly animationDuration?: number;
+}
+/**
+ * Memoized DamageNumbers with custom comparison
+ * Only re-renders when damage array changes
+ */
+export declare const DamageNumbers: React.NamedExoticComponent<DamageNumbersProps>;
+export default DamageNumbers;
+//# sourceMappingURL=DamageNumbers.d.ts.map

package/lib/components/shared/three/effects/DamageNumbers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DamageNumbers.d.ts","sourceRoot":"","sources":["../../../../../src/components/shared/three/effects/DamageNumbers.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAoC,MAAM,OAAO,CAAC;AACzD,OAAO,EAAE,YAAY,EAAc,MAAM,qCAAqC,CAAC;AAE/E,OAAO,EAAgC,KAAK,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIvG;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAwLD;;;GAGG;AACH,eAAO,MAAM,aAAa,gDAyBzB,CAAC;AAIF,eAAe,aAAa,CAAC"}

package/lib/components/shared/three/effects/DamageNumbers.js

@@ -0,0 +1,148 @@
+import { KOREAN_COLORS } from "../../../../types/constants/colors.js";
+import { FONT_FAMILY } from "../../../../types/constants/typography.js";
+import "../../../../types/constants/index.js";
+import { DEFAULT_PHYSICS_ARENA_BOUNDS } from "../../../../types/PhysicsTypes.js";
+import { hexColorToCSS, hexToRgbaString } from "../../../../utils/colorUtils.js";
+import { withGPUAcceleration } from "../../../../utils/performanceOptimization.js";
+import React, { useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { Html } from "@react-three/drei";
+//#region src/components/shared/three/effects/DamageNumbers.tsx
+/**
+* DamageNumbers - Floating damage number display component
+*
+* Displays floating damage numbers that animate upward and fade out.
+* Color-coded based on damage type: normal (cyan), critical (gold), vital (red).
+*
+* Uses Html overlays from @react-three/drei for rendering within 3D scenes.
+* Performance optimized with React.memo to reduce unnecessary re-renders.
+*
+* @module components/shared/three/effects/DamageNumbers
+* @category Shared Effects
+* @korean 피해숫자
+*/
+/**
+* Get color based on damage type
+*/
+function getDamageColor(type) {
+	switch (type) {
+		case "critical": return hexColorToCSS(KOREAN_COLORS.ACCENT_GOLD);
+		case "vital": return hexColorToCSS(KOREAN_COLORS.ACCENT_RED);
+		default: return hexColorToCSS(KOREAN_COLORS.PRIMARY_CYAN);
+	}
+}
+/**
+* Get glow color based on damage type
+*/
+function getGlowColor(type) {
+	switch (type) {
+		case "critical": return hexToRgbaString(KOREAN_COLORS.ACCENT_GOLD, .8);
+		case "vital": return hexToRgbaString(KOREAN_COLORS.ACCENT_RED, .8);
+		default: return hexToRgbaString(KOREAN_COLORS.PRIMARY_CYAN, .8);
+	}
+}
+var SingleDamageNumber = React.memo(({ damage, isMobile, arenaBounds, animationDuration }) => {
+	const [progress, setProgress] = useState(0);
+	const startTimeRef = useRef(damage.timestamp);
+	const halfWidth = arenaBounds.worldWidthMeters / 2;
+	const halfDepth = arenaBounds.worldDepthMeters / 2;
+	const clampedX = Math.min(halfWidth, Math.max(-halfWidth, damage.position.x));
+	const clampedZ = Math.min(halfDepth, Math.max(-halfDepth, damage.position.y));
+	const position3D = [
+		clampedX,
+		2 + progress * 2,
+		clampedZ
+	];
+	useFrame(() => {
+		const elapsed = Date.now() - startTimeRef.current;
+		setProgress(Math.min(elapsed / animationDuration, 1));
+	});
+	if (progress >= 1) return null;
+	const opacity = 1 - progress;
+	const scale = 1 + progress * .3;
+	const fontSize = isMobile ? 20 : 28;
+	const getCriticalBonus = () => {
+		if (damage.type === "critical") return 8;
+		if (damage.type === "vital") return 4;
+		return 0;
+	};
+	const criticalBonus = getCriticalBonus();
+	return /* @__PURE__ */ jsx(Html, {
+		position: position3D,
+		center: true,
+		distanceFactor: 10,
+		style: { pointerEvents: "none" },
+		children: /* @__PURE__ */ jsxs("div", {
+			"data-testid": `damage-${damage.id}`,
+			style: withGPUAcceleration({
+				fontSize: `${fontSize + criticalBonus}px`,
+				fontWeight: "bold",
+				fontFamily: FONT_FAMILY.KOREAN,
+				color: getDamageColor(damage.type),
+				opacity,
+				transform: `scale(${scale})`,
+				textShadow: `
+            0 0 10px ${getGlowColor(damage.type)},
+            0 0 20px ${getGlowColor(damage.type)},
+            2px 2px 4px rgba(0, 0, 0, 0.8)
+          `,
+				whiteSpace: "nowrap",
+				userSelect: "none"
+			}),
+			children: [
+				damage.damage,
+				damage.type === "critical" && "!",
+				damage.type === "vital" && "!!"
+			]
+		})
+	});
+}, (prevProps, nextProps) => {
+	const prevArena = prevProps.arenaBounds;
+	const nextArena = nextProps.arenaBounds;
+	const sameArenaBounds = prevArena?.x === nextArena?.x && prevArena?.y === nextArena?.y && prevArena?.width === nextArena?.width && prevArena?.height === nextArena?.height && prevArena?.worldWidthMeters === nextArena?.worldWidthMeters && prevArena?.worldDepthMeters === nextArena?.worldDepthMeters;
+	return prevProps.damage.id === nextProps.damage.id && prevProps.isMobile === nextProps.isMobile && prevProps.animationDuration === nextProps.animationDuration && sameArenaBounds;
+});
+SingleDamageNumber.displayName = "SingleDamageNumber";
+/**
+* DamageNumbers Component
+*
+* Renders multiple floating damage numbers in the 3D scene.
+* Each number floats upward and fades out over time.
+* Performance optimized with React.memo.
+*
+* @example
+* ```tsx
+* <DamageNumbers
+*   damages={damageNumbers}
+*   isMobile={isMobile}
+*   arenaBounds={arenaBounds}
+* />
+* ```
+*/
+var DamageNumbersComponent = ({ damages, isMobile = false, arenaBounds = DEFAULT_PHYSICS_ARENA_BOUNDS, animationDuration = 1500 }) => {
+	const visibleDamages = useMemo(() => [...damages], [damages]);
+	return /* @__PURE__ */ jsx("group", {
+		"data-testid": "damage-numbers-container",
+		children: visibleDamages.map((damage) => /* @__PURE__ */ jsx(SingleDamageNumber, {
+			damage,
+			isMobile,
+			arenaBounds,
+			animationDuration
+		}, damage.id))
+	});
+};
+/**
+* Memoized DamageNumbers with custom comparison
+* Only re-renders when damage array changes
+*/
+var DamageNumbers = React.memo(DamageNumbersComponent, (prevProps, nextProps) => {
+	if (prevProps.damages.length !== nextProps.damages.length) return false;
+	for (let i = 0; i < prevProps.damages.length; i++) if (prevProps.damages[i].id !== nextProps.damages[i].id) return false;
+	return prevProps.isMobile === nextProps.isMobile && prevProps.animationDuration === nextProps.animationDuration && prevProps.arenaBounds?.x === nextProps.arenaBounds?.x && prevProps.arenaBounds?.y === nextProps.arenaBounds?.y && prevProps.arenaBounds?.width === nextProps.arenaBounds?.width && prevProps.arenaBounds?.height === nextProps.arenaBounds?.height;
+});
+DamageNumbers.displayName = "DamageNumbers";
+//#endregion
+export { DamageNumbers as default };
+
+//# sourceMappingURL=DamageNumbers.js.map

package/lib/components/shared/three/effects/DamageNumbers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DamageNumbers.js","names":[],"sources":["../../../../../src/components/shared/three/effects/DamageNumbers.tsx"],"sourcesContent":["/**\n * DamageNumbers - Floating damage number display component\n *\n * Displays floating damage numbers that animate upward and fade out.\n * Color-coded based on damage type: normal (cyan), critical (gold), vital (red).\n *\n * Uses Html overlays from @react-three/drei for rendering within 3D scenes.\n * Performance optimized with React.memo to reduce unnecessary re-renders.\n *\n * @module components/shared/three/effects/DamageNumbers\n * @category Shared Effects\n * @korean 피해숫자\n */\n\nimport { Html } from \"@react-three/drei\";\nimport { useFrame } from \"@react-three/fiber\";\nimport React, { useMemo, useRef, useState } from \"react\";\nimport { DamageNumber, DamageType } from \"../../../../hooks/useActionFeedback\";\nimport { FONT_FAMILY, KOREAN_COLORS } from \"../../../../types/constants\";\nimport { DEFAULT_PHYSICS_ARENA_BOUNDS, type PhysicsArenaBounds } from \"../../../../types/PhysicsTypes\";\nimport { hexColorToCSS, hexToRgbaString } from \"../../../../utils/colorUtils\";\nimport { withGPUAcceleration } from \"../../../../utils/performanceOptimization\";\n\n/**\n * Props for the DamageNumbers component\n */\nexport interface DamageNumbersProps {\n  /** Array of damage numbers to display */\n  readonly damages: readonly DamageNumber[];\n  /** Whether to use mobile-optimized sizing */\n  readonly isMobile?: boolean;\n  /** Arena bounds for 3D positioning (physics-first with meter dimensions) */\n  readonly arenaBounds?: PhysicsArenaBounds;\n  /** Duration of animation in ms (default: 1500) */\n  readonly animationDuration?: number;\n}\n\n/**\n * Get color based on damage type\n */\nfunction getDamageColor(type: DamageType): string {\n  switch (type) {\n    case \"critical\":\n      return hexColorToCSS(KOREAN_COLORS.ACCENT_GOLD);\n    case \"vital\":\n      return hexColorToCSS(KOREAN_COLORS.ACCENT_RED);\n    case \"normal\":\n    default:\n      return hexColorToCSS(KOREAN_COLORS.PRIMARY_CYAN);\n  }\n}\n\n/**\n * Get glow color based on damage type\n */\nfunction getGlowColor(type: DamageType): string {\n  switch (type) {\n    case \"critical\":\n      return hexToRgbaString(KOREAN_COLORS.ACCENT_GOLD, 0.8);\n    case \"vital\":\n      return hexToRgbaString(KOREAN_COLORS.ACCENT_RED, 0.8);\n    case \"normal\":\n    default:\n      return hexToRgbaString(KOREAN_COLORS.PRIMARY_CYAN, 0.8);\n  }\n}\n\n/**\n * Individual damage number display\n * Memoized to prevent unnecessary re-renders\n */\ninterface SingleDamageNumberProps {\n  readonly damage: DamageNumber;\n  readonly isMobile: boolean;\n  readonly arenaBounds: PhysicsArenaBounds;\n  readonly animationDuration: number;\n}\n\nconst SingleDamageNumber = React.memo<SingleDamageNumberProps>(({\n  damage,\n  isMobile,\n  arenaBounds,\n  animationDuration,\n}) => {\n  const [progress, setProgress] = useState(0);\n  const startTimeRef = useRef(damage.timestamp);\n\n  // Calculate 3D position from meter-based coordinates (physics-first architecture)\n  // Position is in meters relative to arena center (0, 0)\n  // Player models use meter coordinates directly: position={[playerPos.x, 0, playerPos.y]}\n  // So we use meter coordinates directly too for alignment\n  const halfWidth = arenaBounds.worldWidthMeters / 2;\n  const halfDepth = arenaBounds.worldDepthMeters / 2;\n  \n  // Clamp position to arena boundaries in meters\n  const clampedX = Math.min(halfWidth, Math.max(-halfWidth, damage.position.x));\n  const clampedZ = Math.min(halfDepth, Math.max(-halfDepth, damage.position.y));\n  \n  // Use clamped meter coordinates directly in 3D space (no remapping)\n  const x = clampedX; // Meter position X\n  const y = 2 + progress * 2; // Float upward\n  const z = clampedZ; // Meter position Z (depth)\n  const position3D: [number, number, number] = [x, y, z];\n\n  // Update progress using useFrame\n  useFrame(() => {\n    const elapsed = Date.now() - startTimeRef.current;\n    const newProgress = Math.min(elapsed / animationDuration, 1);\n    setProgress(newProgress);\n  });\n\n  // Don't render if expired\n  if (progress >= 1) return null;\n\n  const opacity = 1 - progress;\n  const scale = 1 + progress * 0.3; // Slight scale up during animation\n  const fontSize = isMobile ? 20 : 28;\n  // Calculate critical bonus based on damage type\n  const getCriticalBonus = (): number => {\n    if (damage.type === \"critical\") return 8;\n    if (damage.type === \"vital\") return 4;\n    return 0;\n  };\n  const criticalBonus = getCriticalBonus();\n\n  return (\n    <Html\n      position={position3D}\n      center\n      distanceFactor={10}\n      style={{ pointerEvents: \"none\" }}\n    >\n      <div\n        data-testid={`damage-${damage.id}`}\n        style={withGPUAcceleration({\n          fontSize: `${fontSize + criticalBonus}px`,\n          fontWeight: \"bold\",\n          fontFamily: FONT_FAMILY.KOREAN,\n          color: getDamageColor(damage.type),\n          opacity,\n          transform: `scale(${scale})`,\n          textShadow: `\n            0 0 10px ${getGlowColor(damage.type)},\n            0 0 20px ${getGlowColor(damage.type)},\n            2px 2px 4px rgba(0, 0, 0, 0.8)\n          `,\n          whiteSpace: \"nowrap\",\n          userSelect: \"none\",\n        })}\n      >\n        {damage.damage}\n        {damage.type === \"critical\" && \"!\"}\n        {damage.type === \"vital\" && \"!!\"}\n      </div>\n    </Html>\n  );\n}, (prevProps, nextProps) => {\n  // Custom comparison: re-render only when props that affect rendering change\n  const prevArena = prevProps.arenaBounds;\n  const nextArena = nextProps.arenaBounds;\n\n  const sameArenaBounds =\n    prevArena?.x === nextArena?.x &&\n    prevArena?.y === nextArena?.y &&\n    prevArena?.width === nextArena?.width &&\n    prevArena?.height === nextArena?.height &&\n    prevArena?.worldWidthMeters === nextArena?.worldWidthMeters &&\n    prevArena?.worldDepthMeters === nextArena?.worldDepthMeters;\n\n  return (\n    prevProps.damage.id === nextProps.damage.id &&\n    prevProps.isMobile === nextProps.isMobile &&\n    prevProps.animationDuration === nextProps.animationDuration &&\n    sameArenaBounds\n  );\n});\n\nSingleDamageNumber.displayName = \"SingleDamageNumber\";\n\n/**\n * DamageNumbers Component\n *\n * Renders multiple floating damage numbers in the 3D scene.\n * Each number floats upward and fades out over time.\n * Performance optimized with React.memo.\n *\n * @example\n * ```tsx\n * <DamageNumbers\n *   damages={damageNumbers}\n *   isMobile={isMobile}\n *   arenaBounds={arenaBounds}\n * />\n * ```\n */\nconst DamageNumbersComponent: React.FC<DamageNumbersProps> = ({\n  damages,\n  isMobile = false,\n  arenaBounds = DEFAULT_PHYSICS_ARENA_BOUNDS,\n  animationDuration = 1500,\n}) => {\n  // Derive visible damages from props - no need for state sync\n  const visibleDamages = useMemo(() => [...damages], [damages]);\n\n  return (\n    <group data-testid=\"damage-numbers-container\">\n      {visibleDamages.map((damage) => (\n        <SingleDamageNumber\n          key={damage.id}\n          damage={damage}\n          isMobile={isMobile}\n          arenaBounds={arenaBounds}\n          animationDuration={animationDuration}\n        />\n      ))}\n    </group>\n  );\n};\n\n/**\n * Memoized DamageNumbers with custom comparison\n * Only re-renders when damage array changes\n */\nexport const DamageNumbers = React.memo(\n  DamageNumbersComponent,\n  (prevProps, nextProps) => {\n    // Compare damages array length and contents\n    if (prevProps.damages.length !== nextProps.damages.length) {\n      return false;\n    }\n    \n    // Check if array contents changed (compare IDs)\n    for (let i = 0; i < prevProps.damages.length; i++) {\n      if (prevProps.damages[i].id !== nextProps.damages[i].id) {\n        return false;\n      }\n    }\n    \n    // Check other props\n    return (\n      prevProps.isMobile === nextProps.isMobile &&\n      prevProps.animationDuration === nextProps.animationDuration &&\n      prevProps.arenaBounds?.x === nextProps.arenaBounds?.x &&\n      prevProps.arenaBounds?.y === nextProps.arenaBounds?.y &&\n      prevProps.arenaBounds?.width === nextProps.arenaBounds?.width &&\n      prevProps.arenaBounds?.height === nextProps.arenaBounds?.height\n    );\n  }\n);\n\nDamageNumbers.displayName = \"DamageNumbers\";\n\nexport default DamageNumbers;\n"],"mappings":"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"}

package/lib/components/shared/three/effects/ExplosiveBurstEffect3D.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ExplosiveBurstEffect3D - Explosive particle burst effects for Jin trigram
+ *
+ * Creates explosive particle bursts with Korean cyberpunk aesthetic for
+ * Jin (Thunder) stance techniques on impact.
+ *
+ * **Korean Martial Arts Context:**
+ * - 진괘 (Jin): Thunder trigram explosive impact visualization
+ * - 폭발 (Pokbal): Explosion particle burst
+ * - 충격파 (Chunggyeokpa): Shockwave expansion
+ *
+ * @module components/shared/three/effects/ExplosiveBurstEffect3D
+ * @korean 폭발파열효과3D
+ */
+import React from "react";
+/**
+ * Props for ExplosiveBurstEffect3D component
+ */
+export interface ExplosiveBurstEffect3DProps {
+    /** Position in 3D space [x, y, z] */
+    readonly position: [number, number, number];
+    /** Intensity of the burst (0-1) */
+    readonly intensity?: number;
+    /** Number of particles in the burst */
+    readonly particleCount?: number;
+    /** Duration in milliseconds */
+    readonly duration?: number;
+    /** Callback when effect completes */
+    readonly onComplete?: () => void;
+    /** Whether effect is active */
+    readonly active?: boolean;
+    /** Color theme for particles */
+    readonly color?: number;
+}
+/**
+ * Main Explosive Burst Effect Component
+ * Creates a multi-layered explosive particle burst
+ */
+export declare const ExplosiveBurstEffect3D: React.FC<ExplosiveBurstEffect3DProps>;
+export default ExplosiveBurstEffect3D;
+//# sourceMappingURL=ExplosiveBurstEffect3D.d.ts.map