blacktrigram 0.7.2

package/lib/systems/animation/core/AnimationTransitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationTransitions.js","names":[],"sources":["../../../../src/systems/animation/core/AnimationTransitions.ts"],"sourcesContent":["/**\n * Animation transition rules for Black Trigram\n *\n * Defines valid transitions between animation states.\n * Based on game-design.md specifications and combat flow.\n *\n * Transition rules:\n * - idle ↔ walk ↔ run (movement states)\n * - stance_guard_{stance} ↔ other states (stance-specific guards)\n * - attack → idle (after completion)\n * - defend → idle (after completion)\n * - hit → idle (after completion)\n * - stance_change → idle (after completion)\n * - ko is terminal (no transitions out)\n * - hit can interrupt any non-ko state (high priority)\n *\n * @module systems/animation/AnimationTransitions\n * @category Animation\n * @korean 애니메이션전환\n */\n\nimport { KoreanText } from \"@/types\";\nimport { TrigramStance } from \"@/types/common\";\nimport {\n  AnimationState,\n  FALL_TO_GROUND_MAP,\n  FallType,\n  TransitionRule,\n} from \"./types\";\n\n/**\n * Stance guard animation states (팔괘 방어 자세)\n * @korean 자세방어상태들\n */\nconst STANCE_GUARD_STATES: readonly AnimationState[] = [\n  AnimationState.STANCE_GUARD_GEON,\n  AnimationState.STANCE_GUARD_TAE,\n  AnimationState.STANCE_GUARD_LI,\n  AnimationState.STANCE_GUARD_JIN,\n  AnimationState.STANCE_GUARD_SON,\n  AnimationState.STANCE_GUARD_GAM,\n  AnimationState.STANCE_GUARD_GAN,\n  AnimationState.STANCE_GUARD_GON,\n] as const;\n\n/**\n * Type of stance transition based on stance adjacency\n *\n * **Korean**: 자세 전환 유형\n *\n * - **direct**: Adjacent stances (e.g., geon→tae) - smooth, fast transition\n * - **indirect**: Opposite stances (e.g., geon→gon) - requires intermediate neutral position\n * - **self**: Same stance (no transition needed)\n *\n * @public\n * @category Animation\n * @korean 자세전환유형\n */\nexport type StanceTransitionType = \"direct\" | \"indirect\" | \"self\";\n\n/**\n * Keyframe for stance transition animation with blend weight\n *\n * **Korean**: 자세 전환 키프레임\n *\n * Defines a single keyframe in a stance transition animation, specifying\n * which stance pose to blend and how much weight to apply.\n *\n * @public\n * @category Animation\n * @korean 자세전환키프레임\n */\nexport interface StanceTransitionKeyframe {\n  /** Frame number (0-36 for 600ms at 60fps) */\n  readonly frame: number;\n  /** Stance pose to blend towards */\n  readonly stance: TrigramStance | \"neutral\";\n  /** Blend weight (0.0 to 1.0) */\n  readonly blend: number;\n}\n\n/**\n * Complete stance transition animation configuration\n *\n * **Korean**: 자세 전환 애니메이션\n *\n * Defines a complete transition animation between two trigram stances,\n * including keyframes, timing, and transition type.\n *\n * @public\n * @category Animation\n * @korean 자세전환애니메이션\n */\nexport interface StanceTransition {\n  /** Source stance */\n  readonly from: TrigramStance;\n  /** Target stance */\n  readonly to: TrigramStance;\n  /** Transition type based on adjacency */\n  readonly type: StanceTransitionType;\n  /** Duration in milliseconds (600ms standard) */\n  readonly duration: number;\n  /** Animation keyframes */\n  readonly keyframes: readonly StanceTransitionKeyframe[];\n  /** Bilingual description */\n  readonly description: KoreanText;\n}\n\n/**\n * Order of trigram stances in the stance wheel (circular arrangement)\n *\n * **Korean**: 팔괘 순서\n *\n * The 8 trigrams arranged in traditional order around the Bagua octagon.\n * Adjacent stances in this array are considered \"adjacent\" for transition purposes.\n *\n * @korean 팔괘순서\n */\nexport const TRIGRAM_STANCES_ORDER: readonly TrigramStance[] = [\n  TrigramStance.GEON, // ☰ Heaven\n  TrigramStance.TAE, // ☱ Lake\n  TrigramStance.LI, // ☲ Fire\n  TrigramStance.JIN, // ☳ Thunder\n  TrigramStance.SON, // ☴ Wind\n  TrigramStance.GAM, // ☵ Water\n  TrigramStance.GAN, // ☶ Mountain\n  TrigramStance.GON, // ☷ Earth\n] as const;\n\n/**\n * Fall animation states (낙법 상태)\n * @korean 낙법상태들\n */\nconst FALL_STATES: readonly AnimationState[] = [\n  AnimationState.FALL_FORWARD,\n  AnimationState.FALL_BACKWARD,\n  AnimationState.FALL_SIDE_LEFT,\n  AnimationState.FALL_SIDE_RIGHT,\n] as const;\n\n/**\n * Ground position states (지면 자세)\n * @korean 지면자세들\n */\nconst GROUND_STATES: readonly AnimationState[] = [\n  AnimationState.GROUND_PRONE,\n  AnimationState.GROUND_SUPINE,\n  AnimationState.GROUND_SIDE_LEFT,\n  AnimationState.GROUND_SIDE_RIGHT,\n] as const;\n\n/**\n * Recovery animation states (기상 애니메이션)\n * @korean 회복애니메이션들\n */\nconst RECOVERY_STATES: readonly AnimationState[] = [\n  AnimationState.RECOVERY_PRONE_STANDUP,\n  AnimationState.RECOVERY_SUPINE_STANDUP,\n  AnimationState.RECOVERY_ROLL,\n  AnimationState.RECOVERY_DEFENSIVE,\n] as const;\n\n/**\n * Generate transition rules for fall animations\n *\n * Fall animations have highest priority and can interrupt any state.\n * Falls automatically transition to ground states upon completion.\n * Ground states can transition to recovery animations.\n * Recovery animations transition to idle upon completion.\n *\n * @korean 낙법전환규칙생성\n */\nfunction generateFallTransitions(): TransitionRule[] {\n  const transitions: TransitionRule[] = [];\n\n  // All states (except falls and ko) can transition to fall states\n  const nonFallStates: AnimationState[] = [\n    AnimationState.IDLE,\n    AnimationState.WALK,\n    AnimationState.RUN,\n    AnimationState.ATTACK,\n    AnimationState.DEFEND,\n    AnimationState.HIT,\n    AnimationState.STANCE_CHANGE,\n    AnimationState.STANCE_SIDE_SWITCH,\n    ...STANCE_GUARD_STATES,\n  ];\n\n  for (const fromState of nonFallStates) {\n    for (const fallState of FALL_STATES) {\n      transitions.push({\n        from: fromState,\n        to: fallState,\n        allowed: true,\n      });\n    }\n  }\n\n  // Fall states automatically transition to ground states (handled in state machine)\n  for (const fallState of FALL_STATES) {\n    // Falls can only go to their corresponding ground state\n    // Use FALL_TO_GROUND_MAP for type-safe mapping\n    const fallType = fallState.replace(\"fall_\", \"\");\n\n    // Validate that fallType is a valid FallType before using in map\n    if (\n      fallType === \"forward\" ||\n      fallType === \"backward\" ||\n      fallType === \"side_left\" ||\n      fallType === \"side_right\"\n    ) {\n      const groundState = FALL_TO_GROUND_MAP[fallType as FallType];\n      const groundAnimState = `ground_${groundState}` as AnimationState;\n      transitions.push({\n        from: fallState,\n        to: groundAnimState,\n        allowed: true,\n      });\n    }\n  }\n\n  // Ground states can transition to recovery animations\n  for (const groundState of GROUND_STATES) {\n    // Allow transitions to all recovery types from any ground state\n    for (const recoveryState of RECOVERY_STATES) {\n      transitions.push({\n        from: groundState,\n        to: recoveryState,\n        allowed: true,\n      });\n    }\n\n    // Ground states can still be interrupted by hit or ko\n    transitions.push(\n      { from: groundState, to: AnimationState.HIT, allowed: true },\n      { from: groundState, to: AnimationState.KO, allowed: true },\n    );\n\n    // Falls can interrupt ground states (getting hit while down)\n    for (const fallState of FALL_STATES) {\n      transitions.push({\n        from: groundState,\n        to: fallState,\n        allowed: true,\n      });\n    }\n  }\n\n  // Recovery animations can be interrupted by high-priority states\n  // (falls, hit, ko) but transition to idle when complete\n  for (const recoveryState of RECOVERY_STATES) {\n    // Falls can interrupt recovery (getting hit during recovery)\n    for (const fallState of FALL_STATES) {\n      transitions.push({\n        from: recoveryState,\n        to: fallState,\n        allowed: true,\n      });\n    }\n\n    // Hit and KO can interrupt recovery\n    transitions.push(\n      { from: recoveryState, to: AnimationState.HIT, allowed: true },\n      { from: recoveryState, to: AnimationState.KO, allowed: true },\n    );\n\n    // Recovery animations automatically transition to idle (handled in state machine)\n    transitions.push({\n      from: recoveryState,\n      to: AnimationState.IDLE,\n      allowed: true,\n    });\n  }\n\n  return transitions;\n}\n\n/**\n * Generate transition rules for stance guards\n *\n * Each stance guard can transition to:\n * - walk, run (movement)\n * - attack, defend (combat actions)\n * - step_{direction} (tactical steps while maintaining guard)\n * - stance_change (changing stance)\n * - hit, ko (being hit)\n * - other stance guards (direct stance change with guard)\n *\n * @korean 자세방어전환규칙생성\n */\nfunction generateStanceGuardTransitions(): TransitionRule[] {\n  const transitions: TransitionRule[] = [];\n\n  // Step directions for guard transitions\n  const stepDirections: AnimationState[] = [\n    AnimationState.STEP_FORWARD,\n    AnimationState.STEP_BACK,\n    AnimationState.STEP_LEFT,\n    AnimationState.STEP_RIGHT,\n    AnimationState.STEP_FORWARD_LEFT,\n    AnimationState.STEP_FORWARD_RIGHT,\n    AnimationState.STEP_BACK_LEFT,\n    AnimationState.STEP_BACK_RIGHT,\n  ];\n\n  for (const guardState of STANCE_GUARD_STATES) {\n    // Guard can transition to movement\n    transitions.push(\n      { from: guardState, to: AnimationState.IDLE, allowed: true },\n      { from: guardState, to: AnimationState.WALK, allowed: true },\n      { from: guardState, to: AnimationState.RUN, allowed: true },\n    );\n\n    // Guard can transition to combat actions\n    transitions.push(\n      { from: guardState, to: AnimationState.ATTACK, allowed: true },\n      { from: guardState, to: AnimationState.DEFEND, allowed: true },\n      { from: guardState, to: AnimationState.STANCE_CHANGE, allowed: true },\n    );\n\n    // Guard can transition to tactical steps (guard maintained during step)\n    for (const stepDirection of stepDirections) {\n      transitions.push({ from: guardState, to: stepDirection, allowed: true });\n    }\n\n    // Guard can be interrupted by hits\n    transitions.push(\n      { from: guardState, to: AnimationState.HIT, allowed: true },\n      { from: guardState, to: AnimationState.KO, allowed: true },\n    );\n\n    // Guards can transition between each other (direct stance change)\n    for (const otherGuard of STANCE_GUARD_STATES) {\n      if (guardState !== otherGuard) {\n        transitions.push({ from: guardState, to: otherGuard, allowed: true });\n      }\n    }\n\n    // Other states can transition to guards\n    transitions.push(\n      { from: AnimationState.IDLE, to: guardState, allowed: true },\n      { from: AnimationState.WALK, to: guardState, allowed: true },\n      { from: AnimationState.RUN, to: guardState, allowed: true },\n      { from: AnimationState.DEFEND, to: guardState, allowed: true },\n    );\n\n    // Steps can return to guard (guard maintained throughout step)\n    for (const stepDirection of stepDirections) {\n      transitions.push({ from: stepDirection, to: guardState, allowed: true });\n    }\n  }\n\n  return transitions;\n}\n\n/**\n * Default transition rules for animation states\n *\n * @korean 기본전환규칙\n */\nexport const DEFAULT_TRANSITIONS: readonly TransitionRule[] = [\n  // Idle transitions\n  { from: AnimationState.IDLE, to: AnimationState.WALK, allowed: true },\n  { from: AnimationState.IDLE, to: AnimationState.RUN, allowed: true },\n  { from: AnimationState.IDLE, to: AnimationState.ATTACK, allowed: true },\n  { from: AnimationState.IDLE, to: AnimationState.DEFEND, allowed: true },\n  {\n    from: AnimationState.IDLE,\n    to: AnimationState.STANCE_CHANGE,\n    allowed: true,\n  },\n  { from: AnimationState.IDLE, to: AnimationState.HIT, allowed: true },\n  { from: AnimationState.IDLE, to: AnimationState.KO, allowed: true },\n\n  // Walk transitions\n  { from: AnimationState.WALK, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.WALK, to: AnimationState.RUN, allowed: true },\n  { from: AnimationState.WALK, to: AnimationState.ATTACK, allowed: true },\n  { from: AnimationState.WALK, to: AnimationState.DEFEND, allowed: true },\n  {\n    from: AnimationState.WALK,\n    to: AnimationState.STANCE_CHANGE,\n    allowed: true,\n  },\n  { from: AnimationState.WALK, to: AnimationState.HIT, allowed: true },\n  { from: AnimationState.WALK, to: AnimationState.KO, allowed: true },\n\n  // Run transitions\n  { from: AnimationState.RUN, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.RUN, to: AnimationState.WALK, allowed: true },\n  { from: AnimationState.RUN, to: AnimationState.ATTACK, allowed: true },\n  { from: AnimationState.RUN, to: AnimationState.DEFEND, allowed: true },\n  { from: AnimationState.RUN, to: AnimationState.STANCE_CHANGE, allowed: true },\n  { from: AnimationState.RUN, to: AnimationState.HIT, allowed: true },\n  { from: AnimationState.RUN, to: AnimationState.KO, allowed: true },\n\n  // Attack transitions (typically returns to idle after completion)\n  { from: AnimationState.ATTACK, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.ATTACK, to: AnimationState.HIT, allowed: true }, // Can be interrupted by hit\n  { from: AnimationState.ATTACK, to: AnimationState.KO, allowed: true },\n\n  // Defend transitions (typically returns to idle after completion)\n  { from: AnimationState.DEFEND, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.DEFEND, to: AnimationState.WALK, allowed: true },\n  { from: AnimationState.DEFEND, to: AnimationState.HIT, allowed: true }, // Can be interrupted by hit\n  { from: AnimationState.DEFEND, to: AnimationState.KO, allowed: true },\n\n  // Hit transitions (returns to idle after completion)\n  { from: AnimationState.HIT, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.HIT, to: AnimationState.HIT, allowed: true }, // Can take multiple hits\n  { from: AnimationState.HIT, to: AnimationState.KO, allowed: true },\n\n  // Stance change transitions (returns to idle after completion)\n  {\n    from: AnimationState.STANCE_CHANGE,\n    to: AnimationState.IDLE,\n    allowed: true,\n  },\n  { from: AnimationState.STANCE_CHANGE, to: AnimationState.HIT, allowed: true }, // Can be interrupted by hit\n  { from: AnimationState.STANCE_CHANGE, to: AnimationState.KO, allowed: true },\n\n  // Tactical step transitions (non-interruptible, returns to idle/guard after completion)\n  // Steps can be initiated from idle, walk, or guard states\n  // 전진보법 (Forward Step)\n  { from: AnimationState.IDLE, to: AnimationState.STEP_FORWARD, allowed: true },\n  { from: AnimationState.WALK, to: AnimationState.STEP_FORWARD, allowed: true },\n  { from: AnimationState.STEP_FORWARD, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.STEP_FORWARD, to: AnimationState.HIT, allowed: true }, // Can be hit during step\n  { from: AnimationState.STEP_FORWARD, to: AnimationState.KO, allowed: true },\n\n  // 후퇴보법 (Retreat Step)\n  { from: AnimationState.IDLE, to: AnimationState.STEP_BACK, allowed: true },\n  { from: AnimationState.WALK, to: AnimationState.STEP_BACK, allowed: true },\n  { from: AnimationState.STEP_BACK, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.STEP_BACK, to: AnimationState.HIT, allowed: true },\n  { from: AnimationState.STEP_BACK, to: AnimationState.KO, allowed: true },\n\n  // 좌측면보법 (Left Side Step)\n  { from: AnimationState.IDLE, to: AnimationState.STEP_LEFT, allowed: true },\n  { from: AnimationState.WALK, to: AnimationState.STEP_LEFT, allowed: true },\n  { from: AnimationState.STEP_LEFT, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.STEP_LEFT, to: AnimationState.HIT, allowed: true },\n  { from: AnimationState.STEP_LEFT, to: AnimationState.KO, allowed: true },\n\n  // 우측면보법 (Right Side Step)\n  { from: AnimationState.IDLE, to: AnimationState.STEP_RIGHT, allowed: true },\n  { from: AnimationState.WALK, to: AnimationState.STEP_RIGHT, allowed: true },\n  { from: AnimationState.STEP_RIGHT, to: AnimationState.IDLE, allowed: true },\n  { from: AnimationState.STEP_RIGHT, to: AnimationState.HIT, allowed: true },\n  { from: AnimationState.STEP_RIGHT, to: AnimationState.KO, allowed: true },\n\n  // 전좌측보법 (Forward-Left Diagonal Step)\n  {\n    from: AnimationState.IDLE,\n    to: AnimationState.STEP_FORWARD_LEFT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.WALK,\n    to: AnimationState.STEP_FORWARD_LEFT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_FORWARD_LEFT,\n    to: AnimationState.IDLE,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_FORWARD_LEFT,\n    to: AnimationState.HIT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_FORWARD_LEFT,\n    to: AnimationState.KO,\n    allowed: true,\n  },\n\n  // 전우측보법 (Forward-Right Diagonal Step)\n  {\n    from: AnimationState.IDLE,\n    to: AnimationState.STEP_FORWARD_RIGHT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.WALK,\n    to: AnimationState.STEP_FORWARD_RIGHT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_FORWARD_RIGHT,\n    to: AnimationState.IDLE,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_FORWARD_RIGHT,\n    to: AnimationState.HIT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_FORWARD_RIGHT,\n    to: AnimationState.KO,\n    allowed: true,\n  },\n\n  // 후좌측보법 (Back-Left Diagonal Step)\n  {\n    from: AnimationState.IDLE,\n    to: AnimationState.STEP_BACK_LEFT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.WALK,\n    to: AnimationState.STEP_BACK_LEFT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_BACK_LEFT,\n    to: AnimationState.IDLE,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_BACK_LEFT,\n    to: AnimationState.HIT,\n    allowed: true,\n  },\n  { from: AnimationState.STEP_BACK_LEFT, to: AnimationState.KO, allowed: true },\n\n  // 후우측보법 (Back-Right Diagonal Step)\n  {\n    from: AnimationState.IDLE,\n    to: AnimationState.STEP_BACK_RIGHT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.WALK,\n    to: AnimationState.STEP_BACK_RIGHT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_BACK_RIGHT,\n    to: AnimationState.IDLE,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_BACK_RIGHT,\n    to: AnimationState.HIT,\n    allowed: true,\n  },\n  {\n    from: AnimationState.STEP_BACK_RIGHT,\n    to: AnimationState.KO,\n    allowed: true,\n  },\n\n  // KO is terminal - no transitions out\n  // (Player must be revived/reset to leave KO state)\n\n  // Fall transitions (generated dynamically)\n  ...generateFallTransitions(),\n\n  // Stance guard transitions (generated dynamically)\n  ...generateStanceGuardTransitions(),\n] as const;\n\n/**\n * Check if a transition from one animation state to another is allowed\n *\n * @param from - Source animation state\n * @param to - Target animation state\n * @param transitions - Optional custom transition rules (defaults to DEFAULT_TRANSITIONS)\n * @returns Whether the transition is allowed\n *\n * @example\n * ```typescript\n * // Valid transitions\n * isTransitionAllowed(\"idle\", \"walk\"); // true\n * isTransitionAllowed(\"attack\", \"idle\"); // true\n * isTransitionAllowed(\"hit\", \"idle\"); // true\n *\n * // Invalid transitions\n * isTransitionAllowed(\"ko\", \"idle\"); // false (KO is terminal)\n * isTransitionAllowed(\"attack\", \"walk\"); // false (must return to idle first)\n * ```\n *\n * @korean 전환허용여부확인\n */\nexport function isTransitionAllowed(\n  from: AnimationState,\n  to: AnimationState,\n  transitions: readonly TransitionRule[] = DEFAULT_TRANSITIONS,\n): boolean {\n  // Same state is always allowed\n  if (from === to) {\n    return true;\n  }\n\n  // Find matching transition rule\n  const rule = transitions.find((t) => t.from === from && t.to === to);\n\n  if (!rule) {\n    return false;\n  }\n\n  // Check condition if provided\n  if (rule.condition) {\n    return rule.condition();\n  }\n\n  return rule.allowed;\n}\n\n/**\n * Get all valid transitions from a given animation state\n *\n * @param from - Source animation state\n * @param transitions - Optional custom transition rules (defaults to DEFAULT_TRANSITIONS)\n * @returns Array of allowed target animation states\n *\n * @example\n * ```typescript\n * getValidTransitions(\"idle\");\n * // Returns: [\"walk\", \"run\", \"attack\", \"defend\", \"stance_change\", \"hit\", \"ko\"]\n *\n * getValidTransitions(\"ko\");\n * // Returns: [] (KO is terminal)\n * ```\n *\n * @korean 유효전환목록가져오기\n */\nexport function getValidTransitions(\n  from: AnimationState,\n  transitions: readonly TransitionRule[] = DEFAULT_TRANSITIONS,\n): AnimationState[] {\n  return transitions\n    .filter((t) => t.from === from && t.allowed)\n    .map((t) => t.to)\n    .filter((to) => isTransitionAllowed(from, to, transitions));\n}\n\n/**\n * Build a transition map for fast lookups\n *\n * @param transitions - Transition rules to build map from\n * @returns Map of from->to->allowed\n *\n * @korean 전환맵생성\n */\nexport function buildTransitionMap(\n  transitions: readonly TransitionRule[] = DEFAULT_TRANSITIONS,\n): Map<AnimationState, Set<AnimationState>> {\n  const map = new Map<AnimationState, Set<AnimationState>>();\n\n  for (const rule of transitions) {\n    if (!rule.allowed) continue;\n\n    if (!map.has(rule.from)) {\n      map.set(rule.from, new Set());\n    }\n\n    map.get(rule.from)?.add(rule.to);\n  }\n\n  return map;\n}\n\n/**\n * Calculate stance adjacency (distance around the stance wheel)\n *\n * **Korean**: 자세 인접도 계산\n *\n * Determines how many steps apart two stances are on the octagonal stance wheel.\n * Returns 0 for same stance, 1-3 for adjacent stances, 4 for opposite stances.\n *\n * @param from - Source stance\n * @param to - Target stance\n * @returns Number of steps apart (0-4)\n *\n * @example\n * ```typescript\n * calculateStanceDistance(TrigramStance.GEON, TrigramStance.TAE); // 1 (adjacent)\n * calculateStanceDistance(TrigramStance.GEON, TrigramStance.SON); // 4 (opposite)\n * calculateStanceDistance(TrigramStance.GEON, TrigramStance.GEON); // 0 (same)\n * ```\n *\n * @korean 자세거리계산\n */\nexport function calculateStanceDistance(\n  from: TrigramStance,\n  to: TrigramStance,\n): number {\n  if (from === to) return 0;\n\n  const fromIndex = TRIGRAM_STANCES_ORDER.indexOf(from);\n  const toIndex = TRIGRAM_STANCES_ORDER.indexOf(to);\n\n  if (fromIndex === -1 || toIndex === -1) {\n    console.warn(`Invalid stance in distance calculation: ${from} -> ${to}`);\n    return 4; // Treat as opposite stance\n  }\n\n  // Calculate shortest distance around the circular wheel\n  const directDistance = Math.abs(toIndex - fromIndex);\n  const wrapDistance = TRIGRAM_STANCES_ORDER.length - directDistance;\n\n  return Math.min(directDistance, wrapDistance);\n}\n\n/**\n * Determine transition type based on stance distance\n *\n * **Korean**: 전환 유형 결정\n *\n * Classifies transition as direct (adjacent), indirect (opposite), or self.\n *\n * @param from - Source stance\n * @param to - Target stance\n * @returns Transition type\n *\n * @korean 전환유형결정\n */\nexport function determineTransitionType(\n  from: TrigramStance,\n  to: TrigramStance,\n): StanceTransitionType {\n  const distance = calculateStanceDistance(from, to);\n\n  if (distance === 0) return \"self\";\n  if (distance <= 2) return \"direct\"; // Adjacent or near-adjacent\n  return \"indirect\"; // Opposite or far apart\n}\n\n/**\n * Generate keyframes for direct stance transition (adjacent stances)\n *\n * **Korean**: 직접 전환 키프레임 생성\n *\n * Creates smooth keyframes for transitions between adjacent stances.\n * Phase breakdown:\n * - Frames 0-12: Weight shift away from source stance\n * - Frames 12-24: Foot repositioning\n * - Frames 24-36: Guard change to target stance\n *\n * @param from - Source stance\n * @param to - Target stance\n * @returns Array of keyframes\n *\n * @korean 직접전환키프레임생성\n */\nfunction generateDirectTransitionKeyframes(\n  from: TrigramStance,\n  to: TrigramStance,\n): readonly StanceTransitionKeyframe[] {\n  return [\n    // Phase 1: Initial weight shift (frames 0-12)\n    { frame: 0, stance: from, blend: 1.0 },\n    { frame: 6, stance: from, blend: 0.8 },\n    { frame: 12, stance: \"neutral\", blend: 0.5 },\n\n    // Phase 2: Foot repositioning (frames 12-24)\n    { frame: 18, stance: \"neutral\", blend: 0.4 },\n    { frame: 24, stance: to, blend: 0.3 },\n\n    // Phase 3: Guard position change (frames 24-36)\n    { frame: 30, stance: to, blend: 0.7 },\n    { frame: 36, stance: to, blend: 1.0 },\n  ];\n}\n\n/**\n * Generate keyframes for indirect stance transition (opposite stances)\n *\n * **Korean**: 간접 전환 키프레임 생성\n *\n * Creates keyframes for transitions between opposite stances via neutral position.\n * Longer neutral phase for more complex repositioning.\n *\n * @param from - Source stance\n * @param to - Target stance\n * @returns Array of keyframes\n *\n * @korean 간접전환키프레임생성\n */\nfunction generateIndirectTransitionKeyframes(\n  from: TrigramStance,\n  to: TrigramStance,\n): readonly StanceTransitionKeyframe[] {\n  return [\n    // Phase 1: Exit source stance (frames 0-12)\n    { frame: 0, stance: from, blend: 1.0 },\n    { frame: 6, stance: from, blend: 0.7 },\n    { frame: 12, stance: \"neutral\", blend: 0.5 },\n\n    // Phase 2: Extended neutral position (frames 12-24)\n    { frame: 18, stance: \"neutral\", blend: 0.5 },\n    { frame: 24, stance: \"neutral\", blend: 0.4 },\n\n    // Phase 3: Enter target stance (frames 24-36)\n    { frame: 30, stance: to, blend: 0.6 },\n    { frame: 36, stance: to, blend: 1.0 },\n  ];\n}\n\n/**\n * Create a stance transition configuration\n *\n * **Korean**: 자세 전환 생성\n *\n * Generates complete transition configuration between two stances.\n *\n * @param from - Source stance\n * @param to - Target stance\n * @returns Complete stance transition configuration\n *\n * @korean 자세전환생성\n */\nexport function createStanceTransition(\n  from: TrigramStance,\n  to: TrigramStance,\n): StanceTransition {\n  const type = determineTransitionType(from, to);\n\n  // Self-transition (no animation)\n  if (type === \"self\") {\n    return {\n      from,\n      to,\n      type: \"self\",\n      duration: 0,\n      keyframes: [{ frame: 0, stance: from, blend: 1.0 }],\n      description: {\n        korean: `${from} 자세 유지`,\n        english: `Maintain ${from} stance`,\n      },\n    };\n  }\n\n  // Generate keyframes based on transition type\n  const keyframes =\n    type === \"direct\"\n      ? generateDirectTransitionKeyframes(from, to)\n      : generateIndirectTransitionKeyframes(from, to);\n\n  return {\n    from,\n    to,\n    type,\n    duration: 600, // 600ms standard transition\n    keyframes,\n    description: {\n      korean: `${from}에서 ${to}로 전환`,\n      english: `Transition from ${from} to ${to}`,\n    },\n  };\n}\n\n/**\n * Stance transition matrix containing all 64 transitions (8x8)\n *\n * **Korean**: 팔괘 전환 행렬\n *\n * Maps from every stance to every other stance, including self-transitions.\n * Key format: \"from_to\" (e.g., \"geon_tae\")\n *\n * Total transitions: 64 (8 source stances × 8 target stances)\n * - 8 self-transitions (0ms)\n * - ~24 direct transitions (600ms, adjacent stances)\n * - ~32 indirect transitions (600ms, opposite stances)\n *\n * @korean 팔괘전환행렬\n */\nexport const STANCE_TRANSITIONS: Map<string, StanceTransition> = new Map();\n\n/**\n * Initialize the stance transition matrix\n *\n * **Korean**: 전환 행렬 초기화\n *\n * Generates all 64 stance transitions and populates the transition map.\n * Call this during system initialization.\n *\n * @korean 전환행렬초기화\n */\nexport function initializeStanceTransitions(): void {\n  // Generate all 64 transitions (8 from × 8 to)\n  for (const from of TRIGRAM_STANCES_ORDER) {\n    for (const to of TRIGRAM_STANCES_ORDER) {\n      const key = `${from}_${to}`;\n      const transition = createStanceTransition(from, to);\n      STANCE_TRANSITIONS.set(key, transition);\n    }\n  }\n\n  if (process.env.NODE_ENV === \"development\") {\n    console.log(\n      `[StanceTransitions] Initialized ${STANCE_TRANSITIONS.size} stance transitions`,\n    );\n  }\n}\n\n/**\n * Get stance transition configuration\n *\n * **Korean**: 자세 전환 가져오기\n *\n * Retrieves the transition configuration for moving from one stance to another.\n *\n * @param from - Source stance\n * @param to - Target stance\n * @returns Transition configuration, or undefined if not found\n *\n * @example\n * ```typescript\n * const transition = getStanceTransition(TrigramStance.GEON, TrigramStance.TAE);\n * console.log(transition.duration); // 600\n * console.log(transition.type); // \"direct\"\n * ```\n *\n * @korean 자세전환가져오기\n */\nexport function getStanceTransition(\n  from: TrigramStance,\n  to: TrigramStance,\n): StanceTransition | undefined {\n  const key = `${from}_${to}`;\n  return STANCE_TRANSITIONS.get(key);\n}\n\n/**\n * Get all valid transitions from a stance\n *\n * **Korean**: 유효한 전환 목록\n *\n * Returns all possible transitions from the given stance.\n *\n * @param from - Source stance\n * @returns Array of all transitions from this stance\n *\n * @korean 유효한전환목록\n */\nexport function getTransitionsFromStance(\n  from: TrigramStance,\n): StanceTransition[] {\n  const transitions: StanceTransition[] = [];\n\n  for (const to of TRIGRAM_STANCES_ORDER) {\n    const transition = getStanceTransition(from, to);\n    if (transition) {\n      transitions.push(transition);\n    }\n  }\n\n  return transitions;\n}\n\n/**\n * Clear all cached stance transitions\n *\n * **Korean**: 자세 전환 캐시 초기화\n *\n * Clears the stance transition cache to free memory.\n * Useful for session cleanup or hot reloading.\n * Call initializeStanceTransitions() to repopulate after clearing.\n *\n * @korean 자세전환캐시초기화\n */\nexport function clearStanceTransitions(): void {\n  STANCE_TRANSITIONS.clear();\n}\n\n// Note: For production use, consider calling initializeStanceTransitions()\n// during application startup to avoid blocking the main thread.\n// For now, initialize on module load for convenience.\ninitializeStanceTransitions();\n"],"mappings":"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"}

