@auto-wiz/dom 1.1.0 → 1.1.2

package/dist/runner.d.ts

@@ -1,6 +1,5 @@
 import { type FlowRunner, type RunResult, type ExecutionResult, type RunnerOptions, type Flow, type Step } from "@auto-wiz/core";
 export declare class DomFlowRunner implements FlowRunner<void> {
-    run(flow: Flow, _context?: any, // unused
-    _options?: RunnerOptions): Promise<RunResult>;
-    runStep(step: Step): Promise<ExecutionResult>;
+    run(flow: Flow, _context?: any, options?: RunnerOptions): Promise<RunResult>;
+    runStep(step: Step, _context?: void, options?: RunnerOptions): Promise<ExecutionResult>;
 }

package/dist/runner.js

@@ -1,14 +1,12 @@
 import { executeStep } from "./steps/stepExecution";
 export class DomFlowRunner {
-    async run(flow, _context = {}, // unused
-    _options = {} // unused
-    ) {
+    async run(flow, _context = {}, options = {}) {
         const extractedData = {};
         const steps = flow.steps;
         for (let i = 0; i < steps.length; i++) {
             const step = steps[i];
             try {
-                const result = await this.runStep(step);
+                const result = await this.runStep(step, undefined, options);
                 if (!result.success) {
                     return {
                         success: false,
@@ -32,10 +30,10 @@ export class DomFlowRunner {
         }
         return { success: true, extractedData };
     }
-    async runStep(step) {
+    async runStep(step, _context, options = {}) {
         try {
             // Direct DOM execution using existing logic
-            const result = await executeStep(step);
+            const result = await executeStep(step, options);
             return result;
         }
         catch (error) {

package/dist/selectors/locatorUtils.d.ts

@@ -45,20 +45,21 @@ export declare function findByLabelText(text: string, options?: {
  */
 export declare function findByTestId(testId: string): HTMLElement | null;
 /**
- * ElementLocator로 요소 찾기 (fallback 지원)
+ * ElementLocator로 요소 찾기 (fallback 지원 + 다중 매칭 검증)
  *
  * Primary selector부터 시도하고, 실패하면 fallback들을 순차적으로 시도
+ * 여러 요소가 매칭되면 metadata로 정확한 요소 선별
  */
-export declare function findByLocator(locator: ElementLocator): HTMLElement | null;
+export declare function findByLocator(locator: ElementLocator): HTMLElement | SVGElement | null;
 /**
- * 요소가 상호작용 가능한지 확인 (enabled + visible)
+ * 요소가 상호작용 가능한지 확인 (enabled + visible) - HTMLElement와 SVGElement 모두 지원
  */
-export declare function isInteractable(element: HTMLElement): boolean;
+export declare function isInteractable(element: HTMLElement | SVGElement): boolean;
 /**
- * Smart waiting: 요소가 나타날 때까지 대기
+ * Smart waiting: 요소가 나타날 때까지 대기 - HTMLElement와 SVGElement 모두 지원
  */
 export declare function waitForLocator(locator: ElementLocator, options?: {
     timeout?: number;
     visible?: boolean;
     interactable?: boolean;
-}): Promise<HTMLElement>;
+}): Promise<HTMLElement | SVGElement>;

package/dist/selectors/locatorUtils.js

@@ -258,27 +258,207 @@ export function findByTestId(testId) {
     return null;
 }
 /**
- * ElementLocator로 요소 찾기 (fallback 지원)
+ * Input 요소와 연결된 label 텍스트 가져오기 (재생 시 검증용)
+ */
+function getAssociatedLabelTextForElement(element) {
+    // 1. label[for="id"] 방식
+    if (element.id) {
+        const label = document.querySelector(`label[for="${CSS.escape(element.id)}"]`);
+        if (label)
+            return label.textContent?.trim() || null;
+    }
+    // 2. 부모 label 방식
+    const parentLabel = element.closest("label");
+    if (parentLabel) {
+        const clone = parentLabel.cloneNode(true);
+        const input = clone.querySelector("input, textarea, select");
+        if (input)
+            input.remove();
+        const text = clone.textContent?.trim();
+        if (text)
+            return text;
+    }
+    // 3. aria-labelledby 방식
+    const labelledby = element.getAttribute("aria-labelledby");
+    if (labelledby) {
+        const labelEl = document.getElementById(labelledby);
+        if (labelEl)
+            return labelEl.textContent?.trim() || null;
+    }
+    // 4. 이전 형제 label 탐지
+    const prevSibling = element.previousElementSibling;
+    if (prevSibling && prevSibling.tagName.toLowerCase() === "label") {
+        return prevSibling.textContent?.trim() || null;
+    }
+    // 5. 같은 컨테이너 내 첫 번째 label
+    const parent = element.parentElement;
+    if (parent) {
+        const labelInParent = parent.querySelector("label");
+        if (labelInParent) {
+            const forAttr = labelInParent.getAttribute("for");
+            if (!forAttr || forAttr === element.id) {
+                return labelInParent.textContent?.trim() || null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Form 내에서의 위치 정보 가져오기 (재생 시 검증용)
+ */
+function getFormContextForElement(element) {
+    const form = element.closest("form");
+    if (!form)
+        return null;
+    let formSelector = "";
+    if (form.id && !form.id.match(/[0-9a-f]{8,}/i)) {
+        formSelector = `#${CSS.escape(form.id)}`;
+    }
+    else if (form.getAttribute("name")) {
+        formSelector = `form[name="${form.getAttribute("name")}"]`;
+    }
+    else {
+        // 클래스 기반
+        const classes = Array.from(form.classList).filter((c) => !c.match(/[0-9a-f]{8,}/i) && !c.startsWith("_"));
+        if (classes.length > 0) {
+            formSelector = "form." + classes.slice(0, 2).map((c) => CSS.escape(c)).join(".");
+        }
+        else {
+            const forms = document.querySelectorAll("form");
+            const index = Array.from(forms).indexOf(form);
+            formSelector = `form:nth-of-type(${index + 1})`;
+        }
+    }
+    const allFormFields = form.querySelectorAll("input, textarea, select");
+    const fieldIndex = Array.from(allFormFields).indexOf(element) + 1;
+    return { formSelector, fieldIndex };
+}
+/**
+ * Metadata로 후보 요소들 중 정확한 요소 찾기 (다중 매칭 시 검증)
+ */
+function verifyWithMetadata(candidates, metadata) {
+    if (!metadata)
+        return candidates[0]; // metadata 없으면 첫 번째 반환
+    let bestMatch = null;
+    let bestScore = -1;
+    for (const el of candidates) {
+        if (!isVisible(el))
+            continue;
+        let score = 0;
+        // labelText 매칭 (가장 높은 우선순위)
+        if (metadata.labelText &&
+            (el instanceof HTMLInputElement ||
+                el instanceof HTMLTextAreaElement ||
+                el instanceof HTMLSelectElement)) {
+            const labelText = getAssociatedLabelTextForElement(el);
+            if (labelText === metadata.labelText) {
+                score += 100;
+            }
+            else if (labelText && labelText.includes(metadata.labelText)) {
+                score += 50;
+            }
+        }
+        // formContext 매칭
+        if (metadata.formContext && el instanceof HTMLElement) {
+            const context = getFormContextForElement(el);
+            if (context) {
+                // formSelector가 일치하고 fieldIndex도 일치하면 높은 점수
+                if (context.fieldIndex === metadata.formContext.fieldIndex) {
+                    score += 80;
+                }
+            }
+        }
+        // placeholder 매칭
+        if (metadata.placeholder) {
+            if (el.getAttribute("placeholder") === metadata.placeholder) {
+                score += 60;
+            }
+        }
+        // tagName 매칭
+        if (metadata.tagName) {
+            if (el.tagName.toLowerCase() === metadata.tagName) {
+                score += 10;
+            }
+        }
+        // role 매칭
+        if (metadata.role) {
+            const elementRole = el.getAttribute("role") ||
+                (el instanceof HTMLElement ? getImplicitRoleForElement(el) : null);
+            if (elementRole === metadata.role) {
+                score += 10;
+            }
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            bestMatch = el;
+        }
+    }
+    // 최소 점수 기준 (labelText나 formContext가 매칭되어야 신뢰)
+    if (bestScore >= 50) {
+        return bestMatch;
+    }
+    // 점수가 낮으면 첫 번째 visible 요소 반환 (기존 동작 유지)
+    return candidates.find((el) => isVisible(el)) || null;
+}
+/**
+ * 암시적 ARIA role 추론 (verifyWithMetadata용)
+ */
+function getImplicitRoleForElement(element) {
+    const tagName = element.tagName.toLowerCase();
+    const type = element.getAttribute("type");
+    const roleMap = {
+        button: "button",
+        input: type === "text" || !type
+            ? "textbox"
+            : type === "checkbox"
+                ? "checkbox"
+                : type === "radio"
+                    ? "radio"
+                    : type === "button" || type === "submit"
+                        ? "button"
+                        : "",
+        textarea: "textbox",
+        select: "combobox",
+    };
+    return roleMap[tagName] || null;
+}
+/**
+ * ElementLocator로 요소 찾기 (fallback 지원 + 다중 매칭 검증)
  *
  * Primary selector부터 시도하고, 실패하면 fallback들을 순차적으로 시도
+ * 여러 요소가 매칭되면 metadata로 정확한 요소 선별
  */
 export function findByLocator(locator) {
-    // 1. Primary selector 시도
+    // 1. Primary selector로 모든 요소 찾기
     try {
-        const el = document.querySelector(locator.primary);
-        if (el instanceof HTMLElement && isVisible(el)) {
-            return el;
+        const elements = document.querySelectorAll(locator.primary);
+        const candidates = Array.from(elements).filter((el) => (el instanceof HTMLElement || el instanceof SVGElement) && isVisible(el));
+        if (candidates.length === 1) {
+            // 하나만 매칭되면 그것 사용
+            return candidates[0];
+        }
+        else if (candidates.length > 1) {
+            // 여러 개 매칭되면 metadata로 검증
+            const verified = verifyWithMetadata(candidates, locator.metadata);
+            if (verified)
+                return verified;
         }
     }
     catch (error) {
         console.warn(`Primary selector failed: ${locator.primary}`, error);
     }
-    // 2. Fallback selectors 순차 시도
+    // 2. Fallback selectors 순차 시도 (동일 로직)
     for (const selector of locator.fallbacks) {
         try {
-            const el = document.querySelector(selector);
-            if (el instanceof HTMLElement && isVisible(el)) {
-                return el;
+            const elements = document.querySelectorAll(selector);
+            const candidates = Array.from(elements).filter((el) => (el instanceof HTMLElement || el instanceof SVGElement) && isVisible(el));
+            if (candidates.length === 1) {
+                return candidates[0];
+            }
+            else if (candidates.length > 1) {
+                const verified = verifyWithMetadata(candidates, locator.metadata);
+                if (verified)
+                    return verified;
             }
         }
         catch (error) {
@@ -288,6 +468,22 @@ export function findByLocator(locator) {
     // 3. Metadata 기반 fuzzy matching
     if (!locator.metadata)
         return null;
+    // labelText로 시도 (form input 특화)
+    if (locator.metadata.labelText) {
+        const elements = findByLabelTextExtended(locator.metadata.labelText, {
+            exact: true,
+        });
+        if (elements.length > 0) {
+            // tagName도 일치하는 것 우선
+            if (locator.metadata.tagName) {
+                const matchingTag = elements.find((el) => el.tagName.toLowerCase() === locator.metadata.tagName);
+                if (matchingTag && isVisible(matchingTag))
+                    return matchingTag;
+            }
+            if (isVisible(elements[0]))
+                return elements[0];
+        }
+    }
     // TestID로 시도
     if (locator.metadata.testId) {
         const el = findByTestId(locator.metadata.testId);
@@ -331,7 +527,65 @@ export function findByLocator(locator) {
     return null;
 }
 /**
- * 요소가 화면에 보이는지 확인
+ * Label로 요소 찾기 (확장 버전 - 이전 형제 label도 지원)
+ */
+function findByLabelTextExtended(text, options) {
+    const results = [];
+    // 1. 기존 label[for] 및 부모 label 방식
+    const labels = Array.from(document.querySelectorAll("label"));
+    for (const label of labels) {
+        const labelText = label.textContent?.trim() || "";
+        const matches = options?.exact ? labelText === text : labelText.includes(text);
+        if (!matches)
+            continue;
+        // label[for] 참조
+        const forAttr = label.getAttribute("for");
+        if (forAttr) {
+            const input = document.getElementById(forAttr);
+            if (input instanceof HTMLElement) {
+                results.push(input);
+            }
+        }
+        else {
+            // label 내부의 input
+            const input = label.querySelector("input, textarea, select");
+            if (input instanceof HTMLElement) {
+                results.push(input);
+            }
+        }
+    }
+    // 2. 이전 형제 label 방식 (div > label + input 구조)
+    const allInputs = document.querySelectorAll("input, textarea, select");
+    for (const input of allInputs) {
+        if (!(input instanceof HTMLElement))
+            continue;
+        if (results.includes(input))
+            continue; // 이미 찾은 요소는 제외
+        const prevSibling = input.previousElementSibling;
+        if (prevSibling && prevSibling.tagName.toLowerCase() === "label") {
+            const labelText = prevSibling.textContent?.trim() || "";
+            const matches = options?.exact ? labelText === text : labelText.includes(text);
+            if (matches) {
+                results.push(input);
+            }
+        }
+        // 같은 컨테이너 내 label
+        const parent = input.parentElement;
+        if (parent && !results.includes(input)) {
+            const labelInParent = parent.querySelector("label");
+            if (labelInParent && labelInParent !== prevSibling) {
+                const labelText = labelInParent.textContent?.trim() || "";
+                const matches = options?.exact ? labelText === text : labelText.includes(text);
+                if (matches) {
+                    results.push(input);
+                }
+            }
+        }
+    }
+    return results;
+}
+/**
+ * 요소가 화면에 보이는지 확인 - HTMLElement와 SVGElement 모두 지원
  */
 function isVisible(element) {
     // BODY와 HTML은 항상 visible로 간주
@@ -349,11 +603,12 @@ function isVisible(element) {
     return true;
 }
 /**
- * 요소가 상호작용 가능한지 확인 (enabled + visible)
+ * 요소가 상호작용 가능한지 확인 (enabled + visible) - HTMLElement와 SVGElement 모두 지원
  */
 export function isInteractable(element) {
     if (!isVisible(element))
         return false;
+    // HTMLElement의 disabled 체크
     if (element instanceof HTMLInputElement ||
         element instanceof HTMLTextAreaElement ||
         element instanceof HTMLSelectElement ||
@@ -367,7 +622,7 @@ export function isInteractable(element) {
     return true;
 }
 /**
- * Smart waiting: 요소가 나타날 때까지 대기
+ * Smart waiting: 요소가 나타날 때까지 대기 - HTMLElement와 SVGElement 모두 지원
  */
 export async function waitForLocator(locator, options) {
     const timeout = options?.timeout || 5000;

package/dist/selectors/selectorGenerator.d.ts

@@ -36,13 +36,13 @@ export declare function makeSelector(el: HTMLElement): string;
  */
 export declare function isValidSelector(selector: string): boolean;
 /**
- * Selector로 단일 요소 찾기 (안전)
+ * Selector로 단일 요소 찾기 (안전) - HTMLElement와 SVGElement 모두 지원
  */
-export declare function querySelector(selector: string): HTMLElement | null;
+export declare function querySelector(selector: string): HTMLElement | SVGElement | null;
 /**
- * Selector로 여러 요소 찾기 (안전)
+ * Selector로 여러 요소 찾기 (안전) - HTMLElement와 SVGElement 모두 지원
  */
-export declare function querySelectorAll(selector: string): HTMLElement[];
+export declare function querySelectorAll(selector: string): (HTMLElement | SVGElement)[];
 /**
  * Robust한 다중 selector 생성 (Playwright/Maestro 스타일)
  */

package/dist/selectors/selectorGenerator.js

@@ -20,6 +20,23 @@
  * Tier 4 (텍스트 기반):
  * - 텍스트 내용 검색
  */
+/**
+ * CSS-in-JS 클래스 간단 체크 (getSimpleSelector용)
+ */
+function isUnstableClass(className) {
+    // CSS-in-JS 패턴들
+    if (/^css-[a-z0-9]+$/i.test(className))
+        return true;
+    if (/^sc-[a-zA-Z0-9]+$/.test(className))
+        return true;
+    if (/^_[a-zA-Z0-9_]+$/.test(className))
+        return true;
+    if (/[0-9a-f]{8,}/i.test(className))
+        return true;
+    if (/^chakra-/.test(className))
+        return true;
+    return false;
+}
 /**
  * 단순 selector 생성 (빠른 선택용)
  * ID가 있으면 ID만 사용, 없으면 전체 경로 생성
@@ -27,18 +44,21 @@
 export function getSimpleSelector(el) {
     if (!(el instanceof Element))
         return "";
-    if (el.id)
+    if (el.id && !el.id.match(/[0-9a-f]{8,}/i))
         return `#${CSS.escape(el.id)}`;
     const parts = [];
     let node = el;
     while (node && node.nodeType === 1 && parts.length < 5) {
         let part = node.tagName.toLowerCase();
         if (node.classList.length > 0) {
-            const cls = Array.from(node.classList)
-                .slice(0, 2)
-                .map((c) => `.${CSS.escape(c)}`)
-                .join("");
-            part += cls;
+            // CSS-in-JS 클래스 제외
+            const stableClasses = Array.from(node.classList)
+                .filter((c) => !isUnstableClass(c))
+                .slice(0, 2);
+            if (stableClasses.length > 0) {
+                const cls = stableClasses.map((c) => `.${CSS.escape(c)}`).join("");
+                part += cls;
+            }
         }
         // nth-child
         let idx = 1;
@@ -103,12 +123,15 @@ export function isValidSelector(selector) {
     }
 }
 /**
- * Selector로 단일 요소 찾기 (안전)
+ * Selector로 단일 요소 찾기 (안전) - HTMLElement와 SVGElement 모두 지원
  */
 export function querySelector(selector) {
     try {
         const el = document.querySelector(selector);
-        return el instanceof HTMLElement ? el : null;
+        if (el instanceof HTMLElement || el instanceof SVGElement) {
+            return el;
+        }
+        return null;
     }
     catch (error) {
         console.error(`Invalid selector: ${selector}`, error);
@@ -116,12 +139,12 @@ export function querySelector(selector) {
     }
 }
 /**
- * Selector로 여러 요소 찾기 (안전)
+ * Selector로 여러 요소 찾기 (안전) - HTMLElement와 SVGElement 모두 지원
  */
 export function querySelectorAll(selector) {
     try {
         const elements = document.querySelectorAll(selector);
-        return Array.from(elements).filter((el) => el instanceof HTMLElement);
+        return Array.from(elements).filter((el) => el instanceof HTMLElement || el instanceof SVGElement);
     }
     catch (error) {
         console.error(`Invalid selector: ${selector}`, error);
@@ -191,6 +214,29 @@ function getTestId(element) {
         element.getAttribute("data-test-id") ||
         null);
 }
+/**
+ * CSS-in-JS 라이브러리가 생성한 클래스인지 확인
+ */
+function isCssInJsClass(className) {
+    // Emotion: css-xxxx, css-1abc2de
+    if (/^css-[a-z0-9]+$/i.test(className))
+        return true;
+    // Styled-components: sc-xxx, StyledXxx
+    if (/^sc-[a-zA-Z0-9]+$/.test(className))
+        return true;
+    // CSS Modules: _xxx_hash, Component_class__hash
+    if (/^_[a-zA-Z0-9_]+$/.test(className))
+        return true;
+    if (/^[A-Z][a-zA-Z]+_[a-zA-Z]+__[a-zA-Z0-9]+$/.test(className))
+        return true;
+    // Random hashes (8+ hex chars)
+    if (/[0-9a-f]{8,}/i.test(className))
+        return true;
+    // Chakra UI: chakra-xxx
+    if (/^chakra-/.test(className))
+        return true;
+    return false;
+}
 /**
  * CSS 클래스 기반 selector 생성 (고유한 클래스 우선)
  */
@@ -198,8 +244,8 @@ function generateClassSelector(element) {
     const classes = Array.from(element.classList);
     if (classes.length === 0)
         return null;
-    // 고유해 보이는 클래스 우선 (숫자나 해시가 없는 것)
-    const stableClasses = classes.filter((c) => !c.match(/[0-9a-f]{8,}/) && !c.startsWith("_"));
+    // CSS-in-JS 클래스 제외, 안정적인 클래스만 사용
+    const stableClasses = classes.filter((c) => !isCssInJsClass(c));
     if (stableClasses.length > 0) {
         // 최대 2개 클래스 사용
         const selectedClasses = stableClasses.slice(0, 2);
@@ -207,6 +253,93 @@ function generateClassSelector(element) {
     }
     return null;
 }
+/**
+ * Input 요소와 연결된 label 텍스트 가져오기
+ * 다양한 label 연결 방식 지원:
+ * 1. label[for="id"] - 명시적 연결
+ * 2. 부모 label - 암시적 연결
+ * 3. aria-labelledby - ARIA 연결
+ * 4. 이전 형제 label - div > label + input 구조
+ * 5. 같은 컨테이너 내 label - div 내 첫 번째 label
+ */
+function getAssociatedLabelText(element) {
+    // 1. label[for="id"] 방식 (명시적 연결)
+    if (element.id) {
+        const label = document.querySelector(`label[for="${CSS.escape(element.id)}"]`);
+        if (label)
+            return label.textContent?.trim() || null;
+    }
+    // 2. 부모 label 방식 (암시적 연결)
+    const parentLabel = element.closest("label");
+    if (parentLabel) {
+        // input 자체의 텍스트는 제외하고 label 텍스트만 추출
+        const clone = parentLabel.cloneNode(true);
+        const input = clone.querySelector("input, textarea, select");
+        if (input)
+            input.remove();
+        const text = clone.textContent?.trim();
+        if (text)
+            return text;
+    }
+    // 3. aria-labelledby 방식
+    const labelledby = element.getAttribute("aria-labelledby");
+    if (labelledby) {
+        const labelEl = document.getElementById(labelledby);
+        if (labelEl)
+            return labelEl.textContent?.trim() || null;
+    }
+    // 4. 이전 형제 label 탐지 (div > label + input 구조)
+    const prevSibling = element.previousElementSibling;
+    if (prevSibling && prevSibling.tagName.toLowerCase() === "label") {
+        return prevSibling.textContent?.trim() || null;
+    }
+    // 5. 같은 컨테이너(div) 내 첫 번째 label
+    const parent = element.parentElement;
+    if (parent) {
+        const labelInParent = parent.querySelector("label");
+        if (labelInParent) {
+            // 해당 label이 다른 input과 연결되어 있지 않은지 확인
+            const forAttr = labelInParent.getAttribute("for");
+            if (!forAttr || forAttr === element.id) {
+                return labelInParent.textContent?.trim() || null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Form 내에서의 위치 정보 가져오기
+ */
+function getFormContext(element) {
+    const form = element.closest("form");
+    if (!form)
+        return null;
+    // Form의 selector 생성 (id, name, 또는 구조적)
+    let formSelector = "";
+    if (form.id && !form.id.match(/[0-9a-f]{8,}/i)) {
+        formSelector = `#${CSS.escape(form.id)}`;
+    }
+    else if (form.getAttribute("name")) {
+        formSelector = `form[name="${form.getAttribute("name")}"]`;
+    }
+    else {
+        // form의 클래스 기반 selector 시도
+        const formClassSelector = generateClassSelector(form);
+        if (formClassSelector) {
+            formSelector = formClassSelector;
+        }
+        else {
+            // 여러 form이 있을 경우 구조적 selector
+            const forms = document.querySelectorAll("form");
+            const index = Array.from(forms).indexOf(form);
+            formSelector = `form:nth-of-type(${index + 1})`;
+        }
+    }
+    // Form 내에서 모든 input/textarea/select 요소 중 순서 계산
+    const allFormFields = form.querySelectorAll("input, textarea, select");
+    const fieldIndex = Array.from(allFormFields).indexOf(element) + 1;
+    return { formSelector, fieldIndex };
+}
 /**
  * Robust한 다중 selector 생성 (Playwright/Maestro 스타일)
  */
@@ -265,6 +398,25 @@ export function generateRobustLocator(element) {
     if (element instanceof HTMLImageElement && element.alt) {
         selectors.push(`img[alt="${element.alt}"]`);
     }
+    // === Form Input 특화: Label 텍스트 및 Form Context ===
+    if (element instanceof HTMLInputElement ||
+        element instanceof HTMLTextAreaElement ||
+        element instanceof HTMLSelectElement) {
+        // Label 텍스트 추출
+        const labelText = getAssociatedLabelText(element);
+        if (labelText) {
+            metadata.labelText = labelText;
+        }
+        // Form 내 위치 정보
+        const formContext = getFormContext(element);
+        if (formContext) {
+            metadata.formContext = formContext;
+            // Form context 기반 selector 추가 (fallback용)
+            selectors.push(`${formContext.formSelector} :nth-child(${formContext.fieldIndex}) input, ` +
+                `${formContext.formSelector} :nth-child(${formContext.fieldIndex}) textarea, ` +
+                `${formContext.formSelector} :nth-child(${formContext.fieldIndex}) select`);
+        }
+    }
     // === Tier 3: 구조적 selector ===
     // 클래스 기반
     const classSelector = generateClassSelector(element);

package/dist/steps/stepExecution.d.ts

@@ -1,4 +1,4 @@
-import type { Step } from "@auto-wiz/core";
+import type { Step, RunnerOptions } from "@auto-wiz/core";
 /**
  * Step execution 유틸리티
  * 각 Step 타입별 실행 로직
@@ -19,7 +19,7 @@ export declare function executeClickStep(step: Step): Promise<ExecutionResult>;
 /**
  * Type step 실행
  */
-export declare function executeTypeStep(step: Step): Promise<ExecutionResult>;
+export declare function executeTypeStep(step: Step, options?: RunnerOptions): Promise<ExecutionResult>;
 /**
  * Select step 실행
  */
@@ -32,7 +32,11 @@ export declare function executeExtractStep(step: Step): Promise<ExecutionResult>
  * WaitFor step 실행
  */
 export declare function executeWaitForStep(step: Step): Promise<ExecutionResult>;
+/**
+ * Keyboard step 실행
+ */
+export declare function executeKeyboardStep(step: Step): Promise<ExecutionResult>;
 /**
  * Step 실행 (타입에 따라 자동 분기)
  */
-export declare function executeStep(step: Step): Promise<ExecutionResult>;
+export declare function executeStep(step: Step, options?: RunnerOptions): Promise<ExecutionResult>;

package/dist/steps/stepExecution.js

@@ -1,6 +1,6 @@
 import { waitForLocator, isInteractable } from "../selectors/locatorUtils";
 /**
- * Step에서 요소 찾기 (locator 시스템 사용)
+ * Step에서 요소 찾기 (locator 시스템 사용) - HTMLElement와 SVGElement 모두 지원
  */
 async function findElement(step) {
     if (!("locator" in step) || !step.locator) {
@@ -41,7 +41,19 @@ export async function executeClickStep(step) {
         };
     }
     try {
-        element.click();
+        // HTMLElement는 click() 메서드 사용, SVGElement는 dispatchEvent 사용
+        if (element instanceof HTMLElement) {
+            element.click();
+        }
+        else {
+            // SVGElement doesn't have click(), use dispatchEvent
+            const clickEvent = new MouseEvent("click", {
+                bubbles: true,
+                cancelable: true,
+                view: window,
+            });
+            element.dispatchEvent(clickEvent);
+        }
         return { success: true, usedSelector };
     }
     catch (error) {
@@ -52,10 +64,18 @@ export async function executeClickStep(step) {
         };
     }
 }
+/**
+ * Resolve placeholders in text (e.g., {{username}} → variables.username)
+ */
+function resolveText(text, variables) {
+    if (!variables || !text)
+        return text;
+    return text.replace(/\{\{(\w+)\}\}/g, (_, key) => variables[key] ?? "");
+}
 /**
  * Type step 실행
  */
-export async function executeTypeStep(step) {
+export async function executeTypeStep(step, options = {}) {
     if (step.type !== "type") {
         return { success: false, error: "Invalid type step" };
     }
@@ -81,7 +101,8 @@ export async function executeTypeStep(step) {
         };
     }
     try {
-        const text = step.originalText || step.text || "";
+        const rawText = step.originalText || step.text || "";
+        const text = resolveText(rawText, options.variables);
         element.value = text;
         element.dispatchEvent(new Event("input", { bubbles: true }));
         element.dispatchEvent(new Event("change", { bubbles: true }));
@@ -250,16 +271,106 @@ export async function executeWaitForStep(step) {
         };
     }
 }
+/**
+ * Keyboard step 실행
+ */
+export async function executeKeyboardStep(step) {
+    if (step.type !== "keyboard") {
+        return { success: false, error: "Invalid keyboard step" };
+    }
+    const key = step.key;
+    if (!key) {
+        return { success: false, error: "Keyboard step requires key" };
+    }
+    try {
+        // locator가 있으면 해당 요소에 포커스 후 키 이벤트 발생
+        let targetElement = document.activeElement;
+        let usedSelector = "activeElement";
+        if ("locator" in step && step.locator) {
+            const { element, usedSelector: selector } = await findElement(step);
+            if (element) {
+                targetElement = element;
+                usedSelector = selector;
+                // HTMLElement만 focus() 메서드 지원
+                if (element instanceof HTMLElement) {
+                    element.focus();
+                }
+            }
+        }
+        if (!targetElement) {
+            targetElement = document.body;
+            usedSelector = "body";
+        }
+        // 키보드 이벤트 발생
+        const keyCode = getKeyCode(key);
+        targetElement.dispatchEvent(new KeyboardEvent("keydown", {
+            key,
+            code: key === "Enter" ? "Enter" : key,
+            keyCode,
+            which: keyCode,
+            bubbles: true,
+            cancelable: true,
+        }));
+        // Enter 키인 경우 폼 제출 시도
+        if (key === "Enter") {
+            const activeEl = document.activeElement;
+            if (activeEl instanceof HTMLInputElement || activeEl instanceof HTMLTextAreaElement) {
+                const form = activeEl.form;
+                if (form) {
+                    if (typeof form.requestSubmit === "function") {
+                        form.requestSubmit();
+                    }
+                    else {
+                        form.submit();
+                    }
+                }
+            }
+        }
+        targetElement.dispatchEvent(new KeyboardEvent("keyup", {
+            key,
+            code: key === "Enter" ? "Enter" : key,
+            keyCode,
+            which: keyCode,
+            bubbles: true,
+            cancelable: true,
+        }));
+        return { success: true, usedSelector };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to execute keyboard step: ${error.message}`,
+        };
+    }
+}
+/**
+ * 키 이름을 keyCode로 변환
+ */
+function getKeyCode(key) {
+    const keyCodes = {
+        Enter: 13,
+        Tab: 9,
+        Escape: 27,
+        Backspace: 8,
+        Delete: 46,
+        ArrowUp: 38,
+        ArrowDown: 40,
+        ArrowLeft: 37,
+        ArrowRight: 39,
+        Space: 32,
+    };
+    return keyCodes[key] || key.charCodeAt(0);
+}
 /**
  * Step 실행 (타입에 따라 자동 분기)
  */
-export async function executeStep(step) {
+export async function executeStep(step, options = {}) {
     try {
         switch (step.type) {
             case "click":
                 return await executeClickStep(step);
             case "type":
-                return await executeTypeStep(step);
+                return await executeTypeStep(step, options);
             case "select":
                 return await executeSelectStep(step);
             case "extract":
@@ -269,6 +380,11 @@ export async function executeStep(step) {
             case "navigate":
                 // navigate는 background에서 처리
                 return { success: true };
+            case "keyboard":
+                return await executeKeyboardStep(step);
+            case "waitForNavigation":
+                // waitForNavigation은 background에서 처리
+                return { success: true };
             default:
                 return { success: false, error: `Unknown step type: ${step.type}` };
         }
@@ -295,7 +411,7 @@ function formatXml(xml) {
     // <[^>]+> : 태그
     // [^<]+ : 텍스트
     const tags = xml.match(/<[^>]+>|[^<]+/g) || [];
-    tags.forEach(tag => {
+    tags.forEach((tag) => {
         // 닫는 태그 </... >
         if (tag.match(/^<\//)) {
             indent = Math.max(0, indent - 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auto-wiz/dom",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "license": "MIT",
   "author": "JaeSang",
   "repository": {
@@ -23,7 +23,7 @@
     }
   },
   "dependencies": {
-    "@auto-wiz/core": "1.2.0"
+    "@auto-wiz/core": "1.2.3"
   },
   "devDependencies": {
     "typescript": "^5.0.0"