> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Synheart Behavior - Chrome Extension

> Browser-side behavioral input for the Synheart stack — timing and patterns only, streamed to your local sensor agent

## Overview

The Synheart Behavior Chrome Extension extends behavioral input to the desktop browser. It captures how you interact with Chrome — rhythm, attention, movement patterns — not what you read or type, and streams anonymized session events to your local [Synheart Sensor Agent](/synheart-sensor-agent/overview).

It produces the same event shape as the mobile SDKs ([Flutter](/synheart-behavior/flutter), [Kotlin](/synheart-behavior/kotlin), [Swift](/synheart-behavior/swift)), so the browser becomes another input source for the same downstream pipeline. As with the mobile SDKs, the extension is an input layer; higher-level metrics (focus, distraction, HSI fields) are derived downstream — see the [Behavior overview](/synheart-behavior/overview).

**Distribution:** Source-available. The repository is open for reading, auditing, and filing issues. Pull requests are not accepted — see the repo's `CONTRIBUTING.md`. Security reports follow `SECURITY.md`.

## Privacy posture

The extension records interaction timing and patterns only. It does not record URLs, page titles, passwords, or typed content. Tabs use anonymous labels (`tab-1`, `tab-2`). Sites are classified into generic categories only.

| Captured                                                                 | Never captured                               |
| ------------------------------------------------------------------------ | -------------------------------------------- |
| Mouse movement patterns (not precise positions tied to page content)     | URLs or page titles                          |
| Keystroke timing (categories: letter / digit / symbol — never which key) | Typed content, passwords, or search queries  |
| Tab-switch timing with anonymized tab IDs                                | Clipboard, form values, or link destinations |
| Scroll patterns and reversals                                            | Media URLs                                   |
| Generic site categories                                                  | —                                            |

### Site categories

| Category            | Examples                       |
| ------------------- | ------------------------------ |
| `search-engine`     | Google, Bing, DuckDuckGo       |
| `video-platform`    | YouTube, Vimeo, Twitch         |
| `code-repository`   | GitHub, GitLab, Bitbucket      |
| `developer-qa`      | Stack Overflow, Stack Exchange |
| `social-media`      | Facebook, X, LinkedIn          |
| `forum`             | Reddit                         |
| `e-commerce`        | Amazon, eBay                   |
| `email`             | Gmail, Outlook                 |
| `documentation`     | Google Docs, Notion            |
| `local-development` | localhost, 127.0.0.1           |
| `website`           | Default for other sites        |

## Installation

### From source

```bash theme={null}
git clone https://github.com/synheart-ai/synheart-behavior-chrome.git
cd synheart-behavior-chrome
npm install
npm run build
```

Load the extension in Chrome:

1. Open `chrome://extensions`
2. Enable Developer mode
3. Click Load unpacked and select the `dist` folder

For iterative development, run `npm run build -- --watch` and use Reload on the extension card after each change.

### Requirements

* Chrome (Manifest V3)
* A running [Synheart Sensor Agent](/synheart-sensor-agent/overview) reachable on a configured host/port (typically `127.0.0.1`)

## Quick start

1. Start the sensor agent.
2. Open the extension popup, go to Sensor, set the port and auth token, choose Save, then Test Connection.
3. Toggle the main switch to ON to begin capture. Use Stats and HSI in the popup to verify flow.

There is no account in this repo — only your local configuration.

### Popup tabs

| Tab    | Purpose                                                   |
| ------ | --------------------------------------------------------- |
| Stats  | Buffered events, session id, sensor-agent status.         |
| Sensor | Port, auth token, test + save.                            |
| HSI    | Latest human-state readouts when your agent returns them. |

## Behavioral metrics captured

### Focus and attention

| Metric              | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| Tab switch          | Moves between tabs (anonymized IDs).                       |
| Tab hijacking       | Rapid tab switches within a short window (e.g. 5 seconds). |
| Window focus / blur | Browser focus at the OS level.                             |
| Visibility change   | Tab hidden / visible transitions.                          |
| Cursor parking      | Where the cursor settles (e.g. by quadrant).               |

### Micro-motor patterns

