{"id":51093514,"url":"https://github.com/Intuned/selector-forge","last_synced_at":"2026-07-12T08:01:01.697Z","repository":{"id":365934758,"uuid":"1271270944","full_name":"Intuned/selector-forge","owner":"Intuned","description":"Browser extension to create reliable selectors (CSS and Xpath) using AI","archived":false,"fork":false,"pushed_at":"2026-07-02T07:17:42.000Z","size":511,"stargazers_count":66,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T09:38:24.443Z","etag":null,"topics":["ai","chrome","css","extention","firefox","mx3","playwright","scraping","selector","testing","xpath"],"latest_commit_sha":null,"homepage":"https://selectorforge.ai/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Intuned.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T13:53:50.000Z","updated_at":"2026-07-02T07:17:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Intuned/selector-forge","commit_stats":null,"previous_names":["intuned/selector-forge"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Intuned/selector-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intuned%2Fselector-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intuned%2Fselector-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intuned%2Fselector-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intuned%2Fselector-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Intuned","download_url":"https://codeload.github.com/Intuned/selector-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Intuned%2Fselector-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35385772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","chrome","css","extention","firefox","mx3","playwright","scraping","selector","testing","xpath"],"created_at":"2026-06-24T04:00:42.100Z","updated_at":"2026-07-12T08:01:01.685Z","avatar_url":"https://github.com/Intuned.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Selector Forge\n\n\u003e Pick an element on any page, get back a **reliable** selector — generated and judged by AI, then re-verified against the live DOM before you ever see it.\n\nSelector Forge is a standalone browser extension (Chrome \u0026 Firefox, MV3) that helps you build robust CSS or XPath selectors directly from the pages you're looking at. You point at what you want; the extension and [Intuned](https://intuned.io)'s selector backend do the rest — proposing candidates, testing them against the real page, and discarding anything that doesn't resolve correctly.\n\nIt's useful for writing end-to-end tests, building scrapers, and automating any page where a brittle selector would cost you later.\n\n## Install\n\n- **Chrome** — [Chrome Web Store](https://chromewebstore.google.com/detail/selector-forge-ai-selecto/lbendfnlmhdakbeblajoffkfmafbfaha)\n- **Firefox** — [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/selector-forge/)\n\n## How it works\n\n1. Open any page and click the extension.\n2. Choose a **selection mode** and pick element(s) directly on the live page.\n3. The extension captures a compact snapshot of your picks (selected targets, DOM context, seed candidates) and sends it to the backend.\n4. The backend proposes and ranks candidate selectors; the extension **tests every candidate against the live DOM** and feeds the results back.\n5. This loop repeats until the backend settles on a winner.\n6. The popup shows only **re-verified** selectors, each with a copy button.\n\nThe browser is always the source of truth for what a selector actually matches. The AI proposes and ranks; it never gets the final word on correctness.\n\n### The trust boundary\n\n- The extension holds the selector-creation session state — the source of continuity for the loop.\n- The browser is the source of truth — re-verification is mandatory for every result.\n- The AI proposes and ranks selectors; it does not prove correctness.\n- For lists, verification checks the **full** intended set, so over-matching and under-matching selectors are rejected.\n\nSee [ARCHITECTURE.md](./ARCHITECTURE.md) for the module map, the messaging layer, the background/content/popup contexts, and the auth + CLI seams.\n\n## Selection modes\n\n| Mode       | You do                                 | You get                                                                                                |\n| ---------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------ |\n| **Single** | Pick one element                       | Verified selector candidates for that exact element — buttons, inputs, links, labels, one-off targets. |\n| **List**   | Pick two examples from a repeating set | A verified container selector for the full set, previewed before you save it.                          |\n\n## Dev quickstart\n\nRequires Node 18+ and Yarn.\n\n```bash\nyarn install         # also runs `wxt prepare`\nyarn dev             # watch + load .output/chrome-mv3 in Chrome (unpacked)\nyarn dev:firefox     # same for Firefox\n```\n\nAfter the first `yarn dev`, load the unpacked extension from `.output/chrome-mv3` at `chrome://extensions` (enable Developer mode).\n\n## Commands\n\n| Command                             | What it does                                                        |\n| ----------------------------------- | ------------------------------------------------------------------- |\n| `yarn dev` / `yarn dev:firefox`     | Watch build, loadable as an unpacked extension                      |\n| `yarn compile`                      | `tsc --noEmit` typecheck                                            |\n| `yarn test`                         | Vitest — unit + real-Chromium browser projects                      |\n| `yarn build` / `yarn build:firefox` | Production extension bundle                                         |\n| `yarn build:e2e`                    | E2E variant with `\u003call_urls\u003e` host permission — **never ship this** |\n| `yarn e2e`                          | `build:e2e` then Playwright against the packaged extension          |\n| `yarn zip` / `yarn zip:firefox`     | Store-ready zip                                                     |\n| `yarn icons`                        | Regenerate icon assets                                              |\n| `yarn ladle`                        | Preview popup components in isolation at `http://localhost:61010`    |\n\n### Component previews (Ladle)\n\n`yarn ladle` serves the popup's React components in isolation for design and review — no extension reload, no real backend. Stories live in [stories/](./stories) (`*.stories.tsx`); Ladle config is in [.ladle/](./.ladle). The popup expects WXT's injected `browser` global, so [.ladle/wxt-globals.ts](./.ladle/wxt-globals.ts) installs a no-op stub for it. `yarn ladle:build` produces a static bundle under `dist/ladle`.\n\n### Testing layers\n\n- **Unit** — fast Vitest tests (node/happy-dom) for selector logic, state transforms, storage, and deterministic fallbacks.\n- **Browser** — Vitest browser-mode tests that run selector generation against a real DOM and prove each candidate resolves to exactly the expected element set. This is the correctness oracle. Both layers run under `yarn test`.\n- **E2E** — Playwright against the packaged MV3 extension with a real page, pointer flow, popup, content script, and background worker. Run with `yarn e2e`.\n\n## Project layout\n\n```\nentrypoints/\n  background.ts     background service worker — session state, agent loop, network I/O\n  content.ts        content script — picker overlay, DOM access, selector testing\n  popup/            React popup — mode controls, results, copy actions\nlib/\n  agent/            agent loop controller (backend turn-taking)\n  content/          picker overlay, element registry, DOM inspection\n  background/       handlers, context menu, session wiring, CLI bridge\n  messaging/        typed, direction-partitioned runtime-message protocol\n  state/            session state, history, schema, preferences\n  auth/             auth client + token handling\n  graphql/          workspace + usage queries\n  config.ts         API base + runtime config\ntests/              vitest (unit + browser)\ne2e/                playwright against the built extension\nARCHITECTURE.md     module map, trust boundary, agent loop, seams\n```\n\nBuilt on [WXT](https://wxt.dev) with React for the popup.\n\n## Roadmap\n\n- **CLI control** — drive the extension from the Intuned CLI: Intuned IDE support, local agents running end-to-end tests and automations, and exposure through MCP. (Foundational wiring — the `tabs` permission and CDP-driven session start — is already in place.)\n- **Smart picker** — a `multiple` mode that lets you select many elements in one flow and have the extension group them into single items and list-like sets, plus AI field detection that suggests useful fields, names, and selectors for a page automatically.\n- **Drill-down modes** — precision refinement after a pick: walk the XPath/DOM tree to the element you actually meant (child span → button → row → label → parent container), move a list selection to a parent or child level, and add required examples or exclude wrong ones.\n- **Bring your own backend** — today the extension talks to Intuned for authentication and selector generation. We plan to ship a small, self-hostable reference backend that drops into that seam and replaces Intuned entirely — including an open-source agent that generates and judges reliable selectors — so you can run the whole loop on your own infrastructure.\n\nFurther out: selector/automation history, export to Playwright or plain JavaScript, automatic pagination detection, and cross-iframe / shadow-DOM support.\n\n## Contributing\n\nIssues and pull requests are welcome. Please run `yarn compile` and `yarn test` before opening a PR.\n\n## License\n\n[MIT](./LICENSE) © The Metrics Shop, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntuned%2Fselector-forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIntuned%2Fselector-forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntuned%2Fselector-forge/lists"}