# Heatmaps

DX-14. Where people click and how far they scroll on one route, read from the counters the
[interaction stream](interaction-stream.md) already folds. Bucker keeps **no page, no raw click and no session** for
this: a heatmap is a ranked table of elements, a scroll-reach curve and, once a person allows it, a coarse grid of
click positions. The picture behind it is one **you upload**.

Nothing here works until product analytics is enabled for the project (the PA-01 gate). With the gate shut every
heatmap route and tool refuses and stores nothing.

## What a heatmap holds

| Part | Source | Notes |
| --- | --- | --- |
| Top 15 elements | `interaction_route_hours` | Clicks, share of the route's clicks, sessions, rage clicks, dead clicks, and clicks followed by an error within one second. Route-wide: the viewport filter does not split it. |
| Attribution | the same | `totals.attributionRate` is the share of clicks that name an element. A click the SDK could not name counts in the total and in no element. |
| `other` | the cohort floor | An element whose busiest single hour had fewer sessions than the project's minimum cohort size (default 5) is folded into `other`, with its clicks. The busiest hour is a lower bound on distinct sessions, so one visitor who clicks across five hours is not five people. |
| Positioned clicks per viewport | `heatmap_cells` | Only clicks that carried a position. |
| Scroll reach | `heatmap_cells` (scroll cell) | The share of sessions that scrolled at least to each 6.25 % step, and `medianDepthPct`, the depth by which half of the sessions had left (100 when most read to the end). Withheld when fewer sessions than the floor left the route. |
| Grid cells | `heatmap_cells` | Page-relative click counts on a 100 by 100 grid. **Off until a person enables them**, and cells under the cohort floor are dropped. |
| `selector_check` | `interaction_route_hours`, last 7 days | `include: ["selector_check"]` with a selector says whether its last element appears among the route's elements. |

An element is the **last part of its selector** (`button.primary`). The whole chain is kept only as a digest, so two
chains that end in the same leaf read as one element. Selectors and routes are text from your page: the MCP tool treats
them as untrusted and says so in `trust.untrustedFields`.

## Coordinates are opt-in

`heatmap_capture.enable` turns click coordinates on for a project. It is a **human-only** act: an organization OWNER,
signed in as themselves, with a stated reason and the statement that a privacy review took place. No agent, service,
OAuth client or personal access token can do it, whatever scopes it holds. The act is audited; enabling twice writes
nothing. The setting is `heatmapCoordinates` on the project's web settings and is read fresh on every call; the SDK learns
of it from the capture document's replay section.

There is no tool that enables it and none that disables it: turning it back off is not an act the registry knows yet.

## Screenshots

Bucker does not render your page. To draw a heatmap over a picture, **a person uploads a PNG or JPEG**
(`heatmap_screenshot.create`, human-only, `org:admin`).

- The file is checked by content, not by the type it claims: PNG or JPEG magic, the size read from the header, at most
  2 MiB and 8,000 by 30,000 pixels. Anything else is refused.
- It is stored under `heatmaps/<project id>/<sha256>.<ext>` and deduplicated per route and viewport bucket. A project
  keeps at most 50.
- It is served back only to a reader of that project, with `nosniff` and a sandboxing content-security-policy.
- It is erased when the project or the organization is deleted, and after the lifetime you set (`expiresInDays`).

The overlay itself (the table, the image and the cells together) is drawn in the dashboard, in your browser. The
live-page overlay is a later feature and is not part of this.

## REST

| Route | Act |
| --- | --- |
| `GET /orgs/:org/projects/:project/interactions/heatmap?route=&days=&viewport=&selector=` | read (`analytics:read`) |
| `GET .../interactions/heatmap/screenshots?route=` | read |
| `GET .../interactions/heatmap/screenshots/:id/image` | read |
| `POST .../interactions/heatmap/screenshot` | `heatmap_screenshot.create`, human-only |
| `POST .../interactions/heatmap/capture` | `heatmap_capture.enable`, human-only |

## MCP

`heatmap_get` (dx toolset, 800 tokens, 1,200 with a selector check). It reads under `analytics:read`, which is **held**:
no token minted in production reaches it until the MCP ceiling is raised (SG-059). It writes one aggregated `data.read`
count, because it returns no personal data.
