pi-remote-control/docs/PHASE-3-ios-augmentation.md

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 §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.