Selector Forge

어떤 페이지에서든 요소를 선택하면, AI가 생성하고 판단하며, 사용자가 확인하기 전에 실제 DOM을 통해 재검증된 신뢰할 수 있는 셀렉터를 얻을 수 있습니다.

Selector Forge는 여러분이 보고 있는 페이지에서 직접 견고한 CSS 또는 XPath 셀렉터를 구축할 수 있도록 돕는 독립형 브라우저 확장 프로그램 (Chrome & Firefox, MV3)입니다. 원하는 것을 가리키기만 하면, 확장 프로그램과 Intuned의 셀렉터 백엔드(backend)가 나머지 작업을 수행합니다. 즉, 후보군을 제안하고, 실제 페이지를 대상으로 테스트하며, 올바르게 해결되지 않는 것은 모두 폐기합니다.

이 도구는 엔드 투 엔드 테스트 (end-to-end tests) 작성, 스크래퍼 (scrapers) 구축, 그리고 취약한 셀렉터가 나중에 문제를 일으킬 수 있는 모든 페이지 자동화에 유용합니다.

설치 (Install)

• Chrome — Chrome Web Store
• Firefox — Firefox Add-ons

작동 방식 (How it works)

1. 아무 페이지나 열고 확장 프로그램을 클릭합니다.
2. **선택 모드 (selection mode)**를 선택하고 실제 페이지에서 요소(element)를 직접 선택합니다.
3. 확장 프로그램은 선택한 항목(선택된 대상, DOM 컨텍스트, 시드 후보군)의 압축된 스냅샷을 캡처하여 백엔드(backend)로 전송합니다.
4. 백엔드는 후보 셀렉터를 제안하고 순위를 매기며, 확장 프로그램은 모든 후보를 실제 DOM을 대상으로 테스트하여 그 결과를 다시 전달합니다.
5. 백엔드가 최종 승자를 결정할 때까지 이 루프가 반복됩니다.
6. 팝업에는 재검증된 (re-verified) 셀렉터만 표시되며, 각 셀렉터에는 복사 버튼이 포함되어 있습니다.

브라우저는 셀렉터가 실제로 무엇과 일치하는지에 대한 항상 유일한 진실의 원천 (source of truth)입니다. AI는 제안하고 순위를 매길 뿐이며, 정확성에 대한 최종 결정권을 갖지는 않습니다.

신뢰 경계 (The trust boundary)

• 확장 프로그램은 셀렉터 생성 세션 상태(session state)를 보유하며, 이는 루프(loop)의 연속성을 위한 소스 역할을 합니다.
• 브라우저는 신뢰할 수 있는 유일한 원천(source of truth)입니다. 모든 결과에 대해 재검증(re-verification)이 필수적입니다.
• AI는 셀렉터를 제안하고 순위를 매길 뿐이며, 정확성을 증명하지는 않습니다.
• 리스트(List)의 경우, 검증 과정에서 의도된 전체 세트를 확인하므로, 과잉 매칭(over-matching)되거나 과소 매칭(under-matching)되는 셀렉터는 거부됩니다.

모듈 맵(module map), 메시징 레이어(messaging layer), 백그라운드/콘텐츠/팝업 컨텍스트(background/content/popup contexts), 그리고 인증(auth) + CLI 접점(seams)에 대한 내용은 ARCHITECTURE.md를 참조하세요.

선택 모드 (Selection modes)

모드 (Mode)	사용자가 하는 일	얻게 되는 결과
Single	요소 하나를 선택	해당 정확한 요소에 대해 검증된 셀렉터 후보 — 버튼, 입력창, 링크, 레이블, 일회성 대상.
List	반복되는 세트에서 두 가지 예시를 선택	저장하기 전에 미리 볼 수 있는, 전체 세트에 대한 검증된 컨테이너 셀렉터.

개발 퀵스타트 (Dev quickstart)

Node 18 이상 및 Yarn이 필요합니다.

yarn install         # `wxt prepare`도 함께 실행됩니다
yarn dev             # watch 모드 + Chrome에서 .output/chrome-mv3를 로드 (unpacked) 
yarn dev:firefox     # Firefox의 경우도 동일함

첫 번째 yarn dev 실행 후, chrome://extensions에서 .output/chrome-mv3에 있는 언팩된(unpacked) 확장 프로그램을 로드하세요 (개발자 모드 활성화 필요).

명령어 (Commands)

명령어	기능
yarn dev / yarn dev:firefox	빌드 감시(watch), 언팩된 확장 프로그램으로 로드 가능
...

