blacktrigram 0.7.2

package/lib/utils/htmlOverlayHelpers.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Html Overlay Positioning Helpers for Three.js
+ *
+ * Provides utilities for positioning Html overlays from @react-three/drei
+ * with bounds checking, z-index management, and Korean text measurement.
+ *
+ * Fixes:
+ * - Z-fighting between Html overlays and 3D elements
+ * - Text clipping at screen edges
+ * - Inconsistent overlay positioning
+ * - Performance issues with many overlays
+ *
+ * @module utils/htmlOverlayHelpers
+ * @category Utilities
+ * @korean HTML오버레이헬퍼
+ */
+import { type ZIndexValue } from "../types/LayoutTypes";
+import type { HtmlOverlayLayer, ScreenBounds, ElementBounds, SafePosition, HtmlOverlayStyle, TextMeasurement, HtmlOverlayPositionOptions, HtmlOverlayConfig } from "../types/HtmlOverlayTypes";
+/**
+ * Get z-index value for Html overlay layer
+ *
+ * Maps layer names to Z_INDEX constants for consistent stacking order.
+ * Prevents z-fighting by maintaining clear hierarchy.
+ *
+ * @param layer - Html overlay layer category
+ * @param offset - Optional offset to add to base z-index (default: 0)
+ * @returns Z-index value for the layer
+ *
+ * @example
+ * ```typescript
+ * const zIndex = getZIndexForLayer('hud'); // Returns 40
+ * const zIndexWithOffset = getZIndexForLayer('hud', 5); // Returns 45
+ * ```
+ *
+ * @category Html Overlay Helpers
+ * @korean Z인덱스가져오기
+ */
+export declare function getZIndexForLayer(layer: HtmlOverlayLayer, offset?: number): ZIndexValue;
+/**
+ * Calculate safe position that prevents clipping at screen edges
+ *
+ * Takes a desired position and element bounds, then ensures the element
+ * stays within screen bounds by clamping to safe area.
+ *
+ * @param position - Desired 3D position [x, y, z]
+ * @param elementBounds - Size of the element
+ * @param screenBounds - Screen size and safe area insets
+ * @returns Safe position with clipping prevention
+ *
+ * @example
+ * ```typescript
+ * const safePos = calculateSafePosition(
+ *   [100, 50, 0],
+ *   { width: 200, height: 100, margin: 10 },
+ *   { width: 1920, height: 1080 }
+ * );
+ * // Returns: { x: 100, y: 50, wasClamped: false }
+ * ```
+ *
+ * @category Html Overlay Helpers
+ * @korean 안전위치계산
+ */
+export declare function calculateSafePosition(position: [number, number, number], elementBounds: ElementBounds, screenBounds: ScreenBounds): SafePosition;
+/**
+ * Measure Korean and English text dimensions
+ *
+ * Uses canvas-based text measurement to calculate accurate bounds
+ * for bilingual text before rendering. Prevents text overflow.
+ *
+ * @param korean - Korean text content
+ * @param english - English text content
+ * @param fontSize - Font size in pixels
+ * @param fontFamily - Font family to use (default: FONT_FAMILY.KOREAN)
+ * @param layout - Text layout direction ('vertical' | 'horizontal')
+ * @returns Text measurement with width and height
+ *
+ * @example
+ * ```typescript
+ * const bounds = measureTextBounds('공격', 'Attack', 16, FONT_FAMILY.KOREAN, 'vertical');
+ * // Returns: { width: 48, height: 42, koreanWidth: 32, englishWidth: 48 }
+ * ```
+ *
+ * @category Html Overlay Helpers
+ * @korean 텍스트경계측정
+ */
+export declare function measureTextBounds(korean: string, english: string, fontSize: number, fontFamily?: string, layout?: "vertical" | "horizontal"): TextMeasurement;
+/**
+ * Apply standardized Html overlay styles
+ *
+ * Creates consistent styling for Html overlays with proper z-index,
+ * pointer events, and performance optimizations.
+ *
+ * @param layer - Html overlay layer for z-index
+ * @param interactive - Whether the overlay should receive pointer events
+ * @param distanceFactor - Distance scaling factor (default: 10)
+ * @param center - Whether to center the overlay (default: true)
+ * @param occlude - Whether to occlude behind 3D objects (default: false)
+ * @param zIndexOffset - Optional z-index offset (default: 0)
+ * @returns Html overlay style configuration
+ *
+ * @example
+ * ```typescript
+ * const style = applyHtmlOverlayStyles('hud', false, 10, true);
+ * // Returns: { zIndex: 40, pointerEvents: 'none', distanceFactor: 10, center: true, ... }
+ * ```
+ *
+ * @category Html Overlay Helpers
+ * @korean 오버레이스타일적용
+ */
+export declare function applyHtmlOverlayStyles(layer: HtmlOverlayLayer, interactive?: boolean, distanceFactor?: number, center?: boolean, occlude?: boolean, zIndexOffset?: number): HtmlOverlayStyle;
+/**
+ * Create complete Html overlay configuration
+ *
+ * Combines position calculation, bounds checking, and styling
+ * into a single configuration object for Html overlays.
+ *
+ * @param options - Html overlay positioning options
+ * @returns Complete Html overlay configuration
+ *
+ * @example
+ * ```typescript
+ * const config = createHtmlOverlayConfig({
+ *   position: [0, 2, 0],
+ *   layer: 'hud',
+ *   screenBounds: { width: 1920, height: 1080 },
+ *   elementBounds: { width: 200, height: 100 },
+ *   isMobile: false,
+ * });
+ * ```
+ *
+ * @category Html Overlay Helpers
+ * @korean 오버레이설정생성
+ */
+export declare function createHtmlOverlayConfig(options: HtmlOverlayPositionOptions): HtmlOverlayConfig;
+/**
+ * Get default safe area insets for mobile devices
+ *
+ * Provides standard safe area values for devices with notches
+ * and home indicators (iPhone X+, modern Android).
+ *
+ * @param isMobile - Whether device is mobile
+ * @returns Safe area insets
+ *
+ * @category Html Overlay Helpers
+ * @korean 기본안전영역
+ */
+export declare function getDefaultSafeArea(isMobile: boolean): {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+};
+/**
+ * Calculate optimal distance factor for Html overlay
+ *
+ * Determines appropriate distance scaling based on screen size
+ * and overlay purpose. Prevents overlays from being too small or large.
+ *
+ * @param screenWidth - Screen width in pixels
+ * @param overlayType - Type of overlay ('text' | 'button' | 'panel')
+ * @param isMobile - Whether on mobile device
+ * @returns Optimal distance factor
+ *
+ * @category Html Overlay Helpers
+ * @korean 거리인수계산
+ */
+export declare function calculateDistanceFactor(screenWidth: number, overlayType: "text" | "button" | "panel", isMobile: boolean): number;
+//# sourceMappingURL=htmlOverlayHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"htmlOverlayHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/htmlOverlayHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAC1B,iBAAiB,EAClB,MAAM,2BAA2B,CAAC;AAGnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,gBAAgB,EACvB,MAAM,GAAE,MAAU,GACjB,WAAW,CA2Bb;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAClC,aAAa,EAAE,aAAa,EAC5B,YAAY,EAAE,YAAY,GACzB,YAAY,CA8Bd;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,MAA2B,EACvC,MAAM,GAAE,UAAU,GAAG,YAAyB,GAC7C,eAAe,CA8CjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,gBAAgB,EACvB,WAAW,GAAE,OAAe,EAC5B,cAAc,GAAE,MAAW,EAC3B,MAAM,GAAE,OAAc,EACtB,OAAO,GAAE,OAAe,EACxB,YAAY,GAAE,MAAU,GACvB,gBAAgB,CASlB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,0BAA0B,GAClC,iBAAiB,CAsCnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAYA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,EACxC,QAAQ,EAAE,OAAO,GAChB,MAAM,CAqBR"}