package/lib/systems/animation/core/LateralityTransform.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Laterality Transform System for Animation Pipeline
+ *
+ * **Korean**: 측면성 변환 시스템
+ *
+ * Extends the animation system to support StanceLaterality (왼발서기/오른발서기),
+ * enabling authentic Korean martial arts stance mirroring across all animations.
+ * Creates 16 distinct stance configurations (8 trigrams × 2 sides).
+ *
+ * Key Features:
+ * - Transform skeletal animations for left/right laterality
+ * - Mirror bone rotations (swap left ↔ right, negate Y/Z axes)
+ * - Preserve animation timing and type information
+ * - Performance optimized (<1ms transformation time)
+ *
+ * Korean Terminology:
+ * - **왼발서기 (Oenbal Seogi)**: Left foot forward, left guard high
+ * - **오른발서기 (Oreun Bal Seogi)**: Right foot forward, right guard high
+ * - **측면성 (Cheugmyeonseong)**: Laterality/sidedness in martial arts
+ *
+ * @module systems/animation/LateralityTransform
+ * @category Animation
+ * @korean 측면성변환
+ */
+import type { SkeletalAnimation } from "../../../types/skeletal";
+import type { StanceLaterality } from "../../trigram/types";
+/**
+ * Apply laterality transformation to a skeletal animation.
+ *
+ * **Korean**: 애니메이션 측면성 적용
+ *
+ * Transforms a skeletal animation to match the specified laterality (left/right stance).
+ * Right laterality returns the original animation; left laterality creates a mirrored version
+ * with left/right bones swapped and lateral rotations negated.
+ *
+ * Transformation Rules:
+ * - Swap left ↔ right bone names (e.g., "shoulder_L" ↔ "shoulder_R")
+ * - Negate Y rotation (lateral twist around vertical axis)
+ * - Negate Z rotation (roll around forward-back axis)
+ * - Preserve X rotation (forward/back bend)
+ * - Maintain timing, duration, and easing information
+ *
+ * Performance: <1ms for typical animation (verified in tests)
+ *
+ * @param animation - Source skeletal animation to transform
+ * @param laterality - Target laterality: "left" or "right"
+ * @returns Transformed animation with mirrored bone rotations for left laterality
+ *
+ * @example
+ * ```typescript
+ * // Get right-handed punch animation
+ * const rightPunch = GEON_BONE_BREAKING_STRIKE_1;
+ *
+ * // Create left-handed version
+ * const leftPunch = applyLaterality(rightPunch, "left");
+ * // leftPunch has left hand as striking hand, mirrored rotations
+ *
+ * // Right laterality returns original (no transformation cost)
+ * const sameAnimation = applyLaterality(rightPunch, "right");
+ * // sameAnimation === rightPunch (same reference)
+ * ```
+ *
+ * @public
+ * @category Animation Transform
+ * @korean 애니메이션측면성적용
+ */
+export declare function applyLaterality(animation: SkeletalAnimation, laterality: StanceLaterality): SkeletalAnimation;
+/**
+ * Get the laterality identifier for an animation.
+ *
+ * **Korean**: 애니메이션 측면성 식별
+ *
+ * Determines if an animation is configured for left or right laterality
+ * based on its name suffix.
+ *
+ * @param animation - Skeletal animation to inspect
+ * @returns "left" if animation has "_left" suffix, otherwise "right"
+ *
+ * @example
+ * ```typescript
+ * const rightAnim = { name: "geon_punch", ... };
+ * const leftAnim = { name: "geon_punch_left", ... };
+ *
+ * getAnimationLaterality(rightAnim); // → "right"
+ * getAnimationLaterality(leftAnim);  // → "left"
+ * ```
+ *
+ * @public
+ * @category Animation Query
+ * @korean 애니메이션측면성식별
+ */
+export declare function getAnimationLaterality(animation: SkeletalAnimation): StanceLaterality;
+/**
+ * Check if two animations are laterality variants of each other.
+ *
+ * **Korean**: 애니메이션 측면성 변형 확인
+ *
+ * Determines if two animations represent the same technique but
+ * with different laterality (left vs right stance).
+ *
+ * @param anim1 - First animation
+ * @param anim2 - Second animation
+ * @returns True if animations are laterality variants of the same base animation
+ *
+ * @example
+ * ```typescript
+ * const rightPunch = { name: "geon_punch", ... };
+ * const leftPunch = { name: "geon_punch_left", ... };
+ * const otherMove = { name: "tae_throw", ... };
+ *
+ * areLateralityVariants(rightPunch, leftPunch);  // → true
+ * areLateralityVariants(rightPunch, otherMove);  // → false
+ * ```
+ *
+ * @public
+ * @category Animation Query
+ * @korean 애니메이션측면성변형확인
+ */
+export declare function areLateralityVariants(anim1: SkeletalAnimation, anim2: SkeletalAnimation): boolean;
+//# sourceMappingURL=LateralityTransform.d.ts.map

