@vircle/sdk-web 0.2.0

package/dist/index.esm.js

@@ -0,0 +1,1472 @@
+import { VircleCore, WebIdleScheduler } from '@vircle/sdk-core-ts';
+
+/**
+ * 웹 브라우저 환경 정보 수집기
+ */
+class WebContextCollector {
+    /**
+     * 전체 컨텍스트 수집
+     * @returns 수집된 컨텍스트
+     */
+    async collect() {
+        const [device, page, app] = await Promise.all([
+            this.collectDeviceContext(),
+            this.collectPageContext(),
+            this.collectAppContext(),
+        ]);
+        return {
+            device,
+            page,
+            app,
+            custom: this.collectCustomContext(),
+        };
+    }
+    /**
+     * 디바이스 정보 수집
+     */
+    async collectDeviceContext() {
+        const ua = navigator.userAgent;
+        const platform = navigator.platform || 'unknown';
+        return {
+            type: this.getDeviceType(ua),
+            os: this.getOS(ua, platform),
+            osVersion: this.getOSVersion(ua),
+            browser: this.getBrowser(ua),
+            browserVersion: this.getBrowserVersion(ua),
+            screenResolution: `${screen.width}x${screen.height}`,
+            viewport: {
+                width: window.innerWidth,
+                height: window.innerHeight,
+            },
+            language: navigator.language,
+            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        };
+    }
+    /**
+     * 페이지 정보 수집
+     */
+    async collectPageContext() {
+        const url = new URL(window.location.href);
+        return {
+            url: url.href,
+            title: document.title,
+            path: url.pathname,
+            search: url.search,
+            hash: url.hash,
+        };
+    }
+    /**
+     * 앱 정보 수집
+     */
+    async collectAppContext() {
+        return {
+            name: this.getAppName(),
+            version: this.getAppVersion(),
+            environment: this.getEnvironment(),
+        };
+    }
+    /**
+     * 커스텀 컨텍스트 수집
+     */
+    collectCustomContext() {
+        const context = {};
+        // Referrer 정보
+        if (document.referrer) {
+            context.referrer = document.referrer;
+        }
+        // UTM 파라미터 추출
+        const url = new URL(window.location.href);
+        const campaign = this.extractCampaignParams(url.searchParams);
+        if (campaign) {
+            context.campaign = campaign;
+        }
+        // 쿠키 활성화 여부
+        context.cookieEnabled = navigator.cookieEnabled;
+        // Do Not Track 설정
+        if (navigator.doNotTrack) {
+            context.doNotTrack = navigator.doNotTrack === '1';
+        }
+        const nav = navigator;
+        if (nav.connection) {
+            context.connection = {
+                effectiveType: nav.connection.effectiveType,
+                downlink: nav.connection.downlink,
+                rtt: nav.connection.rtt,
+                saveData: nav.connection.saveData,
+            };
+        }
+        const perf = performance;
+        if (perf.memory) {
+            context.memory = {
+                usedJSHeapSize: perf.memory.usedJSHeapSize,
+                totalJSHeapSize: perf.memory.totalJSHeapSize,
+                jsHeapSizeLimit: perf.memory.jsHeapSizeLimit,
+            };
+        }
+        return context;
+    }
+    /**
+     * 디바이스 타입 판별
+     */
+    getDeviceType(ua) {
+        if (/mobile/i.test(ua) && !/ipad/i.test(ua)) {
+            return 'mobile';
+        }
+        if (/ipad|tablet|playbook|silk/i.test(ua)) {
+            return 'tablet';
+        }
+        return 'desktop';
+    }
+    /**
+     * OS 판별
+     */
+    getOS(ua, platform) {
+        if (/windows/i.test(ua))
+            return 'Windows';
+        if (/macintosh|mac os x/i.test(ua))
+            return 'macOS';
+        if (/linux/i.test(ua))
+            return 'Linux';
+        if (/android/i.test(ua))
+            return 'Android';
+        if (/iphone|ipad|ipod/i.test(ua))
+            return 'iOS';
+        if (/cros/i.test(ua))
+            return 'Chrome OS';
+        return platform;
+    }
+    /**
+     * OS 버전 추출
+     */
+    getOSVersion(ua) {
+        let version = null;
+        if (/windows nt (\d+\.\d+)/i.test(ua)) {
+            version = ua.match(/windows nt (\d+\.\d+)/i);
+        }
+        else if (/mac os x (\d+[._]\d+)/i.test(ua)) {
+            version = ua.match(/mac os x (\d+[._]\d+)/i);
+        }
+        else if (/android (\d+\.\d+)/i.test(ua)) {
+            version = ua.match(/android (\d+\.\d+)/i);
+        }
+        else if (/os (\d+[._]\d+)/i.test(ua)) {
+            version = ua.match(/os (\d+[._]\d+)/i);
+        }
+        return version ? version[1].replace(/_/g, '.') : undefined;
+    }
+    /**
+     * 브라우저 판별
+     */
+    getBrowser(ua) {
+        if (/edg/i.test(ua))
+            return 'Edge';
+        if (/chrome|chromium|crios/i.test(ua))
+            return 'Chrome';
+        if (/firefox|fxios/i.test(ua))
+            return 'Firefox';
+        if (/safari/i.test(ua) && !/chrome/i.test(ua))
+            return 'Safari';
+        if (/opr|opera/i.test(ua))
+            return 'Opera';
+        if (/trident/i.test(ua))
+            return 'IE';
+        return 'Unknown';
+    }
+    /**
+     * 브라우저 버전 추출
+     */
+    getBrowserVersion(ua) {
+        let version = null;
+        if (/edg\/(\d+\.\d+)/i.test(ua)) {
+            version = ua.match(/edg\/(\d+\.\d+)/i);
+        }
+        else if (/chrome\/(\d+\.\d+)/i.test(ua)) {
+            version = ua.match(/chrome\/(\d+\.\d+)/i);
+        }
+        else if (/firefox\/(\d+\.\d+)/i.test(ua)) {
+            version = ua.match(/firefox\/(\d+\.\d+)/i);
+        }
+        else if (/version\/(\d+\.\d+).*safari/i.test(ua)) {
+            version = ua.match(/version\/(\d+\.\d+).*safari/i);
+        }
+        else if (/opr\/(\d+\.\d+)/i.test(ua)) {
+            version = ua.match(/opr\/(\d+\.\d+)/i);
+        }
+        return version ? version[1] : undefined;
+    }
+    /**
+     * UTM 캠페인 파라미터 추출
+     */
+    extractCampaignParams(params) {
+        const campaign = {};
+        const utmParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'];
+        let hasParams = false;
+        for (const param of utmParams) {
+            const value = params.get(param);
+            if (value) {
+                campaign[param.replace('utm_', '')] = value;
+                hasParams = true;
+            }
+        }
+        return hasParams ? campaign : undefined;
+    }
+    /**
+     * 앱 이름 가져오기 (meta 태그에서)
+     */
+    getAppName() {
+        const appNameMeta = document.querySelector('meta[name="application-name"]');
+        const ogSiteName = document.querySelector('meta[property="og:site_name"]');
+        return (appNameMeta?.content ||
+            ogSiteName?.content ||
+            document.title ||
+            'Web App');
+    }
+    /**
+     * 앱 버전 가져오기 (meta 태그에서)
+     */
+    getAppVersion() {
+        const versionMeta = document.querySelector('meta[name="version"]');
+        return versionMeta?.content || undefined;
+    }
+    /**
+     * 환경 판별
+     */
+    getEnvironment() {
+        const hostname = window.location.hostname;
+        if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname.includes('.local')) {
+            return 'development';
+        }
+        // Staging/test environments are considered as development
+        if (hostname.includes('staging') || hostname.includes('stage') || hostname.includes('test')) {
+            return 'development';
+        }
+        return 'production';
+    }
+}
+
+/**
+ * Vircle Web SDK 전용 에러 클래스
+ *
+ * @description
+ * Vircle Web SDK에서 발생하는 모든 에러의 기본 클래스입니다.
+ * 에러 코드와 상세 정보를 포함하여 디버깅을 용이하게 합니다.
+ *
+ * @example
+ * ```typescript
+ * throw new VircleWebError(
+ *   'API 키가 유효하지 않습니다',
+ *   'INVALID_API_KEY',
+ *   { apiKey: 'xxx...xxx' }
+ * )
+ * ```
+ */
+class VircleWebError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'VircleWebError';
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, VircleWebError);
+        }
+    }
+}
+/**
+ * 설정 관련 에러
+ *
+ * @description
+ * SDK 설정에 문제가 있을 때 발생하는 에러입니다.
+ * API 키 누락, 잘못된 설정 값 등의 경우에 사용됩니다.
+ *
+ * @example
+ * ```typescript
+ * if (!config.apiKey) {
+ *   throw new VircleConfigError('API 키가 필수입니다')
+ * }
+ * ```
+ */
+class VircleConfigError extends VircleWebError {
+    constructor(message, details) {
+        super(message, 'CONFIG_ERROR', details);
+        this.name = 'VircleConfigError';
+    }
+}
+/**
+ * 초기화 관련 에러
+ *
+ * @description
+ * SDK 초기화 과정에서 발생하는 에러입니다.
+ * 브라우저 호환성, 필수 API 지원 여부 등을 확인할 때 사용됩니다.
+ *
+ * @example
+ * ```typescript
+ * if (!window.Promise) {
+ *   throw new VircleInitializationError(
+ *     'Promise API를 지원하지 않는 브라우저입니다'
+ *   )
+ * }
+ * ```
+ */
+class VircleInitializationError extends VircleWebError {
+    constructor(message, details) {
+        super(message, 'INITIALIZATION_ERROR', details);
+        this.name = 'VircleInitializationError';
+    }
+}
+/**
+ * 스토리지 관련 에러
+ *
+ * @description
+ * LocalStorage 접근 실패, 용량 초과, 직렬화 오류 등
+ * 스토리지 작업 중 발생하는 에러입니다.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   localStorage.setItem(key, value)
+ * } catch (error) {
+ *   throw new VircleStorageError(
+ *     'LocalStorage 용량 초과',
+ *     { key, size: value.length }
+ *   )
+ * }
+ * ```
+ */
+class VircleStorageError extends VircleWebError {
+    constructor(message, details) {
+        super(message, 'STORAGE_ERROR', details);
+        this.name = 'VircleStorageError';
+    }
+}
+/**
+ * 브라우저 호환성 에러
+ *
+ * @description
+ * 현재 브라우저가 SDK에 필요한 기능을 지원하지 않을 때 발생하는 에러입니다.
+ * 필수 API 또는 기능이 누락된 경우에 사용됩니다.
+ *
+ * @example
+ * ```typescript
+ * if (!window.fetch) {
+ *   throw new VircleBrowserCompatibilityError(
+ *     'Fetch API를 지원하지 않는 브라우저입니다',
+ *     { userAgent: navigator.userAgent }
+ *   )
+ * }
+ * ```
+ */
+class VircleBrowserCompatibilityError extends VircleWebError {
+    constructor(message, details) {
+        super(message, 'BROWSER_COMPATIBILITY_ERROR', details);
+        this.name = 'VircleBrowserCompatibilityError';
+    }
+}
+
+/**
+ * 브라우저 LocalStorage를 사용하는 스토리지 어댑터
+ *
+ * @description
+ * 브라우저의 LocalStorage API를 활용하여 데이터를 영구 저장합니다.
+ * LocalStorage를 사용할 수 없는 환경에서는 자동으로 대체 스토리지로 폴백합니다.
+ * 용량 초과 시 자동으로 오래된 항목을 정리하는 LRU 방식을 지원합니다.
+ *
+ * @example
+ * ```typescript
+ * const storage = new LocalStorageAdapter('vircle_')
+ * await storage.set('user_id', '12345')
+ * const userId = await storage.get('user_id')
+ * ```
+ */
+class LocalStorageAdapter {
+    constructor(prefix = 'vircle_') {
+        this.prefix = prefix;
+        this.isAvailable = this.checkAvailability();
+    }
+    /**
+     * LocalStorage 사용 가능 여부 확인
+     *
+     * @description
+     * LocalStorage API의 사용 가능 여부를 테스트합니다.
+     * 개인정보 보호 모드나 보안 제한으로 인해 LocalStorage가 비활성화된 경우를 감지합니다.
+     *
+     * @private
+     * @returns {boolean} LocalStorage 사용 가능 여부
+     */
+    checkAvailability() {
+        try {
+            const testKey = `${this.prefix}test`;
+            localStorage.setItem(testKey, 'test');
+            localStorage.removeItem(testKey);
+            return true;
+        }
+        catch {
+            console.warn('[Vircle] LocalStorage를 사용할 수 없습니다. 메모리 스토리지로 대체됩니다.');
+            return false;
+        }
+    }
+    /**
+     * 키에 접두사 추가
+     *
+     * @description
+     * 키에 접두사를 추가하여 다른 애플리케이션과의 충돌을 방지합니다.
+     *
+     * @param {string} key - 원본 키
+     * @returns {string} 접두사가 추가된 키
+     * @private
+     */
+    getKey(key) {
+        return `${this.prefix}${key}`;
+    }
+    /**
+     * 값 저장
+     *
+     * @description
+     * LocalStorage에 값을 저장합니다. 자동으로 타임스탬프를 추가하여 LRU 정리를 지원합니다.
+     * 용량 초과 시 자동으로 오래된 항목을 정리한 후 재시도합니다.
+     *
+     * @example
+     * ```typescript
+     * await storage.set('preferences', { theme: 'dark', lang: 'ko' })
+     * ```
+     *
+     * @template T - 저장할 값의 타입
+     * @param {string} key - 키
+     * @param {T} value - 저장할 값
+     * @throws {VircleStorageError} 저장 실패 시
+     * @returns {Promise<void>}
+     */
+    async set(key, value) {
+        if (!this.isAvailable) {
+            return;
+        }
+        const item = {
+            value,
+            timestamp: Date.now(),
+        };
+        try {
+            const serialized = JSON.stringify(item);
+            localStorage.setItem(this.getKey(key), serialized);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'QuotaExceededError') {
+                console.warn('[Vircle] LocalStorage 용량 초과. 오래된 항목을 정리합니다.');
+                await this.clearOldItems();
+                // 재시도
+                try {
+                    const serialized = JSON.stringify(item);
+                    localStorage.setItem(this.getKey(key), serialized);
+                }
+                catch (retryError) {
+                    throw new VircleStorageError('LocalStorage 저장 실패', {
+                        key,
+                        error: retryError instanceof Error ? retryError.message : String(retryError),
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * 값 가져오기
+     *
+     * @description
+     * LocalStorage에서 값을 가져옵니다. 이전 버전과의 호환성을 지원합니다.
+     *
+     * @example
+     * ```typescript
+     * const preferences = await storage.get<{ theme: string }>('preferences')
+     * if (preferences) {
+     *   console.log(preferences.theme)
+     * }
+     * ```
+     *
+     * @template T - 반환할 값의 타입
+     * @param {string} key - 키
+     * @returns {Promise<T | null>} 저장된 값 또는 null
+     */
+    async get(key) {
+        if (!this.isAvailable) {
+            return null;
+        }
+        try {
+            const data = localStorage.getItem(this.getKey(key));
+            if (data === null) {
+                return null;
+            }
+            const parsed = JSON.parse(data);
+            // 구조가 올바른지 확인 (이전 버전 호환성)
+            if (parsed && typeof parsed === 'object' && 'value' in parsed && 'timestamp' in parsed) {
+                return parsed.value;
+            }
+            // 이전 버전 데이터 처리
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 값 삭제
+     *
+     * @description
+     * LocalStorage에서 특정 키의 값을 삭제합니다.
+     *
+     * @example
+     * ```typescript
+     * const removed = await storage.remove('old_data')
+     * console.log(removed ? '삭제 성공' : '키가 존재하지 않음')
+     * ```
+     *
+     * @param {string} key - 키
+     * @returns {Promise<boolean>} 삭제 성공 여부
+     */
+    async remove(key) {
+        if (!this.isAvailable) {
+            return false;
+        }
+        try {
+            const fullKey = this.getKey(key);
+            const exists = localStorage.getItem(fullKey) !== null;
+            if (exists) {
+                localStorage.removeItem(fullKey);
+                return true;
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 모든 값 삭제
+     *
+     * @description
+     * 현재 접두사로 시작하는 모든 키의 값을 LocalStorage에서 삭제합니다.
+     * 성능 최적화를 위해 모든 키를 한 번에 가져와서 필터링합니다.
+     *
+     * @example
+     * ```typescript
+     * await storage.clear()
+     * console.log('모든 데이터 삭제 완료')
+     * ```
+     *
+     * @returns {Promise<void>}
+     */
+    async clear() {
+        if (!this.isAvailable) {
+            return;
+        }
+        try {
+            // localStorage의 모든 키를 한번에 가져와서 필터링 (성능 최적화)
+            const allKeys = Object.keys(localStorage);
+            const keysToRemove = allKeys.filter((key) => key.startsWith(this.prefix));
+            keysToRemove.forEach((key) => localStorage.removeItem(key));
+        }
+        catch {
+            // 무시
+        }
+    }
+    /**
+     * 키 존재 여부 확인
+     *
+     * @description
+     * LocalStorage에 특정 키가 존재하는지 확인합니다.
+     *
+     * @example
+     * ```typescript
+     * if (await storage.has('user_preferences')) {
+     *   const prefs = await storage.get('user_preferences')
+     * }
+     * ```
+     *
+     * @param {string} key - 키
+     * @returns {Promise<boolean>} 존재 여부
+     */
+    async has(key) {
+        if (!this.isAvailable) {
+            return false;
+        }
+        try {
+            return localStorage.getItem(this.getKey(key)) !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 저장된 항목 수
+     *
+     * @description
+     * 현재 접두사로 저장된 모든 항목의 개수를 반환합니다.
+     *
+     * @example
+     * ```typescript
+     * const count = await storage.size()
+     * console.log(`저장된 항목 수: ${count}`)
+     * ```
+     *
+     * @returns {Promise<number>} 항목 수
+     */
+    async size() {
+        if (!this.isAvailable) {
+            return 0;
+        }
+        try {
+            // localStorage의 모든 키를 한번에 가져와서 필터링 (성능 최적화)
+            const allKeys = Object.keys(localStorage);
+            return allKeys.filter((key) => key.startsWith(this.prefix)).length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * 모든 키 반환
+     *
+     * @description
+     * 현재 접두사로 저장된 모든 키를 배열로 반환합니다.
+     * 접두사는 제거된 원본 키를 반환합니다.
+     *
+     * @example
+     * ```typescript
+     * const allKeys = await storage.keys()
+     * for (const key of allKeys) {
+     *   console.log(`Key: ${key}`)
+     * }
+     * ```
+     *
+     * @returns {Promise<string[]>} 키 배열
+     */
+    async keys() {
+        if (!this.isAvailable) {
+            return [];
+        }
+        try {
+            // localStorage의 모든 키를 한번에 가져와서 필터링 (성능 최적화)
+            const allKeys = Object.keys(localStorage);
+            return allKeys.filter((key) => key.startsWith(this.prefix)).map((key) => key.substring(this.prefix.length));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 오래된 항목 정리 (LRU 방식)
+     *
+     * @description
+     * LocalStorage 용량이 부족할 때 가장 오래된 항목들을 삭제합니다.
+     * 타임스탬프를 기준으로 오래된 순으로 정렬하여 하위 20%를 삭제합니다.
+     *
+     * @private
+     * @returns {Promise<void>}
+     */
+    async clearOldItems() {
+        try {
+            const items = [];
+            const allKeys = Object.keys(localStorage);
+            const prefixedKeys = allKeys.filter((key) => key.startsWith(this.prefix));
+            // 타임스탬프가 있는 항목 수집
+            for (const key of prefixedKeys) {
+                try {
+                    const data = localStorage.getItem(key);
+                    if (data) {
+                        const parsed = JSON.parse(data);
+                        if (parsed && typeof parsed === 'object' && 'timestamp' in parsed) {
+                            items.push({
+                                key,
+                                timestamp: parsed.timestamp || 0,
+                            });
+                        }
+                    }
+                }
+                catch {
+                    // 파싱 실패한 항목은 무시
+                }
+            }
+            // 오래된 순으로 정렬
+            items.sort((a, b) => a.timestamp - b.timestamp);
+            // 가장 오래된 20% 삭제 (최소 1개)
+            const deleteCount = Math.max(1, Math.floor(items.length * 0.2));
+            for (let i = 0; i < deleteCount && i < items.length; i++) {
+                localStorage.removeItem(items[i].key);
+            }
+        }
+        catch (error) {
+            // 전체 삭제 대신 에러 로깅만 수행
+            console.error('[Vircle] LocalStorage 정리 중 오류:', error);
+        }
+    }
+    /**
+     * 타임스탬프와 함께 저장 (LRU 지원)
+     *
+     * @deprecated set 메서드가 이미 타임스탬프를 포함합니다
+     * @param {string} key - 키
+     * @param {T} value - 저장할 값
+     * @returns {Promise<void>}
+     */
+    async setWithTimestamp(key, value) {
+        // 이제 set 메서드가 자동으로 타임스탬프를 저장합니다
+        await this.set(key, value);
+    }
+}
+
+/**
+ * 웹 성능 측정 및 추적
+ */
+class WebPerformanceTracker {
+    constructor() {
+        this.marks = new Map();
+    }
+    /**
+     * 성능 추적 시작
+     */
+    startTracking() {
+        if (!this.isSupported()) {
+            return;
+        }
+        // Long Task 감지
+        this.observeLongTasks();
+        // Layout Shift 감지
+        this.observeLayoutShifts();
+        // Largest Contentful Paint 감지
+        this.observeLCP();
+        // First Input Delay 감지
+        this.observeFID();
+    }
+    /**
+     * 성능 추적 중지
+     */
+    stopTracking() {
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = undefined;
+        }
+        this.marks.clear();
+    }
+    /**
+     * Performance API 지원 여부 확인
+     */
+    isSupported() {
+        return (typeof PerformanceObserver !== 'undefined' &&
+            typeof performance !== 'undefined' &&
+            typeof performance.mark === 'function');
+    }
+    /**
+     * Long Task 감지
+     */
+    observeLongTasks() {
+        if (!('PerformanceObserver' in window)) {
+            return;
+        }
+        try {
+            const observer = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    if (entry.duration > 50) {
+                        // 50ms 이상
+                        console.warn('[Vircle] Long task detected:', {
+                            duration: entry.duration,
+                            startTime: entry.startTime,
+                            name: entry.name,
+                        });
+                    }
+                }
+            });
+            observer.observe({ entryTypes: ['longtask'] });
+        }
+        catch {
+            // Long Task API를 지원하지 않는 브라우저
+        }
+    }
+    /**
+     * Layout Shift 감지
+     */
+    observeLayoutShifts() {
+        if (!('PerformanceObserver' in window)) {
+            return;
+        }
+        try {
+            const observer = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    const layoutShiftEntry = entry;
+                    if (!layoutShiftEntry.hadRecentInput) {
+                        // CLS would be tracked here: layoutShiftEntry.value
+                    }
+                }
+            });
+            observer.observe({ entryTypes: ['layout-shift'] });
+        }
+        catch {
+            // Layout Shift API를 지원하지 않는 브라우저
+        }
+    }
+    /**
+     * Largest Contentful Paint 감지
+     */
+    observeLCP() {
+        if (!('PerformanceObserver' in window)) {
+            return;
+        }
+        try {
+            const observer = new PerformanceObserver((list) => {
+                const entries = list.getEntries();
+                if (entries.length > 0) {
+                    // LCP tracked: entries[entries.length - 1].startTime
+                }
+            });
+            observer.observe({ entryTypes: ['largest-contentful-paint'] });
+        }
+        catch {
+            // LCP API를 지원하지 않는 브라우저
+        }
+    }
+    /**
+     * First Input Delay 감지
+     */
+    observeFID() {
+        if (!('PerformanceObserver' in window)) {
+            return;
+        }
+        try {
+            const observer = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    const fidEntry = entry;
+                    if (fidEntry.processingStart && fidEntry.startTime) {
+                        // FID tracked: fidEntry.processingStart - fidEntry.startTime
+                    }
+                }
+            });
+            observer.observe({ entryTypes: ['first-input'] });
+        }
+        catch {
+            // FID API를 지원하지 않는 브라우저
+        }
+    }
+    /**
+     * 커스텀 성능 마크 시작
+     * @param name - 마크 이름
+     */
+    mark(name) {
+        if (!this.isSupported()) {
+            return;
+        }
+        performance.mark(`vircle_${name}_start`);
+        this.marks.set(name, performance.now());
+    }
+    /**
+     * 커스텀 성능 측정
+     * @param name - 마크 이름
+     * @returns 측정된 시간 (ms)
+     */
+    measure(name) {
+        if (!this.isSupported() || !this.marks.has(name)) {
+            return null;
+        }
+        const startTime = this.marks.get(name);
+        const duration = performance.now() - startTime;
+        performance.mark(`vircle_${name}_end`);
+        performance.measure(`vircle_${name}`, `vircle_${name}_start`, `vircle_${name}_end`);
+        this.marks.delete(name);
+        return duration;
+    }
+    /**
+     * 페이지 로드 메트릭 가져오기
+     */
+    getLoadMetrics() {
+        if (!performance || !performance.timing) {
+            return {};
+        }
+        const timing = performance.timing;
+        const metrics = {};
+        // DNS 조회 시간
+        if (timing.domainLookupEnd && timing.domainLookupStart) {
+            metrics.dns = timing.domainLookupEnd - timing.domainLookupStart;
+        }
+        // TCP 연결 시간
+        if (timing.connectEnd && timing.connectStart) {
+            metrics.tcp = timing.connectEnd - timing.connectStart;
+        }
+        // 요청 시간
+        if (timing.responseStart && timing.requestStart) {
+            metrics.request = timing.responseStart - timing.requestStart;
+        }
+        // 응답 시간
+        if (timing.responseEnd && timing.responseStart) {
+            metrics.response = timing.responseEnd - timing.responseStart;
+        }
+        // DOM 처리 시간
+        if (timing.domComplete && timing.domLoading) {
+            metrics.domProcessing = timing.domComplete - timing.domLoading;
+        }
+        // 페이지 로드 완료 시간
+        if (timing.loadEventEnd && timing.navigationStart) {
+            metrics.pageLoad = timing.loadEventEnd - timing.navigationStart;
+        }
+        return metrics;
+    }
+    /**
+     * 리소스 타이밍 데이터 가져오기
+     */
+    getResourceTimings() {
+        if (!performance || !performance.getEntriesByType) {
+            return [];
+        }
+        const resources = performance.getEntriesByType('resource');
+        return resources.map((resource) => ({
+            name: resource.name,
+            type: resource.initiatorType,
+            duration: resource.duration,
+            size: resource.transferSize || 0,
+        }));
+    }
+}
+/**
+ * 함수 실행 시간 측정 데코레이터
+ */
+function measurePerformance(target, propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    descriptor.value = async function (...args) {
+        const start = performance.now();
+        const result = await originalMethod.apply(this, args);
+        performance.now() - start;
+        return result;
+    };
+    return descriptor;
+}
+/**
+ * 디바운스 유틸리티
+ * @param func - 디바운스할 함수
+ * @param wait - 대기 시간 (ms)
+ * @returns 디바운스된 함수
+ */
+function debounce(func, wait) {
+    let timeoutId = null;
+    return function debounced(...args) {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            func(...args);
+            timeoutId = null;
+        }, wait);
+    };
+}
+/**
+ * 쓰로틀 유틸리티
+ * @param func - 쓰로틀할 함수
+ * @param limit - 제한 시간 (ms)
+ * @returns 쓰로틀된 함수
+ */
+function throttle(func, limit) {
+    let inThrottle = false;
+    let lastArgs = null;
+    return function throttled(...args) {
+        if (!inThrottle) {
+            func(...args);
+            inThrottle = true;
+            setTimeout(() => {
+                inThrottle = false;
+                if (lastArgs) {
+                    const args = lastArgs;
+                    lastArgs = null;
+                    throttled(...args);
+                }
+            }, limit);
+        }
+        else {
+            lastArgs = args;
+        }
+    };
+}
+
+/**
+ * Web 플랫폼용 Vircle SDK
+ *
+ * @example
+ * ```typescript
+ * const vircle = new VircleWeb({
+ *   apiKey: 'your-api-key',
+ *   trackPageViews: true,
+ *   trackErrors: true
+ * })
+ *
+ * await vircle.initialize()
+ * ```
+ */
+class VircleWeb extends VircleCore {
+    constructor(config, options = {}) {
+        // 웹 환경용 스토리지 어댑터 설정
+        const storageAdapter = new LocalStorageAdapter(config.storagePrefix);
+        const coreOptions = {
+            ...options,
+            storageAdapter,
+        };
+        super(config, coreOptions);
+        this.pageViewTracked = false;
+        this.webConfig = config;
+        this.webOptions = {
+            flushOnUnload: true,
+            contextCacheTime: 300000, // 5분
+            idleScheduler: new WebIdleScheduler(),
+            enablePerformance: true,
+            ...options,
+        };
+        // 웹 환경 전용 컴포넌트 초기화
+        this.contextCollector = new WebContextCollector();
+        if (this.webOptions.enablePerformance) {
+            this.performanceTracker = new WebPerformanceTracker();
+        }
+    }
+    /**
+     * SDK 초기화 및 자동 추적 설정
+     *
+     * @description
+     * SDK를 초기화하고 설정에 따라 자동 추적 기능을 활성화합니다.
+     * 페이지뷰, 에러, 클릭, 폼 제출 등의 자동 추적을 설정할 수 있습니다.
+     *
+     * @example
+     * ```typescript
+     * const vircle = new VircleWeb({
+     *   apiKey: 'your-api-key',
+     *   trackPageViews: true,
+     *   trackErrors: true
+     * })
+     *
+     * await vircle.initialize()
+     * ```
+     *
+     * @throws {VircleInitializationError} 초기화 실패 시
+     * @returns {Promise<void>}
+     */
+    async initialize() {
+        try {
+            await super.initialize();
+            // 자동 추적 핸들러 설정
+            this.setupAutoTracking();
+            // 초기 컨텍스트 수집
+            const context = await this.contextCollector.collect();
+            this.setContext(context);
+            // 초기 페이지뷰 추적
+            if (this.webConfig.trackPageViews && !this.pageViewTracked) {
+                await this.trackPageView();
+                this.pageViewTracked = true;
+            }
+            // 성능 메트릭 수집 시작
+            if (this.performanceTracker) {
+                this.performanceTracker.startTracking();
+            }
+        }
+        catch (error) {
+            console.error('[Vircle] 초기화 실패:', error);
+            throw error;
+        }
+    }
+    /**
+     * 페이지뷰 추적
+     *
+     * @description
+     * 현재 페이지의 방문을 추적합니다. URL, 제목, 리퍼러 등의 정보를 자동으로 수집합니다.
+     *
+     * @example
+     * ```typescript
+     * // 기본 페이지뷰 추적
+     * await vircle.trackPageView()
+     *
+     * // 추가 속성과 함께 추적
+     * await vircle.trackPageView({
+     *   category: 'blog',
+     *   author: 'john.doe'
+     * })
+     * ```
+     *
+     * @param {Record<string, unknown>} [properties] - 추가 속성
+     * @param {EventContext} [context] - 추가 컨텍스트
+     * @returns {Promise<void>}
+     */
+    async trackPageView(properties, context) {
+        const pageContext = await this.contextCollector.collectPageContext();
+        return this.track('page_view', {
+            ...pageContext,
+            ...properties,
+        }, context);
+    }
+    /**
+     * 웹 환경에 최적화된 이벤트 추적
+     * AIDEV-NOTE: 이제 코어의 TaskScheduler를 사용하여 requestIdleCallback 기반의
+     * 일관된 성능 최적화 구현
+     */
+    async track(name, properties, context) {
+        return new Promise((resolve) => {
+            this.taskScheduler.enqueue(async () => {
+                try {
+                    const webContext = await this.getCachedContext();
+                    const mergedContext = {
+                        ...webContext,
+                        ...context,
+                    };
+                    await super.track(name, properties, mergedContext);
+                    resolve();
+                }
+                catch (error) {
+                    console.warn(`[Vircle] 이벤트 추적 실패 "${name}":`, error);
+                    resolve(); // 에러 시에도 resolve하여 앱 크래시 방지
+                }
+            });
+        });
+    }
+    /**
+     * 캐시된 컨텍스트 반환 또는 새로 수집
+     *
+     * @description
+     * 컨텍스트 정보를 캐시에서 가져오거나 새로 수집합니다.
+     * 성능 최적화를 위해 캐싱을 사용하며, 중복 수집을 방지합니다.
+     *
+     * @private
+     * @returns {Promise<EventContext>} 이벤트 컨텍스트
+     *
+     * AIDEV-NOTE: 컨텍스트 수집은 DOM 접근이 많아 비용이 높으므로
+     * 캐싱을 통해 성능을 최적화. 중복 수집 방지를 위한 Promise 재사용 구현
+     */
+    async getCachedContext() {
+        return this.contextCache.getOrCollect(() => this.contextCollector.collect());
+    }
+    /**
+     * 자동 추적 설정
+     *
+     * @description
+     * 설정에 따라 다양한 자동 추적 기능을 활성화합니다.
+     * 페이지 언로드 시 플러시, 에러 추적, 클릭 추적, 폼 제출 추적, SPA 라우팅 추적 등을 설정합니다.
+     *
+     * @private
+     */
+    setupAutoTracking() {
+        // 페이지 언로드 시 플러시
+        if (this.webOptions.flushOnUnload) {
+            this.unloadHandler = async () => {
+                try {
+                    // 대기 중인 idle 작업들 먼저 처리
+                    // Flush any pending tasks
+                    await this.flush();
+                    // 이벤트 플러시
+                    await this.flush();
+                }
+                catch (error) {
+                    console.warn('[Vircle] 언로드 시 플러시 실패:', error);
+                }
+            };
+            window.addEventListener('beforeunload', this.unloadHandler);
+            // visibilitychange 이벤트도 처리 (모바일 브라우저 대응)
+            document.addEventListener('visibilitychange', () => {
+                if (document.visibilityState === 'hidden') {
+                    this.flush().catch((error) => {
+                        console.warn('[Vircle] 백그라운드 전환 시 플러시 실패:', error);
+                    });
+                }
+            });
+        }
+        // 에러 추적
+        if (this.webConfig.trackErrors) {
+            this.setupErrorTracking();
+        }
+        // 클릭 추적
+        if (this.webConfig.trackClicks) {
+            this.setupClickTracking();
+        }
+        // 폼 제출 추적
+        if (this.webConfig.trackForms) {
+            this.setupFormTracking();
+        }
+        // SPA 라우팅 추적
+        if (this.webConfig.singlePageApp) {
+            this.setupSPATracking();
+        }
+    }
+    /**
+     * 에러 추적 설정
+     *
+     * @description
+     * JavaScript 에러와 처리되지 않은 Promise rejection을 자동으로 추적합니다.
+     * 에러 메시지, 파일 위치, 스택 트레이스 등의 정보를 수집합니다.
+     *
+     * @private
+     */
+    setupErrorTracking() {
+        this.errorHandler = (event) => {
+            this.track('error', {
+                message: event.message,
+                source: event.filename,
+                line: event.lineno,
+                column: event.colno,
+                stack: event.error?.stack,
+            }).catch((error) => {
+                console.warn('[Vircle] 에러 추적 실패:', error);
+            });
+        };
+        this.unhandledRejectionHandler = (event) => {
+            this.track('unhandled_rejection', {
+                reason: event.reason?.toString(),
+                promise: event.promise?.toString(),
+            }).catch((error) => {
+                console.warn('[Vircle] Promise rejection 추적 실패:', error);
+            });
+        };
+        window.addEventListener('error', this.errorHandler);
+        window.addEventListener('unhandledrejection', this.unhandledRejectionHandler);
+    }
+    /**
+     * 클릭 추적 설정
+     *
+     * @description
+     * 사용자의 클릭 이벤트를 자동으로 추적합니다.
+     * 링크, 버튼, 입력 필드 등의 의미 있는 요소들의 클릭을 감지합니다.
+     * data-vircle-ignore 속성이 있는 요소는 추적에서 제외됩니다.
+     *
+     * @private
+     */
+    setupClickTracking() {
+        this.clickHandler = (event) => {
+            const target = event.target;
+            // 추적할 요소 필터링
+            if (!this.shouldTrackElement(target)) {
+                return;
+            }
+            const properties = this.extractElementProperties(target);
+            this.track('element_clicked', properties).catch((error) => {
+                console.warn('[Vircle] 클릭 추적 실패:', error);
+            });
+        };
+        document.addEventListener('click', this.clickHandler, true);
+    }
+    /**
+     * 폼 제출 추적 설정
+     *
+     * @description
+     * HTML 폼의 제출 이벤트를 자동으로 추적합니다.
+     * 폼 ID, 이름, action URL, 메서드 등의 정보를 수집합니다.
+     *
+     * @private
+     */
+    setupFormTracking() {
+        this.submitHandler = (event) => {
+            const form = event.target;
+            const properties = {
+                form_id: form.id,
+                form_name: form.name,
+                form_action: form.action,
+                form_method: form.method,
+            };
+            this.track('form_submitted', properties).catch((error) => {
+                console.warn('[Vircle] 폼 제출 추적 실패:', error);
+            });
+        };
+        document.addEventListener('submit', this.submitHandler, true);
+    }
+    /**
+     * SPA 라우팅 추적 설정
+     *
+     * @description
+     * 싱글 페이지 애플리케이션(SPA)의 라우팅 변경을 감지하고 추적합니다.
+     * History API의 pushState, replaceState를 래핑하고 popstate 이벤트를 수신하여
+     * 클라이언트 사이드 라우팅 변경을 감지합니다.
+     *
+     * @private
+     */
+    setupSPATracking() {
+        // pushState/replaceState 래핑
+        const originalPushState = history.pushState;
+        const originalReplaceState = history.replaceState;
+        history.pushState = (...args) => {
+            originalPushState.apply(history, args);
+            this.handleRouteChange();
+        };
+        history.replaceState = (...args) => {
+            originalReplaceState.apply(history, args);
+            this.handleRouteChange();
+        };
+        // popstate 이벤트 리스너
+        this.popstateHandler = () => {
+            this.handleRouteChange();
+        };
+        window.addEventListener('popstate', this.popstateHandler);
+    }
+    /**
+     * 라우트 변경 처리
+     *
+     * @description
+     * SPA에서 라우트가 변경될 때 호출되는 핸들러입니다.
+     * 컨텍스트 캐시를 무효화하고 새로운 페이지뷰를 추적합니다.
+     *
+     * @private
+     */
+    handleRouteChange() {
+        // 캐시 무효화
+        this.contextCache.invalidate();
+        // 새 페이지뷰 추적
+        if (this.webConfig.trackPageViews) {
+            this.trackPageView().catch((error) => {
+                console.warn('[Vircle] 라우트 변경 추적 실패:', error);
+            });
+        }
+    }
+    /**
+     * 요소가 추적 대상인지 확인
+     *
+     * @description
+     * HTML 요소가 자동 추적 대상인지 판단합니다.
+     * data-vircle-ignore 속성이 있거나 부모 요소에 해당 속성이 있으면 false를 반환합니다.
+     *
+     * @param {HTMLElement} element - 확인할 HTML 요소
+     * @returns {boolean} 추적 대상 여부
+     * @private
+     */
+    shouldTrackElement(element) {
+        // data-vircle-ignore 속성이 있으면 무시
+        if (element.hasAttribute('data-vircle-ignore')) {
+            return false;
+        }
+        // 부모 요소에도 ignore 속성이 있는지 확인
+        let parent = element.parentElement;
+        while (parent) {
+            if (parent.hasAttribute('data-vircle-ignore')) {
+                return false;
+            }
+            parent = parent.parentElement;
+        }
+        // 의미있는 요소들만 추적
+        const trackableTags = ['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'];
+        return trackableTags.includes(element.tagName);
+    }
+    /**
+     * 요소에서 속성 추출
+     *
+     * @description
+     * HTML 요소에서 추적에 필요한 속성을 추출합니다.
+     * 태그 이름, ID, 클래스, href, 텍스트 내용 등을 수집합니다.
+     *
+     * @param {HTMLElement} element - 속성을 추출할 HTML 요소
+     * @returns {Record<string, unknown>} 추출된 속성 객체
+     * @private
+     */
+    extractElementProperties(element) {
+        const properties = {
+            tag_name: element.tagName.toLowerCase(),
+            element_id: element.id || undefined,
+            element_class: element.className || undefined,
+            element_href: element.href || undefined,
+            element_text: element.textContent?.slice(0, 100) || undefined,
+        };
+        // 추가 속성 수집은 idle 시간에 처리 (성능 최적화)
+        this.taskScheduler.enqueue(() => {
+            // data-* 속성 수집
+            const dataAttributes = {};
+            Array.from(element.attributes).forEach((attr) => {
+                if (attr.name.startsWith('data-') && !attr.name.startsWith('data-vircle-')) {
+                    dataAttributes[attr.name] = attr.value;
+                }
+            });
+            if (Object.keys(dataAttributes).length > 0) {
+                // 비동기로 추가 속성을 포함한 이벤트 업데이트
+                this.track('element_data_collected', {
+                    ...properties,
+                    data_attributes: dataAttributes,
+                }).catch((error) => {
+                    console.debug('[Vircle] Data attributes collection failed:', error);
+                });
+            }
+        });
+        return properties;
+    }
+    /**
+     * SDK 리소스 정리
+     *
+     * @description
+     * SDK가 사용하는 모든 리소스를 정리합니다.
+     * 이벤트 리스너 제거, 성능 추적 중지, 대기 중인 이벤트 전송 등을 수행합니다.
+     *
+     * @example
+     * ```typescript
+     * // 앱 종료 시 정리
+     * window.addEventListener('beforeunload', async () => {
+     *   await vircle.cleanup()
+     * })
+     * ```
+     *
+     * @throws {Error} 정리 중 오류 발생 시
+     * @returns {Promise<void>}
+     */
+    async cleanup() {
+        try {
+            // 이벤트 리스너 제거
+            if (this.unloadHandler) {
+                window.removeEventListener('beforeunload', this.unloadHandler);
+            }
+            if (this.errorHandler) {
+                window.removeEventListener('error', this.errorHandler);
+            }
+            if (this.unhandledRejectionHandler) {
+                window.removeEventListener('unhandledrejection', this.unhandledRejectionHandler);
+            }
+            if (this.clickHandler) {
+                document.removeEventListener('click', this.clickHandler, true);
+            }
+            if (this.submitHandler) {
+                document.removeEventListener('submit', this.submitHandler, true);
+            }
+            if (this.popstateHandler) {
+                window.removeEventListener('popstate', this.popstateHandler);
+            }
+            // 성능 추적 정지
+            if (this.performanceTracker) {
+                this.performanceTracker.stopTracking();
+            }
+            // Idle 작업 정리
+            // Flush pending tasks
+            await this.flush();
+            // 부모 cleanup 호출
+            await super.cleanup();
+        }
+        catch (error) {
+            console.error('[Vircle] 정리 중 오류:', error);
+            throw error;
+        }
+    }
+    /**
+     * 현재 페이지 URL 반환
+     *
+     * @description
+     * 현재 브라우저의 전체 URL을 반환합니다.
+     *
+     * @example
+     * ```typescript
+     * const url = vircle.getCurrentUrl()
+     * console.log(url) // https://example.com/path?query=value
+     * ```
+     *
+     * @returns {string} 현재 페이지의 전체 URL
+     */
+    getCurrentUrl() {
+        return window.location.href;
+    }
+    /**
+     * 네트워크 연결 상태 확인
+     *
+     * @description
+     * 브라우저의 온라인/오프라인 상태를 확인합니다.
+     * Navigator.onLine API를 사용하여 네트워크 연결 상태를 반환합니다.
+     *
+     * @example
+     * ```typescript
+     * if (vircle.isOnline()) {
+     *   // 온라인 상태에서만 실행할 코드
+     *   await vircle.flush()
+     * }
+     * ```
+     *
+     * @returns {boolean} 온라인 상태 여부
+     */
+    isOnline() {
+        return navigator.onLine;
+    }
+}
+
+export { LocalStorageAdapter, VircleBrowserCompatibilityError, VircleConfigError, VircleInitializationError, VircleStorageError, VircleWeb, VircleWebError, WebContextCollector, WebPerformanceTracker, debounce, VircleWeb as default, measurePerformance, throttle };
+//# sourceMappingURL=index.esm.js.map