blacktrigram 0.7.2

package/lib/utils/controlMapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlMapping.js","names":[],"sources":["../../src/utils/controlMapping.ts"],"sourcesContent":["/**\n * Control Mapping System for Black Trigram\n * Manages keyboard control bindings with localStorage persistence\n * \n * @module utils/controlMapping\n * @category Input System\n * @korean 컨트롤 매핑 시스템\n */\n\nimport { TrigramStance } from \"../types/common\";\nimport { TRIGRAM_STANCES_ORDER } from \"../systems/trigram/types\";\n\n/**\n * Control binding configuration\n * Maps game actions to keyboard keys\n * \n * @category Input System\n * @korean 컨트롤 바인딩\n */\nexport interface ControlBinding {\n  /** Stance selection keys (1-8 by default) */\n  readonly stances: readonly string[];\n  /** Technique execution keys (Q-E-R-T-Y-F-G-Z-X-C by default) */\n  readonly techniques: readonly string[];\n  /** Attack action key */\n  readonly attack: string;\n  /** Block/Guard action key */\n  readonly block: string;\n  /** Movement keys */\n  readonly movement: {\n    readonly up: string;\n    readonly down: string;\n    readonly left: string;\n    readonly right: string;\n  };\n  /** Vital points overlay toggle key */\n  readonly vitalPointsOverlay: string;\n  /** Stance side switch key (swap front foot) */\n  readonly stanceSideSwitch?: string;\n  /** Pause/Menu keys */\n  readonly pause: readonly string[];\n}\n\n/**\n * Storage key for localStorage persistence\n */\nconst STORAGE_KEY = \"blacktrigram_controls\";\n\n/**\n * Default control bindings following game design specifications\n * NEW: Conflict-free control scheme with Q-E-R-T-Y-F-G-Z-X-C for techniques\n * \n * Uses keys around WASD that are easy to reach with left hand\n * No conflicts with movement, browser shortcuts, or function keys\n * \n * All keys stored in lowercase for consistent comparison\n * \n * @see CONTROLS.md for complete documentation\n */\nconst DEFAULT_BINDINGS: ControlBinding = {\n  stances: [\"1\", \"2\", \"3\", \"4\", \"5\", \"6\", \"7\", \"8\"],\n  techniques: [\"q\", \"e\", \"r\", \"t\", \"y\", \"f\", \"g\", \"z\", \"x\", \"c\"],\n  attack: \" \", // Spacebar\n  block: \"b\",\n  movement: {\n    up: \"w\",\n    down: \"s\",\n    left: \"a\",\n    right: \"d\",\n  },\n  vitalPointsOverlay: \"v\",\n  stanceSideSwitch: \"h\", // H key for switching front foot\n  pause: [\"escape\", \"m\"],\n};\n\n/**\n * Control Mapper class for managing keyboard bindings\n * Handles loading, saving, and querying control mappings\n * \n * @example\n * ```typescript\n * const mapper = new ControlMapper();\n * \n * // Get stance for key press\n * const stance = mapper.getStanceForKey(\"3\"); // Returns 2 (0-indexed)\n * \n * // Update bindings\n * mapper.saveBindings({\n *   ...mapper.getBindings(),\n *   stances: ['q', 'w', 'e', 'r', 'a', 's', 'd', 'f']\n * });\n * ```\n * \n * @public\n * @korean 컨트롤매퍼\n */\nexport class ControlMapper {\n  private bindings: ControlBinding;\n\n  /**\n   * Creates a new ControlMapper instance\n   * Automatically loads bindings from localStorage\n   */\n  constructor() {\n    this.bindings = this.loadBindings();\n  }\n\n  /**\n   * Load bindings from localStorage\n   * Returns default bindings if none exist\n   * \n   * @returns Control bindings from storage or defaults\n   * @korean 바인딩 로드\n   */\n  loadBindings(): ControlBinding {\n    try {\n      const saved = localStorage.getItem(STORAGE_KEY);\n      if (saved) {\n        const parsed = JSON.parse(saved) as ControlBinding;\n        // Validate loaded bindings\n        if (this.validateBindings(parsed)) {\n          return parsed;\n        }\n      }\n    } catch (error) {\n      console.warn(\"Failed to load control bindings:\", error);\n    }\n    return this.getDefaultBindings();\n  }\n\n  /**\n   * Save bindings to localStorage\n   * \n   * @param bindings - Control bindings to save\n   * @korean 바인딩 저장\n   */\n  saveBindings(bindings: ControlBinding): void {\n    if (!this.validateBindings(bindings)) {\n      console.error(\"Invalid control bindings, not saving\");\n      return;\n    }\n\n    try {\n      localStorage.setItem(STORAGE_KEY, JSON.stringify(bindings));\n      this.bindings = bindings;\n    } catch (error) {\n      console.error(\"Failed to save control bindings:\", error);\n    }\n  }\n\n  /**\n   * Get default control bindings\n   * \n   * @returns Default control configuration\n   * @korean 기본 바인딩\n   */\n  getDefaultBindings(): ControlBinding {\n    return { ...DEFAULT_BINDINGS };\n  }\n\n  /**\n   * Get current control bindings\n   * \n   * @returns Current control configuration\n   * @korean 현재 바인딩\n   */\n  getBindings(): ControlBinding {\n    return { ...this.bindings };\n  }\n\n  /**\n   * Reset bindings to default\n   * \n   * @korean 기본값으로 리셋\n   */\n  resetToDefaults(): void {\n    this.saveBindings(this.getDefaultBindings());\n  }\n\n  /**\n   * Get stance index for a given key\n   * Returns null if key is not bound to a stance\n   * \n   * @param key - Keyboard key to check\n   * @returns Stance index (0-7) or null\n   * @korean 키에 대한 자세 조회\n   */\n  getStanceForKey(key: string): number | null {\n    const normalizedKey = key.toLowerCase();\n    const index = this.bindings.stances.findIndex(\n      (k) => k.toLowerCase() === normalizedKey\n    );\n    return index >= 0 ? index : null;\n  }\n\n  /**\n   * Get key for a given stance index\n   * \n   * @param stanceIndex - Stance index (0-7)\n   * @returns Key bound to that stance\n   * @korean 자세에 대한 키 조회\n   */\n  getKeyForStance(stanceIndex: number): string | null {\n    if (stanceIndex < 0 || stanceIndex >= this.bindings.stances.length) {\n      return null;\n    }\n    return this.bindings.stances[stanceIndex];\n  }\n\n  /**\n   * Get TrigramStance enum for a given key\n   * \n   * @param key - Keyboard key to check\n   * @returns TrigramStance or null\n   * @korean 키에 대한 팔괘 자세\n   */\n  getTrigramStanceForKey(key: string): TrigramStance | null {\n    const index = this.getStanceForKey(key);\n    if (index === null) return null;\n    return TRIGRAM_STANCES_ORDER[index] ?? null;\n  }\n\n  /**\n   * Get technique index for a key\n   * \n   * @param key - Keyboard key\n   * @returns Technique index (0-9) or null\n   * @korean 기술 키 확인\n   */\n  getTechniqueForKey(key: string): number | null {\n    const normalizedKey = key.toLowerCase();\n    const index = this.bindings.techniques.indexOf(normalizedKey);\n    return index >= 0 ? index : null;\n  }\n\n  /**\n   * Get key for technique index\n   * \n   * @param index - Technique index (0-9)\n   * @returns Key or null\n   * @korean 기술 인덱스로 키 조회\n   */\n  getKeyForTechnique(index: number): string | null {\n    if (index < 0 || index >= this.bindings.techniques.length) {\n      return null;\n    }\n    return this.bindings.techniques[index];\n  }\n\n  /**\n   * Check if a key is bound to an action\n   * \n   * @param key - Keyboard key to check\n   * @returns Action name or null\n   * @korean 키 바인딩 확인\n   */\n  getActionForKey(key: string): string | null {\n    const normalizedKey = key.toLowerCase();\n\n    // Check stance keys\n    if (this.getStanceForKey(key) !== null) {\n      return \"stance\";\n    }\n\n    // Check other actions\n    if (normalizedKey === this.bindings.attack.toLowerCase()) return \"attack\";\n    if (normalizedKey === this.bindings.block.toLowerCase()) return \"block\";\n\n    // Check movement\n    const movement = this.bindings.movement;\n    if (normalizedKey === movement.up.toLowerCase()) return \"move_up\";\n    if (normalizedKey === movement.down.toLowerCase()) return \"move_down\";\n    if (normalizedKey === movement.left.toLowerCase()) return \"move_left\";\n    if (normalizedKey === movement.right.toLowerCase()) return \"move_right\";\n\n    // Check vital points overlay\n    if (normalizedKey === this.bindings.vitalPointsOverlay.toLowerCase())\n      return \"vital_points_overlay\";\n\n    // Check stance side switch\n    if (\n      normalizedKey === this.bindings.stanceSideSwitch?.toLowerCase()\n    ) {\n      return \"stance_side_switch\";\n    }\n\n    // Check pause keys\n    if (\n      this.bindings.pause.some((k) => k.toLowerCase() === normalizedKey)\n    ) {\n      return \"pause\";\n    }\n\n    return null;\n  }\n\n  /**\n   * Validate control bindings\n   * Ensures no duplicate keys and all required keys are present\n   * \n   * @param bindings - Bindings to validate\n   * @returns True if valid\n   * @korean 바인딩 검증\n   */\n  private validateBindings(bindings: ControlBinding): boolean {\n    // Check that stances array has exactly 8 entries\n    if (\n      !bindings.stances ||\n      !Array.isArray(bindings.stances) ||\n      bindings.stances.length !== 8\n    ) {\n      return false;\n    }\n\n    // Check that techniques array has up to 10 entries\n    if (\n      !bindings.techniques ||\n      !Array.isArray(bindings.techniques) ||\n      bindings.techniques.length === 0 ||\n      bindings.techniques.length > 10\n    ) {\n      return false;\n    }\n\n    // Check for duplicate keys\n    const allKeys = [\n      ...bindings.stances,\n      ...bindings.techniques,\n      bindings.attack,\n      bindings.block,\n      bindings.movement.up,\n      bindings.movement.down,\n      bindings.movement.left,\n      bindings.movement.right,\n      bindings.vitalPointsOverlay,\n      ...bindings.pause,\n    ];\n\n    const uniqueKeys = new Set(allKeys.map((k) => k.toLowerCase()));\n    if (uniqueKeys.size !== allKeys.length) {\n      // Duplicate keys found\n      return false;\n    }\n\n    return true;\n  }\n\n  /**\n   * Check if bindings have conflicts\n   * Returns array of conflicting keys\n   * \n   * @param bindings - Bindings to check\n   * @returns Array of duplicate keys\n   * @korean 바인딩 충돌 확인\n   */\n  getConflicts(bindings: ControlBinding): string[] {\n    const keyCount = new Map<string, number>();\n    const conflicts: string[] = [];\n\n    const allKeys = [\n      ...bindings.stances,\n      ...bindings.techniques,\n      bindings.attack,\n      bindings.block,\n      bindings.movement.up,\n      bindings.movement.down,\n      bindings.movement.left,\n      bindings.movement.right,\n      bindings.vitalPointsOverlay,\n      ...bindings.pause,\n    ];\n\n    allKeys.forEach((key) => {\n      const normalized = key.toLowerCase();\n      keyCount.set(normalized, (keyCount.get(normalized) ?? 0) + 1);\n    });\n\n    keyCount.forEach((count, key) => {\n      if (count > 1) {\n        conflicts.push(key);\n      }\n    });\n\n    return conflicts;\n  }\n}\n"],"mappings":"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"}