package/lib/utils/htmlOverlayHelpers.js

@@ -0,0 +1,279 @@
+import { FONT_FAMILY } from "../types/constants/typography.js";
+import "../types/constants/index.js";
+import { Z_INDEX } from "../types/LayoutTypes.js";
+//#region src/utils/htmlOverlayHelpers.ts
+/**
+* Html Overlay Positioning Helpers for Three.js
+*
+* Provides utilities for positioning Html overlays from @react-three/drei
+* with bounds checking, z-index management, and Korean text measurement.
+*
+* Fixes:
+* - Z-fighting between Html overlays and 3D elements
+* - Text clipping at screen edges
+* - Inconsistent overlay positioning
+* - Performance issues with many overlays
+*
+* @module utils/htmlOverlayHelpers
+* @category Utilities
+* @korean HTML오버레이헬퍼
+*/
+/**
+* Get z-index value for Html overlay layer
+*
+* Maps layer names to Z_INDEX constants for consistent stacking order.
+* Prevents z-fighting by maintaining clear hierarchy.
+*
+* @param layer - Html overlay layer category
+* @param offset - Optional offset to add to base z-index (default: 0)
+* @returns Z-index value for the layer
+*
+* @example
+* ```typescript
+* const zIndex = getZIndexForLayer('hud'); // Returns 40
+* const zIndexWithOffset = getZIndexForLayer('hud', 5); // Returns 45
+* ```
+*
+* @category Html Overlay Helpers
+* @korean Z인덱스가져오기
+*/
+function getZIndexForLayer(layer, offset = 0) {
+	const baseZIndex = {
+		background: Z_INDEX.BACKGROUND,
+		arena: Z_INDEX.ARENA,
+		players: Z_INDEX.PLAYERS,
+		effects: Z_INDEX.EFFECTS,
+		hud: Z_INDEX.HUD,
+		"mobile-controls": Z_INDEX.MOBILE_CONTROLS,
+		modal: Z_INDEX.MODAL,
+		tooltip: Z_INDEX.TOOLTIP,
+		debug: Z_INDEX.DEBUG
+	}[layer];
+	const zIndexValues = Object.values(Z_INDEX).filter((value) => typeof value === "number");
+	const minZIndex = Math.min(...zIndexValues);
+	const maxZIndex = Math.max(...zIndexValues);
+	const rawZIndex = baseZIndex + offset;
+	return Math.max(minZIndex, Math.min(maxZIndex, rawZIndex));
+}
+/**
+* Calculate safe position that prevents clipping at screen edges
+*
+* Takes a desired position and element bounds, then ensures the element
+* stays within screen bounds by clamping to safe area.
+*
+* @param position - Desired 3D position [x, y, z]
+* @param elementBounds - Size of the element
+* @param screenBounds - Screen size and safe area insets
+* @returns Safe position with clipping prevention
+*
+* @example
+* ```typescript
+* const safePos = calculateSafePosition(
+*   [100, 50, 0],
+*   { width: 200, height: 100, margin: 10 },
+*   { width: 1920, height: 1080 }
+* );
+* // Returns: { x: 100, y: 50, wasClamped: false }
+* ```
+*
+* @category Html Overlay Helpers
+* @korean 안전위치계산
+*/
+function calculateSafePosition(position, elementBounds, screenBounds) {
+	const [x, y] = position;
+	const margin = elementBounds.margin ?? 0;
+	const safeArea = screenBounds.safeArea ?? {
+		top: 0,
+		right: 0,
+		bottom: 0,
+		left: 0
+	};
+	const minX = safeArea.left + margin;
+	const maxX = screenBounds.width - safeArea.right - elementBounds.width - margin;
+	const minY = safeArea.top + margin;
+	const maxY = screenBounds.height - safeArea.bottom - elementBounds.height - margin;
+	const safeX = Math.max(minX, Math.min(x, maxX));
+	const safeY = Math.max(minY, Math.min(y, maxY));
+	return {
+		x: safeX,
+		y: safeY,
+		wasClamped: safeX !== x || safeY !== y
+	};
+}
+/**
+* Measure Korean and English text dimensions
+*
+* Uses canvas-based text measurement to calculate accurate bounds
+* for bilingual text before rendering. Prevents text overflow.
+*
+* @param korean - Korean text content
+* @param english - English text content
+* @param fontSize - Font size in pixels
+* @param fontFamily - Font family to use (default: FONT_FAMILY.KOREAN)
+* @param layout - Text layout direction ('vertical' | 'horizontal')
+* @returns Text measurement with width and height
+*
+* @example
+* ```typescript
+* const bounds = measureTextBounds('공격', 'Attack', 16, FONT_FAMILY.KOREAN, 'vertical');
+* // Returns: { width: 48, height: 42, koreanWidth: 32, englishWidth: 48 }
+* ```
+*
+* @category Html Overlay Helpers
+* @korean 텍스트경계측정
+*/
+function measureTextBounds(korean, english, fontSize, fontFamily = FONT_FAMILY.KOREAN, layout = "vertical") {
+	const ctx = document.createElement("canvas").getContext("2d");
+	if (!ctx) return {
+		width: fontSize * Math.max(korean.length, english.length),
+		height: fontSize * 2.4,
+		koreanWidth: fontSize * korean.length,
+		englishWidth: fontSize * english.length
+	};
+	ctx.font = `bold ${fontSize}px ${fontFamily}`;
+	const koreanWidth = ctx.measureText(korean).width;
+	const englishFontSize = fontSize * .75;
+	ctx.font = `italic ${englishFontSize}px ${fontFamily}`;
+	const englishWidth = ctx.measureText(english).width;
+	let totalWidth;
+	let totalHeight;
+	if (layout === "vertical") {
+		totalWidth = Math.max(koreanWidth, englishWidth);
+		totalHeight = fontSize * 1.2 + englishFontSize * 1.2 + 4;
+	} else {
+		totalWidth = koreanWidth + 8 + englishWidth;
+		totalHeight = Math.max(fontSize * 1.2, englishFontSize * 1.2);
+	}
+	return {
+		width: totalWidth,
+		height: totalHeight,
+		koreanWidth,
+		englishWidth
+	};
+}
+/**
+* Apply standardized Html overlay styles
+*
+* Creates consistent styling for Html overlays with proper z-index,
+* pointer events, and performance optimizations.
+*
+* @param layer - Html overlay layer for z-index
+* @param interactive - Whether the overlay should receive pointer events
+* @param distanceFactor - Distance scaling factor (default: 10)
+* @param center - Whether to center the overlay (default: true)
+* @param occlude - Whether to occlude behind 3D objects (default: false)
+* @param zIndexOffset - Optional z-index offset (default: 0)
+* @returns Html overlay style configuration
+*
+* @example
+* ```typescript
+* const style = applyHtmlOverlayStyles('hud', false, 10, true);
+* // Returns: { zIndex: 40, pointerEvents: 'none', distanceFactor: 10, center: true, ... }
+* ```
+*
+* @category Html Overlay Helpers
+* @korean 오버레이스타일적용
+*/
+function applyHtmlOverlayStyles(layer, interactive = false, distanceFactor = 10, center = true, occlude = false, zIndexOffset = 0) {
+	return {
+		zIndex: getZIndexForLayer(layer, zIndexOffset),
+		pointerEvents: interactive ? "all" : "none",
+		distanceFactor,
+		center,
+		occlude,
+		transform: "translateZ(0)"
+	};
+}
+/**
+* Create complete Html overlay configuration
+*
+* Combines position calculation, bounds checking, and styling
+* into a single configuration object for Html overlays.
+*
+* @param options - Html overlay positioning options
+* @returns Complete Html overlay configuration
+*
+* @example
+* ```typescript
+* const config = createHtmlOverlayConfig({
+*   position: [0, 2, 0],
+*   layer: 'hud',
+*   screenBounds: { width: 1920, height: 1080 },
+*   elementBounds: { width: 200, height: 100 },
+*   isMobile: false,
+* });
+* ```
+*
+* @category Html Overlay Helpers
+* @korean 오버레이설정생성
+*/
+function createHtmlOverlayConfig(options) {
+	const { position, layer, screenBounds, elementBounds, isMobile = false, zIndexOffset = 0 } = options;
+	let safePosition;
+	if (screenBounds && elementBounds) safePosition = calculateSafePosition(position, elementBounds, screenBounds);
+	else safePosition = {
+		x: position[0],
+		y: position[1],
+		wasClamped: false
+	};
+	const style = applyHtmlOverlayStyles(layer, false, isMobile ? 15 : 10, true, false, zIndexOffset);
+	return {
+		position: safePosition,
+		style,
+		position3D: position
+	};
+}
+/**
+* Get default safe area insets for mobile devices
+*
+* Provides standard safe area values for devices with notches
+* and home indicators (iPhone X+, modern Android).
+*
+* @param isMobile - Whether device is mobile
+* @returns Safe area insets
+*
+* @category Html Overlay Helpers
+* @korean 기본안전영역
+*/
+function getDefaultSafeArea(isMobile) {
+	if (!isMobile) return {
+		top: 0,
+		right: 0,
+		bottom: 0,
+		left: 0
+	};
+	return {
+		top: 44,
+		right: 0,
+		bottom: 34,
+		left: 0
+	};
+}
+/**
+* Calculate optimal distance factor for Html overlay
+*
+* Determines appropriate distance scaling based on screen size
+* and overlay purpose. Prevents overlays from being too small or large.
+*
+* @param screenWidth - Screen width in pixels
+* @param overlayType - Type of overlay ('text' | 'button' | 'panel')
+* @param isMobile - Whether on mobile device
+* @returns Optimal distance factor
+*
+* @category Html Overlay Helpers
+* @korean 거리인수계산
+*/
+function calculateDistanceFactor(screenWidth, overlayType, isMobile) {
+	const baseFactor = {
+		text: 10,
+		button: 12,
+		panel: 15
+	}[overlayType];
+	if (isMobile) return baseFactor * 1.5;
+	if (screenWidth < 1200) return baseFactor * 1.2;
+	return baseFactor;
+}
+//#endregion
+export { applyHtmlOverlayStyles, calculateDistanceFactor, calculateSafePosition, createHtmlOverlayConfig, getDefaultSafeArea, getZIndexForLayer, measureTextBounds };
+
+//# sourceMappingURL=htmlOverlayHelpers.js.map

