@auto-wiz/dom 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./selectors/selectorGenerator";
+export * from "./selectors/locatorUtils";
+export * from "./steps/stepExecution";
+export * from "./runner";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./selectors/selectorGenerator";
+export * from "./selectors/locatorUtils";
+export * from "./steps/stepExecution";
+export * from "./runner";
+// stepValidation might still belong in core if it's pure logic, but checking dependencies...

package/dist/runner.d.ts

@@ -0,0 +1,6 @@
+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>;
+}

package/dist/runner.js

@@ -0,0 +1,45 @@
+import { executeStep } from "./steps/stepExecution";
+export class DomFlowRunner {
+    async run(flow, _context = {}, // unused
+    _options = {} // unused
+    ) {
+        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);
+                if (!result.success) {
+                    return {
+                        success: false,
+                        error: result.error,
+                        failedStepIndex: i,
+                        extractedData,
+                    };
+                }
+                if (result.extractedData) {
+                    extractedData[`step_${i}`] = result.extractedData;
+                }
+            }
+            catch (e) {
+                return {
+                    success: false,
+                    error: e.message,
+                    failedStepIndex: i,
+                    extractedData,
+                };
+            }
+        }
+        return { success: true, extractedData };
+    }
+    async runStep(step) {
+        try {
+            // Direct DOM execution using existing logic
+            const result = await executeStep(step);
+            return result;
+        }
+        catch (error) {
+            return { success: false, error: error.message };
+        }
+    }
+}

package/dist/selectors/locatorUtils.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Locator 유틸리티 - 고급 요소 검색 기능
+ * Playwright/Maestro 스타일의 텍스트 기반, role 기반 매칭
+ */
+import type { ElementLocator } from "@auto-wiz/core";
+/**
+ * Role로 요소 찾기 (ARIA role)
+ */
+export declare function findByRole(role: string, options?: {
+    name?: string;
+    exact?: boolean;
+    level?: number;
+}): HTMLElement[];
+/**
+ * 텍스트로 찾기 (공백/대소문자 무시)
+ */
+export declare function findByCleanText(text: string): HTMLElement[];
+/**
+ * 텍스트로 찾기 (부분 일치)
+ */
+export declare function findByFuzzyText(text: string): HTMLElement[];
+/**
+ * 텍스트로 요소 찾기 (Playwright 스타일)
+ */
+export declare function findByText(text: string, options?: {
+    exact?: boolean;
+    normalize?: boolean;
+    selector?: string;
+    role?: string;
+}): HTMLElement[];
+/**
+ * Placeholder로 요소 찾기
+ */
+export declare function findByPlaceholder(text: string, options?: {
+    exact?: boolean;
+}): HTMLElement[];
+/**
+ * Label로 요소 찾기 (form inputs)
+ */
+export declare function findByLabelText(text: string, options?: {
+    exact?: boolean;
+}): HTMLElement[];
+/**
+ * TestID로 요소 찾기
+ */
+export declare function findByTestId(testId: string): HTMLElement | null;
+/**
+ * ElementLocator로 요소 찾기 (fallback 지원)
+ *
+ * Primary selector부터 시도하고, 실패하면 fallback들을 순차적으로 시도
+ */
+export declare function findByLocator(locator: ElementLocator): HTMLElement | null;
+/**
+ * 요소가 상호작용 가능한지 확인 (enabled + visible)
+ */
+export declare function isInteractable(element: HTMLElement): boolean;
+/**
+ * Smart waiting: 요소가 나타날 때까지 대기
+ */
+export declare function waitForLocator(locator: ElementLocator, options?: {
+    timeout?: number;
+    visible?: boolean;
+    interactable?: boolean;
+}): Promise<HTMLElement>;

package/dist/selectors/locatorUtils.js

