blacktrigram 0.7.2

package/lib/systems/ResponsiveScaling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponsiveScaling.js","names":[],"sources":["../../src/systems/ResponsiveScaling.ts"],"sourcesContent":["/**\n * Responsive Scaling System for Black Trigram\n * \n * Centralized scaling calculations for responsive layout across all screen sizes.\n * Implements proportional font and spacing scaling with smooth transitions.\n * \n * Features:\n * - Five screen size categories (mobile, tablet, desktop, large, xlarge)\n * - Font scaling: 0.8x (mobile) to 1.4x (4K displays)\n * - Spacing scaling: 0.5x (mobile) to 1.5x (4K displays)\n * - Korean text readability: 14-24px range enforced\n * - Smooth CSS transitions for resize operations\n * - 60fps performance maintained\n * \n * @module systems/ResponsiveScaling\n * @category Responsive Layout\n * @korean 반응형스케일시스템\n */\n\nimport type {\n  ScreenSize,\n  ResponsiveBreakpoints,\n  FontScaleMap,\n  SpacingScaleMap,\n  ResponsiveScaleConfig,\n  ResizeTransitionConfig,\n  ResponsiveValues,\n  ScreenSizeTestResult,\n} from '../types/ResponsiveTypes';\n\n// Re-export types for convenience\nexport type {\n  ScreenSize,\n  ResponsiveBreakpoints,\n  FontScaleMap,\n  SpacingScaleMap,\n  ResponsiveScaleConfig,\n  ResizeTransitionConfig,\n  ResponsiveValues,\n  ScreenSizeTestResult,\n};\n\n/**\n * Standard breakpoints for responsive design\n * Maps viewport widths to device categories\n * \n * Note: XLARGE is defined as a reference value (2560px) but xlarge category\n * starts at LARGE (1920px). This allows for consistent scaling across all\n * displays from 1920px upwards, including 2K, 4K, and ultra-wide monitors.\n * \n * @constant\n * @category Responsive Layout\n */\nexport const RESPONSIVE_BREAKPOINTS: ResponsiveBreakpoints = {\n  MOBILE: 768,      // < 768px: Mobile devices\n  TABLET: 1024,     // 768-1024px: Tablets\n  DESKTOP: 1440,    // 1024-1440px: Standard desktop\n  LARGE: 1920,      // 1440-1920px: HD/2K displays\n  XLARGE: 2560,     // Reference for 4K displays (xlarge starts at 1920px)\n} as const;\n\n/**\n * Font scaling multipliers by screen size\n * Base size (16px) * scale = final size\n * \n * Results clamped to 14-24px for readability\n * \n * @constant\n * @category Typography\n */\nexport const FONT_SCALE_MAP: FontScaleMap = {\n  mobile: 0.8,    // 16px * 0.8 = 12.8px → clamped to 14px min\n  tablet: 0.9,    // 16px * 0.9 = 14.4px\n  desktop: 1.0,   // 16px * 1.0 = 16px (base)\n  large: 1.2,     // 16px * 1.2 = 19.2px\n  xlarge: 1.4,    // 16px * 1.4 = 22.4px → clamped to 24px max\n} as const;\n\n/**\n * Spacing scaling multipliers by screen size\n * Base spacing * scale = final spacing\n * \n * @constant\n * @category Layout\n */\nexport const SPACING_SCALE_MAP: SpacingScaleMap = {\n  mobile: 0.5,    // Compact spacing for small screens\n  tablet: 0.75,   // Moderate spacing for tablets\n  desktop: 1.0,   // Standard reference spacing\n  large: 1.25,    // Spacious for large displays\n  xlarge: 1.5,    // Maximum spacing for 4K\n} as const;\n\n/**\n * Default transition configuration for smooth resizing\n * Optimized for 60fps performance\n * \n * @constant\n * @category Animation\n */\nexport const DEFAULT_RESIZE_TRANSITION: ResizeTransitionConfig = {\n  duration: '300ms',\n  easing: 'ease-in-out',\n  properties: ['font-size', 'padding', 'margin', 'width', 'height'] as const,\n  enabled: true,\n} as const;\n\n/**\n * Font size constraints for Korean and English text\n * Ensures readability across all screen sizes\n * \n * @constant\n * @category Typography\n */\nexport const FONT_SIZE_CONSTRAINTS = {\n  /** Minimum body text size for readability */\n  MIN_BODY_SIZE: 14,\n  /** Maximum size before text becomes too large */\n  MAX_SIZE: 24,\n  /** Base reference size (desktop) */\n  BASE_SIZE: 16,\n} as const;\n\n/**\n * Determine screen size category from viewport width\n * \n * Categories:\n * - mobile: < 768px (phones)\n * - tablet: 768-1024px (tablets)\n * - desktop: 1024-1440px (standard monitors)\n * - large: 1440-1920px (HD/2K displays)\n * - xlarge: ≥1920px (4K/ultra-wide)\n * \n * @param width - Viewport width in pixels\n * @returns Screen size category\n * \n * @example\n * ```typescript\n * getScreenSize(375);  // 'mobile'\n * getScreenSize(768);  // 'tablet'\n * getScreenSize(1920); // 'xlarge'\n * ```\n * \n * @public\n * @korean 화면크기얻기\n */\nexport function getScreenSize(width: number): ScreenSize {\n  if (width < RESPONSIVE_BREAKPOINTS.MOBILE) return 'mobile';\n  if (width < RESPONSIVE_BREAKPOINTS.TABLET) return 'tablet';\n  if (width < RESPONSIVE_BREAKPOINTS.DESKTOP) return 'desktop';\n  if (width < RESPONSIVE_BREAKPOINTS.LARGE) return 'large';\n  return 'xlarge';\n}\n\n/**\n * Calculate scaled font size with readability constraints\n * \n * Formula: baseSize * scale\n * Clamped: max(minSize, min(maxSize, calculated))\n * \n * Ensures Korean and English text remain readable at all sizes\n * \n * @param baseSize - Base font size in pixels (typically 16px)\n * @param screenSize - Current screen size category\n * @param minSize - Minimum allowed size (default: 14px)\n * @param maxSize - Maximum allowed size (default: 24px)\n * @returns Calculated font size in pixels\n * \n * @example\n * ```typescript\n * calculateFontSize(16, 'mobile');  // 14 (clamped from 12.8)\n * calculateFontSize(16, 'desktop'); // 16\n * calculateFontSize(16, 'xlarge');  // 22.4\n * calculateFontSize(20, 'xlarge', 14, 24); // 24 (clamped from 28)\n * ```\n * \n * @public\n * @korean 글꼴크기계산\n */\nexport function calculateFontSize(\n  baseSize: number,\n  screenSize: ScreenSize,\n  minSize: number = FONT_SIZE_CONSTRAINTS.MIN_BODY_SIZE,\n  maxSize: number = FONT_SIZE_CONSTRAINTS.MAX_SIZE\n): number {\n  const scale = FONT_SCALE_MAP[screenSize];\n  const scaled = baseSize * scale;\n  \n  // Clamp to readable range\n  return Math.max(minSize, Math.min(maxSize, scaled));\n}\n\n/**\n * Calculate scaled spacing value\n * \n * Formula: baseSpacing * scale\n * Rounded to nearest integer for crisp rendering\n * \n * @param baseSpacing - Base spacing value in pixels\n * @param screenSize - Current screen size category\n * @returns Calculated spacing in pixels (rounded)\n * \n * @example\n * ```typescript\n * calculateSpacing(20, 'mobile');  // 10 (20 * 0.5)\n * calculateSpacing(20, 'desktop'); // 20\n * calculateSpacing(20, 'xlarge');  // 30 (20 * 1.5)\n * ```\n * \n * @public\n * @korean 간격계산\n */\nexport function calculateSpacing(\n  baseSpacing: number,\n  screenSize: ScreenSize\n): number {\n  const scale = SPACING_SCALE_MAP[screenSize];\n  return Math.round(baseSpacing * scale);\n}\n\n/**\n * Get font scale multiplier for screen size\n * \n * @param screenSize - Screen size category\n * @returns Scale multiplier (0.8 - 1.4)\n * \n * @example\n * ```typescript\n * getFontScale('mobile');  // 0.8\n * getFontScale('desktop'); // 1.0\n * getFontScale('xlarge');  // 1.4\n * ```\n * \n * @public\n * @korean 글꼴스케일얻기\n */\nexport function getFontScale(screenSize: ScreenSize): number {\n  return FONT_SCALE_MAP[screenSize];\n}\n\n/**\n * Get spacing scale multiplier for screen size\n * \n * @param screenSize - Screen size category\n * @returns Scale multiplier (0.5 - 1.5)\n * \n * @example\n * ```typescript\n * getSpacingScale('mobile');  // 0.5\n * getSpacingScale('desktop'); // 1.0\n * getSpacingScale('xlarge');  // 1.5\n * ```\n * \n * @public\n * @korean 간격스케일얻기\n */\nexport function getSpacingScale(screenSize: ScreenSize): number {\n  return SPACING_SCALE_MAP[screenSize];\n}\n\n/**\n * Create CSS transition string for smooth resizing\n * \n * @param config - Transition configuration (optional)\n * @returns CSS transition string\n * \n * @example\n * ```typescript\n * createTransitionString();\n * // 'font-size 300ms ease-in-out, padding 300ms ease-in-out, ...'\n * \n * createTransitionString({ duration: '200ms', easing: 'linear' });\n * // 'font-size 200ms linear, padding 200ms linear, ...'\n * ```\n * \n * @public\n * @korean 전환문자열생성\n */\nexport function createTransitionString(\n  config: Partial<ResizeTransitionConfig> = {}\n): string {\n  const {\n    duration = DEFAULT_RESIZE_TRANSITION.duration,\n    easing = DEFAULT_RESIZE_TRANSITION.easing,\n    properties = DEFAULT_RESIZE_TRANSITION.properties,\n    enabled = DEFAULT_RESIZE_TRANSITION.enabled,\n  } = config;\n\n  if (!enabled) {\n    return 'none';\n  }\n\n  return properties\n    .map((prop) => `${prop} ${duration} ${easing}`)\n    .join(', ');\n}\n\n/**\n * Create complete responsive scale configuration\n * \n * @param width - Viewport width\n * @param height - Viewport height\n * @returns Complete responsive configuration\n * \n * @example\n * ```typescript\n * const config = createResponsiveConfig(375, 667);\n * console.log(config.screenSize);  // 'mobile'\n * console.log(config.fontScale);   // 0.8\n * console.log(config.spacingScale); // 0.5\n * ```\n * \n * @public\n * @korean 반응형설정생성\n */\nexport function createResponsiveConfig(\n  width: number,\n  height: number\n): ResponsiveScaleConfig {\n  const screenSize = getScreenSize(width);\n  const fontScale = getFontScale(screenSize);\n  const spacingScale = getSpacingScale(screenSize);\n\n  return {\n    screenSize,\n    fontScale,\n    spacingScale,\n    viewport: { width, height },\n  };\n}\n\n/**\n * Calculate all responsive values for a component\n * \n * Computes font sizes, spacing, and transitions based on screen size\n * Ready-to-use values for component styling\n * \n * @param width - Viewport width\n * @param baseFontSize - Base font size (default: 16px)\n * @param baseSpacing - Base spacing unit (default: 16px)\n * @returns Complete responsive values\n * \n * @example\n * ```typescript\n * const values = calculateResponsiveValues(375);\n * \n * <div style={{\n *   fontSize: values.fontSize.body,\n *   padding: values.spacing.md,\n *   transition: values.transition,\n * }}>\n *   Responsive content\n * </div>\n * ```\n * \n * @public\n * @korean 반응형값계산\n */\nexport function calculateResponsiveValues(\n  width: number,\n  baseFontSize: number = FONT_SIZE_CONSTRAINTS.BASE_SIZE,\n  baseSpacing: number = 16\n): ResponsiveValues {\n  const screenSize = getScreenSize(width);\n  \n  // Calculate font sizes for all text levels\n  const fontSize = {\n    small: calculateFontSize(baseFontSize * 0.75, screenSize, 12, 18),\n    body: calculateFontSize(baseFontSize, screenSize),\n    title: calculateFontSize(baseFontSize * 1.5, screenSize, 18, 28),\n    hero: calculateFontSize(baseFontSize * 2.25, screenSize, 24, 36),\n    hud: calculateFontSize(baseFontSize * 1.25, screenSize, 16, 24),\n  };\n\n  // Calculate spacing scale\n  const spacing = {\n    xs: calculateSpacing(baseSpacing * 0.5, screenSize),\n    sm: calculateSpacing(baseSpacing * 0.75, screenSize),\n    md: calculateSpacing(baseSpacing, screenSize),\n    lg: calculateSpacing(baseSpacing * 1.5, screenSize),\n    xl: calculateSpacing(baseSpacing * 2, screenSize),\n  };\n\n  // Create transition string\n  const transition = createTransitionString();\n\n  return {\n    fontSize,\n    spacing,\n    transition,\n  };\n}\n\n/**\n * Test screen size determination for validation\n * \n * Useful for testing and debugging responsive breakpoints.\n * Screen size is determined by width (breakpoints), but height is included\n * in the result for testing portrait/landscape orientations.\n * \n * @param width - Viewport width to test\n * @param height - Viewport height to test\n * @returns Test result with screen size and device type flags\n * \n * @example\n * ```typescript\n * const result = testScreenSize(768, 1024);\n * console.log(result.screenSize);  // 'tablet'\n * console.log(result.isTablet);    // true\n * console.log(result.isMobile);    // false\n * ```\n * \n * @public\n * @korean 화면크기테스트\n */\nexport function testScreenSize(\n  width: number,\n  height: number\n): ScreenSizeTestResult {\n  const screenSize = getScreenSize(width);\n  const isLandscape = width > height;\n  \n  return {\n    width,\n    height,\n    screenSize,\n    isMobile: screenSize === 'mobile',\n    isTablet: screenSize === 'tablet',\n    isDesktop: screenSize === 'desktop' || screenSize === 'large' || screenSize === 'xlarge',\n    // Include landscape in test result for completeness\n    isLandscape,\n  };\n}\n\n/**\n * Check if screen size is mobile\n * \n * @param width - Viewport width\n * @returns True if mobile screen size\n * \n * @public\n * @korean 모바일확인\n */\nexport function isMobileSize(width: number): boolean {\n  return getScreenSize(width) === 'mobile';\n}\n\n/**\n * Check if screen size is tablet\n * \n * @param width - Viewport width\n * @returns True if tablet screen size\n * \n * @public\n * @korean 태블릿확인\n */\nexport function isTabletSize(width: number): boolean {\n  return getScreenSize(width) === 'tablet';\n}\n\n/**\n * Check if screen size is desktop or larger\n * \n * @param width - Viewport width\n * @returns True if desktop, large, or xlarge screen size\n * \n * @public\n * @korean 데스크톱확인\n */\nexport function isDesktopSize(width: number): boolean {\n  const size = getScreenSize(width);\n  return size === 'desktop' || size === 'large' || size === 'xlarge';\n}\n"],"mappings":"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"}

