🛠️ Selector Forge: AI-Powered Resilient Selectors

Selector Forge is a sophisticated browser extension (supporting Chrome and Firefox via Manifest V3) designed to eliminate the headache of brittle fragile selectors. By leveraging AI and real-time DOM verification, it helps developers generate CSS and XPath selectors that actually last.

Whether you are crafting complex end-to-end (E2E) test suites, building a web scraper, or automating repetitive browser tasks, Selector Forge ensures your selectors are robust and reliable.

---

⚙️ How It Works

The tool operates on a continuous feedback loop between the user's browser and the Intuned backend.

The Operational Flow

1. Interaction: Open the extension on any webpage and select your target element(s).
2. Contextual Capture: The extension gathers a lean snapshot containing the target, the surrounding DOM context, and initial seed candidates.
3. AI Proposal: The backend generates and ranks potential selectors.
4. Live Validation: The extension tests every single proposal against the actual live page.
5. Delivery: Only selectors that are proven to work are presented to the user with a one-click copy button.

---

🛡️ The Trust Boundary

The core philosophy of Selector Forge is that the browser is the ultimate source of truth.

"The AI proposes and ranks; it never gets the final word on correctness."

To ensure absolute reliability, the system follows these constraints:

• Mandatory Re-verification: No selector is displayed unless it is verified against the live DOM.
• State Management: The extension maintains the session state to ensure continuity.
• Precision Matching: For list-based selections, the system rejects any selector that results in over-matching or under-matching.

Mathematically, a selector $S$ is only accepted if: $\text{Match}(S, \text{DOM}_{\text{live}}) = \text{TargetSet}$

---

🎯 Selection Modes

Mode	User Action	Result	Ideal Use Case
Single	Select one element	Verified candidates for that specific node	Buttons, inputs, unique labels
List	Select two examples from a set	A verified container selector for the entire group	Tables, product grids, repeating lists

---

💻 Development Guide

Getting Started

• yarn install (This also triggers wxt prepare)
• yarn dev (For Chrome) or yarn dev:firefox (For Firefox)
• Load the unpacked extension from .output/chrome-mv3 via chrome://extensions (Developer mode enabled).

Command Reference

Command	Purpose
yarn dev	Watch mode for unpacked extension development
yarn compile	Run tsc --noEmit for type checking
yarn test	Execute Vitest unit and browser-mode tests
yarn build	Create production-ready extension bundle
yarn build:e2e	Build variant with all_urls permissions (Internal use only)
yarn e2e	Run Playwright tests against the packaged extension
yarn zip	Generate store-ready .zip archives
yarn icons	Refresh icon assets
yarn ladle	Launch isolated component previews at http://localhost:61010

Component Previews (Ladle)

The popup's React components are developed in isolation using Ladle.

• Stories are located in stories/*.stories.tsx.
• Configuration is found in .ladle/.
• Since the popup relies on WXT globals, a no-op stub is provided in .ladle/wxt-globals.ts.

---

🧪 Testing Strategy

The project employs a three-tiered testing architecture:

1. Unit Tests: Fast Vitest tests (Node/happy-dom) focusing on selector logic and state transformations.
2. Browser Tests: Vitest browser-mode tests that validate candidates against a real DOM to ensure exact element set resolution.
3. E2E Tests: Full-scale Playwright tests covering the entire flow: Pointer $\rightarrow$ Popup $\rightarrow$ Content Script $\rightarrow$ Background Worker.

---

📂 Project Architecture

root/
├── entrypoints/      # Main execution contexts
│   ├── background.ts # Service worker: session state & network I/O
│   ├── content.ts    # Content script: picker overlay & DOM testing
│   └── popup/        # React UI: controls and results
├── lib/              # Core logic
│   ├── agent/        # Backend turn-taking controller
│   ├── content/      # Element registry & DOM inspection
│   ├── background/   # Context menus & CLI bridge
│   ├── messaging/    # Typed runtime-message protocol
│   ├── state/        # Schema, history, and preferences
│   ├── auth/         # Token handling & client
│   └── graphql/      # Workspace & usage queries
├── tests/            # Vitest (Unit + Browser)
└── e2e/              # Playwright suites

For a deeper dive into the messaging layer and auth seams, refer to ARCHITECTURE.md.