package/lib/utils/deviceDetection.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Device Detection Utility
+ *
+ * Provides robust mobile device detection combining:
+ * - User-agent string analysis
+ * - Screen size detection
+ * - Touch capability detection
+ *
+ * This ensures mobile controls are shown on all mobile devices,
+ * including high-resolution phones that exceed typical mobile breakpoints.
+ *
+ * @module utils/deviceDetection
+ * @category Mobile
+ * @korean 기기감지유틸리티
+ */
+/**
+ * Device type classification
+ */
+export declare enum DeviceType {
+    /** Desktop computer or laptop */
+    DESKTOP = "desktop",
+    /** Mobile phone (iOS, Android, etc.) */
+    MOBILE = "mobile",
+    /** Tablet device (iPad, Android tablets) */
+    TABLET = "tablet"
+}
+/**
+ * Platform detection results
+ */
+export interface PlatformInfo {
+    /** Operating system type */
+    readonly os: "ios" | "android" | "windows" | "macos" | "linux" | "unknown";
+    /** Device type classification */
+    readonly deviceType: DeviceType;
+    /** Whether device has touch capability */
+    readonly hasTouch: boolean;
+    /** Whether device is mobile phone */
+    readonly isMobile: boolean;
+    /** Whether device is tablet */
+    readonly isTablet: boolean;
+    /** Whether device is desktop */
+    readonly isDesktop: boolean;
+    /** Screen width in pixels */
+    readonly screenWidth: number;
+    /** Screen height in pixels */
+    readonly screenHeight: number;
+}
+/**
+ * Mobile screen size breakpoint
+ * Devices with width <= this value are considered mobile by size
+ */
+export declare const MOBILE_BREAKPOINT = 768;
+/**
+ * Tablet screen size breakpoint
+ * Devices with width > MOBILE_BREAKPOINT and <= TABLET_BREAKPOINT are tablets
+ */
+export declare const TABLET_BREAKPOINT = 1024;
+/**
+ * Clear the cached platform information
+ * Useful when window is resized or device emulation changes
+ * Also clears CSS environment variable cache
+ *
+ * @public
+ */
+export declare function clearPlatformCache(): void;
+/**
+ * Detect device type and platform information
+ *
+ * Combines multiple detection methods for reliability:
+ * 1. User-agent string analysis (most reliable for device type)
+ * 2. Screen dimensions
+ * 3. Touch capability
+ *
+ * This ensures mobile controls are shown on:
+ * - Standard mobile phones (< 768px width)
+ * - High-resolution phones (>= 768px width but mobile user-agent)
+ * - Android 15/16 devices with 2K/4K resolutions (1200px+, 1440px+)
+ * - Tablets (user preference via touch support)
+ *
+ * **User-agent detection takes priority over screen size**, ensuring that
+ * high-end Android phones with desktop-class resolutions (e.g., Galaxy S23 Ultra,
+ * Pixel 9 Pro) are correctly identified as mobile devices.
+ *
+ * Results are cached to avoid re-parsing user-agent on every call.
+ * Cache is invalidated when screen dimensions change.
+ *
+ * @returns Complete platform information
+ *
+ * @example
+ * ```typescript
+ * const platform = detectPlatform();
+ *
+ * if (platform.isMobile) {
+ *   // Show mobile controls even on 4K Android phones
+ *   return <MobileControls />;
+ * }
+ * ```
+ *
+ * @public
+ * @korean 플랫폼감지
+ */
+export declare function detectPlatform(): PlatformInfo;
+/**
+ * Simple mobile check for backward compatibility
+ * Returns true for both mobile phones and tablets
+ *
+ * @returns True if device is mobile or tablet
+ *
+ * @public
+ * @korean 모바일확인
+ */
+export declare function isMobileDevice(): boolean;
+/**
+ * Check if device should use mobile controls
+ * Takes into account device type, screen size, and touch capability
+ *
+ * Uses user-agent detection to correctly identify mobile devices regardless
+ * of screen resolution. This ensures high-end Android 15/16 phones with
+ * 2K/4K displays (1200px+, 1440px+) show mobile controls.
+ *
+ * Also ensures tablets and touch-enabled devices always show mobile controls
+ * regardless of resolution, for better UX on touch devices.
+ *
+ * @returns True if mobile controls should be shown
+ *
+ * @example
+ * ```typescript
+ * // High-res Android phone (1440x3168) → returns true via user-agent
+ * // Desktop with 1440px screen → returns false (no mobile user-agent)
+ * // iPad Pro 12.9" (1024x1366) → returns true (tablet user-agent)
+ * // Surface Pro in tablet mode → returns true (touch + tablet size)
+ * if (shouldUseMobileControls()) {
+ *   return <VirtualDPad />; // Touch-optimized controls
+ * }
+ * ```
+ *
+ * @public
+ * @korean 모바일컨트롤사용
+ */
+export declare function shouldUseMobileControls(): boolean;
+/**
+ * Get safe area insets for device
+ * Returns appropriate values based on device type and OS
+ *
+ * For iOS devices, attempts to detect if device has a notch by checking
+ * screen dimensions. Falls back to CSS environment variables if available.
+ *
+ * @returns Safe area insets in pixels
+ *
+ * @public
+ * @korean 안전영역인셋
+ */
+export declare function getSafeAreaInsets(): {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+//# sourceMappingURL=deviceDetection.d.ts.map

package/lib/utils/deviceDetection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviceDetection.d.ts","sourceRoot":"","sources":["../../src/utils/deviceDetection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AACH,oBAAY,UAAU;IACpB,iCAAiC;IACjC,OAAO,YAAY;IACnB,wCAAwC;IACxC,MAAM,WAAW;IACjB,4CAA4C;IAC5C,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3E,iCAAiC;IACjC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAuHD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AA8CtC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAKzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAoF7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAGxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAyBjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB;;;;;EAuEhC"}

package/lib/utils/deviceDetection.js

@@ -0,0 +1,337 @@
+//#region src/utils/deviceDetection.ts
+/**
+* Device Detection Utility
+*
+* Provides robust mobile device detection combining:
+* - User-agent string analysis
+* - Screen size detection
+* - Touch capability detection
+*
+* This ensures mobile controls are shown on all mobile devices,
+* including high-resolution phones that exceed typical mobile breakpoints.
+*
+* @module utils/deviceDetection
+* @category Mobile
+* @korean 기기감지유틸리티
+*/
+/**
+* Device type classification
+*/
+var DeviceType = /* @__PURE__ */ function(DeviceType) {
+	/** Desktop computer or laptop */
+	DeviceType["DESKTOP"] = "desktop";
+	/** Mobile phone (iOS, Android, etc.) */
+	DeviceType["MOBILE"] = "mobile";
+	/** Tablet device (iPad, Android tablets) */
+	DeviceType["TABLET"] = "tablet";
+	return DeviceType;
+}({});
+/**
+* Detect if user-agent indicates a mobile device
+* Checks for common mobile device identifiers in user-agent string
+*
+* @param userAgent - Browser user-agent string
+* @returns True if user-agent indicates mobile device
+*/
+function isMobileUserAgent(userAgent) {
+	return [
+		"Android",
+		"webOS",
+		"iPhone",
+		"iPod",
+		"BlackBerry",
+		"IEMobile",
+		"Opera Mini",
+		"Mobile",
+		"mobile"
+	].some((keyword) => userAgent.includes(keyword));
+}
+/**
+* Detect if user-agent indicates a tablet device
+*
+* @param userAgent - Browser user-agent string
+* @returns True if user-agent indicates tablet
+*/
+function isTabletUserAgent(userAgent) {
+	if (userAgent.includes("iPad")) return true;
+	if (userAgent.includes("Android")) return userAgent.includes("Tablet") || !userAgent.includes("Mobile");
+	return false;
+}
+/**
+* Detect operating system from user-agent
+*
+* @param userAgent - Browser user-agent string
+* @returns Operating system identifier
+*/
+function detectOS(userAgent) {
+	if (userAgent.includes("iPhone") || userAgent.includes("iPad") || userAgent.includes("iPod")) return "ios";
+	if (userAgent.includes("Android")) return "android";
+	if (userAgent.includes("Windows")) return "windows";
+	if (userAgent.includes("Mac")) {
+		if (typeof navigator !== "undefined" && typeof navigator.maxTouchPoints === "number" && navigator.maxTouchPoints > 1 && userAgent.includes("Macintosh")) return "ios";
+		return "macos";
+	}
+	if (userAgent.includes("Linux")) return "linux";
+	return "unknown";
+}
+/**
+* Detect if device has touch capability
+* Uses multiple methods for reliability
+*
+* @returns True if touch is supported
+*/
+function hasTouchSupport() {
+	if ("ontouchstart" in window) return true;
+	if (typeof navigator !== "undefined" && typeof navigator.maxTouchPoints !== "undefined" && navigator.maxTouchPoints > 0) return true;
+	if (typeof window !== "undefined" && window.matchMedia && window.matchMedia("(pointer: coarse)").matches) return true;
+	return false;
+}
+/**
+* Mobile screen size breakpoint
+* Devices with width <= this value are considered mobile by size
+*/
+var MOBILE_BREAKPOINT = 768;
+/**
+* Tablet screen size breakpoint
+* Devices with width > MOBILE_BREAKPOINT and <= TABLET_BREAKPOINT are tablets
+*/
+var TABLET_BREAKPOINT = 1024;
+/**
+* Cached CSS environment variable insets
+*/
+var cachedCSSEnvInsets = null;
+/**
+* Read CSS environment variables for safe area insets
+* Results are cached as they don't change during a session
+*/
+function readCSSEnvInsets() {
+	if (cachedCSSEnvInsets !== null) return cachedCSSEnvInsets;
+	if (typeof window !== "undefined" && typeof getComputedStyle === "function") try {
+		const root = document.documentElement;
+		const style = getComputedStyle(root);
+		const topEnv = style.getPropertyValue("env(safe-area-inset-top)");
+		const bottomEnv = style.getPropertyValue("env(safe-area-inset-bottom)");
+		if (topEnv || bottomEnv) {
+			const result = {
+				top: parseInt(topEnv || "0", 10) || 0,
+				bottom: parseInt(bottomEnv || "0", 10) || 0
+			};
+			cachedCSSEnvInsets = result;
+			return result;
+		}
+	} catch {}
+	return null;
+}
+/**
+* Cached platform information to avoid re-parsing user-agent on every call
+*/
+var cachedPlatform = null;
+var cachedScreenWidth = 0;
+var cachedScreenHeight = 0;
+/**
+* Clear the cached platform information
+* Useful when window is resized or device emulation changes
+* Also clears CSS environment variable cache
+*
+* @public
+*/
+function clearPlatformCache() {
+	cachedPlatform = null;
+	cachedScreenWidth = 0;
+	cachedScreenHeight = 0;
+	cachedCSSEnvInsets = null;
+}
+/**
+* Detect device type and platform information
+*
+* Combines multiple detection methods for reliability:
+* 1. User-agent string analysis (most reliable for device type)
+* 2. Screen dimensions
+* 3. Touch capability
+*
+* This ensures mobile controls are shown on:
+* - Standard mobile phones (< 768px width)
+* - High-resolution phones (>= 768px width but mobile user-agent)
+* - Android 15/16 devices with 2K/4K resolutions (1200px+, 1440px+)
+* - Tablets (user preference via touch support)
+*
+* **User-agent detection takes priority over screen size**, ensuring that
+* high-end Android phones with desktop-class resolutions (e.g., Galaxy S23 Ultra,
+* Pixel 9 Pro) are correctly identified as mobile devices.
+*
+* Results are cached to avoid re-parsing user-agent on every call.
+* Cache is invalidated when screen dimensions change.
+*
+* @returns Complete platform information
+*
+* @example
+* ```typescript
+* const platform = detectPlatform();
+*
+* if (platform.isMobile) {
+*   // Show mobile controls even on 4K Android phones
+*   return <MobileControls />;
+* }
+* ```
+*
+* @public
+* @korean 플랫폼감지
+*/
+function detectPlatform() {
+	const userAgent = typeof navigator !== "undefined" ? navigator.userAgent : "";
+	const screenWidth = typeof window !== "undefined" ? window.innerWidth : 1920;
+	const screenHeight = typeof window !== "undefined" ? window.innerHeight : 1080;
+	if (cachedPlatform !== null && cachedScreenWidth === screenWidth && cachedScreenHeight === screenHeight) return cachedPlatform;
+	const os = detectOS(userAgent);
+	const hasTouch = hasTouchSupport();
+	const isMobileUA = isMobileUserAgent(userAgent);
+	const isTabletUA = isTabletUserAgent(userAgent);
+	const isMobileBySize = screenWidth <= 768;
+	const isTabletBySize = screenWidth > 768 && screenWidth <= 1024;
+	let deviceType;
+	let isMobile;
+	let isTablet;
+	if (isMobileUA && !isTabletUA) {
+		deviceType = DeviceType.MOBILE;
+		isMobile = true;
+		isTablet = false;
+	} else if (isTabletUA) {
+		deviceType = DeviceType.TABLET;
+		isMobile = false;
+		isTablet = true;
+	} else if (isMobileBySize) {
+		deviceType = DeviceType.MOBILE;
+		isMobile = true;
+		isTablet = false;
+	} else if (isTabletBySize && hasTouch) {
+		deviceType = DeviceType.TABLET;
+		isMobile = false;
+		isTablet = true;
+	} else {
+		deviceType = DeviceType.DESKTOP;
+		isMobile = false;
+		isTablet = false;
+	}
+	const isDesktop = deviceType === DeviceType.DESKTOP;
+	const result = {
+		os,
+		deviceType,
+		hasTouch,
+		isMobile,
+		isTablet,
+		isDesktop,
+		screenWidth,
+		screenHeight
+	};
+	cachedPlatform = result;
+	cachedScreenWidth = screenWidth;
+	cachedScreenHeight = screenHeight;
+	return result;
+}
+/**
+* Simple mobile check for backward compatibility
+* Returns true for both mobile phones and tablets
+*
+* @returns True if device is mobile or tablet
+*
+* @public
+* @korean 모바일확인
+*/
+function isMobileDevice() {
+	const platform = detectPlatform();
+	return platform.isMobile || platform.isTablet;
+}
+/**
+* Check if device should use mobile controls
+* Takes into account device type, screen size, and touch capability
+*
+* Uses user-agent detection to correctly identify mobile devices regardless
+* of screen resolution. This ensures high-end Android 15/16 phones with
+* 2K/4K displays (1200px+, 1440px+) show mobile controls.
+*
+* Also ensures tablets and touch-enabled devices always show mobile controls
+* regardless of resolution, for better UX on touch devices.
+*
+* @returns True if mobile controls should be shown
+*
+* @example
+* ```typescript
+* // High-res Android phone (1440x3168) → returns true via user-agent
+* // Desktop with 1440px screen → returns false (no mobile user-agent)
+* // iPad Pro 12.9" (1024x1366) → returns true (tablet user-agent)
+* // Surface Pro in tablet mode → returns true (touch + tablet size)
+* if (shouldUseMobileControls()) {
+*   return <VirtualDPad />; // Touch-optimized controls
+* }
+* ```
+*
+* @public
+* @korean 모바일컨트롤사용
+*/
+function shouldUseMobileControls() {
+	const platform = detectPlatform();
+	if (platform.isMobile) return true;
+	if (platform.isTablet) return true;
+	if (platform.hasTouch && platform.screenWidth <= 1024) return true;
+	if (platform.screenWidth <= 768 && platform.hasTouch) return true;
+	return false;
+}
+/**
+* Get safe area insets for device
+* Returns appropriate values based on device type and OS
+*
+* For iOS devices, attempts to detect if device has a notch by checking
+* screen dimensions. Falls back to CSS environment variables if available.
+*
+* @returns Safe area insets in pixels
+*
+* @public
+* @korean 안전영역인셋
+*/
+function getSafeAreaInsets() {
+	const platform = detectPlatform();
+	if (platform.os === "ios" && platform.isMobile) {
+		const cssEnvInsets = readCSSEnvInsets();
+		if (cssEnvInsets) return {
+			top: cssEnvInsets.top,
+			bottom: cssEnvInsets.bottom,
+			left: 0,
+			right: 0
+		};
+		const isLandscape = platform.screenWidth > platform.screenHeight;
+		if (platform.screenHeight >= 812 || platform.screenWidth >= 812) if (isLandscape) return {
+			top: 0,
+			bottom: 21,
+			left: 44,
+			right: 44
+		};
+		else return {
+			top: 44,
+			bottom: 34,
+			left: 0,
+			right: 0
+		};
+		else return {
+			top: 20,
+			bottom: 0,
+			left: 0,
+			right: 0
+		};
+	}
+	if (platform.os === "android" && platform.isMobile) return {
+		top: 24,
+		bottom: 0,
+		left: 0,
+		right: 0
+	};
+	return {
+		top: 0,
+		bottom: 0,
+		left: 0,
+		right: 0
+	};
+}
+//#endregion
+export { DeviceType, MOBILE_BREAKPOINT, TABLET_BREAKPOINT, clearPlatformCache, detectPlatform, getSafeAreaInsets, isMobileDevice, shouldUseMobileControls };
+
+//# sourceMappingURL=deviceDetection.js.map

package/lib/utils/deviceDetection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviceDetection.js","names":[],"sources":["../../src/utils/deviceDetection.ts"],"sourcesContent":["/**\n * Device Detection Utility\n *\n * Provides robust mobile device detection combining:\n * - User-agent string analysis\n * - Screen size detection\n * - Touch capability detection\n *\n * This ensures mobile controls are shown on all mobile devices,\n * including high-resolution phones that exceed typical mobile breakpoints.\n *\n * @module utils/deviceDetection\n * @category Mobile\n * @korean 기기감지유틸리티\n */\n\n/**\n * Device type classification\n */\nexport enum DeviceType {\n  /** Desktop computer or laptop */\n  DESKTOP = \"desktop\",\n  /** Mobile phone (iOS, Android, etc.) */\n  MOBILE = \"mobile\",\n  /** Tablet device (iPad, Android tablets) */\n  TABLET = \"tablet\",\n}\n\n/**\n * Platform detection results\n */\nexport interface PlatformInfo {\n  /** Operating system type */\n  readonly os: \"ios\" | \"android\" | \"windows\" | \"macos\" | \"linux\" | \"unknown\";\n  /** Device type classification */\n  readonly deviceType: DeviceType;\n  /** Whether device has touch capability */\n  readonly hasTouch: boolean;\n  /** Whether device is mobile phone */\n  readonly isMobile: boolean;\n  /** Whether device is tablet */\n  readonly isTablet: boolean;\n  /** Whether device is desktop */\n  readonly isDesktop: boolean;\n  /** Screen width in pixels */\n  readonly screenWidth: number;\n  /** Screen height in pixels */\n  readonly screenHeight: number;\n}\n\n/**\n * Detect if user-agent indicates a mobile device\n * Checks for common mobile device identifiers in user-agent string\n *\n * @param userAgent - Browser user-agent string\n * @returns True if user-agent indicates mobile device\n */\nfunction isMobileUserAgent(userAgent: string): boolean {\n  const mobileKeywords = [\n    \"Android\",\n    \"webOS\",\n    \"iPhone\",\n    // 'iPad' is handled separately in isTabletUserAgent\n    \"iPod\",\n    \"BlackBerry\",\n    \"IEMobile\",\n    \"Opera Mini\",\n    \"Mobile\",\n    \"mobile\",\n  ];\n\n  return mobileKeywords.some((keyword) => userAgent.includes(keyword));\n}\n\n/**\n * Detect if user-agent indicates a tablet device\n *\n * @param userAgent - Browser user-agent string\n * @returns True if user-agent indicates tablet\n */\nfunction isTabletUserAgent(userAgent: string): boolean {\n  // iPad is always a tablet\n  if (userAgent.includes(\"iPad\")) {\n    return true;\n  }\n\n  // Android tablets typically include \"Tablet\" or have Mobile absent\n  if (userAgent.includes(\"Android\")) {\n    return userAgent.includes(\"Tablet\") || !userAgent.includes(\"Mobile\");\n  }\n\n  return false;\n}\n\n/**\n * Detect operating system from user-agent\n *\n * @param userAgent - Browser user-agent string\n * @returns Operating system identifier\n */\nfunction detectOS(userAgent: string): PlatformInfo[\"os\"] {\n  if (\n    userAgent.includes(\"iPhone\") ||\n    userAgent.includes(\"iPad\") ||\n    userAgent.includes(\"iPod\")\n  ) {\n    return \"ios\";\n  }\n  if (userAgent.includes(\"Android\")) {\n    return \"android\";\n  }\n  if (userAgent.includes(\"Windows\")) {\n    return \"windows\";\n  }\n  if (userAgent.includes(\"Mac\")) {\n    // Handle iPadOS 13+ in desktop mode, which reports a Mac-like user agent\n    // e.g. \"Macintosh; Intel Mac OS X\" but still has touch support\n    const isLikelyIPadOSDesktop =\n      typeof navigator !== \"undefined\" &&\n      typeof navigator.maxTouchPoints === \"number\" &&\n      navigator.maxTouchPoints > 1 &&\n      userAgent.includes(\"Macintosh\");\n\n    if (isLikelyIPadOSDesktop) {\n      return \"ios\";\n    }\n    return \"macos\";\n  }\n  if (userAgent.includes(\"Linux\")) {\n    return \"linux\";\n  }\n  return \"unknown\";\n}\n\n/**\n * Detect if device has touch capability\n * Uses multiple methods for reliability\n *\n * @returns True if touch is supported\n */\nfunction hasTouchSupport(): boolean {\n  // Check for touch events support\n  if (\"ontouchstart\" in window) {\n    return true;\n  }\n\n  // Check for touch points (must be defined and > 0)\n  if (\n    typeof navigator !== \"undefined\" &&\n    typeof navigator.maxTouchPoints !== \"undefined\" &&\n    navigator.maxTouchPoints > 0\n  ) {\n    return true;\n  }\n\n  // Check for pointer events with touch\n  if (\n    typeof window !== \"undefined\" &&\n    window.matchMedia &&\n    window.matchMedia(\"(pointer: coarse)\").matches\n  ) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Mobile screen size breakpoint\n * Devices with width <= this value are considered mobile by size\n */\nexport const MOBILE_BREAKPOINT = 768;\n\n/**\n * Tablet screen size breakpoint\n * Devices with width > MOBILE_BREAKPOINT and <= TABLET_BREAKPOINT are tablets\n */\nexport const TABLET_BREAKPOINT = 1024;\n\n/**\n * Cached CSS environment variable insets\n */\nlet cachedCSSEnvInsets: { top: number; bottom: number } | null = null;\n\n/**\n * Read CSS environment variables for safe area insets\n * Results are cached as they don't change during a session\n */\nfunction readCSSEnvInsets(): { top: number; bottom: number } | null {\n  if (cachedCSSEnvInsets !== null) {\n    return cachedCSSEnvInsets;\n  }\n\n  if (typeof window !== \"undefined\" && typeof getComputedStyle === \"function\") {\n    try {\n      const root = document.documentElement;\n      const style = getComputedStyle(root);\n      const topEnv = style.getPropertyValue(\"env(safe-area-inset-top)\");\n      const bottomEnv = style.getPropertyValue(\"env(safe-area-inset-bottom)\");\n\n      if (topEnv || bottomEnv) {\n        const result = {\n          top: parseInt(topEnv || \"0\", 10) || 0,\n          bottom: parseInt(bottomEnv || \"0\", 10) || 0,\n        };\n        cachedCSSEnvInsets = result;\n        return result;\n      }\n    } catch {\n      // Fall through to null\n    }\n  }\n\n  return null;\n}\n\n/**\n * Cached platform information to avoid re-parsing user-agent on every call\n */\nlet cachedPlatform: PlatformInfo | null = null;\nlet cachedScreenWidth = 0;\nlet cachedScreenHeight = 0;\n\n/**\n * Clear the cached platform information\n * Useful when window is resized or device emulation changes\n * Also clears CSS environment variable cache\n *\n * @public\n */\nexport function clearPlatformCache(): void {\n  cachedPlatform = null;\n  cachedScreenWidth = 0;\n  cachedScreenHeight = 0;\n  cachedCSSEnvInsets = null;\n}\n\n/**\n * Detect device type and platform information\n *\n * Combines multiple detection methods for reliability:\n * 1. User-agent string analysis (most reliable for device type)\n * 2. Screen dimensions\n * 3. Touch capability\n *\n * This ensures mobile controls are shown on:\n * - Standard mobile phones (< 768px width)\n * - High-resolution phones (>= 768px width but mobile user-agent)\n * - Android 15/16 devices with 2K/4K resolutions (1200px+, 1440px+)\n * - Tablets (user preference via touch support)\n *\n * **User-agent detection takes priority over screen size**, ensuring that\n * high-end Android phones with desktop-class resolutions (e.g., Galaxy S23 Ultra,\n * Pixel 9 Pro) are correctly identified as mobile devices.\n *\n * Results are cached to avoid re-parsing user-agent on every call.\n * Cache is invalidated when screen dimensions change.\n *\n * @returns Complete platform information\n *\n * @example\n * ```typescript\n * const platform = detectPlatform();\n *\n * if (platform.isMobile) {\n *   // Show mobile controls even on 4K Android phones\n *   return <MobileControls />;\n * }\n * ```\n *\n * @public\n * @korean 플랫폼감지\n */\nexport function detectPlatform(): PlatformInfo {\n  const userAgent = typeof navigator !== \"undefined\" ? navigator.userAgent : \"\";\n  const screenWidth = typeof window !== \"undefined\" ? window.innerWidth : 1920;\n  const screenHeight =\n    typeof window !== \"undefined\" ? window.innerHeight : 1080;\n\n  // Return cached result if screen dimensions haven't changed\n  if (\n    cachedPlatform !== null &&\n    cachedScreenWidth === screenWidth &&\n    cachedScreenHeight === screenHeight\n  ) {\n    return cachedPlatform;\n  }\n\n  // Detect OS\n  const os = detectOS(userAgent);\n\n  // Detect touch capability\n  const hasTouch = hasTouchSupport();\n\n  // Detect if mobile by user-agent (most reliable method)\n  const isMobileUA = isMobileUserAgent(userAgent);\n\n  // Detect if tablet by user-agent\n  const isTabletUA = isTabletUserAgent(userAgent);\n\n  // Detect by screen size (fallback method)\n  const isMobileBySize = screenWidth <= MOBILE_BREAKPOINT;\n  const isTabletBySize =\n    screenWidth > MOBILE_BREAKPOINT && screenWidth <= TABLET_BREAKPOINT;\n\n  // Determine device type\n  // Priority: User-agent > Screen size\n  let deviceType: DeviceType;\n  let isMobile: boolean;\n  let isTablet: boolean;\n\n  if (isMobileUA && !isTabletUA) {\n    // User-agent indicates phone\n    deviceType = DeviceType.MOBILE;\n    isMobile = true;\n    isTablet = false;\n  } else if (isTabletUA) {\n    // User-agent indicates tablet\n    deviceType = DeviceType.TABLET;\n    isMobile = false;\n    isTablet = true;\n  } else if (isMobileBySize) {\n    // Small screen, assume mobile\n    deviceType = DeviceType.MOBILE;\n    isMobile = true;\n    isTablet = false;\n  } else if (isTabletBySize && hasTouch) {\n    // Medium screen with touch, assume tablet\n    deviceType = DeviceType.TABLET;\n    isMobile = false;\n    isTablet = true;\n  } else {\n    // Desktop\n    deviceType = DeviceType.DESKTOP;\n    isMobile = false;\n    isTablet = false;\n  }\n\n  const isDesktop = deviceType === DeviceType.DESKTOP;\n\n  const result: PlatformInfo = {\n    os,\n    deviceType,\n    hasTouch,\n    isMobile,\n    isTablet,\n    isDesktop,\n    screenWidth,\n    screenHeight,\n  };\n\n  // Cache the result along with screen dimensions\n  cachedPlatform = result;\n  cachedScreenWidth = screenWidth;\n  cachedScreenHeight = screenHeight;\n\n  return result;\n}\n\n/**\n * Simple mobile check for backward compatibility\n * Returns true for both mobile phones and tablets\n *\n * @returns True if device is mobile or tablet\n *\n * @public\n * @korean 모바일확인\n */\nexport function isMobileDevice(): boolean {\n  const platform = detectPlatform();\n  return platform.isMobile || platform.isTablet;\n}\n\n/**\n * Check if device should use mobile controls\n * Takes into account device type, screen size, and touch capability\n *\n * Uses user-agent detection to correctly identify mobile devices regardless\n * of screen resolution. This ensures high-end Android 15/16 phones with\n * 2K/4K displays (1200px+, 1440px+) show mobile controls.\n *\n * Also ensures tablets and touch-enabled devices always show mobile controls\n * regardless of resolution, for better UX on touch devices.\n *\n * @returns True if mobile controls should be shown\n *\n * @example\n * ```typescript\n * // High-res Android phone (1440x3168) → returns true via user-agent\n * // Desktop with 1440px screen → returns false (no mobile user-agent)\n * // iPad Pro 12.9\" (1024x1366) → returns true (tablet user-agent)\n * // Surface Pro in tablet mode → returns true (touch + tablet size)\n * if (shouldUseMobileControls()) {\n *   return <VirtualDPad />; // Touch-optimized controls\n * }\n * ```\n *\n * @public\n * @korean 모바일컨트롤사용\n */\nexport function shouldUseMobileControls(): boolean {\n  const platform = detectPlatform();\n\n  // Always use mobile controls on phones\n  if (platform.isMobile) {\n    return true;\n  }\n\n  // Use mobile controls on tablets (better touch experience)\n  if (platform.isTablet) {\n    return true;\n  }\n\n  // Use mobile controls on any touch-enabled device up to tablet breakpoint\n  // This catches Windows tablets, Chromebooks in tablet mode, etc.\n  if (platform.hasTouch && platform.screenWidth <= TABLET_BREAKPOINT) {\n    return true;\n  }\n\n  // Use mobile controls on small desktop screens with touch\n  if (platform.screenWidth <= MOBILE_BREAKPOINT && platform.hasTouch) {\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Get safe area insets for device\n * Returns appropriate values based on device type and OS\n *\n * For iOS devices, attempts to detect if device has a notch by checking\n * screen dimensions. Falls back to CSS environment variables if available.\n *\n * @returns Safe area insets in pixels\n *\n * @public\n * @korean 안전영역인셋\n */\nexport function getSafeAreaInsets() {\n  const platform = detectPlatform();\n\n  // iOS devices - distinguish between notched and non-notched\n  if (platform.os === \"ios\" && platform.isMobile) {\n    // Try to read CSS environment variables first (most accurate)\n    const cssEnvInsets = readCSSEnvInsets();\n    if (cssEnvInsets) {\n      return {\n        top: cssEnvInsets.top,\n        bottom: cssEnvInsets.bottom,\n        left: 0,\n        right: 0,\n      };\n    }\n\n    // Detect orientation\n    const isLandscape = platform.screenWidth > platform.screenHeight;\n\n    // Heuristic: iPhone X and later have notches and specific screen dimensions\n    // iPhone X/XS/11 Pro: 375x812, iPhone XR/11: 414x896, iPhone 12/13/14: 390x844, etc.\n    // Only devices with height >= 812 (portrait) or width >= 812 (landscape) have notches\n    const hasNotch =\n      platform.screenHeight >= 812 || platform.screenWidth >= 812;\n\n    if (hasNotch) {\n      if (isLandscape) {\n        // In landscape, notch is on the side\n        return {\n          top: 0,\n          bottom: 21, // Home indicator\n          left: 44, // Notch side\n          right: 44, // Opposite side for symmetry\n        };\n      } else {\n        // In portrait, notch is at top\n        return {\n          top: 44,\n          bottom: 34,\n          left: 0,\n          right: 0,\n        };\n      }\n    } else {\n      // Older iPhones without notch (iPhone 8, SE, etc.)\n      return {\n        top: 20, // Status bar height\n        bottom: 0,\n        left: 0,\n        right: 0,\n      };\n    }\n  }\n\n  // Android devices (standard status bar)\n  if (platform.os === \"android\" && platform.isMobile) {\n    return {\n      top: 24,\n      bottom: 0,\n      left: 0,\n      right: 0,\n    };\n  }\n\n  // Tablets and desktop - no safe area needed\n  return {\n    top: 0,\n    bottom: 0,\n    left: 0,\n    right: 0,\n  };\n}\n"],"mappings":"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"}

