blacktrigram 0.7.2

package/lib/systems/animation/builders/MartialArtsAnimationBuilder.d.ts

@@ -0,0 +1,1310 @@
+/**
+ * Martial Arts Animation Builder
+ *
+ * Korean martial arts specific animation builder with semantic methods
+ * that make animations readable by martial arts practitioners.
+ *
+ * 한국 무술 애니메이션 빌더 - 무술 전문가가 이해할 수 있는 시맨틱 메서드 제공
+ *
+ * @module systems/animation
+ * @category Animation System
+ * @korean 무술애니메이션빌더
+ */
+import type { AnimationKeyframe, SkeletalAnimation } from "../../../types/skeletal";
+import { AnimationType, HAND_POSES, KICK_PHASES, MARTIAL_POSES, PUNCH_PHASES } from "./MartialArtsConstants";
+import { KeyframeConfig } from "./KeyframeConfig";
+import { TrigramStance } from "../../../types/common";
+import { type TrigramGuardOptions } from "./TrigramGuardApplicator";
+export { AnimationType, HAND_POSES, KICK_PHASES, MARTIAL_POSES, PUNCH_PHASES };
+/**
+ * Technique Timing Constants
+ *
+ * Defines standard timing phases for martial arts techniques to ensure
+ * all movements are visible and comprehensible. Minimum total duration
+ * is 0.5s to prevent "teleporting" strikes.
+ *
+ * Korean martial arts emphasize visible technique phases:
+ * - 준비 (Preparation) - Wind-up/chamber
+ * - 실행 (Execution) - Strike/extension
+ * - 회수 (Recovery) - Retraction
+ * - 복귀 (Return) - Return to stance
+ *
+ * @korean 기술타이밍상수
+ */
+export declare const TECHNIQUE_TIMING: {
+    /**
+     * Fast techniques (빠른 기술)
+     * Examples: Jabs, quick strikes, fast kicks
+     * Total: 550ms
+     */
+    readonly FAST: {
+        readonly chamber: 0.1;
+        readonly extend: 0.15;
+        readonly peak: 0.05;
+        readonly retract: 0.1;
+        readonly recover: 0.15;
+        readonly total: 0.55;
+    };
+    /**
+     * Fast-Medium techniques (빠른-중간 기술)
+     * Examples: Low kicks, lead hooks, quick counters
+     * Total: 600ms
+     */
+    readonly FAST_MEDIUM: {
+        readonly chamber: 0.1;
+        readonly extend: 0.15;
+        readonly peak: 0.05;
+        readonly retract: 0.1;
+        readonly recover: 0.2;
+        readonly total: 0.6;
+    };
+    /**
+     * Medium-Light techniques (중간-가벼운 기술)
+     * Examples: Lead uppercuts, backfists, push kicks
+     * Total: 700ms
+     */
+    readonly MEDIUM_LIGHT: {
+        readonly chamber: 0.12;
+        readonly extend: 0.18;
+        readonly peak: 0.08;
+        readonly retract: 0.1;
+        readonly recover: 0.22;
+        readonly total: 0.7;
+    };
+    /**
+     * Medium techniques (중간 기술)
+     * Examples: Crosses, roundhouse kicks, hooks
+     * Total: 730ms
+     */
+    readonly MEDIUM: {
+        readonly chamber: 0.15;
+        readonly extend: 0.2;
+        readonly peak: 0.08;
+        readonly retract: 0.12;
+        readonly recover: 0.18;
+        readonly total: 0.73;
+    };
+    /**
+     * Medium-Heavy techniques (중간-무거운 기술)
+     * Examples: Body shots, side kicks, crescent kicks
+     * Total: 750ms
+     */
+    readonly MEDIUM_HEAVY: {
+        readonly chamber: 0.12;
+        readonly extend: 0.2;
+        readonly peak: 0.08;
+        readonly retract: 0.15;
+        readonly recover: 0.2;
+        readonly total: 0.75;
+    };
+    /**
+     * Heavy-Light techniques (무거운-가벼운 기술)
+     * Examples: Hooks, uppercuts, sweep kicks
+     * Total: 800ms
+     */
+    readonly HEAVY_LIGHT: {
+        readonly chamber: 0.15;
+        readonly extend: 0.2;
+        readonly peak: 0.1;
+        readonly retract: 0.15;
+        readonly recover: 0.2;
+        readonly total: 0.8;
+    };
+    /**
+     * Heavy-Medium techniques (무거운-중간 기술)
+     * Examples: Question mark kicks, crescent kicks
+     * Total: 850ms
+     */
+    readonly HEAVY_MEDIUM: {
+        readonly chamber: 0.12;
+        readonly extend: 0.22;
+        readonly peak: 0.08;
+        readonly retract: 0.15;
+        readonly recover: 0.28;
+        readonly total: 0.85;
+    };
+    /**
+     * Heavy techniques (무거운 기술)
+     * Examples: Spinning kicks, power punches, jumping techniques
+     * Total: 1000ms
+     */
+    readonly HEAVY: {
+        readonly chamber: 0.2;
+        readonly extend: 0.3;
+        readonly peak: 0.12;
+        readonly retract: 0.15;
+        readonly recover: 0.23;
+        readonly total: 1;
+    };
+    /**
+     * Combo techniques (연속 기술)
+     * Examples: Jab-cross, double hooks, double kicks
+     * Total: 700ms
+     */
+    readonly COMBO_FAST: {
+        readonly chamber: 0.08;
+        readonly extend: 0.12;
+        readonly peak: 0.08;
+        readonly retract: 0.1;
+        readonly recover: 0.32;
+        readonly total: 0.7;
+    };
+    /**
+     * Jumping techniques (뛰어차기 기술)
+     * Examples: Jumping kicks, jumping punches
+     * Total: 900ms
+     */
+    readonly JUMPING: {
+        readonly chamber: 0.18;
+        readonly extend: 0.22;
+        readonly peak: 0.08;
+        readonly retract: 0.12;
+        readonly recover: 0.3;
+        readonly total: 0.9;
+    };
+    /**
+     * Combo heavy techniques (연속 무거운 기술)
+     * Examples: Double kicks with different heights
+     * Total: 950ms
+     */
+    readonly COMBO_HEAVY: {
+        readonly chamber: 0.12;
+        readonly extend: 0.22;
+        readonly peak: 0.08;
+        readonly retract: 0.15;
+        readonly recover: 0.38;
+        readonly total: 0.95;
+    };
+    /**
+     * Spinning techniques (회전 기술)
+     * Examples: Spinning backfist, tornado kick, spinning heel kick, spinning back kick
+     * Total: 1200ms
+     */
+    readonly SPINNING: {
+        readonly chamber: 0.3;
+        readonly extend: 0.35;
+        readonly peak: 0.12;
+        readonly retract: 0.15;
+        readonly recover: 0.28;
+        readonly total: 1.2;
+    };
+};
+/**
+ * Martial Arts Animation Builder
+ *
+ * Fluent API for creating Korean martial arts animations with semantic methods.
+ * Designed to be readable by martial arts practitioners.
+ *
+ * @example
+ * ```typescript
+ * // Create a front kick (앞차기)
+ * const frontKick = MartialArtsAnimationBuilder
+ *   .create("front_kick", "앞차기")
+ *   .asAttack(0.55)
+ *   .chamber()           // 준비 - Knee lifts
+ *   .withHighGuard()     // 상단방어 - Protect face
+ *   .extend()            // 차기 - Leg extends
+ *   .retract()           // 회수 - Return to chamber
+ *   .recover()           // 복귀 - Return to stance
+ *   .build();
+ * ```
+ *
+ * @korean 무술애니메이션빌더
+ */
+export declare class MartialArtsAnimationBuilder {
+    private name;
+    private koreanName;
+    private duration;
+    private type;
+    private loop;
+    private keyframes;
+    private currentTime;
+    private constructor();
+    /**
+     * Create new martial arts animation
+     * @param name - English animation name
+     * @param koreanName - Korean animation name (한글이름)
+     */
+    static create(name: string, koreanName: string): MartialArtsAnimationBuilder;
+    /**
+     * Configure as attack animation (공격 애니메이션)
+     */
+    asAttack(duration: number): this;
+    /**
+     * Configure as defense animation (방어 애니메이션)
+     */
+    asDefense(duration: number): this;
+    /**
+     * Configure as movement animation (이동 애니메이션)
+     */
+    asMovement(duration: number, shouldLoop?: boolean): this;
+    /**
+     * Configure as idle/stance animation (대기 애니메이션)
+     */
+    asIdle(duration: number, shouldLoop?: boolean): this;
+    /**
+     * Configure as stance transition animation (자세 전환 애니메이션)
+     */
+    asStance(duration: number, shouldLoop?: boolean): this;
+    /**
+     * Add initial fighting stance keyframe (기본 자세)
+     *
+     * Adds a neutral fighting stance at time 0 as the starting position
+     * for attack animations. This is the ready position before techniques.
+     *
+     * @korean 기본자세추가
+     */
+    stance(): this;
+    /**
+     * Chamber - Knee lifts to waist height (준비자세)
+     * Starting position for all kicks
+     *
+     * Authentic Korean martial arts chamber mechanics:
+     * - Hip flexed to 90° (1.57 rad) bringing knee to torso height
+     * - Knee bent tight (120° angle = -2.0 rad) for power generation
+     * - Support leg slightly bent for stability
+     * - Pelvis tilts back slightly for balance
+     * - Toe neutral, ready for extension
+     *
+     * @korean 준비자세
+     */
+    chamber(timeOffset?: number, easing?: string): this;
+    /**
+     * Extend - Leg snaps forward (차기 - 확장)
+     *
+     * Authentic Korean martial arts extension mechanics:
+     * - Hip maintains elevation (1.7 rad ~97°) for target height
+     * - Knee extends fully (0.1 rad ~6°) for maximum reach
+     * - Ankle dorsiflexes (0.5 rad ~29°) pointing toe/ball of foot
+     * - Pelvis tilts forward (0.15 rad ~9°) for hip thrust
+     * - Support leg bends deeper (-0.35 rad) for power transfer
+     * - Spine remains upright for balance
+     *
+     * This is the impact frame where the strike connects.
+     *
+     * @korean 차기확장
+     */
+    extend(timeOffset?: number, easing?: string): this;
+    /**
+     * Retract - Return to chamber (회수)
+     *
+     * Authentic Korean martial arts retraction mechanics:
+     * - Leg returns THROUGH chamber position (proper 낙법)
+     * - Knee bends back to tight position (-2.0 rad)
+     * - Hip maintains height initially, then lowers
+     * - Foot resets to neutral from pointed position
+     * - Pelvis returns to neutral
+     * - Support leg maintains stability
+     *
+     * This is critical for proper technique - the leg must return
+     * through chamber to protect against counters and maintain balance.
+     *
+     * @korean 회수자세
+     */
+    retract(timeOffset?: number, easing?: string): this;
+    /**
+     * Set down - Foot returns to ground (착지)
+     * @korean 착지
+     */
+    setDown(timeOffset?: number, easing?: string): this;
+    /**
+     * Roundhouse chamber - Hip rotates for 돌려차기
+     *
+     * Authentic Taekwondo roundhouse chamber (돌려차기 준비):
+     * - Hip flexed and rotated out (~1.2 rad flex, ~0.8 rad external rotation)
+     * - Knee bent tight (-1.5 rad) preparing for snap
+     * - Pelvis begins rotation (-0.5 rad on Y-axis)
+     * - Spine counter-rotates for power (0.3 rad on Y-axis)
+     * - Support leg stable
+     * - Arms in high guard
+     *
+     * The hip rotation is KEY - it opens the hip for the circular strike path
+     * that defines a roundhouse kick vs. a front kick.
+     *
+     * @korean 돌려차기준비
+     */
+    roundhouseChamber(timeOffset?: number, easing?: string): this;
+    /**
+     * Roundhouse extension - Full hip rotation for 돌려차기
+     *
+     * Authentic Taekwondo roundhouse extension (돌려차기 실행):
+     * - Hip fully extended with maximal rotation (1.2 rad flex, 1.6 rad rotation)
+     * - Knee snaps out to nearly straight (-0.1 rad)
+     * - Foot pointed and rotated (0.4 rad dorsiflexion, 0.3 rad rotation)
+     * - Pelvis fully rotated (-1.5 rad) providing hip whip power
+     * - Spine counter-rotates (0.8 rad) for torque generation
+     * - Foot position extends laterally (0.8m forward)
+     * - Support leg pivots on ball of foot
+     *
+     * Enhanced with compensatory torso lean (중심축회전):
+     * - Torso leans AWAY from kicking leg for balance
+     * - Increases reach and prevents backward fall
+     * - 12° lateral lean on Z-axis for high kicks
+     *
+     * The "snap" comes from the sudden knee extension combined with
+     * the hip rotation - this is the signature of Taekwondo roundhouse.
+     *
+     * @korean 돌려차기
+     */
+    roundhouseExtend(timeOffset?: number, easing?: string): this;
+    /**
+     * Side kick chamber - Turn sideways for 옆차기
+     *
+     * Authentic Taekwondo side kick chamber (옆차기 준비):
+     * - Body turns 90° sideways (pelvis -1.57 rad on Y-axis)
+     * - Hip flexed and chambered (1.3 rad flex, 0.3 rad rotation)
+     * - Knee bent tight (-1.6 rad) preparing for lateral thrust
+     * - Spine rotates with body (-1.2 rad on Y-axis)
+     * - Lean away from kick for balance (0.2 rad lean)
+     * - Support leg stable and aligned
+     * - Arms protect vital areas
+     *
+     * The perpendicular chamber is essential - the hips must turn
+     * sideways to allow the heel to drive through the target laterally.
+     *
+     * @korean 옆차기준비
+     */
+    sideKickChamber(timeOffset?: number, easing?: string): this;
+    /**
+     * Side kick extension - Lateral heel thrust for 옆차기
+     *
+     * Authentic Taekwondo side kick extension (옆차기 실행):
+     * - Hip extends laterally (1.3 rad flex, 0.7 rad rotation)
+     * - Knee extends fully (-0.1 rad) driving heel through target
+     * - Foot turned heel-first (0.4 rad on Y-axis)
+     * - Pelvis maintains 90° turn (-1.57 rad)
+     * - Spine leans away (0.4 rad) for counterbalance
+     * - Foot extends laterally (0.7m to side)
+     * - Support leg drives power
+     *
+     * The side kick is one of the most powerful kicks because the
+     * entire body mass drives through the heel in a straight line.
+     *
+     * @korean 옆차기
+     */
+    sideKickExtend(timeOffset?: number, easing?: string): this;
+    /**
+     * Axe kick rise - Leg rises high for 내려차기
+     *
+     * Enhanced with hip rotation and support leg positioning
+     * @korean 내려차기올리기
+     */
+    axeKickRise(timeOffset?: number, easing?: string): this;
+    /**
+     * Axe kick chop - Downward heel strike for 내려차기
+     *
+     * Enhanced with hip rotation and guard hands
+     * @korean 내려차기
+     */
+    axeKickChop(timeOffset?: number, easing?: string): this;
+    /**
+     * Back kick spin - 180° turn for 뒤차기
+     *
+     * Authentic Taekwondo back kick spin (뒤차기 회전):
+     * - Body rotates 180° (pelvis -1.5 rad initially)
+     * - Spine rotates with body (lower: -1.3 rad, upper: -1.0 rad)
+     * - Head looks over shoulder (0.5 rad) to maintain target visual
+     * - Hip chambers (0.3 rad flex)
+     * - Knee bends (-0.8 rad) preparing for backward thrust
+     * - Support leg maintains balance
+     *
+     * Looking over the shoulder is CRITICAL - you must see the target
+     * to execute an accurate back kick. This is emphasized in all
+     * traditional Korean martial arts.
+     *
+     * @korean 뒤차기회전
+     */
+    backKickSpin(timeOffset?: number, easing?: string): this;
+    /**
+     * Back kick thrust - Heel drives backward for 뒤차기
+     *
+     * Authentic Taekwondo back kick thrust (뒤차기 밀기):
+     * - Body completes 180° rotation (pelvis -3.14 rad = π)
+     * - Hip extends backward (0.5 rad flex maintained)
+     * - Knee extends fully (-0.2 rad) driving heel back
+     * - Foot dorsiflexes (-0.4 rad) presenting heel
+     * - Foot position extends backward (0 forward, 0 up, -0.8 back)
+     * - Head maintains target visual (1.0 rad look-back)
+     * - Spine fully rotated with body
+     * - Support leg powers the thrust
+     *
+     * The back kick delivers tremendous power because the entire
+     * body mass drives through the strongest leg muscles (glutes,
+     * hamstrings) in a straight line backward.
+     *
+     * @korean 뒤차기
+     */
+    backKickThrust(timeOffset?: number, easing?: string): this;
+    /**
+     * Low kick chamber - Small knee lift for low kick (하단차기준비)
+     * @korean 하단차기준비
+     */
+    lowKickChamber(timeOffset?: number, easing?: string): this;
+    /**
+     * Low kick sweep - Shin sweeps at thigh height (하단차기)
+     * @korean 하단차기
+     */
+    lowKickSweep(timeOffset?: number, easing?: string): this;
+    /**
+     * Crescent kick chamber - Leg swings inward (반달차기준비)
+     * @korean 반달차기준비
+     */
+    crescentKickChamber(timeOffset?: number, easing?: string): this;
+    /**
+     * Crescent kick arc - Leg sweeps across body (반달차기)
+     * @korean 반달차기
+     */
+    crescentKickArc(timeOffset?: number, easing?: string): this;
+    /**
+     * Push kick chamber - Ball of foot position (밀어차기준비)
+     *
+     * Enhanced with hip rotation and guard hand protection
+     * @korean 밀어차기준비
+     */
+    pushKickChamber(timeOffset?: number, easing?: string): this;
+    /**
+     * Push kick thrust - Foot pushes opponent back (밀어차기)
+     *
+     * Enhanced with hip rotation for power and guard hand protection
+     * @korean 밀어차기
+     */
+    pushKickThrust(timeOffset?: number, easing?: string): this;
+    /**
+     * Spinning heel kick - 360° with heel strike (뒤돌려차기)
+     *
+     * Full 360° spin requires complete support foot pivot
+     * @korean 뒤돌려차기
+     */
+    spinningHeelKick(timeOffset?: number, easing?: string): this;
+    /**
+     * Hook kick extension - Leg extends past target (후려차기 연장)
+     *
+     * Authentic Korean hook kick (후려차기) first phase:
+     * - Body rotates past perpendicular (~100°)
+     * - Leg extends past target like a missed side kick
+     * - Foot positioned to hook back toward target
+     * - Head maintains target visual
+     *
+     * The hook kick is distinct from crescent kick:
+     * - Crescent: sweeps ACROSS body
+     * - Hook: extends PAST, then hooks BACK
+     *
+     * @korean 후려차기연장
+     */
+    hookKickExtend(timeOffset?: number, easing?: string): this;
+    /**
+     * Hook kick hook-back - Heel hooks back toward target (후려차기 후림)
+     *
+     * Authentic Korean hook kick (후려차기) second phase:
+     * - Leg retracts/hooks back toward target
+     * - Heel is the striking surface (발뒤꿈치)
+     * - Body rotates back toward target during hook
+     * - Snapping motion at knee for power
+     *
+     * The hook motion is what makes this kick unique:
+     * - Extends past, then HOOKS back
+     * - Catches opponent from unexpected angle
+     * - Heel strikes back of head or temple
+     *
+     * @korean 후려차기후림
+     */
+    hookKickHook(timeOffset?: number, easing?: string): this;
+    /**
+     * Tornado kick jump with 360° rotation (회전차기 도약)
+     *
+     * Authentic Korean tornado kick (회전차기) jump phase:
+     * - Jump with full 360° body rotation
+     * - Arms swing to generate rotational momentum
+     * - Body elevates during spin
+     * - Prepares for roundhouse at apex
+     *
+     * @korean 회전차기도약
+     */
+    tornadoJump(timeOffset?: number): this;
+    /**
+     * Punch chamber - Fist at hip with vertical palm (주먹준비자세)
+     * Korean martial arts chamber position with fist vertical (세로주먹)
+     * @param timeOffset Time offset in seconds
+     * @param hand Which hand to chamber ("left" | "right")
+     * @param easing Easing function
+     * @korean 주먹준비자세
+     */
+    punchChamber(timeOffset?: number, hand?: "left" | "right", easing?: string): this;
+    /**
+     * Punch wind-up - Arm coils back (주먹준비)
+     * @param timeOffset Time offset in seconds
+     * @param hand Which hand to wind up ("left" | "right")
+     * @param easing Easing function
+     * @korean 주먹준비
+     */
+    punchWindup(timeOffset?: number, hand?: "left" | "right", easing?: string): this;
+    /**
+     * Punch extension - Arm extends with torso rotation (지르기)
+     * Includes fist rotation from vertical to pronated and hikite
+     *
+     * Enhanced with realistic torso rotation (허리비틀기):
+     * - Straight punches: 20° counter-rotation for power
+     * - Torso rotates OPPOSITE to punch direction
+     * - Sequential spine rotation (lower → mid → upper)
+     *
+     * @param timeOffset Time offset in seconds
+     * @param hand Which hand to extend ("left" | "right")
+     * @param easing Easing function
+     * @korean 지르기
+     */
+    punchExtend(timeOffset?: number, hand?: "left" | "right", easing?: string): this;
+    /**
+     * Punch peak - Maximum extension with full rotation (정점)
+     * Hold at full extension for impact frame
+     *
+     * Enhanced with sustained torso rotation at impact:
+     * - Maintains 20° counter-rotation at peak
+     * - Maximizes power transfer through spine
+     *
+     * @param timeOffset Time offset in seconds
+     * @param hand Which hand is extended ("left" | "right")
+     * @param easing Easing function
+     * @korean 정점
+     */
+    punchPeak(timeOffset?: number, hand?: "left" | "right", easing?: string): this;
+    /**
+     * Cross punch - Left arm punch with full body rotation (크로스)
+     * @korean 크로스
+     */
+    crossPunch(timeOffset?: number, easing?: string): this;
+    /**
+     * Palm strike extension - Open palm heel strike (장권)
+     * @korean 장권
+     */
+    palmStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Hook punch - Circular punch targeting temple (후크)
+     * Enhanced with Korean martial arts shoulder rotation and hikite (당기기)
+     *
+     * Enhanced with realistic circular torso rotation (몸통회전):
+     * - Hook punches: 50° rotation for circular power
+     * - Torso rotates INTO the punch for arc generation
+     * - Sequential spine rotation creates whipping motion
+     *
+     * @param timeOffset Time offset in seconds
+     * @param hand Which hand is hooking ("left" | "right")
+     * @param easing Easing function
+     * @korean 후크
+     */
+    hookPunch(timeOffset?: number, hand?: "left" | "right", easing?: string): this;
+    /**
+     * Hook wind-up - Arm pulls to side (후크준비)
+     * Enhanced with hikite (당기기) preparation
+     * @param timeOffset Time offset in seconds
+     * @param hand Which hand is hooking ("left" | "right")
+     * @param easing Easing function
+     * @korean 후크준비
+     */
+    hookWindup(timeOffset?: number, hand?: "left" | "right", easing?: string): this;
+    /**
+     * Uppercut punch - Rising punch to chin (어퍼컷)
+     * Enhanced with Korean martial arts leg drive and hikite (당기기)
+     * @param timeOffset Time offset in seconds
+     * @param hand Which hand is uppercutting ("left" | "right")
+     * @param easing Easing function
+     * @korean 어퍼컷
+     */
+    uppercutPunch(timeOffset?: number, hand?: "left" | "right", easing?: string): this;
+    /**
+     * Uppercut crouch - Dip before rising punch (어퍼컷준비)
+     * Enhanced with hikite (당기기) preparation
+     * @param timeOffset Time offset in seconds
+     * @param hand Which hand is uppercutting ("left" | "right")
+     * @param easing Easing function
+     * @korean 어퍼컷준비
+     */
+    uppercutCrouch(timeOffset?: number, hand?: "left" | "right", easing?: string): this;
+    /**
+     * Overhand punch - Looping downward punch (오버핸드)
+     * @korean 오버핸드
+     */
+    overhandPunch(timeOffset?: number, easing?: string): this;
+    /**
+     * Elbow strike chamber - Arm crosses body (팔꿈치준비)
+     * @korean 팔꿈치준비
+     */
+    elbowChamber(timeOffset?: number, easing?: string): this;
+    /**
+     * Elbow strike - Elbow drives through target (팔꿈치치기)
+     * @korean 팔꿈치치기
+     */
+    elbowStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Elbow uppercut - Upward elbow strike (팔꿈치올려치기)
+     * @korean 팔꿈치올려치기
+     */
+    elbowUppercut(timeOffset?: number, easing?: string): this;
+    /**
+     * Knee strike from clinch (무릎차기)
+     *
+     * Enhanced with hip rotation and proper clinch mechanics
+     * @korean 무릎차기
+     */
+    kneeStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Brachial elbow - Horizontal elbow to brachial nerve (상박치기)
+     * Targets the lateral neck/brachial plexus area
+     * @korean 상박치기
+     */
+    brachialElbow(timeOffset?: number, easing?: string): this;
+    /**
+     * Slashing elbow - Diagonal cutting elbow (베기팔꿈치)
+     * Diagonal slash across opponent's face/temple
+     * @korean 베기팔꿈치
+     */
+    slashingElbow(timeOffset?: number, easing?: string): this;
+    /**
+     * Spinal elbow - Downward elbow to spine (척추팔꿈치)
+     * Strikes spine from behind or above
+     * @korean 척추팔꿈치
+     */
+    spinalElbow(timeOffset?: number, easing?: string): this;
+    /**
+     * Side knee - Lateral knee to ribs (옆무릎)
+     * Clinch knee targeting opponent's side
+     * @korean 옆무릎
+     */
+    sideKneeStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Flying knee - Jumping knee strike (뛰어무릎)
+     * Explosive airborne knee
+     * @korean 뛰어무릎
+     */
+    flyingKnee(timeOffset?: number, easing?: string): this;
+    /**
+     * Kidney knee - Knee to kidney from side (신장무릎)
+     * Targets kidney area from side clinch
+     * @korean 신장무릎
+     */
+    kidneyKnee(timeOffset?: number, easing?: string): this;
+    /**
+     * Femoral knee - Knee to femoral nerve (대퇴부무릎)
+     * Low knee targeting thigh/femoral nerve
+     * @korean 대퇴부무릎
+     */
+    femoralKnee(timeOffset?: number, easing?: string): this;
+    /**
+     * Throat strike - Precise strike to trachea (기도격)
+     * Fingers extended targeting windpipe
+     * @korean 기도격
+     */
+    throatStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Temple strike - Precision temple elbow (관자놀이격)
+     * Horizontal elbow targeting temple
+     * @korean 관자놀이격
+     */
+    templeElbow(timeOffset?: number, easing?: string): this;
+    /**
+     * Nerve strike - Precision brachial plexus attack (신경격)
+     * Short sharp strike to nerve cluster
+     * @korean 신경격
+     */
+    nerveStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Jugular strike - Knife hand to jugular vein (경정맥격)
+     * Slicing motion to jugular
+     * @korean 경정맥격
+     */
+    jugularStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Occipital strike - Palm heel to base of skull (후두부격)
+     * Upward palm strike to brain stem area
+     * @korean 후두부격
+     */
+    occipitalStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Jaw attack - Upward palm to jaw (턱격)
+     * Palm strike causing jaw dislocation
+     * @korean 턱격
+     */
+    jawStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Eye gouge approach - Fingers to eyes (안격)
+     * Two finger strike to eyes
+     * @korean 안격
+     */
+    eyeGouge(timeOffset?: number, easing?: string): this;
+    /**
+     * Solar plexus strike - Deep body shot (명치격)
+     * Penetrating strike to solar plexus
+     * @korean 명치격
+     */
+    solarPlexusStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Liver shot - Hook to liver area (간격)
+     * Hooking punch targeting liver
+     * @korean 간격
+     */
+    liverShot(timeOffset?: number, easing?: string): this;
+    /**
+     * Kidney strike - Hook to kidney from behind (신장격)
+     * Rear kidney targeting hook
+     * @korean 신장격
+     */
+    kidneyStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Spine strike - Downward elbow to spine (척추격)
+     * 12-6 elbow targeting spine
+     * @korean 척추격
+     */
+    spineStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Groin strike - Low rising knee or palm (낭심격)
+     * Targeting groin area
+     * @korean 낭심격
+     */
+    groinStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Throw entry - Step in and grab (던지기진입)
+     * @korean 던지기진입
+     */
+    throwEntry(timeOffset?: number, easing?: string): this;
+    /**
+     * Throw execution - Hip under and throw (던지기)
+     * @korean 던지기
+     */
+    throwExecute(timeOffset?: number, easing?: string): this;
+    /**
+     * Joint lock application (관절기)
+     * @korean 관절기
+     */
+    jointLock(timeOffset?: number, easing?: string): this;
+    /**
+     * Wrist lock grab - Two-hand wrist control (손목잡기)
+     * @korean 손목잡기
+     */
+    wristGrab(timeOffset?: number, easing?: string): this;
+    /**
+     * Wrist lock twist - Apply rotational pressure (손목꺾기)
+     * @korean 손목꺾기
+     */
+    wristTwist(timeOffset?: number, easing?: string): this;
+    /**
+     * Arm bar entry - Wrap arm across body (팔꺾기진입)
+     * @korean 팔꺾기진입
+     */
+    armBarEntry(timeOffset?: number, easing?: string): this;
+    /**
+     * Arm bar drop - Go to ground for submission (팔꺾기)
+     * @korean 팔꺾기
+     */
+    armBarDrop(timeOffset?: number, easing?: string): this;
+    /**
+     * Slam lift - Hoist opponent up (슬램올리기)
+     * @korean 슬램올리기
+     */
+    slamLift(timeOffset?: number, easing?: string): this;
+    /**
+     * Slam down - Drive opponent to ground (슬램)
+     * @korean 슬램
+     */
+    slamDown(timeOffset?: number, easing?: string): this;
+    /**
+     * Hip throw - Classic hip projection (배대되치기)
+     * Rotating hip throw with arm control
+     * @korean 배대되치기
+     */
+    hipThrow(timeOffset?: number, easing?: string): this;
+    /**
+     * Takedown entry - Shoot and grab legs (태클진입)
+     * Double leg takedown initiation
+     * @korean 태클진입
+     */
+    takedownShoot(timeOffset?: number, easing?: string): this;
+    /**
+     * Takedown finish - Lift and dump (태클완료)
+     * Complete the takedown with dump
+     * @korean 태클완료
+     */
+    takedownDump(timeOffset?: number, easing?: string): this;
+    /**
+     * Elbow lock application - Arm bar pressure (팔꿈치꺾기)
+     * Specific elbow hyperextension lock
+     * @korean 팔꿈치꺾기
+     */
+    elbowLockApply(timeOffset?: number, easing?: string): this;
+    /**
+     * Shoulder lock twist - Shoulder manipulation (어깨꺾기)
+     * Rotational shoulder joint attack
+     * @korean 어깨꺾기
+     */
+    shoulderLockTwist(timeOffset?: number, easing?: string): this;
+    /**
+     * Finger manipulation - Small joint lock (손가락비틀기)
+     * Precise finger control technique
+     * @korean 손가락비틀기
+     */
+    fingerLockTwist(timeOffset?: number, easing?: string): this;
+    /**
+     * Choke grip - Rear naked choke position (교살잡기)
+     * Setting up blood choke
+     * @korean 교살잡기
+     */
+    chokeGrip(timeOffset?: number, easing?: string): this;
+    /**
+     * Ground control - Mounted position (마운트)
+     * Dominant ground position
+     * @korean 마운트
+     */
+    groundMount(timeOffset?: number, easing?: string): this;
+    /**
+     * Clinch grab - Arms wrap around opponent (클린치잡기)
+     * @korean 클린치잡기
+     */
+    clinchGrab(timeOffset?: number, easing?: string): this;
+    /**
+     * Counter parry - Quick deflection (반격막기)
+     * @korean 반격막기
+     */
+    counterParry(timeOffset?: number, easing?: string): this;
+    /**
+     * Counter strike - Fast return strike (반격치기)
+     * @korean 반격치기
+     */
+    counterStrike(timeOffset?: number, easing?: string): this;
+    /**
+     * Sweep - Low sweeping leg (걸기)
+     * @korean 걸기
+     */
+    sweep(timeOffset?: number, easing?: string): this;
+    /**
+     * Counter parry - Deflect incoming attack (막기)
+     * @korean 막기
+     */
+    parry(timeOffset?: number, easing?: string): this;
+    /**
+     * High block defensive pose (상단막기)
+     * @korean 상단막기
+     */
+    blockHigh(timeOffset?: number, easing?: string): this;
+    /**
+     * Low block defensive pose (하단막기)
+     * @korean 하단막기
+     */
+    blockLow(timeOffset?: number, easing?: string): this;
+    /**
+     * Mid-section block - Standard middle block (중단막기)
+     * Arms crossed protecting torso
+     * @korean 중단막기
+     */
+    blockMiddle(timeOffset?: number, easing?: string): this;
+    /**
+     * Knife hand block - Open hand deflection (수도막기)
+     * Blade of hand for blocking
+     * @korean 수도막기
+     */
+    blockKnifeHand(timeOffset?: number, easing?: string): this;
+    /**
+     * Step forward or backward (스텝)
+     * @korean 스텝
+     */
+    step(timeOffset?: number, easing?: string): this;
+    /**
+     * Forward step - Advancing stance (전진)
+     * Weight transfers forward with lead foot
+     * @korean 전진
+     */
+    forwardStep(timeOffset?: number, easing?: string): this;
+    /**
+     * Backward step - Retreating stance (후진)
+     * Weight transfers backward with rear foot
+     * @korean 후진
+     */
+    backwardStep(timeOffset?: number, easing?: string): this;
+    /**
+     * Side step left - Lateral evasion (좌측이동)
+     * Quick lateral movement to the left
+     * @korean 좌측이동
+     */
+    sideStepLeft(timeOffset?: number, easing?: string): this;
+    /**
+     * Side step right - Lateral evasion (우측이동)
+     * Quick lateral movement to the right
+     * @korean 우측이동
+     */
+    sideStepRight(timeOffset?: number, easing?: string): this;
+    /**
+     * Lateral shift movement (측면이동)
+     * @korean 측면이동
+     */
+    shift(timeOffset?: number, easing?: string): this;
+    /**
+     * Rotation/pivot movement (회전)
+     * @korean 회전
+     */
+    rotate(timeOffset?: number, easing?: string): this;
+    /**
+     * Full 360° spin (회전)
+     * @korean 전체회전
+     */
+    spin(timeOffset?: number, easing?: string): this;
+    /**
+     * Spinning kick finish (회전차기)
+     * @korean 회전차기
+     */
+    spinKick(timeOffset?: number, easing?: string): this;
+    /**
+     * Jump/hop movement (점프)
+     * @korean 점프
+     */
+    jump(timeOffset?: number, easing?: string): this;
+    /**
+     * Duck/crouch movement (숙이기)
+     * @korean 숙이기
+     */
+    duck(timeOffset?: number, easing?: string): this;
+    /**
+     * Lean back movement (뒤로젖히기)
+     * @korean 뒤로젖히기
+     */
+    lean(timeOffset?: number, easing?: string): this;
+    /**
+     * Bob head movement (헤드밥)
+     * @korean 헤드밥
+     */
+    bob(timeOffset?: number, easing?: string): this;
+    /**
+     * Weave movement (위브)
+     * @korean 위브
+     */
+    weave(timeOffset?: number, easing?: string): this;
+    /**
+     * Roundhouse kick extension (돌려차기)
+     * @korean 돌려차기
+     */
+    roundhouse(timeOffset?: number, easing?: string): this;
+    /**
+     * Axe kick downward motion (내려차기)
+     * @korean 내려차기
+     */
+    axeKick(timeOffset?: number, easing?: string): this;
+    /**
+     * Apply fighting guard - Hands protect face (경계자세)
+     * @korean 경계자세
+     */
+    withGuard(): this;
+    /**
+     * Apply high guard - Hands at temple (상단방어)
+     * @korean 상단방어
+     */
+    withHighGuard(): this;
+    /**
+     * Apply Korean guard position helper
+     *
+     * Private helper method to reduce code duplication across guard methods.
+     * Applies guard positions to the last keyframe in the animation.
+     *
+     * @param guardType - Type of guard to apply
+     * @param side - Which side to apply ("left" | "right" | "both")
+     * @returns this for chaining
+     * @korean 한국방어자세적용헬퍼
+     * @private
+     */
+    private applyKoreanGuard;
+    /**
+     * Apply Korean high guard position (상단막기)
+     *
+     * Traditional Korean martial arts high guard with hands at temple level
+     * protecting head and face. Uses authentic 막기자세 positioning.
+     *
+     * @param side - Which side to apply ("left" | "right" | "both")
+     * @returns this for chaining
+     * @korean 상단막기자세
+     */
+    withKoreanHighGuard(side?: "left" | "right" | "both"): this;
+    /**
+     * Apply Korean middle guard position (중단막기)
+     *
+     * Standard Korean martial arts guard at chest/solar plexus level.
+     * Most versatile guard position, used in most fighting stances.
+     *
+     * @param side - Which side to apply ("left" | "right" | "both")
+     * @returns this for chaining
+     * @korean 중단막기자세
+     */
+    withKoreanMiddleGuard(side?: "left" | "right" | "both"): this;
+    /**
+     * Apply Korean low guard position (하단막기)
+     *
+     * Low guard position protecting lower body and groin.
+     * Used in grappling and ground-fighting scenarios.
+     *
+     * @param side - Which side to apply ("left" | "right" | "both")
+     * @returns this for chaining
+     * @korean 하단막기자세
+     */
+    withKoreanLowGuard(side?: "left" | "right" | "both"): this;
+    /**
+     * Apply trigram-specific guard pose (팔괘자세)
+     *
+     * Sets the complete body position for the specified trigram stance,
+     * including arms, legs, torso, and pelvis. Unlike generic guards,
+     * this applies the authentic Korean martial arts posture for each
+     * of the eight trigram stances.
+     *
+     * Use this for:
+     * - Idle stance animations
+     * - Returning to guard after techniques
+     * - Walk/run animations (arms only mode)
+     *
+     * @param stance - Trigram stance (e.g., TrigramStance.GEON)
+     * @param options - Application options (what body parts to apply)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // Full guard pose in idle stance
+     * builder.at(0).withTrigramGuard(TrigramStance.GEON);
+     *
+     * // Arms only for walk animation (legs handled separately)
+     * builder.at(0).withTrigramGuard(TrigramStance.TAE, {
+     *   includeLegs: false,
+     *   includePelvis: false
+     * });
+     * ```
+     *
+     * @korean 팔괘방어자세
+     */
+    withTrigramGuard(stance: TrigramStance, options?: TrigramGuardOptions): this;
+    /**
+     * Get trigram guard arm positions for locomotion animations
+     *
+     * Returns the base arm positions for the specified trigram's guard pose.
+     * Use this when building walk/run animations that need to maintain
+     * the trigram's arm guard while adding swing motion.
+     *
+     * @param stance - Trigram stance
+     * @returns Left and right arm base rotations (shoulder, elbow)
+     *
+     * @example
+     * ```typescript
+     * const arms = builder.getTrigramArmGuard(TrigramStance.GEON);
+     * // Add swing to left shoulder while keeping guard shape
+     * kf.rotate(BoneName.SHOULDER_L,
+     *   arms.left.shoulder[0] + swingOffset,
+     *   arms.left.shoulder[1],
+     *   arms.left.shoulder[2]
+     * );
+     * ```
+     *
+     * @korean 팔괘팔자세가져오기
+     */
+    static getTrigramArmGuard(stance: TrigramStance): {
+        left: {
+            shoulder: [number, number, number];
+            elbow: [number, number, number];
+        };
+        right: {
+            shoulder: [number, number, number];
+            elbow: [number, number, number];
+        };
+    };
+    /**
+     * Apply clinch position (클린치)
+     * @korean 클린치
+     */
+    withClinch(): this;
+    /**
+     * Helper to apply finger rotations from a hand pose to a keyframe
+     * @internal
+     */
+    private applyHandPose;
+    /**
+     * Apply open palm pose - Palm strikes and blocks (장권)
+     * @param hand Which hand(s) to apply the pose to
+     * @korean 손바닥펴기
+     */
+    withOpenPalm(hand?: "left" | "right" | "both"): this;
+    /**
+     * Apply spear hand pose - Finger strikes to throat/eyes (관수)
+     * @param hand Which hand(s) to apply the pose to
+     * @korean 관수펴기
+     */
+    withSpearHand(hand?: "left" | "right" | "both"): this;
+    /**
+     * Apply backfist pose - Knuckle strikes (등주먹)
+     * @param hand Which hand(s) to apply the pose to
+     * @korean 등주먹
+     */
+    withBackfist(hand?: "left" | "right" | "both"): this;
+    /**
+     * Apply grab pose - Grappling and holds (잡기)
+     * @param hand Which hand(s) to apply the pose to
+     * @korean 잡기손
+     */
+    withGrab(hand?: "left" | "right" | "both"): this;
+    /**
+     * Helper to apply finger rotations from a hand pose to an existing keyframe
+     * @internal
+     */
+    private applyHandPoseToKeyframe;
+    /**
+     * Apply hand pose during a keyframe (inline version for addKeyframe)
+     * @param pose The hand pose to apply
+     * @param hand Which hand(s) to apply the pose to
+     * @korean 손모양적용
+     */
+    applyHandPoseDuring(kf: KeyframeConfig, pose: keyof typeof HAND_POSES, hand?: "left" | "right" | "both"): void;
+    /**
+     * Apply foot positions based on stance width (발너비)
+     * Sets left and right foot X positions symmetrically around center
+     *
+     * @param stanceWidthMultiplier - Multiplier from KOREAN_STANCE_BIOMECHANICS
+     * @param shoulderWidth - Fighter's shoulder width in centimeters
+     * @korean 발너비적용
+     *
+     * @example
+     * ```typescript
+     * // Jin Thunder stance (2.0x shoulder width)
+     * .withFootWidth(2.0, 46)  // 0.92m total width
+     *
+     * // Son Wind stance (0.0x - crane stance)
+     * .withFootWidth(0.0, 46)  // 0m - single leg
+     * ```
+     */
+    withFootWidth(stanceWidthMultiplier: number, shoulderWidth: number): this;
+    /**
+     * Apply foot positions to current keyframe during addKeyframe
+     * Inline version for use within keyframe callback
+     *
+     * @param kf - KeyframeConfig to modify
+     * @param stanceWidthMultiplier - Multiplier from KOREAN_STANCE_BIOMECHANICS
+     * @param shoulderWidth - Fighter's shoulder width in centimeters
+     * @korean 발너비설정
+     */
+    applyFootPositionsDuring(kf: KeyframeConfig, stanceWidthMultiplier: number, shoulderWidth: number): void;
+    /**
+     * Recover to fighting guard (복귀)
+     * Returns to neutral stance with torso reset
+     * @korean 복귀
+     */
+    recover(timeOffset?: number, easing?: string): this;
+    /**
+     * Full 360° spin recovery (회전복귀)
+     * @korean 회전복귀
+     */
+    spinRecover(timeOffset?: number, easing?: string): this;
+    /**
+     * Apply torso rotation for straight punch power generation (주먹허리비틀기)
+     *
+     * Korean martial arts principle: 허리비틀기 (Heori Biteulgi) - Waist twist for power
+     * The torso rotates OPPOSITE to the punch direction, creating torque through
+     * the spine that transfers power into the strike.
+     *
+     * Biomechanics:
+     * - SPINE_LOWER rotates 50% of target angle (foundation rotation)
+     * - SPINE_MIDDLE rotates 70% of target angle (power transfer zone)
+     * - SPINE_UPPER rotates 100% of target angle (maximum rotation at shoulders)
+     *
+     * @param kf - KeyframeConfig to apply rotation to
+     * @param side - Which hand is punching ("left" | "right")
+     * @param rotationDegrees - Target rotation in degrees (15-25° recommended)
+     *
+     * @example
+     * ```typescript
+     * // Right cross with 20° counter-rotation
+     * this.addKeyframe(0.35, "ease-out", (kf) => {
+     *   this.applyPunchTorsoRotation(kf, "right", 20);
+     *   // ... other punch mechanics
+     * });
+     * ```
+     *
+     * @korean 주먹허리비틀기
+     */
+    private applyPunchTorsoRotation;
+    /**
+     * Apply torso rotation for hook punch circular power (훅허리비틀기)
+     *
+     * Korean martial arts principle: 몸통회전 (Momtong Hoejeon) - Full torso rotation
+     * Hook punches generate power from hip and shoulder rotation in a circular motion.
+     * Larger rotation angle (45-60°) creates the circular arc needed for hooks.
+     *
+     * Biomechanics:
+     * - SPINE_LOWER rotates 50% (hip engagement)
+     * - SPINE_MIDDLE rotates 70% (core power transfer)
+     * - SPINE_UPPER rotates 100% (shoulder whip into target)
+     *
+     * @param kf - KeyframeConfig to apply rotation to
+     * @param side - Which hand is hooking ("left" | "right")
+     * @param rotationDegrees - Target rotation in degrees (45-60° recommended)
+     *
+     * @example
+     * ```typescript
+     * // Right hook with 50° rotation
+     * this.addKeyframe(0.30, "ease-out", (kf) => {
+     *   this.applyHookTorsoRotation(kf, "right", 50);
+     *   // ... other hook mechanics
+     * });
+     * ```
+     *
+     * @korean 훅허리비틀기
+     */
+    private applyHookTorsoRotation;
+    /**
+     * Apply torso lean for kick balance (차기허리기울이기)
+     *
+     * Korean martial arts principle: 중심축회전 (Jungsim Chuk Hoejeon) - Central axis rotation
+     * When executing kicks, the torso leans AWAY from the kicking leg to:
+     * 1. Maintain balance on the support leg
+     * 2. Increase reach by extending the kick further
+     * 3. Prevent falling backward during high kicks
+     *
+     * Biomechanics:
+     * - SPINE_LOWER leans away from kick (foundation)
+     * - SPINE_MIDDLE leans with lower spine (stability)
+     * - SPINE_UPPER leans slightly less (control)
+     *
+     * @param kf - KeyframeConfig to apply lean to
+     * @param side - Which leg is kicking ("left" | "right")
+     * @param leanDegrees - Amount of lean in degrees (10-20° recommended)
+     *
+     * @example
+     * ```typescript
+     * // Right roundhouse kick with compensatory lean
+     * this.addKeyframe(0.35, "ease-out", (kf) => {
+     *   this.applyKickTorsoLean(kf, "right", 15);
+     *   // ... other kick mechanics
+     * });
+     * ```
+     *
+     * @korean 차기허리기울이기
+     */
+    private applyKickTorsoLean;
+    /**
+     * Reset torso to neutral position (허리중립)
+     *
+     * Returns all spine bones to neutral rotation (0, 0, 0).
+     * Used during recovery phases to return to fighting stance.
+     *
+     * @param kf - KeyframeConfig to reset
+     *
+     * @korean 허리중립
+     */
+    private resetTorsoRotation;
+    /**
+     * Add custom keyframe with callback
+     */
+    private addKeyframe;
+    /**
+     * Add raw keyframe at specific time
+     */
+    at(time: number, easing?: string): KeyframeConfig;
+    /**
+     * Internal: Add keyframe from KeyframeConfig
+     */
+    _addKeyframe(kf: AnimationKeyframe): void;
+    /**
+     * Build the complete animation
+     *
+     * Automatically normalizes timing to ensure animations start at time 0.
+     * This is important for animation system consistency and performance.
+     */
+    build(): SkeletalAnimation;
+}
+//# sourceMappingURL=MartialArtsAnimationBuilder.d.ts.map