@@ -0,0 +1,394 @@
+/**
+ * Locator 유틸리티 - 고급 요소 검색 기능
+ * Playwright/Maestro 스타일의 텍스트 기반, role 기반 매칭
+ */
+/**
+ * 텍스트 정규화 (공백, 대소문자 무시)
+ */
+function normalizeText(text) {
+    return text
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * 요소의 접근 가능한 이름(accessible name) 계산
+ * ARIA 명세에 따른 우선순위
+ */
+function getAccessibleName(element) {
+    // 1. aria-label
+    const ariaLabel = element.getAttribute("aria-label");
+    if (ariaLabel)
+        return ariaLabel;
+    // 2. aria-labelledby
+    const labelledby = element.getAttribute("aria-labelledby");
+    if (labelledby) {
+        const labelEl = document.getElementById(labelledby);
+        if (labelEl)
+            return labelEl.textContent?.trim() || "";
+    }
+    // 3. label 요소 (form controls)
+    if (element instanceof HTMLInputElement ||
+        element instanceof HTMLTextAreaElement ||
+        element instanceof HTMLSelectElement) {
+        const id = element.id;
+        if (id) {
+            const label = document.querySelector(`label[for="${id}"]`);
+            if (label)
+                return label.textContent?.trim() || "";
+        }
+        // 부모 label
+        const parentLabel = element.closest("label");
+        if (parentLabel)
+            return parentLabel.textContent?.trim() || "";
+    }
+    // 4. alt (이미지)
+    if (element instanceof HTMLImageElement) {
+        return element.alt;
+    }
+    // 5. placeholder
+    const placeholder = element.getAttribute("placeholder");
+    if (placeholder)
+        return placeholder;
+    // 6. title
+    const title = element.getAttribute("title");
+    if (title)
+        return title;
+    // 7. 텍스트 내용
+    return element.textContent?.trim() || "";
+}
+/**
+ * Role로 요소 찾기 (ARIA role)
+ */
+export function findByRole(role, options) {
+    const allElements = Array.from(document.querySelectorAll("*"));
+    const results = [];
+    for (const el of allElements) {
+        if (!(el instanceof HTMLElement))
+            continue;
+        // Role 확인
+        const explicitRole = el.getAttribute("role");
+        const implicitRole = getImplicitRole(el);
+        const elementRole = explicitRole || implicitRole;
+        if (elementRole !== role)
+            continue;
+        // Level 확인 (heading용)
+        if (options?.level !== undefined) {
+            const tagName = el.tagName.toLowerCase();
+            const headingLevel = parseInt(tagName.charAt(1), 10);
+            if (headingLevel !== options.level)
+                continue;
+        }
+        // Name 확인
+        if (options?.name !== undefined) {
+            const accessibleName = getAccessibleName(el);
+            if (options.exact) {
+                if (accessibleName !== options.name)
+                    continue;
+            }
+            else {
+                if (!accessibleName.includes(options.name))
+                    continue;
+            }
+        }
+        results.push(el);
+    }
+    return results;
+}
+/**
+ * 텍스트로 찾기 (공백/대소문자 무시)
+ */
+export function findByCleanText(text) {
+    return findByText(text, { normalize: true });
+}
+/**
+ * 텍스트로 찾기 (부분 일치)
+ */
+export function findByFuzzyText(text) {
+    return findByText(text, { exact: false });
+}
+/**
+ * 암시적 ARIA role 추론
+ */
+function getImplicitRole(element) {
+    const tagName = element.tagName.toLowerCase();
+    const type = element.getAttribute("type");
+    const roleMap = {
+        a: element.hasAttribute("href") ? "link" : "",
+        button: "button",
+        input: type === "text" || !type ? "textbox" :
+            type === "checkbox" ? "checkbox" :
+                type === "radio" ? "radio" :
+                    type === "button" || type === "submit" ? "button" : "",
+        textarea: "textbox",
+        select: "combobox",
+        img: "img",
+        h1: "heading",
+        h2: "heading",
+        h3: "heading",
+        h4: "heading",
+        h5: "heading",
+        h6: "heading",
+        nav: "navigation",
+        main: "main",
+        aside: "complementary",
+        header: "banner",
+        footer: "contentinfo",
+        section: "region",
+        article: "article",
+        form: "form",
+        table: "table",
+        ul: "list",
+        ol: "list",
+        li: "listitem",
+    };
+    return roleMap[tagName] || null;
+}
+/**
+ * 텍스트로 요소 찾기 (Playwright 스타일)
+ */
+export function findByText(text, options) {
+    const container = options?.selector
+        ? document.querySelector(options.selector)
+        : document.body;
+    if (!container)
+        return [];
+    const allElements = Array.from(container.querySelectorAll("*"));
+    const results = [];
+    for (const el of allElements) {
+        if (!(el instanceof HTMLElement))
+            continue;
+        // Role 필터
+        if (options?.role) {
+            const elementRole = el.getAttribute("role") || getImplicitRole(el);
+            if (elementRole !== options.role)
+                continue;
+        }
+        // 텍스트 내용 가져오기
+        let elementText = getAccessibleName(el);
+        if (!elementText) {
+            elementText = el.textContent || "";
+        }
+        // 자식 요소의 텍스트는 제외 (직접 텍스트만)
+        if (el.children.length > 0) {
+            let directText = "";
+            for (const node of el.childNodes) {
+                if (node.nodeType === Node.TEXT_NODE) {
+                    directText += node.textContent || "";
+                }
+            }
+            if (directText.trim()) {
+                elementText = directText;
+            }
+        }
+        // 매칭
+        if (options?.normalize) {
+            if (normalizeText(elementText) === normalizeText(text)) {
+                results.push(el);
+            }
+        }
+        else if (options?.exact) {
+            if (elementText.trim() === text) {
+                results.push(el);
+            }
+        }
+        else {
+            if (elementText.includes(text)) {
+                results.push(el);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Placeholder로 요소 찾기
+ */
+export function findByPlaceholder(text, options) {
+    const selector = options?.exact
+        ? `[placeholder="${text}"]`
+        : `[placeholder*="${text}"]`;
+    return Array.from(document.querySelectorAll(selector)).filter((el) => el instanceof HTMLElement);
+}
+/**
+ * Label로 요소 찾기 (form inputs)
+ */
+export function findByLabelText(text, options) {
+    const labels = Array.from(document.querySelectorAll("label"));
+    const results = [];
+    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);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * TestID로 요소 찾기
+ */
+export function findByTestId(testId) {
+    const selectors = [
+        `[data-testid="${testId}"]`,
+        `[data-test="${testId}"]`,
+        `[data-cy="${testId}"]`,
+        `[data-test-id="${testId}"]`,
+    ];
+    for (const selector of selectors) {
+        const el = document.querySelector(selector);
+        if (el instanceof HTMLElement)
+            return el;
+    }
+    return null;
+}
+/**
+ * ElementLocator로 요소 찾기 (fallback 지원)
+ *
+ * Primary selector부터 시도하고, 실패하면 fallback들을 순차적으로 시도
+ */
+export function findByLocator(locator) {
+    // 1. Primary selector 시도
+    try {
+        const el = document.querySelector(locator.primary);
+        if (el instanceof HTMLElement && isVisible(el)) {
+            return el;
+        }
+    }
+    catch (error) {
+        console.warn(`Primary selector failed: ${locator.primary}`, error);
+    }
+    // 2. Fallback selectors 순차 시도
+    for (const selector of locator.fallbacks) {
+        try {
+            const el = document.querySelector(selector);
+            if (el instanceof HTMLElement && isVisible(el)) {
+                return el;
+            }
+        }
+        catch (error) {
+            console.warn(`Fallback selector failed: ${selector}`, error);
+        }
+    }
+    // 3. Metadata 기반 fuzzy matching
+    if (!locator.metadata)
+        return null;
+    // TestID로 시도
+    if (locator.metadata.testId) {
+        const el = findByTestId(locator.metadata.testId);
+        if (el && isVisible(el))
+            return el;
+    }
+    // 텍스트로 시도 (role 필터링)
+    if (locator.metadata.text) {
+        const elements = findByText(locator.metadata.text, {
+            normalize: true,
+            role: locator.metadata.role,
+        });
+        // tagName도 일치하는 것 우선
+        if (locator.metadata.tagName) {
+            const matchingTag = elements.find((el) => el.tagName.toLowerCase() === locator.metadata.tagName);
+            if (matchingTag)
+                return matchingTag;
+        }
+        if (elements.length > 0 && isVisible(elements[0])) {
+            return elements[0];
+        }
+    }
+    // Placeholder로 시도
+    if (locator.metadata.placeholder) {
+        const elements = findByPlaceholder(locator.metadata.placeholder, {
+            exact: true,
+        });
+        if (elements.length > 0 && isVisible(elements[0])) {
+            return elements[0];
+        }
+    }
+    // Label로 시도
+    if (locator.metadata.ariaLabel) {
+        const elements = findByLabelText(locator.metadata.ariaLabel, {
+            exact: true,
+        });
+        if (elements.length > 0 && isVisible(elements[0])) {
+            return elements[0];
+        }
+    }
+    return null;
+}
+/**
+ * 요소가 화면에 보이는지 확인
+ */
+function isVisible(element) {
+    // BODY와 HTML은 항상 visible로 간주
+    if (element.tagName === "BODY" || element.tagName === "HTML") {
+        return true;
+    }
+    const style = window.getComputedStyle(element);
+    if (style.display === "none" ||
+        style.visibility === "hidden" ||
+        style.opacity === "0") {
+        return false;
+    }
+    // offsetParent는 happy-dom에서 제대로 동작하지 않을 수 있음
+    // 위의 스타일 체크만으로 충분
+    return true;
+}
+/**
+ * 요소가 상호작용 가능한지 확인 (enabled + visible)
+ */
+export function isInteractable(element) {
+    if (!isVisible(element))
+        return false;
+    if (element instanceof HTMLInputElement ||
+        element instanceof HTMLTextAreaElement ||
+        element instanceof HTMLSelectElement ||
+        element instanceof HTMLButtonElement) {
+        if (element.disabled)
+            return false;
+    }
+    const style = window.getComputedStyle(element);
+    if (style.pointerEvents === "none")
+        return false;
+    return true;
+}
+/**
+ * Smart waiting: 요소가 나타날 때까지 대기
+ */
+export async function waitForLocator(locator, options) {
+    const timeout = options?.timeout || 5000;
+    const startTime = Date.now();
+    const pollInterval = 100;
+    while (Date.now() - startTime < timeout) {
+        const element = findByLocator(locator);
+        if (element) {
+            // visible 체크
+            if (options?.visible && !isVisible(element)) {
+                await new Promise((resolve) => setTimeout(resolve, pollInterval));
+                continue;
+            }
+            // interactable 체크
+            if (options?.interactable && !isInteractable(element)) {
+                await new Promise((resolve) => setTimeout(resolve, pollInterval));
+                continue;
+            }
+            return element;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    throw new Error(`Timeout waiting for element. Primary selector: ${locator.primary}`);
+}

package/dist/selectors/selectorGenerator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * CSS Selector 생성 유틸리티
+ *
+ * Playwright/Maestro 스타일의 다중 selector 전략:
+ *
+ * Tier 1 (가장 안정적):
+ * - data-testid, data-test, data-cy
+ * - id 속성
+ * - name 속성
+ * - ARIA labels
+ *
+ * Tier 2 (의미론적):
+ * - role + 텍스트
+ * - placeholder, title, alt
+ *
+ * Tier 3 (구조적):
+ * - CSS selector (class + structure)
+ * - nth-of-type
+ *
+ * Tier 4 (텍스트 기반):
+ * - 텍스트 내용 검색
+ */
+import type { ElementLocator } from "@auto-wiz/core";
+/**
+ * 단순 selector 생성 (빠른 선택용)
+ * ID가 있으면 ID만 사용, 없으면 전체 경로 생성
+ */
+export declare function getSimpleSelector(el: Element): string;
+/**
+ * 상세한 selector 생성 (안정성 우선)
+ * data-testid, aria-label 등 안정적인 속성 우선 사용
+ */
+export declare function makeSelector(el: HTMLElement): string;
+/**
+ * Selector가 유효한지 검증
+ */
+export declare function isValidSelector(selector: string): boolean;
+/**
+ * Selector로 단일 요소 찾기 (안전)
+ */
+export declare function querySelector(selector: string): HTMLElement | null;
+/**
+ * Selector로 여러 요소 찾기 (안전)
+ */
+export declare function querySelectorAll(selector: string): HTMLElement[];
+/**
+ * Robust한 다중 selector 생성 (Playwright/Maestro 스타일)
+ */
+export declare function generateRobustLocator(element: HTMLElement): ElementLocator;
+/**
+ * 단순 selector 생성 래퍼 (하위 호환성)
+ * @deprecated generateRobustLocator 사용 권장
+ */
+export declare function generateSelector(element: HTMLElement): string;

package/dist/selectors/selectorGenerator.js

@@ -0,0 +1,299 @@
+/**
+ * CSS Selector 생성 유틸리티
+ *
+ * Playwright/Maestro 스타일의 다중 selector 전략:
+ *
+ * Tier 1 (가장 안정적):
+ * - data-testid, data-test, data-cy
+ * - id 속성
+ * - name 속성
+ * - ARIA labels
+ *
+ * Tier 2 (의미론적):
+ * - role + 텍스트
+ * - placeholder, title, alt
+ *
+ * Tier 3 (구조적):
+ * - CSS selector (class + structure)
+ * - nth-of-type
+ *
+ * Tier 4 (텍스트 기반):
+ * - 텍스트 내용 검색
+ */
+/**
+ * 단순 selector 생성 (빠른 선택용)
+ * ID가 있으면 ID만 사용, 없으면 전체 경로 생성
+ */
+export function getSimpleSelector(el) {
+    if (!(el instanceof Element))
+        return "";
+    if (el.id)
+        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;
+        }
+        // nth-child
+        let idx = 1;
+        let sib = node;
+        while ((sib = sib.previousElementSibling)) {
+            if (sib && sib.tagName === node.tagName)
+                idx++;
+        }
+        part += `:nth-of-type(${idx})`;
+        parts.unshift(part);
+        node = node.parentElement;
+    }
+    return parts.join(" > ");
+}
+/**
+ * 상세한 selector 생성 (안정성 우선)
+ * data-testid, aria-label 등 안정적인 속성 우선 사용
+ */
+export function makeSelector(el) {
+    const segs = [];
+    let cur = el;
+    for (let depth = 0; cur && depth < 5; depth++) {
+        let s = cur.nodeName.toLowerCase();
+        const id = cur.id;
+        if (id) {
+            segs.unshift(`${s}#${CSS.escape(id)}`);
+            break;
+        }
+        const testid = cur.getAttribute("data-testid");
+        const aria = cur.getAttribute("aria-label");
+        if (testid) {
+            s += `[data-testid="${testid}"]`;
+        }
+        else if (aria) {
+            s += `[aria-label="${aria}"]`;
+        }
+        else {
+            const parent = cur.parentElement;
+            if (parent && cur) {
+                const currentNode = cur;
+                const same = Array.from(parent.children).filter((c) => c.nodeName === currentNode.nodeName);
+                if (same.length > 1) {
+                    s += `:nth-of-type(${same.indexOf(currentNode) + 1})`;
+                }
+            }
+        }
+        segs.unshift(s);
+        cur = cur.parentElement;
+    }
+    return segs.join(">");
+}
+/**
+ * Selector가 유효한지 검증
+ */
+export function isValidSelector(selector) {
+    try {
+        document.querySelector(selector);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Selector로 단일 요소 찾기 (안전)
+ */
+export function querySelector(selector) {
+    try {
+        const el = document.querySelector(selector);
+        return el instanceof HTMLElement ? el : null;
+    }
+    catch (error) {
+        console.error(`Invalid selector: ${selector}`, error);
+        return null;
+    }
+}
+/**
+ * Selector로 여러 요소 찾기 (안전)
+ */
+export function querySelectorAll(selector) {
+    try {
+        const elements = document.querySelectorAll(selector);
+        return Array.from(elements).filter((el) => el instanceof HTMLElement);
+    }
+    catch (error) {
+        console.error(`Invalid selector: ${selector}`, error);
+        return [];
+    }
+}
+/**
+ * ARIA role을 추론
+ */
+function inferRole(element) {
+    const tagName = element.tagName.toLowerCase();
+    const type = element.getAttribute("type");
+    // 명시적 role이 있으면 사용
+    const explicitRole = element.getAttribute("role");
+    if (explicitRole)
+        return explicitRole;
+    // 암시적 role 추론
+    const roleMap = {
+        button: "button",
+        a: "link",
+        input: type === "text" ? "textbox" : type || "textbox",
+        textarea: "textbox",
+        select: "combobox",
+        img: "img",
+        h1: "heading",
+        h2: "heading",
+        h3: "heading",
+        h4: "heading",
+        h5: "heading",
+        h6: "heading",
+    };
+    return roleMap[tagName] || null;
+}
+/**
+ * 요소의 가시 텍스트 추출 (trimmed)
+ */
+function getVisibleText(element) {
+    // input/textarea의 경우 value 또는 placeholder
+    if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+        return element.value || element.placeholder || "";
+    }
+    // 이미지의 경우 alt
+    if (element instanceof HTMLImageElement) {
+        return element.alt || "";
+    }
+    // 일반 텍스트 내용 (자식 요소는 제외하고 직접 텍스트만)
+    let text = "";
+    for (const node of element.childNodes) {
+        if (node.nodeType === Node.TEXT_NODE) {
+            text += node.textContent || "";
+        }
+    }
+    // 텍스트가 너무 길면 앞부분만 (50자)
+    text = text.trim();
+    if (text.length > 50) {
+        text = text.substring(0, 50);
+    }
+    return text;
+}
+/**
+ * Test ID 속성 찾기 (다양한 형태 지원)
+ */
+function getTestId(element) {
+    return (element.getAttribute("data-testid") ||
+        element.getAttribute("data-test") ||
+        element.getAttribute("data-cy") ||
+        element.getAttribute("data-test-id") ||
+        null);
+}
+/**
+ * CSS 클래스 기반 selector 생성 (고유한 클래스 우선)
+ */
+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("_"));
+    if (stableClasses.length > 0) {
+        // 최대 2개 클래스 사용
+        const selectedClasses = stableClasses.slice(0, 2);
+        return element.tagName.toLowerCase() + selectedClasses.map((c) => `.${CSS.escape(c)}`).join("");
+    }
+    return null;
+}
+/**
+ * Robust한 다중 selector 생성 (Playwright/Maestro 스타일)
+ */
+export function generateRobustLocator(element) {
+    const selectors = [];
+    const metadata = {
+        tagName: element.tagName.toLowerCase(),
+    };
+    // === Tier 1: 가장 안정적인 속성들 ===
+    // Test ID (최우선)
+    const testId = getTestId(element);
+    if (testId) {
+        selectors.push(`[data-testid="${testId}"]`);
+        metadata.testId = testId;
+    }
+    // ID 속성
+    if (element.id && !element.id.match(/[0-9a-f]{8,}/)) {
+        // 랜덤 해시가 아닌 의미있는 ID만
+        selectors.push(`#${CSS.escape(element.id)}`);
+    }
+    // Name 속성 (forms)
+    const name = element.getAttribute("name");
+    if (name) {
+        selectors.push(`${element.tagName.toLowerCase()}[name="${name}"]`);
+    }
+    // ARIA label
+    const ariaLabel = element.getAttribute("aria-label");
+    if (ariaLabel) {
+        selectors.push(`[aria-label="${ariaLabel}"]`);
+        metadata.ariaLabel = ariaLabel;
+    }
+    // === Tier 2: 의미론적 속성들 ===
+    const role = inferRole(element);
+    const text = getVisibleText(element);
+    if (role) {
+        metadata.role = role;
+    }
+    if (text) {
+        metadata.text = text;
+    }
+    // Placeholder (input/textarea)
+    const placeholder = element.getAttribute("placeholder");
+    if (placeholder) {
+        const tagName = element.tagName.toLowerCase();
+        selectors.push(`${tagName}[placeholder="${placeholder}"]`);
+        metadata.placeholder = placeholder;
+    }
+    // Title
+    const title = element.getAttribute("title");
+    if (title) {
+        const tagName = element.tagName.toLowerCase();
+        selectors.push(`${tagName}[title="${title}"]`);
+        metadata.title = title;
+    }
+    // Alt (이미지)
+    if (element instanceof HTMLImageElement && element.alt) {
+        selectors.push(`img[alt="${element.alt}"]`);
+    }
+    // === Tier 3: 구조적 selector ===
+    // 클래스 기반
+    const classSelector = generateClassSelector(element);
+    if (classSelector) {
+        selectors.push(classSelector);
+    }
+    // 기존 makeSelector 함수 사용 (구조 기반)
+    const structuralSelector = makeSelector(element);
+    if (structuralSelector) {
+        selectors.push(structuralSelector);
+    }
+    // === Tier 4: 폴백 - XPath (가장 정확하지만 취약) ===
+    // XPath는 마지막 수단으로만 사용
+    // (기존 XPath 생성 로직이 필요하다면 여기 추가)
+    // Primary는 첫 번째, 나머지는 fallback
+    const [primary, ...fallbacks] = selectors;
+    // 중복 제거
+    const uniqueFallbacks = Array.from(new Set(fallbacks));
+    return {
+        primary: primary || structuralSelector, // 최소한 구조 기반이라도
+        fallbacks: uniqueFallbacks,
+        metadata,
+    };
+}
+/**
+ * 단순 selector 생성 래퍼 (하위 호환성)
+ * @deprecated generateRobustLocator 사용 권장
+ */
+export function generateSelector(element) {
+    const locator = generateRobustLocator(element);
+    return locator.primary;
+}

package/dist/steps/stepExecution.d.ts

@@ -0,0 +1,39 @@
+import type { Step } from "@auto-wiz/core";
+/**
+ * Step execution 유틸리티
+ * 각 Step 타입별 실행 로직
+ *
+ * 새로운 locator 시스템 지원:
+ * - step.locator가 있으면 다중 selector fallback 사용
+ * - 없으면 기존 step.selector 사용 (하위 호환성)
+ */
+export interface ExecutionResult {
+    success: boolean;
+    error?: string;
+    extractedData?: any;
+    usedSelector?: string;
+}
+/**
+ * Click step 실행
+ */
+export declare function executeClickStep(step: Step): Promise<ExecutionResult>;
+/**
+ * Type step 실행
+ */
+export declare function executeTypeStep(step: Step): Promise<ExecutionResult>;
+/**
+ * Select step 실행
+ */
+export declare function executeSelectStep(step: Step): Promise<ExecutionResult>;
+/**
+ * Extract step 실행
+ */
+export declare function executeExtractStep(step: Step): Promise<ExecutionResult>;
+/**
+ * WaitFor step 실행
+ */
+export declare function executeWaitForStep(step: Step): Promise<ExecutionResult>;
+/**
+ * Step 실행 (타입에 따라 자동 분기)
+ */
+export declare function executeStep(step: Step): Promise<ExecutionResult>;

package/dist/steps/stepExecution.js

@@ -0,0 +1,285 @@
+import { querySelector } from "../selectors/selectorGenerator";
+import { waitForLocator, isInteractable } from "../selectors/locatorUtils";
+/**
+ * Step에서 요소 찾기 (locator 우선, fallback to selector)
+ */
+async function findElement(step) {
+    // 1. 새로운 locator 시스템 시도
+    if ("locator" in step && step.locator) {
+        try {
+            const element = await waitForLocator(step.locator, {
+                timeout: step.timeoutMs || 5000,
+                visible: true,
+                interactable: true,
+            });
+            return { element, usedSelector: step.locator.primary };
+        }
+        catch (error) {
+            // Locator로 찾지 못하면 selector로 폴백
+            console.warn("Locator failed, falling back to selector", error);
+        }
+    }
+    // 2. 기존 selector 사용 (하위 호환성)
+    if ("selector" in step && step.selector) {
+        const element = querySelector(step.selector);
+        return { element, usedSelector: step.selector };
+    }
+    return { element: null, usedSelector: "none" };
+}
+/**
+ * Click step 실행
+ */
+export async function executeClickStep(step) {
+    if (step.type !== "click") {
+        return { success: false, error: "Invalid click step" };
+    }
+    const { element, usedSelector } = await findElement(step);
+    if (!element) {
+        return {
+            success: false,
+            error: `Element not found with selector: ${usedSelector}`,
+        };
+    }
+    // 상호작용 가능 여부 확인
+    if (!isInteractable(element)) {
+        return {
+            success: false,
+            error: `Element is not interactable: ${usedSelector}`,
+        };
+    }
+    try {
+        element.click();
+        return { success: true, usedSelector };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to click element: ${error.message}`,
+            usedSelector,
+        };
+    }
+}
+/**
+ * Type step 실행
+ */
+export async function executeTypeStep(step) {
+    if (step.type !== "type") {
+        return { success: false, error: "Invalid type step" };
+    }
+    const { element, usedSelector } = await findElement(step);
+    if (!element) {
+        return {
+            success: false,
+            error: `Element not found with selector: ${usedSelector}`,
+        };
+    }
+    if (!(element instanceof HTMLInputElement) &&
+        !(element instanceof HTMLTextAreaElement)) {
+        return {
+            success: false,
+            error: "Element is not a text input",
+            usedSelector,
+        };
+    }
+    if (!isInteractable(element)) {
+        return {
+            success: false,
+            error: `Element is not interactable: ${usedSelector}`,
+        };
+    }
+    try {
+        const text = step.originalText || step.text || "";
+        element.value = text;
+        element.dispatchEvent(new Event("input", { bubbles: true }));
+        element.dispatchEvent(new Event("change", { bubbles: true }));
+        // Submit 플래그가 있으면 Enter 키 입력
+        if (step.submit) {
+            const form = element.form;
+            if (form) {
+                // 폼이 있으면 submit
+                if (typeof form.requestSubmit === "function") {
+                    form.requestSubmit();
+                }
+                else {
+                    form.submit();
+                }
+            }
+            else {
+                // 폼이 없으면 Enter 키 이벤트 발생
+                element.dispatchEvent(new KeyboardEvent("keydown", {
+                    key: "Enter",
+                    code: "Enter",
+                    keyCode: 13,
+                    which: 13,
+                    bubbles: true,
+                    cancelable: true,
+                }));
+            }
+        }
+        return { success: true, usedSelector };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to type into element: ${error.message}`,
+            usedSelector,
+        };
+    }
+}
+/**
+ * Select step 실행
+ */
+export async function executeSelectStep(step) {
+    if (step.type !== "select" || step.value === undefined) {
+        return { success: false, error: "Invalid select step" };
+    }
+    const { element, usedSelector } = await findElement(step);
+    if (!element) {
+        return {
+            success: false,
+            error: `Element not found with selector: ${usedSelector}`,
+        };
+    }
+    if (!(element instanceof HTMLSelectElement)) {
+        return {
+            success: false,
+            error: "Element is not a select element",
+            usedSelector,
+        };
+    }
+    if (!isInteractable(element)) {
+        return {
+            success: false,
+            error: `Element is not interactable: ${usedSelector}`,
+        };
+    }
+    try {
+        element.value = step.value;
+        element.dispatchEvent(new Event("change", { bubbles: true }));
+        return { success: true, usedSelector };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to select option: ${error.message}`,
+            usedSelector,
+        };
+    }
+}
+/**
+ * Extract step 실행
+ */
+export async function executeExtractStep(step) {
+    if (step.type !== "extract") {
+        return { success: false, error: "Invalid extract step" };
+    }
+    const { element, usedSelector } = await findElement(step);
+    if (!element) {
+        return {
+            success: false,
+            error: `Element not found with selector: ${usedSelector}`,
+        };
+    }
+    try {
+        let extractedData;
+        // prop에 따라 다른 데이터 추출 (기본값: innerText)
+        const prop = step.prop || "innerText";
+        if (prop === "value" && "value" in element) {
+            extractedData = element.value;
+        }
+        else if (prop === "innerText") {
+            extractedData = element.textContent?.trim() || "";
+        }
+        else {
+            extractedData = element.textContent?.trim() || "";
+        }
+        return { success: true, extractedData, usedSelector };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to extract data: ${error.message}`,
+            usedSelector,
+        };
+    }
+}
+/**
+ * WaitFor step 실행
+ */
+export async function executeWaitForStep(step) {
+    if (step.type !== "waitFor") {
+        return { success: false, error: "Invalid waitFor step" };
+    }
+    // 단순 timeout인 경우
+    if (!("selector" in step) && !("locator" in step) && step.timeoutMs) {
+        await new Promise((resolve) => setTimeout(resolve, step.timeoutMs));
+        return { success: true };
+    }
+    const timeout = step.timeoutMs || 5000; // 기본 5초
+    try {
+        // locator가 있으면 waitForLocator 사용 (자동 대기 기능)
+        if ("locator" in step && step.locator) {
+            await waitForLocator(step.locator, {
+                timeout,
+                visible: true,
+            });
+            return { success: true, usedSelector: step.locator.primary };
+        }
+        // selector가 있으면 기존 방식 (하위 호환성)
+        if ("selector" in step && step.selector) {
+            const startTime = Date.now();
+            const pollInterval = 100;
+            while (Date.now() - startTime < timeout) {
+                const element = querySelector(step.selector);
+                if (element) {
+                    return { success: true, usedSelector: step.selector };
+                }
+                await new Promise((resolve) => setTimeout(resolve, pollInterval));
+            }
+            return {
+                success: false,
+                error: `Timeout waiting for element: ${step.selector}`,
+            };
+        }
+        return {
+            success: false,
+            error: "WaitFor step requires selector, locator, or timeoutMs",
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `WaitFor failed: ${error.message}`,
+        };
+    }
+}
+/**
+ * Step 실행 (타입에 따라 자동 분기)
+ */
+export async function executeStep(step) {
+    try {
+        switch (step.type) {
+            case "click":
+                return await executeClickStep(step);
+            case "type":
+                return await executeTypeStep(step);
+            case "select":
+                return await executeSelectStep(step);
+            case "extract":
+                return await executeExtractStep(step);
+            case "waitFor":
+                return await executeWaitForStep(step);
+            case "navigate":
+                // navigate는 background에서 처리
+                return { success: true };
+            default:
+                return { success: false, error: `Unknown step type: ${step.type}` };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Step execution failed: ${error.message}`,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@auto-wiz/dom",
+  "version": "1.0.0",
+  "license": "MIT",
+  "author": "JaeSang",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JaeSang1998/automation-wizard.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@auto-wiz/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}