package/lib/systems/TrigramSystem.d.ts

@@ -0,0 +1,388 @@
+import { KoreanText, TrigramStance } from "../types/common";
+import { PlayerState } from "./player";
+import { TrigramTransitionCost } from "./trigram";
+/**
+ * Stance counter relationships based on I Ching philosophy
+ *
+ * Each stance has a counter stance that provides tactical advantage:
+ * - **GEON (Heaven)** countered by **GAM (Water)** - Water flows around Heaven's force
+ * - **TAE (Lake)** countered by **GON (Earth)** - Earth contains and grounds Lake
+ * - **LI (Fire)** countered by **SON (Wind)** - Wind disperses Fire's intensity
+ * - **JIN (Thunder)** countered by **GAN (Mountain)** - Mountain absorbs Thunder's impact
+ * - **SON (Wind)** countered by **GEON (Heaven)** - Heaven's force overpowers Wind
+ * - **GAM (Water)** countered by **TAE (Lake)** - Lake contains and channels Water
+ * - **GAN (Mountain)** countered by **LI (Fire)** - Fire melts Mountain's solidity
+ * - **GON (Earth)** countered by **JIN (Thunder)** - Thunder breaks Earth's stability
+ *
+ * Using a counter stance provides a 1.2x damage multiplier in combat.
+ *
+ * @korean 팔괘 상극 관계 (Eight Trigram Counter Relationships)
+ */
+export declare const STANCE_COUNTERS: Record<TrigramStance, TrigramStance>;
+/**
+ * Counter stance damage multiplier
+ * Applied when using a counter stance against opponent's stance
+ *
+ * @korean 상극 자세 피해 배율
+ */
+export declare const COUNTER_STANCE_DAMAGE_MULTIPLIER = 1.2;
+/**
+ * Apply counter stance damage bonus when appropriate.
+ *
+ * This helper should be used by combat damage calculation code after it has
+ * determined whether the current stance matchup is a counter stance
+ * (for example, via an `isCounterStance` check elsewhere in the system).
+ *
+ * When `isCounterStance` is `true`, the base damage is multiplied by
+ * {@link COUNTER_STANCE_DAMAGE_MULTIPLIER}. Non-positive damage values are
+ * returned unchanged to avoid introducing invalid negative or zero scaling.
+ *
+ * @param baseDamage - The pre-modifier damage value.
+ * @param isCounterStance - Whether the attacker is using a counter stance.
+ * @returns The adjusted damage value with counter stance bonus applied when relevant.
+ *
+ * @example
+ * ```ts
+ * const isCounter = trigramSystem.isCounterStance(attackerStance, defenderStance);
+ * const finalDamage = applyCounterStanceDamage(baseDamage, isCounter);
+ * ```
+ *
+ * @korean
+ * 반격 자세(상극 자세)일 때만 피해 배율(1.2배)을 적용합니다.
+ */
+export declare function applyCounterStanceDamage(baseDamage: number, isCounterStance: boolean): number;
+/**
+ * System for managing Eight Trigram (팔괘) stance transitions and combat calculations.
+ *
+ * **Korean**: 팔괘 시스템 (Eight Trigram System)
+ *
+ * The TrigramSystem implements the core mechanics of the Eight Trigram martial arts system,
+ * managing stance transitions, calculating effectiveness, and determining resource costs.
+ * Based on I Ching (易經) philosophy adapted for tactical combat.
+ *
+ * ## Key Responsibilities
+ *
+ * - Validate stance transitions based on Ki and Stamina costs
+ * - Calculate transition difficulty between stances
+ * - Recommend optimal stance choices
+ * - Determine stance effectiveness in combat matchups
+ * - Apply archetype-specific modifiers to transitions
+ *
+ * @example
+ * ```typescript
+ * const trigramSystem = new TrigramSystem();
+ *
+ * // Check if transition is possible
+ * const canTransition = trigramSystem.canTransitionTo(
+ *   TrigramStance.GEON,
+ *   TrigramStance.GAM,
+ *   playerState
+ * );
+ *
+ * // Get recommended stance
+ * const recommendedStance = trigramSystem.recommendStance(playerState);
+ * ```
+ *
+ * @public
+ * @category Trigram System
+ * @korean 팔괘시스템
+ */
+export declare class TrigramSystem {
+    private calculator;
+    /**
+     * Creates a new TrigramSystem instance.
+     *
+     * Initializes the internal calculator for stance effectiveness and transition difficulty.
+     */
+    constructor();
+    /**
+     * Gets the defensive/offensive characteristic of a stance.
+     *
+     * **Korean**: 자세 특성 조회 (Stance Characteristic Query)
+     *
+     * Returns whether a stance is primarily defensive, offensive, or balanced.
+     * This information is useful for UI display and tactical decision-making.
+     *
+     * ## Stance Classifications
+     *
+     * - **Defensive**: 간 (GAN/Mountain), 곤 (GON/Earth) - Protect vital areas
+     * - **Offensive**: 건 (GEON/Heaven), 진 (JIN/Thunder) - Expose for power
+     * - **Balanced**: 태 (TAE/Lake), 리 (LI/Fire), 손 (SON/Wind), 감 (GAM/Water)
+     *
+     * @param stance - Trigram stance to query
+     * @returns "defensive", "offensive", or "balanced"
+     *
+     * @example
+     * ```typescript
+     * const characteristic = trigramSystem.getStanceCharacteristic(TrigramStance.GAN);
+     * console.log(characteristic); // "defensive"
+     *
+     * const offensive = trigramSystem.getStanceCharacteristic(TrigramStance.GEON);
+     * console.log(offensive); // "offensive"
+     * ```
+     *
+     * @public
+     * @korean 자세특성조회
+     */
+    getStanceCharacteristic(stance: TrigramStance): "defensive" | "offensive" | "balanced";
+    /**
+     * Checks if a stance provides defensive advantages.
+     *
+     * **Korean**: 방어 자세 확인 (Check Defensive Stance)
+     *
+     * @param stance - Trigram stance to check
+     * @returns true if stance is defensive, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (trigramSystem.isDefensiveStance(player.currentStance)) {
+     *   console.log("Player is in defensive posture");
+     * }
+     * ```
+     *
+     * @public
+     * @korean 방어자세확인
+     */
+    isDefensiveStance(stance: TrigramStance): boolean;
+    /**
+     * Checks if a stance provides offensive advantages.
+     *
+     * **Korean**: 공격 자세 확인 (Check Offensive Stance)
+     *
+     * @param stance - Trigram stance to check
+     * @returns true if stance is offensive, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (trigramSystem.isOffensiveStance(player.currentStance)) {
+     *   console.log("Player is in offensive posture");
+     * }
+     * ```
+     *
+     * @public
+     * @korean 공격자세확인
+     */
+    isOffensiveStance(stance: TrigramStance): boolean;
+    /**
+     * Checks if a player can transition from one stance to another.
+     *
+     * Validates that the player has sufficient Ki (氣) and Stamina resources
+     * to perform the stance transition. Same-stance transitions are always valid.
+     *
+     * @param fromStance - Current stance
+     * @param toStance - Target stance
+     * @param player - Player state with current Ki and Stamina
+     * @returns true if transition is possible, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const canChange = trigramSystem.canTransitionTo(
+     *   TrigramStance.GEON, // From Heaven
+     *   TrigramStance.GON,  // To Earth
+     *   player
+     * );
+     * ```
+     *
+     * @public
+     * @korean 자세전환가능확인
+     */
+    canTransitionTo(fromStance: TrigramStance, toStance: TrigramStance, player: PlayerState): boolean;
+    /**
+     * Recommends the optimal stance for current combat situation.
+     *
+     * Calculates the least-cost stance transition from the player's current position.
+     * Uses combined cost of Ki, Stamina, and transition time to determine best option.
+     *
+     * **Algorithm**: Evaluates all eight stances and selects the one with minimum
+     * total cost (Ki + Stamina + Time).
+     *
+     * @param player - Player state with current stance
+     * @returns Recommended stance to transition to
+     *
+     * @example
+     * ```typescript
+     * const recommended = trigramSystem.recommendStance(player);
+     * console.log(`Consider switching to ${recommended}`);
+     * ```
+     *
+     * @public
+     * @korean 최적자세추천
+     */
+    recommendStance(player: PlayerState): TrigramStance;
+    /**
+     * Calculates the resource cost for transitioning between stances.
+     *
+     * Determines Ki, Stamina, and time costs based on the I Ching philosophical
+     * distance between trigrams. Applies archetype-specific modifiers for favored stances.
+     *
+     * ## Cost Calculation
+     *
+     * - **Base Cost**: 10 Ki, 15 Stamina per difficulty point
+     * - **Base Time**: 500ms per difficulty point
+     * - **Archetype Modifier**: 0.8x for favored stances, 1.0x otherwise
+     * - **Same Stance**: Zero cost
+     *
+     * @param from - Starting stance
+     * @param to - Target stance
+     * @param player - Optional player for archetype modifiers
+     * @returns Transition cost breakdown
+     *
+     * @example
+     * ```typescript
+     * const cost = trigramSystem.getTransitionCost(
+     *   TrigramStance.GEON,
+     *   TrigramStance.TAE,
+     *   player
+     * );
+     * console.log(`Cost: ${cost.ki} Ki, ${cost.stamina} Stamina`);
+     * ```
+     *
+     * @public
+     * @korean 자세전환비용
+     */
+    getTransitionCost(from: TrigramStance, to: TrigramStance, player?: PlayerState): TrigramTransitionCost;
+    /**
+     * Calculates stance effectiveness in combat matchup.
+     *
+     * Determines the multiplier advantage/disadvantage when one stance attacks another.
+     * Based on I Ching elemental relationships (e.g., Water extinguishes Fire).
+     *
+     * @param attackerStance - Attacking player's stance
+     * @param defenderStance - Defending player's stance
+     * @returns Effectiveness multiplier (0.5 = disadvantage, 1.0 = neutral, 1.5 = advantage)
+     *
+     * @example
+     * ```typescript
+     * const effectiveness = trigramSystem.calculateStanceEffectiveness(
+     *   TrigramStance.GAM,  // Water
+     *   TrigramStance.LI    // Fire
+     * ); // Returns > 1.0 (Water beats Fire)
+     * ```
+     *
+     * @public
+     * @korean 자세효과성계산
+     */
+    calculateStanceEffectiveness(attackerStance: TrigramStance, defenderStance: TrigramStance): number;
+    /**
+     * Gets bilingual name for a stance.
+     *
+     * Returns Korean (Hangul) and English names for display purposes.
+     *
+     * @param stance - Stance to get name for
+     * @returns Object with korean and english name properties
+     *
+     * @example
+     * ```typescript
+     * const name = trigramSystem.getStanceName(TrigramStance.GEON);
+     * console.log(`${name.korean} (${name.english})`); // "건 (Heaven)"
+     * ```
+     *
+     * @public
+     * @korean 자세이름조회
+     */
+    getStanceName(stance: TrigramStance): {
+        korean: string;
+        english: string;
+    };
+    /**
+     * Gets the counter stance for opponent's current stance.
+     *
+     * Returns the stance that provides tactical advantage against the opponent's stance,
+     * based on I Ching elemental relationships. Using a counter stance provides a 1.2x
+     * damage multiplier in combat.
+     *
+     * **Korean Philosophy (상극 자세)**:
+     * - Water counters Heaven (flows around force)
+     * - Earth counters Lake (grounds and contains)
+     * - Wind counters Fire (disperses intensity)
+     * - Mountain counters Thunder (absorbs impact)
+     *
+     * @param opponentStance - Opponent's current stance
+     * @returns Counter stance that provides advantage
+     *
+     * @example
+     * ```typescript
+     * const counterStance = trigramSystem.getCounterStance(TrigramStance.GEON);
+     * console.log(counterStance); // TrigramStance.GAM (Water counters Heaven)
+     * ```
+     *
+     * @public
+     * @korean 상극자세조회
+     */
+    getCounterStance(opponentStance: TrigramStance): TrigramStance;
+    /**
+     * Checks if player's stance counters opponent's stance.
+     *
+     * Determines if the player has a tactical advantage through stance matchup.
+     * When true, player should receive a 1.2x damage multiplier for attacks.
+     *
+     * @param myStance - Player's current stance
+     * @param opponentStance - Opponent's current stance
+     * @returns True if player's stance counters opponent's stance
+     *
+     * @example
+     * ```typescript
+     * const hasAdvantage = trigramSystem.isCounterStance(
+     *   TrigramStance.GAM,  // My stance: Water
+     *   TrigramStance.GEON  // Opponent: Heaven
+     * ); // Returns true - Water counters Heaven
+     *
+     * if (hasAdvantage) {
+     *   damage *= 1.2; // Apply counter bonus
+     * }
+     * ```
+     *
+     * @public
+     * @korean 상극자세확인
+     */
+    isCounterStance(myStance: TrigramStance, opponentStance: TrigramStance): boolean;
+    /**
+     * Gets complete stance data for UI display.
+     *
+     * Returns structured data object containing stance ID and bilingual names.
+     *
+     * @param stance - Stance to get data for
+     * @returns Stance data object
+     *
+     * @public
+     * @korean 자세데이터조회
+     */
+    getCurrentStanceData(stance: TrigramStance): {
+        id: TrigramStance;
+        name: KoreanText;
+        korean: string;
+        english: string;
+    };
+    /**
+     * Validates a stance transition with detailed feedback.
+     *
+     * Checks if transition is valid and provides reason if not.
+     * More detailed than {@link canTransitionTo}, includes specific failure reasons.
+     *
+     * @param fromStance - Current stance
+     * @param toStance - Target stance
+     * @param player - Player state
+     * @returns Validation result with optional failure reason
+     *
+     * @example
+     * ```typescript
+     * const validation = trigramSystem.validateTransition(
+     *   TrigramStance.GEON,
+     *   TrigramStance.GON,
+     *   player
+     * );
+     * if (!validation.valid) {
+     *   console.error(validation.reason);
+     * }
+     * ```
+     *
+     * @public
+     * @korean 자세전환검증
+     */
+    validateTransition(fromStance: TrigramStance, toStance: TrigramStance, player: PlayerState): {
+        valid: boolean;
+        reason?: string;
+    };
+}
+export default TrigramSystem;
+//# sourceMappingURL=TrigramSystem.d.ts.map

