ML-176.2: research and implementation plan

backlog/tasks/ml-176.2 - Presto-add-splash-screen-search-views-and-on-screen-keyboard.md

@@ -4,15 +4,20 @@ title: "Presto: add splash screen, search views, and on-screen keyboard"
 status: To Do
 assignee: []
 created_date: "2026-05-10 13:35"
+updated_date: "2026-05-10 13:56"
 labels:
   - presto
   - search
   - micropython
 milestone: m-0
-dependencies: []
+dependencies:
+  - ML-176.1
 references:
-  - presto/AGENTS.md (constraints and patterns)
-  - presto/README.md (API contract)
+  - presto/AGENTS.md
+  - presto/README.md
+  - >-
+    doc-17 -
+    Implementation-Plan-ML-176.2-—-Presto-splash-screen-search-views-and-on-screen-keyboard
 modified_files:
   - presto/records_on_the_day.py
 parent_task_id: ML-176
@@ -113,3 +118,35 @@ Refactor `presto/records_on_the_day.py` into a unified app with a splash screen,
 - [ ] #18 Keyboard renders correctly at 720×720: all keys visible and tappable
 - [ ] #19 Back-to-Home navigation available from month view and search views
 <!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+
+## Implementation Plan
+
+Full plan: `doc-17 - Implementation Plan: ML-176.2 — Presto splash screen, search views, and on-screen keyboard`
+
+### Summary
+
+11-step plan, all within `records_on_the_day.py`:
+
+1. **State constants + globals** — Add `STATE_HOME` (4), `STATE_SEARCH_INPUT` (5), `STATE_SEARCH_RESULTS` (6). Remove `STATE_STARTUP`. Add `search_query`, `search_results`, `keyboard_mode`, `previous_state` globals.
+2. **`fetch_search_results()`** — New API client calling `GET /api/v1/collection?q=<encoded>&limit=20`. Returns `(records_list, error_flag)`. Depends on ML-176.1 for the backend `q` parameter.
+3. **Splash screen (`STATE_HOME`)** — `draw_home_screen()` with two large buttons: "Search Collection" and "Today's Records".
+4. **On-screen keyboard (`STATE_SEARCH_INPUT`)** — `draw_search_input()` with 3-row QWERTY + numbers keyboard. Hit-test via `_keyboard_hit_test()`. Touch handler `handle_search_input_touch()`. Visual key-press feedback. OK button dimmed when query empty.
+5. **Search results (`STATE_SEARCH_RESULTS`)** — Reuses `_draw_record_row()`. Own scroll state (`search_scroll_offset`, `_search_content_height`). `prepare_records_for_display(recs=None)` made generic to support both `records` and `search_results`. Empty/error states.
+6. **Navigation tracking** — `previous_state` tracks whether detail was entered from day or search. Back from detail returns to correct origin.
+7. **Back-to-Home** — Home button added to month header. `wake_display()` sets `state = STATE_HOME`. `redraw_current_view()` updated for new states.
+8. **Boot flow** — Starts at `STATE_HOME`, no auto-fetch. User taps "Today's Records" → month view.
+9. **Main loop dispatch** — Added handlers for all new states. `handle_home_touch()`. Search results drag-scroll mirrors day view.
+10. **Cleanup** — Remove all `STATE_STARTUP` references.
+11. **Deploy** — Verify ML-176.1 deployed → `mise run presto` → manual verification on device.
+
+### Key design decisions
+
+- "Today's Records" navigates to month view (with today highlighted), not directly to day — preserves calendar context
+- Keyboard: fixed layout, lowercase only, no shift/caps, max 50 chars
+- Search results: 20 per page, no infinite scroll. Own scroll state per AGENTS.md rules.
+- `prepare_records_for_display()` parameterized to accept optional list — avoids duplicating the entire display-prep pipeline
+<!-- SECTION:NOTES:END -->