Mark-VIII/docs/superpowers/specs/2026-08-11-virtual-pager-dock-design.md

# Virtual Pager Dock — Design Spec

- **Date:** 2026-08-11
- **Status:** Approved
- **Owner:** WiFi Pineapple Pager expansion project
- **Applies to:** `payload/user/general/pager-webui/www/` (front-end only) and
  `scripts/dev_proxy.py` (dev config)

## 1. Goal

Add a **Virtual Pager** button in the topbar next to the existing **Terminal**
button in the Pager WebUI (`http://172.16.52.1:8080/`). Clicking it opens a
bottom-docked panel that shows a live, interactive replica of the Pager device:
the physical-device graphic with the real-time screen in the middle and
clickable directional/A/B buttons — matching the virtual pager view of the
Pager's stock UI at `http://172.16.52.1:1471/`.

Behavior mirrors the existing Terminal dock: open/close toggling, docked panel,
connect/disconnect of WebSockets on open/close.

## 2. Stock UI Reference (verified 2026-08-11)

Source: `http://172.16.52.1:1471/` (captured to
`%TEMP%\opencode\pager-virtual-pager.html`, 141,707 bytes).

### 2.1 Connections

- Screen: `ws://<host>:1471/api/pager/display/screen.ws` — streams binary RGBA
  framebuffer frames. Requires the daemon `AUTH_<serverid>` cookie; returns
  `401 Unauthorized` without it.
- Keys: `ws://<host>:1471/api/pager/input/keys.ws` — text frames; same cookie.
- Both handshakes verified returning `101 Switching Protocols` with a valid
  `AUTH_<serverid>=<token>` cookie.
- Cookies are host-scoped (not port-scoped), so a browser that has logged into
  `172.16.52.1:8080` already sends the cookie to `172.16.52.1:1471`. This is the
  same mechanism the existing Terminal WS uses (direct `:1471` connection, no
  backend relay), and requires **no backend changes**.

### 2.2 Screen framebuffer

- Resolution `480 × 222`, stride `480 * 4 = 1920`, expected
  `1920 * 222 = 426,240` bytes per frame (4 bytes/pixel RGBA).
- Client renders each frame: copy RGBA into a hidden 480×222 canvas
  (`createImageData`/`putImageData`), `canvas.toDataURL('image/png')` into the
  `<img id="pager">` screen element.

### 2.3 Buttons / keys

Button image click sends these strings over the keys WS:

| Control   | Sent key         |
|-----------|------------------|
| LEFT      | `ArrowLeft`      |
| UP        | `ArrowUp`        |
| RIGHT     | `ArrowRight`     |
| DOWN      | `ArrowDown`      |
| A         | `Enter`          |
| B         | `Escape`         |

Physical keyboard: when the pager screen is focused (or body, with no other
control focused) the stock UI sends `e.key` on keydown (no repeats). Buttons
show a brief `.pressed` feedback (brightness filter).

### 2.4 Device graphic

`<table id="pager_ui">` (745 × 531) built from 24 image slices +
`spacer.gif`, button images `LEFT.png`, `UP.png`, `RIGHT.png`, `DOWN.png`,
`A_Button.png`, `B_Button.png`, and a 480×222 screen surface with hidden canvas
and a `#pager_error` overlay. Images are static and fetchable without auth from
`http://172.16.52.1:1471/images/`. Identical files already exist in
`wifipineapplepager/payloads/library/user/remote_access/nautilus/www/images/`
(sizes match byte-for-byte); they will be copied from there and hash-verified
against the stock UI.

Scaling: the stock UI scales the graphic with CSS `zoom` (`scale =
min(1, availableWidth / 745)`), `transform-origin: top center`.

## 3. Design

### 3.1 index.html

- Add `#pager-btn` ("Virtual Pager", `btn ghost`) next to `#terminal-btn`.
- Add `#pager-panel` dock after `#terminal-panel`, mirroring its structure:
  - `#pager-bar` — title "Virtual Pager" + `#pager-close` button.
  - `#pager` content area containing the pager graphic table with the live
    screen, hidden canvas, and error/retry overlay.
- Load `js/pager.js` after `js/terminal.js`.

### 3.2 app.css

- `#pager-btn`: same style as `#terminal-btn`; `.active` state for both.
- `#pager-panel`: fixed bottom dock like `#terminal-panel` but `height: 540px`;
  reuses the `term-up` slide-in animation and a shared `.dock` utility where
  practical. Content centered; overflow hidden.
- Pager graphic scale-to-fit: a wrapper whose `zoom`/transform scales the
  745×531 graphic to the available panel width, never upscaling
  (`scale = min(1, availableWidth / 745)`), per §2.4.
