Feature: Reset App Settings - Android

Why

Bring Android to iOS parity for app reset (originally requested in #57, open since 2020 with no implementation). #360 made preset categories user-editable/deletable, with its own acceptance criteria assuming reset would restore them — that reset logic doesn't exist yet.

Sequencing dependency: starts after Voice Selection (#613) merges to main. Reset must clear/handle whatever preference key voice-selection introduces for the selected voice — building reset first would mean re-touching the reset logic once voice-selection lands anyway.

Confirmed iOS behavior (AppResetController.performReset()`)
An engineer inspected the shipped iOS implementation directly and posted findings in [issue #613, comment](https://github.com/willowtreeapps/vocable-android/issues/613#issuecomment-5167007934). Reset is a blanket wipe-and-reseed, not a curated restore:

1. Wipes every key in UserDefaults unconditionally — not a curated list, the whole store. Every preference falls back to its Swift-level default the next time it's read: head tracking (device-dependent), dwell duration (1s), cursor sensitivity (medium), compact QWERTY keyboard (off), Listening Mode/smart-assist/hot-word toggles (unset/default).
2. Deletes all Core Data Phrase and Category rows, then re-runs the preset migration from bundled presets.json for the current language — all user-added phrases/categories and any edits to preset phrases (renames, hidden state, etc.) are permanently deleted. The app ends up in a fresh-install state.
3. Voice selection reverting to the system voice is deliberate, not accidental: selectedVoiceIdentifier is a user preference stored in UserDefaults, and it is intentionally wiped alongside every other user setting on reset. UPDATE - Per Chris Stroud (Slack, 2026-08-04): the identifier becoming unset is the correct, intended end state — the user either has an override voice selected in Vocable or doesn't, and reset should revert to "doesn't," i.e. the system voice, same as initial install.

Scope

Epic tracking issue — the actual work is broken into the child issues below - to mirror iOS behavior.

Child Issues

• #638 — Full preference wipe + defaults inventory
• #639 — Category/phrase data wipe + reseed
• #640 — Settings UI entry point + confirmation + accessibility
• #641 — Final device verification pass

Out of Scope

• Anything voice-selection-specific — depends on #613 shipping first

Links

• Original request: #57 (to be closed referencing this ticket once shipped)
• Dependency: #360 (why reset isn't a pure settings-values reset)
• Sequencing dependency: #613 (Voice Selection)
• Reference: Documentation/reset-app-settings-ios-reference.md

---

FEATURE ACCEPTANCE CRITERIA (Product):

Reset App Settings button

• The button shown on the Settings screen
• The button matches the Figma design

Reset Confirmation

• The button is fully operable via head tracking/gaze selection and switch input, not just touch
• On click, a confirmation dialogue is shown
• The dialog plainly states the reset is permanent and total
• The dialog includes cancel or confirm actions
• Selection of the actions are operable via head tracking or gaze selection and switch input, not just touch.
• On selection of Confirm, the reset logic is triggered
• On selection of Cancel, no changes occur

Reset Logic

Preferences

• 'Head tracking enabled 'is reset to default =boolean = true (Settings --> Selection Mode --> Head tracking is ON)
• Gaze/ cursor sensitivity is reset to default =medium (0.1F) (Settings --> Timing & Sensitivity)
• 'Dwell Time' is reset to default =1000L (Settings --> Timing & Sensitivity --> 'Hover Time' = "1 second")
• 'Selected Voice' is reset to default = device voice (Settings --> Voice --> top row matches voice selected on the device)

Category and Phrase Data

• Built-in/Preset Categories on Home Screen reset to the 8 default categories (General, Basic Needs, Personal Care, Conversation, Environment, 123, Recents).
• "Recents" tile defaults to empty (Home --> Recents --> "No recently used phrases"
• Built-in/Preset Phrases match original defaults. (Settings --> Categories & Phrases --> ))
• Edited Categories and Phrases - No hidden, deleted, reordered state remains

Edge cases & robustness

• Reset behaves correctly when triggered mid-speech/TTS playback — no crash, no stuck state
• Reset behaves correctly if triggered during onboarding or immediately after first install
• Reset does not require an app reinstall or restart to take effect
• No regression in the three existing Settings screen options (Categories and Phrases, Timing and Sensitivity, Selection Mode) after reset logic is added

Testing & verification

• Unit tests cover: reset after a category edit, reset after a category deletion, reset after a custom category/phrase addition, reset after preference changes, and reset of voice selection specifically
• Instrumented UI test confirms post-reset state matches a fresh install's default category/phrase set exactly
• Feature manually verified on a device/emulator build, not just via automated tests