package/lib/systems/TrigramSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrigramSystem.d.ts","sourceRoot":"","sources":["../../src/systems/TrigramSystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,EAAyB,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAIzE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,aAAa,EAAE,aAAa,CAShE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,MAAM,CAMR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAAoB;IAEtC;;;;OAIG;;IAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,uBAAuB,CACrB,MAAM,EAAE,aAAa,GACpB,WAAW,GAAG,WAAW,GAAG,UAAU;IAezC;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO;IAIjD;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO;IAIjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CACb,UAAU,EAAE,aAAa,EACzB,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,WAAW,GAClB,OAAO;IAYV;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa;IAiBnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACI,iBAAiB,CACtB,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,aAAa,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,qBAAqB;IAmCxB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,4BAA4B,CAC1B,cAAc,EAAE,aAAa,EAC7B,cAAc,EAAE,aAAa,GAC5B,MAAM;IAOT;;;;;;;;;;;;;;;;OAgBG;IACH,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAezE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gBAAgB,CAAC,cAAc,EAAE,aAAa,GAAG,aAAa;IAI9D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,eAAe,CAAC,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,GAAG,OAAO;IAIhF;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG;QAC3C,EAAE,EAAE,aAAa,CAAC;QAClB,IAAI,EAAE,UAAU,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB;IAUD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAAkB,CAChB,UAAU,EAAE,aAAa,EACzB,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,WAAW,GAClB;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAuBvC;AAED,eAAe,aAAa,CAAC"}