67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# Waggle Companion - Chrome MV3 extension
|
|
|
|
Browser-side capture for Waggle OS. It saves a page selection or the current
|
|
page to personal Waggle memory without leaving the tab.
|
|
|
|
## What it does
|
|
|
|
- The popup shows connection status and the active memory destination.
|
|
- Save Selection and Save Page send personal imported-memory captures.
|
|
- The context menu can save selected text.
|
|
- Pairing is explicit: generate a one-time code in Waggle Settings, then enter
|
|
it in the popup. The code is single-use and expires after ten minutes.
|
|
|
|
The popup never makes network requests. The MV3 background worker redeems the
|
|
code and stores only the resulting scoped credential in
|
|
`chrome.storage.local.companionToken`. Legacy `sessionToken` values are deleted
|
|
and never trusted. A rejected credential is removed; captures are never replayed
|
|
or automatically re-paired.
|
|
|
|
## Load locally
|
|
|
|
1. Start Waggle with an extension allowlist:
|
|
- Development only: `WAGGLE_DEV_ALLOW_ANY_EXTENSION=1`
|
|
- Production-shaped: `WAGGLE_BROWSER_EXT_IDS=<extension-id>`
|
|
2. Open `chrome://extensions`, enable Developer mode, and choose Load unpacked.
|
|
3. Select this `apps/browser-ext` directory.
|
|
4. If using the production-shaped allowlist, copy the installed extension ID
|
|
into `WAGGLE_BROWSER_EXT_IDS` and restart Waggle.
|
|
5. In Waggle Settings -> Advanced, generate a Browser Companion code.
|
|
6. Enter that code in the extension popup.
|
|
|
|
Never enable `WAGGLE_DEV_ALLOW_ANY_EXTENSION` in a production build.
|
|
|
|
## Files
|
|
|
|
| File | Role |
|
|
|---|---|
|
|
| `manifest.json` | MV3 permissions, popup, content script, background worker |
|
|
| `popup.html` | Popup UI |
|
|
| `popup.js` | Pairing, health, and capture UI logic |
|
|
| `content.js` | On-demand selection and page extraction |
|
|
| `background.js` | Pairing and authenticated loopback requests |
|
|
|
|
## Sidecar contract
|
|
|
|
- `POST /api/browser-ext/pair` redeems an allowlisted extension's valid code.
|
|
- `GET /api/browser-ext/health` reports local connection and workspace state.
|
|
- `POST /api/memory/frames` accepts only `source: "import"`, personal scope,
|
|
and normal/low importance for the paired credential.
|
|
|
|
The global desktop session token is never exposed to the extension.
|
|
|
|
## Manual smoke test
|
|
|
|
1. Open the popup before pairing: it must show the code form and disable
|
|
authenticated capture.
|
|
2. Pair with a fresh Settings code: the popup must show Connected.
|
|
3. Save a selection and confirm a personal frame with source `import` appears.
|
|
4. Revoke in Settings: the next health/save request must require a new code and
|
|
must not retry the previous capture.
|
|
|
|
## Deferred
|
|
|
|
- Side-panel chat about the current page.
|
|
- Firefox-specific packaging.
|
|
- Reader-mode extraction and branded icons.
|