# Design: PineAP Overview — Mark VII stats + mode quick toggle (Pager-supported)

Date: 2026-08-11
Status: Approved

## Problem

The Pager WebUI PineAP overview (`#/pineap`) currently shows only a mode badge, an
intro line, two Quick Settings checkboxes, and four status cards (Karma / Open
Network / Evil WPA / Evil Enterprise). Compared with the WiFi Pineapple Mark VII
PineAP overview it is missing:

1. The three overall dashboard counters: **Total SSIDs in Pool**, **Clients
   Connected**, **Handshakes Captured**.
2. The **Passive / Active / Advanced** quick mode toggle.

All required data is already served by existing, on-device-verified webui
endpoints; the backend is not involved in this change.

## Data sources (all verified live)

| Card | Endpoint | Value | Link |
|---|---|---|---|
| Total SSIDs in Pool | `GET /api/pineap/ssids` | `data.ssids.length` (hak5cmd `PINEAPPLE_SSID_POOL_LIST`) | `#/pineap/impersonation` |
| Clients Connected | `GET /api/pineap/clients` | `data.count` (iwinfo assoclist) | `#/pineap/clients` |
| Handshakes Captured | `GET /api/pineap/handshakes` | `data.files.length` (loot dir scan) | `#/pineap/evilwpa` |

## Pager constraints (drives the design)

- **Karma (mimic) state is not readable.** The daemon exposes only
  `mimic/enable` and `mimic/disable` (POST); `get_config` has no karma field and
  there is no `mimic` GET route. The webui therefore tracks karma in a
  view-local variable; on a fresh page load the true state is unknown.
- **SSID Pool Broadcasting cannot start** (`ssidpool/enable` returns 500 because
  no `wlan0open` interface exists on the Pager). The mode presets do NOT touch
  broadcast; it remains a manual Quick Settings toggle that surfaces the daemon
  error.

## Design

### 1. Stats row (3 clickable cards)

A new `.cards` row placed above the existing status cards. Each card shows a
large numeric value via the existing `.card-label` / `.card-value` styles and a
`View`/`Configure` ghost button that navigates to the tab listed above. The row
is populated inside the existing 5-second `load()` loop by adding the three GETs
above to the current `Promise.all`.

### 2. Mode quick toggle (Passive / Active / Advanced)

A segmented control (new `.seg` / `.seg button` styles in `app.css`, modeled on
`.tabbar`) rendered directly under the mode badge in the header section. It has
three mutually exclusive buttons: Passive, Active, Advanced.

Preset actions (only Pager-supported features):

- **Passive**: `POST /api/pineap/enable {enable:true}` (PineAP on),
  `POST /api/pineap/mimic {enable:false}` (Karma off).
- **Active**: `enable:true` + `mimic:true` (Karma on).
- **Advanced**: `enable:true` + `mimic:true`; Evil WPA / Evil Enterprise are left
  as configured (customizable from their cards/tabs).

Apply flow: on click, disable the buttons, fire the preset requests (Promise.all),
then reload state. On any failure, revert the selection and toast "Failed". The
mode badge remains computed from readable state (`pineap_disabled`, Evil WPA /
Enterprise enabled) and the toggle highlight is synced to that computed mode.

Under the toggle, a short muted line describes the currently selected mode
(Mk7-style, adapted):
- Passive: "PineAP is on; network impersonation (Karma) is off."
- Active: "PineAP and Karma are on; the open network is impersonated."
- Advanced: "All PineAP features are enabled and customizable."

### 3. Karma status card

Replaces the current always-`null` value with the locally-tracked karma state
('On' / 'Off'; '—' if never set this session).

### 4. Quick Settings

Unchanged: "Capture SSIDs to Pool" and "Advertise AP Impersonation Pool".
**Randomize Source MAC is explicitly out of scope** — the Pager has no backing
route.

## Files touched

- `payload/user/general/pager-webui/www/js/views.js` — `views.pineap` overview
  section (stats row, mode toggle, karma card, feature-list line).
- `payload/user/general/pager-webui/www/css/app.css` — add `.seg` segmented
  control styles.

No backend changes. No test-module changes (frontend-only; verified by JS
delimiter balance check, the 13-module unittest loop, deploy, and an on-device
walk).

## Verification

1. JS delimiter balance check (no node available; Python checker).
2. All 13 test modules still pass (unchanged).
3. Deploy via `scripts/deploy.ps1` (password supplied securely).
4. On-device: confirm the three stat endpoints return counts; user walks the
   overview UI to confirm stats populate, cards navigate, and the mode toggle
   applies presets (karma tracking, error toast on failure).