# Android Client Notes

This project is based on the upstream `tmux-browser` documents under
`docs/`, especially:

- `docs/api.md`
- `docs/superpowers/specs/2026-04-17-browser-tmux-dashboard-design.md`
- `docs/superpowers/specs/2026-04-21-pty-streaming-terminal-design.md`
- `docs/superpowers/specs/2026-04-30-harmonyos-mobile-tmux-manager-design.md`

## What The Upstream Docs Say

The mobile design document is HarmonyOS-first and recommends a native ArkTS
client with these modules:

- connection profile store
- session API client
- terminal WebSocket client
- terminal core
- terminal view
- shortcut bar
- session list and terminal screens

It also says Android is second priority and WebView terminal rendering is out of
scope for that first HarmonyOS version.

## Android Request Reconciliation

The current request is different from that document in two important ways:

- target platform is Android first
- remote testing requires online APK builds and app-side update checks

For that reason, this repository starts with an Android API-client MVP. The
existing server is expected to already be running on port 3000. The app calls
the server HTTP API and terminal WebSocket directly instead of loading the
existing browser UI.

This is not yet the full native-terminal architecture described by the HarmonyOS
design document, but every exposed Android feature is native and calls the
server API directly. There is no WebView fallback.

## Backend Contract

The Android client must not change the server protocol.

HTTP:

- `GET /api/sessions`
- `POST /api/sessions`
- `DELETE /api/sessions/:name`
- `POST /api/sessions/:name/input`

WebSocket:

- `/ws/terminal`
- `/ws/events`
- `attach`
- `input`
- `resize`
- `scroll`
- `clear-history`

The server remains the source of truth. Closing the app or terminal viewer must
not kill a tmux session.

## Current MVP

Implemented now:

- configurable base URL, defaulting to `http://100.89.0.116:3000`
- support for Tailscale URLs such as `http://100.x.y.z:3000`
- native session list from `GET /api/sessions`
- create, rename, command send, split, pane select, pane kill, pin, mute, and
  kill session through documented session/preference endpoints
- basic live terminal through `/ws/terminal`
- native event stream through `/ws/events`
- bottom shortcut bar for `Esc`, `Tab`, `Ctrl+C`, `Ctrl+V`, arrows, page keys,
  tmux prefix actions, and paste
- shortcut delivery through the terminal WebSocket `input` message
- native action center for health, server status, timeline, preferences, kanban
  projects, group messages, hook events, image file/URL upload, image preview
  metadata, and native image preview display
- GitHub Actions APK build
- release manifest `latest.json`
- APK download, SHA-256 verification, and installer handoff

## Native Roadmap

To converge with the upstream mobile design, the next implementation should add
native Android modules in this order:

1. richer native layouts for kanban, group messages, timeline, and preferences
2. `TerminalCore` with ANSI parsing, cursor state, colors, and dirty rows
3. configurable shortcut bar backed directly by WebSocket `input`