@adstage/web-sdk 1.3.3 → 1.3.4

package/dist/index.cjs.js

@@ -257,6 +257,72 @@ class DOMUtils {
             scrollLeft: this.getWindowProperty('pageXOffset', 0),
         };
     }
+    /**
+     * DOM 요소가 나타날 때까지 기다리기 (사용자 친화적 API)
+     */
+    static async waitForElement(id, options = {}) {
+        const { timeout = 3000, retryInterval = 100, debug = false } = options;
+        if (!this.canUseDOM()) {
+            throw new Error('DOM을 사용할 수 없는 환경입니다.');
+        }
+        // 즉시 찾을 수 있으면 바로 반환
+        const immediateElement = document.getElementById(id);
+        if (immediateElement) {
+            if (debug) {
+                console.log(`✅ 컨테이너 즉시 발견: ${id}`);
+            }
+            return immediateElement;
+        }
+        if (debug) {
+            console.log(`⏳ 컨테이너 대기 시작: ${id} (최대 ${timeout}ms)`);
+        }
+        return new Promise((resolve, reject) => {
+            let attempts = 0;
+            const maxAttempts = Math.ceil(timeout / retryInterval);
+            const checkElement = () => {
+                attempts++;
+                const element = document.getElementById(id);
+                if (element) {
+                    if (debug) {
+                        console.log(`✅ 컨테이너 발견: ${id} (${attempts}번째 시도, ${attempts * retryInterval}ms 경과)`);
+                    }
+                    resolve(element);
+                    return;
+                }
+                if (attempts >= maxAttempts) {
+                    const errorMessage = `❌ 컨테이너를 찾을 수 없습니다: "${id}"
+          
+다음을 확인해보세요:
+1. HTML에 id="${id}" 요소가 있는지 확인
+2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+3. 철자가 정확한지 확인
+4. 중복된 ID가 없는지 확인
+
+대기 시간: ${timeout}ms (${attempts}번 시도)`;
+                    if (debug) {
+                        console.error(errorMessage);
+                    }
+                    reject(new Error(errorMessage));
+                    return;
+                }
+                if (debug && attempts % 10 === 0) {
+                    console.log(`⏳ 컨테이너 대기 중: ${id} (${attempts}/${maxAttempts})`);
+                }
+                // Exponential backoff: 처음엔 빠르게, 나중엔 느리게
+                const nextInterval = Math.min(retryInterval * Math.pow(1.2, attempts), 500);
+                setTimeout(checkElement, nextInterval);
+            };
+            // 첫 번째 체크는 즉시 실행
+            setTimeout(checkElement, retryInterval);
+        });
+    }
+    /**
+     * 여러 DOM 요소를 동시에 기다리기
+     */
+    static async waitForElements(ids, options = {}) {
+        const promises = ids.map(id => this.waitForElement(id, options));
+        return Promise.all(promises);
+    }
 }
 
 /**
@@ -1814,31 +1880,49 @@ class AdStageSDK {
      * 광고 슬롯 생성 및 로드
      */
     async createSlot(id, containerId, adType = exports.AdType.BANNER, options) {
-        const container = DOMUtils.safeGetElementById(containerId);
-        if (!container) {
-            if (DOMUtils.canUseDOM()) {
-                console.error(`Container with ID "${containerId}" not found`);
+        try {
+            // 💡 사용자 친화적 개선: 컨테이너가 나타날 때까지 자동으로 기다림
+            if (this.config.debug) {
+                console.log(`🔍 컨테이너 검색 시작: ${containerId}`);
+            }
+            const container = await DOMUtils.waitForElement(containerId, {
+                timeout: 5000, // 최대 5초 대기
+                retryInterval: 50, // 50ms마다 체크 (부드러운 사용자 경험)
+                debug: this.config.debug
+            });
+            if (this.config.debug) {
+                console.log(`✅ 컨테이너 확인됨: ${containerId}`, container);
+            }
+            const slot = {
+                id,
+                containerId,
+                adType,
+                width: options?.width || 0, // 문자열도 지원
+                height: options?.height || 0, // 문자열도 지원
+                isLoaded: false,
+                isVisible: false,
+                refreshRate: 0,
+                lazyLoad: false,
+                targeting: {},
+                load: async () => { await this.loadSlot(slot, options); return null; },
+                render: (ad) => this.renderSlot(slot, ad),
+                refresh: () => this.refreshSlot(slot.id),
+                destroy: () => this.destroySlot(slot.id),
+            };
+            this.slots.set(id, slot);
+            await this.loadSlot(slot, options);
+        }
+        catch (error) {
+            // 친절한 에러 메시지로 사용자 가이드
+            if (error instanceof Error && error.message.includes('컨테이너를 찾을 수 없습니다')) {
+                console.error(error.message);
+                throw error;
+            }
+            else {
+                console.error(`❌ 광고 슬롯 생성 실패 (${id}):`, error);
+                throw new Error(`광고 슬롯 생성에 실패했습니다: ${error}`);
             }
-            return;
         }
-        const slot = {
-            id,
-            containerId,
-            adType,
-            width: options?.width || 0, // 문자열도 지원
-            height: options?.height || 0, // 문자열도 지원
-            isLoaded: false,
-            isVisible: false,
-            refreshRate: 0,
-            lazyLoad: false,
-            targeting: {},
-            load: async () => { await this.loadSlot(slot, options); return null; },
-            render: (ad) => this.renderSlot(slot, ad),
-            refresh: () => this.refreshSlot(slot.id),
-            destroy: () => this.destroySlot(slot.id),
-        };
-        this.slots.set(id, slot);
-        await this.loadSlot(slot, options);
     }
     /**
      * 광고 슬롯 로드
@@ -1905,9 +1989,10 @@ class AdStageSDK {
      * 광고 슬롯 렌더링 (슬라이더 포함)
      */
     renderSlotWithSlider(slot, advertisements, options) {
+        // 💡 한 번 더 안전하게 컨테이너 확인
         const container = DOMUtils.safeGetElementById(slot.containerId);
         if (!container) {
-            console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
+            console.error(`❌ 렌더링 시점에 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
         }
         if (this.config.debug) {

package/dist/index.esm.js

@@ -253,6 +253,72 @@ class DOMUtils {
             scrollLeft: this.getWindowProperty('pageXOffset', 0),
         };
     }
+    /**
+     * DOM 요소가 나타날 때까지 기다리기 (사용자 친화적 API)
+     */
+    static async waitForElement(id, options = {}) {
+        const { timeout = 3000, retryInterval = 100, debug = false } = options;
+        if (!this.canUseDOM()) {
+            throw new Error('DOM을 사용할 수 없는 환경입니다.');
+        }
+        // 즉시 찾을 수 있으면 바로 반환
+        const immediateElement = document.getElementById(id);
+        if (immediateElement) {
+            if (debug) {
+                console.log(`✅ 컨테이너 즉시 발견: ${id}`);
+            }
+            return immediateElement;
+        }
+        if (debug) {
+            console.log(`⏳ 컨테이너 대기 시작: ${id} (최대 ${timeout}ms)`);
+        }
+        return new Promise((resolve, reject) => {
+            let attempts = 0;
+            const maxAttempts = Math.ceil(timeout / retryInterval);
+            const checkElement = () => {
+                attempts++;
+                const element = document.getElementById(id);
+                if (element) {
+                    if (debug) {
+                        console.log(`✅ 컨테이너 발견: ${id} (${attempts}번째 시도, ${attempts * retryInterval}ms 경과)`);
+                    }
+                    resolve(element);
+                    return;
+                }
+                if (attempts >= maxAttempts) {
+                    const errorMessage = `❌ 컨테이너를 찾을 수 없습니다: "${id}"
+          
+다음을 확인해보세요:
+1. HTML에 id="${id}" 요소가 있는지 확인
+2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+3. 철자가 정확한지 확인
+4. 중복된 ID가 없는지 확인
+
+대기 시간: ${timeout}ms (${attempts}번 시도)`;
+                    if (debug) {
+                        console.error(errorMessage);
+                    }
+                    reject(new Error(errorMessage));
+                    return;
+                }
+                if (debug && attempts % 10 === 0) {
+                    console.log(`⏳ 컨테이너 대기 중: ${id} (${attempts}/${maxAttempts})`);
+                }
+                // Exponential backoff: 처음엔 빠르게, 나중엔 느리게
+                const nextInterval = Math.min(retryInterval * Math.pow(1.2, attempts), 500);
+                setTimeout(checkElement, nextInterval);
+            };
+            // 첫 번째 체크는 즉시 실행
+            setTimeout(checkElement, retryInterval);
+        });
+    }
+    /**
+     * 여러 DOM 요소를 동시에 기다리기
+     */
+    static async waitForElements(ids, options = {}) {
+        const promises = ids.map(id => this.waitForElement(id, options));
+        return Promise.all(promises);
+    }
 }
 
 /**
@@ -1810,31 +1876,49 @@ class AdStageSDK {
      * 광고 슬롯 생성 및 로드
      */
     async createSlot(id, containerId, adType = AdType.BANNER, options) {
-        const container = DOMUtils.safeGetElementById(containerId);
-        if (!container) {
-            if (DOMUtils.canUseDOM()) {
-                console.error(`Container with ID "${containerId}" not found`);
+        try {
+            // 💡 사용자 친화적 개선: 컨테이너가 나타날 때까지 자동으로 기다림
+            if (this.config.debug) {
+                console.log(`🔍 컨테이너 검색 시작: ${containerId}`);
+            }
+            const container = await DOMUtils.waitForElement(containerId, {
+                timeout: 5000, // 최대 5초 대기
+                retryInterval: 50, // 50ms마다 체크 (부드러운 사용자 경험)
+                debug: this.config.debug
+            });
+            if (this.config.debug) {
+                console.log(`✅ 컨테이너 확인됨: ${containerId}`, container);
+            }
+            const slot = {
+                id,
+                containerId,
+                adType,
+                width: options?.width || 0, // 문자열도 지원
+                height: options?.height || 0, // 문자열도 지원
+                isLoaded: false,
+                isVisible: false,
+                refreshRate: 0,
+                lazyLoad: false,
+                targeting: {},
+                load: async () => { await this.loadSlot(slot, options); return null; },
+                render: (ad) => this.renderSlot(slot, ad),
+                refresh: () => this.refreshSlot(slot.id),
+                destroy: () => this.destroySlot(slot.id),
+            };
+            this.slots.set(id, slot);
+            await this.loadSlot(slot, options);
+        }
+        catch (error) {
+            // 친절한 에러 메시지로 사용자 가이드
+            if (error instanceof Error && error.message.includes('컨테이너를 찾을 수 없습니다')) {
+                console.error(error.message);
+                throw error;
+            }
+            else {
+                console.error(`❌ 광고 슬롯 생성 실패 (${id}):`, error);
+                throw new Error(`광고 슬롯 생성에 실패했습니다: ${error}`);
             }
-            return;
         }
-        const slot = {
-            id,
-            containerId,
-            adType,
-            width: options?.width || 0, // 문자열도 지원
-            height: options?.height || 0, // 문자열도 지원
-            isLoaded: false,
-            isVisible: false,
-            refreshRate: 0,
-            lazyLoad: false,
-            targeting: {},
-            load: async () => { await this.loadSlot(slot, options); return null; },
-            render: (ad) => this.renderSlot(slot, ad),
-            refresh: () => this.refreshSlot(slot.id),
-            destroy: () => this.destroySlot(slot.id),
-        };
-        this.slots.set(id, slot);
-        await this.loadSlot(slot, options);
     }
     /**
      * 광고 슬롯 로드
@@ -1901,9 +1985,10 @@ class AdStageSDK {
      * 광고 슬롯 렌더링 (슬라이더 포함)
      */
     renderSlotWithSlider(slot, advertisements, options) {
+        // 💡 한 번 더 안전하게 컨테이너 확인
         const container = DOMUtils.safeGetElementById(slot.containerId);
         if (!container) {
-            console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
+            console.error(`❌ 렌더링 시점에 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
         }
         if (this.config.debug) {

package/dist/index.standalone.js

@@ -253,6 +253,72 @@ class DOMUtils {
             scrollLeft: this.getWindowProperty('pageXOffset', 0),
         };
     }
+    /**
+     * DOM 요소가 나타날 때까지 기다리기 (사용자 친화적 API)
+     */
+    static async waitForElement(id, options = {}) {
+        const { timeout = 3000, retryInterval = 100, debug = false } = options;
+        if (!this.canUseDOM()) {
+            throw new Error('DOM을 사용할 수 없는 환경입니다.');
+        }
+        // 즉시 찾을 수 있으면 바로 반환
+        const immediateElement = document.getElementById(id);
+        if (immediateElement) {
+            if (debug) {
+                console.log(`✅ 컨테이너 즉시 발견: ${id}`);
+            }
+            return immediateElement;
+        }
+        if (debug) {
+            console.log(`⏳ 컨테이너 대기 시작: ${id} (최대 ${timeout}ms)`);
+        }
+        return new Promise((resolve, reject) => {
+            let attempts = 0;
+            const maxAttempts = Math.ceil(timeout / retryInterval);
+            const checkElement = () => {
+                attempts++;
+                const element = document.getElementById(id);
+                if (element) {
+                    if (debug) {
+                        console.log(`✅ 컨테이너 발견: ${id} (${attempts}번째 시도, ${attempts * retryInterval}ms 경과)`);
+                    }
+                    resolve(element);
+                    return;
+                }
+                if (attempts >= maxAttempts) {
+                    const errorMessage = `❌ 컨테이너를 찾을 수 없습니다: "${id}"
+          
+다음을 확인해보세요:
+1. HTML에 id="${id}" 요소가 있는지 확인
+2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+3. 철자가 정확한지 확인
+4. 중복된 ID가 없는지 확인
+
+대기 시간: ${timeout}ms (${attempts}번 시도)`;
+                    if (debug) {
+                        console.error(errorMessage);
+                    }
+                    reject(new Error(errorMessage));
+                    return;
+                }
+                if (debug && attempts % 10 === 0) {
+                    console.log(`⏳ 컨테이너 대기 중: ${id} (${attempts}/${maxAttempts})`);
+                }
+                // Exponential backoff: 처음엔 빠르게, 나중엔 느리게
+                const nextInterval = Math.min(retryInterval * Math.pow(1.2, attempts), 500);
+                setTimeout(checkElement, nextInterval);
+            };
+            // 첫 번째 체크는 즉시 실행
+            setTimeout(checkElement, retryInterval);
+        });
+    }
+    /**
+     * 여러 DOM 요소를 동시에 기다리기
+     */
+    static async waitForElements(ids, options = {}) {
+        const promises = ids.map(id => this.waitForElement(id, options));
+        return Promise.all(promises);
+    }
 }
 
 /**
@@ -1810,31 +1876,49 @@ class AdStageSDK {
      * 광고 슬롯 생성 및 로드
      */
     async createSlot(id, containerId, adType = AdType.BANNER, options) {
-        const container = DOMUtils.safeGetElementById(containerId);
-        if (!container) {
-            if (DOMUtils.canUseDOM()) {
-                console.error(`Container with ID "${containerId}" not found`);
+        try {
+            // 💡 사용자 친화적 개선: 컨테이너가 나타날 때까지 자동으로 기다림
+            if (this.config.debug) {
+                console.log(`🔍 컨테이너 검색 시작: ${containerId}`);
+            }
+            const container = await DOMUtils.waitForElement(containerId, {
+                timeout: 5000, // 최대 5초 대기
+                retryInterval: 50, // 50ms마다 체크 (부드러운 사용자 경험)
+                debug: this.config.debug
+            });
+            if (this.config.debug) {
+                console.log(`✅ 컨테이너 확인됨: ${containerId}`, container);
+            }
+            const slot = {
+                id,
+                containerId,
+                adType,
+                width: options?.width || 0, // 문자열도 지원
+                height: options?.height || 0, // 문자열도 지원
+                isLoaded: false,
+                isVisible: false,
+                refreshRate: 0,
+                lazyLoad: false,
+                targeting: {},
+                load: async () => { await this.loadSlot(slot, options); return null; },
+                render: (ad) => this.renderSlot(slot, ad),
+                refresh: () => this.refreshSlot(slot.id),
+                destroy: () => this.destroySlot(slot.id),
+            };
+            this.slots.set(id, slot);
+            await this.loadSlot(slot, options);
+        }
+        catch (error) {
+            // 친절한 에러 메시지로 사용자 가이드
+            if (error instanceof Error && error.message.includes('컨테이너를 찾을 수 없습니다')) {
+                console.error(error.message);
+                throw error;
+            }
+            else {
+                console.error(`❌ 광고 슬롯 생성 실패 (${id}):`, error);
+                throw new Error(`광고 슬롯 생성에 실패했습니다: ${error}`);
             }
-            return;
         }
-        const slot = {
-            id,
-            containerId,
-            adType,
-            width: options?.width || 0, // 문자열도 지원
-            height: options?.height || 0, // 문자열도 지원
-            isLoaded: false,
-            isVisible: false,
-            refreshRate: 0,
-            lazyLoad: false,
-            targeting: {},
-            load: async () => { await this.loadSlot(slot, options); return null; },
-            render: (ad) => this.renderSlot(slot, ad),
-            refresh: () => this.refreshSlot(slot.id),
-            destroy: () => this.destroySlot(slot.id),
-        };
-        this.slots.set(id, slot);
-        await this.loadSlot(slot, options);
     }
     /**
      * 광고 슬롯 로드
@@ -1901,9 +1985,10 @@ class AdStageSDK {
      * 광고 슬롯 렌더링 (슬라이더 포함)
      */
     renderSlotWithSlider(slot, advertisements, options) {
+        // 💡 한 번 더 안전하게 컨테이너 확인
         const container = DOMUtils.safeGetElementById(slot.containerId);
         if (!container) {
-            console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
+            console.error(`❌ 렌더링 시점에 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
         }
         if (this.config.debug) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "1.3.3",
-  "description": "AdStage Web SDK for displaying advertisements",
+  "version": "1.3.4",
+  "description": "AdStage Web SDK for displaying advertisements with auto DOM-ready detection",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/src/index.ts

@@ -85,33 +85,51 @@ export class AdStageSDK {
       sliderEffect?: 'slide' | 'fade'; // 슬라이더 효과 선택 (기본값: slide)
     }
   ): Promise<void> {
-    const container = DOMUtils.safeGetElementById(containerId);
-    if (!container) {
-      if (DOMUtils.canUseDOM()) {
-        console.error(`Container with ID "${containerId}" not found`);
+    try {
+      // 💡 사용자 친화적 개선: 컨테이너가 나타날 때까지 자동으로 기다림
+      if (this.config.debug) {
+        console.log(`🔍 컨테이너 검색 시작: ${containerId}`);
       }
-      return;
-    }
+      
+      const container = await DOMUtils.waitForElement(containerId, {
+        timeout: 5000,      // 최대 5초 대기
+        retryInterval: 50,  // 50ms마다 체크 (부드러운 사용자 경험)
+        debug: this.config.debug
+      });
 
-    const slot: AdSlot = {
-      id,
-      containerId,
-      adType,
-      width: options?.width || 0,  // 문자열도 지원
-      height: options?.height || 0, // 문자열도 지원
-      isLoaded: false,
-      isVisible: false,
-      refreshRate: 0,
-      lazyLoad: false,
-      targeting: {},
-      load: async () => { await this.loadSlot(slot, options); return null; },
-      render: (ad: Advertisement) => this.renderSlot(slot, ad),
-      refresh: () => this.refreshSlot(slot.id),
-      destroy: () => this.destroySlot(slot.id),
-    };
+      if (this.config.debug) {
+        console.log(`✅ 컨테이너 확인됨: ${containerId}`, container);
+      }
 
-    this.slots.set(id, slot);
-    await this.loadSlot(slot, options);
+      const slot: AdSlot = {
+        id,
+        containerId,
+        adType,
+        width: options?.width || 0,  // 문자열도 지원
+        height: options?.height || 0, // 문자열도 지원
+        isLoaded: false,
+        isVisible: false,
+        refreshRate: 0,
+        lazyLoad: false,
+        targeting: {},
+        load: async () => { await this.loadSlot(slot, options); return null; },
+        render: (ad: Advertisement) => this.renderSlot(slot, ad),
+        refresh: () => this.refreshSlot(slot.id),
+        destroy: () => this.destroySlot(slot.id),
+      };
+
+      this.slots.set(id, slot);
+      await this.loadSlot(slot, options);
+    } catch (error) {
+      // 친절한 에러 메시지로 사용자 가이드
+      if (error instanceof Error && error.message.includes('컨테이너를 찾을 수 없습니다')) {
+        console.error(error.message);
+        throw error;
+      } else {
+        console.error(`❌ 광고 슬롯 생성 실패 (${id}):`, error);
+        throw new Error(`광고 슬롯 생성에 실패했습니다: ${error}`);
+      }
+    }
   }
 
   /**
@@ -189,9 +207,10 @@ export class AdStageSDK {
    * 광고 슬롯 렌더링 (슬라이더 포함)
    */
   private renderSlotWithSlider(slot: AdSlot, advertisements: Advertisement[], options?: any): void {
+    // 💡 한 번 더 안전하게 컨테이너 확인
     const container = DOMUtils.safeGetElementById(slot.containerId);
     if (!container) {
-      console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
+      console.error(`❌ 렌더링 시점에 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
       return;
     }
 

package/src/utils/dom-utils.ts

@@ -234,4 +234,97 @@ export class DOMUtils {
       scrollLeft: this.getWindowProperty('pageXOffset', 0),
     };
   }
+
+  /**
+   * DOM 요소가 나타날 때까지 기다리기 (사용자 친화적 API)
+   */
+  static async waitForElement(
+    id: string, 
+    options: {
+      timeout?: number;        // 최대 대기 시간 (ms), 기본값: 3000
+      retryInterval?: number;  // 재시도 간격 (ms), 기본값: 100  
+      debug?: boolean;         // 디버그 로그 출력 여부
+    } = {}
+  ): Promise<HTMLElement> {
+    const { timeout = 3000, retryInterval = 100, debug = false } = options;
+    
+    if (!this.canUseDOM()) {
+      throw new Error('DOM을 사용할 수 없는 환경입니다.');
+    }
+
+    // 즉시 찾을 수 있으면 바로 반환
+    const immediateElement = document.getElementById(id);
+    if (immediateElement) {
+      if (debug) {
+        console.log(`✅ 컨테이너 즉시 발견: ${id}`);
+      }
+      return immediateElement;
+    }
+
+    if (debug) {
+      console.log(`⏳ 컨테이너 대기 시작: ${id} (최대 ${timeout}ms)`);
+    }
+
+    return new Promise((resolve, reject) => {
+      let attempts = 0;
+      const maxAttempts = Math.ceil(timeout / retryInterval);
+      
+      const checkElement = () => {
+        attempts++;
+        const element = document.getElementById(id);
+        
+        if (element) {
+          if (debug) {
+            console.log(`✅ 컨테이너 발견: ${id} (${attempts}번째 시도, ${attempts * retryInterval}ms 경과)`);
+          }
+          resolve(element);
+          return;
+        }
+        
+        if (attempts >= maxAttempts) {
+          const errorMessage = `❌ 컨테이너를 찾을 수 없습니다: "${id}"
+          
+다음을 확인해보세요:
+1. HTML에 id="${id}" 요소가 있는지 확인
+2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+3. 철자가 정확한지 확인
+4. 중복된 ID가 없는지 확인
+
+대기 시간: ${timeout}ms (${attempts}번 시도)`;
+          
+          if (debug) {
+            console.error(errorMessage);
+          }
+          reject(new Error(errorMessage));
+          return;
+        }
+        
+        if (debug && attempts % 10 === 0) {
+          console.log(`⏳ 컨테이너 대기 중: ${id} (${attempts}/${maxAttempts})`);
+        }
+        
+        // Exponential backoff: 처음엔 빠르게, 나중엔 느리게
+        const nextInterval = Math.min(retryInterval * Math.pow(1.2, attempts), 500);
+        setTimeout(checkElement, nextInterval);
+      };
+      
+      // 첫 번째 체크는 즉시 실행
+      setTimeout(checkElement, retryInterval);
+    });
+  }
+
+  /**
+   * 여러 DOM 요소를 동시에 기다리기
+   */
+  static async waitForElements(
+    ids: string[], 
+    options: {
+      timeout?: number;
+      retryInterval?: number;
+      debug?: boolean;
+    } = {}
+  ): Promise<HTMLElement[]> {
+    const promises = ids.map(id => this.waitForElement(id, options));
+    return Promise.all(promises);
+  }
 }