ADR-MOB-003 — Text delivery: IME first, RecognitionService second, share/clipboard fallback¶

Status: Accepted (2026-08-07) · design only, no code yet Deciders: Mohsen Seyedkazemi Ardebili Context links: [[adr-mob-001]], [[adr-mob-002]], [[adr-mob-004]] (activation), [[adr-011]] (no ambient capture), desktop analogue: src/yazses/inject/

Context¶

On the desktop, the hardest-won part of YazSes is injection: getting text into whatever window has focus (inject/auto.py, xdotool/ydotool/wtype/clipboard, plus the "no text target" guard in inject/target.py). Android has the same problem and a much better answer, but the answer constrains the whole app.

The candidate surfaces, with what each actually buys:

The precedent is informative: Transcribro, the closest FOSS neighbour (whisper.cpp + Silero VAD on Android), ships exactly the IME + RecognitionService pair and nothing riskier. That combination is the proven shape.

AccessibilityService deserves a hard look because it is the only surface that could reproduce the desktop's "dictate into the focused field without changing the keyboard". It is rejected below.

Decision¶

1. The IME is the primary and only required delivery surface. :feature:ime implements InputMethodService; the YazSes keyboard is a compact bar — mic key, a status/level indicator, backspace, enter, an "undo last insert" key and a switch-keyboard key — not a full QWERTY. Text is delivered with InputConnection.commitText().
2. The IME does not implement typing. Deliberate: it keeps the surface small, it keeps the app out of the "we can see everything you type" trust problem entirely, and it lets the user keep Gboard/HeliBoard/AnySoftKeyboard for actual typing. The mic key offers "switch back to previous keyboard" so a dictate→edit→dictate loop is two taps. If the community later wants a full keyboard, that is a separate ADR and a separate app module.
3. RecognitionService is the secondary surface (:feature:recognition), shipped in M2. It makes YazSes selectable as the device speech recogniser, so a different keyboard's mic button, or any app calling SpeechRecognizer, is served on-device by YazSes. It is best-effort by nature: whether and where a user can change the default recogniser varies by OEM and Android version, so the UI must state honestly when the setting is not reachable on this device rather than claiming success.
4. Share/PROCESS_TEXT and clipboard are the fallbacks. File-share → transcript is the M3 file-transcription entry point (desktop analogue: yazses transcribe). Clipboard is the guard path, mirroring the desktop's "no text target" behaviour: if commitText fails or there is no InputConnection, the transcript is copied to the clipboard and the user is told — never silently dropped.
5. The overlay bubble is opt-in and off by default (M3, :feature:bubble), for dictating into an app while keeping another keyboard active. Requires the overlay grant, and the app must work fully without it.
6. No AccessibilityService in wave 1 — see Rejected. If it is ever added it will be a separate, clearly-labelled, off-by-default module with its own ADR, and it will never be a prerequisite for basic dictation.
7. Delivery is behaviourally identical to the desktop where the contract says so: continuation spacing between consecutive bursts, voice punctuation, disfluency filtering and command-vs-dictation classification all run in :core:postprocess / :core:commands before delivery, validated by the shared golden vectors ([[adr-mob-008]]).

Consequences¶

• Enabling YazSes is a two-step onboarding (enable the keyboard in system Settings, then select it) that Android deliberately makes friction-ful, plus a scary-looking system warning about keyboards being able to collect what you type. The onboarding screen must address that warning head-on and truthfully: this keyboard has no typing surface, no network permission in the recognition path, and its source is public.
• Because the IME window is visible while recording, the app is "in use" for the while-in-use RECORD_AUDIO rule and needs no microphone foreground service for hold-to-talk. Meeting Mode does need one — see [[adr-mob-007]].
• Password fields (InputType variations with TYPE_TEXT_VARIATION_PASSWORD) must disable the mic entirely and say why. This is both a privacy duty and a no-surprises rule.
• The "no text target" concept carries over as "no InputConnection", giving the mobile app the same never-lose-your-words guarantee the desktop has.

Rejected¶

• AccessibilityService as the primary (or default) injector. It grants the app the ability to read every screen and act on it — the single most-abused permission on Android, restricted by Play policy to apps whose core function requires it, and a permanent, prominent system warning for the user. YazSes' core function does not require it: the IME reaches every text field already. Taking that grant would trade the project's central promise (a tool you can trust with everything you say) for convenience. Non-negotiable for wave 1.
• A full QWERTY keyboard in wave 1. Enormous surface (layouts, locales, autocorrect, gesture typing, theming) with no relation to the product thesis, and it would put YazSes in possession of every keystroke. Rejected on both cost and principle.
• Root / ADB-based input text. Not shippable to normal users.
• Replacing the system dictation with a hidden hook. No supported API; would require a custom ROM.