Migrate the browser-extension project to be the root

.claude/agents/corpus-fixer.md

@@ -4,7 +4,7 @@ description: Use this agent when you need to fix or improve the detection logic
 model: inherit
 ---
 
-You are an expert Gitcasso corpus debugging specialist with deep knowledge of browser extension development. You operate exclusively within the `browser-extension` directory and specialize in using the corpus:view development environment to diagnose and fix detection logic issues.
+You are an expert Gitcasso corpus debugging specialist with deep knowledge of browser extension development. You operate within the root project directory and specialize in using the corpus:view development environment to diagnose and fix detection logic issues.
 
 Your primary workflow:
 

.github/workflows/browser-extension.yml

@@ -21,9 +21,6 @@ jobs:
           node-version-file: '.nvmrc'
           cache: 'pnpm'
       - run: pnpm install --frozen-lockfile
-      - run: pnpm run biome
-        working-directory: browser-extension
       - run: pnpm test
-        working-directory: browser-extension
-      - run: pnpm run typecheck
-        working-directory: browser-extension
+      - run: pnpm biome
+      - run: pnpm typecheck

CONTRIBUTING.md

@@ -11,9 +11,111 @@ By submitting a Pull Request, you agree that your contributions are licensed und
 This extension ***must never transmit any data outside the browser***.
 
 - it adds syntax highlighting by running local scripts
-- it stores unfinished comments in local storage
+- it stores finished and unfinished comments in local storage
 - there is no need to initiate an outbound network request, no features will be added which require outbound network requests
 
-## How to
+## Developer quickstart
 
-- `browser-extension` is the primary project. Go to [its README.md](browser-extension/README.md) for development info.
+### Hotreload development
+
+- `pnpm install`
+- `pnpm dev`
+- open [`chrome://extensions`](chrome://extensions)
+- toggle **Developer mode** (top-right)
+- click "Load unpacked" (far left)
+  - `.output/chrome-mv3-dev`
+  - if you can't find `.output`, it's probably hidden, `command+shift+period` will show it
+- click the puzzle icon next to the url bar, then pin the Gitcasso icon
+
+### Testing and quality
+- `pnpm biome` - runs `biome check` (lint & formatting)
+- `pnpm biome:fix` - fixes most of what `biome check` finds
+- `pnpm typecheck` - typechecking
+- `pnpm test` - vitest
+- `pnpm test -u` - updates all snapshots
+
+## How it works
+
+This is a [WXT](https://wxt.dev/)-based browser extension that
+
+- finds `textarea` components and decorates them with [overtype](https://overtype.dev/) and [highlight.js](https://highlightjs.org/)
+- stores unposted comment drafts, and makes them easy to find via the extension popup
+
+### Entry points
+
+- [`src/entrypoints/content.ts`](src/entrypoints/content.ts) - injected into every webpage
+- [`src/entrypoints/background.ts`](src/entrypoints/background.ts) - service worker that manages state and handles messages
+- [`src/entrypoints/popup/popup.tsx`](src/entrypoints/popup/popup.tsx) - popup (react html + TailwindCSS)
+
+```mermaid
+graph TD
+    Content[Content Script<br/>content.ts] 
+    Background[Background Script<br/>background.ts]
+    Popup[Popup Script<br/>popup/popup.tsx]
+
+    Content -->|ENHANCED/DESTROYED<br/>CommentEvent| Background
+    Popup -->|GET_OPEN_SPOTS<br/>SWITCH_TO_TAB| Background
+    Background -->|GetOpenSpotsResponse<br/>spots array| Popup
+
+    Background -.->|manages| Storage[Comment State Storage<br/>openSpots JsonMap]
+    Content -.->|enhances| TextArea[textarea elements<br/>on web pages]
+    Popup -.->|displays| UI[Extension UI<br/>list of comment spots]
+
+    classDef entrypoint fill:#e1f5fe
+    classDef storage fill:#f3e5f5
+    classDef ui fill:#e8f5e8
+
+    class Content,Background,Popup entrypoint
+    class Storage storage
+    class TextArea,UI ui
+```
+
+Every time a `textarea` shows up on a page, on initial load or later on, it gets passed to a list of `CommentEnhancer`s. Each one gets a turn to say "I can enhance this box!". They show that they can enhance it by returning something non-null in the method `tryToEnhance(textarea: HTMLTextAreaElement): Spot | null`. Later on, that same `Spot` data will be used by the `tableRow(spot: Spot): ReactNode` method to create React components for rich formatting in the popup table.
+
+Those `Spot` values get bundled up with the `HTMLTextAreaElement` itself into an `EnhancedTextarea`, which gets added to the `TextareaRegistry`. At some interval, draft edits get saved by the browser extension.
+
+When the `textarea` gets removed from the page, the `TextareaRegistry` is notified so that the `CommentSpot` can be marked as abandoned or submitted as appropriate.
+
+## Testing
+
+- `pnpm playground` gives you a test environment where you can tinker with the popup with various test data, supports hot reload
+- `pnpm corpus:view` gives you recordings of various web pages which you can see with and without enhancement by the browser extension
+
+### Test Corpus
+
+We maintain a corpus of test pages in two formats for testing the browser extension:
+
+#### HAR Corpus (Automated)
+
+- For testing initial page loads and network requests
+- HAR recordings live in `tests/corpus/*.har`, complete recordings of the network requests of a single page load
+- You can add or change URLs in `tests/corpus/_corpus-index.ts`
+- **Recording new HAR files:**
+  - `npx playwright codegen https://github.com/login --save-storage=playwright/.auth/gh.json` will store new auth tokens
+    - login manually, then close the browser
+    - ***these cookies are very sensitive! we only run this script using a test account that has no permissions or memberships to anything, recommend you do the same!***
+  - `pnpm corpus:har:record` records new HAR files using those auth tokens (it needs args, run it with no args for docs)
+    - DO NOT COMMIT AND PUSH NEW OR CHANGED HAR files!
+    - we try to sanitize these (see `corpus-har-record.ts` for details) but there may be important PII in them
+    - if you need new HAR files for something, let us know and we will generate them ourselves using a dummy account
+    - IF YOUR PR CHANGES OR ADDS HAR FILES WE WILL CLOSE IT. Ask for HAR files and we'll be happy to generate clean ones you can test against.
+
+#### HTML Corpus (Manual)
+
+- For testing post-interaction states (e.g., expanded textareas, modal dialogs, dynamic content)
+- HTML snapshots live in `tests/corpus/*.html`, manually captured using SingleFile browser extension
+- All assets are inlined in a single HTML file by SingleFile
+- **Creating new HTML corpus files:**
+  1. Navigate to the desired page state (click buttons, expand textareas, etc.)
+  2. Use SingleFile browser extension to save the complete page
+  3. Save the `.html` file to `tests/corpus/html/` with a descriptive name
+  4. Add an entry to `tests/corpus/_corpus-index.ts` with `type: 'html'` and a description of the captured state
+  5. Feel free to contribute these if you want, but be mindful that they will be part of our immutable git history
+
+#### Viewing Corpus Files
+
+- Run `pnpm corpus:view` to start the test server at http://localhost:3001
+- Select any corpus file to view in two modes:
+  - **Clean**: Original page without extension
+  - **Gitcasso**: Page with extension injected for testing
+- Both HAR and HTML corpus types are supported

README.md

@@ -1,4 +1,4 @@
-# <img align="left" src="browser-extension/public/icons/icon-48.png"> Gitcasso
+# <img align="left" src="public/icons/icon-48.png"> Gitcasso
 
 *Syntax highlighting and autosave for comments on GitHub (and other other markdown-friendly websites).*