package/lib/systems/animation/core/LateralityTransform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LateralityTransform.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/core/LateralityTransform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAqB,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,iBAAiB,EAC5B,UAAU,EAAE,gBAAgB,GAC3B,iBAAiB,CAkBnB;AA0LD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,iBAAiB,GAC3B,gBAAgB,CAElB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,EACxB,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAUT"}

package/lib/systems/animation/core/LateralityTransform.js

@@ -0,0 +1,204 @@
+import * as THREE from "three";
+//#region src/systems/animation/core/LateralityTransform.ts
+/**
+* Apply laterality transformation to a skeletal animation.
+*
+* **Korean**: 애니메이션 측면성 적용
+*
+* Transforms a skeletal animation to match the specified laterality (left/right stance).
+* Right laterality returns the original animation; left laterality creates a mirrored version
+* with left/right bones swapped and lateral rotations negated.
+*
+* Transformation Rules:
+* - Swap left ↔ right bone names (e.g., "shoulder_L" ↔ "shoulder_R")
+* - Negate Y rotation (lateral twist around vertical axis)
+* - Negate Z rotation (roll around forward-back axis)
+* - Preserve X rotation (forward/back bend)
+* - Maintain timing, duration, and easing information
+*
+* Performance: <1ms for typical animation (verified in tests)
+*
+* @param animation - Source skeletal animation to transform
+* @param laterality - Target laterality: "left" or "right"
+* @returns Transformed animation with mirrored bone rotations for left laterality
+*
+* @example
+* ```typescript
+* // Get right-handed punch animation
+* const rightPunch = GEON_BONE_BREAKING_STRIKE_1;
+*
+* // Create left-handed version
+* const leftPunch = applyLaterality(rightPunch, "left");
+* // leftPunch has left hand as striking hand, mirrored rotations
+*
+* // Right laterality returns original (no transformation cost)
+* const sameAnimation = applyLaterality(rightPunch, "right");
+* // sameAnimation === rightPunch (same reference)
+* ```
+*
+* @public
+* @category Animation Transform
+* @korean 애니메이션측면성적용
+*/
+function applyLaterality(animation, laterality) {
+	if (laterality === "right") return animation;
+	const mirroredKeyframes = animation.keyframes.map((keyframe) => mirrorAnimationKeyframe(keyframe));
+	return {
+		...animation,
+		name: `${animation.name}_left`,
+		koreanName: `${animation.koreanName} (왼발)`,
+		keyframes: mirroredKeyframes
+	};
+}
+/**
+* Mirror a single animation keyframe for left laterality.
+*
+* **Korean**: 키프레임 좌우 대칭
+*
+* Creates a mirrored version of an animation keyframe by:
+* 1. Swapping left and right bone names
+* 2. Negating Y and Z rotations (lateral twist and roll)
+* 3. Preserving X rotation (forward/back bend)
+* 4. Maintaining timing and easing information
+*
+* Bone Name Swapping:
+* - "_L" suffix → "_R" suffix
+* - "_R" suffix → "_L" suffix
+* - "left_" prefix → "right_" prefix
+* - "right_" prefix → "left_" prefix
+*
+* @param keyframe - Original animation keyframe
+* @returns Mirrored keyframe with swapped bones and negated rotations
+*
+* @internal
+* @korean 키프레임대칭
+*/
+function mirrorAnimationKeyframe(keyframe) {
+	const mirroredRotations = /* @__PURE__ */ new Map();
+	keyframe.boneRotations.forEach((rotation, boneName) => {
+		const mirroredBoneName = mirrorBoneName(boneName);
+		const mirroredRotation = mirrorEuler(rotation);
+		mirroredRotations.set(mirroredBoneName, mirroredRotation);
+	});
+	const mirroredPositions = /* @__PURE__ */ new Map();
+	if (keyframe.bonePositions) keyframe.bonePositions.forEach((position, boneName) => {
+		const mirroredBoneName = mirrorBoneName(boneName);
+		const mirroredPosition = mirrorPosition(position);
+		mirroredPositions.set(mirroredBoneName, mirroredPosition);
+	});
+	return {
+		time: keyframe.time,
+		boneRotations: mirroredRotations,
+		bonePositions: mirroredPositions,
+		easing: keyframe.easing
+	};
+}
+/**
+* Mirror a bone name by swapping left/right suffixes and prefixes.
+*
+* **Korean**: 뼈 이름 대칭
+*
+* Transforms bone names to their mirrored counterparts:
+* - "shoulder_L" → "shoulder_R"
+* - "upper_arm_R" → "upper_arm_L"
+* - "left_hand" → "right_hand"
+* - "right_foot" → "left_foot"
+*
+* If bone has no laterality marker (e.g., "spine", "pelvis"),
+* returns the original name unchanged.
+*
+* @param boneName - Original bone name
+* @returns Mirrored bone name with swapped left/right markers
+*
+* @example
+* ```typescript
+* mirrorBoneName("shoulder_L")    // → "shoulder_R"
+* mirrorBoneName("upper_arm_R")   // → "upper_arm_L"
+* mirrorBoneName("left_hand")     // → "right_hand"
+* mirrorBoneName("spine_upper")   // → "spine_upper" (no change)
+* ```
+*
+* @internal
+* @korean 뼈이름대칭
+*/
+function mirrorBoneName(boneName) {
+	if (boneName.endsWith("_L")) return boneName.slice(0, -2) + "_R";
+	if (boneName.endsWith("_R")) return boneName.slice(0, -2) + "_L";
+	if (boneName.startsWith("left_")) return "right_" + boneName.slice(5);
+	if (boneName.startsWith("right_")) return "left_" + boneName.slice(6);
+	return boneName;
+}
+/**
+* Mirror a bone rotation by negating Y and Z axes.
+*
+* **Korean**: 뼈 회전 대칭
+*
+* Transforms rotation for left/right mirroring:
+* - X rotation: Preserved (forward/back bend is symmetric)
+* - Y rotation: Negated (lateral twist direction reverses)
+* - Z rotation: Negated (roll direction reverses)
+*
+* This creates anatomically correct mirrored poses where:
+* - Right arm punch becomes left arm punch
+* - Left leg kick becomes right leg kick
+* - Torso twist direction reverses appropriately
+*
+* @param euler - Original bone rotation
+* @returns Mirrored rotation with negated Y and Z axes
+*
+* @example
+* ```typescript
+* // Right arm forward punch: shoulder rotates forward and inward
+* const rightPunch = new THREE.Euler(-1.2, 0.5, 0.6);
+* const leftPunch = mirrorEuler(rightPunch);
+* // leftPunch: (-1.2, -0.5, -0.6) - forward bend preserved, twist/roll negated
+* ```
+*
+* @internal
+* @korean 뼈회전대칭
+*/
+function mirrorEuler(euler) {
+	return new THREE.Euler(euler.x, -euler.y, -euler.z, euler.order);
+}
+/**
+* Mirror a bone position by negating the X coordinate.
+*
+* **Korean**: 뼈 위치 대칭
+*
+* Mirrors position across the YZ plane (body centerline).
+*
+* **World-Space Coordinate System (matching AnimationMirror):**
+* Skeletal animations use world-space coordinates consistent with the 28-bone rig:
+* - X coordinate: Left/right (arms extend along ±X)
+* - Y coordinate: Up/down (pelvis at Y=1.1, legs extend -Y)
+* - Z coordinate: Forward/back (character faces +Z)
+*
+* For mirroring:
+* - X: Negated (left ↔ right)
+* - Y: Preserved (up/down is symmetric)
+* - Z: Preserved (forward/back is symmetric)
+*
+* Used for IK targets and special move positioning where
+* absolute bone positions are specified.
+*
+* @param position - Original bone position offset
+* @returns Mirrored position with negated X coordinate
+*
+* @example
+* ```typescript
+* // Right hand extends to the right (+X)
+* const rightHandPos = new THREE.Vector3(0.5, 1.5, 0.3);
+* const leftHandPos = mirrorPosition(rightHandPos);
+* // leftHandPos: (-0.5, 1.5, 0.3) - extends to the left (-X)
+* ```
+*
+* @internal
+* @korean 뼈위치대칭
+*/
+function mirrorPosition(position) {
+	return new THREE.Vector3(-position.x, position.y, position.z);
+}
+//#endregion
+export { applyLaterality };
+
+//# sourceMappingURL=LateralityTransform.js.map