- `.pager-btn` cursor/`user-select`/pressed feedback (stock rules).
- `#pager_error` overlay styles (centered, dark overlay, Reconnect button).

### 3.3 js/pager.js (new, mirrors js/terminal.js)

Module `Pager` with:

- `SCREEN_WIDTH = 480`, `SCREEN_HEIGHT = 222`, `FB_STRIDE = 1920`.
- `ensure()` — lazily grab `#pager-panel`, canvas, `<img id="pager">`, build the
  graphic table (static innerHTML from bundled images), wire button clicks.
- `toggle()` — show/hide `#pager-panel`, toggle `#pager-btn.active`,
  connect/disconnect.
- Screen WS: binary `event.data` → `new Uint8Array(buffer)` →
  `renderRGBAFrame(bytes)` (reject frames `< FB_STRIDE * SCREEN_HEIGHT`).
  On error/close: hide screen, show error overlay with Reconnect.
- Keys WS: `sendKey(name)` helper; button clicks send the §2.3 strings.
- Keyboard: a `keydown` listener active only while the dock is open; skips when
  focus is in an INPUT/TEXTAREA/SELECT or the terminal; captures
  ArrowLeft/ArrowUp/ArrowRight/ArrowDown/Enter/Escape (preventDefault on the
  arrows to stop page scroll) and sends them via keys WS. Letter shortcuts
  (D/C/P/R/L/M) and backtick (terminal toggle) keep working — backtick closes
  the pager dock via the replace-on-open behavior.
- `disconnect()` closes both WS.
- `window.addEventListener('resize')` re-applies scale-to-fit while open.

### 3.4 app.js

- Wire `#pager-btn` and `#pager-close` to `Pager.toggle()` (guarded with
  `typeof Pager === 'undefined'` like the terminal).
- **Replace-on-open:** a small helper `showDock(name)` that, when opening
  `pager`, calls `Term.close()` if `Term` is defined and its panel is open, and
  vice versa. Refactor the terminal wiring to go through `showDock('terminal')`
  so both directions use the same rule. (`Term` gains a `close()`/`isOpen()`
  helper in `terminal.js`.)
- Keyboard shortcut `g` (or none) is not required; the button is the entry
  point. Backtick toggles the terminal and closes the pager dock (per
  replace-on-open).

### 3.5 config.js / dev_proxy.py

- `config.js`: add `pagerScreenWs: ''`, `pagerKeysWs: ''`.
- `app.js`: read `cfg.pagerScreenWs || ('ws://' + location.hostname +
  ':1471/api/pager/display/screen.ws')` and the keys equivalent; expose as
  `App.pagerScreenWs` / `App.pagerKeysWs`.
- `dev_proxy.py` `_serve_dev_config`: emit both fields pointing at the pager
  host (same shape as `terminalWs`).

### 3.6 Assets

- Copy from the nautilus payload into `www/assets/pager/`:
  `virtual_pager_01..24.png`, `LEFT.png`, `UP.png`, `RIGHT.png`, `DOWN.png`,
  `A_Button.png`, `B_Button.png`, `spacer.gif`.
- Hash-verify each against the stock UI (`http://172.16.52.1:1471/images/…`)
  during implementation; if any differ, use the stock bytes instead.

### 3.7 Error handling

- Screen WS error/close: show `#pager_error` ("Lost connection to virtual
  pager") with a Reconnect button that calls `connect()`.
- Keys WS is best-effort: if not OPEN, button presses are ignored (stock
  behavior).
- If WS construction throws (unreachable daemon), write a message into the
  error overlay rather than throwing in app.js.

## 4. Testing

- **Unit (Python):** none required — no backend changes.
- **Static review:** `pager.js` frame renderer bounds check; button→key mapping
  table; keyboard guard conditions; replace-on-open logic.
- **On-device smoke (per §8 of the main webui spec):**
  1. Log in at `http://172.16.52.1:8080/`; Virtual Pager button present next to
     Terminal.
  2. Open Virtual Pager: dock slides up, screen streams live, graphic scales to
     fit width.
  3. Click LEFT/UP/RIGHT/DOWN/A/B — screen responds; physical arrow/Enter/Escape
     also drive it; typing in an input/terminal does not.
  4. Open Terminal while Pager open → Pager dock closes (replace-on-open) and
     vice versa.
  5. Kill/reconnect network to the daemon → error overlay + Reconnect recovers.
  6. Backtick still toggles the terminal and closes the Pager dock.

## 5. Out of scope

- The stock page's embedded shell terminal and terminal-shortcut grid (the
  WebUI already has a Terminal dock).
- The Pager Skinner / virtual-pager theme features.
- Any backend relay for the pager WS (direct `:1471` connection, same as the
  Terminal).