oil-oil/selector

Purpose and delivery model

Selector is a client-side bookmarklet for inspecting arbitrary web pages and producing structured context for AI coding assistants. It injects an editor payload and stylesheet into the active page; no backend or remote data service is involved. The install surface is index.html, while the shipped bookmarklet payload is assembled by scripts/build.js.

Build and deployment pipeline

The build script combines the editor source fragments, Sharingan reporting logic, and in-page styles into a distributable bookmarklet/install-page artifact. GitHub Pages deployment is automated from the main branch through .github/workflows/deploy.yml. Key paths: scripts/build.js, index.html, assets/editor.css.

Injection runtime and editor lifecycle

The injected runtime owns activation, teardown, pause/resume behavior, keyboard handling, and cross-module state. It runs in the host page’s browser context, so its primary boundary is between Selector-owned overlay/UI DOM and inspected page DOM. Core orchestration is centered in src/core.js, with shared state/context in src/context.js.

Element selection and navigation

Selection supports direct click, additive Shift-click, drag marquee, undo, and keyboard traversal across parent/child/sibling relationships. This stage translates page DOM targets into an ordered selection model while avoiding interference from Selector’s own UI. Primary implementation paths: src/selection.js, src/core.js.

In-page UI and annotations

The overlay UI renders highlights, controls, selection state, settings, and per-element instructions. It is styled independently so the host page can be inspected without adopting its visual system. Relevant paths: src/ui.js, assets/editor.css, src/prompt.js.

Context extraction and prompt generation

For each selected node, Selector derives compact facts such as readable names, stable selectors/locators, semantic containment, React metadata, filtered props, and page route/query context. It then formats the multi-element prompt and combines user instructions with extracted facts for clipboard output. Key paths: src/context.js, src/prompt.js, src/export.js.

Export boundary: clipboard, Markdown, screenshots

Export logic converts selected context into AI-ready prompt text, selected content Markdown, or screenshots. Clipboard APIs are the main integration; screenshot-plus-text mode also downloads a PNG and references it in the copied prompt. This is isolated in src/export.js, coordinated by src/core.js.

Sharingan high-fidelity reporting

Sharingan mode is a specialized replication-report pipeline. It captures document and viewport context, sanitized DOM, computed-style differences, matching CSS rules, fonts, animations, pseudo-elements, assets, SVG references, and React fiber details. Small Markdown reports use the clipboard; large ones are downloaded. Its substantial implementation is src/sharingan.js, invoked through the main editor/export flow in src/core.js and src/export.js.