package/lib/utils/effectUtils.d.ts

@@ -0,0 +1,63 @@
+import { HitEffect, StatusEffect } from "../systems";
+import { EffectIntensity, EffectType, HitEffectType } from "../systems/effects";
+import type { KoreanText, Position } from "../types";
+/**
+ * Create a hit effect for visual feedback
+ */
+export declare function createHitEffect(id: string, type: HitEffectType, position: Position, intensity: number, duration?: number): HitEffect;
+/**
+ * Get hit effect color based on type
+ */
+export declare function getHitEffectColor(type: HitEffectType): number;
+/**
+ * Create a status effect
+ */
+export declare function createStatusEffect(id: string, type: EffectType, intensity: EffectIntensity, duration: number, description: KoreanText, source?: string): StatusEffect;
+/**
+ * Calculate effect intensity based on damage
+ */
+export declare function calculateEffectIntensity(damage: number): EffectIntensity;
+/**
+ * Get effect duration modifier based on type
+ */
+export declare function getEffectDurationModifier(type: EffectType): number;
+/**
+ * Apply effect to player stats
+ */
+export declare function applyEffectModifiers(baseValue: number, effects: readonly StatusEffect[], statType: "attack" | "defense" | "speed"): number;
+/**
+ * Check if effect is beneficial or harmful
+ */
+export declare function isEffectBeneficial(type: EffectType): boolean;
+/**
+ * Get effect description based on type and intensity
+ */
+export declare function getEffectDescription(type: EffectType, intensity: EffectIntensity): KoreanText;
+/**
+ * Update effect over time
+ */
+export declare function updateEffect(effect: StatusEffect, currentTime: number): StatusEffect | null;
+/**
+ * Combine multiple effects of same type
+ */
+export declare function combineEffects(effects: StatusEffect[]): StatusEffect[];
+/**
+ * Remove expired effects
+ */
+export declare function removeExpiredEffects(effects: StatusEffect[]): StatusEffect[];
+/**
+ * Create effect from Korean text
+ */
+export declare function createEffectFromKoreanText(koreanText: string, englishText: string, duration?: number): StatusEffect;
+/**
+ * Get effect display text
+ */
+export declare function getEffectDisplayText(effect: StatusEffect, preferKorean?: boolean): string;
+export declare function createKoreanStatusEffect(koreanName: string, englishName: string, intensity?: EffectIntensity, duration?: number): StatusEffect;
+export declare function createTrigramEffect(stanceName: string, effectType: EffectType, duration?: number): StatusEffect;
+export declare function groupEffectsByTypeEnum(effects: StatusEffect[]): Map<EffectType, StatusEffect[]>;
+/**
+ * Group effects by type using string keys (works with StatusEffect.type)
+ */
+export declare function groupEffectsByType(effects: StatusEffect[]): Map<string, StatusEffect[]>;
+//# sourceMappingURL=effectUtils.d.ts.map

package/lib/utils/effectUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectUtils.d.ts","sourceRoot":"","sources":["../../src/utils/effectUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAErD;;GAEG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAa,GACtB,SAAS,CAeX;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAa7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,UAAU,EACvB,MAAM,GAAE,MAAkB,GACzB,YAAY,CAad;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAQxE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAalE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,GACvC,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAQ5D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,eAAe,GACzB,UAAU,CAuKZ;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,MAAM,GAClB,YAAY,GAAG,IAAI,CAMrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAmCtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAG5E;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,MAAa,GACtB,YAAY,CAYd;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,YAAY,GAAE,OAAc,GAC3B,MAAM,CAER;AAGD,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,eAA6C,EACxD,QAAQ,GAAE,MAAa,GACtB,YAAY,CAQd;AAED,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,UAAU,EACtB,QAAQ,GAAE,MAAa,GACtB,YAAY,CAWd;AAGD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,EAAE,GACtB,GAAG,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAgBjC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EAAE,GACtB,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAe7B"}