package/lib/utils/htmlOverlayHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlOverlayHelpers.js","names":[],"sources":["../../src/utils/htmlOverlayHelpers.ts"],"sourcesContent":["/**\n * Html Overlay Positioning Helpers for Three.js\n *\n * Provides utilities for positioning Html overlays from @react-three/drei\n * with bounds checking, z-index management, and Korean text measurement.\n *\n * Fixes:\n * - Z-fighting between Html overlays and 3D elements\n * - Text clipping at screen edges\n * - Inconsistent overlay positioning\n * - Performance issues with many overlays\n *\n * @module utils/htmlOverlayHelpers\n * @category Utilities\n * @korean HTML오버레이헬퍼\n */\n\n// Note: Using Z_INDEX from LayoutTypes which is designed for Three.js Html overlays.\n// This is distinct from the legacy Z_INDEX in ui.ts which is for traditional DOM elements.\nimport { Z_INDEX, type ZIndexValue } from \"../types/LayoutTypes\";\nimport type {\n  HtmlOverlayLayer,\n  ScreenBounds,\n  ElementBounds,\n  SafePosition,\n  HtmlOverlayStyle,\n  TextMeasurement,\n  HtmlOverlayPositionOptions,\n  HtmlOverlayConfig,\n} from \"../types/HtmlOverlayTypes\";\nimport { FONT_FAMILY } from \"@/types/constants\";\n\n/**\n * Get z-index value for Html overlay layer\n *\n * Maps layer names to Z_INDEX constants for consistent stacking order.\n * Prevents z-fighting by maintaining clear hierarchy.\n *\n * @param layer - Html overlay layer category\n * @param offset - Optional offset to add to base z-index (default: 0)\n * @returns Z-index value for the layer\n *\n * @example\n * ```typescript\n * const zIndex = getZIndexForLayer('hud'); // Returns 40\n * const zIndexWithOffset = getZIndexForLayer('hud', 5); // Returns 45\n * ```\n *\n * @category Html Overlay Helpers\n * @korean Z인덱스가져오기\n */\nexport function getZIndexForLayer(\n  layer: HtmlOverlayLayer,\n  offset: number = 0,\n): ZIndexValue {\n  const layerMap: Record<HtmlOverlayLayer, ZIndexValue> = {\n    background: Z_INDEX.BACKGROUND,\n    arena: Z_INDEX.ARENA,\n    players: Z_INDEX.PLAYERS,\n    effects: Z_INDEX.EFFECTS,\n    hud: Z_INDEX.HUD,\n    \"mobile-controls\": Z_INDEX.MOBILE_CONTROLS,\n    modal: Z_INDEX.MODAL,\n    tooltip: Z_INDEX.TOOLTIP,\n    debug: Z_INDEX.DEBUG,\n  };\n\n  const baseZIndex = layerMap[layer];\n\n  // Derive the valid numeric z-index range from Z_INDEX to ensure we never\n  // return an out-of-bounds value, even if a large offset is provided.\n  const zIndexValues = Object.values(Z_INDEX).filter(\n    (value) => typeof value === \"number\",\n  ) as number[];\n  const minZIndex = Math.min(...zIndexValues);\n  const maxZIndex = Math.max(...zIndexValues);\n\n  const rawZIndex = baseZIndex + offset;\n  const clampedZIndex = Math.max(minZIndex, Math.min(maxZIndex, rawZIndex));\n\n  return clampedZIndex as ZIndexValue;\n}\n\n/**\n * Calculate safe position that prevents clipping at screen edges\n *\n * Takes a desired position and element bounds, then ensures the element\n * stays within screen bounds by clamping to safe area.\n *\n * @param position - Desired 3D position [x, y, z]\n * @param elementBounds - Size of the element\n * @param screenBounds - Screen size and safe area insets\n * @returns Safe position with clipping prevention\n *\n * @example\n * ```typescript\n * const safePos = calculateSafePosition(\n *   [100, 50, 0],\n *   { width: 200, height: 100, margin: 10 },\n *   { width: 1920, height: 1080 }\n * );\n * // Returns: { x: 100, y: 50, wasClamped: false }\n * ```\n *\n * @category Html Overlay Helpers\n * @korean 안전위치계산\n */\nexport function calculateSafePosition(\n  position: [number, number, number],\n  elementBounds: ElementBounds,\n  screenBounds: ScreenBounds,\n): SafePosition {\n  const [x, y] = position;\n  const margin = elementBounds.margin ?? 0;\n  const safeArea = screenBounds.safeArea ?? {\n    top: 0,\n    right: 0,\n    bottom: 0,\n    left: 0,\n  };\n\n  // Calculate effective bounds with safe area and margin\n  const minX = safeArea.left + margin;\n  const maxX =\n    screenBounds.width - safeArea.right - elementBounds.width - margin;\n  const minY = safeArea.top + margin;\n  const maxY =\n    screenBounds.height - safeArea.bottom - elementBounds.height - margin;\n\n  // Clamp position to safe bounds\n  const safeX = Math.max(minX, Math.min(x, maxX));\n  const safeY = Math.max(minY, Math.min(y, maxY));\n\n  // Check if position was clamped\n  const wasClamped = safeX !== x || safeY !== y;\n\n  return {\n    x: safeX,\n    y: safeY,\n    wasClamped,\n  };\n}\n\n/**\n * Measure Korean and English text dimensions\n *\n * Uses canvas-based text measurement to calculate accurate bounds\n * for bilingual text before rendering. Prevents text overflow.\n *\n * @param korean - Korean text content\n * @param english - English text content\n * @param fontSize - Font size in pixels\n * @param fontFamily - Font family to use (default: FONT_FAMILY.KOREAN)\n * @param layout - Text layout direction ('vertical' | 'horizontal')\n * @returns Text measurement with width and height\n *\n * @example\n * ```typescript\n * const bounds = measureTextBounds('공격', 'Attack', 16, FONT_FAMILY.KOREAN, 'vertical');\n * // Returns: { width: 48, height: 42, koreanWidth: 32, englishWidth: 48 }\n * ```\n *\n * @category Html Overlay Helpers\n * @korean 텍스트경계측정\n */\nexport function measureTextBounds(\n  korean: string,\n  english: string,\n  fontSize: number,\n  fontFamily: string = FONT_FAMILY.KOREAN,\n  layout: \"vertical\" | \"horizontal\" = \"vertical\",\n): TextMeasurement {\n  // Create canvas for text measurement\n  const canvas = document.createElement(\"canvas\");\n  const ctx = canvas.getContext(\"2d\");\n\n  if (!ctx) {\n    // Fallback if canvas not available\n    return {\n      width: fontSize * Math.max(korean.length, english.length),\n      height: fontSize * 2.4, // Line height * 2 lines\n      koreanWidth: fontSize * korean.length,\n      englishWidth: fontSize * english.length,\n    };\n  }\n\n  // Measure Korean text (larger, bold)\n  ctx.font = `bold ${fontSize}px ${fontFamily}`;\n  const koreanMetrics = ctx.measureText(korean);\n  const koreanWidth = koreanMetrics.width;\n\n  // Measure English text (smaller, italic)\n  const englishFontSize = fontSize * 0.75;\n  ctx.font = `italic ${englishFontSize}px ${fontFamily}`;\n  const englishMetrics = ctx.measureText(english);\n  const englishWidth = englishMetrics.width;\n\n  // Calculate total dimensions based on layout\n  let totalWidth: number;\n  let totalHeight: number;\n\n  if (layout === \"vertical\") {\n    // Vertical layout: max width, sum heights\n    totalWidth = Math.max(koreanWidth, englishWidth);\n    totalHeight = fontSize * 1.2 + englishFontSize * 1.2 + 4; // Line heights + gap\n  } else {\n    // Horizontal layout: sum widths, max height\n    totalWidth = koreanWidth + 8 + englishWidth; // Add gap between texts\n    totalHeight = Math.max(fontSize * 1.2, englishFontSize * 1.2);\n  }\n\n  return {\n    width: totalWidth,\n    height: totalHeight,\n    koreanWidth,\n    englishWidth,\n  };\n}\n\n/**\n * Apply standardized Html overlay styles\n *\n * Creates consistent styling for Html overlays with proper z-index,\n * pointer events, and performance optimizations.\n *\n * @param layer - Html overlay layer for z-index\n * @param interactive - Whether the overlay should receive pointer events\n * @param distanceFactor - Distance scaling factor (default: 10)\n * @param center - Whether to center the overlay (default: true)\n * @param occlude - Whether to occlude behind 3D objects (default: false)\n * @param zIndexOffset - Optional z-index offset (default: 0)\n * @returns Html overlay style configuration\n *\n * @example\n * ```typescript\n * const style = applyHtmlOverlayStyles('hud', false, 10, true);\n * // Returns: { zIndex: 40, pointerEvents: 'none', distanceFactor: 10, center: true, ... }\n * ```\n *\n * @category Html Overlay Helpers\n * @korean 오버레이스타일적용\n */\nexport function applyHtmlOverlayStyles(\n  layer: HtmlOverlayLayer,\n  interactive: boolean = false,\n  distanceFactor: number = 10,\n  center: boolean = true,\n  occlude: boolean = false,\n  zIndexOffset: number = 0,\n): HtmlOverlayStyle {\n  return {\n    zIndex: getZIndexForLayer(layer, zIndexOffset),\n    pointerEvents: interactive ? \"all\" : \"none\",\n    distanceFactor,\n    center,\n    occlude,\n    transform: \"translateZ(0)\", // GPU acceleration\n  };\n}\n\n/**\n * Create complete Html overlay configuration\n *\n * Combines position calculation, bounds checking, and styling\n * into a single configuration object for Html overlays.\n *\n * @param options - Html overlay positioning options\n * @returns Complete Html overlay configuration\n *\n * @example\n * ```typescript\n * const config = createHtmlOverlayConfig({\n *   position: [0, 2, 0],\n *   layer: 'hud',\n *   screenBounds: { width: 1920, height: 1080 },\n *   elementBounds: { width: 200, height: 100 },\n *   isMobile: false,\n * });\n * ```\n *\n * @category Html Overlay Helpers\n * @korean 오버레이설정생성\n */\nexport function createHtmlOverlayConfig(\n  options: HtmlOverlayPositionOptions,\n): HtmlOverlayConfig {\n  const {\n    position,\n    layer,\n    screenBounds,\n    elementBounds,\n    isMobile = false,\n    zIndexOffset = 0,\n  } = options;\n\n  // Calculate safe position if bounds provided\n  let safePosition: SafePosition;\n  if (screenBounds && elementBounds) {\n    safePosition = calculateSafePosition(position, elementBounds, screenBounds);\n  } else {\n    // No bounds checking needed\n    safePosition = {\n      x: position[0],\n      y: position[1],\n      wasClamped: false,\n    };\n  }\n\n  // Create style configuration\n  const style = applyHtmlOverlayStyles(\n    layer,\n    false, // Default to non-interactive for performance\n    isMobile ? 15 : 10, // Larger distance factor for mobile\n    true, // Center by default\n    false, // Don't occlude by default\n    zIndexOffset,\n  );\n\n  return {\n    position: safePosition,\n    style,\n    position3D: position,\n  };\n}\n\n/**\n * Get default safe area insets for mobile devices\n *\n * Provides standard safe area values for devices with notches\n * and home indicators (iPhone X+, modern Android).\n *\n * @param isMobile - Whether device is mobile\n * @returns Safe area insets\n *\n * @category Html Overlay Helpers\n * @korean 기본안전영역\n */\nexport function getDefaultSafeArea(isMobile: boolean): {\n  readonly top: number;\n  readonly right: number;\n  readonly bottom: number;\n  readonly left: number;\n} {\n  if (!isMobile) {\n    return { top: 0, right: 0, bottom: 0, left: 0 };\n  }\n\n  // Standard safe area for mobile devices with notches\n  return {\n    top: 44, // Status bar + notch\n    right: 0,\n    bottom: 34, // Home indicator\n    left: 0,\n  };\n}\n\n/**\n * Calculate optimal distance factor for Html overlay\n *\n * Determines appropriate distance scaling based on screen size\n * and overlay purpose. Prevents overlays from being too small or large.\n *\n * @param screenWidth - Screen width in pixels\n * @param overlayType - Type of overlay ('text' | 'button' | 'panel')\n * @param isMobile - Whether on mobile device\n * @returns Optimal distance factor\n *\n * @category Html Overlay Helpers\n * @korean 거리인수계산\n */\nexport function calculateDistanceFactor(\n  screenWidth: number,\n  overlayType: \"text\" | \"button\" | \"panel\",\n  isMobile: boolean,\n): number {\n  // Base distance factors by type\n  const baseFactors = {\n    text: 10,\n    button: 12,\n    panel: 15,\n  };\n\n  const baseFactor = baseFactors[overlayType];\n\n  // Adjust for mobile\n  if (isMobile) {\n    return baseFactor * 1.5; // 50% larger on mobile\n  }\n\n  // Adjust for screen width\n  if (screenWidth < 1200) {\n    return baseFactor * 1.2; // 20% larger on smaller screens\n  }\n\n  return baseFactor;\n}\n"],"mappings":"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"}

