quickSnote

AGENTS.md

@@ -82,3 +82,52 @@ snotes/
   app needs internet access on first editor load (or vendor these locally later).
 - `notes.py` opens a new `aiosqlite` connection per operation (same pattern as
   `tasky`); fine for a small personal corpus, not for hot paths.
+
+## Browser extension (browser-extension/)
+
+A Firefox MV3 "quick capture" extension — mirrors the pve-max extension pattern.
+No backend changes: it reuses `GET /api/users` and `POST/PUT /api/notes`.
+
+```
+browser-extension/
+  manifest.json        # MV3, gecko id snotes-capture@schmeeve.com
+  background.js        # Relays fetch() to snotes API (credentials:'include')
+  content.js           # postMessage ping/pong + settings handshake; get_context msg
+  popup.html/js/css    # Capture form: textarea, user select, Save, Page button
+  options.html/js      # Server URL config (auto-filled via ping/pong)
+  release-firefox.sh   # Package + --sign; copies .xpi to static/
+  icons/               # 48px + 96px PNGs (from assets/snotes-favicon.png)
+```
+
+### How it works
+
+1. **Content script** runs on all pages. It answers `snotes-ping` → `snotes-pong`
+   and `snotes-settings` → writes `serverUrl` to `browser.storage.sync`, plus a
+   `get_context` message returning the page's selected text, title, and URL.
+2. **Popup** prefills the note from the active tab's selection, lists users via
+   `list_users`, and Save creates (`POST`) then updates (`PUT`) via `save_note`.
+   A **Page** button inserts `[title](url)`; the note **autosaves 8s** after the
+   last keystroke.
+3. **Helper page** — the SPA's "Capture" view (`showTools()` in `static/app.js`)
+   pings the extension, offers one-click install from
+   `/static/snotes-capture-firefox.xpi`, and sends `snotes-settings` with
+   `location.origin` to auto-configure.
+
+### Install / release
+
+```bash
+# Manual dev install: about:debugging → Load Temporary Add-on → manifest.json
+bash browser-extension/release-firefox.sh            # package .zip only
+bash browser-extension/release-firefox.sh --sign     # sign via AMO (auto-bumps version)
+```
+
+The signed `.xpi` is copied to `static/snotes-capture-firefox.xpi` (git-tracked)
+so the helper page serves it. Signing needs `AMO_JWT_ISSUER` / `AMO_JWT_SECRET`
+and `npm install -g web-ext`.
+
+### Gotchas
+
+- The extension's `fetch` uses `credentials:'include'`, so on remote hosts it
+  only works if the user has already logged into snotes in that browser (the
+  `snotes_auth` cookie is reused). On LAN no auth is needed.
+- `dist/` is gitignored; committed artifact lives in `static/` instead.