# Sidekick Browser Companion (Chrome Extension)

A local-developer Chrome (MV3) extension that pairs with the macOS
[Sidekick](../../..) app to capture pinned sections, console errors, and
network failures as structured evidence for Claude/Codex handoff.

The extension can be loaded unpacked for internal testing or packaged for the
Chrome Web Store under the WP Suites developer account. Internal packages keep
`manifest.key` so the load-unpacked extension ID is stable; Web Store packages
must use `dist/sidekick-chrome-webstore-v<version>.zip`, which removes that
development-only field. It talks to the bundled `sidekick-native-host` helper
binary via [Chrome native messaging][nm], which in turn forwards to the
running Sidekick.app over a Unix domain socket.

[nm]: https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging

## One-time install

1. **Build Sidekick** so the native-host helper exists:
   ```bash
   ./scripts/build.sh debug
   ```
   This produces `build/Sidekick.app/Contents/MacOS/sidekick-native-host`.

2. **Launch Sidekick.app** and keep it running. The Browser Companion
   listener starts automatically on app launch.

3. **Load the extension in Chrome**:
   - Open `chrome://extensions`.
   - Toggle on **Developer mode** (top-right).
   - Click **Load unpacked**.
   - Pick the folder this README lives in:
     `Sidekick/Resources/BrowserExtension/sidekick-chrome/`.
   - The internal build's manifest key pins the extension ID to
     `odcoeanpomepaolegpkhpnccohegamjk`.

4. **Register the native host manifest from Sidekick**:
   - Launch or relaunch Sidekick. It automatically registers the helper for
     the pinned internal extension ID.
   - If you installed a Web Store build or Chrome shows a different ID, click
     the **Browser** dot in Sidekick, choose **Install Chrome Helper…**, paste
     the ID from `chrome://extensions`, and click **Install**.

Sidekick will write
`~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.wpsuites.sidekick.browser_companion.json`
(and equivalent paths for Chromium, Edge, Brave, Arc if installed) so Chrome
can launch the helper binary on demand.

## Daily use

1. In Sidekick, click **Feedback** in the Capture section or **Capture
   Feedback** in the menu-bar menu. Sidekick starts a Feedback session and
   arms the companion controller.
2. In Chrome, click the **Sidekick** action icon to open the side panel.
3. During an active Feedback session, the side panel shows **Ready to
   capture** with the session ID.
4. Browse normally and click through the page. Normal page clicks are
   captured as browser-enriched feedback evidence: selector, bounds, visible
   text, curated computed styles, DOM context, viewport, a tab screenshot,
   and redacted `outerHTML` (password and hidden inputs are stripped before
   the payload leaves the page).
5. Use **Mark Section** only when you want to capture a non-clickable area
   without changing page state. Mark Section puts the page into selection
   mode (crosshair cursor, hover highlight) and captures the selected area as
   structured evidence.
6. Optional: click **Attach Console + Network** to subscribe via
   `chrome.debugger` to console messages and failed responses. Click
   **Detach Console + Network** when done so Chrome's debugger bar and state
   are released.
7. Click **Capture Viewport** to save a full-tab screenshot as evidence.
8. Stop the Sidekick session. `request.md` includes browser-enriched click
   evidence and any manual marks; raw artifacts are
   written under
   `~/Library/Application Support/Sidekick/sessions/<id>/browser/`.

## Privacy defaults

- All capture is gated on an active Sidekick Feedback session.
- Passive browser-click DOM capture runs only while the companion is armed by
  that active Feedback session.
- Mark Section DOM capture is user-triggered, never passive.
- `outerHTML` is capped to 40 KB and visible text to 4 KB per captured click
  or mark.
- `<input type="password">` values are stripped client-side; URLs have
  their query and fragment removed; common token/secret patterns are
  redacted server-side by `BrowserArtifactRedactor`.
- Network capture records metadata only (method, status, sanitized URL,
  timing, failure reason) — never request/response bodies, headers,
  cookies, or form values.
- Nothing is sent to a remote server; everything stays on the user's Mac.

## Troubleshooting

- **Side panel shows "Connection failed"** — Chrome could not start or reach
  the native messaging helper. Rebuild Sidekick, then re-run the helper
  install step so the manifest points at the bundled helper binary.
- **Chrome says access is forbidden** — The extension ID is not in the native
  messaging manifest's `allowed_origins`. Copy the ID shown in the side panel
  or `chrome://extensions`, then run **Browser → Install Chrome Helper…** in
  Sidekick with that ID.
- **"Waiting on Sidekick", "Disconnected from Sidekick", or "Sidekick
  rejected the message"** — Sidekick.app may not be running, or there is no
  active Feedback session. Launch Sidekick, then click **Feedback** in
  Sidekick or **Capture Feedback** from the menu-bar menu.
- **Mark Section click does nothing** — verify the page isn't using a custom
  event handler that swallows clicks before Sidekick's capture-phase listener.
  Hit `Esc` to cancel selection mode without capturing a mark.
- **`chrome.debugger` permission prompt** — Chrome shows a yellow bar
  saying "Sidekick started debugging this browser". Click **Cancel** in
  the prompt only if you want to detach; this is Chrome's required UX for
  DevTools-equivalent access.
