# mohamedaminehmm/spinneret architecture

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

- Interactive diagram: https://gitdiagram.com/mohamedaminehmm/spinneret
- Repository: https://github.com/mohamedaminehmm/spinneret

## Overview

Spinneret is a browser extension that reads a page locally, identifies salient phrases, and animates a procedural spider toward them. The main workflow is page text extraction and phrase scoring, optional on-device semantic reranking, then an idle patrol that highlights words under the spider’s feet. A dwell-based “Can I help?” prompt and toolbar/keyboard controls are additional user-facing capabilities. The excerpts show the reader, spider model, ranking, and message dispatch; some content-script details are omitted, so uncertain links are left out.

Main entry points: [`spider-extensiontransformer/content.js`](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/content.js) (Overlay and patrol), [`spider-extensiontransformer/background.js`](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/background.js) (Background dispatcher), [`spider-extensiontransformer/reader.js`](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/reader.js) (Text reader), [`spider-extensiontransformer/src/offscreen.js`](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/src/offscreen.js) (Offscreen model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_page["Page Understanding"]
  node_reader["Text reader<br/>[reader.js]"]
  node_phrase_scoring["Phrase scoring<br/>[reader.js]"]
end

subgraph group_model["Local Ranking"]
  node_offscreen_model["Offscreen model<br/>[offscreen.js]"]
  node_semantic_ranking["Semantic ranking<br/>[rank.js]"]
end

subgraph group_spider["Spider Experience"]
  node_on_page_overlay["Overlay and patrol<br/>[content.js]"]
  node_spider_motion["Spider motion model<br/>[spider.js]"]
  node_dwell_prompt["Dwell prompt<br/>[dwell.js]"]
  node_remembered_pages[("Dismissal memory<br/>[content.js]")]
end

subgraph group_extension["Extension Control"]
  node_background_dispatch["Background dispatcher<br/>[background.js]"]
end

node_user(("Page user"))
node_webpage["Web page"]
node_browser_runtime["Extension runtime"]

node_webpage -->|"reads text"| node_reader
node_reader -->|"scores phrases"| node_phrase_scoring
node_on_page_overlay -->|"requests phrases"| node_reader
node_on_page_overlay -->|"requests ranking"| node_background_dispatch
node_background_dispatch -->|"forwards request"| node_offscreen_model
node_offscreen_model -->|"computes scores"| node_semantic_ranking
node_on_page_overlay -->|"reranks phrases"| node_reader
node_on_page_overlay -->|"updates gait"| node_spider_motion
node_on_page_overlay -->|"highlights words"| node_webpage
node_user -->|"uses overlay"| node_on_page_overlay
node_user -->|"clicks toolbar"| node_background_dispatch
node_background_dispatch -->|"toggles overlay"| node_on_page_overlay
node_on_page_overlay -->|"tracks dwell"| node_dwell_prompt
node_on_page_overlay -->|"stores dismissals"| node_remembered_pages
node_browser_runtime -->|"hosts document"| node_offscreen_model

click node_reader "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/reader.js"
click node_phrase_scoring "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/reader.js"
click node_on_page_overlay "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/content.js"
click node_spider_motion "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/spider.js"
click node_dwell_prompt "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/dwell.js"
click node_remembered_pages "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/content.js"
click node_background_dispatch "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/background.js"
click node_offscreen_model "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/src/offscreen.js"
click node_semantic_ranking "https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/rank.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_reader,node_phrase_scoring,node_user toneBlue
class node_offscreen_model,node_semantic_ranking toneAmber
class node_on_page_overlay,node_spider_motion,node_dwell_prompt,node_remembered_pages toneMint
class node_background_dispatch toneRose
class node_webpage,node_browser_runtime toneIndigo
```

## Components

### Page Understanding

- [Text reader](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/reader.js): `spider-extensiontransformer/reader.js`
- [Phrase scoring](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/reader.js): `spider-extensiontransformer/reader.js`

### Local Ranking

- [Offscreen model](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/src/offscreen.js): `spider-extensiontransformer/src/offscreen.js`
- [Semantic ranking](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/rank.js): `spider-extensiontransformer/rank.js`

### Spider Experience

- [Overlay and patrol](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/content.js): `spider-extensiontransformer/content.js`
- [Spider motion model](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/spider.js): `spider-extensiontransformer/spider.js`
- [Dwell prompt](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/dwell.js): `spider-extensiontransformer/dwell.js`
- [Dismissal memory](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/content.js): `spider-extensiontransformer/content.js`

### Extension Control

- [Background dispatcher](https://github.com/mohamedaminehmm/spinneret/blob/main/spider-extensiontransformer/background.js): `spider-extensiontransformer/background.js`

### Other components

- **Page user**
- **Web page**
- **Extension runtime**

## Connections

- Web page → Text reader: reads text (evidence: `spider-extensiontransformer/reader.js`)
- Text reader → Phrase scoring: scores phrases (evidence: `spider-extensiontransformer/reader.js`)
- Overlay and patrol → Text reader: requests phrases (evidence: `spider-extensiontransformer/content.js`)
- Overlay and patrol → Background dispatcher: requests ranking (evidence: `spider-extensiontransformer/content.js`)
- Background dispatcher → Offscreen model: forwards request (evidence: `spider-extensiontransformer/background.js`)
- Offscreen model → Semantic ranking: computes scores (evidence: `spider-extensiontransformer/src/offscreen.js`)
- Overlay and patrol → Text reader: reranks phrases (evidence: `spider-extensiontransformer/reader.js`)
- Overlay and patrol → Spider motion model: updates gait (evidence: `spider-extensiontransformer/content.js`)
- Overlay and patrol → Web page: highlights words
- Page user → Overlay and patrol: uses overlay (evidence: `README.md`)
- Page user → Background dispatcher: clicks toolbar (evidence: `spider-extensiontransformer/background.js`)
- Background dispatcher → Overlay and patrol: toggles overlay (evidence: `spider-extensiontransformer/background.js`)
- Overlay and patrol → Dwell prompt: tracks dwell (evidence: `spider-extensiontransformer/content.js`)
- Overlay and patrol → Dismissal memory: stores dismissals (evidence: `spider-extensiontransformer/content.js`)
- Extension runtime → Offscreen model: hosts document