package/lib/systems/animation/core/LateralityTransform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LateralityTransform.js","names":[],"sources":["../../../../src/systems/animation/core/LateralityTransform.ts"],"sourcesContent":["/**\n * Laterality Transform System for Animation Pipeline\n *\n * **Korean**: 측면성 변환 시스템\n *\n * Extends the animation system to support StanceLaterality (왼발서기/오른발서기),\n * enabling authentic Korean martial arts stance mirroring across all animations.\n * Creates 16 distinct stance configurations (8 trigrams × 2 sides).\n *\n * Key Features:\n * - Transform skeletal animations for left/right laterality\n * - Mirror bone rotations (swap left ↔ right, negate Y/Z axes)\n * - Preserve animation timing and type information\n * - Performance optimized (<1ms transformation time)\n *\n * Korean Terminology:\n * - **왼발서기 (Oenbal Seogi)**: Left foot forward, left guard high\n * - **오른발서기 (Oreun Bal Seogi)**: Right foot forward, right guard high\n * - **측면성 (Cheugmyeonseong)**: Laterality/sidedness in martial arts\n *\n * @module systems/animation/LateralityTransform\n * @category Animation\n * @korean 측면성변환\n */\n\nimport type { AnimationKeyframe, SkeletalAnimation } from \"@/types/skeletal\";\nimport * as THREE from \"three\";\nimport type { StanceLaterality } from \"../../trigram/types\";\n\n/**\n * Apply laterality transformation to a skeletal animation.\n *\n * **Korean**: 애니메이션 측면성 적용\n *\n * Transforms a skeletal animation to match the specified laterality (left/right stance).\n * Right laterality returns the original animation; left laterality creates a mirrored version\n * with left/right bones swapped and lateral rotations negated.\n *\n * Transformation Rules:\n * - Swap left ↔ right bone names (e.g., \"shoulder_L\" ↔ \"shoulder_R\")\n * - Negate Y rotation (lateral twist around vertical axis)\n * - Negate Z rotation (roll around forward-back axis)\n * - Preserve X rotation (forward/back bend)\n * - Maintain timing, duration, and easing information\n *\n * Performance: <1ms for typical animation (verified in tests)\n *\n * @param animation - Source skeletal animation to transform\n * @param laterality - Target laterality: \"left\" or \"right\"\n * @returns Transformed animation with mirrored bone rotations for left laterality\n *\n * @example\n * ```typescript\n * // Get right-handed punch animation\n * const rightPunch = GEON_BONE_BREAKING_STRIKE_1;\n *\n * // Create left-handed version\n * const leftPunch = applyLaterality(rightPunch, \"left\");\n * // leftPunch has left hand as striking hand, mirrored rotations\n *\n * // Right laterality returns original (no transformation cost)\n * const sameAnimation = applyLaterality(rightPunch, \"right\");\n * // sameAnimation === rightPunch (same reference)\n * ```\n *\n * @public\n * @category Animation Transform\n * @korean 애니메이션측면성적용\n */\nexport function applyLaterality(\n  animation: SkeletalAnimation,\n  laterality: StanceLaterality,\n): SkeletalAnimation {\n  // Right laterality returns original animation (no transformation)\n  if (laterality === \"right\") {\n    return animation;\n  }\n\n  // Left laterality: mirror all keyframes\n  const mirroredKeyframes = animation.keyframes.map((keyframe) =>\n    mirrorAnimationKeyframe(keyframe),\n  );\n\n  // Return transformed animation with updated name\n  return {\n    ...animation,\n    name: `${animation.name}_left`,\n    koreanName: `${animation.koreanName} (왼발)`,\n    keyframes: mirroredKeyframes,\n  };\n}\n\n/**\n * Mirror a single animation keyframe for left laterality.\n *\n * **Korean**: 키프레임 좌우 대칭\n *\n * Creates a mirrored version of an animation keyframe by:\n * 1. Swapping left and right bone names\n * 2. Negating Y and Z rotations (lateral twist and roll)\n * 3. Preserving X rotation (forward/back bend)\n * 4. Maintaining timing and easing information\n *\n * Bone Name Swapping:\n * - \"_L\" suffix → \"_R\" suffix\n * - \"_R\" suffix → \"_L\" suffix\n * - \"left_\" prefix → \"right_\" prefix\n * - \"right_\" prefix → \"left_\" prefix\n *\n * @param keyframe - Original animation keyframe\n * @returns Mirrored keyframe with swapped bones and negated rotations\n *\n * @internal\n * @korean 키프레임대칭\n */\nfunction mirrorAnimationKeyframe(\n  keyframe: AnimationKeyframe,\n): AnimationKeyframe {\n  // Mirror bone rotations\n  const mirroredRotations = new Map<string, THREE.Euler>();\n\n  keyframe.boneRotations.forEach((rotation, boneName) => {\n    const mirroredBoneName = mirrorBoneName(boneName);\n    const mirroredRotation = mirrorEuler(rotation);\n    mirroredRotations.set(mirroredBoneName, mirroredRotation);\n  });\n\n  // Mirror bone positions (if present)\n  const mirroredPositions = new Map<string, THREE.Vector3>();\n\n  if (keyframe.bonePositions) {\n    keyframe.bonePositions.forEach((position, boneName) => {\n      const mirroredBoneName = mirrorBoneName(boneName);\n      const mirroredPosition = mirrorPosition(position);\n      mirroredPositions.set(mirroredBoneName, mirroredPosition);\n    });\n  }\n\n  return {\n    time: keyframe.time,\n    boneRotations: mirroredRotations,\n    bonePositions: mirroredPositions,\n    easing: keyframe.easing,\n  };\n}\n\n/**\n * Mirror a bone name by swapping left/right suffixes and prefixes.\n *\n * **Korean**: 뼈 이름 대칭\n *\n * Transforms bone names to their mirrored counterparts:\n * - \"shoulder_L\" → \"shoulder_R\"\n * - \"upper_arm_R\" → \"upper_arm_L\"\n * - \"left_hand\" → \"right_hand\"\n * - \"right_foot\" → \"left_foot\"\n *\n * If bone has no laterality marker (e.g., \"spine\", \"pelvis\"),\n * returns the original name unchanged.\n *\n * @param boneName - Original bone name\n * @returns Mirrored bone name with swapped left/right markers\n *\n * @example\n * ```typescript\n * mirrorBoneName(\"shoulder_L\")    // → \"shoulder_R\"\n * mirrorBoneName(\"upper_arm_R\")   // → \"upper_arm_L\"\n * mirrorBoneName(\"left_hand\")     // → \"right_hand\"\n * mirrorBoneName(\"spine_upper\")   // → \"spine_upper\" (no change)\n * ```\n *\n * @internal\n * @korean 뼈이름대칭\n */\nfunction mirrorBoneName(boneName: string): string {\n  // Handle _L and _R suffixes (most common pattern)\n  if (boneName.endsWith(\"_L\")) {\n    return boneName.slice(0, -2) + \"_R\";\n  }\n  if (boneName.endsWith(\"_R\")) {\n    return boneName.slice(0, -2) + \"_L\";\n  }\n\n  // Handle left_ and right_ prefixes\n  if (boneName.startsWith(\"left_\")) {\n    return \"right_\" + boneName.slice(5);\n  }\n  if (boneName.startsWith(\"right_\")) {\n    return \"left_\" + boneName.slice(6);\n  }\n\n  // No laterality marker - return unchanged (e.g., spine, pelvis, neck)\n  return boneName;\n}\n\n/**\n * Mirror a bone rotation by negating Y and Z axes.\n *\n * **Korean**: 뼈 회전 대칭\n *\n * Transforms rotation for left/right mirroring:\n * - X rotation: Preserved (forward/back bend is symmetric)\n * - Y rotation: Negated (lateral twist direction reverses)\n * - Z rotation: Negated (roll direction reverses)\n *\n * This creates anatomically correct mirrored poses where:\n * - Right arm punch becomes left arm punch\n * - Left leg kick becomes right leg kick\n * - Torso twist direction reverses appropriately\n *\n * @param euler - Original bone rotation\n * @returns Mirrored rotation with negated Y and Z axes\n *\n * @example\n * ```typescript\n * // Right arm forward punch: shoulder rotates forward and inward\n * const rightPunch = new THREE.Euler(-1.2, 0.5, 0.6);\n * const leftPunch = mirrorEuler(rightPunch);\n * // leftPunch: (-1.2, -0.5, -0.6) - forward bend preserved, twist/roll negated\n * ```\n *\n * @internal\n * @korean 뼈회전대칭\n */\nfunction mirrorEuler(euler: THREE.Euler): THREE.Euler {\n  return new THREE.Euler(\n    euler.x, // Preserve forward/back bend\n    -euler.y, // Negate lateral twist\n    -euler.z, // Negate roll\n    euler.order, // Preserve rotation order\n  );\n}\n\n/**\n * Mirror a bone position by negating the X coordinate.\n *\n * **Korean**: 뼈 위치 대칭\n *\n * Mirrors position across the YZ plane (body centerline).\n *\n * **World-Space Coordinate System (matching AnimationMirror):**\n * Skeletal animations use world-space coordinates consistent with the 28-bone rig:\n * - X coordinate: Left/right (arms extend along ±X)\n * - Y coordinate: Up/down (pelvis at Y=1.1, legs extend -Y)\n * - Z coordinate: Forward/back (character faces +Z)\n *\n * For mirroring:\n * - X: Negated (left ↔ right)\n * - Y: Preserved (up/down is symmetric)\n * - Z: Preserved (forward/back is symmetric)\n *\n * Used for IK targets and special move positioning where\n * absolute bone positions are specified.\n *\n * @param position - Original bone position offset\n * @returns Mirrored position with negated X coordinate\n *\n * @example\n * ```typescript\n * // Right hand extends to the right (+X)\n * const rightHandPos = new THREE.Vector3(0.5, 1.5, 0.3);\n * const leftHandPos = mirrorPosition(rightHandPos);\n * // leftHandPos: (-0.5, 1.5, 0.3) - extends to the left (-X)\n * ```\n *\n * @internal\n * @korean 뼈위치대칭\n */\nfunction mirrorPosition(position: THREE.Vector3): THREE.Vector3 {\n  return new THREE.Vector3(\n    -position.x, // Negate left/right (X axis = lateral in world-space rig)\n    position.y, // Preserve vertical\n    position.z, // Preserve forward/back\n  );\n}\n\n/**\n * Get the laterality identifier for an animation.\n *\n * **Korean**: 애니메이션 측면성 식별\n *\n * Determines if an animation is configured for left or right laterality\n * based on its name suffix.\n *\n * @param animation - Skeletal animation to inspect\n * @returns \"left\" if animation has \"_left\" suffix, otherwise \"right\"\n *\n * @example\n * ```typescript\n * const rightAnim = { name: \"geon_punch\", ... };\n * const leftAnim = { name: \"geon_punch_left\", ... };\n *\n * getAnimationLaterality(rightAnim); // → \"right\"\n * getAnimationLaterality(leftAnim);  // → \"left\"\n * ```\n *\n * @public\n * @category Animation Query\n * @korean 애니메이션측면성식별\n */\nexport function getAnimationLaterality(\n  animation: SkeletalAnimation,\n): StanceLaterality {\n  return animation.name.endsWith(\"_left\") ? \"left\" : \"right\";\n}\n\n/**\n * Check if two animations are laterality variants of each other.\n *\n * **Korean**: 애니메이션 측면성 변형 확인\n *\n * Determines if two animations represent the same technique but\n * with different laterality (left vs right stance).\n *\n * @param anim1 - First animation\n * @param anim2 - Second animation\n * @returns True if animations are laterality variants of the same base animation\n *\n * @example\n * ```typescript\n * const rightPunch = { name: \"geon_punch\", ... };\n * const leftPunch = { name: \"geon_punch_left\", ... };\n * const otherMove = { name: \"tae_throw\", ... };\n *\n * areLateralityVariants(rightPunch, leftPunch);  // → true\n * areLateralityVariants(rightPunch, otherMove);  // → false\n * ```\n *\n * @public\n * @category Animation Query\n * @korean 애니메이션측면성변형확인\n */\nexport function areLateralityVariants(\n  anim1: SkeletalAnimation,\n  anim2: SkeletalAnimation,\n): boolean {\n  // Get base names (remove _left suffix if present)\n  const baseName1 = anim1.name.replace(/_left$/, \"\");\n  const baseName2 = anim2.name.replace(/_left$/, \"\");\n\n  // Check if base names match and laterality differs\n  return (\n    baseName1 === baseName2 &&\n    getAnimationLaterality(anim1) !== getAnimationLaterality(anim2)\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqEA,SAAgB,gBACd,WACA,YACmB;AAEnB,KAAI,eAAe,QACjB,QAAO;CAIT,MAAM,oBAAoB,UAAU,UAAU,KAAK,aACjD,wBAAwB,SAAS,CAClC;AAGD,QAAO;EACL,GAAG;EACH,MAAM,GAAG,UAAU,KAAK;EACxB,YAAY,GAAG,UAAU,WAAW;EACpC,WAAW;EACZ;;;;;;;;;;;;;;;;;;;;;;;;;AA0BH,SAAS,wBACP,UACmB;CAEnB,MAAM,oCAAoB,IAAI,KAA0B;AAExD,UAAS,cAAc,SAAS,UAAU,aAAa;EACrD,MAAM,mBAAmB,eAAe,SAAS;EACjD,MAAM,mBAAmB,YAAY,SAAS;AAC9C,oBAAkB,IAAI,kBAAkB,iBAAiB;GACzD;CAGF,MAAM,oCAAoB,IAAI,KAA4B;AAE1D,KAAI,SAAS,cACX,UAAS,cAAc,SAAS,UAAU,aAAa;EACrD,MAAM,mBAAmB,eAAe,SAAS;EACjD,MAAM,mBAAmB,eAAe,SAAS;AACjD,oBAAkB,IAAI,kBAAkB,iBAAiB;GACzD;AAGJ,QAAO;EACL,MAAM,SAAS;EACf,eAAe;EACf,eAAe;EACf,QAAQ,SAAS;EAClB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BH,SAAS,eAAe,UAA0B;AAEhD,KAAI,SAAS,SAAS,KAAK,CACzB,QAAO,SAAS,MAAM,GAAG,GAAG,GAAG;AAEjC,KAAI,SAAS,SAAS,KAAK,CACzB,QAAO,SAAS,MAAM,GAAG,GAAG,GAAG;AAIjC,KAAI,SAAS,WAAW,QAAQ,CAC9B,QAAO,WAAW,SAAS,MAAM,EAAE;AAErC,KAAI,SAAS,WAAW,SAAS,CAC/B,QAAO,UAAU,SAAS,MAAM,EAAE;AAIpC,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCT,SAAS,YAAY,OAAiC;AACpD,QAAO,IAAI,MAAM,MACf,MAAM,GACN,CAAC,MAAM,GACP,CAAC,MAAM,GACP,MAAM,MACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCH,SAAS,eAAe,UAAwC;AAC9D,QAAO,IAAI,MAAM,QACf,CAAC,SAAS,GACV,SAAS,GACT,SAAS,EACV"}

