# oil-oil/selector architecture

> Architecture diagram of the GitHub repository oil-oil/selector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oil-oil/selector
- Repository: https://github.com/oil-oil/selector

## Overview

#### 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`.

Main entry points: [`src/core.js`](https://github.com/oil-oil/selector/blob/main/src/core.js) (Editor orchestrator), [`src/export.js`](https://github.com/oil-oil/selector/blob/main/src/export.js) (Export service), [`src/selection.js`](https://github.com/oil-oil/selector/blob/main/src/selection.js) (Selection engine), [`src/ui.js`](https://github.com/oil-oil/selector/blob/main/src/ui.js) (Overlay UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Build & delivery"]
  node_install["Install page<br/>HTML entry<br/>[index.html]"]
  node_build{{"Bookmarklet builder<br/>build script<br/>[build.js]"}}
  node_deploy["GitHub Pages deploy<br/>CI workflow<br/>[deploy.yml]"]
  node_styles["Editor stylesheet<br/>in-page CSS<br/>[editor.css]"]
  node_bookmarklet["Injected payload<br/>bookmarklet artifact"]
end

subgraph group_runtime["Injected editor runtime"]
  node_core{{"Editor orchestrator<br/>runtime controller<br/>[core.js]"}}
  node_selection["Selection engine<br/>DOM selection<br/>[selection.js]"]
  node_ui["Overlay UI<br/>page overlay<br/>[ui.js]"]
  node_context["Context extractor<br/>DOM metadata<br/>[context.js]"]
  node_prompt["Prompt formatter<br/>prompt generation<br/>[prompt.js]"]
  node_export["Export service<br/>browser integration<br/>[export.js]"]
  node_hostdom["Inspected page DOM<br/>host-page boundary"]
  node_clipboard["Clipboard &amp; downloads<br/>browser APIs"]
end

subgraph group_reporting["Sharingan reporting"]
  node_sharingan["Sharingan reporter<br/>replication report pipeline<br/>[sharingan.js]"]
end

node_build -->|"assembles"| node_bookmarklet
node_styles -->|"bundled into"| node_build
node_bookmarklet -->|"activates"| node_core
node_install -->|"installs"| node_bookmarklet
node_deploy -->|"publishes"| node_install
node_core -->|"coordinates"| node_selection
node_selection -->|"selects targets from"| node_hostdom
node_core -->|"drives"| node_ui
node_ui -->|"uses"| node_styles
node_ui -.->|"overlays"| node_hostdom
node_selection -->|"passes selected nodes"| node_context
node_context -->|"supplies facts"| node_prompt
node_prompt -->|"formats output for"| node_export
node_core -->|"coordinates export"| node_export
node_export -->|"writes or downloads"| node_clipboard
node_core -->|"invokes reporting"| node_sharingan
node_sharingan -->|"captures page evidence"| node_hostdom
node_sharingan -->|"routes report output"| node_export

click node_install "https://github.com/oil-oil/selector/blob/main/index.html"
click node_build "https://github.com/oil-oil/selector/blob/main/scripts/build.js"
click node_deploy "https://github.com/oil-oil/selector/blob/main/.github/workflows/deploy.yml"
click node_styles "https://github.com/oil-oil/selector/blob/main/assets/editor.css"
click node_core "https://github.com/oil-oil/selector/blob/main/src/core.js"
click node_selection "https://github.com/oil-oil/selector/blob/main/src/selection.js"
click node_ui "https://github.com/oil-oil/selector/blob/main/src/ui.js"
click node_context "https://github.com/oil-oil/selector/blob/main/src/context.js"
click node_prompt "https://github.com/oil-oil/selector/blob/main/src/prompt.js"
click node_export "https://github.com/oil-oil/selector/blob/main/src/export.js"
click node_sharingan "https://github.com/oil-oil/selector/blob/main/src/sharingan.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_install,node_build,node_deploy,node_styles,node_bookmarklet toneBlue
class node_core,node_selection,node_ui,node_context,node_prompt,node_export,node_hostdom,node_clipboard toneAmber
class node_sharingan toneMint
```

## Components

### Build & delivery

- [Install page](https://github.com/oil-oil/selector/blob/main/index.html): HTML entry · Bookmarklet installation surface. · `index.html`
- [Bookmarklet builder](https://github.com/oil-oil/selector/blob/main/scripts/build.js): build script · Assembles the distributable injected payload. · `scripts/build.js`
- [GitHub Pages deploy](https://github.com/oil-oil/selector/blob/main/.github/workflows/deploy.yml): CI workflow · Deploys main-branch output. · `.github/workflows/deploy.yml`
- [Editor stylesheet](https://github.com/oil-oil/selector/blob/main/assets/editor.css): in-page CSS · Isolated styling for Selector UI. · `assets/editor.css`
- **Injected payload**: bookmarklet artifact · Client-side code injected into arbitrary host pages.

### Injected editor runtime

Runs inside the inspected page.

- [Editor orchestrator](https://github.com/oil-oil/selector/blob/main/src/core.js): runtime controller · Owns lifecycle, keyboard handling, and cross-module coordination. · `src/core.js`
- [Selection engine](https://github.com/oil-oil/selector/blob/main/src/selection.js): DOM selection · Click, marquee, traversal, and ordered selection behavior. · `src/selection.js`
- [Overlay UI](https://github.com/oil-oil/selector/blob/main/src/ui.js): page overlay · Renders highlights, controls, settings, and annotations. · `src/ui.js`
- [Context extractor](https://github.com/oil-oil/selector/blob/main/src/context.js): DOM metadata · Derives locators, semantics, React details, and route context. · `src/context.js`
- [Prompt formatter](https://github.com/oil-oil/selector/blob/main/src/prompt.js): prompt generation · Combines instructions with extracted selection facts. · `src/prompt.js`
- [Export service](https://github.com/oil-oil/selector/blob/main/src/export.js): browser integration · Produces clipboard text, Markdown, screenshots, and downloads. · `src/export.js`
- **Inspected page DOM**: host-page boundary · Arbitrary page content kept separate from Selector overlay UI.
- **Clipboard & downloads**: browser APIs · Receives prompts and small reports; PNG and large reports download.

### Sharingan reporting

- [Sharingan reporter](https://github.com/oil-oil/selector/blob/main/src/sharingan.js): replication report pipeline · Captures high-fidelity DOM, style, asset, and React-fiber evidence. · `src/sharingan.js`

## Connections

- Bookmarklet builder → Injected payload: assembles
- Editor stylesheet → Bookmarklet builder: bundled into
- Injected payload → Editor orchestrator: activates
- Install page → Injected payload: installs
- GitHub Pages deploy → Install page: publishes
- Editor orchestrator → Selection engine: coordinates
- Selection engine → Inspected page DOM: selects targets from
- Editor orchestrator → Overlay UI: drives
- Overlay UI → Editor stylesheet: uses
- Overlay UI → Inspected page DOM: overlays
- Selection engine → Context extractor: passes selected nodes
- Context extractor → Prompt formatter: supplies facts
- Prompt formatter → Export service: formats output for
- Editor orchestrator → Export service: coordinates export
- Export service → Clipboard & downloads: writes or downloads
- Editor orchestrator → Sharingan reporter: invokes reporting
- Sharingan reporter → Inspected page DOM: captures page evidence
- Sharingan reporter → Export service: routes report output