waggle-os/apps/browser-ext/README.md

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.