package/lib/systems/animation/core/RecoveryPhaseEnhancer.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Recovery Phase Enhancement for Black Trigram Animations
+ *
+ * Implements realistic recovery animations following Korean martial arts principles:
+ * - 균형회복 (Gyunhyeong Hoebog) - Balance restoration
+ * - 자세복귀 (Jase Bokgwi) - Stance return
+ * - 호흡조절 (Hoheup Jojoel) - Breath control during recovery
+ * - 근육이완 (Geunryuk Ihwan) - Muscle relaxation after tension
+ *
+ * @module systems/animation/RecoveryPhaseEnhancer
+ * @category Animation System
+ * @korean 복귀애니메이션강화
+ */
+import type { SkeletalAnimation } from "../../../types/skeletal";
+/**
+ * Recovery phase configuration options
+ *
+ * **Korean**: 복귀 설정
+ *
+ * @public
+ * @category Animation
+ * @korean 복귀설정
+ */
+export interface RecoveryPhaseConfig {
+    /**
+     * Duration of recovery phase in seconds (default: 0.2s = 200ms)
+     * Recommended range: 0.15 - 0.25 seconds
+     * **Korean**: 복귀 시간
+     */
+    readonly duration?: number;
+    /**
+     * Percentage of return in intermediate keyframe (default: 0.8 = 80%)
+     * **Korean**: 중간 복귀 비율
+     */
+    readonly intermediateReturnPercent?: number;
+    /**
+     * Initial muscle tension level at peak technique (default: 1.0 = 100%)
+     * **Korean**: 최대 근육 긴장도
+     */
+    readonly peakMuscleTension?: number;
+    /**
+     * Muscle tension at intermediate recovery (default: 0.4 = 40%)
+     * **Korean**: 중간 근육 긴장도
+     */
+    readonly intermediateMuscleTension?: number;
+    /**
+     * Final muscle tension in relaxed state (default: 0.1 = 10%)
+     * **Korean**: 최종 근육 긴장도
+     */
+    readonly finalMuscleTension?: number;
+    /**
+     * Whether to use ease-out interpolation (default: true)
+     * **Korean**: 부드러운 감속 사용
+     */
+    readonly useEaseOut?: boolean;
+}
+/**
+ * Add realistic recovery phase to technique animation
+ *
+ * **Korean**: 기술 애니메이션에 복귀 단계 추가
+ *
+ * Enhances technique animations with proper recovery phases following
+ * Korean martial arts principles of 복귀 (Bokgwi - recovery/return).
+ *
+ * The recovery phase consists of two keyframes:
+ * 1. **Intermediate recovery** (60% of recovery duration):
+ *    - Returns 80% toward neutral position
+ *    - Reduces muscle tension to 40%
+ *    - Uses ease-out for gradual deceleration
+ *
+ * 2. **Final recovery** (100% of recovery duration):
+ *    - Fully returns to neutral stance
+ *    - Relaxes muscle tension to 10%
+ *    - Completes breath cycle
+ *
+ * @param animation - Base technique animation
+ * @param config - Recovery phase configuration options
+ * @returns Enhanced animation with recovery phase
+ *
+ * @example
+ * ```typescript
+ * // Add default 220ms recovery to front kick
+ * const kickWithRecovery = addRecoveryPhase(FRONT_KICK_ANIMATION);
+ *
+ * // Add custom 180ms recovery with faster muscle release
+ * const quickRecovery = addRecoveryPhase(JAB_ANIMATION, {
+ *   duration: 0.18,
+ *   intermediateMuscleTension: 0.3,
+ *   finalMuscleTension: 0.05,
+ * });
+ * ```
+ *
+ * @korean 복귀단계추가
+ */
+export declare function addRecoveryPhase(animation: SkeletalAnimation, config?: RecoveryPhaseConfig): SkeletalAnimation;
+/**
+ * Create technique animation with recovery phase
+ *
+ * **Korean**: 복귀 단계를 포함한 기술 애니메이션 생성
+ *
+ * Convenience function that wraps animation creation with automatic recovery phase.
+ * Use this when creating new technique animations from scratch.
+ *
+ * @param baseAnimation - Base animation without recovery
+ * @param config - Recovery configuration
+ * @returns Complete animation with recovery phase
+ *
+ * @example
+ * ```typescript
+ * // Create front kick with recovery
+ * const frontKick = createTechniqueWithRecovery(
+ *   baseFrontKickAnimation,
+ *   { duration: 0.22 }
+ * );
+ * ```
+ *
+ * @korean 복귀단계기술생성
+ */
+export declare function createTechniqueWithRecovery(baseAnimation: SkeletalAnimation, config?: RecoveryPhaseConfig): SkeletalAnimation;
+/**
+ * Validate recovery phase quality
+ *
+ * **Korean**: 복귀 단계 품질 검증
+ *
+ * Checks if an animation has proper recovery phase characteristics:
+ * - Has at least 2 recovery keyframes
+ * - Recovery duration between 150-250ms
+ * - Uses ease-out interpolation
+ * - Returns to neutral position
+ *
+ * @param animation - Animation to validate
+ * @returns Validation result with details
+ *
+ * @korean 복귀품질검증
+ */
+export interface RecoveryValidationResult {
+    /** Whether animation has valid recovery phase */
+    readonly isValid: boolean;
+    /** Validation issues found */
+    readonly issues: string[];
+    /** Recovery duration in milliseconds */
+    readonly recoveryDuration: number;
+    /** Number of recovery keyframes */
+    readonly recoveryKeyframes: number;
+}
+/**
+ * Validate recovery phase in animation
+ *
+ * @param animation - Animation to validate
+ * @returns Validation result
+ *
+ * @korean 복귀검증
+ */
+export declare function validateRecoveryPhase(animation: SkeletalAnimation): RecoveryValidationResult;
+/**
+ * Calculate muscle tension at specific time in animation
+ *
+ * **Korean**: 애니메이션 시간별 근육 긴장도 계산
+ *
+ * Interpolates muscle tension based on animation progress and recovery phase.
+ * Tension peaks during technique execution and gradually releases during recovery.
+ *
+ * @param animation - Animation with recovery phase
+ * @param currentTime - Current time in animation (seconds)
+ * @param config - Recovery configuration used
+ * @returns Muscle tension value (0.0 to 1.0)
+ *
+ * @korean 근육긴장도계산
+ */
+export declare function calculateMuscleTension(animation: SkeletalAnimation, currentTime: number, config?: RecoveryPhaseConfig): number;
+//# sourceMappingURL=RecoveryPhaseEnhancer.d.ts.map

package/lib/systems/animation/core/RecoveryPhaseEnhancer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecoveryPhaseEnhancer.d.ts","sourceRoot":"","sources":["../../../../src/systems/animation/core/RecoveryPhaseEnhancer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAE5C;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAEpC;;;OAGG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAE5C;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAErC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,iBAAiB,EAC5B,MAAM,GAAE,mBAAwB,GAC/B,iBAAiB,CA6FnB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,iBAAiB,EAChC,MAAM,GAAE,mBAAwB,GAC/B,iBAAiB,CAEnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,mCAAmC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,iBAAiB,GAC3B,wBAAwB,CAqE1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,iBAAiB,EAC5B,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,mBAAwB,GAC/B,MAAM,CA6CR"}