| Metric                 | Description                                                   |
| ---------------------- | ------------------------------------------------------------- |
| Cursor path tortuosity | Movement efficiency (1.0 ≈ straight; higher ≈ more hesitant). |
| Click dwell            | How long the mouse button is held.                            |
| Scroll events          | Velocity, direction, ratchet vs linear.                       |
| Scroll reversals       | Direction flips (re-reading–style signal).                    |

### Keystroke dynamics (timing only)

| Metric          | Description                                            |
| --------------- | ------------------------------------------------------ |
| Key hold time   | By category (letter, digit, symbol) — never which key. |
| Flight time     | Gap between releasing one key and pressing the next.   |
| Backspace burst | Rapid backspace bursts (e.g. 3+ in 500ms).             |
| Modifier combos | Ctrl / Alt / Shift / Meta usage patterns.              |

### Navigation patterns

| Metric            | Description                                       |
| ----------------- | ------------------------------------------------- |
| Navigation events | Transition type (typed, link, reload, generated). |
| Anchor scanning   | Link hover duration, internal vs external.        |
| Form submit       | GET vs POST (method only).                        |

## Session payload

The extension batches browser events into session payloads and POSTs them to the sensor agent.

```json theme={null}
{
  "session": {
    "session_id": "SESS-1768471200000",
    "device_id": "chrome-abc12345",
    "timezone": "America/New_York",
    "start_time": "2026-01-15T10:00:00.000Z",
    "end_time": "2026-01-15T10:05:00.000Z",
    "events": [
      {
        "timestamp": "2026-01-15T10:00:05.000Z",
        "event_type": "app_switch",
        "app_switch": {
          "from_app_id": "tab-1",
          "to_app_id": "tab-2",
          "site_category": "code-repository"
        }
      },
      {
        "timestamp": "2026-01-15T10:00:10.000Z",
        "event_type": "scroll",
        "scroll": {
          "velocity": 150,
          "direction": "down",
          "direction_reversal": false
        }
      },
      {
        "timestamp": "2026-01-15T10:00:15.000Z",
        "event_type": "typing",
        "typing": {
          "key_category": "letter",
          "hold_ms": 85,
          "flight_ms": 120
        }
      }
    ],
    "meta": {
      "source": "synheart-behavior-chrome",
      "version": "0.0.1",
      "event_count": 45
    }
  }
}
```

### Event type mapping

| Browser concept  | `event_type` |
| ---------------- | ------------ |
| Tab switch       | `app_switch` |
| Scroll           | `scroll`     |
| Click dwell      | `tap`        |
| Cursor path      | `swipe`      |
| Keystroke timing | `typing`     |
| Focus / blur     | `focus`      |
| Idle             | `idle`       |
| Navigation       | `navigation` |

## Sensor agent endpoint

```http theme={null}
POST http://127.0.0.1:{port}/collect
Authorization: Bearer {token}
Content-Type: application/json
```

Body: `{ "session": { ... } }` as produced by the extension. Response shape varies with agent version.

## Repository layout

* Repository root: `LICENSE`, `README.md`
* `synheart-behavior/` (extension package)
  * `manifest.json` — Chrome MV3 manifest
  * `background.js` — Service worker (batch + send)
  * `content.js` — Behavioral capture
  * `popup.html`
  * `src/popup.js`, `src/popup.css`
  * `icons/`

## Testing

Validate manifest and JavaScript syntax:

```bash theme={null}
node -e "JSON.parse(require('fs').readFileSync('synheart-behavior/manifest.json','utf8'))"
node --check synheart-behavior/background.js
node --check synheart-behavior/content.js
node --check synheart-behavior/src/popup.js
```

For manual verification, load unpacked from `dist`, open the Sensor tab, enable recording, and confirm events in your agent logs.

## Resources

* Repository: [synheart-behavior-chrome](https://github.com/synheart-ai/synheart-behavior-chrome)
* Sensor agent: [Synheart Sensor Agent](/synheart-sensor-agent/overview)
* Behavior concepts: [Synheart Behavior overview](/synheart-behavior/overview), [Metric definitions](/synheart-behavior/metric-definitions), [Threat model](/synheart-behavior/threat-model)

## License

Licensed under the Apache License, Version 2.0.