# Phase 3 — iOS Augmentation

> **Status:** blocked on Phase 2 MVP shipping.
> **Owners:** highly parallelisable — features are largely independent.
> **Repo:** `pi-remote-ios`.
> **Spec reference:** [`reference/SPEC-ios-app.md`](./reference/SPEC-ios-app.md) §5
> Groups B-06, B-07, B-08, B-09, C-03, C-04, C-05, D-01c, D-02, A-05 extensions.

## Goal

Make the iOS app distinctly nicer to use than a generic terminal client.
Each Phase 3 feature is independently shippable; no global blocker.
Features can land in any order, driven by daily use feedback.

## Acceptance Criteria

Per-feature checklist (each feature ships when its row passes):

| Feature | Acceptance |
|---|---|
| Slash-Command Palette | Long-press modifier bar opens palette, fuzzy search works, command injects correctly, argument forms render for commands with args. |
| Voice-to-Prompt | Mic button → preview → send works offline (iOS Speech). |
| Predictive Thumbnails | Switcher list shows live 40×12 capture-pane previews refreshed on open. |
| Scrollback Search | Cmd-F (HW kb) or pull-down gesture opens search; jump-to-match highlights and centres. |
| Hardware Keyboard Shortcuts | Cmd-K, Cmd-T, Cmd-1..9, Cmd-F, Cmd-Shift-P, Cmd-, route correctly. |
| Reachability | iPhone landscape: modifier bar mirrored for one-handed use. |
| Smart Paste (full) | Clipboard preview chip, multi-line preview sheet, bracketed-paste correctness. |
| Haptic Feedback | Subtle haptic on thinking→idle and thinking→awaiting transitions. |
| Theme + Font Picker UI | Settings UI exposes all bundled themes and fonts; iCloud-sync for custom. |

## Task Breakdown

| ID | Task | Touches | Depends on | Parallel With |
|---|---|---|---|---|
| T-3.1 | **Slash-Command Palette** (iOS-C-04). Long-press recogniser on ModifierBar, palette sheet, fuzzy-search engine, argument form generator from JSON schema returned by sidecar. | `Sources/UI/Input/SlashPalette/`, sidecar `/sessions/:id/commands` already exists (S-08) | Phase 2 | all others |
| T-3.2 | **Voice-to-Prompt** (iOS-C-05). `Sources/Voice/`, SFSpeechRecognizer, microphone permission, preview-edit-send flow. | `Sources/Voice/`, `Sources/UI/Input/ModifierBar.swift` (🎙 wiring) | Phase 2 | all others |
| T-3.3 | **Predictive Thumbnails** (iOS-D-01c). Add `GET /sessions/:id/thumbnail` on sidecar if not already (Phase 1 IC-2 includes it); poll on switcher open; render small SwiftTerm in `SessionRow`. | `Sources/UI/Sessions/SessionRow.swift`, `Sources/Core/Sessions/SessionRegistry.swift` | Phase 2 | all others |
| T-3.4 | **Scrollback Search** (iOS-D-02). Search bar over `ScrollbackCache`, in-memory index (linear search is fine at 5MB), highlight + jump in TerminalView. | `Sources/UI/Terminal/Search/`, `Sources/Core/Persistence/ScrollbackCache.swift` (read API) | Phase 2 | all others |
| T-3.5 | **Hardware Keyboard Shortcuts** (iOS-B-06). Register `UIKeyCommand` set in piRemoteApp + scene; route to app actions. Caps→Esc opt-in. | `Apps/piRemote/piRemoteApp.swift`, individual view controllers via scene delegate | Phase 2 | T-3.1 (Cmd-Shift-P depends on slash palette existing) |
| T-3.6 | **Reachability / One-Hand-Mode** (iOS-B-07). Landscape layout in `ModifierBar` mirrored; settings toggle. | `Sources/UI/Input/ModifierBar.swift` | Phase 2 | all others |
| T-3.7 | **Smart Paste full** (iOS-B-08 + iOS-B-09 bracketed-paste). Extend stub PasteSheet from Phase 2 with multi-line preview, char/line counter; track `\e[?2004h/l` from stream, switch paste-frame type accordingly. | `Sources/UI/Input/PasteSheet.swift`, `Sources/Core/Sessions/SessionConnection.swift` (state tracker) | Phase 2 | all others |
| T-3.8 | **Haptic Feedback** (iOS-C-03). `UIImpactFeedbackGenerator` hook in StatusBar state change. Setting to disable. | `Sources/UI/Status/StatusBar.swift`, Settings | Phase 2 | all others |
| T-3.9 | **Theme + Font Picker** (iOS-A-05 UI). Settings panes for theme/font selection, custom-theme editor (JSON or color pickers), iCloud KVS sync for custom. | `Sources/UI/Settings/`, `Sources/UI/Terminal/ThemeStore.swift` extensions | Phase 2 | all others |

## Inter-Task Conflicts

Most Phase 3 tasks touch unrelated files. Watch zones:

- **ModifierBar.swift** — T-3.1 (long-press), T-3.2 (mic), T-3.6 (mirror),
  T-3.7 (paste). Coordinate via SYNC.md if more than one of these is in
  flight simultaneously. Recommended order: T-3.1 → T-3.7 → T-3.6 → T-3.2.
- **SessionConnection.swift** — T-3.7 (bracketed-paste state) and any
  follow-up to Phase 2 IC-2.1. Coordinate.
- **Settings UI** — T-3.6, T-3.8, T-3.9 all extend the same settings
  surface. Land in series or merge carefully.

## Test Strategy

Per feature: a manual checklist row in `docs/PHASE-3-checklist.md`. No
heavy automation — these are visual / experiential features.

Critical regressions to watch for:
- Slash palette must not break input flow when dismissed (focus return).
- Voice must not steal focus from the WebSocket stream.
- Thumbnails must not block switcher rendering on slow links.

## Risks

- **R1.** SFSpeechRecognizer offline accuracy varies. Mitigation: allow
  on-device-only mode (slower, more private) vs. server-assisted toggle.
- **R2.** UIKeyCommand routing is finicky across scenes. Mitigation:
  centralise key handling in a single `KeyCommandRouter` actor.
- **R3.** Custom theme JSON schema drift between iCloud devices. Mitigation:
  versioned schema, migrate on read.

## Exit

Phase 3 has no hard exit — features land continuously. A "Phase 3 closed"
event is when every task above is shipped or explicitly deferred. At that
point write `docs/PHASE-3-report.md` summarising what made it, what didn't,
and ideas that came out of daily use for a future Phase 4.