package/lib/utils/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility functions and helpers for Black Trigram
+ * @module utils
+ * @category Utilities
+ */
+export * from "./assetConfig";
+export * from "./colorUtils";
+export * from "./colorHelpers";
+export * from "./deviceDetection";
+export * from "./effectUtils";
+export * from "./playerUtils";
+export * from "./player3DHelpers";
+export * from "./htmlOverlayHelpers";
+export * from "./sharedPhysicsConfig";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC"}

package/lib/utils/index.js

@@ -0,0 +1,92 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.js";
+import { getColorRGB, mixColors, toHexColor } from "./colorHelpers.js";
+import { applyDamage, applyStatusEffect, calculateCombatEffectiveness, canPlayerAct, createPlayerFromArchetype, getArchetypeAssets, getArchetypeBonuses, getPlayerLeadFoot, getPlayerRearFoot, getStanceEffectiveness, getVitalPointByOnPlayerId, hasEnoughResources, initializeBodyFacing, resetPlayerState, toggleStanceSide, updatePlayerState, updateStatusEffects } from "./playerUtils.js";
+import { createCameraConfig, createPhysicsConfig } from "./sharedPhysicsConfig.js";
+import { darkenColor, getArchetypeColors, getArchetypeSkinTone, getArchetypeVisualProperties, getColorWithAlpha, getContrastColor, getHealthColor, hexColorToCSS, hexToRgb, hexToRgbaString, interpolateColor, lightenColor, rgbToHex, toHex } from "./colorUtils.js";
+import { animationStateToPlayerAnimation, convertPlayerStateToProps, getBalanceState, getPlayerAnimation } from "./player3DHelpers.js";
+import { applyHtmlOverlayStyles, calculateDistanceFactor, calculateSafePosition, createHtmlOverlayConfig, getDefaultSafeArea, getZIndexForLayer, measureTextBounds } from "./htmlOverlayHelpers.js";
+import { DeviceType, TABLET_BREAKPOINT, clearPlatformCache, detectPlatform, getSafeAreaInsets, isMobileDevice, shouldUseMobileControls } from "./deviceDetection.js";
+import { getAssetBasePath, resolveAssetPath, setAssetBasePath } from "./assetConfig.js";
+import { applyEffectModifiers, calculateEffectIntensity, combineEffects, createEffectFromKoreanText, createHitEffect, createKoreanStatusEffect, createStatusEffect, createTrigramEffect, getEffectDescription, getEffectDisplayText, getEffectDurationModifier, getHitEffectColor, groupEffectsByType, groupEffectsByTypeEnum, isEffectBeneficial, removeExpiredEffects, updateEffect } from "./effectUtils.js";
+//#region src/utils/index.ts
+var utils_exports = /* @__PURE__ */ __exportAll({
+	DeviceType: () => DeviceType,
+	MOBILE_BREAKPOINT: () => 768,
+	TABLET_BREAKPOINT: () => TABLET_BREAKPOINT,
+	animationStateToPlayerAnimation: () => animationStateToPlayerAnimation,
+	applyDamage: () => applyDamage,
+	applyEffectModifiers: () => applyEffectModifiers,
+	applyHtmlOverlayStyles: () => applyHtmlOverlayStyles,
+	applyStatusEffect: () => applyStatusEffect,
+	calculateCombatEffectiveness: () => calculateCombatEffectiveness,
+	calculateDistanceFactor: () => calculateDistanceFactor,
+	calculateEffectIntensity: () => calculateEffectIntensity,
+	calculateSafePosition: () => calculateSafePosition,
+	canPlayerAct: () => canPlayerAct,
+	clearPlatformCache: () => clearPlatformCache,
+	combineEffects: () => combineEffects,
+	convertPlayerStateToProps: () => convertPlayerStateToProps,
+	createCameraConfig: () => createCameraConfig,
+	createEffectFromKoreanText: () => createEffectFromKoreanText,
+	createHitEffect: () => createHitEffect,
+	createHtmlOverlayConfig: () => createHtmlOverlayConfig,
+	createKoreanStatusEffect: () => createKoreanStatusEffect,
+	createPhysicsConfig: () => createPhysicsConfig,
+	createPlayerFromArchetype: () => createPlayerFromArchetype,
+	createStatusEffect: () => createStatusEffect,
+	createTrigramEffect: () => createTrigramEffect,
+	darkenColor: () => darkenColor,
+	detectPlatform: () => detectPlatform,
+	getArchetypeAssets: () => getArchetypeAssets,
+	getArchetypeBonuses: () => getArchetypeBonuses,
+	getArchetypeColors: () => getArchetypeColors,
+	getArchetypeSkinTone: () => getArchetypeSkinTone,
+	getArchetypeVisualProperties: () => getArchetypeVisualProperties,
+	getAssetBasePath: () => getAssetBasePath,
+	getBalanceState: () => getBalanceState,
+	getColorRGB: () => getColorRGB,
+	getColorWithAlpha: () => getColorWithAlpha,
+	getContrastColor: () => getContrastColor,
+	getDefaultSafeArea: () => getDefaultSafeArea,
+	getEffectDescription: () => getEffectDescription,
+	getEffectDisplayText: () => getEffectDisplayText,
+	getEffectDurationModifier: () => getEffectDurationModifier,
+	getHealthColor: () => getHealthColor,
+	getHitEffectColor: () => getHitEffectColor,
+	getPlayerAnimation: () => getPlayerAnimation,
+	getPlayerLeadFoot: () => getPlayerLeadFoot,
+	getPlayerRearFoot: () => getPlayerRearFoot,
+	getSafeAreaInsets: () => getSafeAreaInsets,
+	getStanceEffectiveness: () => getStanceEffectiveness,
+	getVitalPointByOnPlayerId: () => getVitalPointByOnPlayerId,
+	getZIndexForLayer: () => getZIndexForLayer,
+	groupEffectsByType: () => groupEffectsByType,
+	groupEffectsByTypeEnum: () => groupEffectsByTypeEnum,
+	hasEnoughResources: () => hasEnoughResources,
+	hexColorToCSS: () => hexColorToCSS,
+	hexToRgb: () => hexToRgb,
+	hexToRgbaString: () => hexToRgbaString,
+	initializeBodyFacing: () => initializeBodyFacing,
+	interpolateColor: () => interpolateColor,
+	isEffectBeneficial: () => isEffectBeneficial,
+	isMobileDevice: () => isMobileDevice,
+	lightenColor: () => lightenColor,
+	measureTextBounds: () => measureTextBounds,
+	mixColors: () => mixColors,
+	removeExpiredEffects: () => removeExpiredEffects,
+	resetPlayerState: () => resetPlayerState,
+	resolveAssetPath: () => resolveAssetPath,
+	rgbToHex: () => rgbToHex,
+	setAssetBasePath: () => setAssetBasePath,
+	shouldUseMobileControls: () => shouldUseMobileControls,
+	toHex: () => toHex,
+	toHexColor: () => toHexColor,
+	toggleStanceSide: () => toggleStanceSide,
+	updateEffect: () => updateEffect,
+	updatePlayerState: () => updatePlayerState,
+	updateStatusEffects: () => updateStatusEffects
+});
+//#endregion
+export { utils_exports };
+
+//# sourceMappingURL=index.js.map

package/lib/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/utils/index.ts"],"sourcesContent":["/**\n * Utility functions and helpers for Black Trigram\n * @module utils\n * @category Utilities\n */\n\nexport * from \"./assetConfig\";\nexport * from \"./colorUtils\";\nexport * from \"./colorHelpers\";\nexport * from \"./deviceDetection\";\nexport * from \"./effectUtils\";\nexport * from \"./playerUtils\";\nexport * from \"./player3DHelpers\";\nexport * from \"./htmlOverlayHelpers\";\nexport * from \"./sharedPhysicsConfig\";\n"],"mappings":""}