Mobile Checklist Experience

Create and complete lists on iPhone · plan source: .claude/plans/mobile-checklist-experience.md · 2026-07-21

Why now: round-1 testing reprioritized mobile above desktop. The grocery list is dictated on the phone and needs to be checked off on the phone — today iOS shows checklists as literal [ ]/[x] text in a plain TextEditor, with no way to tap items done.

What we're building on

Already working

Checked state syncs for free — content is one markdown string through SyncEnvelope, field-level LWW
ChecklistMarkdown in NoteSparrowCore is pure Foundation and parses both checkbox forms — the iOS renderer reuses it, no new dialect
Dictation's Done-moment offer already creates [ ] lists (passed round-1 step 12)

Missing or broken

No way to check off an item on iOS — the core unmet need
No add-item or convert-to-checklist affordance on mobile
Resumed dictation drops the second list 2 root causes found — whole-transcript averaging suppresses the offer, and sustained listening silently gives up after 5 empty windows

Interaction model — settled 2026-07-21

The target decides what a tap means, not a mode

Empty note → opens straight into the keyboard
Note without checklists → read view; tap anywhere → edit
Checklist row, tap → toggle — whole row, always. An accidental toggle is self-inverse; an accidental keyboard pop is the worst failure mid-shop, so the reversible action wins the ambiguity
Plain text or blank space below content, tap → edit, cursor at end (blank-space tap also covers all-checklist notes)
Checklist row, long-press → edit — the escape hatch for fixing that item's text
Edit ↔ Done in the toolbar → the always-visible mode switch; Done is the only exit — swiping the keyboard away stays in edit (people dismiss it to scroll)
"Add item" row → always visible at the end of each checklist block; extends the list without ever leaving read mode — the in-store flow is check, check, add, check on one continuous surface

Accepted limitation: the transition tap can't carry its location into TextEditor — entering edit lands the cursor at the end. Once inside, native tap-to-place-cursor works normally everywhere. (iOS 18 TextSelection is a future refinement, not a dependency.)

Key decisions

Read-mode-first note view — not a rich editor. Opening a note renders checklist lines as native tappable rows (checked = dimmed + strikethrough, display-only); everything else is plain text, never rewritten. Edit button / tapping plain text flips to the untouched TextEditor. Empty notes open straight to edit. This is the smallest architecture that makes checklists tappable and it honors the "Mac is the primary editor" blueprint constraint.

Toggle = marker swap + immediate persist. Tap swaps [ ]↔[x] in the string and saves instantly (bypassing the 2s debounce, same persist-now pattern voice capture uses) — shrinking the known ~1s LWW race window. Rapid toggles coalesce in the existing 1s sync flush.

Three creation paths, smallest-first. Dictation offer (shipped) → "Add item" row at the end of each checklist block (also how you extend the list in the store) → "Convert to Checklist" menu action for plain-line notes, with a discoverable hint when a note looks list-shaped. No smart Enter-continuation inside TextEditor — SwiftUI offers no return-key interception there.

Both dictation defects get fixed here, not deferred. They gate the exact use case driving the priority shift. Detection becomes segment-aware; sustained listening must never silently drop audio — reset the give-up counter on voice activity, and if we truly stop, end the session visibly.

Phases

P1Shared Checklist Document ModelCore · no deps

ChecklistDocument in NoteSparrowCore: parse content into stable-ID line models (plain / checklist) on top of ChecklistMarkdown
togglingLine(at:), appendingItem(...), convertingPlainLinesToChecklist() — all byte-exact on untouched lines, convert is a true toggle
Round-trip unit tests: both forms, indents, blanks, unicode, reversibility

P2Read-Mode Renderer with Tap-to-ToggleiOS · after P1

Read/edit mode state in NoteDetailView (Edit ↔ Done pair, blank-space tap, keyboard-dismiss stays in edit); new ChecklistReadView renders rows with design-token styling, 44pt targets, light haptic, long-press-to-edit
Toggle path with stale-state guard (currentNote re-resolve) and immediate updateNote
Live re-render on remote changes (Mac toggles appear on a watched phone); attachments/footer unchanged; VoiceOver labels + toggle action

P3Mobile Creation AffordancesiOS · after P2

Always-visible "Add item" inline field per checklist block — return commits and re-arms for rapid entry, never leaves read mode
"Convert to Checklist" menu action with count confirmation + reverse; dismissible hint row on list-shaped plain notes

P4Dictation Reliability — the Resume Bugparallel · no deps

Defect A: segment-aware looksLikeList — a wordy resumed segment can't suppress an earlier clean list; offer converts just the list-shaped ranges
Defect B: reset emptyRestarts on voice-band activity; raise the sustained ceiling; if recognition truly stops, end visibly — never a live-looking mic with no recognizer
Segmenter regression tests (list-then-prose, list-pause-list); verify merge() overlap-stitching still dedupes

P5Cross-Device Verification & Docsafter P1–P4

Closes round-1 debt: iOS→Mac direction (untested step 11) verified end-to-end
Manual QA Sarah: check off five items walking the store; 30s-pause resumed dictation captures both sets; Add-item and Convert flows on real notes
Document the ~1s LWW window honestly (two toggle surfaces now); update mobile-app and note-editing blueprints

Final review

Pros. Smallest architecture that delivers tap-to-check; reuses the shared parser; touches no edit/save/sync plumbing; every phase ships value alone; dictation fixes target root causes found by code reading.

Cons, stated plainly. (1) Read-mode-first changes tap-to-edit muscle memory for all notes — now de-risked: the interaction model was walked through the shop flow and settled; residual cost is the cursor-at-end transition tap. (2) Two toggle surfaces widen exposure to the known ~1s LWW window; simultaneous Mac+iPhone toggles resolve to one writer — documented, not fixed (per-line merge would be a sync-engine project). (3) Defect B's fix leans on the level meter distinguishing voice activity; fallback is honest-but-less-magical visible session end. (4) Segment-scoped conversion has fiddly range bookkeeping — the likeliest task to slip, and whole-transcript offers still work if it does.

Edge cases to watch. Very large notes re-parsing per keystroke in the add-item field; RTL/localized strikethrough; a Mac edit turning a checklist line into prose while the phone's read view is open mid-tap.

confidence this is the optimal, most elegant plan for the core request (82 → 85 after the interaction model was settled)