컴포넌트 미리보기 (Ladle)

yarn ladle는 디자인 및 검토를 위해 팝업의 React 컴포넌트들을 격리된 환경에서 제공합니다. 확장 프로그램을 다시 로드하거나 실제 백엔드가 필요하지 않습니다. Stories는 stories/ (*.stories.tsx)에 위치하며, Ladle 설정은 .ladle/에 있습니다. 팝업은 WXT가 주입하는 browser 전역 객체를 필요로 하므로, .ladle/wxt-globals.ts에서 이를 위한 no-op 스텁(stub)을 설치합니다. yarn ladle:build는 dist/ladle 아래에 정적 번들(static bundle)을 생성합니다.

테스트 계층 (Testing layers)

• 단위 테스트 (Unit) — 셀렉터 로직, 상태 변환 (state transforms), 스토리지, 그리고 결정론적 폴백 (deterministic fallbacks)을 위한 빠른 Vitest 테스트 (node/happy-dom).
• 브라우저 테스트 (Browser) — 실제 DOM을 대상으로 셀렉터 생성을 실행하여 각 후보가 정확히 예상된 요소 세트로 해결되는지 증명하는 Vitest 브라우저 모드 테스트입니다. 이것이 정답지 (correctness oracle) 역할을 합니다. 두 계층 모두 yarn test로 실행됩니다.
• E2E (End-to-End) — 실제 페이지, 포인터 흐름 (pointer flow), 팝업, 컨텐트 스크립트 (content script), 그리고 백그라운드 워커 (background worker)가 포함된 패키징된 MV3 확장 프로그램을 대상으로 Playwright를 사용하여 수행합니다. yarn e2e로 실행합니다.

프로젝트 레이아웃 (Project layout)

entrypoints/
  background.ts     백그라운드 서비스 워커 (background service worker) — 세션 상태, 에이전트 루프, 네트워크 I/O
  content.ts        컨텐트 스크립트 (content script) — 피커 오버레이 (picker overlay), DOM 접근, 셀렉터 테스트
...

WXT를 기반으로 구축되었으며, 팝업에는 React를 사용합니다.

로드맵 (Roadmap)

• CLI 제어 (CLI control) — Intuned CLI를 통해 확장 프로그램을 제어합니다: Intuned IDE 지원, 엔드 투 엔드 (end-to-end) 테스트 및 자동화를 실행하는 로컬 에이전트, 그리고 MCP를 통한 노출을 포함합니다. (기초적인 배선 — tabs 권한 및 CDP 기반 세션 시작 — 은 이미 준비되어 있습니다.)
• 스마트 피커 (Smart picker) — 한 번의 흐름 내에서 여러 요소를 선택하면 확장 프로그램이 이를 단일 항목이나 리스트 형태의 세트로 그룹화하는 multiple 모드, 그리고 페이지에 유용한 필드, 이름 및 셀렉터를 자동으로 제안하는 AI 필드 감지 기능을 제공합니다.
• 드릴다운 모드 (Drill-down modes) — 선택 후 정밀한 정제: 실제로 의도한 요소로 XPath/DOM 트리를 따라 이동하고 (자식 span → button → row → label → 부모 컨테이너), 리스트 선택을 부모 또는 자식 레벨로 이동하며, 필수 예시를 추가하거나 잘못된 예시를 제외합니다.
• 자체 백엔드 사용 (Bring your own backend) — 현재 확장 프로그램은 인증 및 셀렉터 생성을 위해 Intuned과 통신합니다. 우리는 해당 접점에 끼워 넣어 Intuned을 완전히 대체할 수 있는, 소규모의 셀프 호스팅 가능한 레퍼런스 백엔드를 출시할 계획입니다. 여기에는 신뢰할 수 있는 셀렉터를 생성하고 판단하는 오픈 소스 에이전트가 포함되어, 사용자가 자신의 인프라에서 전체 루프를 실행할 수 있도록 할 것입니다.

향후 계획: 셀렉터/자동화 히스토리, Playwright 또는 순수 JavaScript로의 내보내기, 자동 페이지네이션 감지, 그리고 cross-iframe / shadow-DOM 지원.

기여하기 (Contributing)

이슈(Issues)와 풀 리퀘스트(pull requests)를 환영합니다. PR을 열기 전에 yarn compile과 yarn test를 실행해 주세요.

라이선스 (License)

MIT © The Metrics Shop, Inc.